binary-galactica 0.5.0__py3-none-any.whl

binary_galactica/__init__.py

@@ -0,0 +1,139 @@
+"""Galactic-binary LISA TDI waveforms in JAX.
+
+``ucb_waveform`` uses GLASS-native parameter vectors; ``tdi_waveform`` accepts
+physical ``GBParams``. Both return frequency-domain LISA detector channels.
+The original ``polarizations`` function remains a source-only interface.
+"""
+
+from __future__ import annotations
+
+# Importing the package leaves JAX's process-global configuration alone.
+#
+# Over a four-year observation the phase of a millihertz binary accumulates to
+# ~1e6 radians.  Held in float32 that carries ~0.06 rad of error -- more than
+# enough to destroy a matched filter, yet far too small to notice in a plot.
+# The float64 functions therefore raise RuntimeError unless the application has
+# enabled double precision with jax.config.update("jax_enable_x64", True); they
+# never fall back to float32 silently.  binary_galactica.single provides float32
+# waveforms, with the frequency split into a reference bin and a small offset,
+# for processes that keep x64 disabled.
+from binary_galactica import single
+from binary_galactica.constants import DAY, YEAR
+from binary_galactica.detector import tdi_waveform
+from binary_galactica.glass import (
+    BACKENDS,
+    DEFAULT_RESPONSE_SAMPLES,
+    FORMATS,
+    FSTAR,
+    GLASS_TO_CONTINUOUS,
+    LARM,
+    SNR_MIN,
+    UCB_MODEL_NP,
+    Alignment,
+    ExtrinsicPriorDraw,
+    FisherCache,
+    FisherProposal,
+    PriorDraw,
+    ProposalMix,
+    UCBPrior,
+    WaveformResult,
+    ae_noise,
+    analytic_orbits,
+    analytic_snr,
+    arm_vectors,
+    detector_tensor,
+    draw_from_fisher,
+    fm_shift,
+    orbit_cache,
+    params_from_native,
+    polarization_tensor,
+    psi_phi_jump,
+    single_source_mix,
+    slow_time_grid,
+    snr_cut,
+    synthesize,
+    tdi_response,
+    template_on_window,
+    to_continuous_ft,
+    ucb_alignment,
+    ucb_bandwidth,
+    ucb_bw,
+    ucb_fdot,
+    ucb_prior,
+    ucb_waveform,
+    xyz_to_ae,
+    xyz_to_aet,
+)
+from binary_galactica.parameters import (
+    NUM_PARAMS,
+    PARAMETER_NAMES,
+    GBParams,
+    from_glass_vector,
+    to_glass_vector,
+)
+from binary_galactica.waveform import (
+    amplitudes,
+    frequency,
+    phase,
+    polarizations,
+)
+
+__version__ = "0.5.0"
+
+__all__ = [
+    "BACKENDS",
+    "DEFAULT_RESPONSE_SAMPLES",
+    "tdi_response",
+    "DAY",
+    "NUM_PARAMS",
+    "PARAMETER_NAMES",
+    "YEAR",
+    "GBParams",
+    "amplitudes",
+    "frequency",
+    "phase",
+    "polarizations",
+    "FORMATS",
+    "FSTAR",
+    "GLASS_TO_CONTINUOUS",
+    "LARM",
+    "SNR_MIN",
+    "UCB_MODEL_NP",
+    "Alignment",
+    "ExtrinsicPriorDraw",
+    "FisherCache",
+    "FisherProposal",
+    "PriorDraw",
+    "ProposalMix",
+    "UCBPrior",
+    "WaveformResult",
+    "ae_noise",
+    "analytic_orbits",
+    "analytic_snr",
+    "arm_vectors",
+    "detector_tensor",
+    "draw_from_fisher",
+    "fm_shift",
+    "orbit_cache",
+    "params_from_native",
+    "polarization_tensor",
+    "psi_phi_jump",
+    "single_source_mix",
+    "slow_time_grid",
+    "snr_cut",
+    "synthesize",
+    "template_on_window",
+    "to_continuous_ft",
+    "ucb_alignment",
+    "ucb_bandwidth",
+    "ucb_bw",
+    "ucb_fdot",
+    "ucb_prior",
+    "ucb_waveform",
+    "xyz_to_ae",
+    "xyz_to_aet",
+    "tdi_waveform",
+    "to_glass_vector",
+    "from_glass_vector",
+    "single",
+]

