pygspice 2.0.0__py3-none-any.whl

gspice/__init__.py

@@ -0,0 +1,80 @@
+"""Gaussian pixelwise conditional estimation for spectra."""
+
+import logging
+import warnings
+from typing import TYPE_CHECKING, Any
+
+from . import legacy
+from ._blocks import fit_blocks
+from ._datasets import Simulation, simulate
+from ._diagnostics import Calibration, calibration, finite_sample_factor, noise_audit
+from ._model import Blocks, LowRank, Model, fit, load, save
+from ._predict import Prediction, Repaired, infill, pixelwise
+from ._repair import repair
+from ._spectra import scale, snr, unscale
+
+# Without a handler, Python prints the records of level WARNING and above to stderr.
+# With one, the application decides where they go.
+logging.getLogger("gspice").addHandler(logging.NullHandler())
+
+__version__ = "2.0.0"
+
+__all__ = [
+    "Blocks",
+    "Calibration",
+    "LowRank",
+    "Model",
+    "Prediction",
+    "Repaired",
+    "Simulation",
+    "calibration",
+    "finite_sample_factor",
+    "fit",
+    "fit_blocks",
+    "infill",
+    "legacy",
+    "load",
+    "noise_audit",
+    "pixelwise",
+    "repair",
+    "save",
+    "scale",
+    "simulate",
+    "snr",
+    "unscale",
+]
+
+# The 2022 names that gspice no longer defines, with their replacements in the new API
+# (design section 7.2). None: the function has no replacement outside gspice.legacy.
+_REPLACEMENT = {
+    "standard_scale": "scale",
+    "covar": "fit",
+    "covar_iter_mask": "fit",
+    "get_chimask": "pixelwise",
+    "gp_interp": "pixelwise",
+    "gaussian_estimate": "infill",
+    "cholesky_inv": None,
+    "submatrix_inv": None,
+    "submatrix_inv_mult": None,
+    "maskinterp1": None,
+    "maskinterp": None,
+}
+
+
+# PEP 562: gspice.<name> of a 2022 name returns gspice.legacy.<name> with a
+# DeprecationWarning. Type checkers do not see the hook, so they report a misspelled or
+# deprecated name instead of typing every attribute of gspice as Any.
+if not TYPE_CHECKING:
+
+    def __getattr__(name: str) -> Any:
+        if name not in _REPLACEMENT:
+            raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+        use = f"gspice.legacy.{name}"
+        if replacement := _REPLACEMENT[name]:
+            use = f"gspice.{replacement}, or {use} to keep the 2022 results"
+        warnings.warn(
+            f"gspice.{name} is deprecated and will be removed in 3.0.0. Use {use}.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return getattr(legacy, name)

gspice/_blocks.py

@@ -0,0 +1,308 @@
+import logging
+import math
+import time
+from fractions import Fraction
+from typing import Any, NamedTuple
+
+import numpy as np
+from numpy.linalg import LinAlgError
+from numpy.typing import ArrayLike, NDArray
+from scipy.linalg import lapack
+
+from ._linalg import factor_pattern, factor_prior
+from ._model import NGUARD_MAX, Blocks, Model, submatrix_of
+from ._predict import filled, noisy, spans, validated, working
+from ._spectra import (
+    Integer,
+    Progress,
+    Real,
+    check_progress,
+    integer,
+    real,
+    to_flux,
+    to_working,
+)
+
+_logger = logging.getLogger("gspice")
+
+
+def fit_blocks(
+    model: Model,
+    flux: ArrayLike,
+    ivar: ArrayLike,
+    mask: ArrayLike | None = None,
+    *,
+    width: Integer = 150,
+    stride: Integer = 75,
+    nguard: Integer = 20,
+    percentile: Real = 99.9,
+    progress: Progress | None = None,
+) -> Model:
+    r"""Return the model with block thresholds from clean spectra.
+
+    Block :math:`j` holds the ``width`` pixels from ``starts[j]``. The starts are 0,
+    ``stride``, 2 ``stride`` and so on, up to npix − ``width``. If the last of them is
+    smaller than npix − ``width``, the start npix − ``width`` follows. The defaults
+    give 31 blocks at npix 2400. fit_blocks first replaces the bad pixels by their
+    conditional mean, as `infill` does. It does not detect outliers by z.
+
+    Take a spectrum in S/N bin :math:`b`, with :math:`x` the working vector of its
+    infilled flux (see `Model`) and :math:`P` the inverse of ``cov[b]``. Let :math:`A`
+    be a block, :math:`G` the pixels within ``nguard`` of :math:`A`, clipped at the
+    ends, and :math:`O` the pixels outside :math:`G`. Then
+
+    .. math::
+
+        \chi^2_A = \frac{r_A^\mathsf{T} C_{AA}^{-1} r_A}{|A|}, \qquad r_A = x_A - \mu_A,
+
+    where :math:`\mu_A` and :math:`C_{AA} = (P_{GG}^{-1})_{AA}` are the conditional mean
+    and covariance of :math:`x_A` given :math:`x_O`. The guard pixels
+    :math:`G \setminus A` are thus marginalized. Where :math:`G` covers all pixels,
+    :math:`\mu_A` and :math:`C_{AA}` are those of the prior, 0 and ``cov[b]`` at
+    :math:`A`, computed without :math:`P`.
+
+    ``thresholds[b, j]`` is ``np.percentile`` (linear) of :math:`\chi^2_A` of block
+    :math:`j`, at :math:`p` = ``percentile``, over the :math:`m` spectra of bin
+    :math:`b`. A block without an artifact then exceeds its threshold with the
+    probability
+
+    .. math::
+
+        \frac{m (1 - p/100) + p/100}{m + 1}
+
+    if :math:`(m - 1) p/100` is an integer. Otherwise the probability is at most this
+    value, for a density that falls beyond the threshold. For :math:`p = 99.9`, it is
+    0.20% at :math:`m = 1000` and 0.12% at :math:`m = 5000`. `repair` also infills the
+    pixels that z flags, which lowers this rate. Use clean held-out spectra.
+
+    For a noise-aware model, :math:`x` is in flux units. The covariance :math:`C_s` of
+    each spectrum (see `Model`) then replaces ``cov[b]`` in its infill and its blocks.
+
+    Parameters
+    ----------
+    model : Model
+        The model.
+    flux, ivar, mask : array_like, shape (nspec, npix)
+        As in `scale`, with the npix of ``model``. Clean spectra, with at least
+        :math:`m` spectra in each bin such that :math:`m (100 - p) \ge 100`. The check
+        reads :math:`p` as the decimal ``Fraction(str(p))``: 1000 spectra at
+        :math:`p = 99.9`.
+    width : int, optional
+        The number of pixels per block, :math:`|A|`; from 1 to npix.
+    stride : int, optional
+        The distance between the starts of consecutive blocks (pixels); 1 or more.
+    nguard : int, optional
+        The half-width of the guard window around each block (pixels); from 0 to
+        :math:`2^{63} - 1`, as for `Blocks`.
+    percentile : float, optional
+        The percentile :math:`p` of the thresholds; :math:`0 < p < 100`.
+    progress : callable, optional
+        ``progress(stage, done, total)``, called after each chunk of spectra, with the
+        stage ``"fit_blocks"``, the number of spectra done and their total. For a
+        noise-aware model, a chunk is one spectrum.
+
+    Returns
+    -------
+    Model
+        A new model, equal to ``model`` except for ``blocks``: a `Blocks` that holds the
+        starts, width, nguard and thresholds.
+
+    Raises
+    ------
+    TypeError
+        If ``model`` is not a Model, or ``width``, ``stride`` or ``nguard`` is not an
+        integer. If ``percentile`` is not a real number, or ``progress`` is not callable
+        or None. If ``flux``, ``ivar`` or ``mask`` has a dtype that `scale` does not
+        allow.
+    ValueError
+        If ``flux``, ``ivar`` or ``mask`` has a shape or a value that `scale` does not
+        allow. If ``flux`` has another npix than ``model``, or a spectrum has no good
+        pixel. If ``width``, ``stride``, ``nguard`` or ``percentile`` is outside its
+        range. If a bin has fewer spectra than :math:`p` needs; the message names the
+        bin and its count. If a threshold is not finite or is 0, as for spectra equal to
+        their conditional mean.
+    numpy.linalg.LinAlgError
+        If the covariance of a bin fails the check of its precision matrix, as in
+        `pixelwise`, and the :math:`G` of a block does not cover all pixels.
+        If :math:`P_{GG}` of a block is not positive definite. If ``cov[b]`` at
+        :math:`T = A` fails that check, for a block whose :math:`G` covers all pixels.
+        Also as in `infill`, for the bad pixels. The message names the bin, and the
+        block or the row of a pattern. For a noise-aware model, as in `infill`, with
+        :math:`C_s` in place of ``cov[b]``.
+
+    Notes
+    -----
+    Cost:
+
+    - :math:`\mathrm{npix}^3` flops for :math:`P` at the first use of a bin, then
+      :math:`|G|^3/3` flops per bin and block.
+    - About :math:`2\,\mathrm{npix}^2 + \sum_A |G|^2` flops per spectrum, plus the
+      `infill` of the bad pixels, of the mean only.
+    - The factors of all bins take :math:`\mathrm{nbin} \sum_A |G|^2 \times 8` bytes
+      during the scan: 8.8 MB per bin at npix 2400 with the defaults, and 649 MB at
+      ``stride=1``.
+    - Beyond the inputs, and their float64 copies if they are long double, fit_blocks
+      holds a bool array of the input shape. It also holds the :math:`\chi^2_A` of the
+      spectra of one bin (nblock float64 per spectrum), and a few float64 arrays of one
+      chunk of ``max(1, 2**24 // npix)`` spectra.
+    - The new model shares the arrays of ``model``, its precision matrices and its guard
+      weights (see `Model`).
+    - Unless every block covers all pixels with its guard, a noise-aware model forms
+      :math:`P_s` and the factors of the blocks for each spectrum. :math:`P_s` takes
+      :math:`\mathrm{npix}^3` flops for a dense ``cov[0]``, or :math:`\mathrm{npix}^2 K`
+      for a `LowRank` of rank :math:`K`. Otherwise the infill of the bad pixels forms no
+      :math:`P_s`, and costs as in `infill`.
+    """
+    start = time.perf_counter()
+    width = integer(width, "width", 1)
+    stride = integer(stride, "stride", 1)
+    nguard = integer(nguard, "nguard", 0, NGUARD_MAX)
+    percentile = real(percentile, "percentile")
+    if not 0 < percentile < 100:
+        raise ValueError(
+            f"percentile: expected a number > 0 and < 100, got {percentile}"
+        )
+    check_progress(progress)
+    flux, ivar, bad = validated(model, flux, ivar, mask, inflate=False)
+    nspec, npix = flux.shape
+    if width > npix:
+        raise ValueError(
+            f"width: expected an integer <= {npix}, the pixels of model, got {width}"
+        )
+    nbin = len(model.cov)
+    bins = model._bins(flux, ivar, bad)
+    # Decision A7, in exact arithmetic with the decimal that prints as percentile: in
+    # float arithmetic, 99.9 would need 1001 spectra.
+    p = Fraction(str(percentile))
+    for b, m in enumerate(np.bincount(bins, minlength=nbin).tolist()):
+        if m * (100 - p) < 100:
+            raise ValueError(
+                f"fit_blocks: percentile {percentile} needs at least "
+                f"{math.ceil(100 / (100 - p))} spectra in each S/N bin, got {m} in "
+                f"bin {b}"
+            )
+    # A stride above npix gives the starts of npix, and keeps arange in int64.
+    starts = np.append(np.arange(0, npix - width, min(stride, npix)), npix - width)
+    # The factors of every bin, and P of the bins with bad pixels for their infill,
+    # before any spectrum, so that a covariance that fails a check raises at once. A
+    # noise model forms them for each spectrum.
+    factors: list[list[BlockFactor]] = []
+    if not model.noise:
+        factors = [block_factors(model, b, starts, width, nguard) for b in range(nbin)]
+        for b in np.unique(bins[bad.any(axis=1)]).tolist():
+            model._precision(b)
+    thresholds = np.empty((nbin, starts.size))
+    done = 0
+    for b in range(nbin):
+        rows = np.flatnonzero(bins == b)
+        chi2 = np.empty((rows.size, starts.size))
+        for c in spans(model, rows.size, npix):
+            spectra = rows[c]
+            cover = (
+                noisy(model, ivar[spectra], bad[spectra], int(spectra[0]))
+                if model.noise
+                else model
+            )
+            F = (
+                block_factors(cover, 0, starts, width, nguard)
+                if model.noise
+                else factors[b]
+            )
+            X = _scan_vectors(model, cover, b, flux, ivar, bad, spectra)
+            chi2[c] = block_chi2(F, X)
+            del cover, F
+            done += spectra.size
+            if progress is not None:
+                progress("fit_blocks", done, nspec)
+        thresholds[b] = np.percentile(chi2, percentile, axis=0)
+    _logger.debug(
+        "fit_blocks: %d spectra, %d blocks in %.3f s",
+        nspec,
+        starts.size,
+        time.perf_counter() - start,
+    )
+    return model._with_blocks(Blocks(starts, width, nguard, thresholds))
+
+
+def _scan_vectors(
+    model: Model,
+    cover: Model,
+    b: int,
+    flux: NDArray[Any],
+    ivar: NDArray[Any],
+    bad: NDArray[np.bool_],
+    spectra: NDArray[np.intp],
+) -> NDArray[np.float64]:
+    # The working vectors x of the infilled flux of the spectra of bin b, under the
+    # covariance of cover.
+    bins = np.full(spectra.size, b)
+    G = bad[spectra]
+    X, a = working(model, flux[spectra], ivar[spectra], G, bins)
+    X = filled(cover, X, bins, spectra, G, G)
+    # Through flux units, as the docstring of fit_blocks defines x.
+    center = 0.0 if model.center is None else model.center
+    x = np.array(flux[spectra], dtype=np.float64)
+    to_flux(X, a, model.mean[b], center, out=X)
+    x[G] = X[G]
+    to_working(x, a, center, model.mean[b])
+    return x
+
+
+class BlockFactor(NamedTuple):
+    # Block A and G, the pixels within nguard of A clipped at the ends; order lists the
+    # pixels of G, counted from G.start, as (G \ A, A). R is the lower Cholesky factor
+    # of P_GG in that order, with P the precision matrix of the bin. Where G covers all
+    # pixels, P is None and R is the factor of C_AA, the prior (design section 4.2).
+    A: slice
+    G: slice
+    order: NDArray[np.intp]
+    R: NDArray[np.float64]
+    P: NDArray[np.float64] | None
+
+
+def block_factors(
+    model: Model, b: int, starts: NDArray[np.int64], width: int, nguard: int
+) -> list[BlockFactor]:
+    npix = model.mean.shape[1]
+    factors = []
+    # Python integers, so that a large nguard cannot overflow.
+    for k, start in enumerate(starts.tolist()):
+        A = slice(start, start + width)
+        G = slice(max(start - nguard, 0), min(start + width + nguard, npix))
+        order = np.r_[G.start : A.start, A.stop : G.stop, A] - G.start
+        P = None if G.stop - G.start == npix else model._precision(b)
+        try:
+            if P is None:
+                R = factor_prior(submatrix_of(model.cov[b], np.arange(A.start, A.stop)))
+            else:
+                R = factor_pattern(P[G, G][np.ix_(order, order)])
+        except LinAlgError as error:
+            raise LinAlgError(f"{model._name(b)} is {error}, for block {k}") from None
+        factors.append(BlockFactor(A, G, order, R, P))
+    return factors
+
+
+def block_chi2(
+    factors: list[BlockFactor], X: NDArray[np.float64]
+) -> NDArray[np.float64]:
+    # chi2_A (nspec, nblock) of the working vectors X of spectra of the bin of factors.
+    chi2 = np.empty((len(X), len(factors)))
+    Y = None
+    for k, (A, G, order, R, P) in enumerate(factors):
+        width = A.stop - A.start
+        if P is None:
+            # ||L^-1 x_A||^2 with L L^T = C_AA, the prior covariance of x_A.
+            w, _ = lapack.dtrtrs(R, X[:, A].T, lower=1)
+        else:
+            if Y is None:
+                # (P x)^T of every spectrum, once for all blocks: P is symmetric.
+                Y = X @ P
+            # y = R^-1 (P x)_G in the order of R. As R R^T = P_GG and r_G = x_G - mu_G
+            # = P_GG^-1 (P x)_G, R^T r_G = y, so R_AA^T r_A = y_A (R^T is upper
+            # triangular) and chi2_A |A| = ||y_A||^2. The guard pixels enter y as R^T
+            # x_(G \ A), which is 0 in the rows of A, so an outlier there cancels to
+            # rounding (test_blocks bounds it).
+            w, _ = lapack.dtrtrs(R, np.take(Y, G.start + order, axis=1).T, lower=1)
+            w = w[-width:]
+        chi2[:, k] = np.sum(w**2, axis=0) / width
+    return chi2

gspice/_datasets.py

@@ -0,0 +1,237 @@
+import math
+from dataclasses import dataclass
+
+import numpy as np
+from numpy.typing import NDArray
+from scipy.special import expit, logit
+
+from ._spectra import Boolean, Integer, Real, boolean, check_rng, integer, real
+
+MAX_DEPTH = 0.95
+
+
+@dataclass(frozen=True, eq=False)
+class Simulation:
+    r"""Synthetic spectra from `simulate`, with their noise-free flux and artifacts.
+
+    The arrays that `simulate` returns are read-only.
+
+    Attributes
+    ----------
+    flux : ndarray, shape (nspec, npix)
+        The flux, with noise and artifacts (flux).
+    ivar : ndarray, shape (nspec, npix)
+        The inverse variance of the noise, :math:`1/\sigma^2` (flux⁻²).
+    truth : ndarray, shape (nspec, npix)
+        The noise-free flux without artifacts (flux).
+    artifacts : ndarray of bool, shape (nspec, npix)
+        The pixels that an injected artifact covers.
+    snr : ndarray, shape (nspec,)
+        The continuum signal-to-noise ratio that each spectrum was drawn with
+        (unit-free).
+    labels : ndarray of int64, shape (nspec,)
+        The population of each spectrum: 0, or 1 for the giants.
+    """
+
+    flux: NDArray[np.float64]
+    ivar: NDArray[np.float64]
+    truth: NDArray[np.float64]
+    artifacts: NDArray[np.bool_]
+    snr: NDArray[np.float64]
+    labels: NDArray[np.int64]
+
+
+def simulate(
+    nspec: Integer,
+    npix: Integer = 500,
+    *,
+    rng: np.random.Generator,
+    artifacts: Real = 0.0,
+    gaussian: Boolean = False,
+) -> Simulation:
+    r"""Synthetic continuum-normalized spectra for tests and examples (no network).
+
+    Each spectrum has the continuum 1 and
+    :math:`\mathrm{nline} = \lceil \mathrm{npix}/25 \rceil` absorption lines
+    :math:`j = 1, \dots, \mathrm{nline}` at evenly spaced centres. Line :math:`j` has a
+    Gaussian profile :math:`p_j`, with a standard deviation from 1.5 to 4 pixels.
+    The lines depend only on npix. Two latent parameters :math:`\theta` set the depths.
+    A spectrum is in population 1, the giants, with the probability 0.3, and then has
+    :math:`\theta \sim N((0, 2), I)`. Otherwise :math:`\theta \sim N(0, I)`.
+    Line :math:`j` has the depth
+
+    .. math::
+
+        \mathrm{depth}_j = 0.95\,\mathrm{expit}\bigl(\mathrm{logit}(d_j / 0.95)
+        + r_j \cdot \theta\bigr),
+
+    with :math:`d_j` from 0.1 to 0.6 its depth at :math:`\theta = 0`, and
+    :math:`r_j = 0.5 (\cos j, \sin j)`. The depths are thus correlated, in (0, 0.95),
+    and not Gaussian. Then :math:`\mathrm{truth} = 1 - \sum_j \mathrm{depth}_j\, p_j`,
+    in (0, 1]. The continuum S/N has the density
+    :math:`p(\mathrm{S/N}) \propto (\mathrm{S/N})^{-2.5}` on [30, 400]. The noise is
+    Gaussian with :math:`\sigma = \sqrt{\mathrm{truth}} / \mathrm{snr}`.
+
+    With ``gaussian=True``, :math:`\mathrm{truth} = \mu + J \theta` with
+    :math:`\theta \sim N(0, I)`. Here :math:`\mu` is the truth of population 0 at
+    :math:`\theta = 0`, and the columns of :math:`J` are its derivatives there.
+    Every spectrum has the label 0 and the S/N 50, and :math:`\sigma = \sqrt{\mu} / 50`.
+    So ``ivar`` is equal for all spectra. Without artifacts,
+    :math:`\mathrm{flux} \sim N(\mu, J J^\mathsf{T} + \mathrm{diag}(\sigma^2))`, and the
+    scaled spectra (see `scale`) are exactly Gaussian. truth can then leave (0, 1].
+
+    ``round(artifacts * nspec)`` spectra (half to even), chosen at random, get one
+    artifact each. Its type is drawn uniformly from three:
+
+    - A cosmic ray adds :math:`h \sigma` to each of 1 to 3 adjacent pixels, with
+      :math:`h` log-uniform on [5, 50].
+    - A bad column sets the flux of 5 to 20 adjacent pixels to 2.
+    - A shifted segment of 200 to 600 adjacent pixels :math:`i` has the flux
+      :math:`\mathrm{truth}(i - d)` plus the noise. The shift :math:`d` is from 0.5 to 3
+      pixels, of either sign. truth is interpolated linearly, and held constant beyond
+      its ends.
+
+    An artifact covers at most npix − 1 pixels, or 1 if npix is 1. Its start is drawn
+    uniformly from the starts where it fits. For one state of ``rng``, every value of
+    ``artifacts`` gives the same ``ivar``, ``truth``, ``snr`` and ``labels``. It also
+    gives the same ``flux`` outside the pixels in ``Simulation.artifacts``.
+
+    Parameters
+    ----------
+    nspec : int
+        The number of spectra; 0 or more.
+    npix : int, optional
+        The number of pixels; 1 or more.
+    rng : numpy.random.Generator
+        The source of all randomness. With the same libraries and thread settings, the
+        same state gives the same result bit for bit.
+    artifacts : float, optional
+        The fraction of spectra with an artifact; from 0 to 1.
+    gaussian : bool, optional
+        Draw exactly Gaussian spectra, as above.
+
+    Returns
+    -------
+    Simulation
+        The spectra.
+
+    Raises
+    ------
+    TypeError
+        If an argument has a type that is not allowed above.
+    ValueError
+        If an argument has a value that is not allowed above.
+
+    Notes
+    -----
+    Cost: :math:`O(\mathrm{nspec}\,\mathrm{npix})` time and memory, plus the nline
+    profiles of npix values each. With ``gaussian=False``, the line sum adds
+    :math:`2\,\mathrm{nspec}\,\mathrm{nline}\,\mathrm{npix}` flops.
+    """
+    nspec = integer(nspec, "nspec", 0)
+    npix = integer(npix, "npix", 1)
+    check_rng(rng)
+    artifacts = real(artifacts, "artifacts")
+    if not 0 <= artifacts <= 1:
+        raise ValueError(f"artifacts: expected a number from 0 to 1, got {artifacts}")
+    gaussian = boolean(gaussian, "gaussian")
+    profiles, depth, response = _lines(npix)
+    if gaussian:
+        mu, J = _linearization(profiles, depth, response)
+        truth = mu + rng.standard_normal((nspec, 2)) @ J.T
+        labels = np.zeros(nspec, dtype=np.int64)
+        # Near 47.0, the median of the S/N law below.
+        snr = np.full(nspec, 50.0)
+        ivar = np.square(snr)[:, np.newaxis] / mu
+    else:
+        labels = (rng.random(nspec) < 0.3).astype(np.int64)
+        theta = rng.standard_normal((nspec, 2)) + np.outer(labels, (0.0, 2.0))
+        depths = MAX_DEPTH * expit(logit(depth / MAX_DEPTH) + theta @ response.T)
+        truth = 1 - depths @ profiles
+        # The inverse of the distribution function of the S/N, in a form where u = 0
+        # gives 30 exactly and u < 1 stays below 400 by about 3.5e-15 relative.
+        u = rng.random(nspec)
+        snr = 30 * (1 - u * (1 - (30 / 400) ** 1.5)) ** (-1 / 1.5)
+        ivar = np.square(snr)[:, np.newaxis] / truth
+    # In place, so that the noise holds one temporary of the size of flux.
+    flux = rng.standard_normal((nspec, npix))
+    flux /= np.sqrt(ivar)
+    flux += truth
+    flagged = _inject(flux, ivar, truth, rng, round(artifacts * nspec))
+    for array in (flux, ivar, truth, flagged, snr, labels):
+        array.flags.writeable = False
+    return Simulation(flux, ivar, truth, flagged, snr, labels)
+
+
+def _lines(
+    npix: int,
+) -> tuple[NDArray[np.float64], NDArray[np.float64], NDArray[np.float64]]:
+    # The profiles (nline, npix), the depths at theta = 0 (nline,) and the responses
+    # (nline, 2). The fractional parts of k sqrt(2) and k sqrt(3) spread the widths and
+    # the depths evenly over their ranges, and the response turns by 1 radian per line.
+    # From k = 1, every line, also a single one, depends on both latent parameters.
+    nline = math.ceil(npix / 25)
+    k = np.arange(1, nline + 1, dtype=np.float64)
+    width = 1.5 + 2.5 * (k * math.sqrt(2) % 1)
+    depth = 0.1 + 0.5 * (k * math.sqrt(3) % 1)
+    # The pixels span [-0.5, npix - 0.5], and the centres divide it evenly.
+    centre = (k - 0.5) * npix / nline - 0.5
+    offset = (np.arange(npix) - centre[:, np.newaxis]) / width[:, np.newaxis]
+    # 0 beyond 30 widths, where a profile is below 1e-195. No sum changes, because every
+    # pixel lies within 8.4 widths of a line, and nothing underflows: subnormal tails
+    # would raise under a caller's errstate and slow the line sum twofold.
+    profiles = np.exp(
+        -0.5 * np.square(offset), out=np.zeros_like(offset), where=np.abs(offset) < 30
+    )
+    response = 0.5 * np.column_stack((np.cos(k), np.sin(k)))
+    return profiles, depth, response
+
+
+def _linearization(
+    profiles: NDArray[np.float64],
+    depth: NDArray[np.float64],
+    response: NDArray[np.float64],
+) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
+    # mu (npix,) and J (npix, 2). At theta = 0, the depth of line k is d_k, and its
+    # derivative is d_k (1 - d_k / MAX_DEPTH) r_k.
+    slope = depth * (1 - depth / MAX_DEPTH)
+    return 1 - depth @ profiles, -profiles.T @ (slope[:, np.newaxis] * response)
+
+
+def _inject(
+    flux: NDArray[np.float64],
+    ivar: NDArray[np.float64],
+    truth: NDArray[np.float64],
+    rng: np.random.Generator,
+    count: int,
+) -> NDArray[np.bool_]:
+    # Adds the artifacts to flux in place, and returns the pixels that they cover.
+    nspec, npix = flux.shape
+    rows = rng.choice(nspec, count, replace=False)
+    # 0, 1 and 2: a cosmic ray, a bad column and a shifted block.
+    kinds = rng.integers(3, size=count)
+    shortest, longest = np.array([(1, 3), (5, 20), (200, 600)])[kinds].T
+    widths = np.minimum(
+        rng.integers(shortest, longest, endpoint=True), max(npix - 1, 1)
+    )
+    starts = rng.integers(npix - widths, endpoint=True)
+    # u sets the height of a cosmic ray and the size of the shift of a block.
+    u = rng.random(count)
+    heights = 5 * 10**u
+    shifts = rng.choice((-1.0, 1.0), count) * (0.5 + 2.5 * u)
+    pixels = np.arange(npix)
+    flagged = np.zeros((nspec, npix), dtype=bool)
+    for s, kind, start, width, height, shift in zip(
+        rows, kinds, starts, widths, heights, shifts, strict=True
+    ):
+        run = slice(start, start + width)
+        flagged[s, run] = True
+        if kind == 0:
+            flux[s, run] += height / np.sqrt(ivar[s, run])
+        elif kind == 1:
+            flux[s, run] = 2.0
+        else:
+            # The noise stays; the truth under it moves.
+            shifted = np.interp(pixels[run] - shift, pixels, truth[s])
+            flux[s, run] += shifted - truth[s, run]
+    return flagged