gwsim 0.1.0__py3-none-any.whl

gwsim/data/time_series/time_series.py

@@ -0,0 +1,355 @@
+"""Module for handling time series data for multiple channels."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Iterable
+from numbers import Number
+from typing import TYPE_CHECKING
+
+import numpy as np
+from astropy.units.quantity import Quantity
+from gwpy.timeseries import TimeSeries as GWpyTimeSeries
+from gwpy.types.index import Index
+from scipy.interpolate import interp1d
+
+from gwsim.data.serialize.serializable import JSONSerializable
+from gwsim.data.time_series.inject import inject
+
+logger = logging.getLogger("gwsim")
+
+
+if TYPE_CHECKING:
+    from gwsim.data.time_series.time_series_list import TimeSeriesList
+
+
+class TimeSeries(JSONSerializable):
+    """Class representing a time series data for multiple channels."""
+
+    def __init__(self, data: np.ndarray, start_time: int | float | Quantity, sampling_frequency: float | Quantity):
+        """Initialize the TimeSeries with a list of GWPy TimeSeries objects.
+
+        Args:
+            data: 2D numpy array of shape (num_of_channels, num_samples) containing the time series data.
+            start_time: Start time of the time series in GPS seconds.
+            sampling_frequency: Sampling frequency of the time series in Hz.
+        """
+        if data.ndim != 2:
+            raise ValueError("Data must be a 2D numpy array with shape (num_of_channels, num_samples).")
+
+        if isinstance(start_time, Number):
+            start_time = Quantity(start_time, unit="s")
+        if isinstance(sampling_frequency, (int, float)):
+            sampling_frequency = Quantity(sampling_frequency, unit="Hz")
+
+        self._data: list[GWpyTimeSeries] = [
+            GWpyTimeSeries(
+                data=data[i],
+                t0=start_time,
+                sample_rate=sampling_frequency,
+            )
+            for i in range(data.shape[0])
+        ]
+        self.num_of_channels = data.shape[0]
+        self.dtype = data.dtype
+        self.metadata = {}
+
+    def __len__(self) -> int:
+        """Get the number of channels in the time series.
+
+        Returns:
+            Number of channels in the time series.
+        """
+        return self.num_of_channels
+
+    def __getitem__(self, index: int) -> GWpyTimeSeries:
+        """Get the GWPy TimeSeries object for a specific channel.
+
+        Args:
+            index: Index of the channel to retrieve.
+
+        Returns:
+            GWPy TimeSeries object for the specified channel.
+        """
+        return self._data[index]
+
+    def __setitem__(self, index: int, value: GWpyTimeSeries) -> None:
+        """Set the GWPy TimeSeries object for a specific channel.
+
+        Args:
+            index: Index of the channel to set.
+            value: GWPy TimeSeries object to set for the specified channel.
+        """
+        # First check whether the start time and sampling frequency match
+        if value.t0 != self.start_time:
+            raise ValueError(
+                "Start time of the provided TimeSeries does not match."
+                f"The start time of this instance is {self.start_time}, "
+                f"while that of the provided TimeSeries is {value.t0}."
+            )
+
+        # Debug: log the sampling frequencies
+        logger.debug(
+            "Assigning to channel %d: value.sample_rate=%.15f, self.sampling_frequency=%.15f",
+            index,
+            float(value.sample_rate.value),
+            float(self.sampling_frequency.value),
+        )
+
+        if value.sample_rate != self.sampling_frequency:
+            # Additional debug info
+            logger.warning(
+                "Sampling frequency mismatch on channel %d. "
+                "Difference: %.15e Hz. "
+                "Value times: %s to %s (%d samples, dt=%.15f). "
+                "Self times span should match.",
+                index,
+                float(value.sample_rate.value) - float(self.sampling_frequency.value),
+                value.times[0],
+                value.times[-1],
+                len(value),
+                float(value.dt.value),
+            )
+            raise ValueError(
+                "Sampling frequency of the provided TimeSeries does not match."
+                f"The sampling frequency of this instance is {self.sampling_frequency}, "
+                f"while that of the provided TimeSeries is {value.sample_rate}."
+            )
+        # Check the duration
+        if value.duration != self.duration:
+            raise ValueError(
+                "Duration of the provided TimeSeries does not match."
+                f"The duration of this instance is {self.duration}, "
+                f"while that of the provided TimeSeries is {value.duration}."
+            )
+
+        if not isinstance(value, GWpyTimeSeries):
+            raise TypeError(f"Value must be a GWpy TimeSeries instance, got {type(value)}")
+
+        self._data[index] = value
+
+    def __iter__(self):
+        """Iterate over the channels in the time series.
+
+        Returns:
+            Iterator over the GWPy TimeSeries objects in the time series.
+        """
+        return iter(self._data)
+
+    def __eq__(self, other: object) -> bool:
+        """Check equality with another TimeSeries object.
+
+        Args:
+            other: Another TimeSeries object to compare with.
+
+        Returns:
+            True if the two TimeSeries objects are equal, False otherwise.
+        """
+        if not isinstance(other, TimeSeries):
+            return False
+        if self.num_of_channels != other.num_of_channels:
+            return False
+        for i in range(self.num_of_channels):
+            if not np.array_equal(self[i].value, other[i].value):
+                return False
+            if self[i].t0 != other[i].t0:
+                return False
+            if self[i].sample_rate != other[i].sample_rate:
+                return False
+        return True
+
+    @property
+    def shape(self) -> tuple[int, int]:
+        """Get the shape of the time series data.
+
+        Returns:
+            Tuple representing the shape of the time series data (num_of_channels, num_samples).
+        """
+        return (self.num_of_channels, self[0].size)
+
+    @property
+    def start_time(self) -> Quantity:
+        """Get the start time of the time series.
+
+        Returns:
+            Start time of the time series.
+        """
+        return Quantity(self._data[0].t0)
+
+    @property
+    def duration(self) -> Quantity:
+        """Get the duration of the time series.
+
+        Returns:
+            Duration of the time series.
+        """
+        return Quantity(self._data[0].duration)
+
+    @property
+    def end_time(self) -> Quantity:
+        """Get the end time of the time series.
+
+        Returns:
+            End time of the time series.
+        """
+        end_time: Quantity = self.start_time + self.duration
+        return end_time
+
+    @property
+    def sampling_frequency(self) -> Quantity:
+        """Get the sampling frequency of the time series.
+
+        Returns:
+            Sampling frequency of the time series.
+        """
+        return Quantity(self._data[0].sample_rate)
+
+    @property
+    def time_array(self) -> Index:
+        """Get the time array of the time series.
+
+        Returns:
+            Time array of the time series.
+        """
+        return self[0].times
+
+    def crop(
+        self,
+        start_time: Quantity | None = None,
+        end_time: Quantity | None = None,
+    ) -> TimeSeries:
+        """Crop the time series to the specified start and end times.
+
+        Args:
+            start_time: Start time of the cropped segment in GPS seconds. If None, use the
+                original start time.
+            end_time: End time of the cropped segment in GPS seconds. If None, use the
+                original end time.
+
+        Returns:
+            Cropped TimeSeries instance.
+        """
+        for i in range(self.num_of_channels):
+            self._data[i] = GWpyTimeSeries(self._data[i].crop(start=start_time, end=end_time, copy=True))
+        return self
+
+    def inject(self, other: TimeSeries) -> TimeSeries | None:
+        """Inject another TimeSeries into the current TimeSeries.
+
+        Args:
+            other: TimeSeries instance to inject.
+
+        Returns:
+            Remaining TimeSeries instance if the injected TimeSeries extends beyond the current
+            TimeSeries end time, otherwise None.
+        """
+        if len(other) != len(self):
+            raise ValueError("Number of channels in chunk must match number of channels in segment.")
+
+        # Enforce that other has the same sampling frequency as self
+        if not other.sampling_frequency == self.sampling_frequency:
+            raise ValueError(
+                f"Sampling frequency of chunk ({other.sampling_frequency}) must match "
+                f"sampling frequency of segment ({self.sampling_frequency}). "
+                "This ensures time grid alignment and avoids rounding errors."
+            )
+
+        if other.end_time < self.start_time:
+            logger.warning(
+                "The time series to inject ends before the current time series starts. No injection performed."
+                "The start time of this segment is %s, while the end time of the other segment is %s",
+                self.start_time,
+                other.end_time,
+            )
+            return other
+
+        if other.start_time > self.end_time:
+            logger.warning(
+                "The time series to inject starts after the current time series ends. No injection performed."
+                "The end time of this segment is %s, while the start time of the other segment is %s",
+                self.end_time,
+                other.start_time,
+            )
+            return other
+
+        # Check whether there is any offset in times
+        other_start_time = other.start_time.to(self.start_time.unit)
+        idx = ((other_start_time - self.start_time) * self.sampling_frequency).value
+        if not np.isclose(idx, np.round(idx)):
+            logger.warning("Chunk time grid does not align with segment time grid.")
+            logger.warning("Interpolation will be used to align the chunk to the segment grid.")
+
+            other_end_time = other.end_time.to(self.start_time.unit)
+            other_new_times = self.time_array.value[
+                (self.time_array.value >= other_start_time.value) & (self.time_array.value <= other_end_time.value)
+            ]
+
+            other = TimeSeries(
+                data=np.array(
+                    [
+                        interp1d(
+                            other.time_array.value, other[i].value, kind="linear", bounds_error=False, fill_value=0.0
+                        )(other_new_times)
+                        for i in range(len(other))
+                    ]
+                ),
+                start_time=Quantity(other_new_times[0], unit=self.start_time.unit),
+                sampling_frequency=self.sampling_frequency,
+            )
+
+        for i in range(self.num_of_channels):
+            self[i] = inject(self[i], other[i])
+
+        if other.end_time > self.end_time:
+            return other.crop(start_time=self.end_time)
+        return None
+
+    def inject_from_list(self, ts_iterable: Iterable[TimeSeries]) -> TimeSeriesList:
+        """Inject multiple TimeSeries from an iterable into the current TimeSeries.
+
+        Args:
+            ts_iterable: Iterable of TimeSeries instances to inject.
+
+        Returns:
+            TimeSeriesList of remaining TimeSeries instances that extend beyond the current TimeSeries end time.
+        """
+        from gwsim.data.time_series.time_series_list import TimeSeriesList  # pylint: disable=import-outside-toplevel
+
+        remaining_ts: list[TimeSeries] = []
+        for ts in ts_iterable:
+            remaining_chunk = self.inject(ts)
+            if remaining_chunk is not None:
+                remaining_ts.append(remaining_chunk)
+        return TimeSeriesList(remaining_ts)
+
+    def to_json_dict(self) -> dict:
+        """Convert the TimeSeries to a JSON-serializable dictionary.
+
+        Assume the unit
+
+        Returns:
+            JSON-serializable dictionary representation of the TimeSeries.
+        """
+        return {
+            "__type__": "TimeSeries",
+            "data": [self[i].value.tolist() for i in range(self.num_of_channels)],
+            "start_time": self.start_time.value,
+            "start_time_unit": str(self.start_time.unit),
+            "sampling_frequency": self.sampling_frequency.value,
+            "sampling_frequency_unit": str(self.sampling_frequency.unit),
+        }
+
+    @classmethod
+    def from_json_dict(cls, json_dict: dict) -> TimeSeries:
+        """Create a TimeSeries object from a JSON-serializable dictionary.
+
+        Args:
+            json_dict: JSON-serializable dictionary representation of the TimeSeries.
+
+        Returns:
+            TimeSeries: An instance of the TimeSeries class created from the dictionary.
+        """
+        data = np.array(json_dict["data"])
+        start_time = Quantity(json_dict["start_time"], unit=json_dict["start_time_unit"])
+        sampling_frequency = Quantity(json_dict["sampling_frequency"], unit=json_dict["sampling_frequency_unit"])
+        return cls(data=data, start_time=start_time, sampling_frequency=sampling_frequency)

gwsim/data/time_series/time_series_list.py

@@ -0,0 +1,182 @@
+"""Module defining TimeSeriesList, a list-like container for TimeSeries objects with validation."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator
+from typing import Any, cast, overload
+
+from gwsim.data.time_series.time_series import TimeSeries
+
+
+class TimeSeriesList(Iterable[TimeSeries]):
+    """List of TimeSeries objects with validation."""
+
+    def __init__(self, iterable: list[TimeSeries] | None = None):
+        """List of TimeSeries objects with validation.
+
+        Args:
+            iterable: Optional list of TimeSeries objects to initialize the list.
+        """
+        self._data: list[TimeSeries] = []
+
+        if iterable is not None:
+            self._validate_items(iterable)
+            self._data.extend(iterable)
+
+    def _validate_items(self, items: Iterable[Any]) -> None:
+        """Validate that all items are TimeSeries instances.
+
+        Args:
+            items: Iterable of items to validate.
+
+        Raises:
+            TypeError: If any item is not a TimeSeries instance.
+        """
+        for item in items:
+            if not isinstance(item, TimeSeries):
+                raise TypeError(f"All items must be TimeSeries instances, got {type(item)}")
+
+    @overload
+    def __setitem__(self, index: int, value: TimeSeries) -> None: ...
+
+    @overload
+    def __setitem__(self, index: slice, value: Iterable[TimeSeries]) -> None: ...
+
+    def __setitem__(self, index: int | slice, value: TimeSeries | Iterable[TimeSeries]) -> None:
+        """Set item with validation.
+
+        Args:
+            index: Index or slice to set.
+            value: TimeSeries object or list of TimeSeries objects to set.
+        """
+        if isinstance(index, slice):
+            items = list(value) if not isinstance(value, list) else value
+            self._validate_items(items)
+            self._data[index] = cast(list[TimeSeries], items)
+        elif isinstance(index, int):
+            if not isinstance(value, TimeSeries):
+                raise TypeError(f"Value must be a TimeSeries instance, got {type(value)}")
+            self._data[index] = value
+        else:
+            raise TypeError("Index must be an int or slice.")
+
+    @overload
+    def __getitem__(self, index: int) -> TimeSeries: ...
+
+    @overload
+    def __getitem__(self, index: slice) -> list[TimeSeries]: ...
+
+    def __getitem__(self, index: int | slice) -> TimeSeries | list[TimeSeries]:
+        """Get item.
+
+        Args:
+            index: Index or slice to get.
+
+        Returns:
+            TimeSeries object or list of TimeSeries objects.
+        """
+        return self._data[index]
+
+    def __len__(self) -> int:
+        """Get the number of TimeSeries objects in the list.
+
+        Returns:
+            Number of TimeSeries objects in the list.
+        """
+        return len(self._data)
+
+    def __iter__(self) -> Iterator[TimeSeries]:
+        """Iterate over the TimeSeries objects in the list.
+
+        Returns:
+            Iterator over the TimeSeries objects in the list.
+        """
+        return iter(self._data)
+
+    def append(self, value: TimeSeries) -> None:
+        """Append a TimeSeries object to the list.
+
+        Args:
+            value: TimeSeries object to append.
+        """
+        if not isinstance(value, TimeSeries):
+            raise TypeError(f"Value must be a TimeSeries instance, got {type(value)}")
+        self._data.append(value)
+
+    def extend(self, iterable: Iterable[TimeSeries]) -> None:
+        """Extend the list with TimeSeries objects from an iterable.
+
+        Args:
+            iterable: Iterable of TimeSeries objects to extend the list.
+        """
+        items = list(iterable)
+        self._validate_items(items)
+        self._data.extend(items)
+
+    def insert(self, index: int, value: TimeSeries) -> None:
+        """Insert a TimeSeries object at a specific index.
+
+        Args:
+            index: Index to insert at.
+            value: TimeSeries object to insert.
+        """
+        if not isinstance(value, TimeSeries):
+            raise TypeError(f"Value must be a TimeSeries instance, got {type(value)}")
+        self._data.insert(index, value)
+
+    def pop(self, index: int = -1) -> TimeSeries:
+        """Pop item at index.
+
+        Args:
+            index: Index to pop. Defaults to -1 (last item).
+
+        Returns:
+            TimeSeries object that was popped.
+        """
+        return self._data.pop(index)
+
+    def to_json_dict(self) -> dict[str, Any]:
+        """Convert the TimeSeriesList to a JSON-serializable dictionary.
+
+        Returns:
+            JSON-serializable dictionary representation of the TimeSeriesList.
+        """
+        return {
+            "__type__": "TimeSeriesList",
+            "data": self._data,
+        }
+
+    @classmethod
+    def from_json_dict(cls, data: dict[str, Any]) -> TimeSeriesList:
+        """Reconstruct a TimeSeriesList instance from a JSON dictionary.
+
+        Args:
+            data: Dictionary with keys: 'data' containing list of TimeSeries dicts.
+
+        Returns:
+            Reconstructed TimeSeriesList instance.
+
+        Raises:
+            ValueError: If required keys are missing or data format is invalid.
+        """
+        try:
+            items = data["data"]
+        except KeyError as e:
+            raise ValueError(f"Missing required key in JSON dict: {e}") from e
+
+        ts_list: list[TimeSeries] = []
+        for item in items:
+            if isinstance(item, TimeSeries):
+                ts_list.append(item)
+            else:
+                raise TypeError(f"Invalid item in TimeSeriesList JSON data: {type(item)}")
+
+        return cls(ts_list)
+
+    def __repr__(self) -> str:
+        """Get the string representation of the TimeSeriesList.
+
+        Returns:
+            String representation of the TimeSeriesList.
+        """
+        return f"TimeSeriesList({self._data!r})"

