COBRA - A Circuit-Level Open-Source Based RFIC AI-Assisted Optimizer

©2026

Gianluca Simone*, David Lurz*, Martin Grund*, Fabian Schneider°, Michael Loose*, Sascha Breun*, Manuel Koch*, Robert Weigel*, Norman Franchi*

* Institute for Smart Electronics and Systems (LITES), Friedrich-Alexander-Universität (FAU), Erlangen-Nürnberg, Germany

° Chair of Integrated Electronic Systems, Otto-von-Guericke-University Magdeburg, Germany

Paper | Documentation | BibTex

COBRA is an open-source EDA tool for AI-assisted RFIC (RF integrated circuit) design: a circuit-level optimizer that consumes surrogate models built by ORCA. It combines:

• surrogate-model S-parameter prediction (from ORCA-generated ONNX models or fixed Touchstone SNP files),
• circuit-level simulation via Xyce or VACASK,
• goal-driven optimization (Optuna-based).
• optional EM fine-tuning (Palace) to ensure accurate results
• and real-time visualization of optimization progress

You can easily define goals and configurations in the GUI:

and visualize optimization progress in real time:

How COBRA Fits with ORCA

COBRA is the optimization/runtime side of the flow.

• ORCA creates the surrogate model (for example, tf_octa_c_ports.onnx) from EM simulation data.
• COBRA loads that ONNX model and predicts S-parameters during optimization loops.
• Optional fine-tuning in COBRA can call full-wave EM simulations (Palace) and uses ORCA geometry classes (preset or custom).

In short: ORCA builds the model, COBRA uses it to optimize circuits quickly and can verify/refine with EM fine-tuning.

Installation

Requirements

• Python 3.11 to 3.13
• Xyce (default circuit simulator backend) or VACASK (optional second backend, native VACASK netlists; see docs)
• snp2le (installed with COBRA; writes the VACASK surrogates)
• Qucs-S (to create a '.cir' netlist for Xyce)
• A component model source per parsed component:
  • ORCA-generated surrogate ONNX model (.onnx) for optimizable geometry/model inputs, or
  • fixed Touchstone file (.sNp, e.g. .s2p, .s4p, .s6p) for non-optimizable components

Optional:

• AWS Palace, if you want EM fine-tuning
• ORCA, if you want EM fine-tuning or its geometry presets: pip install "cobra-rfic[orca]"

For users: install from PyPI

COBRA is published as cobra-rfic. The import package and the CLI are both still called cobra.

Into a virtual environment with pip:

python3 -m venv .venv
source .venv/bin/activate
pip install cobra-rfic

Or, with uv, as an isolated tool that puts the cobra command on your PATH:

uv tool install cobra-rfic

Upgrade later with pip install -U cobra-rfic or uv tool upgrade cobra-rfic.

For developers: install from source

1. Clone the repository:

git clone https://github.com/DI-PASSIONATE/COBRA
cd COBRA

2. Install uv (if needed):

curl -LsSf https://astral.sh/uv/install.sh | sh

3. Create the environment from uv.lock. This installs COBRA in editable mode plus the dev tools (pytest, ruff, ty), fetching a supported Python if none is installed:

uv sync --python 3.12

Run commands through uv run (uv run cobra, uv run pytest), or activate the environment with source .venv/bin/activate. Re-run uv sync after pulling changes to pyproject.toml or uv.lock.

Without uv, a plain venv works too:

python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e . pytest pytest-cov

Running the tests

The suite covers the netlist parser, the run-configuration schema, the design-goal and penalty math, the harmonic-balance spectrum helpers and the CLI. It is headless and requires no display, no Xyce and no Palace:

uv run pytest                # or: pytest
uv run pytest --cov          # with a coverage report

Running COBRA

COBRA supports three main usage modes.

Technically, fully GUI-free usage through Python code is supported and works well for scripted workflows, CI, and reproducible experiments. For most users and day-to-day interactive optimization, the GUI is still highly recommended.

1. GUI mode

After installation, start the GUI with:

