Instance missing in schematic¶

File: pics/simple_splitter_instance_error.pic.yml

Error caught: An unknown instance was found in the layout.

Error type: LVS.instance.missing_in_schematic

Expected: ok=False, error_count=6

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.pic.yml"
PIC2 = PICS / "simple_splitter_instance_error.pic.yml"

Schematic¶

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

reference_schematic = elvis.load_schematics(PIC1)
reference_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}}}}

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

actual_schematic = elvis.load_schematics(PIC2)
actual_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}}}}

Build from schematic¶

gds_path = BUILD_GDS / "simple_splitter_instance_error.gds"
c = gf.read.from_yaml(actual_schematic["simple_splitter_instance_error"])
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_instance_error.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=6

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

Note

Apart from the LVS.instance.missing_in_schematic we also find opens for all the ports of the instance that's missing in the schematic as it's not connected to anything. Moreover, we also find an LVS.port.missing_in_schematic 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"])
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

Why it matters¶

An instance that appears in the layout but is absent from the schematic means the two no longer describe the same circuit. The extra component may have been left in by accident — a copy-paste artifact, an abandoned design variant, or a fabrication test structure that was never removed. Regardless of the cause, Elvis flags it as LVS.instance.missing_in_schematic so the discrepancy is caught before tape-out rather than after.