specmod 0.2.0__py3-none-any.whl

specmod/core/scalogram.py

@@ -0,0 +1,234 @@
+"""The time-frequency surface a CWT produces, and the QC it makes possible.
+
+A :class:`Scalogram` is deliberately *not* an amplitude spectrum. Its ``power``
+is ``|W(a,b)|**2`` in the L2-Morlet convention, which carries units of
+``[signal]**2 * time`` — documented, but not comparable to a Fourier amplitude
+spectrum and not something to fit a source model to.
+
+The conversion happens in exactly one place, :meth:`Scalogram.time_average`,
+which applies the ``C_delta`` and ``dj*dt`` bridge and returns an ordinary
+:class:`~specmod.core.spectrum.Spectrum`. One normalisation path, one test. A
+second "already normalised" surface would be a second thing to get wrong.
+
+References
+----------
+Torrence, C. and Compo, G.P. (1998). A practical guide to wavelet analysis.
+*Bulletin of the American Meteorological Society* 79(1), 61-78.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+from .spectrum import Spectrum
+from .units import AmplitudeKind, Motion
+
+__all__ = ["Scalogram", "ScalogramQC"]
+
+
+@dataclass(frozen=True)
+class ScalogramQC:
+    """Quality checks a time-frequency surface makes possible.
+
+    An amplitude-only signal-to-noise test cannot see any of these: it collapses
+    the time axis before looking. Every field is computed and recorded rather
+    than acted on — a trace is never silently dropped, the numbers travel with
+    the result so they can be filtered downstream.
+    """
+
+    #: Lowest frequency with usable coverage outside the cone of influence.
+    #: Window length imposes this limit and nothing else in the pipeline
+    #: enforces it, so a short window can otherwise report usable bandwidth
+    #: where the transform has no support.
+    lowest_resolved_frequency: float
+
+    #: Fraction of the window free of edge effects, per frequency, summarised
+    #: as the median across the band.
+    median_coi_coverage: float
+
+    #: Normalised Gini coefficient of energy over time, in ``[0, 1]``. Near 0
+    #: is stationary; near 1 means essentially all the energy is in a handful
+    #: of samples, which is a glitch rather than an arrival.
+    temporal_concentration: float
+
+    #: Ratio of spectral energy in the first half of the window to the second.
+    #: Far from 1 suggests coda contamination, a second arrival, or a window
+    #: that started late.
+    half_window_ratio: float
+
+    def to_dict(self) -> dict[str, float]:
+        """Flat mapping, for landing in a results table as columns."""
+        return {
+            "qc_lowest_resolved_frequency": self.lowest_resolved_frequency,
+            "qc_median_coi_coverage": self.median_coi_coverage,
+            "qc_temporal_concentration": self.temporal_concentration,
+            "qc_half_window_ratio": self.half_window_ratio,
+        }
+
+
+@dataclass(frozen=True)
+class Scalogram:
+    """Full time-frequency surface from a continuous wavelet transform.
+
+    Parameters
+    ----------
+    time
+        Sample times, shape ``(n_times,)``.
+    freq
+        Fourier-equivalent frequencies, shape ``(n_scales,)``. These are true
+        Fourier frequencies via the analytic Morlet relation, not scales, so the
+        axis means the same thing as an FFT's.
+    power
+        ``|W(a,b)|**2``, shape ``(n_scales, n_times)``.
+    scales
+        Wavelet scales in seconds, shape ``(n_scales,)``. Needed by the
+        normalisation bridge, which divides by scale.
+    coi
+        Longest resolvable period at each time, shape ``(n_times,)``. A
+        frequency is inside the cone of influence where ``1/freq > coi``.
+    c_delta
+        Reconstruction constant for the wavelet actually used. Computed rather
+        than tabulated, so a non-default ``omega0`` stays correct.
+    dj
+        Spacing of the log-scale grid, in octaves.
+    """
+
+    time: NDArray[np.float64]
+    freq: NDArray[np.float64]
+    power: NDArray[np.float64]
+    scales: NDArray[np.float64]
+    coi: NDArray[np.float64]
+    c_delta: float
+    dj: float
+    dt: float
+    motion: Motion
+    meta: MappingProxyType[str, Any] = field(
+        default_factory=lambda: MappingProxyType({})
+    )
+
+    def __post_init__(self) -> None:
+        for name in ("time", "freq", "power", "scales", "coi"):
+            array = getattr(self, name)
+            array.setflags(write=False)
+
+    @property
+    def duration(self) -> float:
+        return float(self.time.size * self.dt)
+
+    def coi_mask(self) -> NDArray[np.bool_]:
+        """``True`` where a coefficient is free of edge effects."""
+        period = 1.0 / self.freq
+        return period[:, None] <= self.coi[None, :]
+
+    def coi_coverage(self) -> NDArray[np.float64]:
+        """Fraction of the window free of edge effects, per frequency.
+
+        This is the number that says whether a window is long enough to
+        constrain the low-frequency plateau, which is what sets ``Omega``.
+        """
+        coverage: NDArray[np.float64] = self.coi_mask().mean(axis=1)
+        return coverage
+
+    def time_average(self, *, mask_coi: bool = True) -> Spectrum:
+        """Collapse to an ordinary amplitude spectrum.
+
+        Applies the Torrence & Compo normalisation so that the result satisfies
+        the same Parseval contract as every other estimator: summing the
+        wavelet power over scales, weighted by ``dj*dt/C_delta`` and divided by
+        scale, returns the record's energy.
+
+        Parameters
+        ----------
+        mask_coi
+            Exclude coefficients inside the cone of influence and rescale by
+            the surviving fraction. Without this a short window reads low at
+            low frequency — precisely the band that constrains ``Omega``.
+        """
+        freq, scales = self.freq, self.scales
+        if mask_coi:
+            valid = self.coi_mask()
+            counts = valid.sum(axis=1)
+            # A scale with no edge-free sample is not measured by this record.
+            # Dropping it is the honest answer: emitting zero would read as "no
+            # energy here" rather than "no measurement here", and would take a
+            # log-space fit to -inf. The axis therefore depends on record
+            # length, exactly as the cone of influence says it must.
+            usable = counts > 0
+            if not usable.any():
+                raise ValueError(
+                    f"No frequency in {freq.min():.3g}-{freq.max():.3g} Hz is "
+                    f"free of edge effects over a {self.duration:.3g} s record. "
+                    f"The window is too short for this scale range; raise "
+                    f"f_min, lengthen the window, or pass mask_coi=False to "
+                    f"accept edge-contaminated coefficients."
+                )
+            freq, scales = freq[usable], scales[usable]
+            counts = counts[usable]
+            summed = (self.power * valid).sum(axis=1)[usable]
+            # Rescale the survivors up to the full window length, so masking
+            # changes the variance of the estimate rather than its level.
+            summed = summed * self.time.size / counts
+        else:
+            summed = self.power.sum(axis=1)
+
+        # Torrence & Compo eq. 14: the scale sum of |W|**2 / s, times
+        # dj*dt/C_delta, recovers the variance. Multiplying by dt again turns
+        # variance into energy, matching sum(x**2)*dt.
+        energy_per_scale = summed / scales * (self.dj * self.dt / self.c_delta)
+        energy_per_scale = energy_per_scale * self.dt
+
+        # The scale grid is logarithmic, so each frequency bin subtends
+        # df = f * ln(2) * dj. Spreading each scale's energy over its own bin
+        # gives a density on a frequency axis.
+        bin_width = freq * np.log(2.0) * self.dj
+        psd = energy_per_scale / (bin_width * self.duration)
+
+        # Ascending frequency, matching every other estimator's axis.
+        order = np.argsort(freq)
+        spectrum = Spectrum(
+            freq=np.ascontiguousarray(freq[order]),
+            amp=np.ascontiguousarray(psd[order]),
+            motion=self.motion,
+            kind=AmplitudeKind.PSD,
+            duration=self.duration,
+            sampling_rate=1.0 / self.dt,
+            meta=MappingProxyType({**dict(self.meta), "coi_masked": mask_coi}),
+        )
+        return spectrum.to_kind(AmplitudeKind.FAS)
+
+    def qc(self) -> ScalogramQC:
+        """Compute the §4.4.2 checks."""
+        coverage = self.coi_coverage()
+        resolved = self.freq[coverage > 0.5]
+        lowest = float(resolved.min()) if resolved.size else float(self.freq.max())
+
+        # Energy over time, summed across the band, as a Gini coefficient.
+        over_time = self.power.sum(axis=0)
+        total = float(over_time.sum())
+        if total > 0:
+            sorted_energy = np.sort(over_time)
+            n = sorted_energy.size
+            index = np.arange(1, n + 1)
+            gini = float(
+                (2.0 * (index * sorted_energy).sum()) / (n * sorted_energy.sum())
+                - (n + 1.0) / n
+            )
+        else:
+            gini = 0.0
+
+        half = self.time.size // 2
+        first = float(self.power[:, :half].sum())
+        second = float(self.power[:, half:].sum())
+        ratio = first / second if second > 0 else np.inf
+
+        return ScalogramQC(
+            lowest_resolved_frequency=lowest,
+            median_coi_coverage=float(np.median(coverage)),
+            temporal_concentration=gini,
+            half_window_ratio=ratio,
+        )

specmod/core/spectrum.py

@@ -0,0 +1,326 @@
+"""The :class:`Spectrum` container.
+
+Immutable, self-describing, and normalisation-aware. Every operation returns a
+new object rather than mutating in place, so a spectrum cannot be silently
+integrated twice — the pre-refactor ``Spectrum.integrate()`` mutated, and its
+only inverse was ``differentiate()``, which is neither exact nor recorded.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field, replace
+from types import MappingProxyType
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+from .units import AmplitudeKind, Motion
+
+__all__ = ["Spectrum"]
+
+#: Tolerance on the derived sample count. ``duration`` is ``n * dt`` and
+#: ``sampling_rate`` is ``1 / dt``, so their product is ``n`` exactly up to
+#: floating-point representation — anything further out is a real mismatch,
+#: not rounding.
+_SAMPLE_COUNT_TOL = 1e-6
+
+
+def _validate_record_geometry(
+    freq: NDArray[np.float64], duration: float, sampling_rate: float
+) -> None:
+    """Check the three quantities every correction is built on agree.
+
+    Sample count, duration and sampling rate are not independent: ``duration =
+    n * dt`` and ``sampling_rate = 1 / dt``, so any two determine the third and
+    the frequency axis they imply. Every normalisation in this package — the
+    ``2T`` between amplitude and power, the fold at DC and Nyquist, the taper
+    corrections, the wavelet scale grid — is a function of them.
+
+    That makes an inconsistent triple the most dangerous thing a caller can
+    construct: it produces a spectrum that is wrong by a clean factor
+    everywhere, which looks like a plausible spectrum and survives every check
+    that inspects shape rather than scale. Catching it here is cheap; catching
+    it downstream has historically meant noticing that a magnitude looks odd.
+    """
+    implied = duration * sampling_rate
+    if abs(implied - round(implied)) > _SAMPLE_COUNT_TOL * max(1.0, implied):
+        raise ValueError(
+            f"duration={duration} s at {sampling_rate} Hz implies "
+            f"{implied} samples, which is not a whole number. These are not "
+            f"independent: duration = n_samples / sampling_rate. One of them "
+            f"is wrong, and every amplitude conversion depends on both."
+        )
+
+    if freq.size == 0:
+        return
+    if freq[0] < 0.0:
+        raise ValueError(f"frequencies must be non-negative, got {freq.min()}")
+    if freq.size > 1 and not np.all(np.diff(freq) > 0):
+        raise ValueError(
+            "freq must be strictly increasing; band() and the smoothers both "
+            "assume it, and an unsorted axis integrates to nonsense"
+        )
+
+    nyquist = sampling_rate / 2.0
+    if freq[-1] > nyquist * (1.0 + 1e-9):
+        raise ValueError(
+            f"frequency axis reaches {freq[-1]} Hz but the Nyquist frequency "
+            f"for {sampling_rate} Hz sampling is {nyquist} Hz. Either "
+            f"sampling_rate is wrong or the axis does not belong to this "
+            f"record; energy() would silently integrate over a band the "
+            f"record cannot represent."
+        )
+
+
+@dataclass(frozen=True)
+class Spectrum:
+    """A one-sided spectrum that knows its own units.
+
+    Parameters
+    ----------
+    freq
+        Frequency axis in Hz, strictly increasing, excluding DC by default.
+    amp
+        Amplitude in whatever :attr:`kind` declares.
+    motion
+        Ground-motion domain.
+    kind
+        What ``amp`` represents.
+    duration
+        **Physical** record duration in seconds, ``n_samples * dt``. Carried
+        explicitly because every conversion between kinds needs it and it
+        cannot be recovered from ``len(freq)`` once padding is involved.
+    sampling_rate
+        Samples per second of the source record, in Hz.
+    meta
+        Arbitrary trace metadata. Stored read-only so a shared mapping cannot be
+        mutated through one spectrum and observed through another.
+    """
+
+    freq: NDArray[np.float64]
+    amp: NDArray[np.float64]
+    motion: Motion
+    kind: AmplitudeKind
+    duration: float
+    sampling_rate: float
+    meta: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        freq = np.ascontiguousarray(self.freq, dtype=np.float64)
+        amp = np.ascontiguousarray(self.amp, dtype=np.float64)
+        if freq.ndim != 1 or amp.ndim != 1:
+            raise ValueError("freq and amp must be one-dimensional")
+        if freq.shape != amp.shape:
+            raise ValueError(
+                f"freq and amp must be the same length, got "
+                f"{freq.shape[0]} and {amp.shape[0]}"
+            )
+        if self.duration <= 0:
+            raise ValueError(f"duration must be positive, got {self.duration}")
+        if self.sampling_rate <= 0:
+            raise ValueError(
+                f"sampling_rate must be positive, got {self.sampling_rate}"
+            )
+        _validate_record_geometry(freq, self.duration, self.sampling_rate)
+        freq.setflags(write=False)
+        amp.setflags(write=False)
+        object.__setattr__(self, "freq", freq)
+        object.__setattr__(self, "amp", amp)
+        object.__setattr__(self, "motion", Motion(self.motion))
+        object.__setattr__(self, "kind", AmplitudeKind(self.kind))
+        object.__setattr__(self, "meta", MappingProxyType(dict(self.meta)))
+
+    def __reduce__(self) -> tuple[Any, tuple[Any, ...]]:
+        """Rebuild through ``__init__`` rather than by restoring ``__dict__``.
+
+        ``meta`` is a :class:`~types.MappingProxyType`, which is the right
+        thing for an immutable spectrum and **is not picklable**. Without this
+        the whole container tree — a ``SpectrumPair``, a ``SpectrumSet``, an
+        event — could not be written to disk at all, which was found the moment
+        the legacy pickle I/O was removed and there was nothing left to
+        persist a result with.
+
+        Reconstructing through the constructor also re-freezes the arrays.
+        ``numpy`` restores a pickled array as writeable, so a spectrum
+        round-tripped by any other route would come back mutable and quietly
+        lose the guarantee it exists to make.
+        """
+        return (
+            self.__class__,
+            (
+                self.freq,
+                self.amp,
+                self.motion,
+                self.kind,
+                self.duration,
+                self.sampling_rate,
+                dict(self.meta),
+            ),
+        )
+
+    # ------------------------------------------------------------------ units
+
+    @property
+    def unit(self) -> str:
+        """Unit string, e.g. ``m/s*s`` for a velocity FAS."""
+        return self.kind.unit(self.motion)
+
+    @property
+    def n_samples(self) -> int:
+        """Samples in the source record, ``duration * sampling_rate``.
+
+        The third of the triple, derived rather than stored so it cannot
+        disagree with the other two. Validated on construction — see
+        :func:`_validate_record_geometry` for why that matters.
+
+        Note this is the *record* length, not ``len(freq)``. Zero-padding
+        changes the second and not the first, and confusing them is the §2.2
+        bug.
+        """
+        return round(self.duration * self.sampling_rate)
+
+    @property
+    def nyquist(self) -> float:
+        return self.sampling_rate / 2.0
+
+    @property
+    def frequency_resolution(self) -> float:
+        """``1/T`` — the narrowest frequency difference the record can resolve.
+
+        This is the low-frequency floor the SNR bandwidth search must respect;
+        nothing enforced it before, so a short window could report usable
+        bandwidth below what it could physically resolve.
+        """
+        return 1.0 / self.duration
+
+    def to_kind(self, kind: AmplitudeKind | str) -> Spectrum:
+        """Convert between FAS, MAGNITUDE, PSD and ASD.
+
+        Conversions go via FAS rather than being enumerated pairwise, so the
+        factors of ``2T`` and of the fold each live in exactly one place.
+
+        ``MAGNITUDE`` is the conversion to reach for when reading a long-period
+        level: ``Omega`` is defined on ``|X|``, not on the folded ``FAS``, and
+        the two differ by two. Asking for it by name is the point — the factor
+        is easy to apply by hand and easy to apply twice, or not at all.
+        """
+        target = AmplitudeKind(kind)
+        if target is self.kind:
+            return self
+        fas = self._to_fas()
+        if target is AmplitudeKind.FAS:
+            return fas
+        if target is AmplitudeKind.MAGNITUDE:
+            # Undo the fold: FAS carries the negative-frequency half, |X| does not.
+            return replace(fas, amp=fas.amp / self._fold_factor(), kind=target)
+        two_t = 2.0 * self.duration
+        if target is AmplitudeKind.PSD:
+            amp = fas.amp**2 / two_t
+        else:  # ASD
+            amp = fas.amp / np.sqrt(two_t)
+        return replace(fas, amp=amp, kind=target)
+
+    def _fold_factor(self) -> NDArray[np.float64]:
+        """Per-bin ratio between the folded ``FAS`` and the unfolded ``|X|``.
+
+        Two everywhere except DC and Nyquist, which have no negative-frequency
+        twin to fold in — a real signal's transform is conjugate-symmetric, and
+        those two bins are their own mirror image. A blanket factor of two is
+        therefore wrong at both ends, by exactly two.
+
+        **Parity matters here.** An ``rfft`` of an even-length record ends
+        exactly on Nyquist; an odd-length one ends half a bin below it, at
+        ``fs/2 * (n-1)/n``, and that bin *does* have a twin and *is* folded. So
+        which bins are special depends on the record length as well as on
+        ``drop_dc``, and is read off the axis rather than assumed.
+
+        The tolerance is derived from the axis's own bin spacing rather than
+        being a fixed relative one. For an odd-length record the top bin sits
+        ``df/2`` below Nyquist, and ``df`` shrinks as the record lengthens — so
+        a fixed ``rtol`` eventually swallows the gap and folds that bin wrongly.
+        With ``numpy``'s default it does so from about 200000 samples, which at
+        1000 Hz is a 200 s record. Scaling with ``df`` keeps the two cases
+        separated at any length.
+        """
+        factor = np.full(self.freq.shape, 2.0)
+        if self.freq.size == 0:
+            return factor
+        # A hundredth of the narrowest spacing: far tighter than the df/2 gap
+        # that separates an odd-length top bin from Nyquist, and far looser
+        # than floating-point error on an even-length one, which lands exactly.
+        spacing = float(np.min(np.diff(self.freq))) if self.freq.size > 1 else 0.0
+        tol = 0.01 * spacing if spacing > 0 else 1e-12
+        factor[self.freq < tol] = 1.0
+        factor[np.abs(self.freq - self.nyquist) < tol] = 1.0
+        return factor
+
+    def _to_fas(self) -> Spectrum:
+        if self.kind is AmplitudeKind.FAS:
+            return self
+        if self.kind is AmplitudeKind.MAGNITUDE:
+            return replace(
+                self, amp=self.amp * self._fold_factor(), kind=AmplitudeKind.FAS
+            )
+        two_t = 2.0 * self.duration
+        if self.kind is AmplitudeKind.PSD:
+            amp = np.sqrt(self.amp * two_t)
+        else:  # ASD
+            amp = self.amp * np.sqrt(two_t)
+        return replace(self, amp=amp, kind=AmplitudeKind.FAS)
+
+    def to_motion(self, motion: Motion | str) -> Spectrum:
+        """Integrate or differentiate to another ground-motion domain.
+
+        Multiplies by ``(2*pi*f)`` per order of differentiation. Only valid on
+        an amplitude-like kind, so a PSD is converted to FAS, transformed, and
+        converted back — squaring the frequency factor would otherwise be
+        silently wrong.
+        """
+        target = Motion(motion)
+        if target is self.motion:
+            return self
+        if self.kind is not AmplitudeKind.FAS:
+            return self.to_kind(AmplitudeKind.FAS).to_motion(target).to_kind(self.kind)
+        order = target.derivative_order - self.motion.derivative_order
+        factor = (2.0 * np.pi * self.freq) ** order
+        return replace(self, amp=self.amp * factor, motion=target)
+
+    # ------------------------------------------------------------- operations
+
+    def band(self, fmin: float | None = None, fmax: float | None = None) -> Spectrum:
+        """Restrict to a frequency band, inclusive of both bounds."""
+        mask = np.ones(self.freq.shape, dtype=bool)
+        if fmin is not None:
+            mask &= self.freq >= fmin
+        if fmax is not None:
+            mask &= self.freq <= fmax
+        if not mask.any():
+            raise ValueError(
+                f"No samples in band [{fmin}, {fmax}] Hz; spectrum spans "
+                f"[{self.freq[0]:.4g}, {self.freq[-1]:.4g}] Hz."
+            )
+        return replace(self, freq=self.freq[mask], amp=self.amp[mask])
+
+    def energy(self) -> float:
+        """Total signal energy, ``sum(x^2) * dt``, recovered from the spectrum.
+
+        This is the quantity Parseval's theorem ties to the time domain, and it
+        is what the cross-estimator normalisation test asserts. For a one-sided
+        FAS the two-sided integral folds to ``integral of A^2 / 2 df``.
+        """
+        fas = self.to_kind(AmplitudeKind.FAS)
+        return float(np.trapezoid(fas.amp**2 / 2.0, fas.freq))
+
+    def __len__(self) -> int:
+        return int(self.freq.size)
+
+    def __repr__(self) -> str:
+        sid = self.meta.get("id", "")
+        where = f" {sid}" if sid else ""
+        return (
+            f"Spectrum({self.kind.value}, {self.motion.value},{where} "
+            f"n={len(self)}, {self.freq[0]:.3g}-{self.freq[-1]:.3g} Hz, "
+            f"T={self.duration:.4g} s, [{self.unit}])"
+        )