cobra

The GUI lets you:

• load a netlist and map each parsed subcircuit component to either an ONNX surrogate model or a fixed SNP Touchstone file,
• configure optimization parameters and design goals,
• run/pause/stop optimization,
• visualize S-parameters, harmonic-balance output spectra, and goal losses in real time,
• optionally enable EM fine-tuning with Palace and select ORCA geometry presets or custom geometry classes.
• browse, download, and use community surrogate models directly from HuggingFace.

For a more detailed walkthrough of the GUI features, see the GUI User Guide section below or visit the documentation.

2. Python script mode

Use the provided example:

python examples/main.py

The example in examples/main.py shows how to:

• parse netlist_multiple_SPFiles.cir with XyceNetlistParser().parse_file(...),
• map X1 to an ONNX surrogate and X2 to a fixed Touchstone SNP file,
• optimize prefixed model inputs for X1 (for example X1:bottom_winding_diameter),
• optimize parsed netlist values Cshunt_p and Cshunt_n with linked_to,
• configure OptunaOptimizer and XyceSimulator,
• run cobra.run(...) with optional ORCA geometry (TransformerOcta). The ORCA geometry is only required for finetuning.

3. JSON configuration and CLI mode

The GUI has Save configuration and Load configuration buttons for reproducible runs. A saved configuration restores the netlist, component models, simulation settings, optimizer and simulator options, optimization parameters, goals, and optional fine-tuning settings.

Or start a configuration from a netlist on the command line, then add its design goals and optimization parameters:

cobra init design.cir --model X1=models/coil.onnx -o cobra_config.json

Run the same configuration without opening the GUI:

cobra run path/to/cobra_config.json

Check a configuration or a netlist before starting a run:

cobra parse path/to/cobra_config.json

The report lists the parsed netlist, ports, surrogate components, goals, and tunable variables, and cross-checks the configuration against the netlist it references (missing model mappings, unresolvable optimization parameters, unavailable HB nodes, missing include or library files). It exits with 2 when it finds an error that would stop a run.

Check the environment before a run, and turn up the detail when one misbehaves:

cobra doctor                                  # packages, Xyce, VACASK, Palace
cobra run config.json -v                      # debug output
cobra run config.json --log-file results/run.log

Requested output goes to stdout and diagnostics to stderr, so reports stay pipeable (cobra parse config.json --json > report.json). See the CLI reference for all commands, options, and exit codes.

Relative netlist, model, and custom geometry paths are resolved from the directory containing the JSON file. Every GUI or CLI run also archives its exact input as cobra_config.json inside the timestamped results directory. This input file is separate from cobra_optimization_context.json, which contains run history and results.

See the JSON Configuration Guide for the schema and a complete example.

GUI User Guide

Coming soon

Using the HuggingFace Model Browser

The GUI includes a built-in browser for ORCA surrogate models shared on HuggingFace. How to upload your own models to HuggingFace and make them discoverable in COBRA is covered in ORCA's documentation, but the basic convention is to tag your HuggingFace repo with orca-rfic and include the required files (<repo>.onnx and optionally <repo>.py). Each component selector row in the configuration panel has a HuggingFace button next to the standard Browse button.

Browsing and downloading a model:

1. Click HuggingFace for any component.
2. The dialog opens and immediately shows any models you have already downloaded (marked [LOCAL]) at the top of the list.
3. While the list loads, public models tagged orca-rfic on HuggingFace are fetched in the background and appended once available, sorted by download count.
4. Select a model to see its details on the right (owner, downloads, likes, tags, description, and whether EM fine-tuning is available).
5. If the model is not yet local, click Download — the repo is saved to ./models/<owner>/<repo>/.
6. Once downloaded (or if already local), click Use to populate the component's file field with the path to <repo>.onnx.

File convention for shared models:

COBRA expects each HuggingFace repo to contain at least two files:

If the geometry class file is missing, COBRA will disable fine-tuning for that model and show a warning in the details panel. This allows sharing surrogate models e.g. for the default components included with ORCA.

