Merge pull request #305 from nanograv/master

Merging master changes into release branch

AUTHORS.rst

@@ -1,12 +1,7 @@
 Development Leads
 -----------------
 
-* `Justin A. Ellis (@jellis18) <https://github.com/jellis18>`_
-* `Stephen R. Taylor (@stevertaylor) <https://github.com/stevertaylor>`_
-* `Paul T. Baker (@paulthebaker) <https://github.com/paulthebaker>`_
-* `Michele Vallisneri (@vallis) <https://github.com/vallis>`_
-
-Contributors
-------------
-
-None yet. Why not be the first?
+* Justin A. Ellis (@jellis18) <https://github.com/jellis18>
+* Stephen R. Taylor (@stevertaylor) <https://github.com/stevertaylor>
+* Paul T. Baker (@paulthebaker) <https://github.com/paulthebaker>
+* Michele Vallisneri (@vallis) <https://github.com/vallis>

Makefile

@@ -81,7 +81,8 @@ docs: ## generate Sphinx HTML documentation, including API docs
 	rm -f docs/enterprise*.rst
 	rm -f docs/modules.rst
 	rm -rf docs/_build
-	sphinx-apidoc -o docs/ -M enterprise
+	sphinx-apidoc --ext-autodoc -o docs/ -M enterprise
+	sphinx-apidoc --ext-autodoc -o docs/ -M tests
 	$(MAKE) -C docs clean
 	$(MAKE) -C docs html
 	$(BROWSER) docs/_build/html/index.html

docs/conf.py

@@ -48,6 +48,9 @@
 # make order or docs 'groupwise'
 autodoc_member_order = "groupwise"
 
+# we won't even try installing these
+autodoc_mock_imports = ["libstempo", "PINT", "astropy", "healpy", "sksparse", "ephem"]
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
@@ -280,7 +283,7 @@ def run_apidoc(_):
     # subprocess.check_call(['jupyter nbconvert --template nb-rst.tpl --to rst',
     #                           nb, '--output-dir', output_path])
 
-    modules = ["../enterprise"]
+    modules = ["../enterprise", "../tests"]
     for module in modules:
         cmd_path = "sphinx-apidoc"
         if hasattr(sys, "real_prefix"):  # Check to see if we are in a virtualenv

docs/index.rst

@@ -43,11 +43,11 @@ searches, and timing model analysis.
    mdc
    nano9
 
-.. include:: ../AUTHORS.rst
+.. toctree::
+   :maxdepth: 2
+   :caption: Code Documentation   
 
-Indices and tables
-==================
+   enterprise
+   tests
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+.. include:: ../AUTHORS.rst

docs/mdc.rst

@@ -1,5 +1,6 @@
 
 .. module:: enterprise
+   :noindex:
 
 .. note:: This tutorial was generated from a Jupyter notebook that can be
           downloaded `here <_static/notebooks/mdc.ipynb>`_.

docs/nano9.rst

@@ -1,5 +1,6 @@
 
 .. module:: enterprise
+   :noindex:
 
 .. note:: This tutorial was generated from a Jupyter notebook that can be
           downloaded `here <_static/notebooks/nano9.ipynb>`_.

enterprise/pulsar.py

@@ -330,7 +330,6 @@ def __init__(self, toas, model, sort=True, drop_pintpsr=True, planets=True):
         self._flags = {}
         for ii, obsflags in enumerate(toas.get_flags()):
             for jj, flag in enumerate(obsflags):
-
                 if flag not in list(self._flags.keys()):
                     self._flags[flag] = [""] * toas.ntoas
 

enterprise/signals/signal_base.py

@@ -869,10 +869,16 @@ def get_detres(self, params):
         # than the last time
         @cache_call("basis_params", limit=1)
         def get_basis(self, params={}):
+            if self._Fmat is None:
+                return None
+
+            Fmat = np.zeros_like(self._Fmat)
+
             for signal in self._signals:
                 if signal in self._idx:
-                    self._Fmat[:, self._idx[signal]] = signal.get_basis(params)
-            return self._Fmat
+                    Fmat[:, self._idx[signal]] = signal.get_basis(params)
+
+            return Fmat
 
         def get_phiinv(self, params):
             return self.get_phi(params).inv()

enterprise/signals/utils.py

