ml4gw 0.7.5__tar.gz → 0.7.6__tar.gz

{ml4gw-0.7.5 → ml4gw-0.7.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ml4gw
-Version: 0.7.5
+Version: 0.7.6
 Summary: Tools for training torch models on gravitational wave data
 Author-email: Ethan Marx <emarx@mit.edu>, Will Benoit <benoi090@umn.edu>, Deep Chatterjee <deep1018@mit.edu>, Alec Gunny <alec.gunny@ligo.org>
 License-File: LICENSE

ml4gw-0.7.6/docs/.gitignore

@@ -0,0 +1,2 @@
+api/
+tutorials/data

{ml4gw-0.7.5 → ml4gw-0.7.6}/docs/conf.py

@@ -19,7 +19,7 @@ sys.path.insert(0, os.path.abspath("../"))
 # -- Project information -----------------------------------------------------
 
 project = "ml4gw"
-copyright = "2024, Alec Gunny, Ethan Marx, William Benoit, Deep Chatterjee"
+copyright = "2025, Alec Gunny, Ethan Marx, William Benoit, Deep Chatterjee"
 author = "Alec Gunny, Ethan Marx, William Benoit, Deep Chatterjee"
 
 
@@ -30,11 +30,24 @@ author = "Alec Gunny, Ethan Marx, William Benoit, Deep Chatterjee"
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.autosummary",
     "sphinx.ext.napoleon",
     "sphinx_autodoc_typehints",
     "sphinx.ext.githubpages",
+    "myst_nb",
 ]
+autosummary_generate = True
 
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": True,
+    "show-inheritance": True,
+}
+
+autodoc_typehints = "description"
+autodoc_inherit_docstrings = False
+nb_execution_mode = "off"
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]

ml4gw-0.7.6/docs/examples/augmentations.rst

@@ -0,0 +1,20 @@
+Augmentations
+=============
+
+Apply random time-series reversal and inversion augmentations to batches of data.
+
+.. code-block:: python
+
+   from ml4gw.augmentations import SignalInverter, SignalReverser
+   import torch
+
+   # Initialize augmentors with probability of applying the transformation
+   inverter = SignalInverter(prob=0.25)
+   reverser = SignalReverser(prob=0.5)
+
+   # Example data with shape (batch_size, channels, length)
+   X = torch.randn(10, 2, 1000)
+
+   # Apply augmentations
+   X = inverter(X)
+   X = reverser(X)

ml4gw-0.7.6/docs/examples/distributions.rst

@@ -0,0 +1,50 @@
+Distributions
+================
+
+Sample from probability distributions not yet included in `torch.distributions`.
+
+.. code-block:: python
+
+   from ml4gw.distributions import PowerLaw, Cosine, UniformComovingVolume
+   import matplotlib.pyplot as plt
+
+   # Initialize distributions
+   power_law = PowerLaw(
+      minimum=4,
+      maximum=100,
+      index=-3,
+   )
+   cosine = Cosine()
+   ucv = UniformComovingVolume(
+      minimum=0,
+      maximum=2,
+      distance_type="redshift",
+   )
+
+   # Sample from distributions
+   samples_power_law = power_law.sample((10000,))
+   samples_cosine = cosine.sample((10000,))
+   samples_ucv = ucv.sample((10000,))
+
+   # Plot samples
+   plt.figure(figsize=(12, 4))
+
+   plt.subplot(1, 3, 1)
+   plt.hist(samples_power_law, bins=50)
+   plt.title("PowerLaw")
+
+   plt.subplot(1, 3, 2)
+   plt.hist(samples_cosine, bins=50)
+   plt.title("Cosine")
+
+   plt.subplot(1, 3, 3)
+   plt.hist(samples_ucv, bins=50)
+   plt.title("UniformComovingVolume")
+
+   plt.tight_layout()
+   plt.show()
+
+.. image:: ../images/distribution_samples.png
+   :alt: Histograms of samples from the distributions
+   :width: 600px
+   :align: center