Using a downloaded model in scripts:

Downloaded models land in ./models/<owner>/<repo>/ relative to the working directory. You can reference them directly in Python scripts:

import os
cobra = COBRA(
    netlist=netlist,
    component_onnx_mapping={
        "X1": "models/UserA/my_transformer/my_transformer.onnx",
    },
    ...
)

Capabilities

Design parameters

Small-signal parameters, derived from the .AC S-parameter result:

Large-signal parameters, derived from the .HB result (see Harmonic Balance Support). These are generated per netlist, so <node> and <port> are the names found in your circuit:

Each goal accepts an optional frequency_range string (e.g., "125-135ghz"), a min_value, a max_value, and a weight. For HB goals a single frequency such as "35ghz" selects the corresponding spectral line.

Optimizer options

OptunaOptimizer wraps Optuna and supports:

• Samplers: "tpe" (default, Bayesian), "random", "simulated_annealing", "auto" (requires optunahub)
• Pruners: None (default), "median", "successive_halving", "hyperband"
• Multi-objective mode: set multi_objective=True to optimize for a Pareto front instead of a single aggregated loss

For EM fine-tuning, a GradientDescentOptimizer is also available by passing fine_tuning_optimizer="gradient_descent" to COBRA.

Optimization parameter types

Parameters can be linked (linked_to="other_param") so that one variable always mirrors another, useful for symmetrically constrained components.

Harmonic Balance Support

S-parameters only describe small-signal behaviour. For large-signal designs — power amplifiers, mixers, anything where compression or mixing products matter — COBRA can optimize against a Harmonic Balance (.HB) analysis instead of, or in addition to, the .AC sweep.

Netlist requirements

A Qucs-S schematic with a Harmonic Balance simulation block exports the three directives COBRA needs:

.options hbint numfreq=3 STARTUPPERIODS=2
.HB 130G
.PRINT hb format=csv I(VOut) v(Out) v(Vdd) v(ip) v(on) v(op) v(sub)

• .HB lists the fundamental frequencies. One token is a single-tone analysis (LNA, PA); several tokens make it multi-tone (.HB 95E9 10E9 for a mixer), and Xyce then solves for all mixing products of those tones.
• .options hbint numfreq=… sets the number of harmonics per fundamental (numfreq=4,40 assigns a different count to each tone).
• .PRINT hb … determines which signals end up in the result file.

Both the .HB frequencies and the .options hbint values are editable in the GUI under Simulation Parameters once a netlist is loaded, so you can sweep the harmonic settings without touching the schematic.

Analysis points

Output power needs both a voltage and a current. The Qucs-S convention is a labelled node with a 0 V source used as a current probe in series with it:

VOut Out _net6 DC 0

This yields the pair V(Out) and I(VOut). COBRA scans the .PRINT hb line and offers every node that has both halves of such a pair in the Analysis Point dropdown in the configuration panel. The selected node is what the HB design parameters and the spectrum plot refer to.

Goals

Once a netlist with an HB analysis is loaded, Power_dBm[<node>] and one Gain_dB[<port>@<node>] per driven port appear in the goal dialog. A goal such as Power_dBm[Out] > 10 with a frequency range of 35ghz constrains exactly the 35 GHz line of the output spectrum, which is how you express a mixer conversion target.

AC and HB goals can be mixed freely. COBRA determines which analyses are required, generates one netlist per analysis type, runs them, and combines the resulting penalties in a single loss. If a goal needs an analysis the netlist does not contain, the missing directive is injected automatically — including a matching .PRINT HB format=csv line, without which Xyce would produce no HB output at all.

Spectrum visualization

During optimization the visualization panel plots the output spectrum of the selected analysis point as a stem plot:

• Quantity — output power (dBm), gain (dB) against a selectable input port, node voltage (dBV), or probe current (dBmA).
• Fundamentals are highlighted in a separate colour from the remaining lines.
• Click any line to drop a marker labelled with its frequency, value, and harmonic index — H2 for a single-tone analysis, or the mixing-product decomposition such as 2f1-f2 for multi-tone, so unwanted products are easy to identify when tuning for isolation.

