SQuADDS/SQuADDS_Layout_Embeddings

<center> <img src="https://github.com/LFL-Lab/SQuADDS/blob/master/docs/static/images/squaddslogodarkname.png?raw=true" width="80%" alt="SQuADDS Logo" /> </center>

SQuADDS Layout Embeddings

Versioned layout representations for the 24,106 GDS artifacts in SQuADDS/SQuADDS_Layouts.

Static embedding model v0

static-embedding-v0 implements the original SQuADDS proof-of-concept model:

v0 = parameter_sum + geometric_moments + flattened_shape_bitmap

Each unit-normalized vector has 9,227 dimensions:

The bitmap uses +1 for conductor, -1 for etch, +0.5 for explicit port geometry, and 0 for background. Geometry is cropped to its functional bounds, centered without distortion, supersampled at 4×, and reduced to 96×96. The large simulation-domain ground rectangle on layer (1, 0) is excluded so it does not hide the component shape.

This is a deterministic static embedding, not a learned model. It remains a transparent baseline and a stable input for similarity search.

The exact block offsets, moment order, raster semantics, normalization statistics, and source schema are frozen in metadata/static-embedding-v0.schema.json.

Universal geometry model v1

universal-geometry-v1 is an additive 1,024-dimensional standard built from only a GDS file, a functional layer-role mapping, and the native design-parameter dictionary. Simulation targets are never embedded.

The metric block retains physical scale and role-specific conductor, etch, and port measurements. The shape block captures finger topology and boundary detail without storing a dense pixel tensor. Each block is normalized and explicitly weighted, and every fitted statistic and selected spectral frequency is frozen in the schema.

Parameter identity is retained on every row through parameter_names, parameter_values, parameter_hash_indices, and parameter_hash_signs. models/universal-geometry-v1/control-map.parquet provides the global, auditable bridge back to the originating layout controls.

This first v1 configuration contains all 20,062 GeneralizedCapNInterdigital designs. The encoder accepts foreign GDS layouts when their (layer, datatype) pairs are mapped to conductor, etch, or port; the cross-component reference normalization will be frozen in a later release after it is calibrated on the full SQuADDS catalogue.

The complete input contract, block offsets, transforms, normalization statistics, and invariances are frozen in models/universal-geometry-v1/schema.json.

The earlier 512-dimensional v1.0 candidate was rejected before release because its 8×8 low-pass shape crop lost finger detail and its common offsets collapsed cosine similarities. V1.1 passed paired topology, parameter-locality, shape, held-out capacitance-locality, and similarity-dynamic-range gates against v0 across five deterministic held-out samples. Capacitance was never used to fit the embedding.

Universal geometry model v2

universal-geometry-v2 is additive and answers a question v0 and v1 cannot: how does a contributor who has never seen this catalogue produce a vector that is directly comparable to it?

Both earlier standards are fit on write. Their normalization statistics, and in v1 the selected spectral frequencies, come from whichever rows are written together, so an outside group running the same builder lands in a different space even though the vectors share a length. v2 removes that coupling: every one of its 512 coordinates is a physical measurement in micrometers, inverse micrometers, or farads per meter, accumulated onto frozen bin edges. The encoder is a pure function of one GDS file and one design-option mapping.

Terminals are discovered as connected components of the conductor layer and ordered by port marker, never declared, so a foreign layout with different pin names still yields terminal 0 and terminal 1. The parameter block classifies each option by physical dimension rather than by name, which lets a 28-parameter foreign schema and a 40-parameter local one occupy the same 96 coordinates.

v2 is deliberately not scale invariant. v0 and v1 crop each layout to its own functional bounds, so a design and its exact enlargement produce identical shape blocks; because conductor separation in micrometers is the dominant variable for capacitance, v2 measures distances absolutely.

Simulation targets are never embedding inputs.

Rebuilt on the unified layout convention

TransmonCross and CapNInterdigitalTee were regenerated in SQuADDS/SQuADDS_Layouts to adopt the GeneralizedCapNInterdigital layer convention: a ground plane with a fixed 169 um per-side margin, the etch expressed as a hole in that plane rather than as layer 1/11, and two ordered ports bridging the moat from each terminal to ground. Their v2 rows are rebuilt from that geometry.

