---
name: analyze-spectral-linearity
description: Analyze waveform spectra and linearity with backend-independent OpenADA evidence. Use for FFT setup, coherent sampling, windowing, alias folding, SFDR, harmonic distortion, HD2 or HD3, sampled-data spurs, before/after linearity comparisons, or diagnosing an untrustworthy spectral scalar while preserving exact waveform, sampling, signal-mode, and metric provenance.
---

# Analyze Spectral Linearity

Treat each spectral metric as a simulation result derived from identified
waveform evidence, not as a simulator side effect. Use `$openada:openada` for
semantic operations and normalized results; keep the exact testbench and native
waveform artifact authoritative.

## Preserve the contract layers

- Establish waveform evidence with
  `openada.operation/circuit.simulate/v1alpha2` and
  `openada.assertion/simulation.evidence.valid/v1alpha1`.
- Bind exact native vectors to a real sampled record with
  `openada.operation/result.series.extract/v1alpha1` and
  `openada.assertion/series.extraction.valid/v1alpha1`.
- Extract an implemented coherent single-tone ratio with
  `openada.operation/result.spectral.measure/v1alpha1` and
  `openada.assertion/spectral.measurement.valid/v1alpha1`.
- Use ordinary time-domain scalar algorithms through
  `openada.operation/result.measure/v1alpha2` and
  `openada.assertion/measurement.valid/v1alpha1`.
- Evaluate declared limits with
  `openada.operation/specification.evaluate/v1alpha1` and
  `openada.assertion/specification.satisfied/v1alpha1`.

Inspect installed capability records and parameter schemas before forming a
request. Use `openada profile show
openada.operation/result.spectral.measure/v1alpha1` for the packaged closed
schema. The implemented spectral alpha covers SNR, SINAD, THD, and SFDR only
for its exact coherent rectangular method. A different window, noncoherent
record, sine fit, PSD, averaging, SNDR alias, ENOB, jitter, or phase-noise
question remains **not evaluated — capability unavailable**. Never present an
ad hoc script or backend expression as a `result.spectral.measure` result.

Read [references/standards-and-methods.md](references/standards-and-methods.md)
when a metric is connected to an ADC, DAC, waveform recorder, pulse, jitter,
or IEEE standard.

## Freeze provenance and signal meaning

Record:

- exact testbench, configuration, corner, temperature, mode, stimulus, clock,
  driver, native product/version, and run/result identity;
- native waveform artifact identity and the requested transient interval;
- source signal names and whether the analyzed signal is differential,
  common-mode, single-ended, or a declared mathematical combination;
- fundamental or clock source and how its frequency was established;
- requested metric, units, included/excluded content, and specification source.

Do not reuse a frequency, edge, clock ratio, crop interval, or signal expression
from an earlier run without reconfirming it against the current baseline.

## Establish waveform evidence

Require `openada.feature/simulation.analysis.tran/v1alpha1` and request a
transient analysis covering the intended startup and observation intervals.
Treat simulation-evidence pass only as proof that valid transient evidence
exists. It does not prove uniform sampling, coherent observation, or any
spectral metric.

Derive sampling facts from the retained waveform evidence and the
`result.spectral.measure` definition. Keep these values distinct:

- requested simulator step or maximum step;
- actual waveform sample interval and sample rate;
- samples per signal or clock period;
- observation start, stop, duration, and startup crop;
- FFT length and bin spacing;
- coherent-cycle count;
- window type, parameters, coherent-gain normalization, and noise-bandwidth
  normalization where relevant;
- system oversampling ratio.

A requested maximum step is not an actual waveform sample interval.
Oversampling ratio is not samples per period or FFT length.

## Choose between the implemented and a future method

Before invoking the `result.spectral.measure` contract, declare:

1. source artifact and signal expression;
2. observation crop and handling of nonuniform samples;
3. sample rate, FFT length, bin spacing, and coherent-cycle expectation;
4. window and normalization;
5. fundamental identification rule and search region;
6. DC, fundamental-skirt, harmonic, and spur exclusion rules;
7. harmonic orders, alias-folding convention, interpolation, and output units;
8. exact metric semantics.

The implemented v1alpha1 method fixes a power-of-two record, rectangular
window, mean removal, one-sided mean-square per-bin power, no averaging, exact
coherent fundamental bin, zero-bin integration width, and fold-to-first-
Nyquist harmonics with collision rejection. For harmonic order `k`, its folding
rule is equivalent to:

```text
f_alias = abs(((k * f_fundamental + f_sample / 2) mod f_sample)
              - f_sample / 2)
```

Use the operation only when those fixed choices match the test method. Preserve
the unfolded harmonic frequency, folded frequency/bin, resolution, and
collision with excluded regions. If they do not match, request the smallest
new versioned method instead of relaxing the record.

Keep metrics distinct. HD2 and HD3 below are planning terminology only in this
release: they are not individual `result.spectral.measure/v1alpha1` outputs and
must remain **not evaluated — capability unavailable**.

- **SFDR:** ratio of the fundamental to the largest included spur.
- **HD2/HD3:** ratio of the second/third harmonic to the fundamental after the
  declared folding rule.
- **SNR:** fundamental divided by residual power after DC, fundamental, and the
  declared in-band harmonic bins are removed.
- **SINAD:** fundamental divided by every other non-DC in-band residual bin.
- **THD:** declared in-band harmonic power divided by fundamental power,
  reported as a signed dB ratio.
- **SNDR and ENOB:** not aliases or implemented derivations. Do not derive them
  unless a future installed profile names the exact relation and reference.

If the waveform is nonuniform, the crop is noncoherent, or window normalization
is unspecified, do not repair the ambiguity silently. Ask for the missing
choice or mark the `result.spectral.measure` result unknown/not evaluated as
dictated by the contract result.

## Evaluate and compare

Invoke the specification operation only for an explicit numeric bound with
units and conditions. A valid supported `result.spectral.measure` result such as
SFDR or THD without a supplied limit is a simulation result, not a specification
pass. HD2 and HD3 stay not evaluated in this release.

For a before/after comparison, hold testbench, stimulus, signal mode, crop,
sample handling, FFT length, window, normalization, exclusions, metric
definition, and PVT condition fixed. Change one hypothesis. If any required
identity differs, report a non-comparable pair instead of an improvement.

## Route status

| State | Next action |
|---|---|
| Transient evidence pass | Attempt only spectral metric kinds advertised by the installed profile |
| Series extraction pass | Confirm the actual waveform sample interval, record length, signal mode, units, and canonical series digest |
| Series extraction unknown | Repair artifact, selector, component, unit, or condition binding before any spectral calculation |
| Transient evidence fail | Diagnose the defined solver failure; no spectrum follows |
| Transient evidence unknown | Repair the waveform evidence or binding before spectral work |
| `result.spectral.measure` pass | Report the metric with its complete sampling and bin ledger |
| `result.spectral.measure` fail/unknown | Correct the declared method or source evidence; do not use a favorable plot scalar |
| `result.spectral.measure` capability unavailable | Keep the waveform valid but the metric not evaluated; propose the smallest missing primitive |
| Specification pass/fail | Scope the result to the exact metric, limit, and condition |

## Report

Return the frozen run identity, signal mode, waveform lineage, sampling ledger,
window/normalization, folded-harmonic table, metric definitions, contract status
at each layer, specifications actually evaluated, comparability limits, and one
smallest next experiment. Separate **simulation results** from **inferred**
causes and **proposed** changes. Finish with `signoff: not claimed`.