SQuADDS/SQuADDS_Layout_Embeddings

1---2license: mit3configs:4- config_name: static-embedding-v05  data_files:6  - split: train7    path: "metadata/static-embedding-v0.parquet"8- config_name: universal-geometry-v19  data_files:10  - split: train11    path: "metadata/universal-geometry-v1.parquet"12- config_name: universal-geometry-v213  data_files:14  - split: train15    path: "metadata/universal-geometry-v2.parquet"16tags:17- quantum18- superconducting19- qiskit-metal20- gds21- layout22- embedding23- geometry24- computer-vision25pretty_name: SQuADDS Layout Embeddings26size_categories:27- 10K<n<100K28---29 30<center>31  <img src="https://github.com/LFL-Lab/SQuADDS/blob/master/docs/_static/images/squadds_logo_dark_name.png?raw=true" width="80%" alt="SQuADDS Logo" />32</center>33 34# SQuADDS Layout Embeddings35 36Versioned layout representations for the 24,106 GDS artifacts in37[SQuADDS/SQuADDS_Layouts](https://huggingface.co/datasets/SQuADDS/SQuADDS_Layouts).38 39## Static embedding model `v0`40 41`static-embedding-v0` implements the original SQuADDS proof-of-concept model:42 43```text44v0 = parameter_sum + geometric_moments + flattened_shape_bitmap45```46 47Each unit-normalized vector has **9,227 dimensions**:48 49| Block | Dimensions | Contents |50| --- | ---: | --- |51| Parameter sum | 1 | Permutation- and parameter-count-invariant sum of numerical design options, converted to micrometers where units are present |52| Geometric moments | 10 | Functional area, perimeter, aspect ratio, occupancy, centroid, second central moments, and eccentricity |53| Shape tensor | 9,216 | Row-major flattened 96×96 signed bitmap of functional GDS geometry |54 55The bitmap uses `+1` for conductor, `-1` for etch, `+0.5` for explicit port56geometry, and `0` for background. Geometry is cropped to its functional bounds,57centered without distortion, supersampled at 4×, and reduced to 96×96. The58large simulation-domain ground rectangle on layer `(1, 0)` is excluded so it59does not hide the component shape.60 61This is a deterministic static embedding, not a learned model. It remains a62transparent baseline and a stable input for similarity search.63 64The exact block offsets, moment order, raster semantics, normalization65statistics, and source schema are frozen in66`metadata/static-embedding-v0.schema.json`.67 68## Universal geometry model `v1`69 70`universal-geometry-v1` is an additive 1,024-dimensional standard built from only71a GDS file, a functional layer-role mapping, and the native design-parameter72dictionary. Simulation targets are never embedded.73 74| Block | Dimensions | Contents |75| --- | ---: | --- |76| Geometry metrics | 32 | Centered physical and morphological metrics; availability remains metadata rather than distorting cosine distance |77| Multiscale shape | 768 | Target-blind, variance-selected full-spectrum 2D DCT coefficients from 96×96 signed-material and boundary-distance rasters |78| Parameter controls | 224 | Stable signed feature hashing of canonical parameter paths after per-parameter centering and scaling |79 80The metric block retains physical scale and role-specific conductor, etch, and81port measurements. The shape block captures finger topology and boundary detail82without storing a dense pixel tensor. Each block is normalized and explicitly83weighted, and every fitted statistic and selected spectral frequency is frozen84in the schema.85 86Parameter identity is retained on every row through `parameter_names`,87`parameter_values`, `parameter_hash_indices`, and `parameter_hash_signs`.88`models/universal-geometry-v1/control-map.parquet` provides the global,89auditable bridge back to the originating layout controls.90 91This first v1 configuration contains all **20,062**92`GeneralizedCapNInterdigital` designs. The encoder accepts foreign GDS layouts93when their `(layer, datatype)` pairs are mapped to `conductor`, `etch`, or94`port`; the cross-component reference normalization will be frozen in a later95release after it is calibrated on the full SQuADDS catalogue.96 97The complete input contract, block offsets, transforms, normalization98statistics, and invariances are frozen in99`models/universal-geometry-v1/schema.json`.100 101The earlier 512-dimensional v1.0 candidate was rejected before release because102its 8×8 low-pass shape crop lost finger detail and its common offsets collapsed103cosine similarities. V1.1 passed paired topology, parameter-locality, shape,104held-out capacitance-locality, and similarity-dynamic-range gates against v0105across five deterministic held-out samples. Capacitance was never used to fit106the embedding.107 108## Universal geometry model `v2`109 110`universal-geometry-v2` is additive and answers a question v0 and v1 cannot: how111does a contributor who has never seen this catalogue produce a vector that is112directly comparable to it?113 114Both earlier standards are **fit on write**. Their normalization statistics, and115in v1 the selected spectral frequencies, come from whichever rows are written116together, so an outside group running the same builder lands in a different117space even though the vectors share a length. v2 removes that coupling: every118one of its 512 coordinates is a physical measurement in micrometers, inverse119micrometers, or farads per meter, accumulated onto frozen bin edges. The encoder120is a pure function of one GDS file and one design-option mapping.121 122| Block | Dimensions | Contents |123| --- | ---: | --- |124| Physical metrics | 48 | Absolute extent, per-role area and perimeter, conductor width percentiles, gap integrals, symmetry |125| Coupling spectrum | 192 | Facing boundary length per terminal pair per absolute separation, plus each terminal against ground |126| Shape spectrum | 128 | Two-point correlation, terminal cross-correlation, conductor width distribution, contour harmonics |127| Parameter statistics | 96 | Dimension-typed order statistics with dimension-scoped signed hashing |128| Physics proxy | 48 | Two-dimensional boundary-element capacitance matrix and dilation topology |129 130Terminals are discovered as connected components of the conductor layer and131ordered by port marker, never declared, so a foreign layout with different pin132names still yields terminal 0 and terminal 1. The parameter block classifies each133option by physical dimension rather than by name, which lets a 28-parameter134foreign schema and a 40-parameter local one occupy the same 96 coordinates.135 136v2 is deliberately **not** scale invariant. v0 and v1 crop each layout to its own137functional bounds, so a design and its exact enlargement produce identical shape138blocks; because conductor separation in micrometers is the dominant variable for139capacitance, v2 measures distances absolutely.140 141Simulation targets are never embedding inputs.142 143### Rebuilt on the unified layout convention144 145`TransmonCross` and `CapNInterdigitalTee` were regenerated in146[SQuADDS/SQuADDS_Layouts](https://huggingface.co/datasets/SQuADDS/SQuADDS_Layouts)147to adopt the `GeneralizedCapNInterdigital` layer convention: a ground plane with a148fixed **169 um per-side margin**, the etch expressed as a hole in that plane149rather than as layer `1/11`, and two ordered ports bridging the moat from each150terminal to ground. Their v2 rows are rebuilt from that geometry.151 152The margin is absolute rather than proportional to the device. Padding in the153reference `GeneralizedCapNInterdigital` sweep is essentially uncorrelated with154conductor width (Pearson -0.10), so an earlier proportional rule placed the155ground plane furthest from the largest device, which is the opposite of what an156absolutely anchored coupling spectrum needs. 169 um is the pooled median of the157per-side paddings measured from that sweep.158 159**Every one of the 14,899 rows for the families that were not regenerated is160byte-identical to the previous release.** Correcting two component families161changed nothing for the other two, because no v2 coordinate is derived from162catalogue statistics. This is the fit-on-write property being absent, verified163against a real geometry change rather than asserted.164 165`layout_id` changed for the regenerated rows, matching the layouts dataset;166`design_id` and `source_id` are unchanged.167 168The correction is not cosmetic: it moves held-out cross-component prediction169substantially, and it is what makes all four families share one reference frame.170Current figures are reported in the SQuADDS tutorials rather than restated here,171so they cannot drift out of step with the notebooks that produce them. See172Tutorial 20 (cross-class study) and Tutorial 21 (transfer protocol).173 174`static-embedding-v0` is **unchanged** and still reflects the pre-correction175geometry together with its original role map, which recognizes ports only for176`GeneralizedCapNInterdigital` and discards the `TransmonCross` etch layer. It is177fit on write, so rebuilding it would alter all 24,106 vectors including families178that were never touched. A port-complete role profile is available in the SQuADDS179package for users who want to rebuild it themselves.180 181### Coverage of this v2 table182 183This release contains **17,727** designs spanning **all four** component184families, so v2 is the first standard here that covers the whole catalogue with185a single encoder and no per-family configuration.186 187The `GeneralizedCapNInterdigital` count is 13,683 rather than the 20,062 that v0188and v1 hold for that family. The reason is upstream:189[SQuADDS/SQuADDS_Layouts](https://huggingface.co/datasets/SQuADDS/SQuADDS_Layouts)190currently publishes 10,000 of the 16,379 `q3d_cap` GDS artifacts that its own191`metadata/manifest.parquet` lists, so the remaining 6,379 layouts cannot be192encoded from released geometry. v0 and v1 were generated before that gap193appeared. `models/universal-geometry-v2/release-manifest.json` records the count194as `layouts_without_downloadable_gds`. Restoring the missing artifacts and195re-running the builder is the only step needed for full coverage; the encoder196does not change.197 198Every one of the 13,683 vectors published in the previous v2 release is199**byte-identical** in this one. Adding three component families changed none of200them, because no coordinate is derived from catalogue statistics. That is the201fit-on-write property being absent, demonstrated rather than asserted, and it is202the property that lets an outside contribution be concatenated with this table203instead of requiring a rebuild.204 205### Evidence206 207Under an identical model, split policy, and label budget over the 13,683 paired208designs, with 13 finger-count domains and 12 stratified holdouts:209 210| Held-out macro R² | 1% labels | 10% labels | 100% labels |211| --- | ---: | ---: | ---: |212| `static-shape-v0` (155 compact features) | 0.235 | 0.888 | 0.984 |213| `universal-geometry-v2` | 0.780 | 0.9915 | 0.9998 |214| `universal-geometry-v2`, geometry block only | 0.754 | 0.9896 | 0.9996 |215 216The third row is the control that matters: it receives no design parameters at217all and still beats the whole of v0, which does include v0's parameter sum, so218the improvement is geometric rather than an artifact of v2 retaining more219parameter detail.220 221A single unfitted coordinate, the facing-boundary integral222`log1p_primary_inverse_gap_integral`, reaches Spearman +0.941 against the223simulated mutual capacitance; the boundary-element proxy reaches +0.920. The224minimum gap on its own reaches only −0.165, because gap alone does not set225capacitance — gap weighted by facing boundary length does.226 227Known limits: only one component class is measured so far; extrapolating to228devices larger than any in training the advantage narrows to 0.810 against v0's2290.769; and raw cosine similarity has a compressed spread, so a frozen whitening230transform should be published as a separate metric layer before v2 similarity is231used as a headline number.232 233The complete input contract, block offsets, transforms, bin edges, and234invariances are frozen in `models/universal-geometry-v2/schema.json`.235 236### Cross-component evidence237 238Because v2 now covers every family, three of them - `GeneralizedCapNInterdigital`,239`CapNInterdigitalTee`, and `TransmonCross` - can be joined into one supervised240task, since each reports a mutual capacitance between two conductors241(`north_to_south`, `top_to_bottom`, and `cross_to_claw`). Across those three the242design-option vocabularies intersect in exactly one name, `orientation`, a243placement angle, so no parameter-schema baseline exists for a three-class model.244 245On a class-balanced cohort of 894 designs each, a model trained on two families246and given **zero labels** from the third reaches macro R2 0.859 and 0.422 in two247of the three rotations, where `static-shape-v0` reaches -7.7 and -17.6. A248brand-new component family needs roughly ten labeled designs to pass macro R22490.94.250 251Two limits are worth stating with the result. The third rotation,252`TransmonCross`, stays negative at -1.891, and cross-class cosine similarity has253the wrong sign on every class pair involving that qubit family. Similarity is a254reliable applicability signal within a component family and is not yet reliable255across one.256 257## Similarity metric `metric-v1`258 259v2 coordinates are non-negative log-magnitudes in absolute physical units, so260every device shares a large common direction and a **raw cosine saturates**:261within `TransmonCross` the whole family spans a similarity standard deviation of2620.0005, and nearest-neighbour queries return 1.0000 for their top matches. The263vectors are not wrong. A raw cosine is simply the wrong metric for a264non-negative, absolutely anchored representation.265 266`metric-v1` is a frozen transform that fixes this while keeping the two concerns267separate, which is the point of the design:268 269* the **vectors** stay catalogue-free and byte-stable forever;270* the **metric** is fitted once on the reference catalogue, frozen, published,271  and versioned independently.272 273A newcomer applies the published transform and never refits it, so two274contributions remain directly comparable, exactly as with the vectors.275 276| Property | Value |277| --- | --- |278| Transform | centre, scale, shrinkage-regularized ZCA whitening, then cosine |279| Shrinkage | 0.70, selected by sweeping against within- and cross-family rank correlation |280| Fitted rows | 17,727 across all four families |281| Retained dimensions | 303 of 512 |282 283The 209 discarded coordinates are constant across the entire catalogue. Most are284the five unused terminal-pair slots and two unused terminal-to-ground slots: the285encoder reserves capacity for four terminals and six pairs, and every design286published so far is two-terminal. Those coordinates are reserved, not broken,287and a multi-terminal family would populate them.288 289Effect on within-family similarity spread:290 291| Family | Raw cosine sd | `metric-v1` sd |292| --- | ---: | ---: |293| TransmonCross | 0.0005 | 0.2776 |294| CavityClawRouteMeander | 0.0195 | 0.3016 |295| CapNInterdigitalTee | 0.0411 | 0.1971 |296| GeneralizedCapNInterdigital | 0.0415 | 0.1987 |297 298Mean cross-family similarity falls to approximately zero while within-family299similarity stays positive, which is the behaviour a retrieval metric needs and300which the raw cosine does not provide.301 302```python303from squadds.layouts import LayoutEmbeddingClient304 305client = LayoutEmbeddingClient()306client.nearest(design_id, model="universal-geometry-v2", metric="whitened")307```308 309Files: `models/universal-geometry-v2/metric-v1.json` (contract and checksum) and310`models/universal-geometry-v2/metric-v1.npz` (arrays).311 312 313## Coverage and links314 315| Component | `v0` | `v1` | `v2` |316| --- | ---: | ---: | ---: |317| `GeneralizedCapNInterdigital` | 20,062 | 20,062 | 13,683 |318| `CapNInterdigitalTee` | 894 | — | 894 |319| `CavityClawRouteMeander` | 1,216 | — | 1,216 |320| `TransmonCross` | 1,934 | — | 1,934 |321 322Every row retains `layout_id`, `artifact_id`, `design_id`, `component_name`,323and `source_id`, plus the raw parameter sum, geometric moments, functional324bounds, and a SHA-256 hash of the 96×96 bitmap.325 326The normalization statistics in this release are fit across all four component327families. Existing layout identities and shape bitmaps remain stable; vectors328are republished together so cosine similarity remains comparable across the329complete catalogue.330 331## Access332 333```python334from squadds.layouts import LayoutEmbeddingClient, StaticEmbeddingClient335 336v0 = StaticEmbeddingClient()  # Backward-compatible alias337v1 = LayoutEmbeddingClient(version="v1")338v2 = LayoutEmbeddingClient(version="v2")339 340record = v2.get("layout:sha256:<layout hash>")341neighbors = v2.nearest(record["layout_id"], limit=10)342schema = v2.schema()343```344 345Because v2 consults no catalogue statistics, a layout that is not in this346dataset can be encoded directly into the same space:347 348```python349from squadds.layouts import encode350 351vector = encode("my_capacitor.gds", {"digit_pitch": "5.5um", "digit_population": 9})352```353 354SQuADDS_DB rows can resolve the same vector directly with355`SQuADDS_DB.get_layout_embedding(row, embedding_version="v2")`. Omitting the356version preserves the v0 default. The SQuADDS MCP server also provides357`get_layout_embedding` and `find_similar_layouts`.358 359## Provenance360 361Raw GDS artifacts, layer semantics, checksums, and geometry features live in362[SQuADDS/SQuADDS_Layouts](https://huggingface.co/datasets/SQuADDS/SQuADDS_Layouts).363Simulation results and design options live in364[SQuADDS/SQuADDS_DB](https://huggingface.co/datasets/SQuADDS/SQuADDS_DB).365The generalized-capacitor dataset was contributed by Saikat Das of the366Levenson-Falk Lab at USC.367 368## Citation369 370If you use this dataset, cite SQuADDS:371 372```bibtex373@article{Shanto2024squaddsvalidated,374  doi = {10.22331/q-2024-09-09-1465},375  title = {{SQ}u{ADDS}: {A} validated design database and simulation workflow for superconducting qubit design},376  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},377  journal = {{Quantum}},378  volume = {8},379  pages = {1465},380  year = {2024}381}382```383 384This dataset is licensed under the [MIT License](https://github.com/LFL-Lab/SQuADDS/blob/master/LICENSE).385