Conversation
v0 and v1 are fit on write: their normalization statistics, and in v1 the selected spectral frequencies, come from whichever rows are written together. An outside contributor running either builder lands in a different space even though the vectors share a length, which blocks the foundation-model workflow. Neither standard exposed a way to encode a new layout at all. universal-geometry-v2 is a pure function of one GDS file and one design-option mapping. Every one of its 512 coordinates is a physical measurement in micrometers, inverse micrometers, or farads per meter, accumulated onto frozen bin edges, so no catalogue statistic is consulted anywhere. The blocks are 48 named physical metrics, a 192-bin coupling spectrum holding facing boundary length per terminal pair per absolute separation, 128 shape-spectrum coefficients, 96 dimension-typed parameter statistics that give any parameter schema a fixed width, and a 48-coordinate two-dimensional boundary-element physics proxy. v2 is deliberately not scale invariant. v0 and v1 crop each layout to its own bounds, so a design and its exact enlargement produce identical shape blocks even though their capacitance differs; conductor separation in micrometers is the dominant variable and v2 measures it absolutely. Under an identical model, split policy, and label budget over 13,683 paired designs, v2 raises the full-budget specialist from macro R2 0.984 to 0.9998 and the 1%-label specialist from 0.235 to 0.780. Stripping every design parameter out of v2 still beats the whole of v0, so the gain is geometric rather than an artifact of retaining more parameter detail. - add squadds/layouts/geometry_v2.py with encode() and the frozen schema - register v2 in LayoutEmbeddingClient alongside v0 and v1 - add scripts/build_v2_embeddings.py, which performs no catalogue-wide fitting - add Tutorial 18, the quantitative v0 versus v2 study - add Tutorial 19, a worked example of the encoder with the coupling spectrum re-derived by hand and checked against the implementation - add 17 contract and regression tests covering invariance, scale sensitivity, gap monotonicity, and fixed width across parameter schemas
shanto268
changed the title
nearest() computed a bare dot product between the query and each candidate. That equals the cosine only because v0 and v1 vectors are unit normalized. universal-geometry-v2 stores absolute physical measurements and is deliberately not unit normalized, so the same expression reported similarities in the thousands in a column named cosine_similarity. Divide by the vector norms instead of assuming them. v0 and v1 results are unchanged because their norms are one; v2 now returns values in [-1, 1]. This also fixes the MCP find_similar_layouts tool, which calls the same method.
Tutorial 17 concluded that only the two NCap classes shared a comparable supervised target. TransmonCross reports cross_to_claw, which is the mutual capacitance between two conductors exactly as north_to_south and top_to_bottom are, so three families share one physical target. That makes the held-out-class experiment possible for the first time. Across those three classes the design-option vocabularies intersect in exactly one name, orientation, a placement angle. A parameter-schema baseline for a three-class model does not exist, so a geometry-derived contract is not merely better, it is the only option. Tutorial 20 runs the study on the full catalogue and again on a balanced cohort of 894 designs per class, following the Tutorial 16b pattern so class size stops being a confound. Balanced, v2 predicts a completely unseen component class with zero labels in two of three rotations, reaching macro R2 0.859 and 0.422 where v0 reaches -7.7 and -17.6. A brand-new family needs about ten labels to pass 0.94. A source prior helps only when the representation aligns the classes: at five labels adaptation lifts v2 from 0.610 to 0.887 and pushes v0 from 0.261 down to -0.502. Two negative results are reported rather than dropped. Predicting the physics-proxy residual is worse than predicting capacitance directly in every rotation, because the two-dimensional proxy carries a class-dependent offset. Cross-class cosine similarity has the wrong sign on every pair involving the qubit class, for both representations. Tutorial 19 gains a pipeline roadmap, an interactive slider that replays each encoder step against the coordinates it writes, and a closing section on what would have to change to build embeddings for a different design family or a different simulation output.
The Hugging Face table now holds 17,727 rows spanning GeneralizedCapNInterdigital, TransmonCross, CavityClawRouteMeander and CapNInterdigitalTee, so Tutorial 20's cross-class study is reproducible from the published dataset rather than only from a local build. Every vector in the earlier GeneralizedCapNInterdigital-only release is byte-identical in this one. Adding three families changed none of them because no v2 coordinate is derived from catalogue statistics, which is the fit-on-write property being absent, demonstrated rather than asserted. Also corrects three statements in the release document that the cross-class study made stale: the claim that only one component class had been measured, the single-family build command, and the upload commit message. Records the measured severity of the compressed cosine spread, which is family dependent and worst within TransmonCross at 0.9928 to 1.0.
Tutorial 16b defined the fairest experiment in the repository: each exact finger count is a domain, every domain is deterministically cut to the same size so domain size stops being a confound, and specialists, two pooled generalists and a count-8 foundation are compared under twelve stratified holdouts with paired intervals and Benjamini-Hochberg correction. This runs that protocol unchanged on universal-geometry-v2, with v0 recomputed on exactly the same rows and splits so every comparison is paired. The only variable is the embedding. On 754 designs per domain, the v2 specialist reaches macro R2 0.972 with 28 labeled designs where v0 needs the full 566-row pool to reach 0.984; at six labels v2 reaches 0.666 and v0 reaches 0.023. v0's budget-matched generalist is negative at every budget through 50% and bottoms out at -4.33 while the v2 version stays positive throughout. The gain is geometric: v2 with its parameter block removed still beats all of v0 at every budget. A source prior helps v2 and harms v0. Averaged over the twelve non-source domains the count-8 foundation changes v2's held-out R2 by +0.153 at 1% labels and v0's by -2.147, with every v0 cell at that budget robustly negative after correction. Across the full 13x13 atlas transfer beats a same-budget specialist in 80.5% of ordered pairs with v2 and 58.4% with v0. The cohort is 754 per domain rather than 16b's 1,260 because the upstream layout repository publishes 10,000 of the 16,379 q3d_cap GDS artifacts its manifest lists. The v0 comparison is paired on the same rows, so the conclusion is unaffected, but absolute values are not comparable to 16b's. The 13x13 atlas fits one target head against thirteen priors, so the notebook factorizes once per training set and re-solves per source, asserting the fast path reproduces TransferRidgeRegressor before any result depends on it.
Tutorial 21 ablates v2's blocks inside one component family and finds the parameter block nearly redundant. Tutorial 20 section 6 found the opposite across classes. Both are right, and the resolution is worth measuring rather than asserting. Adds a section evaluating every block in three settings on the balanced cohort: in-class prediction, cross-class with no labels, and cross-class after ten labels from the unseen family. In-class the ablation is almost uninformative. Every block on its own reaches macro R2 0.987 or better, from the shape spectrum at 0.9963 to the physics proxy at 0.9870, against the full vector's 0.9998. Predicting capacitance inside one family is easy enough that any faithful description of the geometry will do. Across classes the same blocks span 0.960 to -3.53, and the ordering is not a rescaling of the in-class one. The shape spectrum reverses outright: among the best in-class and by far the worst across classes, at -56.2 with no labels, because contour harmonics and two-point correlations describe what a family looks like and a comb does not look like a cross. The physical metrics transfer best at 0.960 with ten labels, ahead of the full vector, because absolute area, perimeter, gap and width mean the same thing for a coupler and a qubit. Also restores the kernel metadata on Tutorials 18 and 21, which had been rewritten to a local kernel name by an editor session. Cell outputs are untouched.
The three families did not share a layer convention. GeneralizedCapNInterdigital expresses its etch as a hole in a ground plane sized to about 5.8 times the conductor extent, with two ports bridging the moat from each terminal to ground. CapNInterdigitalTee carried a fixed 9 mm by 6 mm plane, 500 times too far in one axis, and TransmonCross had no ground plane at all; both put their etch on a separate layer and neither port reached ground. Three families were being described in three reference frames. Regenerating them against the GeneralizedCapNInterdigital convention repairs most of the damage that mismatch was causing. Held-out GeneralizedCapNInterdigital moves from -3.998 to -0.031, averaged zero-shot from -2.58 to -0.667, and on a class-balanced cohort two of three rotations are positive at +0.559 and +0.534 where only one was before. Held-out CapNInterdigitalTee holds at +0.817 and cross-family transfer into it reaches 0.994 from thirteen labeled designs. TransmonCross remains the failing rotation at -5.618, negative in both cohorts so not a class-size artefact. It is also the family with the lowest cross-family cosine, 0.044 against the generalized coupler, and the only one whose terminals differ enormously in scale. Ordered ports alone contributed nothing measurable on TransmonCross: its conductor geometry was byte-identical to the published release and its port ordering never disagreed with the previous area-based fallback across 1,934 files. The gain came from the ground plane and moat. - add a gallery drawing one design per family from its GDS polygons, coloured by the role the encoder assigns - add a slider over all six family pairings showing the closest and farthest design pair by cosine similarity, with a mean-cosine matrix - hash the embedding matrix into the checkpoint fingerprint, since the portless and port-complete cohorts share design_id values and a row count alone would have silently reused stale results - rewrite every interpretive block and the conclusions against the new numbers
Three scripts rebuild the layout representations from the regenerated GDS and evaluate them, writing every output to a separate experiment directory so nothing is mixed with the published tables. build_port_complete_embeddings.py produces four clearly separated representations: static-shape-v0 exactly as published, which ignores the new ports for these families and therefore isolates geometry on its own; two labelled local v0 variants, one etch-aware and port-blind and one recognizing both, so the etch effect can be separated from the port effect; and a local v1 fit on this two-family cohort, which is not comparable to published v1 because that standard is Generalized-only and fit on write. run_port_complete_study.py runs within-family prediction and cross-family transfer under repeated holdouts grouped on design_id, so the one duplicated TransmonCross design can never straddle train and test. It resolves the published tables through the hub and refuses a table with fewer than 24,000 rows, because several stale snapshots are cached locally and one holds 4,577 rows, which silently drops entire component families from the comparison. verify_terminal_ordering.py checks terminal and port discovery across every row. The study isolates three effects rather than attributing differences to retraining. TransmonCross etch, which published v0 discards entirely, is worth -29.5% RMSE. TransmonCross ordered ports are worth -4.0% under v0 and -0.2% under v2, a null. CapN ordered ports are worth -15.7% under v0, consistent with ports correcting terminal order in 87 of 894 designs where TransmonCross never needs correcting. It also quantifies a fit-on-write confound: TransmonCross geometry is provably identical between releases, yet a rebuilt v0 is 20% worse than the published one purely because its normalization was refit over a smaller cohort.
Merges the regenerated TransmonCross and CapNInterdigitalTee rows into the published manifest, keeps GeneralizedCapNInterdigital and CavityClawRouteMeander exactly as published, and rebuilds geometry features from the merged result. The script refuses to stage unless design_id and source_id are set-identical to the published manifest, because layout_id is a content hash and necessarily changes for regenerated geometry while those two are the keys the database bridge and every published study join on.
v2 vectors 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 0.9928 to 1.0 and nearest() reports 1.0000 for its top matches. The vectors are correct and nearest() computes a true cosine; a raw cosine is simply the wrong metric for a non-negative, absolutely anchored representation. The fix keeps the two concerns separate. The vectors stay catalogue-free and byte-stable; only the metric is fitted, and it is frozen, published and versioned independently, so a newcomer applies the published transform rather than refitting locally. The transform is centre, scale, then shrinkage-regularized ZCA whitening. Shrinkage was selected by sweeping it against the rank correlation between similarity and capacitance difference within a family and the worst such correlation across any pair of families. At 0.70 every cross-family pair still has the correct sign, where plain standardization leaves one pair at +0.218 and a raw cosine leaves one at +0.384, and the usable spread is 275 times the raw value. nearest() gains a metric argument. It applies the published transform when one exists and falls back to the raw cosine otherwise, so older dataset revisions and the already unit-normalized v0 and v1 keep working unchanged.
The published GeneralizedCapNInterdigital sweep does not scale its ground plane with the device. Across 120 files the per-side padding is uncorrelated with conductor width, Pearson -0.10, so the reference convention is a fixed absolute margin and the 5.8x rule adopted earlier was a misreading of it. The distinction matters for an absolutely anchored coupling spectrum. A proportional rule places the ground plane furthest from the largest device, so TransmonCross, the biggest of the three families and the one that fails, was given a ground plane about 1.7 mm from its conductor. A fixed 169 um margin, the pooled median of the reference sweep, brings every family's ground to a comparable absolute distance. Regenerating all 2,828 files on that rule improves every comparable measurement. Held-out CapNInterdigitalTee moves from +0.817 to +0.824 and Generalized from -0.031 to -0.001, averaged zero-shot from -0.667 to -0.627, and on the balanced cohort all three rotations improve. The gains are small because the ground distance enters only the 48 terminal-to-ground coordinates, while the mutual coupling that dominates these targets is unchanged. TransmonCross improves from -5.618 to -5.385 and remains unsolved. The validator now checks the per-side margin against the 50 to 400 um band the reference sweep spans instead of a fixed ratio. Also makes the Tutorial 20 geometry panels resolve GDS lazily through the hub and skip files the layouts repository advertises but does not store, rather than assuming a complete local mirror.
The coupling block stores log1p of the absolute facing boundary length in each distance bin. That magnitude scales with the device, so it partly encodes which family a design belongs to rather than how its terminals couple, and that is precisely the component which cannot transfer to an unseen class. Dividing by the summed terminal perimeter keeps the distribution across distances and discards the overall size, which the metric block already records separately. Measured over five seeds on the three families that share a mutual capacitance target, zero-shot prediction of a held-out GeneralizedCapNInterdigital moves from macro R2 -0.069 with standard deviation 0.115 to +0.918 with standard deviation 0.011. Ten-label accuracy improves on Generalized, 0.923 to 0.967, and on TransmonCross, 0.915 to 0.947. It costs accuracy on held-out CapNInterdigitalTee, 0.829 to 0.744, so it ships as an opt-in transform rather than as a change to the standard. This also falsifies the terminal-scale-asymmetry hypothesis for TransmonCross. Conditioning on per-terminal scale does not rescue it: -3.560 to -4.198, a difference well inside the seed-to-seed spread of about 1.0. Whatever makes a transmon unpredictable from two couplers is not the size ratio of its terminals. The transform is an exact function of a published vector, since expm1 recovers the stored lengths and perimeters, so it needs no re-encoding, no dataset change and no new embedding version.
Adds CoupledLineTee, Cap3Interdigital, CapNInterdigital, TransmonPocket and StarQubit as declarative sweep specifications, plus a driver that renders them into the published layout convention ready for capacitance simulation. The generation is deliberately generic. The published families needed bespoke port code because their terminals were identified by hand, but a Metal component already declares its pins and its own subtractive geometry, so ordered terminal markers and the ground clearance can both be derived from the component itself. Adding a family is a SweepSpec entry and nothing else. Two of these exist to exercise parts of the encoder that no published design has ever reached. The coupling block reserves six terminal-pair slots and four terminal-to-ground slots, but every design published so far is two-terminal, so five pair slots and two ground slots are identically zero across all 17,727 rows and the fitted metric discards them as constant. TransmonPocket renders four electrically isolated islands, two qubit pads and two connection pads, and populates all six pair slots and all four ground slots. StarQubit renders six islands, which exceeds MAX_TERMINALS, and covers the truncation path while still recording the true terminal count. Full grids generate with no failures: CoupledLineTee 675, TransmonPocket 216, CapNInterdigital 192, Cap3Interdigital 180, StarQubit 81. Every family encodes under universal-geometry-v2 with no change to the encoder. Also lets the metric builder fit against a local embedding table, so a metric can be frozen against the exact vectors it ships beside rather than against whatever is published at the time.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
static-embedding-v0as the backward-compatible 9,227-dimensional baselineuniversal-geometry-v1schema v1.1, a 1,024-dimensional GDS and layout-control encoderuniversal-geometry-v2, a 512-dimensional encoder that consults no catalogue statistics at allv0/v1/v2selection, control maps, nearest-neighbor search, and shape reconstructionWhy v2 exists
v0 and v1 are fit on write. Their normalization statistics, and in v1 the selected spectral frequencies, are derived from whichever rows are written together. A collaborator who runs either builder on their own thousand designs lands in a different space, even though the vectors share a length. Neither standard exposed any way to encode a new layout in the first place.
That blocks the workflow the whole layout-embedding effort exists to enable: another group contributes GDS files plus a results table, we project their designs into the space our catalogue already occupies, find the nearest design family, and transfer.
universal-geometry-v2makessquadds.layouts.encodea pure function of one GDS file and one design-option mapping. Every coordinate is a physical measurement — micrometers, inverse micrometers, farads per meter — accumulated onto frozen bin edges.A second correction: v0 and v1 crop each layout to its own functional bounds, so a design and its exact enlargement produce identical shape blocks. Since conductor separation in micrometers is the dominant variable for capacitance, that discards the answer. v2 measures distances absolutely and is deliberately not scale invariant.
universal-geometry-v2512 dimensions in five blocks, none fitted to any catalogue:
Terminals are discovered as connected components 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 is what lets a 28-parameter foreign schema and our 40-parameter one occupy the same 96 coordinates.
Simulation targets are never embedding inputs.
Results
Identical model, splits, label budgets, and test rows over 13,683 paired designs; 13 finger-count domains, 12 stratified holdouts. Only the input vector differs.
static-shape-v0(155 compact)universal-geometry-v2v2 at 10% of the labels beats v0 trained on the entire pool.
The control that matters
v0 compresses 40 design options into one scalar sum while v2 keeps 96 dimensions of parameter statistics, so the gain could have been parameters rather than geometry. It is not:
Computed from the GDS file and nothing else, v2 beats all of v0 at every budget. The coupling spectrum by itself beats all of v0. v0's raster — 144 of its 155 compact dimensions — is worse than useless at low budgets, which is the quantitative form of the scale-blindness argument.
Physics validation, before any model is fitted
log1p_primary_inverse_gap_integral(facing-boundary integral)log1p_conductor_area_um2log1p_minimum_pair_gap_umGap alone does not set capacitance; gap weighted by facing length does. That distinction is exactly what the spectrum encodes and a scalar summary cannot.
Applicability
v2 similarity ranks zero-shot error more than twice as well as v0 (Spearman -0.560 against -0.248) and halves the median zero-shot error (15.3% against 33.1%). This is the signal the "which family does this newcomer resemble" workflow depends on.
Tutorials
Limits, stated in the notebooks
Upstream data gap
The v2 table covers 13,683 of the 20,062
GeneralizedCapNInterdigitaldesigns that v0 and v1 cover.SQuADDS/SQuADDS_Layoutscurrently publishes 10,000 of the 16,379q3d_capGDS artifacts its ownmetadata/manifest.parquetlists, so the remaining 6,379 layouts cannot be encoded from released geometry. v0 and v1 predate that gap.release-manifest.jsonrecords the count aslayouts_without_downloadable_gds. Re-uploading the missing artifacts and re-running the builder is the only step needed for full coverage; the encoder does not change.Validation
ruff checkandruff format --checkcleandocs/source/layout_embeddings_v2_release.mddocuments the release and reproduction commandsTutorials 19, 20 and 21
TransmonCrossreportscross_to_claw, a mutual capacitance exactly asnorth_to_southandtop_to_bottomare, so three families share one target and an entire class can be held out. Across those three the design-option vocabularies intersect in exactly one name,orientation, a placement angle: no parameter-schema baseline exists for a three-class model.Unified port-complete layout release
Tutorial 20's latest run uses regenerated
CapNInterdigitalTeeandTransmonCrossGDS that follow theGeneralizedCapNInterdigitalconvention: a ground plane sized to about 5.8x the conductor extent and centred on it, the etch expressed as a single hole in that plane rather than its own layer, and two ordered ports bridging the moat from each terminal to ground. All 2,828 files pass layer-set, single-hole, port-touches-conductor-and-ground, distinct-terminal and two-terminal checks.Before that unification the three families sat in three different reference frames, and it cost real accuracy:
CapNInterdigitalTeeGeneralizedCapNInterdigitalTransmonCrossOn a class-balanced cohort two of three rotations are now positive (+0.559, +0.534). Averaged zero-shot moved from -2.58 to -0.667 against v0's -11.21. Cross-family transfer into
CapNInterdigitalTeereaches macro R2 0.994 from thirteen labeled designs, against 0.769 for v0 and 0.625 for the manually aligned parameter baseline. A brand-new component family needs about ten labels to pass 0.94.Two results worth keeping in view:
Still open
TransmonCrossis not predictable from the other two, at -5.618 full and -3.029 balanced. Negative in both cohorts, so not a class-size artefact. It has the lowest cross-family cosine of any pair, 0.044 against the generalized coupler, and is the only family whose terminals differ enormously in scale.TransmonCross: conductor geometry byte-identical to the published release, port ordering never disagreeing with the previous area fallback across 1,934 files. The gain came from the ground plane and moat.TransmonCrosswhere the family spans 0.9928 to 1.0. A frozen whitening transform is still needed before v2 similarity is used for retrieval.q3d_capGDS artifacts its own manifest lists.