Merge tag 'v1.3.0' into staeckelisoinv

.travis.yml

@@ -2,7 +2,7 @@ sudo: false
 language: python
 python:
   - "2.7"
-  - "3.5"
+  - "3.6"
 env: #split tests
   global:
     - REQUIRES_PYNBODY=false
@@ -19,6 +19,8 @@ matrix: # only run crucial tests for python 3.4
   include:
     - python: "3.4"
       env: TEST_FILES='tests/test_orbit.py' REQUIRES_PYNBODY=true REQUIRES_ASTROPY=true
+    - python: "3.5"
+      env: TEST_FILES='tests/test_orbit.py' REQUIRES_PYNBODY=true REQUIRES_ASTROPY=true
 addons:
   apt:
     packages:
@@ -49,7 +51,7 @@ before_install:
  - hash -r
  - conda config --set always_yes yes --set changeps1 no
  - conda update conda
- - conda create -n test-environment python=$TRAVIS_PYTHON_VERSION "numpy<1.14" scipy matplotlib setuptools pip cython>=0.20 pytest
+ - conda create -n test-environment python=$TRAVIS_PYTHON_VERSION numpy scipy matplotlib setuptools pip cython>=0.20 pytest
  - source activate test-environment
  - export DISPLAY=:99.0 #For plotting tests, courtesy Ryan Varley
  - sh -e /etc/init.d/xvfb start $For plotting tests

AUTHORS.txt

@@ -19,11 +19,14 @@ Wilma Trick (KuzminKutuzovPotential and various other contributions)
 Anna Juranova (FerrersPotential)
 Semyeong Oh (FerrersPotential)
 Jack Hong (SpiralArmsPotential)
+Ted Mackereth (addition to estimateDeltaStaeckel function, and fast orbit characterisation docs)
 
 General help:
 ==============
 
 Greg Stinson (advice on SnapshotRZPotential tests)
+Matt Craig (added conda build)
+Brigitta Sipocz (help with conda build)
 
 Bug reports:
 ============
@@ -41,3 +44,6 @@ Eduardo Balbinot
 Semyeong Oh
 Jorrit Hagen
 Ruth Angus
+Anthony Brown
+Larry Widrow
+Jean-François Robitaille

HISTORY.txt

@@ -61,6 +61,10 @@ v1.3 (2017-XX-XX)
 - Changed default method for computing actions, frequencies, and
   angles for Orbit instances to be the Staeckel approximation with an
   automatically-estimated delta parameter.
+
+- Added an option to the estimateDeltaStaeckel function to facilitate the
+  return of an estimated delta parameter at every phase space point passed,
+  rather than returning a median of the estimate at each point.
 
 - Generalized actionAngleStaeckel to allow for different focal lengths
   delta for different phase-space points. Also allowed the order of

README.rst

@@ -39,9 +39,11 @@ full list of contributors.
 If you find this code useful in your research, please let me
 know. **If you use galpy in a publication, please cite** `Bovy (2015)
 <http://adsabs.harvard.edu/abs/2015ApJS..216...29B>`__ **and link to
-http://github.com/jobovy/galpy**. Please also send me a reference to
-the paper or send a pull request including your paper in the list of
-galpy papers on `this page
+http://github.com/jobovy/galpy**. See `the acknowledgement documentation section
+<http://galpy.readthedocs.io/en/latest/index.html#acknowledging-galpy>`__
+for a more detailed guide to citing parts of the code. Please also
+send me a reference to the paper or send a pull request including your
+paper in the list of galpy papers on `this page
 <http://galpy.readthedocs.io/en/latest/>`__ (this page is at
 doc/source/index.rst). Thanks!
 
@@ -55,9 +57,10 @@ PYTHON VERSIONS AND DEPENDENCIES
 ---------------------------------
 
 ``galpy`` supports both Python 2 and 3. Specifically, galpy supports
