Signal Analysis Tools

analyze_waveform

Run one or more analyses on a waveform extracted from simulation results. Combines multiple measurement types in a single call to avoid repeated file parsing. Available analyses: "rms", "peak_to_peak", "settling_time", "rise_time", "fft", "thd".

Parameter	Type	Default	Description
raw_file_path	`str`	---	Path to the `.raw` file.
signal_name	`str`	---	Signal to analyze, e.g. `"V(out)"`.
analyses	`list[str]`	---	List of analysis types to run. Any combination of `"rms"`, `"peak_to_peak"`, `"settling_time"`, `"rise_time"`, `"fft"`, `"thd"`.
settling_tolerance_pct	`float`	`2.0`	Tolerance band (percent) for settling time measurement.
settling_final_value	`float \| None`	`None`	Target value for settling time. `None` uses the last sample as the final value.
rise_low_pct	`float`	`10.0`	Low threshold percentage for rise time measurement.
rise_high_pct	`float`	`90.0`	High threshold percentage for rise time measurement.
fft_max_harmonics	`int`	`50`	Maximum number of harmonic bins to return in the FFT result.
thd_n_harmonics	`int`	`10`	Number of harmonics to include in the THD calculation.

Returns: A dict keyed by signal (echoed back) plus one entry per requested analysis. The structure of each entry depends on the analysis type:

rms — a single float value.
peak_to_peak — a dict with min, max, peak_to_peak, and mean.
settling_time — a dict with settled (bool), settling_time (seconds), final_value, and tolerance_band.
rise_time — a dict with rise_time (seconds), low_value, high_value, and low_time/high_time.
fft — a dict with fundamental_freq, fundamental_magnitude, and harmonics (list of freq/magnitude/phase entries).
thd — a dict with thd_percent, fundamental_freq, and per-harmonic data.

Example — combined RMS, peak-to-peak, and settling time

{
  "signal": "V(out)",
  "rms": 3.298,
  "peak_to_peak": {
    "min": -0.012,
    "max": 4.988,
    "peak_to_peak": 5.0,
    "mean": 2.488
  },
  "settling_time": {
    "settled": true,
    "settling_time": 0.000342,
    "final_value": 4.988,
    "tolerance_band": [4.888, 5.088]
  }
}

Example — FFT analysis

{
  "signal": "V(out)",
  "fft": {
    "fundamental_freq": 1000.0,
    "fundamental_magnitude": 1.414,
    "harmonics": [
      { "harmonic": 1, "frequency": 1000.0, "magnitude": 1.414, "phase_deg": 0.0 },
      { "harmonic": 2, "frequency": 2000.0, "magnitude": 0.003, "phase_deg": 90.1 },
      { "harmonic": 3, "frequency": 3000.0, "magnitude": 0.471, "phase_deg": 0.2 }
    ]
  }
}

measure_bandwidth

Measure -3 dB bandwidth from an AC analysis result. Computes the frequency range where the signal magnitude is within 3 dB of its peak (or a specified reference level). Requires a .raw file from an .ac simulation.

Parameter	Type	Default	Description
raw_file_path	`str`	---	Path to the `.raw` file from an AC simulation.
signal_name	`str`	---	Signal to measure, e.g. `"V(out)"`.
ref_db	`float \| None`	`None`	Reference level in dB. `None` uses the peak magnitude as the reference.

Returns: A dict with bandwidth_hz (the -3 dB bandwidth), f_low (lower -3 dB frequency or null for lowpass), f_high (upper -3 dB frequency), peak_db (maximum gain in dB), and peak_freq_hz (frequency of peak gain).

Example

{
  "bandwidth_hz": 1591.5,
  "f_low": null,
  "f_high": 1591.5,
  "peak_db": -0.01,
  "peak_freq_hz": 1.0
}

get_operating_point

Extract DC operating point results from a .raw file. The .op analysis computes all node voltages and branch currents at the DC bias point, stored as a single data point. This is the starting point for verifying bias conditions before running transient or AC analysis.

Parameter	Type	Default	Description
raw_file_path	`str`	---	Path to the `.raw` file from a simulation that includes a `.op` directive.

Returns: A dict with voltages (node voltage map, e.g. {"V(out)": 2.5}), currents (branch current map, e.g. {"I(R1)": 0.00025}), device_params (any other operating point variables), and total_entries (count of all extracted values).

Example

{
  "voltages": {
    "V(vcc)": 12.0,
    "V(base)": 2.65,
    "V(collector)": 7.14,
    "V(emitter)": 1.98
  },
  "currents": {
    "I(R1)": 0.000167,
    "I(R2)": 0.000167,
    "I(Rc)": 0.002208,
    "I(Re)": 0.001983
  },
  "device_params": {},
  "total_entries": 8
}

get_transfer_function

Extract .tf (transfer function) results from a .raw file. The .tf analysis computes the DC transfer function (gain or transresistance), the input impedance at the source, and the output impedance at the output node. Requires a simulation with a .tf directive (e.g., .tf V(out) V1).

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

Returns: A dict with transfer_function (the DC gain or transresistance value), output_impedance_ohms, input_impedance_ohms, and raw_data (all variables with their original LTspice names and values).

Example — voltage gain

{
  "transfer_function": -10.0,
  "output_impedance_ohms": 999.8,
  "input_impedance_ohms": 10000.0,
  "raw_data": {
    "V(out)/V1": -10.0,
    "output_impedance_at_V(out)": 999.8,
    "input_impedance_at_V1": 10000.0
  }
}

Example — transresistance

{
  "transfer_function": 100000.0,
  "output_impedance_ohms": 0.015,
  "input_impedance_ohms": 1e-06,
  "raw_data": {
    "V(out)/I1": 100000.0,
    "output_impedance_at_V(out)": 0.015,
    "input_impedance_at_I1": 1e-06
  }
}