squadds.ml.capacitance package#

Submodules#

squadds.ml.capacitance.benchmark module#

Scoring of capacitance models with the paper’s metric rules.

Per layout and entry kind: the median over its entries of |p - y| / max(|y|, 0.1 fF) in %, the MAE and the RMSE in fF; then the mean over layouts (the layout mean), so a 68-conductor chip and a two-pad capacitor count once each. Kinds: mutual (every off-diagonal pair, the headline), signal-signal, signal-ground, signal_self, ground_self. Unknown (NaN) label entries are dropped and counted. Every report carries the wall time, machine and thread count.

Validation scoring is open to everyone. Test scoring (split="test") is maintainer-only: once per declared model, recorded in a ledger, and only for models whose training keys are disjoint from the scored layouts (models trained on the TRAIN split).

class squadds.ml.capacitance.benchmark.ScoreReport(layouts: 'object', by_family: 'object', overall: 'object', timing: 'dict' = <factory>, split: 'str' = 'val', model: 'str' = '')[source]#

Bases: object

by_family: object#
headline(kind='mutual')[source]#
Return type:

dict

layouts: object#
model: str = ''#
overall: object#
split: str = 'val'#
timing: dict#
to_dict()[source]#
Return type:

dict

squadds.ml.capacitance.benchmark.checkpoint_paths(model)[source]#

Checkpoint files of a model given as a CapacitanceModel, a run dir / .pt path, or a list of them.

Return type:

list[Path]

squadds.ml.capacitance.benchmark.entry_kinds(sig, pairs)[source]#
Return type:

ndarray

squadds.ml.capacitance.benchmark.layout_rows(y, p, sig, pairs, key, family)[source]#

Per-kind metrics of one layout (y, p: Maxwell matrices in fF).

Return type:

list[dict]

squadds.ml.capacitance.benchmark.load_checkpoints(model, threads=2)[source]#

[(checkpoint dict, network in eval mode)] of a model (CapacitanceModel, path(s), run dir(s), or checkpoint dict(s)).

Return type:

list[tuple[dict, object]]

squadds.ml.capacitance.benchmark.paired_difference(a, b, kind='mutual', n_boot=2000, seed=0)[source]#

Layout-paired difference a - b of the layout means (median % and MAE fF) with a layout-bootstrap 95% interval. a, b: ScoreReports or layout frames scored on the same layouts.

Return type:

dict

squadds.ml.capacitance.benchmark.predict_arrays(models, d, schema, rows=None, chunk=64)[source]#

Ensemble-mean Maxwell matrices (fF) of shard rows rows of one shard dict d (all rows by default): the checkpoint’s own standardisation, intercepts and arm, as infer.Predictor.from_features does per layout.

Return type:

ndarray

squadds.ml.capacitance.benchmark.score(model, data, labels=None, split='val', maintainer=False, threads=2, families=None, keys=None, ledger_dir=None, name=None, **predict_kwargs)[source]#

Score a model on the split rows of a shard dir, or on layouts with labels.

model: "QCap" / "QCap-Fast" (released), a CapacitanceModel, a run dir / .pt path (or a list = ensemble), or checkpoint dict(s). data: a shard dir (array route: the stored embedding and priors) or a list of layouts (GDS paths / PreparedLayouts, predicted end to end) with labels = one (names, Maxwell matrix fF) or cap_matrix.csv path per layout. families / keys restrict the shard rows.

Return type:

ScoreReport

squadds.ml.capacitance.benchmark.summarize(layouts)[source]#

(per family x kind layout means, overall per kind layout means) of a layout-metric frame.

Return type:

tuple

squadds.ml.capacitance.bridge module#

Bridges from the planar capacitance models into the existing SQuADDS workflows.

  • MLSimulator: the call and result shape of the capacitance (Q3D / LOM) path of AnsysSimulator (simulate(device_dict) -> {"design", "sim_options", "sim_results"}) plus fidelity="ml:<model>" and timing. Input: a Qiskit Metal design or component, a SQuADDS row (rebuilt with the component registry) or a GDS path.

  • predict_dataframe: predictions for the rows of an Analyzer result (Analyzer.predict_capacitance calls it).

  • transmon_cross_capacitances / EC_MHz / g_MHz / EC_MHz_from_matrix: feed squadds.calcs.

Export (export=): "auto" (default) writes a component of a dataset family (squadds.layouts.dataset_export: interdigital / paddle, concentric, star, Xmon, TransmonPocket, shielded concentric) exactly as the dataset was exported, so the model sees the input it was trained on; any other layout (e.g. quantum-metal TransmonCross, several components) goes through export_qgeometry_gds (square ground domain, 169 um padding). "dataset" / "qgeometry" force one. The result records it in export. Star rows of the SQuADDS view carry their style in notes.export_style. Conductor bodies are named from the qgeometry they overlap (planar_capacitance_view.QGEOMETRY_NETS), so the sim_results keys match the SQuADDS configs (north_to_south, cross_to_claw, …).

squadds.ml.capacitance.bridge.EC_MHz(x)[source]#

Charging energy (MHz) with the existing SQuADDS convention C_sum = cross_to_ground + cross_to_claw (squadds.calcs.transmon_cross.EC_numba). A second claw is not included: use EC_MHz_from_matrix for it.

Return type:

float

squadds.ml.capacitance.bridge.EC_MHz_from_matrix(C, names, nodes)[source]#

Charging energy (MHz) of a qubit mode from a full Maxwell matrix (fF, every other conductor held at ground).

nodes: one conductor name (grounded transmon: C_sum = C_ii, every coupling included) or two (floating transmon, the differential mode: 1 / C_eff = (C^-1)_aa + (C^-1)_bb - 2 (C^-1)_ab of the two-pad block).

Return type:

float

class squadds.ml.capacitance.bridge.MLSimulator(analyzer=None, design_options=None, model='QCap', threads=None, predictor=None, clearance_um=None, workdir=None, export='auto', export_style=None, margin_gaps=None, ground_gap_um=None, tier=None, **predict_kwargs)[source]#

Bases: object

Capacitance from the planar capacitance models, in the result shape of AnsysSimulator’s capacitance path.

sim = MLSimulator(analyzer, device_dict) # like AnsysSimulator(analyzer, device_dict) res = sim.simulate() # {“design”, “sim_options”, “sim_results”, …} MLSimulator(model=”QCap-Fast”).predict(“chip.gds”) # or a component, a design or a SQuADDS row

model: "QCap" (default), "QCap-Fast" or a loaded CapacitanceModel. predictor: any object with predict(layout) -> CapacitanceResult (tests). export: "auto" (dataset export for the dataset families, else "qgeometry"), "dataset" or "qgeometry"; export_style / margin_gaps / ground_gap_um override the dataset export (squadds.layouts.dataset_export.export_dataset_gds; a row’s notes.export_style is used when not set).

property fidelity: str#
predict(obj, component_name=None)[source]#

Prediction for a GDS path, a Qiskit Metal design or component, or a SQuADDS row / device dict.

Return type:

dict

property predictor#
simulate(device_dict=None, run_async=False)[source]#

