Command Line¶
The cobra command starts a configuration from a netlist, runs a saved
configuration, inspects an input file, checks the environment, or opens the GUI.
cobra # open the graphical interface
cobra init design.cir # write a starter configuration for a netlist
cobra run config.json # run a saved configuration headlessly
cobra parse design.cir # report what COBRA reads from an input file
cobra doctor # check simulators and optional packages
cobra --version
cobra <command> --help
Commands¶
| Command | Purpose |
|---|---|
init NETLIST |
Write a starter JSON configuration for a netlist |
run CONFIG |
Execute a saved JSON configuration without the GUI |
parse TARGET |
Report a configuration or netlist without running it |
doctor |
Report the Python packages and simulators COBRA found |
gui |
Open the graphical interface (also the default with no command) |
Output Options¶
These options are accepted before or after the command, so both
cobra -v run config.json and cobra run -v config.json work.
| Option | Effect |
|---|---|
-v, --verbose |
Show debug output; -vv also includes third-party libraries |
-q, --quiet |
Report warnings and errors only, and hide the progress bar |
--log-file PATH |
Also write a timestamped debug log to PATH |
--no-color |
Disable coloured output (the NO_COLOR variable does the same) |
--log-file always records at debug level, whatever the console shows, so a
long run can be diagnosed afterwards:
What Goes Where¶
Requested output — the parse report, the run header and summary, the
doctor table, the path init wrote — is written to stdout. Progress and
diagnostics are written to stderr. Piping a report therefore stays safe:
Starting a Configuration¶
cobra init writes a configuration filled in from a netlist, to be completed
and checked before a run:
cobra init design.cir --model X1=models/coil.onnx -o design_config.json
# add design_goals and optimization_parameters, then:
cobra parse design_config.json && cobra run design_config.json
| Option | Effect |
|---|---|
-o, --output PATH |
Where to write the file (default: <netlist stem>_config.json in the current directory) |
--model NAME=PATH |
ONNX or Touchstone model for component NAME; repeat for each component |
--simulator NAME |
Simulator whose netlist dialect to read: XyceSimulator (default) or VacaskSimulator |
--force |
Overwrite an existing output file |
The file contains the netlist, the parameters of its analysis directives (.AC,
.HB, .TRAN, .DC; for VACASK acsp, hb, tran, noise, hbnoise), the default optimizer and simulator settings, and a
model for every component given with --model or whose netlist TSTONEFILE
exists. Paths are written relative to the output file. Components still without
a model are listed on stderr, together with the design-goal parameters the
netlist supports.
design_goals and optimization_parameters are left empty: they are design
decisions COBRA cannot infer. cobra parse and cobra run reject a
configuration until both have at least one entry.
For a VACASK netlist pass the simulator, here and for parse:
cobra init examples/netlists/VACASK/trafo_acsp.sim --simulator VacaskSimulator
cobra parse examples/netlists/VACASK/trafo_acsp.sim --simulator VacaskSimulator
parse applies --simulator to a netlist TARGET; for a configuration the
simulator named in the file is used. See VACASK Simulator.
Running a Configuration¶
The run starts with a header describing what is about to happen, shows a progress bar while it iterates, and ends with a summary:
COBRA 1.5.0
netlist amplifier.cir
analysis AC
optimizer OptunaOptimizer
simulator XyceSimulator
parameters 4
goals 2
iterations up to 500
COBRA optimization: 14%|█████ | 68/500 [02:41<17:03, 2.37s/it]
Summary
status design goals achieved at iteration 68
wall time 2m 41s
results results/2026-09-06_11-04-22_amplifier
Checking the Environment¶
cobra doctor reports the interpreter, the required packages and simulators,
and the optional components whose absence only disables a feature. It exits
with 1 when something required is missing, which makes it usable as a
pre-flight check in CI.
Xyce is required for circuit simulation; vacask is listed as an optional
executable (needed only for VacaskSimulator). When it comes from Spack, load it in
the same shell first:
Exit Codes¶
| Code | Meaning |
|---|---|
0 |
Success |
1 |
The run failed, or doctor found a missing requirement |
2 |
Invalid input, or a parse report containing errors |
130 |
Interrupted (Ctrl+C) |
This makes parse usable as a gate: