nullcal 0.2.0__py3-none-any.whl

nullcal/utils/log.py

@@ -0,0 +1,72 @@
+"""
+Functions for logging.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from ..version import __version__
+
+
+def get_version_information() -> str:
+    """Get the version information.
+
+    Returns:
+        str: Version information.
+    """
+
+    return __version__
+
+
+def setup_logger(
+    outdir: str = ".", label: str | None = None, log_level: str | int = "INFO", print_version: bool = False
+):
+    """Setup logging output: call at the start of the script to use
+
+    Args:
+        outdir (str, optional): If supplied, write the logging output to outdir/label.log. Defaults to '.'.
+        label (str, optional): If supplied, write the logging output to outdir/label.log. Defaults to None.
+        log_level (str, optional): ['debug', 'info', 'warning']
+            Either a string from the list above, or an integer as specified
+            in https://docs.python.org/2/library/logging.html#logging-levels
+            Defaults to 'INFO'.
+        print_version (bool): If true, print version information. Defaults to False.
+    """
+
+    if isinstance(log_level, str):
+        try:
+            level = getattr(logging, log_level.upper())
+        except AttributeError as err:
+            raise ValueError(f"log_level {log_level} not understood") from err
+    else:
+        level = int(log_level)
+
+    logger = logging.getLogger("nullcal")
+    logger.propagate = False
+    logger.setLevel(level)
+
+    if not any(isinstance(h, logging.StreamHandler) for h in logger.handlers):
+        stream_handler = logging.StreamHandler()
+        stream_handler.setFormatter(
+            logging.Formatter("%(asctime)s %(name)s %(levelname)-8s: %(message)s", datefmt="%H:%M")
+        )
+        stream_handler.setLevel(level)
+        logger.addHandler(stream_handler)
+
+    if not any(isinstance(h, logging.FileHandler) for h in logger.handlers) and label:
+        Path(outdir).mkdir(parents=True, exist_ok=True)
+        log_file = f"{outdir}/{label}.log"
+        file_handler = logging.FileHandler(log_file)
+        file_handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)-8s: %(message)s", datefmt="%H:%M"))
+
+        file_handler.setLevel(level)
+        logger.addHandler(file_handler)
+
+    for handler in logger.handlers:
+        handler.setLevel(level)
+
+    if print_version:
+        version = get_version_information()
+        logger.info("Running nullcal version: %s", version)

nullcal/utils/snr.py

@@ -0,0 +1,29 @@
+"""
+Helper functions to compute signal-to-noise ratio.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def optimal_uncorrelated_null_stream_snr_squared(signals, power_spectral_densities, duration):
+    """Compute the optimal uncorrelated null stream
+    signal-to-noise ratio. The interferometers are
+    assumed to be uncorrelated to each other.
+
+    Args:
+        signals (array-like): Frequency domain signals in the interferometers (detector, frequency).
+        power_spectral_densities (array-like): Noise power spectral densities of the interferometers
+            (detector, frequency).
+        duration (float): Duration in second.
+
+    Returns:
+        float: Optimal signal-to-noise ratio squared of uncorrelated null stream.
+    """
+    # Direct sum of the signals
+    null_stream = np.sum(signals, axis=0) / np.sqrt(len(signals))
+
+    # Power spectral density
+    power_spectral_density = np.sum(power_spectral_densities, axis=0) / len(power_spectral_densities)
+    return 4.0 / duration * np.sum(np.conj(null_stream) * null_stream / power_spectral_density)

nullcal/version.py

