Troubleshooting¶
Start With cobra doctor¶
cobra doctor reports the interpreter, the required packages and simulators,
and the optional components COBRA found. It exits with 1 when a requirement
is missing, and it is the quickest way to tell a missing dependency from a
misconfigured run.
When a run itself misbehaves, repeat it with more detail:
cobra run config.json -v # debug output on the console
cobra run config.json --log-file results/run.log # a full debug log on disk
--log-file records at debug level regardless of what the console shows, so it
can be combined with -q.
cobra Command Not Found¶
- Activate your virtual environment.
- Reinstall in editable mode:
Xyce Execution Fails¶
COBRA treats the two kinds of Xyce failure differently.
A simulation that fails — Xyce exits non-zero (for example because the sampled parameters describe a circuit that will not converge) or writes no output — is a property of the parameters. COBRA logs a warning, assigns a very high loss to every design goal that needed that analysis, and continues, so the optimizer steers away from those parameters:
WARNING Xyce failed for SimulationType.AC (return code 1) in results/...
WARNING No AC result for these parameters; the design goals that need it are penalised so the optimizer avoids them
Occasional warnings of this kind are normal. If every iteration produces them, the netlist itself is at fault:
- Check your netlist compatibility.
- Confirm generated include/subcircuit files exist in the run output folder.
- Narrow the parameter ranges so the optimizer cannot reach unphysical values.
A simulator that cannot be run at all — Xyce is not installed, not on
PATH, or not executable — raises SimulatorError and stops the run, because
no choice of parameters can fix it:
- Verify
Xyceis installed and inPATH(cobra doctorreports this). - Or set the simulator's
xyce_commandsetting to the absolute path of the executable. - With
parallel_xyceenabled,mpirunmust be onPATHtoo. The rank count comes from theparallel_xyce_processessetting (default: the machine's core count);mpirunfails when it exceeds the available slots.
Component Mapping Errors¶
If COBRA reports missing model files for components:
- Ensure every parsed component name has an entry in
component_onnx_mapping. - Match exact instance names from the netlist (for example
X1,X2).
Frequency Range Errors¶
If goal range parsing fails:
- Use format similar to
125-135ghz. - Avoid malformed ranges like trailing separators.
If cobra parse warns that an analysis evaluates the circuit outside the band the
model covers, the surrogate is only predicted inside the frequency range of its
ONNX metadata; beyond it the vector-fitted subcircuit extrapolates. Narrow the
.AC sweep or numfreq, or use a model trained over the wider band. A model
without that metadata is rejected: re-export it with input_parameter_ranges
(ORCA writes it) so the band is known.
Trained Ranges and Infeasible Geometries¶
ORCA records, in each ONNX model's metadata, the range every geometry input was
trained on and the feasibility constraints a buildable geometry satisfies (for
example bottom_linewidth <= bottom_winding_diameter / 3). cobra parse lists
both for each component, together with the physical properties the model
guarantees.
- If
cobra parsewarns that a parameter's bounds reach beyond the trained range, the surrogate extrapolates there. Narrow the bounds unless you mean to. - During a run, a trial whose parameters violate a constraint is not simulated
and does not count as an iteration: Optuna records it as pruned and suggests
another one, and the progress display, plots and run log never see it.
Optimizers without a pruned state, such as gradient descent, get the same
penalty as a failed simulation instead. Run with
--verboseto see which constraint each skipped trial violated; the number skipped is logged at the end of the optimization. After 1000 skipped trials in a row the run stops, because the bounds cover mostly unbuildable geometries; narrow them. - A model whose constraints are not valid JSON, or use anything beyond ORCA's expression grammar, is refused before the run starts. COBRA parses the expressions itself and never executes them as Python code, so a model from an untrusted source cannot run code through them.
ORCA Geometry Import Errors¶
- Ensure ORCA is installed in the same Python environment.
- Validate import path used in your script.
Palace Fine-Tuning Errors¶
- Verify Palace command is valid and executable.
- Confirm geometry/mesh prerequisites are available.
- "The Palace simulation for X1 failed": ORCA logs Palace's last output lines just above
this message. The Palace model is in
fine_tuning/iteration_NN/palace_sims/inside the results folder.
Large Runtime or Slow Progress¶
- Reduce
max_iterationsduring early debugging. - Narrow parameter search ranges.
- Start with fewer design goals, then add constraints incrementally.