AnsysSimulator.simulate for single components (capacitance only).

Return type:

dict

squadds.ml.capacitance.bridge.body_labels(conductors, design)[source]#

Dataset net label (N, S, P1, …) of each conductor body, and the component class when the layout has a single component. Unmapped bodies keep the predictor’s name C<k>; with several components the labels are <component>:<element>.

Return type:

tuple[list[str], str | None]

squadds.ml.capacitance.bridge.build_component(row, component_name=None, design=None, name='component')[source]#

Rebuild the component of a SQuADDS row in design (a new DesignPlanar by default).

squadds.ml.capacitance.bridge.component_class(name)[source]#

Qiskit Metal class of a dataset component name (SQuADDS registry first, then quantum-metal qubits).

squadds.ml.capacitance.bridge.default_clearance_um(design)[source]#

Signal-to-ground clearance for the exported ground: the smallest lead / claw / ground gap option of the components (the native etch stays authoritative; the clearance only closes open CPW ends).

Return type:

float

squadds.ml.capacitance.bridge.g_MHz(x, EJ_GHz, f_r_GHz, res_type='quarter', Z0=50.0)[source]#

Qubit-claw coupling g (MHz) from squadds.calcs.transmon_cross.g_from_cap_matrix_numba with the predicted cross_to_ground (C_Q) and cross_to_claw (C_g).

Return type:

float

squadds.ml.capacitance.bridge.predict_dataframe(df, model='QCap', component_name=None, simulator=None, **kwargs)[source]#

One prediction per row of a SQuADDS DataFrame (closest designs, interpolated designs): a DataFrame with the same index, the predicted sim_results columns (suffix _ml), fidelity, ml_total_s and ml_result.

squadds.ml.capacitance.bridge.render_gds(design, path, clearance_um=None)[source]#

Export design to a GDS in the training layer convention (ground (1, 0), conductors (1, 10)).

Return type:

Path

squadds.ml.capacitance.bridge.row_notes(row)[source]#

notes of a SQuADDS row (nested record or flattened DataFrame row); {} for a device dict without notes.

Return type:

dict

squadds.ml.capacitance.bridge.row_options_and_class(row, component_name=None)[source]#

(design_options, component class name) of a SQuADDS row: nested HF record, flattened DataFrame row (Series or dict) or an AnsysSimulator device dict.

Return type:

tuple[dict, str]

squadds.ml.capacitance.bridge.transmon_cross_capacitances(x)[source]#

cross_to_claw and cross_to_ground (fF) of a TransmonCross / Xmon prediction or row, the inputs of squadds.calcs.transmon_cross (EC, g). x: an MLSimulator result, a sim_results dict or a DataFrame row.

Return type:

dict

squadds.ml.capacitance.cli module#

squadds-ml predict: GDS -> full Maxwell capacitance matrix (fF, ground first) from the command line.

squadds.ml.capacitance.cli.cmd_predict(a)[source]#
Return type:

int

squadds.ml.capacitance.cli.main(argv=None)[source]#
Return type:

int

squadds.ml.capacitance.contribute module#

Contributing planar capacitance data and models to SQuADDS/SQuADDS_PlanarCapacitance (Hugging Face pull requests).

Data: a contribution directory in the template layout (squadds/database/templates/planar_capacitance_contribution):

manifest.yaml       contributor, licence, solver, stack, setup, layer map, units, generator, family
designs.csv         design, gds, family, params_json, net_order (G first, then conductors in GDS file order), notes
gds/<design>.gds
sims/<design>/<sim_tag>/cap_matrix.csv    Q3D export as is (one row per pass)   or   matrix.csv / matrix.parquet
sims/<design>/<sim_tag>/convergence.txt   the Q3D .conv file (optional)
sims/<design>/<sim_tag>/run.json          solver version, cores, solve_s, wall_s, peak_mem_GB, machine (optional)
nets/<design>.json                        {net: [conductor-layer polygon indices]} (optional explicit net map)

validate_capacitance_contribution(dir) runs the dataset validator (schema, GDS readback, net names, label QC, duplicates, stack, licence, privacy) and contribute_capacitance(dir) opens a pull request adding contrib/<org>-<batch>/ and its validation_report.md. Maintainers merge, compute the priors on HPC and ingest the rows as source="community", split="none".

Models: contribute_model(repo_id, revision) validates a model repository (checkpoints load, sha256, required metadata, validation score with median % and MAE / RMSE in fF plus time, machine and threads) and opens a pull request adding its entry to model_zoo.yaml. Test-set scores are never self-reported: they are run by the maintainers, once per declared model, only for models trained on the TRAIN split.

squadds.ml.capacitance.contribute.contribute_capacitance(path, repo_id='SQuADDS/SQuADDS_PlanarCapacitance', dry_run=False, org=None, batch=None, reference='auto', check_prior=False, api=None, token=None)[source]#

Validate path and open a pull request on the dataset repo_id adding contrib/<org>-<batch>/ (manifest, designs, GDS, simulations, validation_report.md, submission.json with the .env contributor block).

A contribution with errors is refused (ValueError). dry_run: validate and return the planned files without any network call. Returns {"ok", "pr_url", "folder", "files", "report"}.

Return type:

dict

squadds.ml.capacitance.contribute.contribute_model(model_repo_id, revision=None, registry_repo='SQuADDS/SQuADDS_PlanarCapacitance', metadata=None, val_data=None, dry_run=False, local_dir=None, threads=2, api=None, token=None, loader=None)[source]#

Validate a model repository (validate_model) and open a pull request on registry_repo adding its entry to model_zoo.yaml plus model_zoo/<id>/validation_report.md. A model with errors is refused (ValueError). Returns {"ok", "pr_url", "entry", "report", "files"}.

Return type:

dict

squadds.ml.capacitance.contribute.load_manifest(path)[source]#
Return type:

dict

squadds.ml.capacitance.contribute.parse_net_order(s)[source]#
Return type:

list[str]

squadds.ml.capacitance.contribute.read_designs(path)[source]#
Return type:

list[dict]

squadds.ml.capacitance.contribute.read_sim(sim_dir, unit='fF')[source]#

One simulation directory -> {“names”, “C” (label, given unit), “passes”, “unit”, “convergence”, “run”}.

Return type:

dict

squadds.ml.capacitance.contribute.sanitized_manifest(manifest)[source]#

The manifest as it is uploaded: absolute paths stripped, the e-mail dropped unless contributor.email_public.

Return type:

tuple[dict, list[str]]

squadds.ml.capacitance.contribute.submitter_record()[source]#

The contributor block of the repo-root .env (GROUP_NAME, PI_NAME, INSTITUTION, USER_NAME, CONTRIB_MISC).

Return type:

dict

squadds.ml.capacitance.contribute.validate_capacitance_contribution(path, reference='auto', check_prior=False, threads=2, report_path=None, revision=None)[source]#

Validate a contribution directory (PLAN_DATASET_HF.md §4.2). Returns a QCReport with one child per design.

