pluscross 0.1.0__tar.gz

pluscross-0.1.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: pluscross
+Version: 0.1.0
+Summary: IO for the waveform_catalog HDF5 format: frequency-domain waveform polarization catalogs
+Keywords: gravitational-waves,hdf5,waveforms
+Author: Bernardo Veronese
+Author-email: Bernardo Veronese <bernardopveronese@gmail.com>
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Dist: numpy>=1.26
+Requires-Dist: h5py>=3.10
+Requires-Dist: pytest>=8 ; extra == 'test'
+Requires-Python: >=3.11
+Project-URL: Repository, https://github.com/binado/pluscross
+Project-URL: Issues, https://github.com/binado/pluscross/issues
+Provides-Extra: test
+Description-Content-Type: text/markdown
+
+# pluscross (Python)
+
+Pure-IO implementation of the `waveform_catalog` HDF5 format (see `../SPEC.md`):
+catalogs of frequency-domain waveform polarizations.
+
+## Installation
+
+```sh
+pip install pluscross
+```
+
+From source:
+
+```sh
+git clone https://github.com/binado/pluscross
+cd pluscross/python
+uv sync --extra test
+```
+
+```python
+import numpy as np
+
+from pluscross import WaveformCatalog, save_catalog, load_catalog
+
+catalog = WaveformCatalog(
+    frequencies=np.array([20.0, 30.0, 40.0]),
+    plus=np.array([[1.0 + 0.1j, 2.0 + 0.2j, 3.0 + 0.3j]]),
+    cross=np.array([[0.5 - 0.1j, 1.0 - 0.2j, 1.5 - 0.3j]]),
+    source_parameters={"mass_1": np.array([35.0]), "mass_2": np.array([30.0])},
+    approximant="IMRPhenomXAS",
+    minimum_frequency=20.0,
+    maximum_frequency=40.0,
+    reference_frequency=20.0,
+    sampling_frequency=4096.0,
+)
+
+catalog.save("catalog.h5")
+loaded = WaveformCatalog.load("catalog.h5")
+
+loaded.frequencies    # (nfreq,) float64
+loaded.plus           # (nsamples, nfreq) complex128
+loaded.cross          # (nsamples, nfreq) complex128
+loaded.source_parameters  # dict[str, (nsamples,) float64]
+
+save_catalog("copy.h5", loaded)
+copy = load_catalog("copy.h5")
+copy.source_parameters
+```
+
+No derived quantities (e.g. polarization power) are computed here — consumers do
+that themselves.
+
+Run tests with `uv run --extra test pytest tests/`.

pluscross-0.1.0/README.md

@@ -0,0 +1,53 @@
+# pluscross (Python)
+
+Pure-IO implementation of the `waveform_catalog` HDF5 format (see `../SPEC.md`):
+catalogs of frequency-domain waveform polarizations.
+
+## Installation
+
+```sh
+pip install pluscross
+```
+
+From source:
+
+```sh
+git clone https://github.com/binado/pluscross
+cd pluscross/python
+uv sync --extra test
+```
+
+```python
+import numpy as np
+
+from pluscross import WaveformCatalog, save_catalog, load_catalog
+
+catalog = WaveformCatalog(
+    frequencies=np.array([20.0, 30.0, 40.0]),
+    plus=np.array([[1.0 + 0.1j, 2.0 + 0.2j, 3.0 + 0.3j]]),
+    cross=np.array([[0.5 - 0.1j, 1.0 - 0.2j, 1.5 - 0.3j]]),
+    source_parameters={"mass_1": np.array([35.0]), "mass_2": np.array([30.0])},
+    approximant="IMRPhenomXAS",
+    minimum_frequency=20.0,
+    maximum_frequency=40.0,
+    reference_frequency=20.0,
+    sampling_frequency=4096.0,
+)
+
+catalog.save("catalog.h5")
+loaded = WaveformCatalog.load("catalog.h5")
+
+loaded.frequencies    # (nfreq,) float64
+loaded.plus           # (nsamples, nfreq) complex128
+loaded.cross          # (nsamples, nfreq) complex128
+loaded.source_parameters  # dict[str, (nsamples,) float64]
+
+save_catalog("copy.h5", loaded)
+copy = load_catalog("copy.h5")
+copy.source_parameters
+```
+
+No derived quantities (e.g. polarization power) are computed here — consumers do
+that themselves.
+
+Run tests with `uv run --extra test pytest tests/`.

