Quickstart

Once you have completed installation (see Getting Started -> Installation), you are ready to run ORCA.

1. Prepare Inputs

You need:

• A geometry class (BaseGeometry subclass) 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

orca

In GUI mode:

1. Select a geometry preset, or load a custom .py file that defines a BaseGeometry subclass. The name field sets the output folder (output/<name>/).
2. Tick the pipeline stages to run and set their parameters. Every field has a tooltip taken from the stage's documentation; leave an optional field empty (or None) to use the default.
3. Set the Palace executable path in the PalaceSimulator stage.
4. 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 you are asked once before it is overwritten.

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.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,   # If None, Optuna tunes automatically
            # test_frac=0.15,         # Fraction of data held out for testing
            # n_train_samples=None,   # Optional cap on training samples
            # n_fold_cv=5,            # Cross-validation folds during tuning
        ),
        orca.OnnxExporter(),
        orca.ModelTester(),
    ]
)

if __name__ == "__main__":
    orca_instance.run(geometry=geometry, num_processes=16)

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:

1. Generate 1000 parameterised GDS layout variants.
2. Convert each to a Palace mesh and run full-wave EM simulation.
3. Store results in Touchstone format under output/<geometry_name>/.
4. Train a neural network on the simulation dataset.
5. Export the trained model to ONNX format.
6. 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, GDSConverter=1, PalaceSimulator=2, ModelTrainer=4, OnnxExporter=5, ModelTester=6.

4. Run at Scale with OpenStack

For large-scale simulation campaigns, we provide an OpenStack VM image and a REST API with corresponding client CLI. See the ORCA-OpenStack repository for details.

5. Inspect Results

Each run stores artifacts under output/<geometry_name>/:

output/<geometry_name>/
    context.json
    geometries/
    models/
    palace_sims/
    results/

Typical contents include:

• Touchstone .sNp files per simulated sample.
• PyTorch model checkpoint.
• Exported .onnx surrogate model.
• Full run context JSON.

Tip

The exported .onnx file can be used directly with COBRA for circuit-level RFIC optimization.