reference: the dataset’s designs (DataFrame with design_id, geom_hash, split) for the duplicate check; "auto" reads them with PlanarCapacitanceDB (a warning when the dataset is not reachable), None skips it. check_prior: also compare every label with optimized_physics_prior (needs [ml]; seconds per design; report only). report_path: also write the markdown report there.

Return type:

QCReport

squadds.ml.capacitance.contribute.validate_model(model_repo_id, revision=None, local_dir=None, metadata=None, val_data=None, threads=2, api=None, token=None, loader=None)[source]#

Validate a model repository for the model zoo. Returns (report, zoo entry).

The repository holds *.pt checkpoints (squadds-ml train run dirs or model.pt files) and squadds_model.yaml with name, title, licence, contributor, training_data (sha256, split_used, description) and val_score (median_pct, mae_fF, rmse_fF, layouts, seconds or seconds_per_layout, machine, threads); metadata overrides the file. val_data: a validation shard dir: the score is then computed here with benchmark.score and replaces the self-reported one. local_dir: a local copy of the repository (no download).

Return type:

tuple[QCReport, dict]

squadds.ml.capacitance.dataset module#

Query the SQuADDS/SQuADDS_PlanarCapacitance dataset (raw and processed tables) with pandas / pyarrow only.

No [ml] dependency: this module needs pandas, pyarrow and huggingface_hub (all core SQuADDS dependencies), so from squadds.ml.capacitance.dataset import PlanarCapacitanceDB works on a plain pip install squadds.

db = PlanarCapacitanceDB() # HF repo db = PlanarCapacitanceDB(local_dir=”/path/to/SQuADDS_PlanarCapacitance”) # or env SQUADDS_PLANAR_CAP_DATA ids = db.designs(family=”interdigital”, split=”val”).design_id[:5] db.labels(ids) # {design_id: N x N Maxwell matrix (pandas DataFrame, fF, ground first)}

Tables are read file by file with pyarrow column / row filters, so a query never loads more of the dataset than it asks for.

class squadds.ml.capacitance.dataset.PlanarCapacitanceDB(revision=None, local_dir=None, repo_id='SQuADDS/SQuADDS_PlanarCapacitance', token=None)[source]#

Bases: object

Read access to the planar capacitance dataset.

Parameters:
  • revision (str | None) – HF revision (commit sha, tag or branch) of repo_id; default DATASET_REVISION (the pinned commit), "main" for the latest; ignored with a local directory.

  • local_dir – a local copy of the repo (same layout as on HF). Default: env SQUADDS_PLANAR_CAP_DATA, else HF.

  • repo_id (str) – HF dataset repo (default SQuADDS/SQuADDS_PlanarCapacitance).

  • token (str | None) – HF token (default: the logged-in token, if any).

designs(family=None, split=None, n_conductors=None, collection=None, config=None, columns=None, design_ids=None)[source]#

Design rows (without the params JSON unless asked for in columns). family matches family, paper_family or model_family; config is the SQuADDS config name; each filter takes a value or a list.

Return type:

DataFrame

embedding(design_ids)[source]#

planar-capacitance-graph-v1 per design: nodes (one row per conductor, ground = node 0), edges (pairs i < j) and globals (dict).

Return type:

dict[str, dict]

files(table)[source]#
Return type:

list[Path]

gds_path(design_id)[source]#

Local path of the design’s GDS (downloaded from the HF repo when needed).

Return type:

Path

label_passes(design_ids, columns=None)[source]#
Return type:

DataFrame

labels(design_ids, role='reference')[source]#

Final Maxwell matrices (fF, ground first) keyed by design_id (role = simulation role, default the reference Q3D solve); role=None returns every simulation keyed by simulation_id. Designs without a public label (test split) are absent.

Return type:

dict[str, DataFrame]

model_input(design_ids)[source]#
Return type:

DataFrame

nearest(query, k=5, family=None, split=None)[source]#

The k designs closest to query (a design_id, or a 127-value vector in pooled_embedding order) in the pooled embedding space, standardized per feature over the candidate set (Euclidean distance).

Candidates: designs of family (default: the query design’s model_family; all designs when the query is a vector and no family is given) and split. This is a simple geometric similarity, not a capacitance distance.

Return type:

DataFrame

optimized_physics_prior(design_ids, value='C_R_fF')[source]#

C^R = R(1.5, 3) on the corrected stack as N x N Maxwell matrices (value="mutual_1p5_fF" / "mutual_3_fF" for the two solves, diagonal from closure).

Return type:

dict[str, DataFrame]

params(design_ids)[source]#

Generator / component options of each design (parsed params JSON).

Return type:

dict[str, dict]

physics_prior(design_ids, value='C_fF')[source]#

Single thin-film MoM solve at p = 0.375 as N x N Maxwell matrices (fF, ground first).

Return type:

dict[str, DataFrame]

pooled_embedding(design_ids=None, family=None, split=None)[source]#

One vector per design (index design_id): the 4 global features, log N, and the mean and the max of each of the 61 node features over the signal conductors (ground node excluded); 127 values, not standardized.

Return type:

DataFrame

read(table, columns=None, design_ids=None, filters=None)[source]#

Rows of one table (all its split files) with optional column selection and pyarrow row filters ([("split", "=", "val")]); design_ids adds design_id in design_ids.

Return type:

DataFrame

simulations(design_ids=None, role=None, columns=None)[source]#
Return type:

DataFrame

tables()[source]#

Available tables -> their files (repo-relative paths); tables with no file are left out.

Return type:

dict[str, list[str]]

squadds.ml.capacitance.dataset.long_to_matrix(df, value, i='a_idx', j='b_idx', a='net_a', b='net_b')[source]#

Symmetric N x N DataFrame (index = columns = net names, in index order) from long-format entries i <= j.

A table that stores mutual entries only (no diagonal) gets the Maxwell diagonal from closure: C_ii = -sum_{j != i} C_ij (the ground net is one of the nets, so this is exact for a closed system).

squadds.ml.capacitance.models module#

Released planar-capacitance models: manifest, download (Hugging Face, pinned revision) and sha256 verification.

Sources, in order: path= (a local bundle: the repository layout, e.g. <path>/qcap/acc_v2m_sf_s0.pt), the environment variable SQUADDS_CAPML_MODELS (a directory holding one bundle per repository, named after it, e.g. $SQUADDS_CAPML_MODELS/QCap), else huggingface_hub.hf_hub_download from the manifest’s repository at its pinned revision. Every file is checked against the sha256 in the package manifest; a mismatch is refused.

class squadds.ml.capacitance.models.CapacitanceModel(name, entry, root, repo_id, revision, sha256=<factory>)[source]#

Bases: object

A verified local copy of one model.

entry: dict#
property key: str#

The manifest key (qcap, qcap-fast); name is the display name (QCap, QCap-Fast).

property learned_prior_sha256: str | None#
name: str#
registry()[source]#
Return type:

_Registry

repo_id: str#
revision: str | None#
root: Path#
sha256: list[str]#
property title: str#
property warning: str | None#
property weights_sha256: list[str]#
exception squadds.ml.capacitance.models.ModelIntegrityError[source]#

