gwsim 0.1.0__py3-none-any.whl

gwsim/detector/utils.py

@@ -0,0 +1,90 @@
+"""A utility module for loading gravitational wave interferometer configurations."""
+
+from __future__ import annotations
+
+from ast import literal_eval
+from pathlib import Path
+
+import numpy as np
+from pycbc.detector import add_detector_on_earth
+
+# The default base path for detector configuration files
+DEFAULT_DETECTOR_BASE_PATH = Path(__file__).parent / "detectors"
+
+
+def _bilby_to_pycbc_detector_parameters(bilby_params: dict) -> dict:
+    """
+    Convert Bilby detector parameters to PyCBC-compatible parameters.
+
+    This function handles the conversion of units and conventions between Bilby and PyCBC,
+    including latitude/longitude to radians, length from km to meters, and azimuth adjustments
+    due to different reference conventions (Bilby: from East counterclockwise; PyCBC/LAL: from North clockwise).
+
+    Args:
+        bilby_params (dict): Dictionary of Bilby parameters (e.g., 'latitude', 'xarm_azimuth', etc.).
+
+    Returns:
+        dict: Dictionary of converted PyCBC parameters.
+    """
+    pycbc_params = {
+        "name": bilby_params["name"],
+        "latitude": np.deg2rad(bilby_params["latitude"]),
+        "longitude": np.deg2rad(bilby_params["longitude"]),
+        "height": bilby_params["elevation"],
+        "xangle": (np.pi / 2 - np.deg2rad(bilby_params["xarm_azimuth"])) % (2 * np.pi),
+        "yangle": (np.pi / 2 - np.deg2rad(bilby_params["yarm_azimuth"])) % (2 * np.pi),
+        "xaltitude": bilby_params["xarm_tilt"],
+        "yaltitude": bilby_params["yarm_tilt"],
+        "xlength": bilby_params["length"] * 1000,
+        "ylength": bilby_params["length"] * 1000,
+    }
+
+    return pycbc_params
+
+
+def load_interferometer_config(config_file: str | Path, encoding: str = "utf-8") -> str:
+    """
+    Load a .interferometer config file and add its detector using pycbc.detector.add_detector_on_earth.
+
+    Args:
+        config_file: The path to the config file.
+        encoding: The file encoding to use when reading the config file. Default is 'utf-8'.
+
+    Returns:
+        str: Added detector name (e.g., "E1").
+    """
+    # Load the .interferometer config file
+    config_file = Path(config_file)
+    if not config_file.exists():
+        raise FileNotFoundError(f"Config file {config_file} not found.")
+
+    bilby_params = {}
+    with config_file.open(encoding=encoding) as f:
+        lines = f.readlines()
+        for line in lines:
+            if line[0] == "#" or line[0] == "\n":
+                continue
+            split_line = line.split("=")
+            key = split_line[0].strip()
+            if key == "power_spectral_density":
+                continue
+            value = literal_eval("=".join(split_line[1:]))
+            bilby_params[key] = value
+
+    params = _bilby_to_pycbc_detector_parameters(bilby_params)
+    det_name = params["name"]
+
+    add_detector_on_earth(
+        name=det_name,
+        latitude=params["latitude"],
+        longitude=params["longitude"],
+        height=params["height"],
+        xangle=params["xangle"],
+        yangle=params["yangle"],
+        xaltitude=params["xaltitude"],
+        yaltitude=params["yaltitude"],
+        xlength=params["xlength"],
+        ylength=params["ylength"],
+    )
+
+    return det_name

gwsim/glitch/__init__.py

@@ -0,0 +1,7 @@
+"""Glitch simulators for gravitational-wave data."""
+
+from __future__ import annotations
+
+from gwsim.glitch.base import GlitchSimulator
+
+__all__ = ["GlitchSimulator"]

gwsim/glitch/base.py

