Merge pull request #1371 from dlakaplan/polycoreadwrite

More flexible read/write for polycos

CHANGELOG.md

@@ -12,6 +12,9 @@ and this project, at least loosely, adheres to [Semantic Versioning](https://sem
 - Moved observatories to JSON file.  Changed way observatories are loaded/overloaded
 - Split Jodrell Bank observatory based on backend to get correct clock files
 - Clock files can be marked as being valid past the end of the data they contain
+- Polycos can be written/read from Path or Stream objects
+- Polyco format registration now done once as a class method
+- Polyco reading/generation from timing model done as class methods
 ### Added
 - delta_pulse_number column is now saved to -padd flag on TOA write
 - command-line utility to compare parfiles

docs/conf.py

@@ -18,7 +18,8 @@
 from packaging.version import parse
 
 import jupytext
-#import sphinx.ext.apidoc
+
+# import sphinx.ext.apidoc
 
 
 # If extensions (or modules to document with autodoc) are in another
@@ -76,7 +77,7 @@
 templates_path = ["_templates"]
 
 # The suffix of source filenames.
-#source_suffix = ".rst"
+# source_suffix = ".rst"
 
 # The encoding of source files.
 # source_encoding = 'utf-8-sig'
@@ -85,8 +86,8 @@
 master_doc = "index"
 
 # General information about the project.
-project = u"pint"
-copyright = u"2017-2021 PINT Developers"
+project = "pint"
+copyright = "2017-2021 PINT Developers"
 
 # The version info for the project you're documenting, acts as replacement
 # for |version| and |release|, also used in various other places throughout
@@ -109,7 +110,18 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ["_build", "examples/.ipynb_checkpoints", "conf.py", "_ext"]
+# exclude some notebooks that take too long to run and are not needed for the docs bulid
+exclude_patterns = [
+    "_build",
+    "examples/.ipynb_checkpoints",
+    "examples/fit_NGC6440E_MCMC.py",
+    "examples/compare_tempo2_B1855.py",
+    "examples/compare_tempo2_B1855.py",
+    "examples/example_dmx_ranges.py",
+    "examples/example_pulse_numbers.py",
+    "conf.py",
+    "_ext",
+]
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
@@ -262,7 +274,7 @@ def setup(app):
 # (source start file, target name, title, author, documentclass
 # [howto/manual]).
 latex_documents = [
-    ("index", "pint.tex", u"pint Documentation", u"PINT Developers", "manual")
+    ("index", "pint.tex", "pint Documentation", "PINT Developers", "manual")
 ]
 
 # The name of an image file (relative to this directory) to place at
@@ -290,7 +302,7 @@ def setup(app):
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [("index", "pint", u"pint Documentation", [u"PINT Developers"], 1)]
+man_pages = [("index", "pint", "pint Documentation", ["PINT Developers"], 1)]
 
 # If true, show URL addresses after external links.
 # man_show_urls = False
@@ -305,8 +317,8 @@ def setup(app):
     (
         "index",
         "pint",
-        u"pint Documentation",
-        u"PINT Developers",
+        "pint Documentation",
+        "PINT Developers",
         "pint",
         "One line description of project.",
         "Miscellaneous",

docs/examples/example_dmx_ranges.py

@@ -43,7 +43,7 @@
 glsfit.print_summary()
 
 # You can print some statistics on the DMXs like this:
-pint.utils.dmxstats(glsfit)
+pint.utils.dmxstats(glsfit.model, glsfit.toas)
 
 # dmxparse will pull out the DMX values and compute correct errors from the covariance matrix, which we can easily plot
 dmx = pint.utils.dmxparse(glsfit)

docs/tutorials.rst

@@ -35,15 +35,19 @@ For example, the file ``NGC6440E.par`` from the
 Examples
 --------
 
-We don't really have any proper tutorials yet. But for the moment, we
-have a few examples that may be useful.  These tutorials examples are
-in the form of Jupyter notebooks, downloadable from a link at the top
+These tutorials examples are
+in the form of `Jupyter <https://jupyter.org>`_ notebooks, downloadable from a link at the top
 of each page. (Also available in the same place is a plain-python
 script version, in case this is more convenient.) You should be able
 to download these files and run them from anywhere convenient
 (provided ``PINT`` is installed). Finally, there are additional
 notebooks you can download from the `PINT Wiki
-<https://github.com/nanograv/PINT/wiki>`_.
+<https://github.com/nanograv/PINT/wiki>`_ or the 
+`GitHub examples <https://github.com/nanograv/PINT/tree/master/docs/examples>`_ directory: these 
+are not included in the default build because they take too long, but you can download and run them yourself.
+
+.. The list below is just those that are built.  Other notebooks are excluded from the build
+.. Using the exclude_patterns list in conf.py
 
 .. toctree::
 

src/pint/mcmc_fitter.py

@@ -276,7 +276,7 @@ def get_event_phases(self):
         """
         Return pulse phases based on the current model
         """
-        phases = self.model.phase(self.toas)[1]
+        phases = self.model.phase(self.toas).frac
         # ensure all positive
         return np.where(phases < 0.0, phases + 1.0, phases)
 

src/pint/phase.py

@@ -6,36 +6,50 @@
 
 class Phase(namedtuple("Phase", "int frac")):
     """
-    Class representing pulse phase as integer (.int) and fractional (.frac) parts.
+    Class representing pulse phase as integer (``.int``) and fractional (``.frac``) parts.
 
-    The phase values are dimensionless Quantitys (u.dimensionless_unscaled == u.Unit("") == Unit(dimensionless))
+    The phase values are dimensionless :class:`~astropy.units.Quantity` (``u.dimensionless_unscaled == u.Unit("") == Unit(dimensionless)``)
 
     Ensures that the fractional part stays in [-0.5, 0.5)
 
     SUGGESTION(@paulray): How about adding some documentation here
     describing why the fractional part is reduced to [-0.5,0.5) instead of [0,1).
 
+    Examples
+    --------
+
+        >>> from pint.phase import Phase
+        >>> import numpy as np
+        >>> p = Phase(np.arange(10),np.random.random(10))
+        >>> print(p.int)
+        >>> print(p.frac[:5])
+        >>> i,f = p
+        >>> q = p.quantity
+
     """
 
     __slots__ = ()
 
     def __new__(cls, arg1, arg2=None):
         """Create new Phase object
 
-        Constructs a Phase object.
-        Can be initialized with arrays or a scalar Quantity.
-        Can take inputs as plain numerical types, or dimensionless Quantitys
-        Accepts either floating point argument (arg1) or pair of arguments with integer (arg1) and fractional (arg2) parts separate
-        Scalars are converted to length 1 arrays so `Phase.int` and `Phase.frac` are always arrays
+        Can be initialized with arrays or a scalar :class:`~astropy.units.Quantity` (dimensionless).
+
+        Accepts either floating point argument (``arg1``) or pair of arguments with integer (``arg1``) and fractional (``arg2``) parts separate
+        Scalars are converted to length 1 arrays so ``Phase.int`` and ``Phase.frac`` are always arrays
 
         Parameters
         ----------
-        arg1 : array or dimensionless Quantity
-        arg2 : array or dimensionless Quantity
+        arg1 : numpy.ndarray or astropy.units.Quantity
+            Quantity should be dimensionless
+        arg2 : numpy.ndarray or astropy.units.Quantity
+            Quantity should be dimensionless
 
         Returns
         -------
-        Phase : pulse phase object with arrays of dimensionless Quantitys as the int and frac parts
+        Phase
+            pulse phase object with arrays of dimensionless :class:`~astropy.units.Quantity`
+            objects as the ``int`` and ``frac`` parts
         """
         if not hasattr(arg1, "unit"):
             arg1 = u.Quantity(arg1)
@@ -91,3 +105,11 @@ def __mul__(self, num):
 
     def __rmul__(self, num):
         return self.__mul__(num)
+
+    @property
+    def quantity(self):
+        return self.int + self.frac
+
+    @property
+    def value(self):
+        return self.quantity.value