Bases: RuntimeError

A model file is missing or its sha256 differs from the package manifest.

squadds.ml.capacitance.models.is_model_name(name)[source]#

True when name is a released model’s name (see model_key; a retired name raises its ValueError).

Return type:

bool

squadds.ml.capacitance.models.list_models()[source]#

Served models (QCap, QCap-Fast) with their numbers (median % with MAE / RMSE in fF) and warnings. reference = the held-out numbers of the same recipe with networks trained on the TRAIN split only (reported in the paper), not of the served model; own = the served model’s in-sample fit; b5 = its one never-seen check.

Return type:

list[dict]

squadds.ml.capacitance.models.load_model(name='QCap', revision=None, path=None, cache_dir=None, local_files_only=False, tier=None)[source]#

A released model: load_model("QCap") (the default) or load_model("QCap-Fast"). Names are case-insensitive, with - and _ interchangeable.

Return type:

CapacitanceModel

squadds.ml.capacitance.models.model_files(entry)[source]#

(relative path, sha256) of every file a model needs.

Return type:

list[tuple[str, str]]

squadds.ml.capacitance.models.model_key(name)[source]#

Manifest key of a released model name: case-insensitive, - and _ interchangeable (QCap-Fast, qcap_fast). The pre-release names flagship / fast raise a ValueError naming the new ones; other names a KeyError.

Return type:

str

squadds.ml.capacitance.models.no_tier(tier)[source]#

Models are named directly since tiers were removed: refuse tier= with the call to use instead.

squadds.ml.capacitance.models.registry_view(arms, root, key)[source]#
Return type:

_Registry

squadds.ml.capacitance.models.sha256_file(p)[source]#
Return type:

str

squadds.ml.capacitance.models.verify(root, entry)[source]#

Check every file of a model under root against the manifest sha256 (ModelIntegrityError otherwise).

Return type:

list[str]

squadds.ml.capacitance.network module#

Networks of the planar-capacitance models (inference and training share these definitions).

build_model: the residual message-passing network of QCap and QCap-Fast (full_gnn; also direct_gnn / full_mlp / pair_mlp checkpoints), verbatim from tl-squadds scripts/geomfast/pilot_p2.py (sha256 in _core/SOURCES.json under network.py). build_surrogate: the learned prior surrogate of QCap-Fast (_core/lp_surrogate.py TriGNN).

squadds.ml.capacitance.network.build_model(dx, de, dg, rounds, width=64)[source]#
squadds.ml.capacitance.network.build_surrogate(dx, de, dg, w=128, rounds=4)[source]#

squadds.ml.capacitance.predictor module#

GDS -> full N x N Maxwell capacitance matrix with a released model.

The steps are those of the tl-squadds Spaces (geomgnn.paper.predict / geomgnn.flagship.predict), statement for statement: scene from the prepared layout -> geometric embedding (the model’s far-sample setting) -> thin-film priors under the model’s prior stack (or the learned prior surrogate) -> networks. The embedding and the priors are cached in memory by the layout’s geometry hash, so a repeated layout skips them.

class squadds.ml.capacitance.predictor.CapacitancePredictor(model=None, threads=None, embed_cache_dir=None, tier=None, **load_kwargs)[source]#

Bases: object

CapacitancePredictor(load_model("QCap")).predict("chip.gds") -> CapacitanceResult.

threads: CPU threads per prediction (default: every core this process may use, at most one per 2.5 GB of RAM and 32;

SQUADDS_CAPML_THREADS sets it too). Results are deterministic for a given thread count and machine, so pass the same threads to reproduce a result exactly.

embed_cache_dir: optional on-disk cache of per-body embedding blocks (bit-identical on the same machine).

predict(layout, threads=None, eps_r=11.45, thickness_um=350.0, workers=None, **prepare_kwargs)[source]#

layout: GDS path, gdstk Library / Cell, PreparedLayout, or a list of these (a list returns a list; workers > 1 predicts it on that many processes, each with threads threads; by default the cores are split between them). Extra keyword arguments go to the layout preparation (ground_layers, conductor_layers, margin_gaps, select, …).

eps_r, thickness_um: the substrate. Off the training stack (Si, 11.45, 350 µm) QCap solves the physics prior at this stack and correct it with the unchanged networks (the calibrated route, recorded in result.substrate); QCap-Fast rescales its training-stack prediction by (1 + eps_r) / (1 + 11.45) and warns. Combinations outside the tested range (Si at 10-1000 µm, or eps_r 3.8-24 at 350 µm) warn.

squadds.ml.capacitance.predictor.clear_cache()[source]#
squadds.ml.capacitance.predictor.quiet()[source]#

Silence numba’s performance hints of the compiled solver (no effect on values).

squadds.ml.capacitance.predictor.run_scene(reg, name, sc, lhash, threads, stack=None)[source]#

geomgnn.paper.predict_scene with the embedding row and the priors taken from / put into the in-memory caches. stack: (eps_r, thickness_um) the prior is solved at (None: the training stack); the embedding always uses the training stack.

Return type:

dict

squadds.ml.capacitance.priors module#

Physics priors: thin-film method-of-moments capacitance matrices of a layout (no learned parameter).

  • physics_prior: one solve at p = 0.375 panels per gap (the paper’s cheap-physics comparator).

  • optimized_physics_prior: C^R = R(1.5, 3) = exp(2 log C(3) - log C(1.5)), entry by entry, the physics prior of the paper model and of QCap.

Both run on the “corrected” prior stack (prior v2m + substrate far field, compiled exact solver; gap share alpha fitted once on TRAIN), exactly as the models compute them, on a substrate of eps_r and thickness_um (default the training stack, Si 11.45, 350 µm; the thin-film kernel is a dielectric slab of that thickness with vacuum below). Priors computed on macOS are not bit-identical to the released ones (HPC x86; up to ~2.4e-3 relative on some layouts): never mix them into released data.

TODO (other priors of the paper, not served yet): - uncorrected prior (v1, frozen solver + value-preserving rejection-tail fix; stack uncorrected) - version 2 (no window-margin widening; stack version2) - corrected prior with the half-space far field (v2m before 2026-10-20; stack corrected_halfspace) - single solves at 0.75 / 1.5 / 3 panels per gap - Richardson pair R(0.75, 1.5) (the paper’s balanced variant)

class squadds.ml.capacitance.priors.PriorResult(names: 'list[str]', C_fF: 'np.ndarray', solves_fF: 'dict' = <factory>, levels_ppg: 'list[float]' = <factory>, kind: 'str' = '', prior_version: 'str' = '', stack: 'dict' = <factory>, alpha: 'float' = 0.0, timing_s: 'dict' = <factory>, threads: 'int' = 2, machine: 'str' = '', layout_hash: 'str' = '', units: 'str' = 'fF')[source]#

Bases: object

C_fF: ndarray#
alpha: float = 0.0#
kind: str = ''#
layout_hash: str = ''#
levels_ppg: list[float]#
machine: str = ''#
names: list[str]#
prior_version: str = ''#
solves_fF: dict#
stack: dict#
threads: int = 2#
timing_s: dict#
to_dataframe()[source]#
to_dict()[source]#
Return type:

