get_waveform
Retrieve waveform statistics from LTspice simulation results, returning a time-bucketed envelope with min, max, mean, RMS, peak-to-peak, and crest factor to analyze signal shape without downloading all samples.
Instructions
Decimated numeric egress FOR THE MODEL: returns a min/max-preserving stat-envelope of one real-valued signal as DATA in your context (numbers, not a picture) over a time/sweep/frequency window — for when a scalar isn't enough and you need the SHAPE (switching nodes, amplifier internal nodes, startup transients).
Splits the window into equal-time buckets; each bucket reports the raw sample min/max (a narrow spike or ringing peak is never averaged away), time-weighted trapezoidal mean/rms (correct on SPICE's adaptive timestep), pk_pk, and crest_factor (peak/rms — high = impulsive/spiky). Scalar-guided zoom: read the envelope, then re-request a narrower [t_start, t_end] to resolve a region at higher resolution (same call, tighter window). The observations list surfaces FACTS, not verdicts (decimation coverage, dropped non-finite samples, which bucket has the largest pk-to-pk) — you decide what the shape means.
Works on transient (.tran), DC sweep (.dc), and noise (.noise) results. Sibling egress, don't confuse: export_waveform writes EVERY sample to a CSV FILE for your own code; plot_waveform renders an interactive PICTURE for a human to look at. For complex AC data use bode_metrics; for a single scalar use signal_stats; for one point value use query_value.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| step | No | Step index for .step directives. | |
| t_end | No | Window end in SPICE notation. | |
| format | No | Response format: 'json' for structured data, 'text' for human-readable | |
| job_id | No | Decimate a specific run of a completed sweep/MC (or single) job instead of a raw_file path; pair with ``run_index``. | |
| signal | Yes | Signal/trace name (e.g., 'V(out)', 'I(R1)'), or a device operating-point shorthand for an ngspice .save'd parameter: 'm1.gm' / 'm1.vth' (resolves to '@m1[gm]', incl. subcircuit paths like 'x1.m1.gm'). | |
| buckets | No | Number of equal-time envelope buckets (overview resolution). Defaults to 200; capped at 2000 (and at the server's max_points_returned ceiling and the sample count). | |
| t_start | No | Window start in SPICE notation (e.g. '1m', '100u'). Narrow the window and re-request to zoom into a region of interest. | |
| raw_file | No | Path to .raw result file. Pass this OR ``job_id`` (a job run), not both. | |
| run_index | No | 0-based run to read when ``job_id`` is given (default 0). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| signal | No | ||
| buckets | No | ||
| axis_unit | No | ||
| decimated | No | ||
| point_count | No | ||
| bucket_count | No | ||
| observations | No | ||
| analysis_type | No | ||
| window_end_used | No | ||
| window_start_used | No | ||
| max_points_ceiling | No |