@@ -610,21 +610,21 @@ def create_gw_antenna_pattern(pos, gwtheta, gwphi):
 @function
 def bwm_delay(toas, pos, log10_h=-14.0, cos_gwtheta=0.0, gwphi=0.0, gwpol=0.0, t0=55000, antenna_pattern_fn=None):
     """
-    Function that calculates the earth-term gravitational-wave
-    burst-with-memory signal, as described in:
-    Seto et al, van haasteren and Levin, phsirkov et al, Cordes and Jenet.
-    This version uses the F+/Fx polarization modes, as verified with the
-    Continuous Wave and Anisotropy papers.
-
-    :param toas: Time-of-arrival measurements [s]
-    :param pos: Unit vector from Earth to pulsar
+    Function that calculates the Earth-term gravitational-wave
+    Burst-With-Memory signal, as described in:
+    Seto et al., van Haasteren and Levin, Pshirkov et al., Cordes and Jenet.
+    This version uses the F+/Fx polarization modes, and matches the
+    continuous-wave and anisotropy papers.
+
+    :param toas: time-of-arrival measurements [s]
+    :param pos: unit vector from Earth to pulsar
     :param log10_h: log10 of GW strain
-    :param cos_gwtheta: Cosine of GW polar angle
+    :param cos_gwtheta: cosine of GW polar angle
     :param gwphi: GW azimuthal polar angle [rad]
     :param gwpol: GW polarization angle
-    :param t0: Burst central time [day]
+    :param t0: burst central time [day]
     :param antenna_pattern_fn:
-        User defined function that takes `pos`, `gwtheta`, `gwphi` as
+        user defined function that takes `pos`, `gwtheta`, `gwphi` as
         arguments and returns (fplus, fcross)
 
     :return: the waveform as induced timing residuals (seconds)

requirements.txt

@@ -3,5 +3,5 @@ scipy>=1.2.0
 ephem>=3.7.6.0
 healpy>=1.14.0
 scikit-sparse>=0.4.5
-pint-pulsar>=0.8.2
-libstempo>=2.4.0
+pint-pulsar>=0.8.3
+libstempo>=2.4.3

setup.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 3.0.0
+current_version = 3.2.2
 commit = False
 tag = False
 

setup.py

@@ -12,13 +12,12 @@
     "ephem>=3.7.6.0",
     "healpy>=1.14.0",
     "scikit-sparse>=0.4.5",
-    "pint-pulsar>=0.8.2",
-    "libstempo>=2.4.0",
+    "pint-pulsar>=0.8.3",
+    "libstempo>=2.4.3",
 ]
 
 test_requirements = []
 
-
 setup(
     name="enterprise-pulsar",
     description="ENTERPRISE (Enhanced Numerical Toolbox Enabling a Robust PulsaR Inference SuitE)",

tests/enterprise_test_data.py

@@ -1,5 +1,8 @@
 # enterprise_test_data.py
 
+"""This module provides the location of data files for tests as `datadir`.
+Currently they are in `tests/data`, and they are based on the 9-yr data release."""
+
 # import this to get the location of the datafiles for tests.  This file
 # must be kept in the appropriate location relative to the test data
 # dir for this to work.

tests/test_deterministic_signals.py

@@ -2,10 +2,9 @@
 # -*- coding: utf-8 -*-
 
 """
