Skip to content

Elvis CLI Reference

Elvis provides a command-line interface for netlist extraction, LVS comparison, and format conversion.

Installation

uv pip install elvis-lvs

elvis extract

Extract a netlist from a GDS file.

elvis extract <layout.gds> [-f FORMAT] [-o OUTPUT] [-t TOLERANCE]

Arguments:

Argument Description
layout.gds Path to the GDS file

Options:

Option Default Description
-f, --format yaml Output format: yaml, json
-o, --output stdout Write output to file
-t, --tolerance 1 Port matching tolerance (nm)

Example:

elvis extract path/to/layout.gds

instances:
  mmi: mmi1x2
  wg_in: straight
  wg_out1: straight
nets:
  - p1: wg_in,o2
    p2: mmi,o1
  - p1: mmi,o2
    p2: wg_out1,o1
ports:
  o1: wg_in,o1
  o2: wg_out1,o2

elvis lvs

Compare a schematic netlist against a layout (GDS).

elvis lvs <layout.gds> [NAME:]<schematic.pic.yml>... [OPTIONS]

Arguments:

Argument Description
layout.gds Path to the GDS layout file
schematic.pic.yml One or more schematic files. Prefix with name: to override the component name.

Options:

Option Default Description
-f, --format lyrdb Output format: lyrdb, yaml, json
-o, --output stdout Write output to file
-t, --tolerance 1 Port matching tolerance (nm)
--short-layer LAYER,DATATYPE — Enable short detection on this layer. Repeatable.
--connected-layers L1,D1:L2,D2 — Declare cross-layer connectivity (e.g., M1 ↔ VIA). Repeatable.
--equivalent-ports auto \| COMP:P1,P2,... — Group equivalent ports to suppress redundant opens. Pass auto to derive groups from GDS polygon geometry, or one or more explicit component:port1,port2,... groups (the two modes are mutually exclusive). Repeatable for explicit groups.
--top-cell NAME auto Override top cell name

Output formats:

# KLayout lyrdb (default) — viewable in KLayout's marker browser
elvis lvs layout.gds schematic.pic.yml -o report.lyrdb

# YAML
elvis lvs layout.gds schematic.pic.yml -f yaml

# JSON
elvis lvs layout.gds schematic.pic.yml -f json

Short and cross-layer detection:

# Detect shorts on a single metal layer
elvis lvs layout.gds schematic.pic.yml --short-layer 1,0

# Cross-layer: M1 (1,0) connects to VIA (2,0), VIA connects to M2 (3,0)
elvis lvs layout.gds schematic.pic.yml \
    --short-layer 1,0 --short-layer 3,0 \
    --connected-layers 1,0:2,0 --connected-layers 2,0:3,0

Equivalent port grouping:

# Suppress opens for electrically equivalent pad ports (explicit)
elvis lvs layout.gds schematic.pic.yml --equivalent-ports pad:e1,e2,e3,e4

# Or derive groups automatically from GDS polygon geometry
# (requires --short-layer or --connected-layers)
elvis lvs layout.gds schematic.pic.yml --short-layer 41,0 --equivalent-ports auto

Hierarchical LVS:

# Pass all child schematics explicitly
elvis lvs layout.gds mzi.pic.yml mmi1x2.pic.yml

# Override component name for a schematic file
elvis lvs layout.gds my_mzi:mzi.pic.yml mmi1x2.pic.yml

# Override top cell name
elvis lvs layout.gds mzi.pic.yml --top-cell mzi_optimized

Example YAML output:

ok: false
error_count: 2
instance_errors:
  - error_type: missing_in_layout
    name: mmi1
    component: mmi1x2
net_errors:
  - error_type: missing_in_schematic
    ports:
      - wg_in,o2
      - mmi,o1

Each net_errors entry has a ports list of length ≥ 2. Length 2 is a binary A <-> B error; length > 2 is a "group" error meaning all listed ports are on one electrical net in one side of the comparison but not declared as such on the other. Equivalent-port groups are spelled instance,{p1,p2,…} inside the list.

elvis extract-ports

List the ports defined on each component cell (from kfactory metadata).

elvis extract-ports <layout.gds> [-f FORMAT] [-o OUTPUT]

Example:

elvis extract-ports layout.gds

mmi1x2:
  - o1
  - o2
  - o3
straight:
  - o1
  - o2
pad:
  - e1
  - e2
  - e3
  - e4
  - pad

elvis convert

Convert a GDSFactory schematic (.pic.yml) to the simplified elvis-netlist format.

elvis convert <schematic.pic.yml> [-f FORMAT] [-o OUTPUT]

Example:

elvis convert schematic.pic.yml

elvis simplify

Simplify a netlist by removing 2-port routing instances.

elvis simplify <netlist.yml> [OPTIONS]

Configuration file

LVS settings can be stored in elvis.toml or under [tool.elvis] in pyproject.toml. Elvis looks for elvis.toml first, then falls back to pyproject.toml. CLI flags override config values.

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]]]

# Either an explicit table of groups...
[equivalent-ports]
pad = ["e1", "e2", "e3", "e4", "pad"]

# ...or set to "auto" at the top level (mutually exclusive with the table form):
# equivalent-ports = "auto"

pyproject.toml:

[tool.elvis]
short-layers = [[49, 0], [45, 0]]
# equivalent-ports = "auto"   # alternative to the table below

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

With a config file in place, elvis lvs layout.gds schematic.pic.yml picks up all settings automatically.