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.5
+++++
This version will be the last to support Python 2.7 as this version of Python is `reaching end-of-life on January 1 2020 `__.
* This version's highlight is a fully re-written implementation of
``galpy.orbit.Orbit`` such that it can now contain and manipulate
multiple objects at once. ``galpy.orbit.Orbit`` can be initialized
with an arbitrary shape of input objects in a :ref:`variety of ways
`, manipulated in a manner similar to Numpy arrays, and
all ``Orbit`` methods work efficiently on ``Orbit`` instances
containing multiple objects. Some methods, such as :ref:`orbit
integration ` and those for :ref:`fast orbital
characterization ` are parallelized on multi-core
machines. ``Orbit`` instances can contain and manipulate millions of
objects simultaneously now.
* Added the ``galpy.potentials.mwpotentials`` module with various
Milky-Way-like potentials. Currently included are MWPotential2014,
McMillan17 for the potential from McMillan (2017), models 1 through
4 from Dehnen & Binney (1998), and the three models from Irrgang et
al. (2013). See :ref:`this section of the API documentation
` for details.
* Added a (JSON) list with the phase-space coordinates of known
objects (mainly Milky Way globular clusters and dwarf galaxies) for
easy :ref:`Orbit.from_name initialization `. For
ease of use, Orbit.from_name also supports tab completion for known
objects in this list in IPython/Jupyter.
* Added ``galpy.potential.to_amuse`` to create an `AMUSE
`__ representation of any galpy potential,
:ref:`allowing galpy potentials to be used as external gravitational
fields in AMUSE N-body simulations `.
* New or improved potentials and :ref:`potential wrappers `:
* `MovingObjectPotential `__: Re-wrote ``potential.MovingObjectPotential`` to allow general mass distributions for the moving object, implemented now as standard galpy potentials. Also added a C implementation of this potential for fast orbit integration.
* `IsothermalDiskPotential `__: The one-dimensional potential of an isothermal self-gravitating disk (sech^2 profile).
* `NumericalPotentialDerivativesMixin `__: a Mixin class to add numerically-computed forces and second derivatives to any Potential class, allowing new potentials to be implmented quickly by only implementing the potential itself and obtaining all forces and second derivatives numerically.
* `DehnenSmoothWrapperPotential `__: Can now decay rather than grow a potential by setting ``decay=True``.
* Added support to combine Potential instances or lists thereof through the addition operator. E.g., ``pot= pot1+pot2+pot3`` to create the combined potential of the three component potentials (pot1,pot2,pot3). Each of these components can be a combined potential itself. As before, combined potentials are simply lists of potentials, so this is simply an alternative (and perhaps more intuitive) way to create these lists.
* Added support to adjust the amplitude of a Potential instance through multiplication of the instance by a number or through division by a numer. E.g., ``pot= 2.*pot1`` returns a Potential instance that is the same as pot1, except that the amplitude is twice larger. Similarly, ``pot= pot1/2.`` decreases the amplitude by a factor of two. This is useful, for example, to quickly change the mass of a potential. Only works for Potential instances, not for lists of Potential instances.
* New or improved ``galpy.orbit.Orbit`` functionality and methods:
* Added support for 1D orbit integration in C.
* Added support to plot arbitrary combinations of the basic Orbit attributes by giving them as an expresion (e.g., ``orb.plot(d2='vR*R/r+vz*z/r')``); requires the `numexpr `__ package.
* Switched default Sun's vertical height zo parameter for Orbit initialization to be the value of 20.8 pc from `Bennett & Bovy (2019) `__.
* Add Python and C implementation of Dormand-Prince 8(5,3) integrator.
v1.4
+++++
* Added dynamical friction as the `ChandrasekharDynamicalFrictionForce
`__ class, an
implementation of dynamical friction based on the classical
Chandrasekhar formula (with recent tweaks from the literature to
better represent the results from N-body simulations).
* A general ``EllipsoidalPotential`` superclass for implementing
potentials with densities that are constant on ellipsoids (functions
of :math:`m^2 = x^2 + y^2/b^2 + z^2/c^2`). Also implemented in
C. Implementing new types of ellipsoidal potentials now only
requires three simple functions to be defined: the density as a
function of m, its derivative with respect to m, and its integral
with respect to m^2. Makes implementing any ellipsoidal potential a
breeze. See examples in the new-potentials section below.
* New or improved potentials and :ref:`potential wrappers `:
* `CorotatingRotationWrapperPotential `__: wrapper to make a pattern (e.g., a `SpiralArmsPotential `__) wind up over time such that it is always corotating (see `Hunt et al. (2018) `_ for an example of this).
* `GaussianAmplitudeWrapperPotential `__: wrapper to modulate the amplitude of a (list of) ``Potential`` (s) with a Gaussian.
* `PerfectEllipsoidPotential `__: Potential of a perfect triaxial ellipsoid (`de Zeeuw 1985 `__).
* `SphericalShellPotential `__: Potential of a thin, spherical shell.
* `RingPotential `__: Potential of a circular ring.
* Re-implemented ``TwoPowerTriaxialPotential``, ``TriaxialHernquistPotential``, ``TriaxialJaffePotential``, and ``TriaxialNFWPotential`` using the general ``EllipsoidalPotential`` class.
* New ``Potential`` methods and functions:
* Use nested lists of ``Potential`` instances wherever lists of ``Potential`` instances can be used. Allows easy adding of components (e.g., a bar) to previously defined potentials (which may be lists themselves): new_pot= [pot,bar_pot].
* `rtide `__ and `ttensor `__: compute the tidal radius of an object and the full tidal tensor.
* `surfdens `__ method and `evaluateSurfaceDensities `__ function to evaluate the surface density up to a given z.
* `r2deriv `__ and `evaluater2derivs `__: 2nd derivative wrt spherical radius.
* `evaluatephi2derivs `__: second derivative wrt phi.
* `evaluateRphiderivs `__: mixed (R,phi) derivative.
* New or improved ``galpy.orbit.Orbit`` functionality and methods:
* `Orbit.from_name `__ to initialize an ``Orbit`` instance from an object's name. E.g., ``orb= Orbit.from_name('LMC')``.
* Orbit initialization without arguments is now the orbit of the Sun.
* Orbits can be initialized with a `SkyCoord `__.
* Default ``solarmotion=`` parameter is now 'schoenrich' for the Solar motion of `Schoenrich et al. (2010) `__.
* `rguiding `__: Guiding-center radius.
* `Lz `__: vertical component of the angular momentum.
* If astropy version > 3, `Orbit.SkyCoord `__ method returns a SkyCoord object that includes the velocity information and the Galactocentric frame used by the Orbit instance.
* ``galpy.df.jeans`` module with tools for Jeans modeling. Currently only contains the functions `sigmar `__ and `sigmalos `__ to calculate the velocity dispersion in the radial or line-of-sight direction using the spherical Jeans equation in a given potential, density profile, and anisotropy profile (anisotropy can be radially varying).
* Support for compilation on Windows with MSVC.
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
`__). 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
` 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 ` of the
documentation for examples and :ref:`this section ` for
information on how to easily define new wrappers. Example wrappers
include `SolidBodyRotationWrapperPotential
`__ to allow *any*
potential to rotate as a solid body and
`DehnenSmoothWrapperPotential
`__ to smoothly
grow *any* potential. See :ref:`this section of the galpy.potential
API page ` for an up-to-date list of wrappers.
* New or improved potentials:
* `DiskSCFPotential `__: a general Poisson solver well suited for galactic disks
* Bar potentials `SoftenedNeedleBarPotential `__ and `FerrersPotential `__ (latter only in Python for now)
* 3D spiral arms model `SpiralArmsPotential `__
* Henon & Heiles (1964) potential `HenonHeilesPotential `__
* Triaxial version of `LogarithmicHaloPotential `__
* 3D version of `DehnenBarPotential `__
* Generalized version of `CosmphiDiskPotential `__
* New or improved ``galpy.orbit.Orbit`` methods:
* Method to display an animation of an integrated orbit in jupyter notebooks: `Orbit.animate `__. See :ref:`this section ` 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 `__:the simple Schwarzschild distribution function for a razor-thin disk (useful for teaching).
v1.2
+++++
* Full support for providing inputs to all initializations, methods,
and functions as `astropy Quantity
`__
with `units `__ and for
providing outputs as astropy Quantities.
* ``galpy.potential.TwoPowerTriaxialPotential``, a set of triaxial
potentials with iso-density contours that are arbitrary, similar,
coaxial ellipsoids whose 'radial' density is a (different) power-law
at small and large radii: 1/m^alpha/(1+m)^beta-alpha (the triaxial
generalization of TwoPowerSphericalPotential, with flattening in the
density rather than in the potential; includes triaxial Hernquist
and NFW potentials.
* ``galpy.potential.SCFPotential``, a class that implements general
density/potential pairs through the basis expansion approach to
solving the Poisson equation of Hernquist & Ostriker (1992). Also
implemented functions to compute the coefficients for a given
density function. See more explanation :ref:`here
`.
* ``galpy.actionAngle.actionAngleTorus``: an experimental interface to
Binney & McMillan's TorusMapper code for computing positions and
velocities for given actions and angles. See the installation
instructions for how to properly install this. See :ref:`this
section ` and the ``galpy.actionAngle`` API page for
documentation.
* ``galpy.actionAngle.actionAngleIsochroneApprox`` (Bovy 2014) now
implemented for the general case of a time-independent potential.
* ``galpy.df.streamgapdf``, a module for modeling the effect of a
dark-matter subhalo on a tidal stream. See `Sanders et al. (2016)
`__. Also
includes the fast methods for computing the density along the stream
and the stream track for a perturbed stream from `Bovy et al. (2016)
`__.
* ``Orbit.flip`` can now flip the velocities of an orbit in-place by
specifying ``inplace=True``. This allows correct velocities to be
easily obtained for backwards-integrated orbits.
* ``galpy.potential.PseudoIsothermalPotential``, a standard
pseudo-isothermal-sphere
potential. ``galpy.potential.KuzminDiskPotential``, a razor-thin
disk potential.
* Internal transformations between equatorial and Galactic coordinates
are now performed by default using astropy's `coordinates
`__
module. Transformation of (ra,dec) to Galactic coordinates for
general epochs.
v1.1
+++++
* Full support for Python 3.
* ``galpy.potential.SnapshotRZPotential``, a potential class that can
be used to get a frozen snapshot of the potential of an N-body
simulation.
* Various other potentials: ``PlummerPotential``, a standard Plummer
potential; ``MN3ExponentialDiskPotential``, an approximation to an
exponential disk using three Miyamoto-Nagai potentials (`Smith et
al. 2015 `__);
``KuzminKutuzovStaeckelPotential``, a Staeckel potential that can be
used to approximate the potential of a disk galaxy (`Batsleer &
Dejonghe 1994
`__).
* Support for converting potential parameters to `NEMO
`__ format and units.
* Orbit fitting in custom sky coordinates.