Instance missing in layout¶

File: pics/simple_splitter_instance_error.pic.yml

Error caught: An instance declared in the schematic is missing from the layout.

Error type: LVS.instance.missing_in_layout

Expected: ok=False, error_count=3 (1 instance + 1 port + 1 open)

import tempfile
from pathlib import Path

import elvis
import gdsfactory as gf
from IPython.display import Markdown
from kwasm import Tool, show

gf.gpdk.PDK.activate()

PICS = Path("../pics")
BUILD_GDS = Path("../build/gds")
BUILD_GDS.mkdir(parents=True, exist_ok=True)
PIC1 = PICS / "simple_splitter_instance_error.pic.yml"
PIC2 = PICS / "simple_splitter.pic.yml"

Schematic¶

This is the input schematic we'll use for our LVS

reference_schematic = elvis.load_schematics(PIC1)
reference_schematic

{'simple_splitter_instance_error': {'instances': {'fake_coupler': {'component': 'coupler',
    'settings': {}},
   'mmi': {'component': 'mmi1x2', 'settings': {}},
   'wg_in': {'component': 'straight', 'settings': {'length': 10}},
   'wg_out1': {'component': 'straight', 'settings': {'length': 10}},
   'wg_out2': {'component': 'straight', 'settings': {'length': 10}}},
  'connections': {'mmi,o2': 'wg_out1,o1',
   'mmi,o3': 'wg_out2,o1',
   'wg_in,o2': 'mmi,o1'},
  'ports': {'o1': 'wg_in,o1', 'o2': 'wg_out1,o2', 'o3': 'wg_out2,o2'},
  'placements': {'fake_coupler': {'x': 50, 'y': 0},
   'mmi': {'x': 0, 'y': 0},
   'wg_in': {'x': -20, 'y': 0},
   'wg_out1': {'x': 15.5, 'y': 0.625},
   'wg_out2': {'x': 15.5, 'y': -0.625}}}}

This is the actual schematic that was used to generate the layout. It's very similar, but the extra instance fake_coupler was removed:

actual_schematic = elvis.load_schematics(PIC2)
actual_schematic

{'simple_splitter': {'instances': {'mmi': {'component': 'mmi1x2',
    'settings': {}},
   'wg_in': {'component': 'straight', 'settings': {'length': 10}},
   'wg_out1': {'component': 'straight', 'settings': {'length': 10}},
   'wg_out2': {'component': 'straight', 'settings': {'length': 10}}},
  'connections': {'mmi,o2': 'wg_out1,o1',
   'mmi,o3': 'wg_out2,o1',
   'wg_in,o2': 'mmi,o1'},
  'ports': {'o2': 'wg_out1,o2', 'o3': 'wg_out2,o2'},
  'placements': {'mmi': {'x': 0, 'y': 0},
   'wg_in': {'x': -20, 'y': 0},
   'wg_out1': {'x': 15.5, 'y': 0.625},
   'wg_out2': {'x': 15.5, 'y': -0.625}}}}

Build from schematic¶

gds_path = BUILD_GDS / "simple_splitter.gds"
c = gf.read.from_yaml(actual_schematic["simple_splitter"])
c.write_gds(gds_path)
show(gds_path, netlist=PIC2, tools=[Tool.FIT_ALL])

GDS Layout Preview

LVS Results¶

rdb = elvis.lvs_rdb(gds_path, reference_schematic)
lyrdb = Path(tempfile.gettempdir()) / "simple_splitter.lyrdb"
rdb.save(str(lyrdb))
show(
    gds_path,
    lyrdb=lyrdb,
    netlist=PIC2,
    tools=[Tool.FIT_ALL],
)

GDS Layout Preview

Instance errors in detail:

print(f"ok={rdb.num_items() == 0}, error_count={rdb.num_items()}")
Markdown(elvis.error_summary(rdb))

ok=False, error_count=3

cell	error type	description
simple_splitter	LVS.instance.missing_in_layout	Instance 'fake_coupler' (coupler) in schematic but not in layout
simple_splitter	LVS.port.missing_in_layout	Port 'o1' (wg_in,o1) in schematic but not in layout
simple_splitter	LVS.open	Open port: wg_in,o1 is not connected

Note

Apart from the LVS.instance.missing_in_layout we also find an open and a LVS.port.missing_in_layout which is expected because simple_splitter.ipynb does not have that port on purpose (see the 'Open Port' discussion)

Fix¶

The layout was built from the wrong schematic. Rebuild the GDS from reference_schematic (the clean splitter without fake_coupler) and re-run LVS:

c_fixed = gf.read.from_yaml(reference_schematic["simple_splitter_instance_error"])
c_fixed.write_gds(gds_path)
rdb_fixed = elvis.lvs_rdb(gds_path, reference_schematic)
rdb_fixed.save(str(lyrdb))
show(
    gds_path,
    lyrdb=lyrdb,
    netlist=PIC1,
    tools=[Tool.SELECT, Tool.RULER, Tool.CLEAR_ALL],
)

GDS Layout Preview

Note

the LVS still flags a few opens, but those are irrelevant to the error being discussed in this example.

Why it matters¶

An instance that the schematic declares but the layout doesn't contain means a piece of the design wasn't fabricated — typically because the layout was generated from a stale or wrong schematic, or because a recent edit to the schematic wasn't propagated. Elvis flags it as LVS.instance.missing_in_layout so the discrepancy is caught before tape-out rather than after.