dict

units: str = 'fF'#
squadds.ml.capacitance.priors.optimized_physics_prior(layout, threads=None, eps_r=11.45, thickness_um=350.0, **prepare_kwargs)[source]#

C^R = R(1.5, 3) of the corrected stack (two solves, Richardson-extrapolated in log, every entry) on a substrate of eps_r and thickness_um: Maxwell matrix in fF, ground first; both solves are returned in solves_fF.

Return type:

PriorResult

squadds.ml.capacitance.priors.physics_prior(layout, threads=None, eps_r=11.45, thickness_um=350.0, **prepare_kwargs)[source]#

One thin-film solve at 0.375 panels per gap (corrected stack) on a substrate of eps_r and thickness_um: Maxwell matrix in fF, ground first.

Return type:

PriorResult

squadds.ml.capacitance.priors.solve(layout, levels, threads=None, eps_r=11.45, thickness_um=350.0, **prepare_kwargs)[source]#

(prepared layout, {ppg: positive-mutual matrix P = -C}, {ppg: seconds}, stack record, hash) under the corrected stack, solved on a substrate of eps_r and thickness_um.

Return type:

tuple

squadds.ml.capacitance.qc module#

Label and layout QC for planar capacitance data: one set of rules for contributions, dataset builds and training shards.

Every check reports instead of raising; QCReport.ok is False when any check failed (an error). The rules are those of the dataset (PLAN_DATASET_HF.md §4.2):

  • reject: matrix not square over net_order, missing / duplicate / misplaced net names, non-finite entries, asymmetry (rel > 1e-3; Q3D exports are exactly symmetric, other solvers such as Palace are not; > 1e-6 warns, the matrix is then symmetrized), diagonal <= 0, off-diagonal >= 0 (a zero only when flagged), signal block not positive definite, a conductor count from the GDS that differs from the matrix size (nets are never merged), unreadable GDS, a duplicate of a held-out test design (it would leak the test label);

  • warn: signal-row closure |sum_j C_ij| / C_ii > 5 %, not converged, non-monotone pass history, unusual stack, duplicates of non-test designs, label entries far from optimized_physics_prior (physics sanity; never a rejection).

Only numpy is imported at module level; gdstk / shapely are imported by the GDS checks, the physics prior by prior_sanity (needs pip install 'squadds[ml]').

class squadds.ml.capacitance.qc.QCReport(subject='', errors=<factory>, warnings=<factory>, fixes=<factory>, info=<factory>, children=<factory>)[source]#

Bases: object

Result of a QC run: ok (no error), errors, warnings, fixes (applied automatically) and the measured values in info. to_markdown() renders it for a validation report.

all_errors()[source]#
Return type:

list[str]

all_warnings()[source]#
Return type:

list[str]

children: list#
error(msg)[source]#
errors: list[str]#
extend(other, prefix='')[source]#

Fold another report’s errors / warnings / fixes / info into this one (messages prefixed).

Return type:

QCReport

fixes: list[str]#
info: dict#
property ok: bool#
subject: str = ''#
to_dict()[source]#
Return type:

dict

to_markdown(title=None)[source]#
Return type:

str

warn(msg)[source]#
warnings: list[str]#
squadds.ml.capacitance.qc.conductor_count_qc(n_layout, net_order, subject='')[source]#

The matrix must cover every conductor of the layout: N from the GDS (ground included) == len(net_order).

Return type:

QCReport

squadds.ml.capacitance.qc.duplicate_qc(hashes, reference=None, subject='duplicates')[source]#

hashes: {design: geom_hash} of a batch; reference: a DataFrame with design_id, geom_hash, split (the dataset), or None (only duplicates inside the batch are checked; warned). A duplicate of a test design is an error.

Return type:

QCReport

squadds.ml.capacitance.qc.gds_qc(path, layer_map=None, nets=None, subject='')[source]#

GDS readback: readable by gdstk, one top cell, unit 1 um or 1 nm, declared layers present, every polygon valid, and the conductor count (info["n_conductors"], ground included) inferred from the layout.

Conductors: the connected bodies of the conductor-layer polygons (touching polygons are one metal body, hence one net), in file order, unless nets = {net name: [conductor-layer polygon indices in file order]} assigns polygons explicitly. Bodies touching the ground metal are at ground potential (warned). info["geom_hash"] is the dataset duplicate key.

Return type:

QCReport

squadds.ml.capacitance.qc.geom_hash(path)[source]#

"sha256:<hex>" of the canonical polygon multiset of a GDS (layer, datatype, vertices rounded to 1 nm, sorted): the dataset’s duplicate key, identical to the geom_hash column of SQuADDS/SQuADDS_PlanarCapacitance.

Return type:

str

squadds.ml.capacitance.qc.label_qc(C, names, net_order=None, unit='fF', passes=None, convergence=None, flagged_zero=(), sym_rtol=0.001, closure_warn=0.05, subject='')[source]#

QC of one Maxwell matrix C (names = its row order; any unit, converted to fF).

net_order: the declared net order (G first); the matrix must be square over exactly these names. passes: optional [(pass index, matrix in the same names / unit)], the last complete pass must equal C. convergence: optional {"delta_pct_final", "delta_target_pct", "passes_completed"}. flagged_zero: pairs (a, b) whose exact zero is explained (e.g. a lattice entry below the solver floor). info["matrix_fF"] holds the matrix in net_order.

Return type:

QCReport

squadds.ml.capacitance.qc.prior_sanity(C_fF, net_order, gds, layer_map=None, band=(0.5, 2.0), floor_fF=0.1, threads=2, prior=None, subject='physics sanity')[source]#

Ratio of each label entry to optimized_physics_prior of the layout (report only, never an error).

The label’s conductors (net_order[1:]) are matched to the layout’s in GDS file order. Entries with |C| >= floor_fF whose ratio falls outside band are warned. prior: a precomputed PriorResult (else computed here, needs [ml]).

Return type:

QCReport

squadds.ml.capacitance.qc.read_cap_matrix(path)[source]#

Q3D cap_matrix.csv (one row per adaptive pass; C(a,b) [unit] columns in any unit, also the *1e15 header) -> {"names" (G first, then first appearance), "passes" [(pass index, N x N fF)], "units", "freq_GHz"}. Incomplete rows (pre-allocated passes) are kept as NaN matrices and skipped by the QC.

Return type:

dict

squadds.ml.capacitance.qc.read_conv(path)[source]#

Q3D .conv convergence file -> pass history, passes completed, delta target and final delta (%).

Return type:

dict

squadds.ml.capacitance.qc.reference_hashes(db=None, local_dir=None, revision=None)[source]#

design_id / geom_hash / split of every design of the dataset (PlanarCapacitanceDB; HF or a local copy).

squadds.ml.capacitance.qc.stack_qc(stack, freq_GHz=None, subject='stack')[source]#

eps_r in [1, 30], substrate in [5, 2000] um, frequency in [0.1, 50] GHz; a stack other than the training stack (Si 11.45, 350 um) is accepted and recorded (warned: the released models are served for the training stack).