binary_galactica/constants.py

@@ -0,0 +1,18 @@
+"""Physical constants and time units, in SI.
+
+Values follow the LISA Data Challenge conventions. The GLASS backend keeps
+its own pinned literals in :mod:`binary_galactica.glass.constants`; its
+sidereal-year literal differs slightly from the physical unit exposed here.
+"""
+
+from __future__ import annotations
+
+#: Sidereal year in seconds (LDC ``YRSID_SI``).  LISA observation times are
+#: conventionally quoted in sidereal years because the constellation's orbit is
+#: tied to Earth's, so this -- not the Julian year -- is the natural unit.
+YEAR: float = 31_558_149.763_545_603
+
+#: Solar day in seconds.
+DAY: float = 86_400.0
+
+__all__ = ["DAY", "YEAR"]

binary_galactica/detector.py

@@ -0,0 +1,142 @@
+"""LISA detector waveforms from the package's physical source parameters."""
+
+from functools import partial
+
+import jax
+import jax.numpy as jnp
+import numpy as np
+from jax import Array
+from jax.typing import ArrayLike
+
+from binary_galactica.glass import _validation
+from binary_galactica.glass.types import WaveformResult
+from binary_galactica.glass.waveform import (
+    DEFAULT_RESPONSE_SAMPLES,
+    _options,
+    ucb_waveform,
+)
+from binary_galactica.parameters import GBParams, to_glass_vector
+
+
+def tdi_waveform(  # noqa: N803 -- names follow the GLASS waveform API
+    theta: ArrayLike | GBParams,
+    *,
+    T: ArrayLike,
+    BW: int,
+    t0: ArrayLike = 0.0,
+    fmt: str = "sangria",
+    positions: ArrayLike | None = None,
+    backend: str = "onfly",
+    response_samples: int | None = DEFAULT_RESPONSE_SAMPLES,
+) -> WaveformResult:
+    """Generate the raw GLASS TDI spectrum for physical ``GBParams``.
+
+    This is the physical-coordinate counterpart of :func:`ucb_waveform`,
+    whose input array instead uses GLASS-native coordinates. The adapter
+    converts amplitude, phase, sky angles, inclination and time scales using
+    :func:`to_glass_vector`. It includes GLASS's first-order amplitude
+    evolution, which the original source-only ``polarizations`` omits.
+
+    Args:
+        theta: One physical ``GBParams`` or ``(8,)`` physical array. Use
+            ``jax.vmap`` to evaluate multiple sources. All fields must be
+            finite, ``amp`` and ``f0`` positive, ``iota`` in ``[0, pi]``,
+            and ``beta`` in ``[-pi/2, pi/2]``.
+        T: Positive observation duration in seconds. May be traced or
+            captured as a constant in surrounding JIT functions.
+        BW: Positive even number of slow samples and output bins. Static;
+            choose it by convergence for the intended analysis.
+        t0: Time of the first observation, in seconds from the source's
+            reference epoch. The parameters remain defined at time zero.
+        fmt: ``"sangria"``, ``"frequency"``, or ``"phase"`` TDI convention.
+        positions: Optional ``(3, BW, 3)`` spacecraft positions on the exact
+            ``(T, t0, BW)`` slow grid, as returned by ``orbit_cache``.
+            On the on-fly path this cache is interpolated; its sampling limits
+            geometry accuracy. Omit it to evaluate analytic geometry directly.
+        backend: ``"onfly"`` (default) or the legacy ``"fourier"`` path.
+        response_samples: ``None`` selects a duration-dependent power-of-two
+            grid of 32–2048 samples, targeting 128 samples per year. An explicit
+            static integer of at least four fixes the count independently of
+            ``BW``. Unused by the legacy backend. Pass an explicit count when
+            differentiating ``T`` across automatic grid thresholds: automatic
+            selection is piecewise and changes the interpolation grid.
+
+    Returns:
+        A dictionary with complex ``X/Y/Z/A/E`` arrays, ``qmin``, and absolute
+        ``freq_bin_indices``. Channels have length ``BW`` and raw GLASS
+        normalization. ``to_continuous_ft(result, T)`` multiplies by sqrt(T).
+
+    Notes:
+        Derivatives treat the discrete carrier and bandwidth choices as fixed.
+        The backend regularizes the sky-pole coordinate singularity. Those
+        coordinate-boundary derivatives are not exact physical derivatives.
+        Invalid eager inputs raise ``ValueError``. Invalid values supplied
+        through JAX tracers yield NaN in every output; shapes are checked
+        during tracing as well. See :func:`ucb_waveform` for grid validation.
+
+    """
+    _validation.require_x64()
+    response_samples = _options(backend, response_samples)
+    duration, t0, positions = _validation.observation(T, BW, t0, positions)
+    # Host scalar fields can be packed once by validation. Keep to_array's
+    # broadcasting and traced packing for array-valued fields.
+    if isinstance(theta, GBParams) and not all(np.isscalar(field) for field in theta):
+        theta = theta.to_array()
+    theta = _validation.finite_array(theta, "theta")
+    if theta.shape != (8,):
+        raise ValueError(f"theta must have shape (8,); got {theta.shape}")
+    if not isinstance(theta, jax.core.Tracer):
+        p = np.asarray(theta)
+        if p[0] <= 0 or p[1] <= 0:
+            raise ValueError("amp and f0 must be positive")
+        if not 0 <= p[4] <= np.pi:
+            raise ValueError("iota must lie in [0, pi]")
+        if not -np.pi / 2 <= p[7] <= np.pi / 2:
+            raise ValueError("beta must lie in [-pi/2, pi/2]")
+    return _tdi_waveform(
+        theta,
+        T=duration,
+        BW=int(BW),
+        t0=t0,
+        fmt=fmt,
+        positions=positions,
+        backend=backend,
+        response_samples=response_samples,
+    )
+
+
+@partial(jax.jit, static_argnames=("BW", "fmt", "backend", "response_samples"))
+def _tdi_waveform(
+    theta: Array,
+    *,
+    T: Array,
+    BW: int,
+    t0: Array,
+    fmt: str,
+    positions: Array | None,
+    backend: str,
+    response_samples: int | None,
+) -> WaveformResult:
+    """Convert physical coordinates inside JIT and preserve invalid domains."""
+    valid = (
+        jnp.all(jnp.isfinite(theta))
+        & (theta[0] > 0)
+        & (theta[1] > 0)
+        & (theta[4] >= 0)
+        & (theta[4] <= jnp.pi)
+        & (jnp.abs(theta[7]) <= jnp.pi / 2)
+    )
+    native = jnp.where(valid, to_glass_vector(theta, T), jnp.nan)
+    return ucb_waveform(
+        native,
+        T=T,
+        BW=BW,
+        t0=t0,
+        fmt=fmt,
+        positions=positions,
+        backend=backend,
+        response_samples=response_samples,
+    )
+
+
+__all__ = ["tdi_waveform"]