When the run produces more than one of the S-parameter, HB and transient plots, a selector switches the left plot between them; when only one is active, that plot is shown and the selector is disabled.

Transient analysis

A .TRAN analysis reaches the same spectrum by a different route: Xyce integrates in time, and COBRA takes the FFT of the printed window. The .TRAN arguments are <print step> <stop time> [<start time> [<max step>]]; the start time (output start) is the settling time — nothing before it is printed, so nothing before it enters the FFT.

The .PRINT tran line must use format=csv (Qucs-S exports format=raw, which COBRA does not read). The spectrum is written next to Xyce's output as <netlist>.TRAN.FD.csv, and the goals are the HB ones with a TRAN: prefix — TRAN:Power_dBm[Out], TRAN:Gain_dB[P2@Out], TRAN:Isolation_dB[Out] — so HB and transient goals can be mixed in one run. examples/configs/mixer_tran_config.json is the transient counterpart of the HB mixer example.

Typical Inputs and Outputs

Inputs:

• circuit netlist .cir / .sp (Qucs-S / Xyce format)
• one or more component model files: ORCA-generated ONNX (.onnx) and/or fixed Touchstone (.sNp)
• design goals and optimization parameter definitions

Results are saved to a timestamped folder results/<timestamp>_<netlist_name>/ and include:

• cobra_optimization_context.json — full optimization history and best parameters
• surrogate_s_params_<component>.s<N>p — best-trial surrogate S-parameters
• trials/trial_<n>/ — the working directory of one trial: its netlist, <component>_predicted.s<N>p, vector-fitted SPICE subcircuits (<component>.sp) included by that netlist, and the simulator output (<netlist>.HB.FD.csv / .HB.FD.prn for a harmonic-balance analysis). Only the most recently finished trial is kept.

EM Fine-Tuning Notes (Optional)

If you enable fine-tuning:

• pass palace_fine_tuning_command to COBRA (or enable it in the GUI),
• provide one ORCA geometry object per ONNX component via orca_geometries={"X1": geometry} in cobra.run(...),
• choose fine_tuning_optimizer="reuse" to continue with the surrogate optimizer, or "gradient_descent" to switch to gradient descent for the fine-tuning phase,
• COBRA will generate a GDS file, mesh it with gmsh, run a full Palace EM simulation, and iterate.

How COBRA Works Internally

COBRA runs a staged pipeline on each optimization iteration. Understanding each stage clarifies why certain design choices were made.

┌──────────────────────────────────────────────────────────────────────┐
│                          COBRA run loop                              │
│                                                                      │
│  ┌──────────────┐   new params   ┌─────────────────┐                 │
│  │  Optimizer   │───────────────▶│ Netlist Parser  │ (patch .cir)    │
│  │  (Optuna)    │                └────────┬────────┘                 │
│  └──────┬───────┘                         │ updated netlist          │
│         │ tell(penalties)                 ▼                          │
│         │                       ┌─────────────────┐                  │
│         │                       │  EM Surrogate   │ (ONNX inference) │
│         │                       │  Stage          │                  │
│         │                       └────────┬────────┘                  │
│         │                                │ rf.Network per component  │
│         │                                ▼                           │
│         │                       ┌─────────────────┐                  │
│         │                       │  Circuit Sim    │ (vector fit →    │
│         │                       │  Stage          │  Xyce)           │
│         │                       └────────┬────────┘                  │
│         │                                │ simulated rf.Network      │
│         │                                ▼                           │
│         └───────────────────────┌─────────────────┐                  │
│                                 │  Design Goal    │                  │
│                                 │  Checker        │                  │
│                                 └─────────────────┘                  │
└──────────────────────────────────────────────────────────────────────┘

Stage 1 — Optimizer (OptunaOptimizer)

