Merge pull request #82 from adrn/potential/cdef-subclass

Make subclassing easier for CPotentials
adrn · Apr 17, 2017 · 2c65d9e · 2c65d9e
2 parents d0ff55d + 951bcd5
commit 2c65d9e
Show file tree

Hide file tree

Showing 74 changed files with 367 additions and 427 deletions.
diff --git a/CHANGES.md b/CHANGES.md
@@ -2,15 +2,18 @@
 ----------------
 
 - Added a new potential class for the Satoh density (Satoh 1980).
-- Added support for Leapfrog integration when generating mock
-    stellar streams.
+- Added support for Leapfrog integration when generating mock stellar streams.
 - Added new colormaps and defaults for the matplotlib style.
-- Added support for non-inertial reference frames and implemented a
-    constant rotating reference frame.
-- Added a new class - `Hamiltonian` - for storing potentials with
-    reference frames and should be used for orbit integration.
-- Added a new mock stream argument to output orbits of all of the
-    mock stream star particles to an HDF5 file.
+- Added support for non-inertial reference frames and implemented a constant
+  rotating reference frame.
+- Added a new class - `Hamiltonian` - for storing potentials with reference
+  frames and should be used for orbit integration.
+- Added a new mock stream argument to output orbits of all of the mock stream
+  star particles to an HDF5 file.
+- Cleaned up and simplified the process of subclassing a C-implemented
+  gravitational potential.
+- Gravitational potential class instances can now be composed by just adding the
+  instances.
 
 0.1.1 (2016-05-20)
 ------------------

diff --git a/docs/potential/compositepotential.rst b/docs/potential/compositepotential.rst
@@ -6,25 +6,49 @@ Creating a composite (multi-component ) potential
 
 Potential objects can be combined into more complex *composite* potentials
 using the :class:`~gala.potential.potential.CompositePotential` or
-:class:`~gala.potential.potential.CCompositePotential` classes. These classes operate
-like a Python dictionary in that each component potential must be named, and
-the potentials can either be passed in to the initializer or added after the
+:class:`~gala.potential.potential.CCompositePotential` classes. These classes
+operate like a Python dictionary in that each component potential must be named,
+and the potentials can either be passed in to the initializer or added after the
 composite potential container is already created.
 
 For composing any of the built-in potentials or any external potentials
 implemented in C, it is always faster to use
 :class:`~gala.potential.potential.CCompositePotential`, where the composition is
 done at the C layer rather than in Python.
 
-But with either class, interaction with the class is identical. Each component
-potential must be instantiated before adding it to the composite potential::
+With either class, interaction with the class is identical. To compose
+potentials with unique but arbitrary names, you can simply add pre-defined
+potential class instances::
 
     >>> import numpy as np
     >>> import gala.potential as gp
     >>> from gala.units import galactic
+    >>> disk = gp.MiyamotoNagaiPotential(m=1E11, a=6.5, b=0.27, units=galactic)
+    >>> bulge = gp.HernquistPotential(m=3E10, c=0.7, units=galactic)
+    >>> pot = disk + bulge
+    >>> print(pot.__class__.__name__)
+    CCompositePotential
+    >>> list(pot.keys()) # doctest: +SKIP
+    ['c655f07d-a1fe-4905-bdb2-e8a202d15c81',
+     '8098cb0b-ebad-4388-b685-2f93a874296e']
+
+The two components are assigned unique names and composed into a
+:class:`~gala.potential.potential.CCompositePotential` instance because the two
+component potentials are implemented in C (i.e. are
+:class:`~gala.potential.potential.CPotential`subclass instances). If any of the
+individual potential components are Python-only, the resulting object will be
+an instance of :class:`~gala.potential.potential.CompositePotential` instead.
+
+Alternatively, the potentials can be composed directly into the object by
+treating it like a dictionary. This allows you to specify the keys or names of
+the components in the resulting
+:class:`~gala.potential.potential.CCompositePotential` instance::
+
     >>> disk = gp.MiyamotoNagaiPotential(m=1E11, a=6.5, b=0.27, units=galactic)
     >>> bulge = gp.HernquistPotential(m=3E10, c=0.7, units=galactic)
     >>> pot = gp.CCompositePotential(disk=disk, bulge=bulge)
+    >>> list(pot.keys()) # doctest: +SKIP
+    ['disk', 'bulge']
 
 is equivalent to::
 
@@ -34,9 +58,10 @@ is equivalent to::
 
 In detail, the composite potential classes subclass
 :class:`~collections.OrderedDict`, so in this sense there is a slight difference
