Ryan Malloy
844088aa29
Starlight site at docs-site/ following warehack.ing cookie-cutter pattern (3-compose split, Caddy prod stage, Makefile targets). 15 content pages covering simulation engines, waveform viewer, schematics, embedding with postMessage theme sync, and full REST API reference adapted from llms.txt. Blue accent theme matching SpiceBook's application palette. Adds docs link to homepage reference section.
114 lines
3.1 KiB
Plaintext
114 lines
3.1 KiB
Plaintext
---
|
|
title: Simulation
|
|
description: Run SPICE netlists standalone or within notebook cells via the SpiceBook REST API.
|
|
---
|
|
|
|
import { Aside } from '@astrojs/starlight/components';
|
|
|
|
## 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:**
|
|
|
|
```json
|
|
{
|
|
"netlist": "V1 1 0 DC 5\nR1 1 2 1k\nR2 2 0 2k\n.op\n.end",
|
|
"engine": "ngspice"
|
|
}
|
|
```
|
|
|
|
**Response** `200`:
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```json
|
|
{
|
|
"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) |
|
|
|
|
<Aside type="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.
|
|
</Aside>
|
|
|
|
## Error Handling
|
|
|
|
When a simulation fails (syntax error, convergence failure, missing model), the response still returns `200` but with `success: false`:
|
|
|
|
```json
|
|
{
|
|
"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.
|