The margin is absolute rather than proportional to the device. Padding in the reference GeneralizedCapNInterdigital sweep is essentially uncorrelated with conductor width (Pearson -0.10), so an earlier proportional rule placed 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 measured from that sweep.

Every one of the 14,899 rows for the families that were not regenerated is byte-identical to the previous release. Correcting two component families changed nothing for the other two, because no v2 coordinate is derived from catalogue statistics. This is the fit-on-write property being absent, verified against a real geometry change rather than asserted.

layout_id changed for the regenerated rows, matching the layouts dataset; design_id and source_id are unchanged.

The correction is not cosmetic: it moves held-out cross-component prediction substantially, and it is what makes all four families share one reference frame. Current figures are reported in the SQuADDS tutorials rather than restated here, so they cannot drift out of step with the notebooks that produce them. See Tutorial 20 (cross-class study) and Tutorial 21 (transfer protocol).

static-embedding-v0 is unchanged and still reflects the pre-correction geometry together with its original role map, which recognizes ports only for GeneralizedCapNInterdigital and discards the TransmonCross etch layer. It is fit on write, so rebuilding it would alter all 24,106 vectors including families that were never touched. A port-complete role profile is available in the SQuADDS package for users who want to rebuild it themselves.

Coverage of this v2 table

This release contains 17,727 designs spanning all four component families, so v2 is the first standard here that covers the whole catalogue with a single encoder and no per-family configuration.

The GeneralizedCapNInterdigital count is 13,683 rather than the 20,062 that v0 and v1 hold for that family. The reason is upstream: SQuADDS/SQuADDS_Layouts currently publishes 10,000 of the 16,379 q3d_cap GDS artifacts that its own metadata/manifest.parquet lists, so the remaining 6,379 layouts cannot be encoded from released geometry. v0 and v1 were generated before that gap appeared. models/universal-geometry-v2/release-manifest.json records the count as layouts_without_downloadable_gds. Restoring the missing artifacts and re-running the builder is the only step needed for full coverage; the encoder does not change.

Every one of the 13,683 vectors published in the previous v2 release is byte-identical in this one. Adding three component families changed none of them, because no coordinate is derived from catalogue statistics. That is the fit-on-write property being absent, demonstrated rather than asserted, and it is the property that lets an outside contribution be concatenated with this table instead of requiring a rebuild.

Evidence

Under an identical model, split policy, and label budget over the 13,683 paired designs, with 13 finger-count domains and 12 stratified holdouts:

The third row is the control that matters: it receives no design parameters at all and still beats the whole of v0, which does include v0's parameter sum, so the improvement is geometric rather than an artifact of v2 retaining more parameter detail.

A single unfitted coordinate, the facing-boundary integral log1p_primary_inverse_gap_integral, reaches Spearman +0.941 against the simulated mutual capacitance; the boundary-element proxy reaches +0.920. The minimum gap on its own reaches only −0.165, because gap alone does not set capacitance — gap weighted by facing boundary length does.

Known limits: only one component class is measured so far; extrapolating to devices larger than any in training the advantage narrows to 0.810 against v0's 0.769; and raw cosine similarity has a compressed spread, so a frozen whitening transform should be published as a separate metric layer before v2 similarity is used as a headline number.

The complete input contract, block offsets, transforms, bin edges, and invariances are frozen in models/universal-geometry-v2/schema.json.

Cross-component evidence

Because v2 now covers every family, three of them - GeneralizedCapNInterdigital, CapNInterdigitalTee, and TransmonCross - can be joined into one supervised task, since each reports a mutual capacitance between two conductors (north_to_south, top_to_bottom, and cross_to_claw). Across those three the design-option vocabularies intersect in exactly one name, orientation, a placement angle, so no parameter-schema baseline exists for a three-class model.

On a class-balanced cohort of 894 designs each, a model trained on two families and given zero labels from the third reaches macro R2 0.859 and 0.422 in two of the three rotations, where static-shape-v0 reaches -7.7 and -17.6. A brand-new component family needs roughly ten labeled designs to pass macro R2 0.94.