-between the two examples above. By defining components after creating the
-instance, the order is preserved. In the above example, the disk potential
-would always be called first and the bulge would always be called second.
+between the two examples above (if you are using a Python version < 3.6). By
+defining components after creating the instance, the order is preserved. In the
+above example, the disk potential would always be called first and the bulge
+would always be called second.
 
 The resulting potential object has all of the same properties as individual
 potential objects::

diff --git a/gala/__init__.py b/gala/__init__.py
@@ -2,6 +2,8 @@
 Gala.
 """
 
+__author__ = 'adrn <adrianmpw@gmail.com>'
+
 from ._astropy_init import *
 
 # For egg_info test builds to pass, put package imports here.

diff --git a/gala/coordinates/gd1.py b/gala/coordinates/gd1.py
@@ -4,7 +4,6 @@
 
 from __future__ import division, print_function
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 # Third-party
 import numpy as np

diff --git a/gala/coordinates/orphan.py b/gala/coordinates/orphan.py
@@ -4,7 +4,6 @@
 
 from __future__ import division, print_function
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 from astropy.coordinates import frame_transform_graph
 import astropy.coordinates as coord

diff --git a/gala/coordinates/poincarepolar.py b/gala/coordinates/poincarepolar.py
@@ -2,7 +2,6 @@
 
 from __future__ import division, print_function
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 # Third-party
 import numpy as np

diff --git a/gala/coordinates/quaternion.py b/gala/coordinates/quaternion.py
@@ -4,7 +4,6 @@
 
 from __future__ import division, print_function
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 # Third-party
 import numpy as np

diff --git a/gala/coordinates/sgr.py b/gala/coordinates/sgr.py
@@ -4,7 +4,6 @@
 
 from __future__ import division, print_function
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 # Third-party
 import numpy as np

diff --git a/gala/coordinates/tests/test_gd1.py b/gala/coordinates/tests/test_gd1.py
@@ -2,7 +2,6 @@
 
 from __future__ import absolute_import, unicode_literals, division, print_function
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 # Third-party
 import astropy.coordinates as coord

diff --git a/gala/coordinates/tests/test_orphan.py b/gala/coordinates/tests/test_orphan.py
@@ -5,7 +5,6 @@
 
 from __future__ import absolute_import, division, print_function
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 # Third-party
 import astropy.coordinates as coord

diff --git a/gala/coordinates/tests/test_propermotion.py b/gala/coordinates/tests/test_propermotion.py
@@ -5,7 +5,6 @@
 
 from __future__ import absolute_import, division, print_function
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 # Standard library
 import tempfile

diff --git a/gala/coordinates/tests/test_sgr.py b/gala/coordinates/tests/test_sgr.py
@@ -5,7 +5,6 @@
 
 from __future__ import absolute_import, unicode_literals, division, print_function
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 # Third-party
 import astropy.coordinates as coord

diff --git a/gala/coordinates/tests/test_velocity_frame_transforms.py b/gala/coordinates/tests/test_velocity_frame_transforms.py
@@ -5,7 +5,6 @@
 
 from __future__ import absolute_import, division, print_function
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 # Standard library
 import os

diff --git a/gala/coordinates/tests/test_velocity_transforms.py b/gala/coordinates/tests/test_velocity_transforms.py
@@ -4,7 +4,6 @@
 
 from __future__ import division, print_function
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 # Standard library
 import logging

diff --git a/gala/coordinates/velocity_coord_transforms.py b/gala/coordinates/velocity_coord_transforms.py
@@ -4,7 +4,6 @@
 
 from __future__ import division, print_function
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 # Standard library
 

diff --git a/gala/coordinates/velocity_frame_transforms.py b/gala/coordinates/velocity_frame_transforms.py
@@ -4,7 +4,6 @@
 
 from __future__ import division, print_function
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 # Third-party
 import numpy as np

diff --git a/gala/dynamics/actionangle.py b/gala/dynamics/actionangle.py
@@ -7,7 +7,6 @@
 arbitrary potential.
 """
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 # Standard library
 import time

