mbg-spice-to-gds
Converts a SPICE subcircuit netlist into a DRC-clean GDSII layout using gLayout, via the single entry point spice_to_gds_with_checks(netlist). Use when the user asks to generate GDS from SPICE, conver
SKILL.md.ai/skills/mbg-spice-to-gds/SKILL.md
GitHubMBG SPICE to GDS Layout Generator
Before you read anything: context economy
This repository is big enough that how you gather information decides
whether you finish. A measured session here spent 87% of a 1 MB
conversation on tool output — one file re-read 22 times, git status
polled 27+ times, and 33 KB spent searching $HOME for a repo whose path
was already in $MBG_ROOT. Read mbg-context-economy first. The short
version: resolve the repo from $MBG_ROOT, index a file before opening it,
never re-read what is already in context, do not poll git state, and climb
the verification ladder cheapest-first. Reading less is the goal; checking
less is not.
Pipeline Entry Point
spice_to_gds_with_checks(netlist) is the single entry point. It drives the
DesignContext flow: analog-aware placement, the DRC-aware grid router, internal
OPEN/SHORT verification, then Magic DRC + netgen LVS + PEX.
Measured on the four reference blocks (inverter, ring oscillator, 5T OTA,
StrongArm comparator): 4/4 pass DRC and LVS. The older shape-router path passed
0/4 because it mislabelled top-level pins; it is still reachable via
legacy=True for comparison but should not be used for new work.
Returned keys: outdir, gds_path, svg_path, cell_name, drc, lvs,
pex, all_pass, plus context, verification and metrics.
Outputs Produced
Every run emits a full view set beside the GDS, recorded in <cell>.views.json:
| View | File | Notes |
|---|---|---|
| GDS | <cell>.gds |
the implementation |
| LEF | <cell>.lef |
abstract for the floorplanner, written by Magic |
| Liberty | <cell>.lib |
hard-macro abstract; no timing arcs, none were characterised |
| Verilog | <cell>.v |
black-box declaration; signal pins are inout |
| SVG | <cell>.svg |
preview |
| Schematic SPICE | <cell>.spice |
the source netlist |
| Extracted SPICE | <cell>_extracted.spice |
from Magic |
| PEX SPICE | <cell>.pex.spice |
post-layout with parasitics |
| DRC / LVS | <cell>.magic.drc.rpt, <cell>.lvs.out |
tool output, verbatim |
Signal pins are declared inout deliberately: a SPICE netlist records
connectivity, not direction, so anything else would be invented.
Power Rails
VDD and VSS rails are generated automatically on the top metal, with via drops
registered as access points on the supply nets so the router connects to them.
Drops land on the routing grid — off-grid drops are the one thing the track
pitch cannot keep DRC-legal. Disable with power_rails=False.
Deep N-Well
GF180MCU has no deep-n-well transistor model, so isolation is inferred from
connectivity: an NMOS whose bulk is not on the global ground can only be built
with a deep n-well. Isolation propagates across a matching group, because a
differential pair with DNW on one side only is not matched. Override with
PlacementConfig(dnwell_devices={...}) or with_dnwell=True.
Passive Devices (resistors and MIM capacitors)
Passives are built by mbg.passives from raw PDK layers, not by gLayout.
That is not a preference — gLayout cannot produce either device in a form
gf180mcuD recognises:
| Device | gLayout builds | gf180 Magic expects | Result if used |
|---|---|---|---|
| Resistor | a diode-connected pfet (its own docstring says so) | ppolyf_u = POLY & SBLK & PPLUS & RESDEF |
extracts as pfet_03v3, LVS can never match |
| MIM cap | MIM on met2/met3 | mimcc mimcap metal5 over metal4 |
Magic extracts no device at all — the cap silently vanishes |
Write passives the natural way; both spellings are accepted:
XR1 vin vout ppolyf_u W=1u L=4u * or r_width=/r_length=
XC1 vout vss cap_mim_2f0_m4m5_noshield W=5u L=5u * or c_width=/c_length=
Three constraints that surprise people:
W >= 0.80 umfor a poly resistor (PRES.1).- MIM top plate
>= 5.0 um(MIMTM.8a). There is no smaller MIM in gf180; a request below this is rejected rather than silently resized. - Only
ppolyf_uhas a native generator. Another passive resistor model (npolyf_u,rm1, ...) raisesUnsupportedDeviceErrorinstead of being built from a different primitive, because substituting a device that extracts under another name is exactly how a layout passes DRC and then fails LVS for reasons nobody can find.
Two non-obvious rules are already handled and should not be "fixed":
- A resistor contact must land in the window 0.22-0.44 um from the
salicide block. Both bounds report as
PRES.7, so a too-far contact looks like a spacing error and moving it further away never helps. - The MIM's terminals come out on met3, not on the plates. Magic derives
the bottom plate as
bloat-all *mim *m4— the whole connected metal4 shape — and then requires 1.2 um of clearance from any unrelated metal4, so a router reaching the plates directly cannot satisfy MIMTM.1/MIMTM.3.
Chip Integration
python3 scripts/integrate_modules.py --librelane --top chip_top
Collects every module that published a views manifest into a LibreLane macro
integration: top-level Verilog, config.json, info.yaml and per-module
lvs_config.json. If LibreLane is not installed the configuration is still
written and the run is reported NOT RUN — never as passing.
Purpose
Convert a SPICE subcircuit netlist into a DRC-clean GDSII layout with auto-placement, power delivery, and negotiated-congestion routing, using the project's single supported pipeline entry point.
When to Use
- Converting a SPICE netlist to a GDS layout.
- Running the full layout + verification pipeline in one call.
- The user asks to "generate layout", "spice to gds", or "create GDS".
When Not to Use
- Manual step-by-step placement or routing — inspect
mbg.placement_engine/mbg.routerdirectly instead (seembg-placement-debug/mbg-routing-debug), or use a full-automate workflow that still calls the same pipeline entry point underneath. - Simulation-only tasks with no layout requested.
- Verification-only tasks on an existing GDS — use
mbg-ic-verify. - Diagnosing why a placement or route failed — use
mbg-placement-debugormbg-routing-debug; this skill only describes the happy-path call.
Required Inputs
- A SPICE subcircuit netlist string containing a
.subcktdefinition with at least one supported device (XM1-style MOSFETs, resistors, MIM caps). - PDK environment variables set (see Preconditions).
- Optional: an explicit output GDS path; otherwise the pipeline derives one from the subcircuit name.
Preconditions
PDK_ROOT,PDK, andPDKPATHmust be set before calling the pipeline. Inside the IIC-OSIC-TOOLS container the project standard is:export PDK_ROOT=/foss/pdks export PDK=gf180mcuD export PDKPATH=/foss/pdks/gf180mcuDOn a host-only install (no container), do not hardcode a personal home directory. Detect the actual PDK root instead, for example by checking whether
$PDK_ROOT/$PDKexists, or by asking the user which PDK installation path to use.mbg.checksinsrc/mbg/checks.pyalready falls back to/foss/pdkswhenPDK_ROOTis unset, andrun_lvsadditionally searches underPDK_ROOTfor the PDK setup file — read that module before assuming a path.The netlist must reference only
nfet_03v3/pfet_03v3devices for the GF180MCU 3.3V flow (auto-detected from the.lib/.incline bymbg.spice_parser.parse_netlist_with_pdk; the pipeline also supportssky130when that PDK is detected).Minimum five transistors is the informal threshold for meaningful analog layout mode; smaller circuits may still run but are not the intended case.
PDK Constraints (GF180MCU 3.3V)
| Constraint | Value |
|---|---|
| Supply | 3.3V single |
| MOSFET models | nfet_03v3 / pfet_03v3 ONLY |
| W limit | project guidance varies 5-10um per finger — check AGENTS.md and mbg.pdk_rules for the authoritative limit before sizing |
| L limit | project guidance varies 5-10um — same caveat |
| Body | pfet_03v3 -> VDD ONLY, nfet_03v3 -> VSS ONLY |
| Device prefix | XM1 (not M1) |
| Fingers vs multipliers | Prefer nf=N over m=N for matching and compactness |
Workflow
Load the netlist string. Reference the PDK library relative to
$PDK_ROOT, never a hardcoded personal path:from mbg.pipeline import spice_to_gds_with_checks netlist = """ .lib "$PDK_ROOT/gf180mcuD/libs.tech/ngspice/sm141064.ngspice" typical .subckt my_design vdd vss in out XM1 out in vdd vdd pfet_03v3 L=1u W=4u nf=1 XM2 out in vss vss nfet_03v3 L=1u W=2u nf=1 .ends """In a live shell, expand
$PDK_ROOTbefore writing the.libline, or have the calling script substitute the real environment value — do not commit a resolved absolute path into a checked-in netlist example.Call only
spice_to_gds_with_checks(netlist). Never callmbg.placement_engine.place,mbg.router.GridRouter, ormbg.powerfunctions manually to produce a "final" layout — those are internals the pipeline already orchestrates.The pipeline internally: parses the netlist and auto-detects the PDK, activates the PDK via gdsfactory, places devices, adds power strips, auto-routes, adds pin labels, and writes the GDS.
Inspect the returned dict (see Outputs) and report DRC/LVS/PEX results exactly as returned — never upgrade a
FAILor missing report to a claimed pass.
Outputs
spice_to_gds_with_checks(netlist) returns:
| Key | Description |
|---|---|
outdir |
Output directory path (named after the cell) |
gds_path |
GDS file path |
svg_path |
SVG preview path (may be None if preview generation failed) |
cell_name |
Top subcircuit name |
drc |
DRC result dict from run_drc |
lvs |
LVS result dict from run_lvs |
pex |
PEX result dict from run_pex |
drc_signoff |
Dual-engine verdict from run_dual_drc — Magic AND KLayout |
verification |
Internal connectivity: opens, shorts, missing_access, clean |
metrics |
routing_summary(): routed/total nets, wire length, vias, congestion |
context |
The DesignContext the layout was built from |
all_pass |
All four legs: Magic DRC clean AND drc_signoff["verdict"] == "PASS" AND LVS match AND internal connectivity clean |
all_pass is the whole gate, not a DRC summary. Two things it deliberately
includes:
- The KLayout sign-off verdict, not Magic alone. KLayout runs the GF180
foundry deck and is the sign-off authority (see
mbg-ic-verify); Magic is the independent complementary check.all_passonce readdrc["clean"]only, so a design KLayout had FAILED — or never checked, because it was not configured — could still reportall_pass=True.NOT_CONFIGUREDcounts as a failure on purpose: an engine that did not run has not agreed to anything. - Internal connectivity, including
missing_access— a SPICE terminal the layout never gave an access point to. It produces no geometry, soopenscannot see it; without this leg an unconnected device terminal could reach external LVS as the first thing that noticed.
Since v0.2 this entry point drives the DesignContext path
(spice_to_gds_with_checks_ctx in src/mbg/pipeline.py). The original
shape-router path is reached only with legacy=True or via
spice_to_gds_with_checks_legacy().
Failure Modes
- Missing
PDK_ROOT/PDK/PDKPATH— the pipeline raises before layout starts; do not silently set a personal fallback path. - Netlist has no
.subcktor zero parsed components — the pipeline raisesValueErrorbefore layout starts. drc["clean"]isFalse,drc_signoff["verdict"]is notPASS,lvs["match"]isFalse,verification["clean"]isFalse, orpex["pex_path"]isNone— report each stage's ownsummary/reasonfield verbatim; do not claimall_passwhen the dict says otherwise, and do not report a Magic-clean result as "DRC clean" without the sign-off verdict beside it.- Floating/unrouted internal nets — inspect with
mbg-routing-debug(mbg.connectivity.verify) rather than guessing from the SVG preview.