Waveform Tools

get_waveform

Extract waveform data from a .raw simulation results file. For transient analysis, returns time plus voltage/current values. For AC analysis, returns frequency plus magnitude (dB) and phase (degrees). For stepped simulations (.step, .mc, .temp), specify run (1-based) to extract a single run, or omit it to get all data combined.

Parameter	Type	Default	Description
raw_file_path	`str`	---	Path to the `.raw` file produced by simulation.
signal_names	`list[str]`	---	Signal names to extract, e.g. `["V(out)", "I(R1)"]`.
max_points	`int`	`1000`	Maximum data points to return. If the simulation has more points, the data is uniformly downsampled.
run	`int \| None`	`None`	Run number (1-based) for stepped simulations. `None` returns all data combined.

Returns: A dict with x_axis_name ("time" or "frequency"), x_axis_data (list of floats), signals (keyed by signal name --- each contains either values for real data, or magnitude_db and phase_degrees for complex/AC data), total_points, returned_points, is_stepped, and n_runs.

Example — transient analysis

{
  "x_axis_name": "time",
  "x_axis_data": [0.0, 1e-06, 2e-06, 3e-06],
  "signals": {
    "V(out)": {
      "values": [0.0, 0.632, 0.865, 0.950]
    }
  },
  "total_points": 8192,
  "returned_points": 1000,
  "is_stepped": false,
  "n_runs": 1
}

Example — AC analysis

{
  "x_axis_name": "frequency",
  "x_axis_data": [1.0, 10.0, 100.0, 1000.0, 10000.0],
  "signals": {
    "V(out)": {
      "magnitude_db": [-0.01, -0.04, -3.01, -20.04, -40.01],
      "phase_degrees": [-0.57, -5.7, -45.0, -84.3, -89.4]
    }
  },
  "total_points": 801,
  "returned_points": 801,
  "is_stepped": false,
  "n_runs": 1
}

list_simulation_runs

List runs in a stepped simulation (.step, .mc, .temp). Returns run count and boundary information for multi-run .raw files. Use this to discover how many runs exist before extracting individual runs with get_waveform.

Parameter	Type	Default	Description
raw_file_path	`str`	---	Path to the `.raw` file from a stepped simulation.

Returns: A dict with is_stepped (bool), n_runs, total_points, plotname, variables (list of name/type pairs), and for stepped files a runs list where each entry has run (1-based index), start_index, end_index, and points.

Example

{
  "is_stepped": true,
  "n_runs": 5,
  "total_points": 40960,
  "plotname": "Transient Analysis",
  "variables": [
    { "name": "time", "type": "time" },
    { "name": "V(out)", "type": "voltage" }
  ],
  "runs": [
    { "run": 1, "start_index": 0, "end_index": 8192, "points": 8192 },
    { "run": 2, "start_index": 8192, "end_index": 16384, "points": 8192 },
    { "run": 3, "start_index": 16384, "end_index": 24576, "points": 8192 },
    { "run": 4, "start_index": 24576, "end_index": 32768, "points": 8192 },
    { "run": 5, "start_index": 32768, "end_index": 40960, "points": 8192 }
  ]
}

evaluate_waveform_expression

Evaluate a math expression on simulation waveforms. Supports the operators +, -, *, / and the functions abs(), sqrt(), log10(), dB(). Signal names in the expression reference variables from the .raw file directly.

Parameter	Type	Default	Description
raw_file_path	`str`	---	Path to the `.raw` file.
expression	`str`	---	Math expression using signal names. Examples: `"V(out) * I(R1)"` for instantaneous power, `"V(out) / V(in)"` for voltage gain, `"dB(V(out))"` for magnitude in dB.
max_points	`int`	`1000`	Maximum data points to return.

Returns: A dict with expression (echoed back), total_points, returned_points, x_axis_name, x_axis_data, values (computed result array), and available_signals (list of signal names in the .raw file for reference).

Example — instantaneous power

{
  "expression": "V(out) * I(R1)",
  "total_points": 8192,
  "returned_points": 1000,
  "x_axis_name": "time",
  "x_axis_data": [0.0, 1e-06, 2e-06],
  "values": [0.0, 0.00125, 0.00198],
  "available_signals": ["time", "V(out)", "V(in)", "I(R1)"]
}

export_csv

Export waveform data to CSV format. Writes a file with the x-axis (time or frequency) as the first column and each requested signal as subsequent columns. Complex (AC) signals are split into magnitude (dB) and phase (degrees) columns automatically.

Parameter	Type	Default	Description
raw_file_path	`str`	---	Path to the `.raw` file.
signal_names	`list[str] \| None`	`None`	Signals to export. `None` exports all signals.
output_path	`str \| None`	`None`	Where to save the CSV file. `None` auto-generates a path in `/tmp`.
max_points	`int`	`10000`	Maximum rows to export.

Returns: A dict with output_path (where the CSV was written), rows (number of data rows), and columns (list of column header strings).

Example

{
  "output_path": "/tmp/my_circuit.csv",
  "rows": 8192,
  "columns": ["time", "V(out)", "V(in)", "I(R1)"]
}

plot_waveform

Generate an SVG plot from simulation results. Parses a .raw file and creates a waveform plot saved as an SVG file. Supports time-domain, Bode (magnitude and phase vs. frequency), and FFT spectrum plot types.

Parameter	Type	Default	Description
raw_file	`str`	---	Path to the LTspice `.raw` binary file.
signal	`str`	`"V(out)"`	Signal name to plot (e.g., `"V(out)"`, `"I(R1)"`).
plot_type	`str`	`"auto"`	Plot style: `"auto"` (detect from data), `"time"`, `"bode"`, or `"spectrum"`.
output_path	`str \| None`	`None`	Where to save the SVG. `None` auto-generates a path in `/tmp`.

Returns: A dict with svg_path (where the SVG was written), plot_type (the resolved type after auto-detection), signal (the matched signal name), and points (number of data points in the plot).

Example

{
  "svg_path": "/tmp/ltspice_plot_abc123.svg",
  "plot_type": "bode",
  "signal": "V(out)",
  "points": 801
}