Optuna's sampler proposes the next set of parameters (geometry inputs and/or netlist variables). After each iteration the checker's penalty values are fed back via tell(), so the sampler can learn the landscape. TPE (Tree-structured Parzen Estimator) is the default because it works well with a small number of evaluations — exactly what is needed when each evaluation involves a circuit simulation.

Stage 2 — Netlist parsing and patching (XyceNetlistParser, Netlist)

XyceNetlistParser().parse_file(...) turns the .cir file into a Netlist: the logical lines (with + continuations), the components, directives and subcircuits. A trial copies the template (Netlist.copy()) and edits it without re-parsing; an edit replaces only the changed token, so spacing, inline comments and continuation layout are kept and untouched lines render unchanged. Element and parameter names match case-insensitively (c1 updates C1). The first line of a netlist is its title, as in Xyce.

Before each simulation the netlist is updated in two ways:

1. Parsed netlist elements (NETLIST_VARIABLE parameters) are patched in the Netlist (for example R/C/L values and supported instance/model parameters) so Xyce picks them up.
2. TSTONEFILE rewriting — Qucs-S exports Touchstone references as YLIN devices with a .MODEL … LIN TSTONEFILE=… directive. Xyce cannot parse this syntax, and more importantly SPICE simulators in general cannot use a raw Touchstone file as a subcircuit. The parser detects these blocks and rewrites them into normal X… subcircuit instances that point to the vector-fitted .sp file that will be generated in Stage 3.

Stage 3 — EM surrogate inference (EMSurrogateStage)

The ONNX model (produced by ORCA) receives the current geometry parameters and a frequency sweep as inputs. It returns the real and imaginary parts of each S-parameter entry, which are assembled into a scikit-rf Network object.

Before inference, the geometry is checked against the feasibility constraints the model declares in its input_constraints metadata (written by ORCA). A trial that violates one is not simulated at all, since the surrogate was never trained on that geometry, and it does not count as an iteration: Optuna records it as pruned and suggests a replacement (optimizers without a pruned state get the failed-simulation penalty instead).

The sweep covers the whole band the model declares in its input_parameter_ranges metadata (the frequency entry, written by ORCA), in 1 GHz steps; a model without that metadata is rejected before the run starts, since COBRA will not guess a band. A band that starts below 1 GHz also gets the sub-GHz points ORCA's presets simulate (10, 20, 100, 200, 300, 500 and 700 MHz). The full band is used deliberately rather than just the design goals' range: the vector fit of the next stage extrapolates freely outside the frequencies it was given, and Xyce evaluates the fitted subcircuit at the DC operating point and at every harmonic of an .HB or .TRAN analysis. cobra parse warns when the netlist's .AC sweep or .HB harmonics reach beyond the model's band.

ONNX was chosen because it is a portable, framework-agnostic format: the model runs with onnxruntime at inference time without requiring the full training environment (PyTorch, TensorFlow, …), keeping COBRA's dependency footprint small and deployment straightforward.

A plain Touchstone file (.sNp) can also be used instead of an ONNX model when no geometry variation is needed — COBRA detects the file extension and loads it directly as a fixed network.

Stage 4 — Vector fitting and circuit simulation (CircuitSimulationStage)

Why vector fitting?

Xyce (like all SPICE-family simulators) cannot read a Touchstone file directly as a component. SPICE netlists describe circuits in terms of lumped elements and analytical subcircuits — there is no native mechanism to embed a tabulated frequency-domain response.

COBRA solves this by vector-fitting the surrogate-predicted S-parameter network using scikit-rf's VectorFitting implementation. Vector fitting approximates the frequency response as a sum of rational functions (poles and residues). The fitted model is then written out as a standard SPICE subcircuit (.sp) containing only resistors, capacitors, inductors, and controlled sources — elements every SPICE engine understands natively.

VectorFitting.auto_fit has no iteration limit and, on some data, never converges: its adding-and-skimming loop can cycle between two model orders forever (3 of 20 ORCA inductors tested at its default order limit). COBRA stops such a fit after 1000 pole relocations (a converging fit needs about 20 to 120), logs a warning and penalises that trial. The VACASK backend's fitter, snp2le, has its own limit (250 relocations) and refits a stuck fit instead, so there the trial keeps a model.