ml4gw-0.7.6/docs/examples/gw.rst

@@ -0,0 +1,65 @@
+Gravitational-wave projection and SNR calculation
+=================================================
+
+.. code-block:: python
+
+   """
+   Project a batch of waveform polarizations onto the Hanford,
+   Livingston, and Virgo interferometers to compute the observed
+   gravitational wave strain.
+   """
+
+   from ml4gw.gw import get_ifo_geometry, compute_observed_strain
+   from ml4gw.distributions import Cosine
+   from torch.distributions import Uniform
+
+   dec = Cosine()
+   psi = Uniform(0, torch.pi)
+   phi = Uniform(-torch.pi, torch.pi)
+
+   # Get the interferometer geometry
+   ifos = ["H1", "L1", "V1"]
+   tensors, vertices = get_ifo_geometry(*ifos)
+
+   # The following assumes that the plus and cross polarizations
+   # of the gravitational wave have already been computed by
+   # some method; e.g., using the `TimeDomainCBCWaveformGenerator`
+   # from the `ml4gw.waveforms` module. `sample_rate` is the sample
+   # rate at which the polarizations were generated.
+   waveforms = compute_observed_strain(
+      dec=dec.sample((num_waveforms,)),
+      psi=psi.sample((num_waveforms,)),
+      phi=phi.sample((num_waveforms,)),
+      detector_tensors=tensors,
+      detector_vertices=vertices,
+      sample_rate=sample_rate,
+      cross=hc,
+      plus=hp,
+   )
+
+.. code-block:: python
+
+   """
+   Compute the signal-to-noise ratio (SNR) of a batch of waveforms
+   relative to a given noise power spectral density (PSD).
+   """
+
+   from ml4gw.gw import compute_network_snr
+
+   # Assume `waveforms` is a batch of waveforms with shape
+   # (num_waveforms, num_detectors, num_samples) and 
+   # `psd` is a batch of power spectral densities. See the
+   # docstring for details on the allowed PSD shapes.
+
+   # Highpass determines the minimum frequency for the SNR calculation.
+   highpass = 20
+
+   # Sample rate of the waveforms
+   sample_rate = 2048
+
+   snr = compute_network_snr(
+      responses=waveforms,
+      psd=psd,
+      sample_rate=sample_rate,
+      highpass=highpass,
+   )

ml4gw-0.7.6/docs/examples/transforms.qtransform.rst

@@ -0,0 +1,40 @@
+Q-transform
+================
+
+.. code-block:: python
+
+   """
+   Compute the Q-transform of a batch of time-series data.
+   """
+
+   from ml4gw.transforms import QScan
+   import matplotlib.pyplot as plt
+   import torch
+
+   sample_rate = 2048
+   duration = 10
+   # Output shape of the spectrogram
+   spectrogram_shape = [256, 256]
+
+   qscan = QScan(
+      sample_rate=sample_rate,
+      duration=duration,
+      spectrogram_shape=spectrogram_shape,
+   )
+
+   # Example data with shape (batch_size, channels, length)
+   X = torch.randn(10, 2, duration * sample_rate)
+
+   # Apply the Q-transform to compute the Q-transform of X
+   spectrograms = qscan(X)
+
+   # Plot the first spectrogram
+   plt.imshow(spectrograms[0, 0], aspect='auto', origin='lower')
+   plt.colorbar()
+   plt.title('Q-transform Spectrogram')
+   plt.show()
+
+.. image:: ../images/qscan_spectrogram.png
+   :width: 600px
+   :align: center
+   :alt: Spectrogram of the Q-transform

ml4gw-0.7.6/docs/examples/transforms.spectral.rst