Return type:

QCReport

squadds.ml.capacitance.qc.to_fF(values, unit)[source]#

Values in unit (F, nF, pF, fF, aF; "pF*1e15" = the exp12 re-export header C(a,b)*1e15 [pF], whose values are pF x 1e15) converted to fF.

Return type:

ndarray

squadds.ml.capacitance.qc.unit_plausibility(C_fF, declared)[source]#

A warning when a matrix in fF looks like it was given in another unit (entries of ~1e-15 or ~1e3 x the usual size).

Return type:

str | None

squadds.ml.capacitance.result module#

Prediction result: the full Maxwell capacitance matrix (fF, ground first) with checks, timing and provenance.

class squadds.ml.capacitance.result.CapacitanceResult(names: 'list[str]', matrix_fF: 'np.ndarray', model: 'str', title: 'str' = '', prior_version: 'str | None' = None, prior_stack: 'dict | None' = None, weights_sha256: 'list[str]' = <factory>, learned_prior_sha256: 'str | None' = None, timing_s: 'dict' = <factory>, threads: 'int' = 2, machine: 'str' = '', checks: 'dict' = <factory>, warnings: 'list[str]' = <factory>, substrate: 'dict' = <factory>, ground_detection: 'dict | None' = None, source: 'str' = '', layout_hash: 'str' = '', cached: 'bool' = False, package: 'str' = '', units: 'str' = 'fF', convention: 'str' = 'Maxwell matrix: diagonal = self, off-diagonal = -mutual (negative); row/column 0 = ground (G)')[source]#

Bases: object

cached: bool = False#
checks: dict#
convention: str = 'Maxwell matrix: diagonal = self, off-diagonal = -mutual (negative); row/column 0 = ground (G)'#
ground_detection: dict | None = None#
layout_hash: str = ''#
learned_prior_sha256: str | None = None#
machine: str = ''#
matrix_fF: ndarray#
model: str#
property n_conductors: int#
names: list[str]#
package: str = ''#
prior_stack: dict | None = None#
prior_version: str | None = None#
source: str = ''#
substrate: dict#
threads: int = 2#
timing_s: dict#
title: str = ''#
to_dataframe()[source]#
to_dict()[source]#
Return type:

dict

to_sim_results(names=None)[source]#

The SQuADDS_DB sim_results shape: pairwise positive magnitudes <a>_to_<b> (self terms on the diagonal, ground named ground), the signed maxwell_matrix as C_<a>_<b> (ground G) and units. names renames conductors (e.g. {"C1": "north", "C2": "south"}).

Return type:

dict

units: str = 'fF'#
warnings: list[str]#
weights_sha256: list[str]#
squadds.ml.capacitance.result.physical_checks(C)[source]#

Symmetry, Maxwell signs, closure (row sums of the signal rows >= 0) and positive definiteness of the signal block.

Return type:

dict

squadds.ml.capacitance.result.physical_warning(chk)[source]#

Readable warning when a check of physical_checks fails (None when the matrix passes).

Return type:

str | None

squadds.ml.capacitance.serving module#

Serving adapter of the planar capacitance models for the SQuADDS ML API (registry family planar_capacitance).

The API Space imports squadds.ml.capacitance.serving:Adapter by its dotted path; nothing else imports this module. root is a verified local copy of the model repository (the repository layout, e.g. <root>/qcap/acc_v2m_sf_s0.pt).

class squadds.ml.capacitance.serving.Adapter(model_id, root, config, limits)[source]#

Bases: object

InputModel#

alias of CapacitanceInputs

describe()[source]#
Return type:

dict

input_kind = 'file'#
predict(inputs, file=None, options=None)[source]#
Return type:

dict

warm(example)[source]#
class squadds.ml.capacitance.serving.CapacitanceInputs(*, ground_layer='1/0', conductor_layer='1/10', eps_r=11.45, thickness_um=350.0, ground_pieces='', file_base64=None)[source]#

Bases: BaseModel

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

conductor_layer: str#
eps_r: float#
file_base64: str | None#
ground_layer: str#
ground_pieces: str#
model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

thickness_um: float#
exception squadds.ml.capacitance.serving.TooLarge[source]#

Bases: ValueError

too_large = True#

squadds.ml.capacitance.slurm module#

A generic SLURM array script for retraining (one seed per array task). No site-specific accounts, partitions or tooling: pass your own, or leave them out and let your cluster’s defaults apply.

squadds.ml.capacitance.slurm.write_slurm_array(out_path, shard_dir, seeds=(0, 1, 2), out_dir=None, partition=None, account=None, cpus=2, time='01:00:00', mem='6G', python='/home/runner/work/SQuADDS/SQuADDS/.venv/bin/python', arm='full_gnn', steps=18000, device='cpu', gpus=0, job_name='squadds-ml-train', extra_sbatch=(), setup='')[source]#

Write out_path: sbatch out_path trains seeds (array task k -> seeds[k]) on shard_dir into out_dir/s<seed> with cpus threads each. setup: shell lines run before training (e.g. module load ..., source venv/bin/activate). Returns the path.

Return type:

Path

squadds.ml.capacitance.train module#

Retraining the planar-capacitance networks on your own compute (laptop CPU, GPU box or cluster).

  • fit: the paper recipe (P2d full_gnn) on a shard dir, one seed. Every hyperparameter is in TrainConfig.

  • fit_seeds: several seeds, in parallel processes (or SLURM array tasks: squadds.ml.capacitance.slurm).

  • fit_in_family: from scratch on k of your designs, cross-validated against the zero-shot released model; zero-shot is always a candidate and wins ties.

  • retrain_collective: your designs added to the all-data training set, 3 seeds (the QCap recipe).

  • trained_model: a trained run (or several seeds) as a CapacitanceModel for CapacitancePredictor.

The fit loop is the tl-squadds reference (scripts/geomfast/ragged.py fit + QCap’s NaN-label masking, scripts/flagship_v4/ragged_fv4.py) statement for statement. The released fits ran in RELEASE_ENVIRONMENT (Linux aarch64 on the GH200 node, CPU, 2 threads, its torch and numpy); a run is expected to reproduce them bit for bit only in that environment. Other machines, thread counts, devices or library versions drift slightly (gate iii: numpy alone moves the trajectory). The checkpoint records environment, release_environment_match and the differences (release_environment_diff); bit_identical_to_release is kept as an alias of release_environment_match. On CPU with threads > 1 the training step sums some terms in an order that depends on thread timing, so on a busy machine two runs of the same seed can differ in the last bits and then drift apart. threads=1 (or torch.use_deterministic_algorithms(True)) gives the same weights on every run on one machine.

class squadds.ml.capacitance.train.InFamilyResult(chosen: 'str', model: 'object', report: 'object', decision: 'dict', out_dir: 'str', timing: 'dict' = <factory>)[source]#

Bases: object