The generated subcircuit is automatically included in the patched netlist via a .INCLUDE directive, so Xyce sees a fully self-contained netlist on every iteration.

After the include is in place, COBRA runs one Xyce simulation per analysis type required by the goals (.AC, .HB, …), reads each result back — a Touchstone file as a scikit-rf Network for .AC, a frequency-domain table as a DataFrame for .HB — and passes them to the goal checker.

Stage 5 — Design goal checking (DesignGoalChecker)

Each DesignGoal computes a penalty scalar from the simulated network. The penalty is zero (or negative, acting as a reward) when the network already satisfies the goal, and grows proportionally to the squared normalized deviation when it does not. This smooth, differentiable penalty signal is what the optimizer minimizes.

Goals are grouped by the analysis they need, so each one is evaluated against the matching result: S-parameter and lumped-element goals against the .AC network, power and gain goals against the .HB spectrum.

For 4-port networks the checker automatically converts to mixed-mode (differential/common-mode) parameters before extracting lumped quantities such as inductance, Q-factor, and coupling coefficient.

Optional Stage 6 — EM fine-tuning (EMFineTuningStage)

Once the surrogate-driven optimization converges, COBRA can verify and refine the result with a real EM simulation:

1. The current geometry parameters are used to generate a GDS layout file via the ORCA geometry class.
2. gmsh meshes the GDS layout according to the PDK stackup.
3. Palace runs a full-wave EM simulation and produces a verified Touchstone file.
4. The verified S-parameters replace the surrogate prediction and are passed back through the circuit simulation and goal-checking stages.
5. If the goals are not met, the optimizer is updated with the real penalty and a new iteration begins.

This two-phase approach (fast surrogate loop + occasional EM verification) gives the speed of a surrogate-based optimizer while still guaranteeing that the final design is validated against the actual physics.

Troubleshooting

• If cobra command is not found, ensure your virtual environment is activated and reinstall with pip install -e ..
• If geometry presets fail to load, verify ORCA is installed in the same environment (pip install "cobra-rfic[orca]").
• If circuit simulation fails, verify Xyce is installed and available in your PATH.
• If AutoSampler fails to initialize, install its optional dependencies: pip install optunahub cmaes scipy torch.

Cite This Work

If you use COBRA in your research, please cite our SBCCI 2026 paper:

@INPROCEEDINGS{2026_COBRA,
  author={Simone, Gianluca and Lurz, David and Grund, Martin and Schneider, Fabian and Loose, Michael and Breun, Sascha and Koch, Manuel and Weigel, Robert and Franchi, Norman},
  booktitle={2026 39th SBC/SBMicro/IEEE Symposium on Integrated Circuits and Systems Design (SBCCI)},
  title={{COBRA: An AI-Assisted Circuit-Level Optimizer for Open Source Based RFIC Design}},
  year={2026},
  month={aug},
  pages={1--5},
  organization={IEEE},
  doi={10.1109/SBCCI69725.2026.11706804},
  keywords={artificial intelligence, design automation, EDA, neural network, open-source, optimization, Palace, Qucs-S, radio frequency integrated circuit, surrogate model, Xyce}
}

Acknowledgements

This work was supported by the Bundesministerium für Forschung, Technologie und Raumfahrt (BMFTR) under the DI-PASSIONATE project. We appreciate the scientific support and HPC resources provided by the Erlangen National High Performance Computing Center (NHR@FAU) of the Friedrich-Alexander-Universität Erlangen-Nürnberg (FAU). The hardware is funded by the German Research Foundation (DFG).

We thank our colleagues in the LITES institute for their feedback and support during development. Special thanks to the open-source community for providing the tools and libraries that made this project possible, including but not limited to:

• gdsfactory
• gds2palace
• setupEM
• Palace
• PyTorch
• ONNX
• scikit-rf
• OpenStack