@@ -0,0 +1,9 @@
+"""
+Version of the package.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import version
+
+__version__ = version("nullcal")

nullcal-0.2.0.dist-info/METADATA

@@ -0,0 +1,222 @@
+Metadata-Version: 2.5
+Name: nullcal
+Version: 0.2.0
+Summary: A package to constrain calibration errors of a closed-geometry network of gravitational-wave detectors.
+Project-URL: Source, https://github.com/Leuven-Gravity-Institute/nullcal
+Project-URL: Tracker, https://github.com/Leuven-Gravity-Institute/nullcal/issues
+Author-email: "Isaac C. F. Wong" <chunfung.wong@kuleuven.be>, Milan Wils <milan.wils@kuleuven.be>, Francesco Cireddu <francesco.cireddu@kuleuven.be>
+License: MIT License
+        
+        Copyright (c) 2025 Chun-Fung Wong
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.12
+Requires-Dist: blackjax>=1.6.2
+Requires-Dist: jax>=0.11.1
+Requires-Dist: numpy>=1.26.4
+Requires-Dist: pandas>=2.3.3
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: scipy>=1.16.3
+Provides-Extra: cuda
+Requires-Dist: jax[cuda13]>=0.11.1; (sys_platform == 'linux') and extra == 'cuda'
+Provides-Extra: jax
+Requires-Dist: jax>=0.11.1; extra == 'jax'
+Description-Content-Type: text/markdown
+
+# nullcal
+
+[![Python CI](https://github.com/Leuven-Gravity-Institute/nullcal/actions/workflows/ci.yml/badge.svg)](https://github.com/Leuven-Gravity-Institute/nullcal/actions/workflows/ci.yml)
+[![Documentation Status](https://github.com/Leuven-Gravity-Institute/nullcal/actions/workflows/documentation.yml/badge.svg)](https://leuven-gravity-institute.github.io/nullcal)
+[![codecov](https://codecov.io/gh/Leuven-Gravity-Institute/nullcal/branch/main/graph/badge.svg)](https://codecov.io/gh/Leuven-Gravity-Institute/nullcal)
+[![PyPI Version](https://img.shields.io/pypi/v/nullcal)](https://pypi.org/project/nullcal/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/nullcal)](https://pypi.org/project/nullcal/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-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)
+[![DOI](https://zenodo.org/badge/ID.svg)](https://doi.org/DOI)
+
+A Python package for constraining calibration errors of a closed-geometry
+network of gravitational-wave detectors. It provides the null stream formalism
+for noise-only data combinations and Bayesian recalibration likelihoods to
+quantify detector miscalibration.
+
+## Features
+
+- **Null stream construction** for closed-geometry detector networks
+- **Calibration error constraint** via Bayesian recalibration likelihood
+- **Time-frequency transforms** (Short-Time Fourier Transform, wavelet
+  transforms)
+- **Clustering algorithms** for time-frequency map analysis
+- **Modular architecture** with clean separation between null stream,
+  likelihood, calibration, immutable data, result, and utility layers
+
+## Installation
+
+We recommend using `uv` to manage virtual environments for installing nullcal.
+
+If you don't have `uv` installed, you can install it with pip. See the project
+pages for more details:
+
+- Install via pip: `pip install --upgrade pip && pip install uv`
+- Project pages: [uv on PyPI](https://pypi.org/project/uv/) |
+  [uv on GitHub](https://github.com/astral-sh/uv)
+- Full documentation and usage guide: [uv docs](https://docs.astral.sh/uv/)
+
+**Note:** The package requires Python 3.12 or later and is built and tested
+against Python 3.12–3.14. When creating a virtual environment with `uv`, specify
+the Python version to ensure compatibility: `uv venv --python 3.12` (replace
+`3.12` with your preferred supported version: 3.12, 3.13, or 3.14). This avoids
+potential issues with unsupported Python versions.
+
+### From PyPI
+
+```bash
+# Create a virtual environment (recommended with uv)
+uv venv --python 3.12
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+uv pip install nullcal
+```
+
+### From Source
+
+```bash
+git clone git@github.com:Leuven-Gravity-Institute/nullcal.git
+cd nullcal
+# Create a virtual environment (recommended with uv)
+uv venv --python 3.12
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+uv sync --extra jax
+```
+
+## Quick Start
+
+```python
+import numpy as np
+from nullcal.data import InterferometerData
+from nullcal.likelihood import RecalibrationLikelihood
+from nullcal.null_stream.null_stream import NullStream
+from nullcal.time_frequency_transform.wavelet_transforms import WaveletTransform
+
+# Load arrays from your strain source. The loader also accepts detector objects
+# exposing these fields via InterferometerData.from_interferometers(...).
+duration = 4.0
+sampling_frequency = 4096.0
+frequency_array = np.fft.rfftfreq(int(duration * sampling_frequency), 1 / sampling_frequency)
+data = InterferometerData(
+    psd=np.ones((3, frequency_array.size)),
+    strain=np.zeros((3, frequency_array.size), dtype=complex),
+    mask=np.broadcast_to(frequency_array >= 4.0, (3, frequency_array.size)).copy(),
+    frequency_array=frequency_array,
+    duration=duration,
+    sampling_frequency=sampling_frequency,
+    start_time=0.0,
+    name=("ET1", "ET2", "ET3"),
+)
+
+# Compute the null stream
+wavelet_transform = WaveletTransform(
+    duration=duration, sampling_frequency=sampling_frequency, nx=4, frequency_resolution=4
+)
+time_frequency_filter = np.ones(wavelet_transform.shape, dtype=bool)
+null_stream = NullStream(
+    interferometers=data,
+    time_frequency_transform=wavelet_transform,
+    time_frequency_filter=time_frequency_filter,
+)
+null_data = null_stream.compute_calibrated_frequency_domain_null_stream(calibration_factor=np.ones_like(data.strain))
+
+# Set up a recalibration likelihood for calibration error constraints
+likelihood = RecalibrationLikelihood(
+    interferometers=data,
+    knot_frequencies=np.geomspace(4.0, 2048.0, 10),
+    time_frequency_filter=time_frequency_filter,
+    wavelet_transform_frequency_resolution=4,
+    wavelet_transform_nx=4,
+)
+
+params = {
+    "amplitude": np.zeros((3, 10)),
+    "phase": np.zeros((3, 10)),
+}
+log_posterior = likelihood.logdensity_fn(params)
+```
+
+## Development
+
+### Pre-commit hooks
+
+Install `prek` (a wrapper around `pre-commit`):
+
+```console
+uv run prek install
+```
+
+Run all hooks against all files:
+
+```console
+uv run prek run --all-files
+```
+
+## Documentation
+
+Full documentation is available at
+[https://leuven-gravity-institute.github.io/nullcal/](https://leuven-gravity-institute.github.io/nullcal/).
+
+## Contributing
+
+Contributions are welcome!
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests
+5. Submit a pull request
+
+### Release Schedule
+
+Releases follow a fixed schedule: every Tuesday at 00:00 UTC, unless an emergent
+bugfix is required. This ensures predictable updates while allowing flexibility
+for critical issues. Users can view upcoming changes in the draft release on the
+[GitHub Releases page](https://github.com/Leuven-Gravity-Institute/nullcal/releases).
+
+## Testing
+
+Run the test suite:
+
+```bash
+uv run pytest
+```
+
+## License
+
+This project is licensed under the **MIT License**. See the [LICENSE](LICENSE)
+file for the full license text.
+
+## Support
+
+For questions or issues, please open an issue on
+[GitHub](https://github.com/Leuven-Gravity-Institute/nullcal/issues/new) or
+contact the maintainers.

nullcal-0.2.0.dist-info/RECORD

@@ -0,0 +1,42 @@
+nullcal/__init__.py,sha256=nbJwrDKsfvCCDVWsV-b7K69ib6EIsBsAgrDugpRbaJs,269
+nullcal/calibration.py,sha256=dW96gE44V2WAfh2Php2mN2tR6izOFCN4Pa1vbds91K0,7836
+nullcal/data.py,sha256=8ib6wkWjsNVzkKSJIZ0apFTHSYHQ4ll45KTVg5iWu3M,3778
+nullcal/sampler.py,sha256=j66SVbSV9LDRGA1141o8D4-u8q_IPt65Y2K9Y04UZbU,4356
+nullcal/version.py,sha256=HdACpZyuwpg7fn8N-5nDf2JOTxzABBn1RkGLFe_DK60,142
+nullcal/clustering/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nullcal/clustering/base.py,sha256=_M2Iox3KubfpwpzfpvUFQbouEZQLDBXpeXcNSJ1PMkE,1172
+nullcal/clustering/injection.py,sha256=2hORSfuXjoPzorxHKQ6fYwWRybDd8xSvbfNR5rGp6D0,2324
+nullcal/clustering/precompute.py,sha256=gastImY1MHtRWXV6j44Ae6dUMqlDu6Gc8zkHxhDJjVk,1093
+nullcal/clustering/single.py,sha256=G3Poul_QrRaucRrWLTMaiLTbxuY-H8cfZPVv3STaehs,8154
+nullcal/clustering/time_frequency_map.py,sha256=-oCjC0fzjze5Xs0or7PqFDFESp0tBsXxwgCthGF-1is,1779
+nullcal/likelihood/__init__.py,sha256=L7Q2BdTG8XkvZFakuXYpkrEANzgHMfNMxV3JeQvDM8U,180
+nullcal/likelihood/recalibration_likelihood.py,sha256=UOfUyxqRIvXiY9yoQGE8hXExy62s1eDrmgMA39UidYQ,10823
+nullcal/metadata/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nullcal/metadata/yaml.py,sha256=8R5pSvAA2AyXK8AHMpk0g8fot8pBea8ISep5JewZfqc,655
+nullcal/null_stream/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nullcal/null_stream/calibration.py,sha256=CgR_dj95THcy0hdZ0xS_WvfiNwawq01okivaSha2PwY,1533
+nullcal/null_stream/null_stream.py,sha256=oQ7HQ0UXnPyjglwbz2qqUeJrhW61T3qdUyeXn2HYF80,11991
+nullcal/null_stream/projector.py,sha256=qujWOyDhEsZDkA07HidUgc1gkMgEhe499hkTNZl0nqc,1887
+nullcal/null_stream/whiten.py,sha256=tbDNoc3CKpMQ-BLy7RzqSGTO-maTOK2p0vXcInoYEww,4287
+nullcal/result/__init__.py,sha256=LL9RiEvSPU4hERph0hqBKIA8KFG24RwoXGoBKq4zAIs,75
+nullcal/result/result.py,sha256=YCuhkmdcBcnOW08s8Na4UwXveX72yZtgSzgRe19kx8Y,1667
+nullcal/result/utils.py,sha256=Y7-1e1FDnVaC1s0I-_FSy0x2B9Uev4u5CcEVZiSyuAc,299
+nullcal/studies/__init__.py,sha256=ajvu4-ppzHoxNPGrQEOfa-b7MQ_sWsAF5Ox7nTCo4Zg,59
+nullcal/studies/lwa_leakage.py,sha256=NH4pIS0A1GW4gwoB2kY40jzgmjWlCHZXrrxhqS7DEGM,21923
+nullcal/studies/spline_resolution.py,sha256=Xx6DoqfKdtWr1pPiQuIXM3tNxv7zdLaEPudzDUpc9OQ,5905
+nullcal/time_frequency_transform/README.md,sha256=KiLOcOK43Y6zHww3i0_wl7lalmq6T3cPhlbZv3dcPkY,335
+nullcal/time_frequency_transform/__init__.py,sha256=3V8QF-S3HSFHE24GXyK7LsLNiJQChty5yVUuVm9xG7w,564
+nullcal/time_frequency_transform/inverse_wavelet_freq_funcs.py,sha256=l__DXPyx5bwsNf2oUKPfcnVJwzCL1ELgq_36kP57030,1687
+nullcal/time_frequency_transform/inverse_wavelet_time_funcs.py,sha256=yWPeh-RKGX52sqnelywCzxXvLg5FTAUaqPEc2ec2Y74,2116
+nullcal/time_frequency_transform/stft.py,sha256=Kj7VlkSkPrCUt7N-BUKOTE_H5Eg58MfMCAe00m9C0iQ,1310
+nullcal/time_frequency_transform/transform_freq_funcs.py,sha256=PwxAQtHCM_jZG7dhqDOPQhuYwMgAJxcWIxgZNHwWsIw,6280
+nullcal/time_frequency_transform/transform_time_funcs.py,sha256=KeLbA-OX5d-a-MSYiyZ12koyva1OZD7fs-_7HalB4F0,2343
+nullcal/time_frequency_transform/utils.py,sha256=WDt6hPji8tWncu2JX2USmxaKy8pSN3mvlRlQeSqIBdI,649
+nullcal/time_frequency_transform/wavelet_transforms.py,sha256=co0b4br9oWIQpUCvx1R_88Zg-CUrkLWYCuQWy1OBJCk,9219
+nullcal/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nullcal/utils/log.py,sha256=cJ7jzH1IysyBf0truYWQQJLzFR2jRhGp1iQuOTBNyjc,2414
+nullcal/utils/snr.py,sha256=U43mbgmMzY2bweEC2pyIPpvNdcA_dTe1mC3qr9hOU5A,1085
+nullcal-0.2.0.dist-info/METADATA,sha256=GnMzFkroMLE9jgbABawS7ul4THyxyBp89hT4IOrwrxI,8584
+nullcal-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+nullcal-0.2.0.dist-info/licenses/LICENSE,sha256=snOMIM58hahmLXUQ6hTKvk5-V-JuyalaCAP_NIuwdhQ,1071
+nullcal-0.2.0.dist-info/RECORD,,

nullcal-0.2.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

nullcal-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chun-Fung Wong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.