pluscross-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "pluscross"
+version = "0.1.0"
+description = "IO for the waveform_catalog HDF5 format: frequency-domain waveform polarization catalogs"
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{ name = "Bernardo Veronese", email = "bernardopveronese@gmail.com" }]
+license = "MIT"
+keywords = ["gravitational-waves", "hdf5", "waveforms"]
+classifiers = [
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Astronomy",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+dependencies = [
+    "numpy>=1.26",
+    "h5py>=3.10",
+]
+
+[project.urls]
+Repository = "https://github.com/binado/pluscross"
+Issues = "https://github.com/binado/pluscross/issues"
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[dependency-groups]
+dev = ["ruff>=0.9", "ty>=0.0.1a"]
+
+[build-system]
+requires = ["uv_build>=0.11,<0.12"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

pluscross-0.1.0/src/pluscross/__init__.py

@@ -0,0 +1,229 @@
+"""IO for the ``waveform_catalog`` HDF5 format (see SPEC.md at the repo root).
+
+Stores catalogs of frequency-domain waveform polarizations: complex ``h_plus`` /
+``h_cross`` on a shared frequency axis, per-sample source parameters, and the
+waveform-generation attributes. Pure IO: no derived quantities are computed here.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from importlib.metadata import version as _version
+from pathlib import Path
+
+import h5py
+import numpy as np
+from numpy.typing import NDArray
+
+from .utils import frequency_array
+
+__version__ = _version("pluscross")
+
+__all__ = [
+    "WaveformCatalog",
+    "save_catalog",
+    "load_catalog",
+    "frequency_array",
+    "__version__",
+]
+
+FORMAT_NAME = "waveform_catalog"
+FORMAT_VERSION = 1
+DOMAIN_FREQUENCY = "frequency"
+
+#: Target uncompressed chunk size in complex128 elements (~64 MiB).
+_CHUNK_ELEMENTS = 2**22
+
+
+@dataclass(frozen=True)
+class WaveformCatalog:
+    """In-memory frequency-domain waveform polarization catalog.
+
+    ``plus`` and ``cross`` have shape ``(nsamples, nfreq)`` — sample axis
+    first, matching the on-disk C-order layout.
+    """
+
+    frequencies: NDArray[np.float64]
+    plus: NDArray[np.complex128]
+    cross: NDArray[np.complex128]
+    source_parameters: dict[str, NDArray[np.float64]] = field(default_factory=dict)
+    approximant: str = ""
+    minimum_frequency: float = 0.0
+    maximum_frequency: float = 0.0
+    reference_frequency: float = 0.0
+    sampling_frequency: float = 0.0
+
+    def __post_init__(self) -> None:
+        object.__setattr__(
+            self, "frequencies", np.asarray(self.frequencies, dtype=np.float64)
+        )
+        object.__setattr__(self, "plus", np.asarray(self.plus, dtype=np.complex128))
+        object.__setattr__(self, "cross", np.asarray(self.cross, dtype=np.complex128))
+        object.__setattr__(
+            self,
+            "source_parameters",
+            {
+                name: np.asarray(values, dtype=np.float64)
+                for name, values in self.source_parameters.items()
+            },
+        )
+        _validate_arrays(
+            self.frequencies, self.plus, self.cross, self.source_parameters
+        )
+
+    @property
+    def nfreq(self) -> int:
+        return self.frequencies.shape[0]
+
+    @property
+    def nsamples(self) -> int:
+        return self.plus.shape[0]
+
+    def save(self, path: str | Path) -> None:
+        """Write this catalog to ``path`` in waveform_catalog format v1."""
+        save_catalog(path, self)
+
+    @classmethod
+    def load(cls, path: str | Path) -> WaveformCatalog:
+        """Read a waveform_catalog v1 file into a catalog."""
+        return load_catalog(path)
+
+
+def _validate_arrays(
+    frequencies: NDArray[np.float64],
+    plus: NDArray[np.complex128],
+    cross: NDArray[np.complex128],
+    source_parameters: dict[str, NDArray[np.float64]],
+    label: str = "WaveformCatalog",
+) -> None:
+    if frequencies.ndim != 1:
+        raise ValueError(f"{label}: frequencies must be one-dimensional")
+    if frequencies.shape[0] > 1 and not np.all(np.diff(frequencies) > 0.0):
+        raise ValueError(f"{label}: frequencies must be strictly increasing")
+    if plus.ndim != 2 or cross.ndim != 2:
+        raise ValueError(f"{label}: plus and cross must be two-dimensional")
+    if plus.shape != cross.shape:
+        raise ValueError(
+            f"{label}: plus {plus.shape} and cross {cross.shape} shapes differ"
+        )
+    if plus.shape[1] != frequencies.shape[0]:
+        raise ValueError(
+            f"{label}: polarization frequency axis ({plus.shape[1]}) does not "
+            f"match frequencies ({frequencies.shape[0]})"
+        )
+    nsamples = plus.shape[0]
+    for name, values in source_parameters.items():
+        if values.ndim != 1 or values.shape[0] != nsamples:
+            raise ValueError(
+                f"{label}: source parameter {name!r} must be 1-D with length "
+                f"{nsamples}, got shape {values.shape}"
+            )
+
+
+def _chunks(nsamples: int, nfreq: int) -> tuple[int, int]:
+    """On-disk C-order chunk shape: full frequency rows for a bounded sample count."""
+    per_chunk = min(nsamples, max(1, _CHUNK_ELEMENTS // max(nfreq, 1)))
+    return (per_chunk, nfreq)
+
+
+def save_catalog(path: str | Path, catalog: WaveformCatalog) -> None:
+    """Write ``catalog`` to ``path`` in waveform_catalog format v1."""
+    nsamples, nfreq = catalog.plus.shape
+    with h5py.File(path, "w") as f:
+        f.attrs["format_name"] = FORMAT_NAME
+        f.attrs["format_version"] = np.int64(FORMAT_VERSION)
+        f.attrs["domain"] = DOMAIN_FREQUENCY
+        f.attrs["approximant"] = catalog.approximant
+        f.attrs["minimum_frequency"] = np.float64(catalog.minimum_frequency)
+        f.attrs["maximum_frequency"] = np.float64(catalog.maximum_frequency)
+        f.attrs["reference_frequency"] = np.float64(catalog.reference_frequency)
+        f.attrs["sampling_frequency"] = np.float64(catalog.sampling_frequency)
+
+        f.create_dataset("frequencies", data=catalog.frequencies)
+        pol = f.create_group("polarizations")
+        chunks = _chunks(nsamples, nfreq)
+        for name, data in (("plus", catalog.plus), ("cross", catalog.cross)):
+            pol.create_dataset(
+                name,
+                data=np.ascontiguousarray(data),
+                chunks=chunks,
+                compression="gzip",
+            )
+        params = f.create_group("source_parameters")
+        for name, values in catalog.source_parameters.items():
+            params.create_dataset(name, data=values)
+
+
+def _require_attr(f: h5py.File, name: str, label: str) -> str | int | float:
+    if name not in f.attrs:
+        raise ValueError(f"{label}: missing required attribute {name!r}")
+    value = f.attrs[name]
+    if isinstance(value, bytes):
+        return value.decode()
+    if isinstance(value, (str, int, float, np.integer, np.floating)):
+        # np.integer/np.floating satisfy int()/float(); plain cast for typing.
+        return value  # type: ignore[return-value]
+    raise ValueError(f"{label}: attribute {name!r} has unsupported type")
+
+
+def _require_dataset(f: h5py.File, key: str, label: str) -> h5py.Dataset:
+    if key not in f:
+        raise ValueError(f"{label}: missing required object {key!r}")
+    obj = f[key]
+    if not isinstance(obj, h5py.Dataset):
+        raise ValueError(f"{label}: {key!r} is not a dataset")
+    return obj
+
+
+def load_catalog(path: str | Path) -> WaveformCatalog:
+    """Read a waveform_catalog v1 file into a :class:`WaveformCatalog`."""
+    label = Path(path).name
+    with h5py.File(path, "r") as f:
+        format_name = str(_require_attr(f, "format_name", label))
+        if format_name != FORMAT_NAME:
+            raise ValueError(
+                f"{label}: format_name is {format_name!r}, expected {FORMAT_NAME!r}"
+            )
+        version = int(_require_attr(f, "format_version", label))
+        if version != FORMAT_VERSION:
+            raise ValueError(
+                f"{label}: format_version is {version}, expected {FORMAT_VERSION}"
+            )
+        domain = str(_require_attr(f, "domain", label))
+        if domain != DOMAIN_FREQUENCY:
+            raise ValueError(
+                f"{label}: domain is {domain!r}, expected {DOMAIN_FREQUENCY!r}"
+            )
+        approximant = str(_require_attr(f, "approximant", label))
+        physics = {
+            name: float(_require_attr(f, name, label))
+            for name in (
+                "minimum_frequency",
+                "maximum_frequency",
+                "reference_frequency",
+                "sampling_frequency",
+            )
+        }
+
+        frequencies = np.asarray(_require_dataset(f, "frequencies", label)[...])
+        plus = np.asarray(_require_dataset(f, "polarizations/plus", label)[...])
+        cross = np.asarray(_require_dataset(f, "polarizations/cross", label)[...])
+        source_parameters: dict[str, NDArray[np.float64]] = {}
+        if "source_parameters" in f:
+            group = f["source_parameters"]
+            if not isinstance(group, h5py.Group):
+                raise ValueError(f"{label}: 'source_parameters' is not a group")
+            for name in (str(k) for k in group):
+                source_parameters[name] = np.asarray(
+                    _require_dataset(f, f"source_parameters/{name}", label)[...]
+                )
+
+    _validate_arrays(frequencies, plus, cross, source_parameters, label=label)
+    return WaveformCatalog(
+        frequencies=frequencies,
+        plus=plus,
+        cross=cross,
+        source_parameters=source_parameters,
+        approximant=approximant,
+        **physics,
+    )

pluscross-0.1.0/src/pluscross/utils.py

@@ -0,0 +1,66 @@
+"""Frequency-axis helpers, independent of the ``waveform_catalog`` IO format."""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+
+__all__ = ["frequency_array"]
+
+
+def frequency_array(
+    *,
+    sampling_frequency: float,
+    duration: float,
+    minimum_frequency: float,
+    maximum_frequency: float,
+) -> tuple[NDArray[np.float64], NDArray[np.bool_]]:
+    """Build the 0-to-Nyquist frequency axis and an in-band mask.
+
+    Returns ``(frequencies, in_band_mask)``: ``frequencies`` runs from 0 Hz to
+    the Nyquist frequency (``sampling_frequency / 2``) in steps of
+    ``1 / duration``, and ``in_band_mask`` is ``True`` where
+    ``minimum_frequency <= frequencies <= maximum_frequency``.
+
+    ``duration * sampling_frequency`` must be an even integer (the number of
+    time-domain samples), so the grid spacing is exactly ``1 / duration`` and
+    the last frequency lands exactly on the Nyquist frequency.
+    """
+    if sampling_frequency <= 0.0:
+        raise ValueError(
+            f"sampling_frequency must be positive, got {sampling_frequency}"
+        )
+    if duration <= 0.0:
+        raise ValueError(f"duration must be positive, got {duration}")
+    nyquist_frequency = sampling_frequency / 2.0
+    if not (0.0 <= minimum_frequency <= maximum_frequency <= nyquist_frequency):
+        raise ValueError(
+            "expected 0 <= minimum_frequency <= maximum_frequency <= "
+            f"nyquist_frequency ({nyquist_frequency}), got "
+            f"minimum_frequency={minimum_frequency}, "
+            f"maximum_frequency={maximum_frequency}"
+        )
+
+    n_samples_exact = duration * sampling_frequency
+    n_samples = round(n_samples_exact)
+    tolerance = 4.0 * np.finfo(np.float64).eps * max(1.0, abs(n_samples_exact))
+    if abs(n_samples_exact - n_samples) > tolerance:
+        raise ValueError(
+            "duration * sampling_frequency must be an integer number of "
+            f"samples, got duration={duration}, "
+            f"sampling_frequency={sampling_frequency} "
+            f"({n_samples_exact} samples)"
+        )
+    if n_samples % 2 != 0:
+        raise ValueError(
+            "duration * sampling_frequency must be an even integer so the "
+            "frequency grid reaches the Nyquist frequency exactly, got "
+            f"{n_samples} samples (duration={duration}, "
+            f"sampling_frequency={sampling_frequency})"
+        )
+
+    frequencies = np.fft.rfftfreq(n_samples, d=1.0 / sampling_frequency)
+    in_band_mask = (frequencies >= minimum_frequency) & (
+        frequencies <= maximum_frequency
+    )
+    return frequencies, in_band_mask