-Python 2.7 and Python 3.4 and 3.5. It may also work on earlier Python
-3.* versions, but this has not been tested. Travis CI builds regularly
-check support for Python 2.7 and 3.5.
+Python 2.7 and Python 3.4, 3.5, and 3.6. It may also work on earlier
+Python 3.* versions, but this has not been tested. Travis CI builds
+regularly check support for Python 2.7 and 3.6 (and of 3.4/3.5 using a
+limited set of tests).
 
 This package requires `Numpy <http://numpy.scipy.org/>`__, `Scipy
 <http://www.scipy.org/>`__, and `Matplotlib

doc/source/actionAngle.rst

@@ -743,8 +743,8 @@ calculate actions for triaxial potentials by specifying that
 
 .. _aatorus:
 
-**NEW in v1.2** Action-angle coordinates using the TorusMapper code
----------------------------------------------------------------------
+Action-angle coordinates using the TorusMapper code
+----------------------------------------------------
 
 All of the methods described so far allow one to compute the actions,
 angles, and frequencies for a given phase-space location. ``galpy``

doc/source/conf.py

@@ -47,7 +47,7 @@
 # The short X.Y version.
 version = '1.3'
 # The full version, including alpha/beta/rc tags.
-release = '1.3.dev'
+release = '1.3.0'
 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
 if on_rtd:
     version= 'v'+version

doc/source/getting_started.rst

@@ -70,8 +70,8 @@ fit to various dynamical constraints on the Milky Way (see
 
 .. _units:
 
-**UPDATED in v1.2**: Units in galpy
-------------------------------------
+Units in galpy
+---------------
 
 Internal (natural) units
 +++++++++++++++++++++++++

doc/source/index.rst

@@ -89,15 +89,18 @@ If you use galpy in a publication, please cite the following paper
 * *galpy: A Python Library for Galactic Dynamics*, Jo Bovy (2015), *Astrophys. J. Supp.*, **216**, 29 (`arXiv/1412.3451 <http://arxiv.org/abs/1412.3451>`_).
 
 and link to ``http://github.com/jobovy/galpy``. Some of the code's
-functionality is introduced in separate papers (like
-``galpy.df.streamdf`` and ``galpy.df.streamgapdf``, see below), so
-please also cite those papers when using these functions. Please also
-send me a reference to the paper or send a pull request including your
-paper in the list of galpy papers on this page (this page is at
-doc/source/index.rst). Thanks!
+functionality is introduced in separate papers:
 
-When using the ``galpy.actionAngle.actionAngleAdiabatic`` and ``galpy.actionAngle.actionAngleStaeckel`` modules, please cite `2013ApJ...779..115B <http://adsabs.harvard.edu/abs/2013ApJ...779..115B>`_ in addition to the papers describing the algorithm used. When using ``galpy.actionAngle.actionAngleIsochroneApprox``, please cite `2014ApJ...795...95B <http://adsabs.harvard.edu/abs/2014ApJ...795...95B>`_, which introduced this technique.
+* ``galpy.actionAngle.EccZmaxRperiRap`` and ``galpy.orbit.Orbit`` methods with ``analytic=True``: Fast method for computing orbital parameters from :ref:`this section <fastchar>`: please cite `Mackereth & Bovy (2018) <https://www.overleaf.com/docs/fgxwxbkpwcjq/pdf>`__.
+* ``galpy.actionAngle.actionAngleAdiabatic``: please cite `Binney (2010) <http://adsabs.harvard.edu/abs/2010MNRAS.401.2318B>`__.
+* ``galpy.actionAngle.actionAngleStaeckel``:  please cite `Bovy & Rix (2013) <http://adsabs.harvard.edu/abs/2013ApJ...779..115B>`__ and `Binney (2012) <http://adsabs.harvard.edu/abs/2012MNRAS.426.1324B>`__.
+* ``galpy.actionAngle.actionAngleIsochroneApprox``: please cite `Bovy (2014) <http://adsabs.harvard.edu/abs/2014ApJ...795...95B>`__.
+* ``galpy.df.streamdf``: please cite `Bovy (2014) <http://adsabs.harvard.edu/abs/2014ApJ...795...95B>`__.
+* ``galpy.df.streamgapdf``: please cite `Sanders, Bovy, & Erkal (2016) <http://adsabs.harvard.edu/abs/2016MNRAS.457.3817S>`__.
 
+Please also send me a reference to the paper or send a pull request
+including your paper in the list of galpy papers on this page (this
+page is at doc/source/index.rst). Thanks!
 
 Papers using galpy
 --------------------
