stability_metrics
Identify all unity-gain and -180° phase crossovers in a loop-gain AC sweep, compute per-crossing margins, and classify stability.
Instructions
Find EVERY unity-gain and -180° phase crossover in a loop-gain AC sweep, report phase margin at each unity-gain crossing and gain margin at each -180° crossing. Replaces the single-crossing approximation in simulation_summary, which returns wrong margins on conditionally-stable systems.
Run this on a LOOP-GAIN signal (typically a dedicated middlebrook probe or .AC of the open loop). Running on a closed-loop output gives meaningless margins — if the DC phase starts near ±180° (a closed-loop / inverting output rather than a loop probe, which starts near 0°), a warning says so in warnings.
Returns: dc_gain_db, high_freq_gain_db, stability classification (stable / unstable / conditional / unconditional / always_below_unity), all crossings, per-crossing margins, and the worst-case values.
Nuances:
Phase is UNWRAPPED first, so systems whose phase drops past -360° are handled correctly (otherwise the raw wrap hides the crossing).
If phase NEVER crosses -180°, gain margin is 'infinite' (returned as null with stability='unconditional'). That's stable, not an error.
If gain NEVER reaches unity, phase margin is undefined (returned as null with stability='always_below_unity').
Multiple crossovers trigger stability='conditional' and a warning — each one needs its own review.
For -3 dB filter cutoffs use bode_metrics(mode='filter'); for custom crossings use bode_metrics(mode='crossing').
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| raw_file | Yes | Path to loop-gain AC analysis .raw file | |
| signal | Yes | Loop-gain signal (e.g. 'V(loop)') | |
| min_separation_decades | No | Merge near-duplicate crossovers closer than this many decades. | |
| step | No | Step index for .step sweeps | |
| format | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dc_gain_db | Yes | ||
| high_freq_gain_db | Yes | ||
| stability | Yes | ||
| unity_gain_crossovers | Yes | ||
| phase_180_crossovers | Yes | ||
| phase_margins | Yes | ||
| gain_margins | Yes | ||
| phase_margin_worst_deg | No | ||
| gain_margin_worst_db | No | ||
| warnings | Yes | ||
| signal | Yes |