Skip to content

Api

Elvis LVS: Layout vs. Schematic verification for photonic circuits.

convert(netlist)

Convert a GDSFactory netlist dict to elvis-netlist format.

Accepts flat or hierarchical (recursive) netlists. Hierarchical instances are flattened with ~ separators (e.g. mzi_1~splitter).

Parameters:

Name Type Description Default
netlist dict[str, Any]

Flat netlist dict or recursive dict[str, netlist].

 required

Returns:

Type Description
dict[str, Any]

dict with keys: instances, nets, ports.

extract_netlist(gds_path, tolerance_nm=None)

Extract netlist from a GDS file.

Parameters:

Name Type Description Default
gds_path str

Path to the GDS file.

 required
tolerance_nm int | None

Port matching tolerance in nanometers (default: from config or 1).

 None

Returns:

Type Description
dict[str, Any]

dict with keys: instances, nets, ports.

extract_ports(gds_path)

Extract component port table from a GDS file.

Returns a mapping of component name to list of port names, as parsed from the GDS cell metadata (kfactory port properties).

Parameters:

Name Type Description Default
gds_path str

Path to the GDS file.

 required

Returns:

Type Description
dict[str, list[str]]

dict mapping component name to list of port names.

load_schematics(*paths)

Load one or more schematic files (.pic.yml) as a GDSFactory netlist dict.

Parameters:

Name Type Description Default
*paths str

Paths to schematic files (.pic.yml).

 ()

Returns:

Type Description
dict[str, Any]

Recursive GDSFactory netlist dict
dict[str, Any]

(mapping component names to netlists).

lvs(layout_path, schematic, tolerance_nm=None, short_layers=None, connected_layers=None, equivalent_ports=None, *, use_pins=None, top_cell=None, layers=None, connectivity=None)

Run LVS comparison between a schematic and layout.

Parameters:

Name Type Description Default
layout_path str

Path to layout GDS file.

 required
schematic dict[str, Any]

Flat netlist dict or recursive dict[str, netlist].

 required
tolerance_nm int | None

Port matching tolerance in nanometers (default: from config or 1).

 None
short_layers list[tuple[int, int]] | None

List of (layer, datatype) tuples to check for shorts.

 None
connected_layers list[tuple[tuple[int, int], tuple[int, int]]] | None

List of ((l1, d1), (l2, d2)) tuples for cross-layer short detection.

 None
equivalent_ports dict[str, list[str]] | Literal['auto'] | None

Either a dict mapping component name to list of equivalent port names, or the literal string "auto" to derive groups from GDS polygon geometry (requires short_layers or connected_layers).

 None
use_pins bool | None

Use pin metadata from GDS cells as equivalent-port groups (default: True unless overridden in config).

 None
top_cell str | None

Override top cell name for hierarchical schematics.

 None
layers Any | None

A gdsfactory PDK.layers object (dict or enum mapping layer names to (layer, datatype) tuples). Used together with connectivity to derive connected_layers from the PDK when connected_layers is not provided explicitly.

 None
connectivity list[tuple[str, str, str]] | None

A list of (layer1, via, layer2) name triples, as found in PDK.connectivity. Requires layers.

 None

Returns:

Type Description
dict[str, Any]

dict with keys: ok, error_count, instance_errors,
dict[str, Any]

net_errors, port_errors, open_errors, short_errors.

lvs_ok(layout_path, schematic, tolerance_nm=None)

Check if LVS passes between a schematic and layout.

Convenience function that returns a boolean instead of a full report.

Parameters:

Name Type Description Default
layout_path str

Path to layout GDS file.

 required
schematic dict[str, Any]

Flat netlist dict or recursive dict[str, netlist].

 required
tolerance_nm int | None

Port matching tolerance in nanometers (default: from config or 1).

 None

Returns:

Type Description
bool

True if LVS passes (no errors), False otherwise.

lvs_rdb(layout_path, schematic, tolerance_nm=None, short_layers=None, connected_layers=None, equivalent_ports=None, *, use_pins=None, top_cell=None, layers=None, connectivity=None)

Run LVS comparison between a schematic and layout.

Parameters:

Name Type Description Default
layout_path str

Path to layout GDS file.

 required
schematic dict[str, Any]

Flat netlist dict or recursive dict[str, netlist].

 required
tolerance_nm int | None

Port matching tolerance in nanometers (default: from config or 1).

 None
short_layers list[tuple[int, int]] | None

List of (layer, datatype) tuples to check for shorts.

 None
connected_layers list[tuple[tuple[int, int], tuple[int, int]]] | None

List of ((l1, d1), (l2, d2)) tuples for cross-layer short detection.

 None
equivalent_ports dict[str, list[str]] | Literal['auto'] | None

Either a dict mapping component name to list of equivalent port names, or the literal string "auto" to derive groups from GDS polygon geometry (requires short_layers or connected_layers).

 None
use_pins bool | None

Use pin metadata from GDS cells as equivalent-port groups (default: True unless overridden in config).

 None
top_cell str | None

Override top cell name for hierarchical schematics.

 None
layers Any | None

A gdsfactory PDK.layers object (dict or enum mapping layer names to (layer, datatype) tuples). Used together with connectivity to derive connected_layers from the PDK when connected_layers is not provided explicitly.

 None
connectivity list[tuple[str, str, str]] | None

A list of (layer1, via, layer2) name triples, as found in PDK.connectivity. Requires layers.

 None

Returns:

Type Description
ReportDatabase

klayout.rdb.ReportDatabase with LVS results.

Raises:

Type Description
ImportError

If klayout is not installed (pip install elvis[klayout]).

simplify(netlist, remove_twoports='all', output_format='keep', *, flatten=False)

Simplify a netlist by removing 2-port routing instances.

Removes 2-port instances (waveguides, bends, etc.) and collapses their connections so that only multi-port components remain.

Parameters:

Name Type Description Default
netlist dict[str, Any]

Flat netlist dict or recursive dict[str, netlist].

 required
remove_twoports str | list[str]

Which 2-port instances to remove. "all" removes all 2-port instances (default). A list of component names (e.g. ["straight", "bend_euler"]) removes only those types.

 'all'
output_format str

Netlist schema for output. "keep" auto-detects from input (default). "elvis" always outputs ExtractedNetlist format. "gdsfactory" or "gf" preserves Instance metadata.

 'keep'
flatten bool

Flatten hierarchical netlist before simplification. No effect on already-flat netlists.

 False

Returns:

Type Description
dict[str, Any]

Simplified netlist dict.