squadds.layouts package#
Submodules#
squadds.layouts.capacitance_graph module#
Layout embedding planar-capacitance-graph-v1: the geometric vectors the planar-capacitance models read.
One vector per conductor (60 shape and context features; ground is conductor 0), one per conductor pair (42 features: 17
geometric pair features, the ground-pair flag, 9 local-context ring fractions and 15 ground-block features) and one global
vector (4: log chip area, log pocket area, log substrate thickness, effective permittivity). Exact embedding (the paper
model’s; no far-sample decimation). Needs the [ml] extra.
from squadds.layouts.capacitance_graph import encode emb = encode(“chip.gds”) emb[“node_features”].shape, emb[“pair_features”].shape, emb[“global_features”].shape # (N, 60), (N(N-1)/2, 42), (4,)
- squadds.layouts.capacitance_graph.code_sha256()[source]#
sha256 of the ported stage’s SOURCES.json (the sha256 of every file of the embedding and prior code).
- Return type:
str
squadds.layouts.client module#
Lazy Hugging Face access to SQuADDS layout artifacts.
- class squadds.layouts.client.LayoutClient(repo_id='SQuADDS/SQuADDS_Layouts', revision='main', manifest_filename='metadata/manifest.parquet', geometry_features_filename='metadata/geometry-features-v1.parquet', manifest_path=None, geometry_features_path=None, artifact_root=None)[source]#
Bases:
objectFind, download, and inspect GDS files without eager bulk downloads.
- download(reference, verify_checksum=True)[source]#
Download one GDS artifact and verify its immutable content checksum.
- Return type:
Path
- find(*, layout_id=None, design_id=None, source_id=None)[source]#
Resolve exactly one artifact by its stable identity or provenance.
- Return type:
- geometry_features(reference)[source]#
Return the versioned numerical geometry features for one layout.
- Return type:
dict[str, Any]
- manifest()[source]#
Load the compact manifest only; raw GDS files remain remote.
- Return type:
DataFrame
- class squadds.layouts.client.LayoutReference(layout_id, artifact_id, gds_path, component_name, source_id=None, design_id=None)[source]#
Bases:
objectA manifest-backed pointer to an immutable layout artifact.
- artifact_id: str#
- component_name: str#
- design_id: str | None = None#
- gds_path: str#
- layout_id: str#
- source_id: str | None = None#
squadds.layouts.dataset_export module#
GDS export in the convention of the planar capacitance dataset (SQuADDS/SQuADDS_PlanarCapacitance).
The networks were trained on this export, so a component exported here gives the model the input it was trained on.
Layers: ground with its etched pocket on (1, 0), one polygon per signal body on (1, 10), 2 um port stubs on (2, 0) /
(3, 0); 1 nm database unit. The chip is the component extent plus m ground gaps on each side:
helpersconvention (squadds2-helpersgenerate_gds.py; interdigital / paddle exp6-9, concentric exp10, star exp11-12): interdigital chip = fingers + 2 m max(gap_ground) with m = 20, component centred; concentric chip = 2 R_ground (+ CPW lengths in y) + 2 m min_trace_gap, star 2 R_pocket (+ cpw_length) + 2 m gap, m = 8; the Metal GDS renderer output, bodies merged per conductor; star layouts post-processed bysquadds.components.export_fixups(export_style).familiesconvention (exp13-15 generator): chip = qgeometry extent + 2 m g, m = 8 (Xmon: g = max(cross_gap, ground_spacing); shielded concentric: g = ground_gap) and m = 4 for TransmonPocket (g = the pad-to-pocket gap, floored at 20 um); nets unioned from qgeometry, renderer ground, a port stub at thereadoutpin and end slots at the others.
export_dataset_gds rebuilds the component from its class and options in a fresh design at the origin (orientation 0)
and reproduces the dataset GDS bit-exactly (scripts/planar_capacitance/verify_component_gds.py), except where the
ground gap was set from unrounded generator parameters (Xmon, TransmonPocket: pass ground_gap_um) and for the star
styles under another GEOS version (see export_fixups).
- squadds.layouts.dataset_export.dataset_export_cell(obj, family=None, margin_gaps=None, export_style=None, ground_gap_um=None)[source]#
The dataset-convention layout of a component (or a design holding one) as a gdstk cell (nm, 1 nm grid).
- squadds.layouts.dataset_export.dataset_export_layout(obj, family=None, margin_gaps=None, export_style=None, ground_gap_um=None)[source]#
(cell, design, settings): the dataset-convention layout of a component (or a design holding one) as a gdstk cell (nm, snapped to 1 nm as written), the fresh design it was rendered from (its qgeometry names the bodies) and the resolveddataset_export_settings.
- squadds.layouts.dataset_export.dataset_export_settings(obj, family=None, margin_gaps=None, export_style=None, ground_gap_um=None)[source]#
The resolved export settings of a component:
family,convention(helpers / families),margin_gaps,export_style(stars) andground_gap_um(families).- Return type:
dict
- squadds.layouts.dataset_export.default_ground_gap_um(family, options, design)[source]#
Ground gap g of the
familieschip margin (um) from component options; None for thehelpersfamilies.- Return type:
float | None
- squadds.layouts.dataset_export.default_star_style(options)[source]#
Export style of a star by its enabled pads: one pad = exp11 (
original), more = exp12 (reexport_gdspy).- Return type:
str
- squadds.layouts.dataset_export.export_dataset_gds(component_or_design, path, family=None, margin_gaps=None, export_style=None, ground_gap_um=None)[source]#
Write
component_or_designas the dataset exported it and return the path.family: inferred from the component class (
FAMILY_OF_CLASS);paddle/multipad_starexport likeinterdigital/star. margin_gaps: m of the chip margin (defaultMARGIN_GAPS[family]). export_style: star layouts only (squadds.components.export_fixups.EXPORT_STYLES; defaultoriginalfor one pad,reexport_gdspyfor more; SQuADDS rows carry it innotes.export_style). ground_gap_um: the margin’s ground gap for Xmon / TransmonPocket / ShieldedCapConcentric (default from the options; the dataset used the unrounded generator value).
- squadds.layouts.dataset_export.family_of(obj)[source]#
Dataset family of a component, a design with one component, or a class name; None outside the dataset.
- Return type:
str | None
- squadds.layouts.dataset_export.generator_ground_gap_um(family, params)[source]#
Ground gap (um) the exp13-15 generator used for the chip margin, from its unrounded
generator.params; the component options are rounded to 1 nm, so pass this asground_gap_umto reproduce the dataset GDS exactly.- Return type:
float | None
squadds.layouts.layer_semantics module#
Published GDS layer-role contract for the SQuADDS layout registry.
- squadds.layouts.layer_semantics.functional_layer_roles(component_name)[source]#
Return conductor/etch/port roles from the versioned dataset contract.
The simulation-domain ground is deliberately omitted because v0/v1 crop and rasterize only functional component geometry.
- Return type:
dict[tuple[int, int], str]
squadds.layouts.manifest module#
Build portable metadata records for immutable GDS layout artifacts.
- squadds.layouts.manifest.build_layout_record(path, *, component_name, component='coupler', gds_path, source_id=None, design_options=None, simulation_config=None, campaign=None)[source]#
Build one layout-manifest row from a GDS artifact and its provenance.
- Return type:
dict[str, Any]
- squadds.layouts.manifest.canonical_design_id(component_name, design_options)[source]#
Return a stable ID for a parametric component design.
- Return type:
str
- squadds.layouts.manifest.infer_layout_component_name(design)[source]#
Infer the canonical layout family represented by a SQuADDS DB row.
Simulation datasets predate the layout registry and do not consistently store a component class. Recognize their stable design-option schemas before falling back to the explicit component metadata used by couplers.
- Return type:
str | None
- squadds.layouts.manifest.parse_gds_polygons(path, *, layer=None, datatype=None)[source]#
Extract polygon vertices and metrics in micrometers from a GDS file.
- Return type:
list[dict[str, Any]]
- squadds.layouts.manifest.parse_gds_summary(path)[source]#
Extract deterministic geometry metadata from a GDS file in micrometers.
- Return type:
dict[str, Any]
squadds.layouts.qmetal_gds module#
Faithful Qiskit Metal GDS export with explicit two-terminal port markers.
Qiskit Metal stores component geometry in millimetres. SQuADDS layout GDS
files use micrometres and reserve (1, 0) for a ground plane with one etched
hole, (1, 10) for signal metal, and (2, 0) / (3, 0) for the ordered
terminals. The helpers here keep those concerns in one place so generated
datasets and their validation use exactly the same geometry contract.
- squadds.layouts.qmetal_gds.GROUND_DOMAIN_PADDING_UM = 169.0#
Per-side ground-plane margin in micrometres.
Measured from 120 published
GeneralizedCapNInterdigitalfiles, whose padding is essentially uncorrelated with conductor width (Pearson -0.10), so that sweep uses a fixed absolute margin rather than a multiple of the device. A proportional rule would place the ground plane furthest from the largest device, which is the opposite of what an absolutely anchored coupling spectrum needs. 169 um is the pooled median of the per-side paddings.
- class squadds.layouts.qmetal_gds.PortMarker(semantic, layer, polygon, source, datatype=0)[source]#
Bases:
objectOne ordered GDS terminal marker expressed in Qiskit Metal millimetres.
- datatype: int = 0#
- layer: int#
- polygon: Any#
- semantic: str#
- source: str#
- squadds.layouts.qmetal_gds.add_port_markers_to_gds(source, destination, markers)[source]#
Copy a rendered GDS while adding markers, using an atomic destination.
- squadds.layouts.qmetal_gds.capn_interdigital_tee_port_markers(component)[source]#
Return one marker for each electrical conductor in the legacy CapN tee.
prime_startandprime_endare two routing ends of the same prime/top conductor. Onlyprime_startis marked so the file remains a two-terminal capacitance layout;second_endmarks the other (second/bottom) conductor.- Return type:
list[PortMarker]
- squadds.layouts.qmetal_gds.each_polygon(geometry)[source]#
Yield polygonal leaves from a Shapely geometry.
- squadds.layouts.qmetal_gds.export_qgeometry_gds(design, destination, *, markers=(), include_ground_domain=False, minimum_ground_clearance_um=None)[source]#
Write Metal qgeometry and optional ordered terminal markers atomically.
When requested, the ground follows the GeneralizedCapNInterdigital convention: a dynamic square domain on
(1, 0)with one subtractive hole and no filled(1, 11)etch layer.
- squadds.layouts.qmetal_gds.insert_port_markers(layout, cell, markers)[source]#
Insert markers into an existing KLayout layout/cell.
- squadds.layouts.qmetal_gds.marker_from_junction(junction, conductor, *, width_mm, semantic, layer, source, length_um=2.0)[source]#
Place a marker outside the conductor at the connected junction endpoint.
- Return type:
- squadds.layouts.qmetal_gds.marker_from_pin(pin, *, semantic, layer, source, length_um=2.0)[source]#
Extend a Metal pin cross-section outward by
length_um.- Return type:
- squadds.layouts.qmetal_gds.minimum_ground_clearance_um(component)[source]#
Return the smallest native signal-to-ground clearance for a component.
- Return type:
float
- squadds.layouts.qmetal_gds.qgeometry_role(design, *, subtract)[source]#
Return the union of rendered poly/path qgeometry in Metal’s mm units.
- Return type:
Any
- squadds.layouts.qmetal_gds.read_layer_geometry(path)[source]#
Return one Shapely geometry per
(layer, datatype)pair, holes included.- Return type:
dict[tuple[int, int], Any]
- squadds.layouts.qmetal_gds.standardized_ground_geometry(design, markers, *, minimum_clearance_um, domain_padding_um=169.0)[source]#
Return a centered dynamic ground and its single QMetal-derived hole.
The native subtractive qgeometry remains authoritative. A minimum buffer closes the flat CPW ends emitted by Qiskit Metal, terminal bridge polygons make the two lumped ports reach the ground boundary, and only disjoint etch islands receive negligible-width bridges so the ground has one hole.
- Return type:
tuple[Any, Any]
- squadds.layouts.qmetal_gds.transmon_cross_port_markers(component, design)[source]#
Return native-clearance cross and claw bridges to ground.
- Return type:
list[PortMarker]
squadds.layouts.two_transmon module#
A two-Xmon layout: two Xmon crosses with a claw each, coupled across a gap (“gap”) or through an interdigital capacitor (“interdigital”), and the ordering of its Maxwell matrix (ground, cross A, cross B, claw A, claw B).
The geometry vector is p = [L_A, L_B, claw fraction A, claw fraction B, coupling] (um; claw fraction 1 = the claw runs
along the whole arm up to 15 um from the perpendicular arms; coupling = the gap in “gap”, the capacitor’s lead length in
“interdigital”). Fixed parameters are FIXED / IDC. Used by the MCP tool generate_two_transmon_gds.
Validity: this layout is not a family of the planar capacitance dataset; ground_spacing = 0 and the 11.7 um claw lead are
outside the trained Xmon ranges.
- squadds.layouts.two_transmon.idc_options(lead, x_north)[source]#
Interdigital capacitor rotated by 90 degrees: its north lead starts at x_north and it runs towards +x.
- squadds.layouts.two_transmon.idc_span(lead)[source]#
Length (um) of the interdigital capacitor from lead end to lead end.
- squadds.layouts.two_transmon.ordered_maxwell(result)[source]#
Full Maxwell matrix (fF; ground, cross A, cross B, claw A, claw B) of an
MLSimulator.predict(two_transmons(...))result.
- squadds.layouts.two_transmon.two_transmons(p, variant)[source]#
The two-Xmon layout of variant “gap” or “interdigital” (a fresh Qiskit Metal design).
Module contents#
Versioned layout artifacts and port-complete GDS export for SQuADDS.
- class squadds.layouts.LayoutClient(repo_id='SQuADDS/SQuADDS_Layouts', revision='main', manifest_filename='metadata/manifest.parquet', geometry_features_filename='metadata/geometry-features-v1.parquet', manifest_path=None, geometry_features_path=None, artifact_root=None)[source]#
Bases:
objectFind, download, and inspect GDS files without eager bulk downloads.
- download(reference, verify_checksum=True)[source]#
Download one GDS artifact and verify its immutable content checksum.
- Return type:
Path
- find(*, layout_id=None, design_id=None, source_id=None)[source]#
Resolve exactly one artifact by its stable identity or provenance.
- Return type:
- geometry_features(reference)[source]#
Return the versioned numerical geometry features for one layout.
- Return type:
dict[str, Any]
- manifest()[source]#
Load the compact manifest only; raw GDS files remain remote.
- Return type:
DataFrame
- class squadds.layouts.LayoutReference(layout_id, artifact_id, gds_path, component_name, source_id=None, design_id=None)[source]#
Bases:
objectA manifest-backed pointer to an immutable layout artifact.
- artifact_id: str#
- component_name: str#
- design_id: str | None = None#
- gds_path: str#
- layout_id: str#
- source_id: str | None = None#
- class squadds.layouts.PortMarker(semantic, layer, polygon, source, datatype=0)[source]#
Bases:
objectOne ordered GDS terminal marker expressed in Qiskit Metal millimetres.
- datatype: int = 0#
- layer: int#
- polygon: Any#
- semantic: str#
- source: str#
- squadds.layouts.build_layout_record(path, *, component_name, component='coupler', gds_path, source_id=None, design_options=None, simulation_config=None, campaign=None)[source]#
Build one layout-manifest row from a GDS artifact and its provenance.
- Return type:
dict[str, Any]
- squadds.layouts.canonical_design_id(component_name, design_options)[source]#
Return a stable ID for a parametric component design.
- Return type:
str
- squadds.layouts.encode_capacitance_graph(layout, threads=2, **prepare_kwargs)#
Embedding of a GDS path, gdstk Library / Cell or PreparedLayout: arrays (float32), feature names, conductor names (ground
Gfirst; pairs i < j in that order), version and code sha256.- Return type:
dict
- squadds.layouts.export_dataset_gds(component_or_design, path, family=None, margin_gaps=None, export_style=None, ground_gap_um=None)[source]#
Write
component_or_designas the dataset exported it and return the path.family: inferred from the component class (
FAMILY_OF_CLASS);paddle/multipad_starexport likeinterdigital/star. margin_gaps: m of the chip margin (defaultMARGIN_GAPS[family]). export_style: star layouts only (squadds.components.export_fixups.EXPORT_STYLES; defaultoriginalfor one pad,reexport_gdspyfor more; SQuADDS rows carry it innotes.export_style). ground_gap_um: the margin’s ground gap for Xmon / TransmonPocket / ShieldedCapConcentric (default from the options; the dataset used the unrounded generator value).
- squadds.layouts.export_qgeometry_gds(design, destination, *, markers=(), include_ground_domain=False, minimum_ground_clearance_um=None)[source]#
Write Metal qgeometry and optional ordered terminal markers atomically.
When requested, the ground follows the GeneralizedCapNInterdigital convention: a dynamic square domain on
(1, 0)with one subtractive hole and no filled(1, 11)etch layer.
- squadds.layouts.functional_layer_roles(component_name)[source]#
Return conductor/etch/port roles from the versioned dataset contract.
The simulation-domain ground is deliberately omitted because v0/v1 crop and rasterize only functional component geometry.
- Return type:
dict[tuple[int, int], str]
- squadds.layouts.infer_layout_component_name(design)[source]#
Infer the canonical layout family represented by a SQuADDS DB row.
Simulation datasets predate the layout registry and do not consistently store a component class. Recognize their stable design-option schemas before falling back to the explicit component metadata used by couplers.
- Return type:
str | None
- squadds.layouts.parse_gds_polygons(path, *, layer=None, datatype=None)[source]#
Extract polygon vertices and metrics in micrometers from a GDS file.
- Return type:
list[dict[str, Any]]
- squadds.layouts.parse_gds_summary(path)[source]#
Extract deterministic geometry metadata from a GDS file in micrometers.
- Return type:
dict[str, Any]
- squadds.layouts.read_layer_geometry(path)[source]#
Return one Shapely geometry per
(layer, datatype)pair, holes included.- Return type:
dict[tuple[int, int], Any]
- squadds.layouts.sha256_file(path)[source]#
Return the SHA-256 checksum of an exact artifact file.
- Return type:
str
- squadds.layouts.validate_ported_gds(design, path, markers, *, minimum_ground_clearance_um)[source]#
Validate the unified layer, ground-hole, and two-terminal contract.
- Return type:
dict[str, Any]