@@ -0,0 +1,32 @@
+Spectral Density
+================
+
+.. code-block:: python
+
+   """
+   Compute the power spectral density and cross-spectral density of
+   batches of time-series data.
+   """
+
+   from ml4gw.transforms import SpectralDensity
+   import torch
+
+   sample_rate = 2048
+   fftlength = 2
+   duration = 10
+
+   # Initialize the spectral transform with a sample rate and fftlength
+   spectral_density = SpectralDensity(
+      sample_rate=sample_rate, 
+      fftlength=fftlength,
+   )
+
+   # Example data with shape (batch_size, channels, length)
+   X = torch.randn(10, 2, duration * sample_rate)
+
+   # Apply the spectral transform to compute the power spectral density of X
+   psd = spectral_density(X)
+
+   # This module can also compute the cross-spectral density between two signals
+   Y = torch.randn(10, 2, duration * sample_rate)
+   csd = spectral_density(X, Y)

ml4gw-0.7.6/docs/examples/transforms.whitening.rst

@@ -0,0 +1,29 @@
+Whitening
+=========
+
+.. code-block:: python
+
+   """
+   Whiten a batch of time-series data
+   """
+
+   from ml4gw.transforms import Whiten
+   import torch
+
+   fduration = 2
+   sample_rate = 2048
+   highpass = 20
+   duration = 10
+
+   whitener = Whiten(
+      fduration=fduration,
+      sample_rate=sample_rate,
+      highpass=highpass,
+   )
+
+   X = torch.randn(10, 2, duration * sample_rate)
+
+   # Apply the whitening transform. Assume `psd` is the 
+   # power spectral density computed using, e.g., the 
+   # `SpectralDensity` transform.
+   X_whitened = whitener(X, psd)

{ml4gw-0.7.5 → ml4gw-0.7.6}/docs/index.rst

@@ -15,7 +15,7 @@ ml4gw
 ml4gw is a library of `pytorch  <https://pytorch.org/docs/stable/index.html>`_ utilities 
 for training neural networks in service of gravitational wave physics applications.
 
-The code can be found on github at `<https://github.com/ml4gw/ml4gw>`_
+The code can be found on github at `<https://github.com/ML4GW/ml4gw>`_
 
 
 .. toctree::
@@ -23,14 +23,26 @@ The code can be found on github at `<https://github.com/ml4gw/ml4gw>`_
    :caption: Contents:
 
    installation
-   modules
+   usage
+   tutorials/ml4gw_tutorial
+
+API:
+----
+
+.. autosummary::
+   :toctree: api
+   :caption: API
+   :recursive:
+
+   ml4gw
+   ml4gw.utils
 
 Projects
 ========
 Currently, the following projects are using ml4gw to support their research:
 
 * `Aframe <https://github.com/ml4gw/aframev2>`_ - Gravitational wave detection of binary black hole mergers
-* `PE <https://github.com/ml4gw/aframev2>`_ - Parameter estimation of gravitational wave signals
+* `AMPLFI <https://github.com/ml4gw/amplfi>`_ - Parameter estimation of gravitational wave signals
 
 
 Development

{ml4gw-0.7.5 → ml4gw-0.7.6}/docs/installation.rst

@@ -12,8 +12,8 @@ ml4gw is installable with pip:
 
 
 To build with a specific version of PyTorch/CUDA, please see the PyTorch installation `instructions <https://pytorch.org/get-started/previous-versions/>`_
-to see how to specify the desired torch version and :code:`--extra-index-url` flag. For example, to install with PyTorch 1.12 and CUDA 11.6, use the following command:
+to see how to specify the desired torch version and :code:`--extra-index-url` flag. For example, to install with PyTorch 2.5.0 and CUDA 12.1, use the following command:
 
 .. code-block:: console
-    
-        $ pip install ml4gw torch==1.12.0 --extra-index-url=https://download.pytorch.org/whl/cu116
+
+        $ pip install ml4gw torch==2.5.0 --extra-index-url=https://download.pytorch.org/whl/cu121

{ml4gw-0.7.5 → ml4gw-0.7.6}/docs/requirements.txt

@@ -1,3 +1,4 @@
 sphinx-rtd-theme>=2.0.0
 sphinx-autodoc-typehints>=2.0.0
 docutils>=0.17
+myst-nb>=1.3.0