Quickstart¶
Once you have completed installation (see Getting Started -> Installation), you are ready to run ORCA.
1. Prepare Inputs¶
You need:
- A geometry class (
BaseGeometrysubclass) with parameter definitions. - A stackup XML file describing the physical layer stack.
- A Palace simulation configuration file (
.simcfg). - A Palace executable (local or via Apptainer container).
For an immediate starting point, use the built-in TransformerOcta geometry from examples/.
2. Run GUI Mode¶
In GUI mode:
- Select a geometry preset, or load a custom
.pyfile that defines aBaseGeometrysubclass. The name field sets the output folder (output/<name>/). - Tick the pipeline stages to run and set their parameters; an unticked stage collapses to its title. Every field has a tooltip taken from the stage's documentation; leave an optional field empty (or
None) to use the default. - Set the Palace executable path in the
PalaceSimulatorstage. - Optionally enter a Seed next to the run button: it fixes every random choice of the run (parameter draws, data splits, tuning, weight initialisation), so the same seed and inputs give the same samples and model. Leave it empty for an unseeded run.
- Click Run pipeline. Progress, the current stage, and the outcome show next to the progress bar (green when finished, red text on an error); the log panel mirrors what ORCA prints on the console. Validation problems, such as no geometry selected, appear inline instead of in a dialog. If the output directory already exists, the run continues from what is there (see Resuming an interrupted run); you are only asked to confirm when a stage has Overwrite enabled, because that stage deletes its earlier results.
The button in the top-right corner switches the appearance between system (follows the OS colour scheme), light (Sandbank) and dark (Deepwater). The choice is remembered across sessions.
3. Run Script Mode¶
For direct integration into scripts or custom workflows:
import orca
from orca import ORCA
from orca.geometry.examples.transformer.tf_octa_c_ports import TransformerOcta
geometry = TransformerOcta()
orca_instance = ORCA(
[
orca.GDSGenerator(num_samples=1000),
orca.DRCChecker(),
orca.GDSConverter(),
orca.PalaceSimulator(
palace_executable="apptainer exec ~/palace/palace.sif palace",
touchstone_type="dc_deembedded", # "all", "normal", "deembedded", "dc", "dc_deembedded"
),
orca.ModelTrainer(
# hyperparameters=None, # Dict or JSON path; if None, Optuna tunes automatically
# test_frac=0.15, # Fraction of geometries held out for testing
# val_frac=0.15, # Fraction of the rest used for validation
# n_train_samples=None, # Optional cap on training geometries
# n_fold_cv=5, # Cross-validation folds (by geometry) during tuning; 1 = val split
# n_trials=200, # Optuna trials
# tuning_timeout=None, # Stop tuning after this many seconds
# max_epochs=100, # Epoch limit of the final training
# tuning_max_epochs=30, # Epoch limit per cross-validation fold
# batch_sizes=None, # Batch sizes to tune over (None: 32-512)
# regularization=False, # Also tune weight decay and dropout
# lr_schedule="cosine", # Learning-rate decay after warmup: "cosine" or "plateau"
# warmup_epochs=1.0, # Linear learning-rate warmup at the start of training
# grad_clip_norm=1.0, # Gradient-norm clipping; None disables it
# allow_tf32=False, # TF32 matmuls while training (faster on A100 and newer)
# admittance_weight=0.0, # Loss on the relative Y-parameter error (tracks L and Q)
# passivity_weight=0.0, # Penalty on predicted S with a singular value above 1
# above_srf_weight=1.0, # Loss weight of frequencies above each self-resonance
),
orca.OnnxExporter(),
orca.ModelTester(),
]
)
if __name__ == "__main__":
# seed: one seed for the whole run - parameter draws, data splits, tuning, weights,
# and the global generators of Python, NumPy and PyTorch. None (default) is unseeded.
orca_instance.run(geometry=geometry, num_processes=16, seed=40)
Wrap the call in if __name__ == "__main__": (or a main() function) as shown: ORCA starts its worker processes with the spawn start method, which re-imports your script in every worker. Without the guard each worker would start its own pipeline.
This will:
- Generate 1000 parameterised GDS layout variants, spread over the parameter ranges with a space-filling design, and plot their coverage to
geometries/<name>_coverage.png. - Snap them to the manufacturing grid and drop those violating the SG13G2 design rules.
- Convert each to a Palace mesh and run full-wave EM simulation.
- Store results in Touchstone format under
output/<geometry_name>/. - Train a neural network on the simulation dataset.
- Export the trained model to ONNX format.
- Test prediction accuracy against held-out simulation data.
Tip
You can run only a subset of pipeline stages by modifying the list passed to ORCA(...). Stages are sorted by their internal index and some depend on outputs of earlier stages. Stage indices: GDSGenerator=0, DRCChecker=1, GDSConverter=2, PalaceSimulator=3, ModelTrainer=4, OnnxExporter=5, ModelTester=6.
Each run stores artifacts under output/<geometry_name>/:
Typical contents include:
- Touchstone
.sNpfiles per simulated sample. - PyTorch model checkpoint.
- Exported
.onnxsurrogate model. - Full run context JSON.
Tip
The exported .onnx file can be used directly with COBRA for circuit-level RFIC optimization.
Resuming an interrupted run¶
Running the same script again continues where the previous run stopped, for example after a Slurm job hit its time limit. GDSGenerator, GDSConverter and PalaceSimulator each add a row to their parameter table (geometries/<name>.csv, palace_sims/<name>.csv, results/<name>.csv) as soon as a sample is finished, so the tables always list exactly the finished samples, even when the run is killed. The next run keeps those samples and only produces the missing ones:
GDSGeneratorlays out only the sample indices missing from its table. With a fixed run seed (ORCA.run(seed=...)) they get the same parameters as in an uninterrupted run.GDSConverterandPalaceSimulatorreuse a sample only if their table lists it with the same parameters as their input table and its output (Palace config, Touchstone file) still exists. A sample that failed, was never finished, or was drawn anew with other parameters is converted or simulated again.
Rows that no longer fit (other parameters, a missing file, a line cut off by the kill) are dropped from the table, and the previous table is kept as <table>.csv.bak. Earlier results are never deleted unless you ask for it: pass overwrite=True to a stage (the Overwrite option in the GUI) to delete its folder and start that stage from scratch. Do this, or use a new output folder, after changing the geometry code, the stackup or the simconfig: the parameters of a sample would then be unchanged while its layout or simulation is not, which the resume check cannot see. A results folder passed as ORCA.run(result_dir=...) is never deleted; PalaceSimulator(overwrite=True) refuses to run on it.