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.capacitance_graph.encode(layout, threads=2, **prepare_kwargs)[source]#

Embedding of a GDS path, gdstk Library / Cell or PreparedLayout: arrays (float32), feature names, conductor names (ground G first; pairs i < j in that order), version and code sha256.

Return type:

dict

squadds.layouts.capacitance_graph.feature_names()[source]#

Names of the node (60), pair (42) and global (4) features.

Return type:

dict

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: object

Find, 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:

LayoutReference

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

polygons(reference, *, layer=None, datatype=None)[source]#

Download and return selected polygon vertices in micrometers.

Return type:

list[dict[str, Any]]

summary(reference)[source]#

Download and inspect a single GDS file using the optional GDS backend.

Return type:

dict[str, Any]

class squadds.layouts.client.LayoutReference(layout_id, artifact_id, gds_path, component_name, source_id=None, design_id=None)[source]#

Bases: object

A manifest-backed pointer to an immutable layout artifact.

artifact_id: str#
component_name: str#
design_id: str | None = None#
classmethod from_record(record)[source]#
Return type:

LayoutReference

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:

  • helpers convention (squadds2-helpers generate_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 by squadds.components.export_fixups (export_style).

  • families convention (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 the readout pin 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 resolved dataset_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) and ground_gap_um (families).

Return type:

dict

squadds.layouts.dataset_export.default_ground_gap_um(family, options, design)[source]#

Ground gap g of the families chip margin (um) from component options; None for the helpers families.

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_design as the dataset exported it and return the path.

family: inferred from the component class (FAMILY_OF_CLASS); paddle / multipad_star export like interdigital / star. margin_gaps: m of the chip margin (default MARGIN_GAPS[family]). export_style: star layouts only (squadds.components.export_fixups.EXPORT_STYLES; default original for one pad, reexport_gdspy for more; SQuADDS rows carry it in notes.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 as ground_gap_um to reproduce the dataset GDS exactly.

Return type:

float | None

squadds.layouts.dataset_export.write_dataset_gds(cell, path)[source]#

Write a cell as the dataset files are written (1 nm unit and precision, polygons not fractured).

Return type:

Path

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.layer_semantics.write_layer_semantics(path)[source]#

Write the layer contract atomically using the registry filename.

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.manifest.sha256_file(path)[source]#

Return the SHA-256 checksum of an exact artifact file.

Return type:

str

squadds.layouts.manifest.write_manifest(records, output_path)[source]#

Write a deterministic, viewer-friendly Parquet manifest.

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 GeneralizedCapNInterdigital files, 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: object

One 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_start and prime_end are two routing ends of the same prime/top conductor. Only prime_start is marked so the file remains a two-terminal capacitance layout; second_end marks 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:

PortMarker

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:

PortMarker

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.qmetal_gds.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]

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.geometry(p)[source]#
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).

squadds.layouts.two_transmon.um()#

S.format(*args, **kwargs) -> str

Return a formatted version of S, using substitutions from args and kwargs. The substitutions are identified by braces (‘{’ and ‘}’).

squadds.layouts.two_transmon.xmon_options(x, cross_length, claw_length, location)[source]#

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: object

Find, 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:

LayoutReference

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

polygons(reference, *, layer=None, datatype=None)[source]#

Download and return selected polygon vertices in micrometers.

Return type:

list[dict[str, Any]]

summary(reference)[source]#

Download and inspect a single GDS file using the optional GDS backend.

Return type:

dict[str, Any]

class squadds.layouts.LayoutReference(layout_id, artifact_id, gds_path, component_name, source_id=None, design_id=None)[source]#

Bases: object

A manifest-backed pointer to an immutable layout artifact.

artifact_id: str#
component_name: str#
design_id: str | None = None#
classmethod from_record(record)[source]#
Return type:

LayoutReference

gds_path: str#
layout_id: str#
source_id: str | None = None#
class squadds.layouts.PortMarker(semantic, layer, polygon, source, datatype=0)[source]#

Bases: object

One 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 G first; 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_design as the dataset exported it and return the path.

family: inferred from the component class (FAMILY_OF_CLASS); paddle / multipad_star export like interdigital / star. margin_gaps: m of the chip margin (default MARGIN_GAPS[family]). export_style: star layouts only (squadds.components.export_fixups.EXPORT_STYLES; default original for one pad, reexport_gdspy for more; SQuADDS rows carry it in notes.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]

squadds.layouts.write_layer_semantics(path)[source]#

Write the layer contract atomically using the registry filename.

squadds.layouts.write_manifest(records, output_path)[source]#

Write a deterministic, viewer-friendly Parquet manifest.