Configuration¶

Elvis LVS settings can be stored in a config file so you don't have to repeat flags on every CLI invocation or pass kwargs to every Python call.

Lookup order¶

Elvis searches for config in this order, stopping at the first match:

1. elvis.toml in the current directory or any ancestor
2. pyproject.toml [tool.elvis] section in the current directory or any ancestor

CLI flags and Python kwargs always override config file values.

Settings reference¶

All settings are optional. Missing settings use program defaults.

elvis.toml¶

tolerance = 1
top-cell = "my_design"

short-layers = [[49, 0], [45, 0], [41, 0], [44, 0], [1, 0]]
connected-layers = [[[44, 0], [41, 0]], [[44, 0], [45, 0]]]

[equivalent-ports]
pad = ["e1", "e2", "e3", "e4", "pad"]

pyproject.toml¶

[tool.elvis]
tolerance = 1
top-cell = "my_design"

short-layers = [[49, 0], [45, 0], [41, 0], [44, 0], [1, 0]]
connected-layers = [[[44, 0], [41, 0]], [[44, 0], [45, 0]]]

[tool.elvis.equivalent-ports]
pad = ["e1", "e2", "e3", "e4", "pad"]

Setting details¶

tolerance¶

Port matching tolerance in nanometers. Two ports connect when they are at the same position (within this tolerance) and face opposite directions.

tolerance = 10

CLI equivalent: -t 10 or --tolerance 10

top-cell¶

Override the top cell name used for hierarchical LVS. By default Elvis uses the GDS file's top cell. This is useful when the GDS top cell name differs from the schematic name.

top-cell = "mzi_optimized"

CLI equivalent: --top-cell mzi_optimized

short-layers¶

Layers on which to detect geometric shorts. Each entry is a [layer, datatype] pair. Elvis checks whether polygons on these layers create unintended connections between ports on different nets.

short-layers = [[49, 0], [45, 0], [41, 0]]

CLI equivalent: --short-layer 49,0 --short-layer 45,0 --short-layer 41,0

connected-layers¶

Pairs of layers that are electrically connected (e.g., a metal layer and a via layer). Each entry is a pair of [layer, datatype] arrays. This tells Elvis that polygons on one layer can connect to polygons on the other, enabling cross-layer short detection.

connected-layers = [
    [[44, 0], [41, 0]],
    [[44, 0], [45, 0]],
]

This declares that layer 44/0 connects to both 41/0 and 45/0 (e.g., a via layer bridging two metal layers).

CLI equivalent: --connected-layers 44,0:41,0 --connected-layers 44,0:45,0

equivalent-ports¶

Declares groups of electrically equivalent ports on a component. When one port in the group is connected, Elvis does not report the others as open errors. This is common for components like pads where all edge ports touch the same metal.

Explicit groups (table form):

[equivalent-ports]
pad = ["e1", "e2", "e3", "e4", "pad"]
mmi1x2 = ["o2", "o3"]

Automatic derivation (string form):

equivalent-ports = "auto"

When set to "auto", Elvis derives equivalent-port groups from the GDS polygon geometry. This requires at least one short-layers or connected-layers entry to be configured. Ports whose polygons overlap on a short-detection layer are grouped as equivalent.

The two forms are mutually exclusive — you cannot combine "auto" with an explicit table.

CLI equivalent:

# Explicit
--equivalent-ports pad:e1,e2,e3,e4,pad

# Automatic
--equivalent-ports auto

Python API¶

Python functions (lvs, lvs_rdb) accept the same settings as keyword arguments. When a kwarg is None (the default), the config file value is used. Passing an explicit value overrides the config.

import elvis

result = elvis.lvs(
    "layout.gds",
    schematic,
    tolerance_nm=10,
    short_layers=[(49, 0), (45, 0)],
    connected_layers=[((44, 0), (41, 0))],
    equivalent_ports={"pad": ["e1", "e2", "e3", "e4", "pad"]},
    top_cell="my_design",
)

For automatic equivalent-port derivation, pass the string "auto":

result = elvis.lvs(
    "layout.gds",
    schematic,
    short_layers=[(41, 0)],
    equivalent_ports="auto",
)

Precedence¶

Settings are resolved in this order (highest priority first):

1. CLI flags / Python kwargs — explicit values always win
2. Config file — elvis.toml or pyproject.toml
3. Program defaults — tolerance=1, empty lists, no top-cell override