Revert "strip gravitational_wave module"

This reverts commit a457b5e.

Author: ntessore

docs/gravitational_waves/index.rst

@@ -0,0 +1,5 @@
+*************************************************
+Gravitational Waves (`skypy.gravitational_waves`)
+*************************************************
+
+.. automodule:: skypy.gravitational_waves

docs/index.rst

@@ -33,6 +33,7 @@ Packages
    :maxdepth: 1
 
    galaxies
+   gravitational_waves/index
    utils/index
 
 Pipeline

skypy/gravitational_waves/__init__.py

@@ -0,0 +1,16 @@
+"""
+This module contains methods that model the properties of gravitational wave
+populations.
+
+Merger Rates
+================
+
+.. autosummary::
+   :nosignatures:
+   :toctree: ../api/
+
+   b_band_merger_rate
+
+"""
+
+from .merger_rate import *  # noqa F401,F403

skypy/gravitational_waves/merger_rate.py

@@ -0,0 +1,89 @@
+
+r"""Binary merger rate module.
+This module provides functions to calculate compact binary merger rates
+for individual galaxies.
+
+"""
+
+from astropy import constants, units
+
+
+__all__ = [
+    'b_band_merger_rate',
+]
+
+
+abadie_table_III = {
+    'NS-NS': {
+        'low': 0.6,
+        'realistic': 60,
+        'high': 600,
+        'max': 2000},
+    'NS-BH': {
+        'low': 0.03,
+        'realistic': 2,
+        'high': 60},
+    'BH-BH': {
+        'low': 0.006,
+        'realistic': 0.2,
+        'high': 20}
+}
+
+
+def b_band_merger_rate(luminosity,
+                       population='NS-NS',
+                       optimism='low'):
+
+    r"""Model of Abadie et al (2010), Table III
+
+    Compact binary merger rates as a linear function of a galaxies
+    B-band luminosity.
+
+    Parameters
+    ----------
+    luminosity : (ngal,) array-like
+        The B-band luminosity of the galaxies to generate merger
+        rates for, in units of solar luminosity.
+    population : {'NS-NS', 'NS-BH', 'BH-BH'}
+        Compact binary population to get rate for.
+        'NS-NS' is neutron star - neutron star
+        'NS-BH' is neutron star - black hole
+        'BH-BH' is black hole - black hole
+    optimism : {'low', 'realistic', 'high'}
+        Optimism of predicted merger rates.
+        For 'NS-NS' there is an extra option 'max'.
+
+    Returns
+    -------
+    merger_rate : array_like
+        Merger rates for the galaxies in units of year^-1
+
+    Notes
+    -----
+
+    References
+    ----------
+    .. Abadie et al. 2010, Classical and Quantum Gravity,
+        Volume 27, Issue 17, article id. 173001 (2010)
+        https://arxiv.org/abs/1003.2480
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from skypy.gravitational_waves import b_band_merger_rate
+
+    Sample 100 luminosity values near absolute magnitude -20.5.
+
+    >>> luminosities = 10.**(-0.4*(-20.5 + np.random.randn(100)))
+
+    Generate merger rates for these luminosities.
+
+    >>> rates = b_band_merger_rate(luminosities,
+    ...                            population='NS-NS',
+    ...                            optimism='low')
+
+    """
+
+    # Convert luminosity to units of L_10 defined in Abadie et. al. 2010
+    L_10 = luminosity * constants.L_sun.to_value('erg/s') / (1e10 * 2.16e33)
+    return abadie_table_III[population][optimism] * L_10 / units.year

skypy/gravitational_waves/tests/__init__.py

@@ -0,0 +1,2 @@
+def test_import():
+    import skypy.gravitational_waves

skypy/gravitational_waves/tests/test_import.py

@@ -0,0 +1,19 @@
+import numpy as np
+from astropy import constants, units
+from skypy.gravitational_waves import b_band_merger_rate
+from skypy.gravitational_waves.merger_rate import abadie_table_III
+
+
+def test_abadie_rates():
+
+    # Check the number of merger rates returned
+    luminosity = 10.**(-0.4*(-20.5 + np.random.randn(1000)))
+    rates = b_band_merger_rate(luminosity, population='NS-NS', optimism='low')
+    assert len(rates) == len(luminosity)
+
+    # Test that a luminosity of L_10 (in units of solar luminosity) returns a
+    # rate that matches the value in Abadie Table III
+    L_10 = 1e10 * 2.16e33 / constants.L_sun.to_value('erg/s')
+    L_B_rate = b_band_merger_rate(L_10, population='NS-NS', optimism='low')
+    table_value = abadie_table_III['NS-NS']['low']
+    assert np.isclose(L_B_rate.to_value(1/units.year), table_value, rtol=1e-5)