Two limits are worth stating with the result. The third rotation, TransmonCross, stays negative at -1.891, and cross-class cosine similarity has the wrong sign on every class pair involving that qubit family. Similarity is a reliable applicability signal within a component family and is not yet reliable across one.

Similarity metric metric-v1

v2 coordinates are non-negative log-magnitudes in absolute physical units, so every device shares a large common direction and a raw cosine saturates: within TransmonCross the whole family spans a similarity standard deviation of 0.0005, and nearest-neighbour queries return 1.0000 for their top matches. The vectors are not wrong. A raw cosine is simply the wrong metric for a non-negative, absolutely anchored representation.

metric-v1 is a frozen transform that fixes this while keeping the two concerns separate, which is the point of the design:

• —the vectors stay catalogue-free and byte-stable forever;
• —the metric is fitted once on the reference catalogue, frozen, published, and versioned independently.

A newcomer applies the published transform and never refits it, so two contributions remain directly comparable, exactly as with the vectors.

The 209 discarded coordinates are constant across the entire catalogue. Most are the five unused terminal-pair slots and two unused terminal-to-ground slots: the encoder reserves capacity for four terminals and six pairs, and every design published so far is two-terminal. Those coordinates are reserved, not broken, and a multi-terminal family would populate them.

Effect on within-family similarity spread:

Mean cross-family similarity falls to approximately zero while within-family similarity stays positive, which is the behaviour a retrieval metric needs and which the raw cosine does not provide.

from squadds.layouts import LayoutEmbeddingClient

client = LayoutEmbeddingClient()
client.nearest(design_id, model="universal-geometry-v2", metric="whitened")

Files: models/universal-geometry-v2/metric-v1.json (contract and checksum) and models/universal-geometry-v2/metric-v1.npz (arrays).

Coverage and links

Every row retains layout_id, artifact_id, design_id, component_name, and source_id, plus the raw parameter sum, geometric moments, functional bounds, and a SHA-256 hash of the 96×96 bitmap.

The normalization statistics in this release are fit across all four component families. Existing layout identities and shape bitmaps remain stable; vectors are republished together so cosine similarity remains comparable across the complete catalogue.

Access

from squadds.layouts import LayoutEmbeddingClient, StaticEmbeddingClient

v0 = StaticEmbeddingClient()  # Backward-compatible alias
v1 = LayoutEmbeddingClient(version="v1")
v2 = LayoutEmbeddingClient(version="v2")

record = v2.get("layout:sha256:<layout hash>")
neighbors = v2.nearest(record["layout_id"], limit=10)
schema = v2.schema()

Because v2 consults no catalogue statistics, a layout that is not in this dataset can be encoded directly into the same space:

from squadds.layouts import encode

vector = encode("my_capacitor.gds", {"digit_pitch": "5.5um", "digit_population": 9})

SQuADDSDB rows can resolve the same vector directly with `SQuADDSDB.getlayoutembedding(row, embeddingversion="v2")`. Omitting the version preserves the v0 default. The SQuADDS MCP server also provides `getlayoutembedding` and `findsimilar_layouts`.

Provenance

Raw GDS artifacts, layer semantics, checksums, and geometry features live in SQuADDS/SQuADDS_Layouts. Simulation results and design options live in SQuADDS/SQuADDS_DB. The generalized-capacitor dataset was contributed by Saikat Das of the Levenson-Falk Lab at USC.

Citation

If you use this dataset, cite SQuADDS:

@article{Shanto2024squaddsvalidated,
  doi = {10.22331/q-2024-09-09-1465},
  title = {{SQ}u{ADDS}: {A} validated design database and simulation workflow for superconducting qubit design},
  author = {Shanto, Sadman and Kuo, Andre and Miyamoto, Clark and Zhang, Haimeng and Maurya, Vivek and Vlachos, Evangelos and Hecht, Malida and Shum, Chung Wa and Levenson-Falk, Eli},
  journal = {{Quantum}},
  volume = {8},
  pages = {1465},
  year = {2024}
}

This dataset is licensed under the MIT License.