binary_galactica/glass/__init__.py

@@ -0,0 +1,118 @@
+# Copyright 2019 Tyson B. Littenberg & Neil J. Cornish
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""GLASS-compatible galactic-binary TDI waveforms in JAX.
+
+The default waveform constructs first-generation frozen-geometry XYZ directly
+at sparse reception times, interpolates its demodulated analytic response, and
+then Fourier transforms it. It follows the pinned GLASS
+``LISA_spline_response`` / ``LISA_TDI_spline`` path from commit
+``079c6a3a6fcf380a7c107f39640fff7fc720d0f1``. The explicit
+``backend="fourier"`` option retains GLASS's earlier fast-slow / reduced-DFT
+link-response construction for legacy reference comparisons.
+
+Quick start
+-----------
+>>> import jax
+>>> jax.config.update("jax_enable_x64", True)
+>>> import binary_galactica.glass
+>>> T, BW = 7884000.0, 64
+>>> p = binary_galactica.glass.params_from_native(
+...     f0=1e-3, fdot=1e-18, amp=7.16e-22, phi0=0.5,
+...     colat=1.78, lon=0.0, psi=0.7, cos_iota=0.3, T=T)
+>>> w = binary_galactica.glass.ucb_waveform(p, T=T, BW=BW)
+>>> w["A"].shape
+(64,)
+
+The returned spectrum is in GLASS's amplitude convention and occupies
+absolute frequency bins ``qmin ... qmin + BW - 1``. Use
+:func:`binary_galactica.glass.convert.to_continuous_ft` for the continuous-Fourier
+convention used elsewhere in this repository.
+"""
+
+from __future__ import annotations
+
+from .alignment import Alignment, ucb_alignment
+from .bandwidth import ae_noise, analytic_snr, ucb_bandwidth, ucb_bw
+from .compat import template_on_window
+from .constants import FSTAR, LARM, UCB_MODEL_NP
+from .convert import GLASS_TO_CONTINUOUS, to_continuous_ft
+from .orbit import analytic_orbits, arm_vectors, slow_time_grid
+from .prior import SNR_MIN, UCBPrior, snr_cut, ucb_fdot, ucb_prior
+from .proposals import (
+    ExtrinsicPriorDraw,
+    FisherCache,
+    FisherProposal,
+    PriorDraw,
+    ProposalMix,
+    draw_from_fisher,
+    fm_shift,
+    psi_phi_jump,
+    single_source_mix,
+)
+from .response import detector_tensor, polarization_tensor
+from .tdi import FORMATS, synthesize, xyz_to_ae, xyz_to_aet
+from .types import WaveformResult
+from .waveform import (
+    BACKENDS,
+    DEFAULT_RESPONSE_SAMPLES,
+    orbit_cache,
+    params_from_native,
+    tdi_response,
+    ucb_waveform,
+)
+
+__all__ = [
+    "BACKENDS",
+    "DEFAULT_RESPONSE_SAMPLES",
+    "tdi_response",
+    "Alignment",
+    "FORMATS",
+    "FSTAR",
+    "GLASS_TO_CONTINUOUS",
+    "LARM",
+    "UCB_MODEL_NP",
+    "WaveformResult",
+    "ae_noise",
+    "analytic_orbits",
+    "analytic_snr",
+    "arm_vectors",
+    "detector_tensor",
+    "orbit_cache",
+    "params_from_native",
+    "ExtrinsicPriorDraw",
+    "FisherCache",
+    "FisherProposal",
+    "PriorDraw",
+    "ProposalMix",
+    "SNR_MIN",
+    "UCBPrior",
+    "draw_from_fisher",
+    "fm_shift",
+    "polarization_tensor",
+    "psi_phi_jump",
+    "single_source_mix",
+    "slow_time_grid",
+    "snr_cut",
+    "synthesize",
+    "ucb_fdot",
+    "ucb_prior",
+    "template_on_window",
+    "to_continuous_ft",
+    "ucb_alignment",
+    "ucb_bandwidth",
+    "ucb_bw",
+    "ucb_waveform",
+    "xyz_to_ae",
+    "xyz_to_aet",
+]

binary_galactica/glass/_precision.py

@@ -0,0 +1,49 @@
+"""Working precision for kernels that follow the dtype of their inputs.
+
+Float64 inputs keep float64 arithmetic and results; float32 inputs compute
+float32 and complex64 values throughout, even with x64 enabled. Python scalars
+are weakly typed in JAX: they adopt the working precision without promoting
+it. NumPy float64 values and default-dtype constructors are not, so kernels
+cast them to the working dtype explicitly.
+"""
+
+import jax
+import jax.numpy as jnp
+import numpy as np
+
+#: Precision of every contraction. The default lets float32 contractions use
+#: TF32 on NVIDIA GPUs and reduced-precision passes on TPUs. CPU float64
+#: ignores the setting, so float64 results do not change.
+CONTRACTION = jax.lax.Precision.HIGHEST
+
+
+def real_dtype(*values) -> np.dtype:
+    """Return the real working dtype of array-like ``values``, at least float32.
+
+    Complex values give their component dtype. Integer and boolean inputs, and
+    Python scalars on their own, give JAX's default floating dtype: float64
+    only when x64 is enabled.
+    """
+    # Nested sequences have no dtype of their own; their elements decide it.
+    leaves = jax.tree_util.tree_leaves(values)
+    dtype = jnp.result_type(*leaves) if leaves else jnp.result_type(float)
+    if not jnp.issubdtype(dtype, jnp.inexact):
+        dtype = jnp.result_type(float)
+    return jnp.promote_types(jnp.finfo(dtype).dtype, jnp.float32)
+
+
+def complex_dtype(*values) -> np.dtype:
+    """Return the complex dtype with the precision of :func:`real_dtype`."""
+    return jnp.promote_types(real_dtype(*values), jnp.complex64)
+
+
+def cast(value, dtype):
+    """Return ``value`` in ``dtype``, leaving Python scalars weakly typed.
+
+    A Python ``int`` or ``float`` already adopts the precision of the arrays it
+    meets, so it is returned unchanged; arithmetic on it, such as ``T**3``,
+    stays in Python double precision.
+    """
+    if type(value) in (int, float):
+        return value
+    return jnp.asarray(value, dtype=dtype)

binary_galactica/glass/_twofloat.py

@@ -0,0 +1,117 @@
+"""Float32 pairs that carry about twice float32's precision.
+
+A value is an unevaluated sum ``(hi, lo)`` of float32 arrays, as in
+double-single arithmetic: products and quotients keep about 2**-46 relative
+precision. Plain float32 resolves ``t/YEAR`` at multi-year times, or a
+phase of hundreds of cycles, only to about 1e-6 cycles.
+
+The textbook error-free product subtracts a rounded product from the exact
+one. XLA may contract ``a*b + c`` into a fused multiply-add, as measured on
+an arm64 CPU, which silently changes that correction. Products here are
+instead formed from operands split into halves of at most 12 significant
+bits, so every partial product is exact in float32 and fusing it into an
+addition rounds the same exact sum. Additions use Knuth's two-sum, which has
+no products. Splitting masks the low mantissa bits, so it involves no
+arithmetic.
+
+Derivatives pass through: split halves carry no tangent, a two-sum's error
+term carries none, and each pair's derivative is that of the exact
+expression, evaluated in float32.
+"""
+
+from __future__ import annotations
+
+import jax
+import jax.numpy as jnp
+import numpy as np
+from jax import Array
+
+#: An unevaluated sum ``hi + lo`` of float32 values.
+Pair = tuple[Array, Array]
+
+#: Clears the low 12 of float32's 23 stored mantissa bits.
+_HIGH_BITS = np.int32(-(1 << 12))
+
+
+def split(x) -> Pair:
+    """Return ``(hi, lo)`` with ``hi + lo == x`` and at most 12 bits in each."""
+    x = jnp.asarray(x, dtype=jnp.float32)
+    bits = jax.lax.bitcast_convert_type(x, jnp.int32)
+    hi = jax.lax.bitcast_convert_type(bits & _HIGH_BITS, jnp.float32)
+    return hi, x - hi
+
+
+def two_sum(a, b) -> Pair:
+    """Return the rounded sum and its exact rounding error (Knuth)."""
+    s = a + b
+    bb = s - a
+    return s, (a - (s - bb)) + (b - bb)
+
+
+def pair(x) -> Pair:
+    """Return float32 ``x`` as a pair with a zero low part."""
+    x = jnp.asarray(x, dtype=jnp.float32)
+    return x, jnp.zeros_like(x)
+
+
+def constant(value) -> tuple[np.ndarray, np.ndarray]:
+    """Round a host float64 constant or array to a float32 pair."""
+    value = np.asarray(value, dtype=np.float64)
+    hi = value.astype(np.float32)
+    return hi, (value - hi).astype(np.float32)
+
+
+def product(x, y) -> Pair:
+    """Return float32 ``x*y`` as a pair, from exact partial products."""
+    x1, x2 = split(x)
+    y1, y2 = split(y)
+    s, e1 = two_sum(x1 * y1, x1 * y2)
+    s, e2 = two_sum(s, x2 * y1)
+    return two_sum(s, (e1 + e2) + x2 * y2)
+
+
+def add(a: Pair, b: Pair) -> Pair:
+    """Return the pair sum ``a + b``."""
+    s, e = two_sum(a[0], b[0])
+    return two_sum(s, e + (a[1] + b[1]))
+
+
+def multiply(a: Pair, b: Pair) -> Pair:
+    """Return the pair product ``a*b``."""
+    hi, lo = product(a[0], b[0])
+    # The cross terms are about 2**-24 of the product; rounding them is harmless.
+    return two_sum(hi, lo + (a[0] * b[1] + a[1] * b[0]))
+
+
+def divide(a, b) -> Pair:
+    """Return float32 ``a/b`` as a pair, correcting the quotient's remainder."""
+    quotient = a / b
+    hi, lo = product(quotient, b)
+    # a - hi is exact because hi is within a rounding of a.
+    return two_sum(quotient, ((a - hi) - lo) / b)
+
+
+def fraction(a: Pair) -> Pair:
+    """Subtract the integer nearest ``a``, leaving a pair near ``[-0.5, 0.5]``."""
+    hi = a[0] - jnp.round(a[0])
+    return two_sum(hi, a[1])
+
+
+def value(a: Pair) -> Array:
+    """Round a pair to float32."""
+    return a[0] + a[1]
+
+
+__all__ = [
+    "Pair",
+    "add",
+    "constant",
+    "divide",
+    "fraction",
+    "multiply",
+    "pair",
+    "product",
+    "split",
+    "two_sum",
+    "value",
+]