diff --git a/gala/dynamics/analyticactionangle.py b/gala/dynamics/analyticactionangle.py
@@ -6,7 +6,6 @@
 Analytic transformations to action-angle coordinates.
 """
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 # Third-party
 import numpy as np

diff --git a/gala/dynamics/core.py b/gala/dynamics/core.py
@@ -2,7 +2,6 @@
 
 from __future__ import division, print_function
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 # Standard library
 import warnings

diff --git a/gala/dynamics/lyapunov/dop853_lyapunov.pyx b/gala/dynamics/lyapunov/dop853_lyapunov.pyx
@@ -9,7 +9,6 @@
 
 from __future__ import division, print_function
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 # Third-party
 import numpy as np

diff --git a/gala/dynamics/mockstream/_coord.pyx b/gala/dynamics/mockstream/_coord.pyx
@@ -10,7 +10,6 @@
 
 from __future__ import division, print_function
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 from libc.math cimport M_PI
 

diff --git a/gala/dynamics/mockstream/_mockstream.pyx b/gala/dynamics/mockstream/_mockstream.pyx
@@ -10,7 +10,6 @@
 
 from __future__ import division, print_function
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 # Standard library
 import warnings

diff --git a/gala/dynamics/mockstream/core.py b/gala/dynamics/mockstream/core.py
@@ -2,7 +2,6 @@
 
 from __future__ import division, print_function
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 # Standard library
 import warnings

diff --git a/gala/dynamics/mockstream/tests/test_coord.py b/gala/dynamics/mockstream/tests/test_coord.py
@@ -2,7 +2,6 @@
 
 from __future__ import division, print_function
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 # Project
 from .._coord import (_test_sat_rotation_matrix, _test_to_sat_coords_roundtrip,

diff --git a/gala/dynamics/nonlinear.py b/gala/dynamics/nonlinear.py
@@ -2,7 +2,6 @@
 
 from __future__ import division, print_function
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 # Third-party
 import astropy.units as u

diff --git a/gala/dynamics/orbit.py b/gala/dynamics/orbit.py
@@ -2,7 +2,6 @@
 
 from __future__ import division, print_function
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 # Standard library
 import warnings

diff --git a/gala/dynamics/plot.py b/gala/dynamics/plot.py
@@ -4,7 +4,6 @@
 
 from __future__ import division, print_function
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 # Third-party
 import numpy as np

diff --git a/gala/dynamics/tests/helpers.py b/gala/dynamics/tests/helpers.py
@@ -4,7 +4,6 @@
 
 from __future__ import division, print_function
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 # Third-party
 import astropy.coordinates as coord

diff --git a/gala/dynamics/tests/test_actionangle.py b/gala/dynamics/tests/test_actionangle.py
@@ -4,7 +4,6 @@
 
 from __future__ import division, print_function
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 # Standard library
 import logging

diff --git a/gala/dynamics/tests/test_analyticactionangle.py b/gala/dynamics/tests/test_analyticactionangle.py
@@ -4,7 +4,6 @@
 
 from __future__ import division, print_function
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 # Third-party
 import matplotlib.pyplot as pl

diff --git a/gala/dynamics/tests/test_nonlinear.py b/gala/dynamics/tests/test_nonlinear.py
@@ -2,7 +2,6 @@
 
 from __future__ import division, print_function
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 # Third-party
 import numpy as np

diff --git a/gala/dynamics/tests/test_orbit.py b/gala/dynamics/tests/test_orbit.py
@@ -4,7 +4,6 @@
 
 from __future__ import division, print_function
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 # Third-party
 from astropy.coordinates import SphericalRepresentation, Galactic

diff --git a/gala/dynamics/tests/test_plot.py b/gala/dynamics/tests/test_plot.py
@@ -4,7 +4,6 @@
 
 from __future__ import division, print_function
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 # Standard library
 import os

diff --git a/gala/dynamics/tests/test_util.py b/gala/dynamics/tests/test_util.py
@@ -4,7 +4,6 @@
 
 from __future__ import division, print_function
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 # Third-party
 import numpy as np

diff --git a/gala/dynamics/util.py b/gala/dynamics/util.py
@@ -4,7 +4,6 @@
 
 from __future__ import division, print_function
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 # Third-party
 import astropy.units as u

diff --git a/gala/integrate/core.py b/gala/integrate/core.py
@@ -4,7 +4,6 @@
 
 from __future__ import division, print_function
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 # Third-party
 import numpy as np

diff --git a/gala/integrate/cyintegrators/dop853.pyx b/gala/integrate/cyintegrators/dop853.pyx
@@ -9,7 +9,6 @@
 
 from __future__ import division, print_function
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 # Third-party
 import numpy as np

diff --git a/gala/integrate/cyintegrators/leapfrog.pyx b/gala/integrate/cyintegrators/leapfrog.pyx
@@ -9,7 +9,6 @@
 
 from __future__ import division, print_function
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 # Third-party
 import numpy as np

diff --git a/gala/integrate/pyintegrators/dopri853.py b/gala/integrate/pyintegrators/dopri853.py
@@ -4,7 +4,6 @@
 
 from __future__ import division, print_function
 
-__author__ = "adrn <adrn@astro.columbia.edu>"
 
 # Third-party
 from scipy.integrate import ode