Simulation

Run Standalone Simulation

POST /api/simulate

Run a SPICE netlist without creating or modifying a notebook. Useful for one-off simulations or integration testing.

Request body:

{
  "netlist": "V1 1 0 DC 5\nR1 1 2 1k\nR2 2 0 2k\n.op\n.end",
  "engine": "ngspice"
}

Response 200:

{
  "success": true,
  "waveform": {
    "variables": [
      {"name": "v(1)", "type": "voltage"},
      {"name": "v(2)", "type": "voltage"}
    ],
    "points": 1,
    "x_data": [0.0],
    "y_data": {"v(1)": [5.0], "v(2)": [3.333]},
    "x_type": "time",
    "is_complex": false,
    "y_magnitude_db": null,
    "y_phase_deg": null
  },
  "log": "ngspice output...",
  "error": null,
  "elapsed_seconds": 0.42
}

Run Cell in Notebook

POST /api/notebooks/{notebook_id}/cells/{cell_id}/run

No request body. Uses the cell’s source as the netlist and the notebook’s engine setting.

Response 200 — same SimulationResponse shape as standalone. The cell’s outputs array is updated in the saved notebook.

SimulationResponse

Field	Type	Description
success	boolean	Whether the simulation completed without errors
waveform	WaveformData | null	Simulation results (null if simulation failed)
log	string	Raw simulator output (stdout/stderr)
error	string | null	Error message if simulation failed
elapsed_seconds	number	Wall-clock simulation time

WaveformData

{
  "variables": [{"name": "v(out)", "type": "voltage"}],
  "points": 100,
  "x_data": [0.0, 0.001, ...],
  "y_data": {"v(out)": [0.0, 0.5, ...]},
  "x_type": "time",
  "is_complex": false,
  "y_magnitude_db": null,
  "y_phase_deg": null
}

Field	Type	Description
variables	array	Signal names and types (voltage, current)
points	integer	Number of data points
x_data	number[]	Horizontal axis values (time or frequency)
y_data	object	Signal name → value array mapping
x_type	string	"time" or "frequency"
is_complex	boolean	true for AC analysis
y_magnitude_db	object | null	Per-signal magnitude in dB (AC only)
y_phase_deg	object | null	Per-signal phase in degrees (AC only)

Note

For AC analysis (is_complex: true), use y_magnitude_db and y_phase_deg for Bode plots rather than y_data. The x_type will be "frequency" and x_data contains frequency values in Hz.

Error Handling

When a simulation fails (syntax error, convergence failure, missing model), the response still returns 200 but with success: false:

{
  "success": false,
  "waveform": null,
  "log": "Error: unknown subcircuit...",
  "error": "Simulation failed: unknown subcircuit 'LM741'",
  "elapsed_seconds": 0.1
}

Check the log field for the full simulator output — it often contains line numbers and detailed diagnostics that aren’t in the error summary.