binary_galactica/glass/_validation.py

@@ -0,0 +1,94 @@
+"""Eager boundary checks shared by the native and physical waveform APIs."""
+
+import jax
+import jax.numpy as jnp
+import numpy as np
+
+
+def require_x64():
+    """Refuse to run a float64 entry point while JAX would compute in float32."""
+    # read() gives the effective value, including jax.experimental.enable_x64
+    # scopes, on every supported JAX; it never changes the setting.
+    if not jax.config.read("jax_enable_x64"):
+        raise RuntimeError(
+            "binary_galactica's float64 functions need JAX double precision, "
+            "which is disabled. Call "
+            'jax.config.update("jax_enable_x64", True) at startup, before '
+            "creating JAX arrays, or use binary_galactica.single for float32 "
+            "waveforms."
+        )
+
+
+def integer(value, name, *, minimum=None):
+    """Require a concrete integer index/count without truncating or accepting bools."""
+    requirement = {
+        None: "an integer",
+        0: "a non-negative integer",
+        1: "a positive integer",
+    }[minimum]
+    if (
+        isinstance(value, (bool, np.bool_))
+        or not isinstance(value, (int, np.integer))
+        or (minimum is not None and value < minimum)
+    ):
+        raise ValueError(f"{name} must be {requirement}; got {value!r}")
+    return int(value)
+
+
+def _contains_jax(value):
+    """Detect JAX values and conversion protocols before packing sequences."""
+    if isinstance(value, (jax.Array, jax.core.Tracer)) or callable(
+        getattr(value, "__jax_array__", None)
+    ):
+        return True
+    return isinstance(value, (list, tuple)) and any(_contains_jax(x) for x in value)
+
+
+def finite_array(value, name, *, dtype=np.float64):
+    """Validate floating inputs, keeping host values off device until the JIT call.
+
+    Values are cast to ``dtype``: float64 for the double-precision API and
+    float32 for :mod:`binary_galactica.single`. A host value too large for
+    float32 becomes infinite and is rejected like any other nonfinite input.
+    """
+    # Packing host scalars with jnp dispatches before the compiled waveform.
+    # JAX arrays and nested tracers must stay in JAX to preserve placement/AD.
+    if _contains_jax(value):
+        value = jnp.asarray(value, dtype=dtype)
+    else:
+        with np.errstate(over="ignore"):
+            value = np.asarray(value, dtype=dtype)
+    if not isinstance(value, jax.core.Tracer) and not np.all(np.isfinite(value)):
+        raise ValueError(f"{name} must be finite")
+    return value
+
+
+def scalar(value, name, *, positive=False, dtype=np.float64):
+    """Validate scalar shape during tracing, and concrete value eagerly."""
+    value = finite_array(value, name, dtype=dtype)
+    if value.ndim != 0:
+        raise ValueError(f"{name} must be a scalar; got shape {value.shape}")
+    if positive and not isinstance(value, jax.core.Tracer) and np.asarray(value) <= 0:
+        raise ValueError(f"{name} must be positive")
+    return value
+
+
+def observation(T, BW, t0, positions, *, dtype=np.float64):
+    """Check the shared observation arguments at the public boundary."""
+    if (
+        isinstance(BW, bool)
+        or not isinstance(BW, (int, np.integer))
+        or BW <= 0
+        or BW % 2
+    ):
+        raise ValueError(f"BW must be a positive even integer; got {BW!r}")
+    T = scalar(T, "T", positive=True, dtype=dtype)
+    t0 = scalar(t0, "t0", dtype=dtype)
+    if positions is not None:
+        positions = finite_array(positions, "positions", dtype=dtype)
+        if positions.shape != (3, BW, 3):
+            raise ValueError(
+                "positions must have shape (3, BW, 3); "
+                f"got {positions.shape} for BW={BW}"
+            )
+    return T, t0, positions