chosen: str#
decision: dict#
model: object#
out_dir: str#
report: object#
timing: dict#
class squadds.ml.capacitance.train.TrainConfig(steps=18000, lr=0.001, weight_decay=0.0001, lr_min=1e-05, grad_clip=5.0, huber_delta=0.05, w_signal_self=0.1, w_ground_self=0.02, max_batch=64, pair_budget=8192, width=64, standardise_clip=10.0, log_every=500)[source]#

Bases: object

The paper recipe (paper_v4 Sec. 2.3-2.4). Defaults = the released models; change them knowingly.

grad_clip: float = 5.0#
huber_delta: float = 0.05#
log_every: int = 500#
lr: float = 0.001#
lr_min: float = 1e-05#
max_batch: int = 64#
pair_budget: int = 8192#
standardise_clip: float = 10.0#
steps: int = 18000#
w_ground_self: float = 0.02#
w_signal_self: float = 0.1#
weight_decay: float = 0.0001#
width: int = 64#
squadds.ml.capacitance.train.add_train_subcommand(sub)[source]#

Register squadds-ml train on an argparse subparsers object (for cli.py).

squadds.ml.capacitance.train.cmd_train(a)[source]#
Return type:

int

squadds.ml.capacitance.train.fit(shard_dir, out_dir, arm='full_gnn', seed=0, config=TrainConfig(steps=18000, lr=0.001, weight_decay=0.0001, lr_min=1e-05, grad_clip=5.0, huber_delta=0.05, w_signal_self=0.1, w_ground_self=0.02, max_batch=64, pair_budget=8192, width=64, standardise_clip=10.0, log_every=500), device='cpu', threads=2, validate=True, verbose=True)[source]#

Train one network from scratch on the split == "train" rows of a shard dir; writes out_dir/model.pt (loadable by trained_model / CapacitancePredictor), run.json and, with validate, metrics.csv / val_score.json on the val rows. Returns the run record.

Return type:

dict

squadds.ml.capacitance.train.fit_in_family(designs, out_dir, k_folds=5, base='QCap', seed=0, config=TrainConfig(steps=18000, lr=0.001, weight_decay=0.0001, lr_min=1e-05, grad_clip=5.0, huber_delta=0.05, w_signal_self=0.1, w_ground_self=0.02, max_batch=64, pair_budget=8192, width=64, standardise_clip=10.0, log_every=500), device='cpu', threads=2, processes=1, final_seeds=(0,), margin_pp=0.25, margin_fF=0.05, n_boot=2000, family='user', build_kwargs=None)[source]#

From-scratch training on your k designs, cross-validated against the zero-shot base model.

designs: Design objects / dicts (built here with build_shards) or an existing shard dir (every row used). k-fold CV (deterministic folds from seed): each fold is predicted by a network trained from scratch on the other folds, and by the zero-shot base on the same stored embedding and priors. The from-scratch recipe is chosen only if it is materially better (paired layout-bootstrap 95% interval of the layout-mean difference excludes zero AND the gain exceeds margin_pp percentage points of median error or margin_fF of MAE: the paper’s equivalence rule); otherwise the zero-shot model is kept (it wins ties). The chosen from-scratch model is then trained on all k designs (final_seeds). Reported per entry kind: layout-mean median %, MAE and RMSE (fF), with time, machine and threads.

Return type:

InFamilyResult

squadds.ml.capacitance.train.fit_seeds(shard_dir, out_dir, seeds=(0, 1, 2), processes=1, arm='full_gnn', config=TrainConfig(steps=18000, lr=0.001, weight_decay=0.0001, lr_min=1e-05, grad_clip=5.0, huber_delta=0.05, w_signal_self=0.1, w_ground_self=0.02, max_batch=64, pair_budget=8192, width=64, standardise_clip=10.0, log_every=500), device='cpu', threads=2, validate=True, verbose=False)[source]#

fit for each seed into out_dir/s<seed>; processes seeds at a time (spawned processes, threads each).

Return type:

list[dict]

squadds.ml.capacitance.train.main(argv=None)[source]#
Return type:

int

squadds.ml.capacitance.train.release_eligible(device, threads, config, env=None)[source]#

True when the run matches the released fits’ environment (RELEASE_ENVIRONMENT) and the default recipe: the only setting in which a bit-for-bit reproduction of the released checkpoints is expected.

Return type:

bool

squadds.ml.capacitance.train.release_environment_diff(device, threads, config, env=None)[source]#

What differs from the released fits’ environment and recipe (empty = same environment).

Return type:

list[str]

squadds.ml.capacitance.train.retrain_collective(user_shards, base_shards, out_dir, seeds=(0, 1, 2), processes=1, config=TrainConfig(steps=18000, lr=0.001, weight_decay=0.0001, lr_min=1e-05, grad_clip=5.0, huber_delta=0.05, w_signal_self=0.1, w_ground_self=0.02, max_batch=64, pair_budget=8192, width=64, standardise_clip=10.0, log_every=500), device='cpu', threads=2)[source]#

Your shards added to the all-data training set (base_shards: the QCap shard dir, i.e. the dataset’s model_input on the corrected prior), every row trained on, seeds networks from scratch (QCap recipe). Returns (CapacitanceModel of the ensemble, run records).

squadds.ml.capacitance.train.trained_model(runs, name='user', title=None)[source]#

A CapacitanceModel (ensemble mean over the given runs) for CapacitancePredictor: run dirs or model.pt paths. Prior-based arms run on the corrected prior stack (the one the released models serve); the embedding is exact.

squadds.ml.capacitance.train.training_environment(device, threads)[source]#
Return type:

dict

squadds.ml.capacitance.training_data module#

Training data of the planar-capacitance networks: the P2d shard layout, label reading and QC, and shard builders.

A shard directory holds one n0NN.npz per conductor count N (ground included) and schema.json. Arrays per file (L layouts, P = N(N-1)/2 pairs i < j):

key (L,) str split (L,) str family (L,) str X (L, N, 61) f32 node vector (60 features + missing_log_min_halfwidth), node 0 = ground G E (L, P, 42) f32 pair vector G (L, 4) f32 global vector C (L, N, N) f32 Maxwell matrix in fF, ground first (NaN = unknown entry, masked in training) sig (L, N) bool signal mask pri (L, P, 2) f32 positive prior mutuals (fF) at 1.5 and 3 panels per gap pairs (P, 2) int

build_shards turns layouts (GDS) and their labels (a Maxwell matrix with net names, or a Q3D cap_matrix.csv) into shards with the same embedding and the optimized_physics_prior solves the released models read. Net names are matched by name and never merged; every label passes QC (symmetry, signs, closure, positive definiteness) or is refused.

class squadds.ml.capacitance.training_data.Design(gds, labels=None, label_names=None, key=None, family='user', split='train', names='auto', ground_layers=((1, 0), ), conductor_layers=((1, 10), ), meta=<factory>)[source]#

Bases: object

One layout and its label.