gwsim/detector/__init__.py

@@ -0,0 +1,8 @@
+"""Detector module for GWSim."""
+
+from __future__ import annotations
+
+from gwsim.detector.base import Detector
+from gwsim.detector.utils import DEFAULT_DETECTOR_BASE_PATH, load_interferometer_config
+
+__all__ = ["DEFAULT_DETECTOR_BASE_PATH", "Detector", "load_interferometer_config"]

gwsim/detector/base.py

@@ -0,0 +1,156 @@
+"""A module to handle gravitational wave detector configurations,"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import cast
+
+from pycbc.detector import Detector as PyCBCDetector
+
+from gwsim.detector.utils import DEFAULT_DETECTOR_BASE_PATH, load_interferometer_config
+
+logger = logging.getLogger("gwsim")
+
+
+def _load_all_detector_configuration_files(config_dir: Path = DEFAULT_DETECTOR_BASE_PATH) -> None:
+    # Glob all files in the config_dir with .interferometer extension
+    for config_file in config_dir.glob("*.interferometer"):
+        try:
+            load_interferometer_config(config_file)
+            logger.debug("Loaded detector configuration from %s", config_file)
+        except (OSError, ValueError) as e:
+            logger.warning("Failed to load detector configuration from %s: %s", config_file, e)
+
+
+_load_all_detector_configuration_files(config_dir=DEFAULT_DETECTOR_BASE_PATH)
+
+
+class Detector:
+    """A wrapper class around pycbc.detector.Detector that
+    handles custom detector configurations from .interferometer files
+    """
+
+    def __init__(self, name: str | None = None, configuration_file: str | Path | None = None):
+        """
+        Initialize Detector class.
+        If `detector_name` is a built-in PyCBC detector, use it directly.
+        Otherwise, load from the corresponding .interferometer config file.
+
+        Args:
+            detector_name (str): The detector name or config name (e.g., 'V1' or 'E1_Triangle_Sardinia').
+            config_dir (str, optional): Directory where .interferometer files are stored (default: detectors_dir).
+        """
+        self._metadata = {
+            "arguments": {
+                "name": name,
+                "configuration_file": configuration_file,
+            }
+        }
+        if name is not None and configuration_file is None:
+            try:
+                self._detector = PyCBCDetector(str(name))
+                self.name = str(name)
+            except ValueError as e:
+                logger.warning("Detector name '%s' not found in PyCBC: %s", name, e)
+                logger.warning("Setting up detector with no configuration.")
+                self._detector = None
+                self.name = str(name)
+        elif name is None and configuration_file is not None:
+            configuration_file = Path(configuration_file)
+
+            if configuration_file.is_file():
+
+                logger.debug("Loading detector from configuration file: %s", configuration_file)
+
+                prefix = load_interferometer_config(config_file=configuration_file)
+
+            elif (DEFAULT_DETECTOR_BASE_PATH / configuration_file).is_file():
+
+                logger.debug("Loading detector from default path: %s", configuration_file)
+
+                prefix = load_interferometer_config(config_file=DEFAULT_DETECTOR_BASE_PATH / configuration_file)
+            else:
+                raise FileNotFoundError(f"Configuration file '{configuration_file}' not found.")
+            self._detector = PyCBCDetector(prefix)
+            self.name = prefix
+        elif name is not None and configuration_file is not None:
+            raise ValueError("Specify either 'name' or 'configuration_file', not both.")
+        else:
+            raise ValueError("Either 'name' or 'configuration_file' must be provided.")
+
+        self.configuration_file = configuration_file
+
+    def is_configured(self) -> bool:
+        """
+        Check if the detector is properly configured.
+        """
+        return self._detector is not None
+
+    def antenna_pattern(
+        self, right_ascension, declination, polarization, t_gps, frequency=0, polarization_type="tensor"
+    ):
+        """
+        Return the antenna pattern for the detector.
+        """
+        if not self.is_configured():
+            raise ValueError(f"Detector '{self.name}' is not configured.")
+        detector = cast(PyCBCDetector, self._detector)
+        return detector.antenna_pattern(right_ascension, declination, polarization, t_gps, frequency, polarization_type)
+
+    def time_delay_from_earth_center(self, right_ascension, declination, t_gps):
+        """
+        Return the time delay from the Earth center for the detector.
+        """
+        if not self.is_configured():
+            raise ValueError(f"Detector '{self.name}' is not configured.")
+        detector = cast(PyCBCDetector, self._detector)
+        return detector.time_delay_from_earth_center(right_ascension, declination, t_gps)
+
+    def __getattr__(self, attr):
+        """
+        Delegate attributes to the underlying _detector.
+        """
+        return getattr(self._detector, attr)
+
+    def __str__(self) -> str:
+        """
+        Return a string representation of the detector name, stripped to the base part.
+
+        Returns:
+            str: The detector name.
+        """
+        return self.name
+
+    def __repr__(self) -> str:
+        """
+        Return a detailed string representation of the Detector instance.
+
+        Returns:
+            str: A string representation of the Detector instance.
+        """
+        return f"Detector(name={self.name}, configured={self.is_configured()})"
+
+    @staticmethod
+    def get_detector(name: str | Path) -> Detector:
+        """A helper function to get a Detector instance or return the name string.
+
+        Args:
+            name: Name of the detector (e.g., 'H1', 'L1') or configuration.
+
+        Returns:
+            Detector instance if loading is successful, otherwise returns the name string.
+        """
+        # First check if name corresponds to a configuration file
+        if Path(name).is_file() or (DEFAULT_DETECTOR_BASE_PATH / name).is_file():
+            return Detector(configuration_file=name)
+        return Detector(name=str(name))
+
+    @property
+    def metadata(self) -> dict:
+        """Get a dictionary of metadata.
+
+        Returns:
+            dict: A dictionary of metadata.
+        """
+        return self._metadata