periodic_metrics
Measure period, frequency, duty cycle, pulse widths, and jitter from oscillating transient signals in LTspice simulations. Set a threshold and time window to ignore startup transients for accurate periodic metrics.
Instructions
Use for an oscillating transient signal (clock, oscillator output, switching waveform) when you need period, frequency, duty cycle, pulse widths, and period-to-period jitter.
Returns: period (mean across measured periods), frequency (1/period), jitter_rms (std-dev of period lengths — timing jitter, NOT signal amplitude variance), duty_cycle_pct, mean high/low pulse widths, edge counts. duty_cycle_pct / pulse_widths are null if no full periods could be paired. A period is the span between consecutive rising crossings, so num_periods_measured = num_rising_edges - 1 (you need N+1 edges to measure N periods).
Uses threshold crossings; threshold defaults to the midpoint of window min/max. For a signal with DC drift, set an explicit threshold — the auto midpoint moves with the drift and the edge detection gets unstable. min_periods guards against accidentally running on 1-edge windows.
Skip the startup transient via t_start/t_end; the first cycle is often wider than steady state. Rejects AC analysis. For a single edge (not periodic), use edge_metrics.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| step | No | Step index for .step sweeps | |
| t_end | No | Window end in SPICE notation | |
| format | No | 'json' or 'text' | |
| 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``. | |
| signal | Yes | Signal name (e.g. 'V(clk)') | |
| t_start | No | Window start — recommended to skip the startup transient. | |
| raw_file | No | Path to .raw transient result file. Pass this OR ``job_id`` (a job run), not both. | |
| run_index | No | 0-based run to analyze when ``job_id`` is given (default 0). | |
| threshold | No | Absolute threshold level. Auto = midpoint of window min/max. For drifting signals, set explicitly. | |
| min_periods | No | Minimum complete periods required; error if window has fewer. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| period | Yes | ||
| signal | Yes | ||
| warnings | Yes | ||
| frequency | Yes | ||
| jitter_rms | Yes | ||
| duty_cycle_pct | No | ||
| threshold_used | Yes | ||
| pulse_width_low | No | ||
| num_rising_edges | Yes | ||
| pulse_width_high | No | ||
| num_falling_edges | Yes | ||
| num_periods_measured | Yes |