gds: GDS path. labels: a cap_matrix.csv path (last complete pass), or a Maxwell matrix in fF with label_names (any net order; ground G), or None (inference-only rows are not allowed in training shards). names: how the layout’s conductors are named, matched to the label names: "auto" (port-stub layouts, i.e. a (2, 0) marker: N / S fixed by the stubs and the pads named by the sibling design JSON’s Q3D polygon map, the angle-slot or the file-order convention, whichever matches the label (resolve_dataset_names); else C1..Cn in file order), "dataset" (angle slots P<k>), "dataset_file_order" (N, S, P1, … in file order), "design_json", "file_order" (C1..Cn), or an explicit list of signal names in file order.

conductor_layers: tuple = ((1, 10),)#
family: str = 'user'#
gds: str#
ground_layers: tuple = ((1, 0),)#
key: str | None = None#
label_names: list | None = None#
labels: object = None#
meta: dict#
names: object = 'auto'#
resolved_key()[source]#
Return type:

str

split: str = 'train'#
exception squadds.ml.capacitance.training_data.LabelQCError[source]#

Bases: ValueError

A label matrix failed QC (symmetry, Maxwell signs, closure, positive definiteness, net names).

squadds.ml.capacitance.training_data.as_design(x)[source]#
Return type:

Design

squadds.ml.capacitance.training_data.base_schema()[source]#

Feature names and order of the networks’ input (nodekeys 61, edgekeys 42, globkeys 4) and the prior’s physics.

Return type:

dict

squadds.ml.capacitance.training_data.build_shards(designs, out_dir, prior='optimized', threads=2, workers=1, on_error='raise')[source]#

User designs -> a P2d shard dir (n0NN.npz + schema.json + names.json + build.json).

designs: Design objects or dicts of their fields. Labels are QC-checked and matched to the layout nets by name; a design that fails is refused (on_error="raise", default) or skipped and listed in build.json ("skip"). Priors are computed on this machine (macOS is not bit-identical to the released x86 priors: ~2.4e-3 relative at most); threads per design, workers designs at a time (spawned processes).

Return type:

dict

squadds.ml.capacitance.training_data.design_json_names(gds)[source]#

Signal net names in GDS file order from the design’s sibling <stem>.json (the Q3D polygon map ansys_gds.q3d_signal.mapping_polygons + nets), or None when there is no such map.

Return type:

list[str] | None

squadds.ml.capacitance.training_data.embed_design(d, threads=2, prior='optimized', schema=None)[source]#

Shard row of one design: embedding (exact, no far-sample decimation), prior solves at 1.5 and 3 panels per gap under the corrected stack, and the QC-checked label reordered to the scene’s net order (G first).

Return type:

dict

squadds.ml.capacitance.training_data.label_qc(C, names, sym_rtol=None, sign_atol=1e-06, closure_rtol=0.0001)[source]#

Label QC of a Maxwell matrix (fF, names G first). Returns the checks; raises LabelQCError on any failure.

Return type:

dict

squadds.ml.capacitance.training_data.labels_of(d)[source]#
Return type:

tuple[list[str], ndarray, dict]

squadds.ml.capacitance.training_data.merge_shards(base_dir, user_dir, out_dir, user_split=None, all_split=None, allow_prior_mismatch=False)[source]#

Base shards + user shards -> one shard dir for collective retraining. Feature schemas and the prior version must agree (a user prior computed under another stack is refused); duplicate keys are refused. Base arrays the user rows lack (e.g. QCap’s origin / group) are filled with user / the row’s family. user_split overrides the user rows’ split, all_split every row’s ("train" for collective training).

Return type:

Path

squadds.ml.capacitance.training_data.pairs_of(n)[source]#
Return type:

ndarray

squadds.ml.capacitance.training_data.read_names(shard_dir)[source]#

{key: net names (G first)} of a shard dir built here (names.json); {} for shards without it.

Return type:

dict

squadds.ml.capacitance.training_data.read_q3d_csv(path)[source]#

Q3D cap_matrix.csv (one row per adaptive pass, columns C(a,b) [unit], also the C(a,b)*1e15 [pF] re-export) -> (net names, Maxwell matrix in fF of the last complete pass, info). Names: G first, then the file’s order of first appearance.

Return type:

tuple[list[str], ndarray, dict]

squadds.ml.capacitance.training_data.read_schema(shard_dir)[source]#
Return type:

dict

squadds.ml.capacitance.training_data.read_shards(shard_dir)[source]#

Every shard file as a dict of arrays (sorted by N), plus n and file.

Return type:

list[dict]

squadds.ml.capacitance.training_data.resolve_dataset_names(signals, markers, label_names, json_names=None)[source]#

Signal names of a port-stub layout (dataset convention) that match the label nets, and which naming gave them.

N and S are fixed geometrically (N = body at the north stub (2, 0), S = body at the south stub (3, 0) or the origin). Candidates, each kept only if its names are unique, equal the label’s signal nets and put N and S on those bodies: design_json (the Q3D polygon map of the sibling design JSON: exp13-15, quantum-metal exports), dataset (pads P<k> by angle slot: the multi-pad star, exp12) and dataset_file_order (N, S, P1, P2, … in file order). The design JSON wins when valid; otherwise one valid candidate (or two that agree) is used, and anything else is refused.

Return type:

tuple[list[str], str]

squadds.ml.capacitance.training_data.scene_of(d, label_names=None)[source]#

(Scene, naming used) for a design: the training geometry (no crop), ground = net 0. label_names lets names="auto" pick the dataset naming that matches the label (see resolve_dataset_names).

squadds.ml.capacitance.training_data.sha256_file(p)[source]#
Return type:

str

squadds.ml.capacitance.training_data.shard_files(shard_dir)[source]#
Return type:

list[Path]

squadds.ml.capacitance.training_data.shard_summary(shard_dir)[source]#

Layout counts per split and family, conductor-count range and the prior version of a shard dir.

Return type:

dict

squadds.ml.capacitance.training_data.shards_from_model_input(model_input, labels, out_dir, splits=('train', 'val'))[source]#

HOOK: the dataset’s model_input table (squadds.datasets.planar_capacitance_schema, one row per layout: flat X / E / G / pri / sig with net_order) and its labels table (long format, a_idx <= b_idx) -> a shard dir. Both arguments: pandas DataFrames or parquet paths. Test rows are never read (splits may not contain test).

Return type:

Path

squadds.ml.capacitance.training_data.subset_shards(src, out_dir, train_keys=None, val_keys=None, keep=None)[source]#

Copy of a shard dir restricted to train_keys (split set to train) and val_keys (split set to val), or to rows for which keep(shard_dict) -> bool mask is True (splits unchanged).

Return type:

Path

squadds.ml.capacitance.training_data.write_shards(rows, out_dir, schema, extra=None)[source]#

Write per-layout rows (keys of ARRAYS minus pairs, plus names) as a shard dir; refuses duplicate keys.

Return type:

Path

Module contents#

Planar capacitance models: GDS layout -> full N x N Maxwell capacitance matrix (fF, ground first).

from squadds.ml.capacitance import CapacitancePredictor, load_model res = CapacitancePredictor(load_model(“QCap”)).predict(“chip.gds”) res.names, res.matrix_fF, res.to_sim_results()

Models: QCap (the default) and QCap-Fast, both trained on all data. Physics priors: physics_prior and optimized_physics_prior.