@@ -247,6 +250,12 @@ The following is a list of publications using ``galpy``; please let me (bovy at
      Employs ``galpy.orbit`` integration in ``MWPotential2014`` to characterize the orbits of 494 nearby stars analyzed as part of the AMBRE project to learn about their distribution within the Milky Way.
 #. *KELT-21b: A Hot Jupiter Transiting the Rapidly-Rotating Metal-Poor Late-A Primary of a Likely Hierarchical Triple System*, Marshall C. Johnson, Joseph E. Rodriguez, George Zhou, et al. (2017) *Astrophys. J.*, submitted (`arXiv/1712.03241 <http://arxiv.org/abs/1712.03241>`_):
      Uses ``galpy.orbit`` integration in ``MWPotential2014`` to investigate the Galactic orbit of KELT-21b, a hot jupiter around a low-metallicity A-type star.
+#. *GalDynPsr: A package to estimate dynamical contributions in the rate of change of the period of radio pulsars*, Dhruv Pathak & Manjari Bagchi (2017) (`arXiv/1712.06590 <http://arxiv.org/abs/1712.06590>`_):
+     Presents a python package to compute contributions to the GR spin-down of pulsars from the differential galactic acceleration between the Sun and the pulsar. The package uses ``MWPotential2014`` and ``galpy.potential`` functions to help compute this.
+#. *Local Stellar Kinematics from RAVE data – VIII. Effects of the Galactic Disc Perturbations on Stellar Orbits of Red Clump Stars*, O. Onal Tas, S. Bilir, &  O. Plevne (2018) *Astrophys. Sp. Sc.*, in press (`arXiv/1801.02170 <http://arxiv.org/abs/1801.02170>`_):
+     Employs ``galpy.orbit`` integration in ``MWPotential2014`` and the non-axisymmetric ``DehnenBarPotential`` and ``SteadyLogSpiralPotential`` to study the orbits of Milky-Way red-clump stars.
+#. *The VMC survey XXVIII. Improved measurements of the proper motion of the Galactic globular cluster 47 Tucanae*, F. Niederhofer, M.-R. L. Cioni, S. Rubele, et al. (2018) *Astron. & Astrophys.*, in press (`arXiv/1801.07738 <http://arxiv.org/abs/1801.07738>`_):
+     Uses ``galpy.orbit`` integration in ``MWPotential2014`` to investigate the orbit of the cluster 47 Tuc from a newly measured proper motion, finding that the orbit has an eccentricity of about 0.2 and reaches up to 3.6 kpc above the Galactic midplane.
 
 
 Indices and tables

doc/source/installation.rst

@@ -1,15 +1,34 @@
 Installation
 ==============
 
-galpy can be installed using pip as::
+With conda
+----------
+
+The easiest way to install the latest released version of galpy is using conda::
+
+    conda install galpy -c conda-forge
+
+or::
+
+	conda config --add channels conda-forge
+	conda install galpy
+
+With pip
+--------
+
+galpy can also be installed using pip. Some advanced features require
+the GNU Scientific Library (GSL; see below). If you want to use
+these, install the GSL first (or install it later and re-install
+using the upgrade command above). Then do::
 
       pip install galpy
 
 or to upgrade without upgrading the dependencies::
 
       pip install -U --no-deps galpy
 
-Some advanced features require the GNU Scientific Library (GSL; see below). If you want to use these, install the GSL first (or install it later and re-install using the upgrade command above).
+Latest version
+--------------
 
 The latest updates in galpy can be installed using::
     
@@ -27,16 +46,21 @@ or::
 
 	python setup.py install --prefix=~/local
 
-for a local installation. A basic installation works with just the
-numpy/scipy/matplotlib stack. Some basic tests can be performed by executing::
+for a local installation.
+
+Installing from a branch
+------------------------
+
+If you want to use a feature that is currently only available in a branch, do::
 
-		       nosetests -v -w nose/
+   pip install -U --no-deps git+git://github.com/jobovy/galpy.git@dev#egg=galpy
 
+to, for example, install the ``dev`` branch.
 
 .. _install_tm:
 
-**NEW in v1.2**: Installing the TorusMapper code
--------------------------------------------------
+Installing the TorusMapper code
+--------------------------------
 
 Since v1.2, ``galpy`` contains a basic interface to the TorusMapper
 code of `Binney & McMillan (2016)
@@ -179,8 +203,8 @@ versions, but it still does not support ``OpenMP``.
 
 .. _configfile:
 
-**NEW in v1.2**: Configuration file
-------------------------------------
+Configuration file
+-------------------
 
 Since v1.2, ``galpy`` uses a configuration file to set a small number
 of configuration variables. This configuration file is parsed using

doc/source/orbit.rst

@@ -3,8 +3,8 @@ A closer look at orbit integration
 
 .. _orbinit:
 
-**UPDATED in v1.2**: Orbit initialization
--------------------------------------------
+Orbit initialization
+--------------------
 
 Standard initialization
 ***********************
@@ -154,8 +154,8 @@ you can turn this behavior off by doing
 
 All outputs will then be specified in galpy's natural coordinates.
 
-**UPDATED in v1.2**: Orbit integration
-----------------------------------------
+Orbit integration
+------------------
 
 After an orbit is initialized, we can integrate it for a set of times
 ``ts``, given as a numpy array. For example, in a simple logarithmic

doc/source/potential.rst

@@ -200,6 +200,8 @@ and the potential is
 
 Clearly, the potential is much less flattened than the density.
 
+.. _potwrappers:
+
 **NEW in v1.3**: Modifying potential instances using wrappers
 -------------------------------------------------------------
 
@@ -362,8 +364,8 @@ evaluations for functions that use ``C`` to speed up computations.
 
 .. _physunits_pot:
 
-**NEW in v1.2**: Initializing potentials with parameters with units
--------------------------------------------------------------------
+Initializing potentials with parameters with units
+--------------------------------------------------
 
 As already discussed in the section on :ref:`physical units
 <physunits>`, potentials in galpy can be specified with parameters
@@ -384,7 +386,7 @@ you find any problems with this.
 
 .. _scf_potential_docs:
 
-**NEW in v1.2/UPDATED in v1.3**: General density/potential pairs with basis-function expansions
+**UPDATED in v1.3**: General density/potential pairs with basis-function expansions
 ------------------------------------------------------------------------------------------------
 
 ``galpy`` allows for the potential and forces of general,

doc/source/streamdf.rst

@@ -396,8 +396,8 @@ PDF will not be quite correct.
 
 .. _streamgap-tutorial:
 
-**NEW in v1.2**: Modeling gaps in streams
--------------------------------------------
+Modeling gaps in streams
+------------------------
 
 ``galpy`` also contains tools to model the effect of impacts due to
 dark-matter subhalos on streams (see `Sanders, Bovy, & Erkal 2015

doc/source/whatsnew.rst

@@ -1,10 +1,59 @@
-**NEW in v1.2**: What's new?
-=============================
+What's new?
+===========
 
 This page gives some of the key improvements in each galpy
 version. See the ``HISTORY.txt`` file in the galpy source for full
 details on what is new and different in each version.
 
+v1.3
++++++
+
+* A fast and precise method for approximating an orbit's eccentricity,
+  peri- and apocenter radii, and maximum height above the midplane
+  using the Staeckel approximation (see `Mackereth & Bovy 2018
+  <https://www.overleaf.com/docs/fgxwxbkpwcjq/pdf>`__). Can determine
+  these parameters to better than a few percent accuracy in as little
+  as 10 :math:`\mu\mathrm{s}` per object, more than 1,000 times faster
+  than through direct orbit integration. See :ref:`this section
+  <fastchar>` of the documentation for more info.
+
+* A general method for modifying ``Potential`` classes through
+  potential wrappers---simple classes that wrap existing potentials to modify
+  their behavior. See :ref:`this section <potwrappers>` of the
+  documentation for examples and :ref:`this section <addwrappot>` for
+  information on how to easily define new wrappers. Example wrappers
+  include `SolidBodyRotationWrapperPotential
+  <reference/potentialsolidbodyrotationwrapper.html>`__ to allow *any*
+  potential to rotate as a solid body and
+  `DehnenSmoothWrapperPotential
+  <reference/potentialsolidbodyrotationwrapper.html>`__ to smoothly
+  grow *any* potential. See :ref:`this section of the galpy.potential
+  API page <potwrapperapi>` for an up-to-date list of wrappers.
+
+* New or improved potentials:
+
+  * `DiskSCFPotential <reference/potentialdiskscf.html>`__: a general Poisson solver well suited for galactic disks
+  * Bar potentials `SoftenedNeedleBarPotential <reference/potentialsoftenedneedle.html>`__ and `FerrersPotential <reference/potentialferrers.html>`__ (latter only in Python for now)
+  * 3D spiral arms model `SpiralArmsPotential <reference/potentialspiralarms.html>`__
+  * Henon & Heiles (1964) potential `HenonHeilesPotential <reference/potentialhenonheiles.html>`__
+  * Triaxial version of `LogarithmicHaloPotential <reference/potentialloghalo.html>`__
+  * 3D version of `DehnenBarPotential <reference/potentialdehnenbar.html>`__
+  * Generalized version of `CosmphiDiskPotential <reference/potentialcosmphidisk.html>`__
+
+* New or improved ``galpy.orbit.Orbit`` methods:
+
+  * Method to display an animation of an integrated orbit in jupyter notebooks: `Orbit.animate <reference/orbitanimate.html>`__. See :ref:`this section <orbanim>` of the documentation.
+  * Improved default method for fast calculation of eccentricity, zmax, rperi, rap, actions, frequencies, and angles by switching to the Staeckel approximation with automatically-estimated approximation parameters.
+  * Improved plotting functions: plotting of spherical radius and of arbitrary user-supplied functions of time in Orbit.plot, Orbit.plot3d, and Orbit.animate.
+
+* ``actionAngleStaeckel`` upgrades:
+
+  * ``actionAngleStaeckel`` methods now allow for different focal lengths delta for different phase-space points and for the order of the Gauss-Legendre integration to be specified (default: 10, which is good enough when using actionAngleStaeckel to compute approximate actions etc. for an axisymmetric potential). 
+  * Added an option to the estimateDeltaStaeckel function to facilitate the return of an estimated delta parameter at every phase space point passed, rather than returning a median of the estimate at each point. 
+
+* `galpy.df.schwarzschilddf <reference/dfschwarzschild.html>`__:the simple Schwarzschild distribution function for a razor-thin disk (useful for teaching).
+
+
 v1.2
 +++++
 

galpy/__init__.py

@@ -1 +1 @@
-__version__ = "1.3.dev"
+__version__ = "1.3.0"

galpy/orbit_src/FullOrbit.py

@@ -702,6 +702,7 @@ def _fit_orbit(orb,vxvv,vxvv_err,pot,radec=False,lb=False,
                ro=None,vo=None,obs=None,disp=False):
     """Fit an orbit to data in a given potential"""
     # Need to turn this off for speed
+    coords._APY_COORDS_ORIG= coords._APY_COORDS
     coords._APY_COORDS= False
     #Import here, because otherwise there is an infinite loop of imports
     from galpy.actionAngle import actionAngleIsochroneApprox, actionAngle
@@ -729,7 +730,7 @@ def __init__(self,tintJ,ntintJ,pot,integrate_method='dopr54_c'):
                                customsky,lb_to_customsky,pmllpmbb_to_customsky,
                                tmockAA,
                                ro,vo,obs)
-    coords._APY_COORDS= True
+    coords._APY_COORDS= coords._APY_COORDS_ORIG
     return (opt_vxvv,maxLogL)
 
 def _fit_orbit_mlogl(new_vxvv,vxvv,vxvv_err,pot,radec,lb,

galpy/potential.py

@@ -1,6 +1,4 @@
 import warnings
-from galpy.util import galpyWarning
-warnings.warn("A major change in versions > 1.1 is that all galpy.potential functions and methods take the potential as the first argument; previously methods such as evaluatePotentials, evaluateDensities, etc. would be called with (R,z,Pot), now they are called as (Pot,R,z) for greater consistency across the codebase",galpyWarning)
 from galpy.potential_src import Potential
 from galpy.potential_src import planarPotential
 from galpy.potential_src import linearPotential