bode_metrics
Analyze LTspice AC simulations to extract filter cutoffs, roll-off slope, gain/phase at specific frequencies, and crossing points (e.g. unity-gain, phase-margin) in one call.
Instructions
AC / Bode-plot analysis in one tool, selected by mode. The response shape depends on the mode:
mode='filter' — filter type, cutoffs (at ref_db below passband), passband gain/ripple, stopband rejection, transition BW, pole-order, and an auto-estimated asymptotic roll-off slope (dB/decade) — covers cutoff AND slope in one call.
mode='slope' — magnitude slope (dB/decade + dB/octave) between f_low and f_high; pick endpoints ≥1 decade past any knee. Use when you need a custom window or dB/octave ('filter' already reports an auto-estimated asymptotic dB/decade slope).
mode='point' — magnitude (dB + linear) and phase at each of frequencies (log-axis interpolation; out-of-range clamps + warns).
mode='crossing' — every frequency where quantity crosses level (phase is UNWRAPPED first); the escape hatch for custom queries like unity-gain (0 dB) or phase-margin (-180°) frequencies.
Pass all_steps=true to compute the chosen mode for every step of a .step sweep in one call (returns a steps list instead of a single result) — e.g. the -3 dB cutoff at every value of a stepped component.
To analyze a run of a completed sweep/MC job, pass job_id + run_index instead of raw_file (combine with all_steps to also sweep the .step axis within that run).
For loop-gain stability margins use stability_metrics; for resonant peaks & Q use resonance.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | Which view of the AC response to compute: 'filter' — LPF/HPF/BPF/BSF type, cutoffs, ripple, rejection, and an auto-estimated asymptotic roll-off slope (dB/decade) — so one call gives both cutoff AND slope (args: ref_db, flatness_db, passband_range, stopband_range) 'slope' — magnitude slope between two explicit frequencies; use when you need a custom window or dB/octave ('filter' already reports an asymptotic dB/decade slope) (args: f_low, f_high — both required) 'point' — magnitude (dB + linear) and phase at specific frequencies (args: frequencies — required; include_unwrapped_phase) 'crossing' — every frequency where magnitude/phase crosses a level (args: quantity + level — required; direction, f_start, f_end, max_results, min_separation_decades) | |
| step | No | Step index for .step sweeps | |
| f_end | No | crossing: upper frequency bound. | |
| f_low | No | slope: low frequency bound (required). | |
| level | No | crossing: level to cross, in the units of `quantity`. | |
| f_high | No | slope: high frequency bound (required). | |
| format | No | ||
| job_id | No | Analyze a specific run of a completed sweep/MC (or single) job instead of a raw_file path; pair with ``run_index``. The analyzed run's swept parameter values are echoed back under ``params`` (with ``run_index``), so you can tell which sweep point this is without a separate batch_results call. Combine with ``all_steps`` to sweep the .step axis WITHIN that run (a value-list/param sweep stores each run as its own raw — address those by run_index, not all_steps). | |
| ref_db | No | filter: cutoff reference below passband (dB). | |
| signal | Yes | Signal to analyze: a single trace (e.g. 'V(out)') or a transfer-function ratio of two traces (e.g. 'V(out)/V(mid)'), which divides the two complex AC waves — the way to express an inter-stage gain, loop gain, or PSRR the simulator doesn't store as its own trace. | |
| f_start | No | crossing: lower frequency bound. | |
| quantity | No | crossing: 'magnitude_db' | 'magnitude_linear' | 'phase_deg'. | |
| raw_file | No | Path to AC analysis .raw result file. Pass this OR ``job_id``, not both. | |
| all_steps | No | Compute the metric for EVERY step of a stepped (.step) sweep in one call, instead of the single `step`. Returns `steps`: a list of per-step results (each tagged with its `step` index). A step whose computation fails is returned with an `error` field rather than aborting the whole call. On a non-stepped raw this returns a single entry. Use this for 'give me the cutoff/slope/gain at every step'. | |
| direction | No | crossing: edge direction. | any |
| run_index | No | 0-based run to analyze when ``job_id`` is given (default 0). | |
| flatness_db | No | filter: passband flatness tolerance (dB). | |
| frequencies | No | point: frequencies to query (SPICE notation). | |
| max_results | No | crossing: cap on returned crossings. | |
| passband_range | No | filter: optional [f_lo, f_hi] passband override. | |
| stopband_range | No | filter: optional [f_lo, f_hi] stopband region. | |
| min_separation_decades | No | crossing: merge crossings within this many decades. | |
| include_unwrapped_phase | No | point: also return cumulative unwrapped phase. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | ||
| level | No | ||
| steps | No | ||
| params | No | ||
| points | No | ||
| ref_db | No | ||
| signal | No | ||
| delta_db | No | ||
| f_low_hz | No | ||
| quantity | No | ||
| warnings | No | ||
| all_steps | No | ||
| crossings | No | ||
| direction | No | ||
| f_high_hz | No | ||
| run_index | No | ||
| step_count | No | ||
| filter_type | No | ||
| gain_low_db | No | ||
| gain_high_db | No | ||
| span_decades | No | ||
| cutoff_low_hz | No | ||
| cutoff_high_hz | No | ||
| cutoff_level_db | No | ||
| estimated_order | No | ||
| passband_low_hz | No | ||
| passband_gain_db | No | ||
| passband_high_hz | No | ||
| passband_ripple_db | No | ||
| slope_db_per_decade | No | ||
| slope_db_per_octave | No | ||
| stopband_rejection_db | No | ||
| transition_bandwidth_hz | No | ||
| nearest_pole_order_estimate | No | ||
| rolloff_slope_db_per_decade | No |