@@ -0,0 +1,69 @@
+"""Base class for glitch simulators."""
+
+from __future__ import annotations
+
+from typing import cast
+
+import numpy as np
+
+from gwsim.mixin.detector import DetectorMixin
+from gwsim.mixin.randomness import RandomnessMixin
+from gwsim.mixin.time_series import TimeSeriesMixin
+from gwsim.simulator.base import Simulator
+
+
+class GlitchSimulator(TimeSeriesMixin, RandomnessMixin, DetectorMixin, Simulator):
+    """Base class for glitch simulators."""
+
+    def __init__(
+        self,
+        start_time: int = 0,
+        duration: float = 1024,
+        sampling_frequency: float = 4096,
+        max_samples: int | None = None,
+        dtype: type = np.float64,
+        seed: int | None = None,
+        detectors: list[str] | None = None,
+        **kwargs,
+    ) -> None:
+        """Initialize the base glitch simulator.
+
+        Args:
+            start_time: Start time of the first glitch segment in GPS seconds. Default is 0.
+            duration: Duration of each glitch segment in seconds. Default is 1024.
+            sampling_frequency: Sampling frequency of the glitches in Hz. Default is 4096.
+            max_samples: Maximum number of samples to generate. None means infinite.
+            dtype: Data type for the time series data. Default is np.float64.
+            seed: Seed for the random number generator. If None, the RNG is not initialized.
+            detectors: List of detector names. Default is None.
+            **kwargs: Additional arguments absorbed by subclasses and mixins.
+        """
+        super().__init__(
+            start_time=start_time,
+            duration=duration,
+            sampling_frequency=sampling_frequency,
+            max_samples=max_samples,
+            dtype=dtype,
+            seed=seed,
+            detectors=detectors,
+            **kwargs,
+        )
+
+    @property
+    def metadata(self) -> dict:
+        """Get the metadata of the simulator.
+
+        Returns:
+            Metadata dictionary.
+        """
+        meta = super().metadata
+        return meta
+
+    def update_state(self) -> None:
+        """Update internal state after each sample generation.
+
+        This method can be overridden by subclasses to update any internal state
+        after generating a sample. The default implementation does nothing.
+        """
+        self.counter = cast(int, self.counter) + 1
+        self.start_time += self.duration

gwsim/mixin/__init__.py

@@ -0,0 +1,8 @@
+"""Mixins for GW simulation classes."""
+
+from __future__ import annotations
+
+from .randomness import RandomnessMixin
+from .time_series import TimeSeriesMixin
+
+__all__ = ["RandomnessMixin", "TimeSeriesMixin"]

gwsim/mixin/detector.py

