gwmock-data 0.1.0__py3-none-any.whl

gwmock_data/__init__.py

@@ -0,0 +1,13 @@
+"""Top-level package for gwmock_data."""
+
+from __future__ import annotations
+
+# PEP 810: defer importlib.metadata (loaded by version.py) on 3.15+.
+# Ignored on 3.13/3.14 where the lazy import machinery does not exist.
+__lazy_modules__ = ["gwmock_data.sampling_grid", "gwmock_data.timeseries", "gwmock_data.version"]
+
+from gwmock_data.sampling_grid import SamplingGrid
+from gwmock_data.timeseries import TimeSeries, as_timeseries
+from gwmock_data.version import __version__
+
+__all__ = ["SamplingGrid", "TimeSeries", "__version__", "as_timeseries"]

gwmock_data/_optional.py

@@ -0,0 +1,35 @@
+"""Import an optional package, naming the extra that installs it when it is missing."""
+
+from __future__ import annotations
+
+import importlib
+from types import ModuleType
+
+
+def require(module: str, extra: str, feature: str) -> ModuleType:
+    """Return ``module``, importing it; say which extra installs it if it is missing.
+
+    Only ``module`` itself missing, or a package it sits in, is reported that way. Any other
+    missing module -- one it needs, or a part of an installed package that fails to import -- is
+    re-raised unchanged, since installing the extra would not help.
+
+    Args:
+        module: Dotted module name, such as ``"gwpy.timeseries"``.
+        extra: The ``gwmock-data`` extra that installs it, such as ``"gwpy"``.
+        feature: What needs it, for the message, such as ``"Frame (GWF) output"``.
+
+    Raises:
+        ModuleNotFoundError: If the package is not installed.
+    """
+    try:
+        return importlib.import_module(module)
+    except ModuleNotFoundError as exc:
+        parts = module.split(".")
+        enclosing = {".".join(parts[: index + 1]) for index in range(len(parts))}
+        if exc.name not in enclosing:
+            raise
+        root = parts[0]
+        raise ModuleNotFoundError(
+            f"{feature} needs {root}, which is not installed. Install it with: pip install 'gwmock-data[{extra}]'",
+            name=exc.name,
+        ) from exc

gwmock_data/io/__init__.py

@@ -0,0 +1,7 @@
+"""Reading and writing time series."""
+
+from __future__ import annotations
+
+from gwmock_data.io.hdf5 import read_hdf5, write_hdf5
+
+__all__ = ["read_hdf5", "write_hdf5"]

gwmock_data/io/hdf5.py