specmod/core/units.py

@@ -0,0 +1,116 @@
+"""Physical units and domains, as types rather than conventions.
+
+The pre-refactor code tracked none of this. A ``Spectrum`` did not know whether
+it held power or amplitude, nor whether it was in displacement, velocity or
+acceleration; that lived in ``Models.MOTION``, a module global read at import
+time which the user had to keep in sync by hand with however many times they
+had called ``.inte()`` or ``.diff()``. Getting it wrong returned a wrong seismic
+moment with no error anywhere.
+
+Making both a typed attribute turns those silent factor errors into exceptions.
+
+Conventions
+-----------
+The canonical amplitude kind is the **folded** one-sided Fourier amplitude
+spectrum (:attr:`AmplitudeKind.FAS`), in units of ``[signal] * s``. "Folded"
+means the negative-frequency half has been added in, so ``FAS = 2|X|`` where
+``X`` is the Fourier transform. That is what makes energy recoverable by
+integrating over non-negative frequencies alone, and it is why every estimator
+here can be held to one Parseval check.
+
+**It is not the quantity the source model is written in.** Omega, the
+long-period spectral level, is the plateau of ``|X|`` — at zero frequency
+``|X(0)| = |integral u dt|``, which is what ``M0`` is proportional to. Reading
+``FAS`` as Omega puts ``M0`` out by two, which is 0.2 magnitude units. Use
+:attr:`AmplitudeKind.MAGNITUDE` for that, and let :meth:`Spectrum.to_kind`
+apply the factor rather than doing it by hand.
+
+Relationships between the kinds, for a record of duration ``T``:
+
+=============  ========================  ==================================
+Kind           Units                     From FAS ``A``
+=============  ========================  ==================================
+``FAS``        ``[x] * s``               --
+``MAGNITUDE``  ``[x] * s``               ``|X| = A / 2``
+``PSD``        ``[x]^2 / Hz``            ``P = A^2 / (2 T)``
+``ASD``        ``[x] / sqrt(Hz)``        ``D = A / sqrt(2 T)``
+=============  ========================  ==================================
+
+Parseval takes a different form in each amplitude convention, which is the
+whole reason both are named here rather than left to the caller::
+
+    E = integral A**2 / 2 df        (FAS, folded)
+    E = 2 * integral |X|**2 df      (MAGNITUDE, unfolded)
+
+``T`` is the **physical record duration**, ``n_samples * dt``. It is never
+inferred from the length of the frequency axis: zero-padding changes that length
+while leaving the duration alone, which is precisely how the old
+``psd_to_amp`` acquired a padding-dependent error.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+__all__ = ["AmplitudeKind", "Motion"]
+
+
+class Motion(StrEnum):
+    """Ground-motion domain of a time series or spectrum."""
+
+    DISPLACEMENT = "displacement"
+    VELOCITY = "velocity"
+    ACCELERATION = "acceleration"
+
+    @property
+    def derivative_order(self) -> int:
+        """Order of time differentiation relative to displacement.
+
+        Converting between domains multiplies the spectrum by ``(2*pi*f)`` per
+        order, so the difference of two orders gives the exponent directly.
+        """
+        return {"displacement": 0, "velocity": 1, "acceleration": 2}[self.value]
+
+    @property
+    def unit(self) -> str:
+        """SI unit of the time-domain signal."""
+        return {"displacement": "m", "velocity": "m/s", "acceleration": "m/s^2"}[
+            self.value
+        ]
+
+
+class AmplitudeKind(StrEnum):
+    """What the amplitude axis of a spectrum represents."""
+
+    #: Folded one-sided Fourier amplitude spectrum, ``2|X|``, in ``[x] * s``.
+    #: Energy is ``integral(FAS**2 / 2) df``. The default, because it is the
+    #: convention in which one Parseval check covers every estimator.
+    FAS = "fas"
+    #: Unfolded Fourier transform magnitude, ``|X| = |rfft(x)| * dt``, in
+    #: ``[x] * s``. **This is the one Omega is defined in**, and the one to
+    #: read a long-period spectral level off. Energy is
+    #: ``2 * integral(|X|**2) df``.
+    MAGNITUDE = "magnitude"
+    #: One-sided power spectral density, ``[x]^2 / Hz``.
+    PSD = "psd"
+    #: One-sided amplitude spectral density, ``[x] / sqrt(Hz)``.
+    ASD = "asd"
+
+    @property
+    def is_amplitude(self) -> bool:
+        """Whether this kind scales linearly with the record.
+
+        The distinction that matters for :meth:`Spectrum.to_motion`: applying
+        a ``2*pi*f`` factor to a squared quantity is wrong by ``2*pi*f`` again.
+        """
+        return self in (AmplitudeKind.FAS, AmplitudeKind.MAGNITUDE, AmplitudeKind.ASD)
+
+    def unit(self, motion: Motion) -> str:
+        """Full unit string for this kind in a given motion domain."""
+        base = motion.unit
+        return {
+            "fas": f"{base}*s",
+            "magnitude": f"{base}*s",
+            "psd": f"({base})^2/Hz",
+            "asd": f"{base}/sqrt(Hz)",
+        }[self.value]