@@ -0,0 +1,203 @@
+"""Detector mixin for simulators."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import cast
+
+import numpy as np
+from gwpy.timeseries import TimeSeries as GWpyTimeSeries
+from scipy.interpolate import interp1d
+
+from gwsim.data.time_series.time_series import TimeSeries
+from gwsim.detector.base import Detector
+from gwsim.detector.utils import DEFAULT_DETECTOR_BASE_PATH
+
+
+class DetectorMixin:  # pylint: disable=too-few-public-methods
+    """Mixin class to add detector information to simulators."""
+
+    def __init__(self, detectors: list[str] | None = None, **kwargs):  # pylint: disable=unused-argument
+        """Initialize the DetectorMixin.
+
+        Args:
+            detectors (list[str] | None): List of detector names. If None, use all available detectors.
+            **kwargs: Additional arguments.
+        """
+        super().__init__(**kwargs)
+        self._metadata = {"detector": {"arguments": {"detectors": detectors}}}
+        self.detectors = detectors
+
+    @property
+    def detectors(self) -> list[Detector]:
+        """Get the list of detectors.
+
+        Returns:
+            List of detector names or Detector instances, or None if not set.
+        """
+        return self._detectors
+
+    @detectors.setter
+    def detectors(self, value: list[str] | None) -> None:
+        """Set the list of detectors.
+
+        Args:
+            value (list[str | Path | Detector] | None):
+                List of detector names, config file paths, or Detector instances.
+                If None, no detectors are set.
+        """
+        if value is None:
+            self._detectors = []
+        elif isinstance(value, list):
+            self._detectors = []
+            for det in value:
+                if Path(det).is_file() or (DEFAULT_DETECTOR_BASE_PATH / det).is_file():
+                    self._detectors.append(Detector(configuration_file=det))
+                else:
+                    self._detectors.append(Detector(name=str(det)))
+        else:
+            raise ValueError("detectors must be a list.")
+
+    def detectors_are_configured(self) -> bool:
+        """Check if all detectors are configured.
+
+        Returns:
+            True if all detectors are configured, False otherwise.
+        """
+        if all(det.is_configured() for det in self.detectors):
+            return True
+        return False
+
+    def project_polarizations(  # pylint: disable=too-many-locals,unused-argument
+        self,
+        polarizations: dict[str, GWpyTimeSeries],
+        right_ascension: float,
+        declination: float,
+        polarization_angle: float,
+        earth_rotation: bool = True,
+        **kwargs,
+    ) -> TimeSeries:
+        """Project waveform polarizations onto detectors using antenna patterns.
+
+        This method projects the plus and cross polarizations of a gravitational wave
+        onto each detector in the network, accounting for antenna response and
+        time delays.
+
+        Args:
+            polarizations: Dictionary with 'plus' and 'cross' keys containing
+                TimeSeries objects of the waveform polarizations.
+            right_ascension: RA of source in radians.
+            declination: Declination of source in radians.
+            polarization_angle: Polarization angle in radians.
+            earth_rotation: If True, account for Earth's rotation by computing
+                antenna patterns at multiple times and interpolating.
+                Defaults to True.
+
+        Returns:
+            Dictionary mapping detector names (str) to projected TimeSeries objects.
+            Keys are detector names, values are projected strain TimeSeries.
+
+        Raises:
+            ValueError: If detectors are not configured.
+            ValueError: If polarizations dict doesn't contain 'plus' and 'cross' keys,
+                or if detector is not initialized.
+            TypeError: If polarizations values are not TimeSeries objects.
+        """
+        # Validate the detector list
+        if not self.detectors_are_configured():
+            raise ValueError("Detectors are not configured in the simulator.")
+
+        # Validate inputs
+        if not isinstance(polarizations, dict):
+            raise TypeError("polarizations must be a dictionary")
+        if "plus" not in polarizations or "cross" not in polarizations:
+            raise ValueError("polarizations dict must contain 'plus' and 'cross' keys")
+        if not isinstance(polarizations["plus"], GWpyTimeSeries):
+            raise TypeError("polarizations['plus'] must be a GWpyTimeSeries")
+        if not isinstance(polarizations["cross"], GWpyTimeSeries):
+            raise TypeError("polarizations['cross'] must be a GWpyTimeSeries")
+
+        hp = polarizations["plus"]
+        hc = polarizations["cross"]
+
+        # Convert TimeSeries data to numpy arrays for computation
+        # Interpolate the hp and hc data to ensure smooth evaluation
+        time_array = cast(np.ndarray, hp.times.to_value())
+        reference_time = 0.5 * (time_array[0] + time_array[-1])
+
+        # Compute the time_array minus the reference_time to avoid the systematic large time values
+        time_array_wrt_reference = time_array - reference_time
+
+        hp_func = interp1d(time_array_wrt_reference, hp.to_value(), kind="cubic", bounds_error=False, fill_value=0.0)
+        hc_func = interp1d(time_array_wrt_reference, hc.to_value(), kind="cubic", bounds_error=False, fill_value=0.0)
+
+        if earth_rotation:
+            # Calculate the time delays first
+            time_delays = [
+                det.time_delay_from_earth_center(
+                    right_ascension=right_ascension, declination=declination, t_gps=time_array
+                )
+                for det in self.detectors
+            ]
+
+        else:
+            # Calculate the antenna patterns at the reference time
+            reference_time = 0.5 * (time_array[0] + time_array[-1])
+            antenna_patterns = [
+                det.antenna_pattern(
+                    right_ascension=right_ascension,
+                    declination=declination,
+                    polarization=polarization_angle,
+                    t_gps=reference_time,
+                    polarization_type="tensor",
+                )
+                for det in self.detectors
+            ]
+
+            # Calculate the time delays at the reference time
+            time_delays = [
+                det.time_delay_from_earth_center(
+                    right_ascension=right_ascension, declination=declination, t_gps=reference_time
+                )
+                for det in self.detectors
+            ]
+
+        # Evaluate the detector responses
+        detector_responses = np.zeros((len(self.detectors), len(time_array)))
+        for i, det in enumerate(self.detectors):
+            time_delay = time_delays[i]
+
+            # Shift the waveform data according to time delays
+            shifted_times = time_array_wrt_reference + time_delay
+
+            if earth_rotation:
+                # Evaluate antenna patterns exactly at the delayed times
+                fp_vals, fc_vals = det.antenna_pattern(
+                    right_ascension=right_ascension,
+                    declination=declination,
+                    polarization=polarization_angle,
+                    t_gps=time_array + time_delay,
+                    polarization_type="tensor",
+                )
+            else:
+                # Use constant antenna patterns (from earlier calculation)
+                fp_vals, fc_vals = antenna_patterns[i]
+
+            hp_shifted = hp_func(shifted_times)
+            hc_shifted = hc_func(shifted_times)
+
+            detector_responses[i, :] = fp_vals * hp_shifted + fc_vals * hc_shifted
+
+        # Create TimeSeries for projected strain
+        start_time = cast(float, time_array[0])
+        projected_ts = TimeSeries(data=detector_responses, start_time=start_time, sampling_frequency=hp.sample_rate)
+        return projected_ts
+
+    @property
+    def metadata(self) -> dict:
+        """Get metadata including detector information.
+
+        Returns:
+            Dictionary containing the list of detectors.
+        """
+        return self._metadata

gwsim/mixin/gwf.py

@@ -0,0 +1,192 @@
+"""GWF (Gravitational Wave Frame) file output utilities using gwpy."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import numpy as np
+from gwpy.io.gwf import write_frames
+from gwpy.timeseries import TimeSeries
+
+
+def save_timeseries_to_gwf(
+    data: np.ndarray,
+    file_path: str | Path,
+    channel: str = "H1:STRAIN",
+    sampling_frequency: float = 4096,
+    start_time: float = 0,
+    overwrite: bool = False,
+) -> None:
+    """Save time series data to GWF frame file using gwpy.
+
+    Args:
+        data: Time series data array.
+        file_path: Output GWF file path.
+        channel: Channel name (e.g., "H1:STRAIN"). Default is "H1:STRAIN".
+        sampling_frequency: Sampling rate in Hz. Default is 4096.
+        start_time: GPS start time. Default is 0.
+        overwrite: Whether to overwrite existing files. Default is False.
+
+    Raises:
+        ImportError: If gwpy is not available.
+        FileExistsError: If file exists and overwrite=False.
+        ValueError: If data is empty or parameters are invalid.
+    """
+
+    if len(data) == 0:
+        raise ValueError("Data array cannot be empty")
+
+    if sampling_frequency <= 0:
+        raise ValueError("Sample rate must be positive")
+
+    # Convert to Path object
+    file_path = Path(file_path)
+
+    # Check if file exists
+    if file_path.exists() and not overwrite:
+        raise FileExistsError(f"File {file_path} already exists and overwrite=False")
+
+    # Create gwpy TimeSeries
+    timeseries = TimeSeries(data=data, t0=start_time, sample_rate=sampling_frequency, channel=channel, name=channel)
+
+    # Ensure output directory exists
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Write to GWF file
+    timeseries.write(str(file_path), format="gwf")
+
+
+def combine_timeseries_to_gwf(
+    timeseries_list: list[tuple[np.ndarray, str]],
+    file_path: str | Path,
+    sampling_frequency: float = 4096,
+    start_time: float = 0,
+    overwrite: bool = False,
+) -> None:
+    """Combine multiple time series into a single GWF file.
+
+    Args:
+        timeseries_list: List of (data, channel_name) tuples.
+        file_path: Output GWF file path.
+        sampling_frequency: Sampling rate in Hz. Default is 4096.
+        start_time: GPS start time. Default is 0.
+        overwrite: Whether to overwrite existing files. Default is False.
+
+    Raises:
+        ImportError: If gwpy is not available.
+        ValueError: If timeseries_list is empty or data shapes don't match.
+    """
+    if not timeseries_list:
+        raise ValueError("timeseries_list cannot be empty")
+
+    # Convert to Path object
+    file_path = Path(file_path)
+
+    # Check if file exists
+    if file_path.exists() and not overwrite:
+        raise FileExistsError(f"File {file_path} already exists and overwrite=False")
+
+    # Validate all data arrays have the same length
+    lengths = [len(data) for data, _ in timeseries_list]
+    if not all(length == lengths[0] for length in lengths):
+        raise ValueError("All time series must have the same length")
+
+    # Create gwpy TimeSeries objects
+    gwpy_timeseries = []
+    for data, channel in timeseries_list:
+        ts = TimeSeries(data, sampling_frequency=sampling_frequency, epoch=start_time, name=channel, channel=channel)
+        gwpy_timeseries.append(ts)
+
+    # Ensure output directory exists
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Write multiple channels to GWF file
+    # gwpy handles multiple timeseries automatically
+    write_frames(str(file_path), gwpy_timeseries)
+
+
+class GWFOutputMixin:
+    """Mixin to add GWF file output capabilities to simulators.
+
+    This mixin provides methods for saving simulator output to GWF frame files
+    using gwpy. It assumes the simulator has sampling_frequency, start_time, and
+    generates numpy arrays.
+    """
+
+    def __init__(self, **kwargs) -> None:
+        """Initialize GWFOutputMixin.
+
+        Args:
+            **kwargs: Additional arguments absorbed by subclasses.
+        """
+        super().__init__(**kwargs)
+
+    def save_to_gwf(
+        self,
+        data: np.ndarray,
+        file_path: str | Path,
+        channel: str | None = None,
+        overwrite: bool = False,
+    ) -> None:
+        """Save simulator data to GWF file.
+
+        Args:
+            data: Time series data from simulator.
+            file_path: Output GWF file path.
+            channel: Channel name. If None, uses a default based on class name.
+            overwrite: Whether to overwrite existing files.
+        """
+        # Get parameters from simulator
+        sampling_frequency = getattr(self, "sampling_frequency", None)
+        start_time = getattr(self, "start_time", 0)
+
+        if sampling_frequency is None:
+            raise ValueError("Simulator must have sampling_frequency attribute")
+
+        # Generate default channel name if not provided
+        if channel is None:
+            class_name = self.__class__.__name__
+            # Convert CamelCase to UPPER_CASE
+            channel = re.sub("([a-z0-9])([A-Z])", r"\1_\2", class_name).upper()
+            channel = f"SIM:{channel}"
+
+        save_timeseries_to_gwf(
+            data=data,
+            file_path=file_path,
+            channel=channel,
+            sampling_frequency=sampling_frequency,
+            start_time=start_time,
+            overwrite=overwrite,
+        )
+
+    def save_batch_to_gwf(  # pylint: disable=unused-argument
+        self,
+        batch: list[np.ndarray] | np.ndarray,
+        file_path: str | Path,
+        channel: str | None = None,
+        overwrite: bool = False,
+        **kwargs,
+    ) -> None:
+        """Save a batch of simulator data to GWF file.
+
+        Args:
+            batch: Batch of time series data (list of arrays or 2D array).
+            file_path: Output GWF file path.
+            channel: Channel name. If None, uses a default based on class name.
+            overwrite: Whether to overwrite existing files.
+        """
+        # Flatten batch if needed
+        if isinstance(batch, list):
+            concatenated = np.concatenate(batch)
+        elif isinstance(batch, np.ndarray) and batch.ndim == 2:
+            concatenated = batch.flatten()
+        else:
+            concatenated = batch
+
+        self.save_to_gwf(
+            data=concatenated,
+            file_path=file_path,
+            channel=channel,
+            overwrite=overwrite,
+        )