Stability and Power Tools

Three tools for evaluating feedback loop stability and computing power dissipation metrics from simulation results.

analyze_stability

Measure gain margin and phase margin from AC loop gain data. Parses the .raw file from an AC simulation, extracts the specified signal as the complex loop gain T(jw), and computes the full Bode plot (magnitude in dB and unwrapped phase in degrees). Finds the gain crossover frequency (where |T| = 0 dB) and the phase crossover frequency (where phase = -180 degrees), then derives both margins.

Parameter	Type	Default	Description
raw_file_path	`str`	---	Path to `.raw` file from an AC simulation.
signal_name	`str`	---	Loop gain signal name, e.g. `"V(out)"` or `"V(loop_gain)"`.

Returns: A dict with four keys:

gain_margin — contains gain_margin_db (dB above instability, or Infinity if no phase crossover exists), phase_crossover_freq_hz (frequency where phase crosses -180 degrees, or null), and is_stable (boolean).
phase_margin — contains phase_margin_deg (degrees above instability, or Infinity if gain is always below 0 dB), gain_crossover_freq_hz (frequency where gain crosses 0 dB, or null), and is_stable (boolean).
bode — arrays of frequency_hz, magnitude_db, and phase_deg for plotting.
is_stable — overall boolean: true only when both margins are positive.

Example

{
  "gain_margin": {
    "gain_margin_db": 12.4,
    "phase_crossover_freq_hz": 2450000.0,
    "is_stable": true
  },
  "phase_margin": {
    "phase_margin_deg": 62.3,
    "gain_crossover_freq_hz": 485000.0,
    "is_stable": true
  },
  "bode": {
    "frequency_hz": [1.0, 1.26, 1.58, "..."],
    "magnitude_db": [40.0, 39.8, 39.5, "..."],
    "phase_deg": [-2.3, -2.9, -3.6, "..."]
  },
  "is_stable": true
}

analyze_power

Compute power metrics from voltage and current waveforms in a transient simulation. Calculates instantaneous power P(t) = V(t) * I(t) and derives time-averaged, RMS, peak, minimum, and power factor values.

Power factor is computed as the ratio of average (real) power to apparent power (Vrms * Irms). A power factor of 1.0 means voltage and current are perfectly in phase; values below 1.0 indicate reactive loading.

Parameter	Type	Default	Description
raw_file_path	`str`	---	Path to `.raw` file from a transient simulation.
voltage_signal	`str`	---	Voltage signal name, e.g. `"V(out)"`.
current_signal	`str`	---	Current signal name, e.g. `"I(R1)"`.

Returns: A dict with avg_power (time-averaged power in watts), rms_power (RMS of instantaneous power), peak_power (maximum instantaneous power), min_power (minimum instantaneous power), and power_factor (ratio of real to apparent power).

Example

{
  "avg_power": 0.245,
  "rms_power": 0.312,
  "peak_power": 0.588,
  "min_power": -0.012,
  "power_factor": 0.97
}

compute_efficiency_tool

Compute power conversion efficiency by comparing input power to output power. Designed for evaluating regulators, DC-DC converters, and similar power stages. Both input and output power are calculated as time-averaged values over the full transient simulation window.

Parameter	Type	Default	Description
raw_file_path	`str`	---	Path to `.raw` file from a transient simulation.
input_voltage_signal	`str`	---	Input voltage signal, e.g. `"V(vin)"`.
input_current_signal	`str`	---	Input current signal, e.g. `"I(Vin)"`.
output_voltage_signal	`str`	---	Output voltage signal, e.g. `"V(out)"`.
output_current_signal	`str`	---	Output current signal, e.g. `"I(Rload)"`.

Returns: A dict with efficiency_percent (output power / input power as a percentage), input_power_watts, output_power_watts, and power_dissipated_watts (input minus output, representing losses).

Example

{
  "efficiency_percent": 87.3,
  "input_power_watts": 1.44,
  "output_power_watts": 1.257,
  "power_dissipated_watts": 0.183
}