@@ -0,0 +1,88 @@
+"""Read and write time series as HDF5, in the layout GWpy's ``TimeSeriesDict`` uses.
+
+One dataset per series, named by its key and gzip-compressed, with the attributes GWpy writes and
+reads: ``x0`` (the GPS time of the first sample), ``dx`` (the sample spacing, in seconds),
+``xunit`` (``"s"``), ``unit`` and, for a series that has one, ``name``. A file written here therefore loads with
+``gwpy.timeseries.TimeSeriesDict.read(path, format="hdf5")``, and a file GWpy wrote loads here.
+
+Only ``h5py`` is needed, imported when a function is called; GWpy is not.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+
+import numpy as np
+
+from gwmock_data._optional import require
+from gwmock_data.timeseries import TimeSeries, as_timeseries
+
+__all__ = ["read_hdf5", "write_hdf5"]
+
+
+def write_hdf5(series: Mapping[str, TimeSeries], path: str | Path) -> None:
+    """Write each series to ``path`` as one HDF5 dataset named by its key, replacing the file.
+
+    Args:
+        series: Mapping of dataset name to a one-dimensional time series (this package's or
+            GWpy's).
+        path: Output file.
+
+    Raises:
+        ValueError: If a series is not one-dimensional.
+        ModuleNotFoundError: If ``h5py`` is not installed.
+    """
+    h5py = require("h5py", "hdf5", "HDF5 output")
+    channels = {key: as_timeseries(value) for key, value in series.items()}
+    for key, channel in channels.items():
+        if len(channel.data.shape) != 1:
+            raise ValueError(f"{key!r} must be one-dimensional to write; it has shape {tuple(channel.data.shape)}.")
+    with h5py.File(Path(path), "w") as handle:
+        for key, channel in channels.items():
+            dataset = handle.create_dataset(key, data=np.asarray(channel.data), compression="gzip")
+            dataset.attrs["x0"] = channel.t0
+            dataset.attrs["dx"] = channel.dt
+            dataset.attrs["xunit"] = "s"
+            dataset.attrs["unit"] = channel.unit or ""
+            if channel.name is not None:
+                dataset.attrs["name"] = channel.name
+
+
+def read_hdf5(path: str | Path) -> dict[str, TimeSeries]:
+    """Read every dataset in ``path`` written in the layout :func:`write_hdf5` writes.
+
+    Args:
+        path: Input file.
+
+    Returns:
+        Mapping of dataset name to :class:`~gwmock_data.timeseries.TimeSeries`, in file order.
+
+    Raises:
+        ValueError: If a dataset lacks the ``x0`` or ``dx`` attribute, or its time unit is not seconds.
+        ModuleNotFoundError: If ``h5py`` is not installed.
+    """
+    h5py = require("h5py", "hdf5", "HDF5 input")
+    result = {}
+    with h5py.File(Path(path), "r") as handle:
+        for key, dataset in handle.items():
+            attrs = dataset.attrs
+            if "x0" not in attrs or "dx" not in attrs:
+                raise ValueError(f"dataset {key!r} has no x0 and dx attributes, so it is not a time series.")
+            xunit = _text(attrs.get("xunit", "s"))
+            if xunit not in ("s", "second"):
+                raise ValueError(f"dataset {key!r} has a time axis in {xunit!r}; only seconds are supported.")
+            name = _text(attrs["name"]) if "name" in attrs else None
+            result[key] = TimeSeries(
+                dataset[...],
+                t0=float(attrs["x0"]),
+                sample_rate=1.0 / float(attrs["dx"]),
+                name=name,
+                unit=_text(attrs.get("unit", "")) or None,
+            )
+    return result
+
+
+def _text(value: object) -> str:
+    """Return an HDF5 string attribute as ``str``, whether h5py read it as bytes or text."""
+    return value.decode("utf-8") if isinstance(value, bytes) else str(value)

gwmock_data/sampling_grid.py

@@ -0,0 +1,167 @@
+"""A uniform sample lattice, and the arithmetic for placing GPS times on it.
+
+Superposing one series onto another is exact when the two share a sample lattice: the operation
+is an integer-offset add. When they do not, something has to resample, and the resampling sets the
+accuracy of whatever is built on it. A :class:`SamplingGrid` names the lattice so code can decide,
+exactly, whether a time is on it.
+
+GPS times near 1.4e9 s carry float64 rounding of a sizeable fraction of a sample at kilohertz rates,
+so "on the lattice" is judged with a tolerance derived from that resolution, never a fixed one.
+
+This module holds only the lattice arithmetic and its validation, and imports nothing but NumPy.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+#: Timestamp ULPs of slack allowed when deciding whether a time is on the lattice. The
+#: tolerance has to be derived from float64 resolution rather than fixed: one ULP of a GPS
+#: timestamp near 1.4e9 is about 2.4e-7 s, which at 2048 Hz is already 4.9e-4 samples. A fixed
+#: 1e-6-sample tolerance -- the first thing written here -- was therefore some 500x *tighter*
+#: than the timestamps can represent, and would have falsely rejected lattice times produced by
+#: ordinary arithmetic. It survived initial testing only because 64 s at 2048 Hz happens to be
+#: exact in binary; a non-power-of-two segment duration would have broken it.
+_LATTICE_TOLERANCE_ULPS = 8.0
+
+#: Smallest tolerance to use, in samples, so that a tiny epoch does not make the check
+#: unreasonably strict.
+_MINIMUM_TOLERANCE_SAMPLES = 1e-9
+
+#: Largest tolerance to use, in samples. Well below the half-sample displacements the check
+#: exists to catch, so no plausible ULP growth can make it accept a genuinely off-lattice time.
+_MAXIMUM_TOLERANCE_SAMPLES = 1e-2
+
+
+@dataclass(frozen=True)
+class SamplingGrid:
+    """A uniform sample lattice: sample ``k`` sits at ``epoch + k / sampling_frequency``.
+
+    Args:
+        epoch: GPS time of sample zero.
+        sampling_frequency: Sample rate in Hz.
+
+    Raises:
+        ValueError: If ``sampling_frequency`` is not positive and finite, or ``epoch`` is not
+            finite.
+    """
+
+    epoch: float
+    sampling_frequency: float
+
+    def __post_init__(self) -> None:
+        """Validate the lattice definition."""
+        if not np.isfinite(self.epoch):
+            raise ValueError(f"epoch must be finite; got {self.epoch}.")
+        if not np.isfinite(self.sampling_frequency) or self.sampling_frequency <= 0.0:
+            raise ValueError(f"sampling_frequency must be positive and finite; got {self.sampling_frequency}.")
+
+    @property
+    def sample_spacing(self) -> float:
+        """Seconds between samples."""
+        return 1.0 / self.sampling_frequency
+
+    def lattice_tolerance_samples(self, gps_time: np.ndarray | float) -> float:
+        """Return the on-lattice tolerance, in samples, appropriate to these timestamps.
+
+        Scaled by the float64 resolution of the times involved, because at GPS magnitudes that
+        resolution is coarser than any fixed tolerance worth writing down: near 1.4e9 one ULP
+        is already ~5e-4 samples at 2048 Hz.
+
+        An empty input is answered from the epoch alone. A chunked or filtered caller can
+        legitimately arrive with nothing to check, and reducing over an empty array would raise
+        here instead of letting the (vacuously satisfied) lattice check return empty.
+        """
+        times = np.asarray(gps_time, dtype=float)
+        magnitude = abs(float(self.epoch))
+        if times.size:
+            magnitude = max(magnitude, float(np.max(np.abs(times))))
+        ulp_samples = float(np.spacing(magnitude)) * self.sampling_frequency
+        return float(
+            np.clip(_LATTICE_TOLERANCE_ULPS * ulp_samples, _MINIMUM_TOLERANCE_SAMPLES, _MAXIMUM_TOLERANCE_SAMPLES)
+        )
+
+    def index_of(self, gps_time: np.ndarray | float) -> np.ndarray:
+        """Return the (generally fractional) lattice index of *gps_time*.
+
+        The subtraction is done before the multiplication: GPS times are ~1.4e9 and the
+        spacing is ~5e-4 s, so scaling first would lose the sub-sample part entirely.
+        """
+        return (np.asarray(gps_time, dtype=float) - self.epoch) * self.sampling_frequency
+
+    def time_of(self, index: np.ndarray | int) -> np.ndarray:
+        """Return the GPS time of lattice index *index*."""
+        return self.epoch + np.asarray(index, dtype=float) * self.sample_spacing
+
+    def split_index(self, gps_time: np.ndarray | float) -> tuple[np.ndarray, np.ndarray]:
+        """Split *gps_time* into the preceding lattice index and a fractional remainder.
+
+        Returns:
+            ``(index, fraction)`` with ``fraction`` in ``[0, 1)``, such that
+            ``gps_time == time_of(index) + fraction * sample_spacing``. The fraction is what
+            the device must absorb for the sample to land on the lattice.
+        """
+        exact = self.index_of(gps_time)
+        index = np.floor(exact)
+        return index.astype(np.int64), exact - index
+
+    def is_on_lattice(self, gps_time: np.ndarray | float) -> np.ndarray:
+        """Return whether each *gps_time* coincides with a lattice sample."""
+        exact = self.index_of(gps_time)
+        return np.abs(exact - np.round(exact)) <= self.lattice_tolerance_samples(gps_time)
+
+    def require_on_lattice(self, gps_time: np.ndarray | float, *, name: str) -> np.ndarray:
+        """Return integer lattice indices, rejecting any time that is off-lattice.
+
+        Rejected rather than silently rounded: rounding would move a signal by up to half a
+        sample without telling anyone, and silently accepting an off-lattice time is exactly
+        how the off-lattice resampling error described in this module's docstring got in.
+
+        Args:
+            gps_time: Time(s) that must coincide with lattice samples.
+            name: What is being checked, for the error message.
+
+        Returns:
+            Integer lattice indices, same shape as the input.
+
+        Raises:
+            ValueError: If any time is not on the lattice.
+        """
+        times = np.atleast_1d(np.asarray(gps_time, dtype=float))
+        exact = self.index_of(times)
+        offenders = np.abs(exact - np.round(exact)) > self.lattice_tolerance_samples(times)
+        if np.any(offenders):
+            first = int(np.argmax(offenders))
+            raise ValueError(
+                f"{name} must lie on the sampling grid (epoch={self.epoch!r}, "
+                f"sampling_frequency={self.sampling_frequency!r}), but entry {first} at "
+                f"{times[first]!r} is {exact[first] - round(float(exact[first])):+.6g} samples off. "
+                f"Rounding it would displace the data by up to half a sample; choose segment "
+                f"starts on the grid, or build the grid from them."
+            )
+        return np.round(exact).astype(np.int64).reshape(np.shape(gps_time))
+
+    @classmethod
+    def from_segment_starts(cls, segment_start_times: np.ndarray, sampling_frequency: float) -> SamplingGrid:
+        """Build a grid anchored on the first segment start.
+
+        Args:
+            segment_start_times: GPS start times, which must themselves be mutually
+                consistent with one lattice at this sample rate.
+            sampling_frequency: Sample rate in Hz.
+
+        Returns:
+            A grid whose epoch is the first segment start.
+
+        Raises:
+            ValueError: If ``segment_start_times`` is empty, or the starts do not share one
+                lattice — which would make a single canonical grid impossible.
+        """
+        starts = np.atleast_1d(np.asarray(segment_start_times, dtype=float))
+        if starts.size == 0:
+            raise ValueError("segment_start_times must not be empty.")
+        grid = cls(epoch=float(starts[0]), sampling_frequency=sampling_frequency)
+        grid.require_on_lattice(starts, name="segment_start_times")
+        return grid

gwmock_data/timeseries.py

@@ -0,0 +1,428 @@
+"""A uniformly sampled time series whose samples are a NumPy or a JAX array.
+
+:class:`TimeSeries` holds an array and the few numbers that place it in time: the GPS time of the
+first sample and the sample rate. Time runs along the **last** axis; leading axes are allowed and
+share that timing, so the strain of several detectors over one segment can be a single series of
+shape ``(n_detectors, n_samples)``.
+
+The array is kept as given. A NumPy array stays on the host, and a JAX array stays where it is,
+on a GPU included, through every method here: each works through the array's own namespace
+(``data.__array_namespace__()``), never by converting to NumPy. :meth:`TimeSeries.to_numpy` and
+:meth:`TimeSeries.to_jax` move data deliberately.
+
+The class is deliberately small. It has no arithmetic, spectral or plotting methods: code that
+needs them works on :attr:`TimeSeries.data`, and a caller who wants GWpy's API converts with
+:meth:`TimeSeries.to_gwpy`. Conversions to and from GWpy and PyCBC import those packages only when
+called.
+
+Under JAX, :func:`register_pytree` makes a series a pytree, so it passes through ``jax.jit`` and
+``jax.vmap``. The samples and ``t0`` are leaves; the sample rate, name and unit are static. The
+modules that use JAX register it; importing this module never imports JAX. JAX must be in 64-bit mode
+(``jax.config.update("jax_enable_x64", True)``): GPS times need float64, and in 32-bit mode the
+methods that would lose it raise instead.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import functools
+import math
+import sys
+import threading
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from gwmock_data._optional import require
+from gwmock_data.sampling_grid import SamplingGrid
+
+if TYPE_CHECKING:
+    from types import ModuleType
+
+    import gwpy.timeseries
+    import pycbc.types
+
+__all__ = ["TimeSeries", "as_timeseries", "register_pytree"]
+
+
+def _namespace(data: Any) -> ModuleType:
+    """Return the array namespace of ``data``: ``numpy``, ``jax.numpy``, or another array-API library."""
+    return data.__array_namespace__()
+
+
+@dataclass(frozen=True, eq=False)
+class TimeSeries:
+    """A uniformly sampled series: sample ``k`` along the last axis is at ``t0 + k / sample_rate``.
+
+    Args:
+        data: The samples, an array with at least one axis; time is the last. A NumPy or a JAX
+            array is kept as given. Anything else is converted with :func:`numpy.asarray`.
+        t0: GPS time of the first sample, in seconds.
+        sample_rate: Samples per second, in Hz.
+        name: Optional label, such as a detector or channel name. It labels the whole series.
+        unit: Optional unit of the samples, such as ``"strain"``.
+
+    Raises:
+        ValueError: If ``data`` has no axis, or ``t0`` or ``sample_rate`` is not finite, or
+            ``sample_rate`` is not positive.
+        TypeError: If ``t0`` is not a single number.
+
+    Two series are equal only if they are the same object: comparing arrays elementwise has no
+    single truth value, and a JAX array cannot be compared without a device round trip.
+    """
+
+    data: Any
+    t0: float
+    sample_rate: float
+    name: str | None = None
+    unit: str | None = None
+
+    def __post_init__(self) -> None:
+        """Validate the timing and normalise the samples to an array."""
+        data = self.data
+        if not hasattr(data, "__array_namespace__"):
+            data = np.asarray(data)
+            object.__setattr__(self, "data", data)
+        if len(data.shape) == 0:
+            raise ValueError("data must have at least one axis; time is the last.")
+        sample_rate = float(self.sample_rate)
+        if not (math.isfinite(sample_rate) and sample_rate > 0.0):
+            raise ValueError(f"sample_rate must be positive and finite; got {self.sample_rate!r}.")
+        object.__setattr__(self, "sample_rate", sample_rate)
+        try:
+            t0 = float(self.t0)
+        except TypeError as exc:
+            # A traced value inside a JAX transformation has no number yet to check; it was checked
+            # when the series entered the transformation. Matched by name so JAX is not imported.
+            if type(exc).__name__ == "ConcretizationTypeError":
+                return
+            raise TypeError(f"t0 must be a single number; got {self.t0!r}.") from exc
+        if not math.isfinite(t0):
+            raise ValueError(f"t0 must be finite; got {self.t0!r}.")
+        object.__setattr__(self, "t0", t0)
+
+    # ----------------------------------------------------------------------------------------
+    # Derived quantities
+
+    @property
+    def value(self) -> Any:
+        """The samples; an alias of :attr:`data`, the name GWpy uses."""
+        return self.data
+
+    @property
+    def xp(self) -> ModuleType:
+        """The array namespace of :attr:`data`, such as ``numpy`` or ``jax.numpy``."""
+        return _namespace(self.data)
+
+    @property
+    def n_samples(self) -> int:
+        """Number of samples along the time axis."""
+        return int(self.data.shape[-1])
+
+    @property
+    def dt(self) -> float:
+        """Seconds between samples."""
+        return 1.0 / self.sample_rate
+
+    @property
+    def duration(self) -> float:
+        """Seconds spanned by the samples: ``n_samples * dt``."""
+        return self.n_samples * self.dt
+
+    @property
+    def end(self) -> float:
+        """GPS time of the sample after the last, on the series' lattice: ``t0 + n_samples * dt``."""
+        return self._time_of(self.n_samples)
+
+    @property
+    def grid(self) -> SamplingGrid:
+        """The sample lattice of this series."""
+        return SamplingGrid(epoch=self.t0, sampling_frequency=self.sample_rate)
+
+    @property
+    def times(self) -> Any:
+        """GPS time of each sample, in the namespace of :attr:`data`, as float64.
+
+        Raises:
+            RuntimeError: If the namespace cannot hold float64, as JAX cannot outside its 64-bit
+                mode. In single precision a GPS time near 1.4e9 s resolves only to 128 s, so every
+                sample of a typical series would get the same time.
+        """
+        xp = self.xp
+        times = self.t0 + xp.arange(self.n_samples, dtype=xp.float64) * self.dt
+        if times.dtype != xp.float64:
+            raise RuntimeError(_NO_FLOAT64)
+        return times
+
+    # ----------------------------------------------------------------------------------------
+    # New series from this one
+
+    def with_data(self, data: Any) -> TimeSeries:
+        """Return a series with the same timing, name and unit, holding ``data``."""
+        return dataclasses.replace(self, data=data)
+
+    def copy(self) -> TimeSeries:
+        """Return a series whose samples are a copy of these."""
+        return self.with_data(self.xp.asarray(self.data, copy=True))
+
+    def crop(self, start: float | None = None, end: float | None = None) -> TimeSeries:
+        """Return the samples at GPS times in ``[start, end)``.
+
+        The bounds decide the result's length, so ``crop`` needs a concrete ``t0``: it cannot run
+        inside a JAX transformation over the series.
+
+        The result starts at the first sample at or after ``start`` and stops before the first at
+        or after ``end``. A bound that falls on a sample, to within the float64 resolution of GPS
+        times (:meth:`~gwmock_data.sampling_grid.SamplingGrid.lattice_tolerance_samples`), counts
+        as on it, so cropping at a sample's own timestamp keeps that sample however large the GPS
+        time. Bounds outside the series are clipped to it.
+
+        GWpy differs for a bound between samples: it rounds down, keeping the sample before
+        ``start``. Here every kept sample is at or after ``start``.
+
+        Args:
+            start: First GPS time to keep; ``None`` keeps from the first sample.
+            end: GPS time to stop before; ``None`` keeps to the last sample.
+
+        Returns:
+            The cropped series, possibly with no samples. Its samples are a view where the array
+            library makes one.
+
+        Raises:
+            ValueError: If a bound is not finite, or ``end`` is before ``start``.
+        """
+        for bound_name, bound in (("start", start), ("end", end)):
+            if bound is not None and not math.isfinite(bound):
+                raise ValueError(f"{bound_name} must be finite; got {bound!r}.")
+        if start is not None and end is not None and end < start:
+            raise ValueError(f"end ({end}) is before start ({start}).")
+        first = 0 if start is None else self._first_index_at_or_after(start)
+        stop = self.n_samples if end is None else self._first_index_at_or_after(end)
+        first = min(max(first, 0), self.n_samples)
+        stop = min(max(stop, first), self.n_samples)
+        return dataclasses.replace(self, data=self.data[..., first:stop], t0=self._time_of(first))
+
+    def pad(self, before: int = 0, after: int = 0) -> TimeSeries:
+        """Return the series with ``before`` zeros prepended and ``after`` appended, in samples.
+
+        ``t0`` moves back by ``before`` samples, so the existing samples keep their times. The
+        counts decide the result's length, so inside a JAX transformation they must be Python
+        integers, not traced values.
+
+        Raises:
+            ValueError: If either count is negative.
+        """
+        if before < 0 or after < 0:
+            raise ValueError(f"pad counts must not be negative; got before={before}, after={after}.")
+        xp = self.xp
+        lead = self.data.shape[:-1]
+        parts = [
+            xp.zeros((*lead, before), dtype=self.data.dtype),
+            self.data,
+            xp.zeros((*lead, after), dtype=self.data.dtype),
+        ]
+        return dataclasses.replace(self, data=xp.concatenate(parts, axis=-1), t0=self._time_of(-before))
+
+    def is_compatible(self, other: TimeSeries) -> bool:
+        """Return whether ``other`` has the same sample rate and unit, so the two can be combined."""
+        return self.sample_rate == other.sample_rate and self.unit == other.unit
+
+    def _time_of(self, index: int) -> Any:
+        # The arithmetic of SamplingGrid.time_of, written out so it also works on a traced t0.
+        return self.t0 + index * self.dt
+
+    def _first_index_at_or_after(self, gps_time: float) -> int:
+        grid = self.grid
+        exact = float(grid.index_of(gps_time))
+        return math.ceil(exact - grid.lattice_tolerance_samples(gps_time))
+
+    def __array__(self, dtype: Any = None, copy: bool | None = None) -> np.ndarray:
+        """Return the samples as a NumPy array, so ``numpy.asarray(series)`` works as for GWpy.
+
+        Follows NumPy's protocol: ``copy=True`` always copies, ``None`` copies only when the dtype
+        or the array library requires it, and ``False`` raises ``ValueError`` when a copy would be
+        required -- a dtype change, or samples that are not a NumPy array.
+        """
+        needs_copy = not isinstance(self.data, np.ndarray) or (dtype is not None and np.dtype(dtype) != self.data.dtype)
+        if copy is False and needs_copy:
+            raise ValueError("these samples cannot be returned as a NumPy array without a copy.")
+        array = np.asarray(self.data, dtype=dtype)
+        return np.array(array, copy=True) if copy else array
+
+    # ----------------------------------------------------------------------------------------
+    # Moving data and converting
+
+    def to_numpy(self) -> TimeSeries:
+        """Return the series with its samples as a NumPy array on the host."""
+        return self.with_data(np.asarray(self.data))
+
+    def to_jax(self, device: Any = None) -> TimeSeries:
+        """Return the series with its samples as a JAX array, on ``device`` if given.
+
+        Raises:
+            ModuleNotFoundError: If JAX is not installed.
+            RuntimeError: If JAX is not in 64-bit mode, in which it would round double-precision
+                samples to single precision.
+        """
+        jax = require("jax", "jax", "TimeSeries.to_jax")
+        _require_x64(jax)
+        return self.with_data(jax.device_put(jax.numpy.asarray(self.data), device))
+
+    def to_gwpy(self) -> gwpy.timeseries.TimeSeries:
+        """Return a GWpy ``TimeSeries`` with the same samples, timing, name and unit.
+
+        NumPy samples are shared, not copied, as :meth:`from_gwpy` shares GWpy's, so a write through
+        either object is seen by the other. JAX samples are brought to the host with
+        :func:`numpy.asarray`; for a CPU array that is a read-only view of JAX's buffer.
+
+        Raises:
+            ValueError: If the series has more than one axis; GWpy's is one-dimensional.
+            ModuleNotFoundError: If GWpy is not installed.
+        """
+        if len(self.data.shape) != 1:
+            raise ValueError(f"a GWpy TimeSeries is one-dimensional; this series has shape {tuple(self.data.shape)}.")
+        timeseries = require("gwpy.timeseries", "gwpy", "TimeSeries.to_gwpy")
+        return timeseries.TimeSeries(
+            np.asarray(self.data),
+            t0=self.t0,
+            sample_rate=self.sample_rate,
+            name=self.name,
+            unit=self.unit,
+            copy=False,
+        )
+
+    @classmethod
+    def from_gwpy(cls, series: gwpy.timeseries.TimeSeries) -> TimeSeries:
+        """Return a series with the samples, timing, name and unit of a GWpy ``TimeSeries``.
+
+        The samples are GWpy's array itself, not a copy. A dimensionless GWpy series gets
+        ``unit=None``.
+
+        Raises:
+            ValueError: If the GWpy series is irregularly sampled.
+        """
+        try:
+            sample_rate = series.sample_rate.to_value("Hz")
+        except AttributeError as exc:
+            # GWpy has no sample rate for a series built from an explicit, irregular times array.
+            raise ValueError(
+                "a TimeSeries is uniformly sampled; this GWpy series has an irregular time index."
+            ) from exc
+        unit = series.unit.to_string() if series.unit is not None else ""
+        return cls(
+            series.value,
+            t0=series.t0.to_value("s"),
+            sample_rate=sample_rate,
+            name=None if series.name is None else str(series.name),
+            unit=unit or None,
+        )
+
+    def to_pycbc(self) -> pycbc.types.TimeSeries:
+        """Return a PyCBC ``TimeSeries`` with the same samples and timing.
+
+        PyCBC series carry neither a name nor a unit.
+
+        Raises:
+            ValueError: If the series has more than one axis; PyCBC's is one-dimensional.
+            ModuleNotFoundError: If PyCBC is not installed.
+        """
+        if len(self.data.shape) != 1:
+            raise ValueError(f"a PyCBC TimeSeries is one-dimensional; this series has shape {tuple(self.data.shape)}.")
+        types = require("pycbc.types", "pycbc", "TimeSeries.to_pycbc")
+        return types.TimeSeries(np.asarray(self.data), delta_t=self.dt, epoch=self.t0)
+
+    @classmethod
+    def from_pycbc(
+        cls, series: pycbc.types.TimeSeries, *, name: str | None = None, unit: str | None = None
+    ) -> TimeSeries:
+        """Return a series with the samples and timing of a PyCBC ``TimeSeries``."""
+        return cls(
+            np.asarray(series.numpy()),
+            t0=float(series.start_time),
+            sample_rate=float(series.sample_rate),
+            name=name,
+            unit=unit,
+        )
+
+
+def as_timeseries(series: TimeSeries | gwpy.timeseries.TimeSeries) -> TimeSeries:
+    """Return ``series`` as a :class:`TimeSeries`: itself, or converted from a GWpy ``TimeSeries``.
+
+    Functions that take a time series call this on their input, so they accept either kind.
+
+    Raises:
+        TypeError: If ``series`` is neither.
+    """
+    if isinstance(series, TimeSeries):
+        return series
+    # A GWpy series can only exist if GWpy is imported, so it is not imported here to find out.
+    gwpy_timeseries = sys.modules.get("gwpy.timeseries")
+    if gwpy_timeseries is not None and isinstance(series, gwpy_timeseries.TimeSeries):
+        return TimeSeries.from_gwpy(series)
+    raise TypeError(f"expected a gwmock_data.TimeSeries or a gwpy.timeseries.TimeSeries; got {type(series).__name__}.")
+
+
+_NO_FLOAT64 = (
+    "TimeSeries needs float64 timing, which this array library is not providing; with JAX, call "
+    'jax.config.update("jax_enable_x64", True) first. '
+    "In single precision a GPS time near 1.4e9 s resolves only to 128 s, so every sample of "
+    "a typical series would get the same time."
+)
+
+
+def _require_x64(jax: ModuleType) -> None:
+    """Refuse, rather than degrade, when JAX is in 32-bit mode."""
+    if not jax.config.jax_enable_x64:
+        raise RuntimeError(_NO_FLOAT64)
+
+
+#: Serialises the first registrations: the cache alone lets concurrent first calls both run.
+_REGISTRATION_LOCK = threading.Lock()
+
+
+def register_pytree() -> None:
+    """Register :class:`TimeSeries` as a JAX pytree; safe to call more than once, from any thread.
+
+    The samples and ``t0`` are leaves, so a batch of series differing in start time can be mapped
+    over without recompiling. The sample rate, name and unit are static: they decide shapes and
+    meaning, not values.
+
+    Unflattening bypasses validation, because inside a transformation the leaves are tracers,
+    which cannot be checked as numbers. A series rebuilt with its start time as a JAX array that is
+    not float64 -- what ``jit``, ``vmap``, ``grad`` and ``device_put`` produce in JAX's 32-bit mode --
+    raises ``RuntimeError``; structural uses that leave it a Python float, such as ``jax.tree.map``
+    or ``jax.device_get``, work in either mode.
+
+    Raises:
+        ModuleNotFoundError: If JAX is not installed.
+    """
+    with _REGISTRATION_LOCK:
+        _register_pytree_once()
+
+
+# Cached, so registration, which JAX keeps per process, happens once.
+@functools.cache
+def _register_pytree_once() -> None:
+    jax = require("jax", "jax", "Registering TimeSeries with JAX")
+    tree_util = jax.tree_util
+
+    def flatten(series: TimeSeries) -> tuple[tuple[Any, Any], tuple[float, str | None, str | None]]:
+        return (series.data, series.t0), (series.sample_rate, series.name, series.unit)
+
+    def unflatten(static: tuple[float, str | None, str | None], leaves: tuple[Any, Any]) -> TimeSeries:
+        # Checked where it can go wrong: JAX has turned t0 into one of its arrays -- a tracer under
+        # jit, vmap or grad, or a device array after device_put -- and, in 32-bit mode, a
+        # single-precision one, which cannot tell samples apart. A tree map or device_get that
+        # leaves t0 a Python float passes in either mode.
+        t0 = leaves[1]
+        if isinstance(t0, jax.Array) and t0.dtype != jax.numpy.float64:
+            raise RuntimeError(_NO_FLOAT64)
+        series = object.__new__(TimeSeries)
+        for field_name, value in zip(("data", "t0"), leaves, strict=True):
+            object.__setattr__(series, field_name, value)
+        for field_name, value in zip(("sample_rate", "name", "unit"), static, strict=True):
+            object.__setattr__(series, field_name, value)
+        return series
+
+    tree_util.register_pytree_node(TimeSeries, flatten, unflatten)

gwmock_data/version.py

@@ -0,0 +1,11 @@
+"""A script to infer the version number from the metadata."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("gwmock_data")
+except PackageNotFoundError:
+    # Fallback for source checkouts or environments without installed metadata.
+    __version__ = "0+unknown"

gwmock_data-0.1.0.dist-info/METADATA

@@ -0,0 +1,59 @@
+Metadata-Version: 2.5
+Name: gwmock-data
+Version: 0.1.0
+Summary: Shared data structures for the gwmock packages
+Project-URL: Documentation, https://leuven-gravity-institute.github.io/gwmock-data
+Project-URL: Source, https://github.com/Leuven-Gravity-Institute/gwmock-data
+Project-URL: Tracker, https://github.com/Leuven-Gravity-Institute/gwmock-data/issues
+Project-URL: Home, https://github.com/Leuven-Gravity-Institute/gwmock-data
+Project-URL: Release Notes, https://github.com/Leuven-Gravity-Institute/gwmock-data/releases
+Author: Isaac C. F. Wong
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Requires-Python: >=3.13
+Requires-Dist: numpy>=2.2
+Provides-Extra: gwpy
+Requires-Dist: gwpy>=4.0.0; extra == 'gwpy'
+Provides-Extra: hdf5
+Requires-Dist: h5py>=3.12; extra == 'hdf5'
+Provides-Extra: jax
+Requires-Dist: jax>=0.5.0; extra == 'jax'
+Provides-Extra: pycbc
+Requires-Dist: pycbc>=2.6.0; extra == 'pycbc'
+Description-Content-Type: text/markdown
+
+# gwmock-data
+
+[![Python CI](https://github.com/Leuven-Gravity-Institute/gwmock-data/actions/workflows/ci.yml/badge.svg)](https://github.com/Leuven-Gravity-Institute/gwmock-data/actions/workflows/ci.yml)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/Leuven-Gravity-Institute/gwmock-data/main.svg)](https://results.pre-commit.ci/latest/github/Leuven-Gravity-Institute/gwmock-data/main)
+[![Documentation Status](https://github.com/Leuven-Gravity-Institute/gwmock-data/actions/workflows/documentation.yml/badge.svg)](https://leuven-gravity-institute.github.io/gwmock-data/)
+[![codecov](https://codecov.io/gh/Leuven-Gravity-Institute/gwmock-data/graph/badge.svg)](https://codecov.io/gh/Leuven-Gravity-Institute/gwmock-data)
+[![PyPI Version](https://img.shields.io/pypi/v/gwmock-data)](https://pypi.org/project/gwmock-data/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/gwmock-data)](https://pypi.org/project/gwmock-data/)
+[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](LICENSE)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![SPEC 0 — Minimum Supported Dependencies](https://img.shields.io/badge/SPEC-0-green?labelColor=%23004811&color=%235CA038)](https://scientific-python.org/specs/spec-0000/)
+
+Shared data structures for the gwmock packages: the types they pass between each
+other, so every package reads and writes them the same way.
+
+## Installation
+
+```bash
+pip install gwmock-data
+```
+
+## Development
+
+```bash
+uv sync --group dev
+uv run pytest
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).

gwmock_data-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+gwmock_data/__init__.py,sha256=v0iS9KHxSpL9jjQZbgfSx4UhU7J1Cj_cSHaDMHFYpbo,547
+gwmock_data/_optional.py,sha256=v4k7eNEzYhWQtKUgo5Y9QsTvxLa1-0Hi97tCuFBOLMQ,1395
+gwmock_data/sampling_grid.py,sha256=wZQp1d-u1dJsclZAfdaNK2XXCJkpsJH1NoN08yomYC4,7995
+gwmock_data/timeseries.py,sha256=rCN24Rrh4hanBOibnpUZeTu5LCMZROhfe0fK51O6kbQ,19187
+gwmock_data/version.py,sha256=hv5yYdb-Wkr9lKNCSZSQrMnjNoKnaUBK05xgKDhDoEY,346
+gwmock_data/io/__init__.py,sha256=GD3HMrdLrRg2VYbtKvXQC89YpI1HozWEoqzjqijEwxg,169
+gwmock_data/io/hdf5.py,sha256=HdAjIjMpz6xU6dh7BWuTG7701yUmizQrd3snf3t-IYc,3675
+gwmock_data-0.1.0.dist-info/METADATA,sha256=XsF8cDdtt8_96Epi-pii65H2hN80N6uyg35UDm9sbT0,2938
+gwmock_data-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+gwmock_data-0.1.0.dist-info/licenses/LICENSE,sha256=9k1btU36CFFvEBAdimpM63ozNUIPDwhowqECuviFuLw,1481
+gwmock_data-0.1.0.dist-info/RECORD,,

gwmock_data-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

gwmock_data-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,26 @@
+Copyright 2026, Isaac C. F. Wong
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software without
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.