Pipeline Stages¶
ORCA runs a linear pipeline. Each stage receives a context dictionary and adds its outputs for the next stage.
flowchart TB
A[GDSGenerator] -- GDS files --> X["DRCChecker<br/>(grid snap + SG13G2 rules + port contact)"]
X -- clean layouts --> B["GDSConverter<br/>(gds2palace mesh)"]
B -- mesh files --> C["PalaceSimulator<br/>(full-wave EM)"]
C -- "Touchstone .sNp" --> D["ModelTrainer<br/>(PyTorch MLP)"]
D -- trained model --> E[OnnxExporter]
E -- ".onnx (→ COBRA)" --> F[ModelTester]
The sample-producing stages (GDSGenerator, GDSConverter, PalaceSimulator) record every finished sample in their parameter table right away and keep the results of earlier runs, so an interrupted run continues where it stopped when started again. Each of them takes overwrite=True to delete its earlier results instead; see Resuming an interrupted run.
Stage 1 — GDS generation (GDSGenerator)¶
The geometry class's input_parameter_iterator samples parameter combinations — by default with a scrambled Sobol' sequence, a space-filling design that covers the parameter box more evenly than random draws, with a small share of the draws moved onto the faces, edges and corners of the box — drawing each parameter from its declared distribution: uniform, or log-uniform to put more samples at the small end of its range (see Custom Classes). For each combination, create_gds_file() is called to produce a GDS layout file. The number of samples is set by num_samples; the run seed (ORCA.run(seed=...)) makes the draws reproducible. Every draw is first passed to the geometry's is_feasible(); combinations it rejects (a winding that does not fit its diameter, a feed gap wider than the octagon's side) are counted and replaced by further draws (with all but the grid strategies), so num_samples buildable layouts come out; parameters the iterator lists in kept_on_rejection keep their value while the others are redrawn around it, so a rejection cannot skew their distribution. A geometry that still raises ValueError in create_gds_file() costs a sample, and the stage warns when it delivered fewer layouts than requested. At the end the stage plots the coverage to geometries/<name>_coverage.png (plot_coverage=False turns it off): a pair plot of every two parameters with the layouts over the rejected draws, which tells gaps in the sampling apart from regions that cannot be built, and a histogram of each parameter. Layouts listed in the table of an earlier run are kept and only the missing indices are laid out; whenever new layouts are added, the DRC tables of the previous set are deleted so the DRC stage has to check them again.
Stage 2 — Design-rule check (DRCChecker)¶
Every generated layout is snapped to the manufacturing grid and checked against the IHP SG13G2 back-end design rules with KLayout: vertices off the grid, edge angles other than 0/45/90° (0/90° on vias), acute corners, minimum metal width and spacing (M1, M2–M5, TM1, TM2), and via size, spacing and metal enclosure (V1–V4, TV1, TV2). The rule values and names are those of the PDK's own KLayout deck, so a finding such as TV2.d can be looked up in the SG13G2 design rule manual; the rule table lives in orca.geometry.drc.
Off-grid vertices are repaired rather than reported: snap_to_grid=True (the default) moves every vertex onto the grid_nm grid (5 nm for SG13G2) and writes the GDS file back, so geometry code does not need its own snapping. Layouts with remaining violations are left out of the parameter table the later stages use (drop_violations=True); the stage writes <name>_drc_report.csv with the per-layout counts and <name>_drc.csv with the layouts that passed, both next to the GDS files, and logs a summary. This is where parameter combinations that draw unbuildable geometry — a winding folded over itself, a via clipped by a miter — are stopped before they cost simulation time or teach the model shapes that cannot be fabricated.
The stage also checks every layout against its ports (check_ports=True, the default) — the .simcfg's, or the sample's own if the geometry overrides simulation_ports(params): each port's marker — the shape on its source_layernum — has to overlap or touch the metals the port connects (from_layername and to_layername, or target_layername for an in-plane port, with GDS numbers from the stackup XML). gds2palace places a port wherever its marker is drawn and does not check that it meets a conductor, so a marker a few nanometres off its feed line still meshes and simulates, as an open circuit: the S-parameters then describe a different circuit than the parameter table says, and nothing fails. The report lists such layouts as port<N>.missing or port<N>.open_<layer>, and they are left out of the parameter table even with drop_violations=False.
Stage 3 — GDS conversion (GDSConverter)¶
Each GDS file — those that passed DRC when the stage ran, otherwise all of them — is converted to a Palace-ready simulation setup using gds2palace. The geometry's stackup_xml defines the physical layer stackup and material properties; the simconfig_filename defines the simulation parameters (ports, frequency sweep, mesh settings). Each sample gets the ports of the geometry's simulation_ports(params), by default the simconfig's; InductorOcta uses this to land a single turn's ports on TopMetal2, where its feeds are.
Conversions run in parallel worker processes, one sample per task. A sample whose geometry gds2palace/gmsh cannot mesh (e.g. PLC Error: A segment and a facet intersect) is logged and skipped. gmsh can also loop forever on degenerate geometry, so each conversion has a time limit — GDSConverter(timeout=180) seconds by default, which leaves room for fine meshes (a large inductor at refined_cellsize 2 µm takes up to about 50 s) — after which its worker is killed and the sample is skipped as well, instead of stalling the whole pipeline. Models converted by an earlier run for the same parameters are reused.
Every new mesh is also checked for flat or inverted tetrahedra. gmsh occasionally produces such zero-volume elements where thin layers meet in one plane — a 0.85 µm port sheet flush with the ground ring's outer edge, as in both presets, at a coarse refined_cellsize — and Palace cannot solve such a mesh (HasPositiveFiniteDiagonal(...) is false). Rarely (about 1 in 300 small layouts with the passi3D stackup), gmsh also writes a corrupt mesh whose elements reference a node that does not exist; it cannot be read back and counts as quality −∞. A sample whose worst element quality (gmsh's minSICN: 1 for a regular tetrahedron, 0 for a flat one) is at or below min_element_quality (default 1e-6) is left out of the Palace table, and the stage warns that the simcfg's refined_cellsize may be too coarse. Meshes below warn_element_quality (default 1e-4) are kept but listed in a warning; meshes Palace has solved had a worst quality of 6·10⁻⁴ and above. The worst quality of every mesh is written to palace_sims/<name>_mesh_report.csv.
Stage 4 — EM simulation (PalaceSimulator)¶
Palace runs a full-wave finite-element EM simulation for each layout variant and writes the S-parameters to a Touchstone file (.sNp). Simulations are distributed across available CPU cores. The palace_executable argument can point to a local binary or a container invocation (e.g. apptainer exec palace.sif palace).
Several simulations can run at once, each already parallelized internally with MPI (num_processes ranks per simulation). bind chooses what one simulation gets — a whole "node", one "socket" or one "numa" domain — and num_parallel_sims=0 uses all such slots:
PalaceSimulator(num_parallel_sims=0, bind="numa")runs one simulation per NUMA domain of the current machine, each pinned withnumactl(e.g. 2 or 4 at once on a multi-socket workstation).PalaceSimulator(launcher="slurm", num_parallel_sims=0, bind="numa")does the same on every node of a Slurm allocation (sbatch --nodes=N), each simulation launched as ansrunjob step pinned to its node and cores. See examples/slurm_runs for job scripts that run GDS generation, DRC and conversion on one node and then the simulations on many.
Palace is memory-bandwidth bound, so several smaller simulations confined to their own NUMA domain usually give a higher throughput than one simulation spread over a whole node — as long as one simulation fits into a domain's memory (use bind="socket" otherwise). The layout is derived from the machine or allocation at runtime, so num_parallel_sims and num_processes are capped to what is actually available. Pass save_log=True to keep each simulation's full Palace output in palace.log in its simulation folder (off by default, Palace prints a lot); failures are reported either way. A launch the scheduler refuses (srun's "Unable to create step", which comes and goes) is retried in the same slot after 10, 30, 90 and 300 s before the simulation counts as failed; a failed simulation is left out of the results and retried by the next run.
Each simulation that finishes adds its row to results/<name>.csv immediately, so a job killed by its time limit still leaves a table describing every Touchstone file it produced; at the end of the stage the table is put back into the order of the Palace table. A simulation that fails, raises, or does not produce the requested Touchstone file is logged and left out, and the others go on. Started again, the stage skips every model already listed with the same parameters and simulates the rest.
Stage 5 — Model training (ModelTrainer)¶
A PyTorch MLP is trained on the simulation data. Inputs are geometry parameters and frequency; outputs are the real and imaginary parts of each S-parameter entry. Normalization is defined in the geometry's dataset and applied automatically. An optional basis expansion of the inputs — for example a Chebyshev expansion of frequency — is chosen on the stage itself with ModelTrainer(basis="chebyshev"); it lives inside the model, so it is tuned with it and exported into the ONNX graph. Hyperparameters such as learning rate, batch size, and network depth can be passed to ModelTrainer.
The result table is split by geometry, never by frequency point: test_frac of the geometries are held out for ModelTester, and val_frac of the rest select the best checkpoint during training. The split is recorded in models/<name>_split.csv. Without hyperparameters, Optuna tunes them with n_fold_cv-fold cross-validation over the geometries, so every fold is scored on layouts the model has not seen (n_trials trials, or until tuning_timeout seconds have passed). n_fold_cv=1 skips the cross-validation and scores each trial on the val_frac split of the final training instead: one training per trial rather than n_fold_cv, which is usually enough once there are a few thousand geometries; with a few hundred, the average over folds ranks trials more reliably. The number of epochs is not tuned: each fold runs up to tuning_max_epochs with early stopping, the final model up to max_epochs, and a trial that falls behind the others at the same fold and epoch is pruned after any epoch. The batch sizes searched are batch_sizes (32 to 512 if not given); for a per-point dataset with millions of samples, larger ones such as [1024, 2048, 4096] train much faster. A trial that diverges or runs out of memory is pruned; any other error stops the stage. Every training, in tuning and in the final run, starts with a linear learning-rate warmup over warmup_epochs (default 1) and then follows lr_schedule: "cosine" (default) decays the rate smoothly to 1% of its tuned value over the epoch limit, "plateau" halves it whenever the validation loss stalls. Gradients are clipped to a total norm of grad_clip_norm (default 1.0; None disables it), so one bad batch cannot undo the progress so far. With allow_tf32=True, tuning and the final training let matrix multiplies round their inputs to TF32 (10 instead of 23 mantissa bits) on GPUs with TF32 tensor cores (Ampere and newer). Testing and the exported ONNX model always run in full FP32. The MLP's width is searched on a log scale from 64 to 2048 and its depth from 2 to 8 layers, so small networks are tried as often as large ones. With regularization=True the weight decay and the model's own regularization (dropout for the MLP) are tuned too; otherwise AdamW's default weight decay and no dropout are used. Three optional loss settings judge the prediction as a circuit, not only as a vector of normalized S-parameters. They need a per-point dataset, as the presets have. admittance_weight adds the relative error of the admittance matrix Y, as a whole and of its real part: a small error in S can be a large error in L and Q, because at low frequency an inductor is almost a short between its ports. 0.1 to 1 puts it on the scale of the S-parameter loss. passivity_weight penalises predictions with a largest singular value of S above 1, or above the simulated one where that is larger (the DC point that dc_deembedded extrapolates is slightly non-passive). above_srf_weight weights the frequency points above each geometry's first self-resonance relative to those below it. The resonance is found in the simulated S-parameters as the frequency where the first inductive mode turns capacitive, which for the center-tapped inductor is its differential self-resonance. In the InductorOcta results (0 to 500 GHz) about 95% of the frequency points lie above it, so an above_srf_weight of 0.1 still leaves the points below with about a third of the loss. All three default to off, and they apply to tuning and the final training alike; validation losses are only comparable between runs with the same settings. The hyperparameters a run trained with are saved to models/<name>_hyperparameters.json, and hyperparameters accepts the path of such a file as well as a dict, so a later run can retrain with them without tuning again. Each Touchstone file is parsed once per run, for tuning and the final training together. The run seed (ORCA.run(seed=...)) fixes the splits, the tuner and the weight initialisation, so two runs with the same seed and data train the same model.
Stage 6 — ONNX export (OnnxExporter)¶
The trained PyTorch model is exported to ONNX format with a fixed frequency sweep as part of the model signature. The resulting .onnx file is self-contained and can be run with onnxruntime — no PyTorch installation required at inference time. Metadata keys describe the model to its consumer: input_parameter_ranges (the box each input was sampled from, with the step of integer inputs such as turns), input_constraints (the geometry's feasibility_constraints(), expressions that single out the buildable part of that box — the only part the model has seen), physics_guarantees (properties such as reciprocity the architecture enforces by construction), windings (the geometry's windings(), the ports of each winding, when it declares them), touchstone_type (the Palace result the model was trained on: normal, dc, deembedded or dc_deembedded, read from the training files' names), so an EM verification can compare against the same reference plane, and orca_version (the ORCA release that exported it, plus the git describe of its checkout when ORCA runs from one, e.g. 2.2.0 (git v2.2.0-1-gccf1103-dirty)).
Stage 7 — Model testing (ModelTester)¶
The trained model (or, if training did not run in this pipeline, the exported ONNX model) is evaluated against the held-out geometries listed in models/<name>_split.csv. Without that file, for example for a model tested against a fresh results folder, every row of the result table is used and a warning says so. Besides the mean absolute S-parameter error and the median relative error of each electrical parameter, the stage reports the spread: the median, 95th percentile and worst geometry, the error in each of n_frequency_bands frequency bands, and the 95th percentile of each electrical parameter's error. The errors of every test geometry, next to its parameters, are written to models/<name>_test_errors.csv, for example to plot the error against each parameter and find under-sampled regions. The error is also resolved over frequency: models/<name>_errors_vs_frequency.png shows, for the S-parameters and each electrical parameter, the median and the 25th–75th and 5th–95th percentiles over the test geometries at every frequency point, so you can see which frequency ranges the model gets right; the values are in models/<name>_errors_vs_frequency.csv. The electrical parameters are the geometry's own (electrical_parameters(), see Custom Classes), since only the geometry knows which port is which. InductorOcta reports its differential inductance L, resistance R, quality factor Q and self-resonance srf_f, with the center tap AC-grounded as in differential operation; TransformerOcta reports Lp, Ls, Rp, Rs, Qp, Qs, the coupling factor k and the primary's self-resonance, each winding driven differentially with both center taps AC-grounded. A geometry that declares none is tested on its S-parameters only. The coupling factor k is reported as an absolute error, since a relative one explodes for weakly coupled layouts; a geometry lists such parameters in absolute_error_parameters. Prediction errors are logged to help assess whether the surrogate is accurate enough for use in COBRA.
Simulating one sample outside the pipeline¶
simulate_geometry runs stages 1, 3 and 4 for a single parameter set and returns the resulting network, for example to check a surrogate prediction against Palace. COBRA's EM fine-tuning uses it.
from orca import simulate_geometry
from orca.geometry.presets import InductorOcta
params = {"turns": 2, "width": 6.0, "space": 3.0, "diameter": 150.0}
ntwk = simulate_geometry(InductorOcta(), params, "output/check", name="check",
palace_executable="palace", num_processes=8)
It applies the same rules as the pipeline: the sample must pass is_feasible, gets its own ports (simulation_ports(params)), is not simulated when its mesh is at or below min_element_quality, and runs with the same Palace config overrides. Meshing runs in a fresh process, so the function can be called from a GUI worker thread. It returns the most corrected Touchstone result (dc_deembedded if the sweep allows a DC point) and raises orca.SimulationError when any step fails. result_type asks for one variant instead, for example result_type="deembedded" to leave out the 0 Hz point that is added by extrapolation; when that variant was not written, the raw result is returned.