-test_deterministic_signals
-----------------------------------
-
-Tests for deterministic signal module
+Deterministic Signals are those that provide a `get_delay()` method,
+and are created by the class factories in :mod:`enterprise.signals.deterministic_signals`.
+All tests in this module are run on `B1855+09_NANOGrav_9yv1`.
 """
 
 
@@ -23,25 +22,40 @@
 
 @function
 def sine_wave(toas, log10_A=-7, log10_f=-8, phase=0.0):
+    """A simple sine wave Enterprise function object. When instantiated,
+    it will create named Parameters for `log10_A`, `log10_f`, `phase`,
+    and it will automatically extract `toas` from the linked `Pulsar` object. """
+
     return 10 ** log10_A * np.sin(2 * np.pi * toas * 10 ** log10_f + phase)
 
 
 class TestDeterministicSignals(unittest.TestCase):
+    """Tests deterministic signals with a tempo2 Pulsar object."""
+
     @classmethod
     def setUpClass(cls):
-        """Setup the Pulsar object."""
+        """Set up the :func:`enterprise.Pulsar` object used in tests (tempo2 version)."""
 
         # initialize Pulsar class
         cls.psr = Pulsar(datadir + "/B1855+09_NANOGrav_9yv1.gls.par", datadir + "/B1855+09_NANOGrav_9yv1.tim")
 
     def test_bwm(self):
-        """Test BWM waveform."""
+        """Tests :meth:`enterprise.signals.deterministic_signals.Deterministic`
+        using the burst-with-memory function :func:`enterprise.signals.utils.bwm_delay`.
+        The test instantiates a deterministic Signal on our test pulsar, and
+        compares the array returned by calling `get_delay()` on the Signal
+        with a fixed dictionary of parameters, with the result of calling
+        the function directly with those parameters.
+        """
+
         log10_h = parameter.Uniform(-20, -11)("bwm_log10_h")
         cos_gwtheta = parameter.Uniform(-1, 1)("bwm_cos_gwtheta")
         gwphi = parameter.Uniform(0, 2 * np.pi)("bwm_gwphi")
         gwpol = parameter.Uniform(0, np.pi)("bwm_gwpol")
         t0 = parameter.Uniform(53000, 57000)("bwm_t0")
+
         bwm_wf = utils.bwm_delay(log10_h=log10_h, cos_gwtheta=cos_gwtheta, gwphi=gwphi, gwpol=gwpol, t0=t0)
+
         bwm = deterministic_signals.Deterministic(bwm_wf)
         m = bwm(self.psr)
 
@@ -68,11 +82,15 @@ def test_bwm(self):
         assert np.all(m.get_delay(params) == d1), msg
 
     def test_delay(self):
-        """Test deterministic signal no selection."""
+        """Same as :meth:`TestDeterministicSignals.test_bwm`, but
+        for a simple sine wave signal."""
+
         # set up signal and parameters
         log10_Ad = parameter.Uniform(-10, -5)
         log10_fd = parameter.Uniform(-9, -7)
+
         waveform = sine_wave(log10_A=log10_Ad, log10_f=log10_fd)
+
         dt = deterministic_signals.Deterministic(waveform)
         m = dt(self.psr)
 
@@ -89,11 +107,20 @@ def test_delay(self):
         assert np.all(m.get_delay(params) == delay), msg
 
     def test_delay_backend(self):
-        """Test deterministic signal with selection."""
+        """Same as :meth:`TestDeterministicSignals.test_delay`, but
+        instantiates the Signal with :func:`enterprise.signals.selections.by_backend`,
+        which creates separated named parameters for 430_ASP, 430_PUPPI,
+        L-wide_ASP, L-wide_PUPPI. The parameters are automatically accounted for
+        in `get_delay()`, but they need to be used explicitly when calling the
+        function directly. The tests therefore reconstructs the delay vector by
+        building selection masks from :meth:`enterprise.Pulsar.backend_flags`."""
+
         # set up signal and parameters
         log10_Ad = parameter.Uniform(-10, -5)
         log10_fd = parameter.Uniform(-9, -7)
+
         waveform = sine_wave(log10_A=log10_Ad, log10_f=log10_fd)
+
         selection = Selection(selections.by_backend)
         dt = deterministic_signals.Deterministic(waveform, selection=selection)
         m = dt(self.psr)
@@ -124,7 +151,17 @@ def test_delay_backend(self):
         assert np.all(m.get_delay(params) == delay), msg
 
     def test_physical_ephem_model(self):
-        """Test physical ephemeris model"""
+        """Tests physical ephemeris model (which is implemented as a deterministic signal)
+        four ways:
+
+        - computed directly with :func:`enterprise.signals.utils.physical_ephem_delay`;
+        - computed with :meth:`enterprise.signals.deterministic_signals.PhysicalEphemerisSignal.get_delay`
+          with `use_epoch_toas=True` (the default), which reduces computation by evaluating ephemeris corrections
+          once per measurement epoch, and then interpolating to the full `toas` vector;
+        - computed with :meth:`enterprise.signals.deterministic_signals.PhysicalEphemerisSignal.get_delay`,
+          setting `use_epoch_toas=False`;
+        - loaded from a golden copy.
+        """
 
         if isinstance(self.psr, enterprise.pulsar.Tempo2Pulsar):
             # define signals with and without epoch TOAs
@@ -223,9 +260,11 @@ def test_physical_ephem_model_setIII(self):
 
 
 class TestDeterministicSignalsPint(TestDeterministicSignals):
+    """Tests deterministic signals with a PINT Pulsar object."""
+
     @classmethod
     def setUpClass(cls):
-        """Setup the Pulsar object."""
+        """Set up the :func:`enterprise.Pulsar` object used in tests (PINT version)."""
 
         # initialize Pulsar class
         cls.psr = Pulsar(