Welcome to galpy’s documentation¶
galpy is a Python 2 and 3 package for galactic dynamics. It supports orbit integration in a variety of potentials, evaluating and sampling various distribution functions, and the calculation of action-angle coordinates for all static potentials.
Quick-start guide¶
- Installation
- NEW in v1.2: What’s new?
- Introduction
- Potentials in galpy
- Potentials and forces
- Densities
- Close-to-circular orbits and orbital frequencies
- Using interpolations of potentials
- NEW in v1.2: Initializing potentials with parameters with units
- NEW in v1.2: General density/potential pairs with basis-function expansions
- The potential of N-body simulations
- Conversion to NEMO potentials
- Adding potentials to the galpy framework
- Two-dimensional disk distribution functions
- Types of disk distribution functions
- Evaluating moments of the DF
- Using corrected disk distribution functions
- Oort constants and functions
- Sampling data from the DF
- Non-axisymmetric, time-dependent disk distribution functions
- Example: The Hercules stream in the Solar neighborhood as a result of the Galactic bar
- A closer look at orbit integration
- Action-angle coordinates
- Action-angle coordinates for the isochrone potential
- Action-angle coordinates for spherical potentials
- Action-angle coordinates using the adiabatic approximation
- Action-angle coordinates using the Staeckel approximation
- Action-angle coordinates using an orbit-integration-based approximation
- NEW in v1.2 Action-angle coordinates using the TorusMapper code
- Accessing action-angle coordinates for Orbit instances
- Example: Evidence for a Lindblad resonance in the Solar neighborhood
- Example: actions in an N-body simulation
- Three-dimensional disk distribution functions
Tutorials¶
Library reference¶
Acknowledging galpy¶
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).
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!
When using the galpy.actionAngle.actionAngleAdiabatic
and galpy.actionAngle.actionAngleStaeckel
modules, please cite 2013ApJ…779..115B in addition to the papers describing the algorithm used. When using galpy.actionAngle.actionAngleIsochroneApprox
, please cite 2014ApJ…795…95B, which introduced this technique.
Papers using galpy¶
galpy
is described in detail in this publication:
- galpy: A Python Library for Galactic Dynamics, Jo Bovy (2015), Astrophys. J. Supp., 216, 29 (2015ApJS..216…29B).
The following is a list of publications using galpy
; please let me (bovy at astro dot utoronto dot ca) know if you make use of galpy
in a publication.
- Tracing the Hercules stream around the Galaxy, Jo Bovy (2010), Astrophys. J. 725, 1676 (2010ApJ…725.1676B):
- Uses what later became the orbit integration routines and Dehnen and Shu disk distribution functions.
- The spatial structure of mono-abundance sub-populations of the Milky Way disk, Jo Bovy, Hans-Walter Rix, Chao Liu, et al. (2012), Astrophys. J. 753, 148 (2012ApJ…753..148B):
- Employs galpy orbit integration in
galpy.potential.MWPotential
to characterize the orbits in the SEGUE G dwarf sample.
- On the local dark matter density, Jo Bovy & Scott Tremaine (2012), Astrophys. J. 756, 89 (2012ApJ…756…89B):
- Uses
galpy.potential
force and density routines to characterize the difference between the vertical force and the surface density at large heights above the MW midplane.
- The Milky Way’s circular velocity curve between 4 and 14 kpc from APOGEE data, Jo Bovy, Carlos Allende Prieto, Timothy C. Beers, et al. (2012), Astrophys. J. 759, 131 (2012ApJ…759..131B):
- Utilizes the Dehnen distribution function to inform a simple model of the velocity distribution of APOGEE stars in the Milky Way disk and to create mock data.
- A direct dynamical measurement of the Milky Way’s disk surface density profile, disk scale length, and dark matter profile at 4 kpc < R < 9 kpc, Jo Bovy & Hans-Walter Rix (2013), Astrophys. J. 779, 115 (2013ApJ…779..115B):
- Makes use of potential models, the adiabatic and Staeckel actionAngle modules, and the quasiisothermal DF to model the dynamics of the SEGUE G dwarf sample in mono-abundance bins.
- The peculiar pulsar population of the central parsec, Jason Dexter & Ryan M. O’Leary (2013), Astrophys. J. Lett., 783, L7 (2014ApJ…783L…7D):
- Uses galpy for orbit integration of pulsars kicked out of the Galactic center.
- Chemodynamics of the Milky Way. I. The first year of APOGEE data, Friedrich Anders, Christina Chiappini, Basilio X. Santiago, et al. (2013), Astron. & Astrophys., 564, A115 (2014A&A…564A.115A):
- Employs galpy to perform orbit integrations in
galpy.potential.MWPotential
to characterize the orbits of stars in the APOGEE sample.
- Dynamical modeling of tidal streams, Jo Bovy (2014), Astrophys. J., 795, 95 (2014ApJ…795…95B):
- Introduces
galpy.df.streamdf
andgalpy.actionAngle.actionAngleIsochroneApprox
for modeling tidal streams using simple models formulated in action-angle space (see the tutorial above).
- The Milky Way Tomography with SDSS. V. Mapping the Dark Matter Halo, Sarah R. Loebman, Zeljko Ivezic Thomas R. Quinn, Jo Bovy, Charlotte R. Christensen, Mario Juric, Rok Roskar, Alyson M. Brooks, & Fabio Governato (2014), Astrophys. J., 794, 151 (2014ApJ…794..151L):
- Uses
galpy.potential
functions to calculate the acceleration field of the best-fit potential in Bovy & Rix (2013) above.
- The Proper Motion of the Galactic Center Pulsar Relative to Sagittarius A*, Geoffrey C. Bower, Adam Deller, Paul Demorest, et al. (2015), Astrophys. J., 798, 120 (2015ApJ…798..120B):
- Utilizes
galpy.orbit
integration in Monte Carlo simulations of the possible origin of the pulsar PSR J1745-2900 near the black hole at the center of the Milky Way.
- The power spectrum of the Milky Way: Velocity fluctuations in the Galactic disk, Jo Bovy, Jonathan C. Bird, Ana E. Garcia Perez, Steven M. Majewski, David L. Nidever, & Gail Zasowski (2015), Astrophys. J., 800, 83 (2015ApJ…800…83B):
- Uses
galpy.df.evolveddiskdf
to calculate the mean non-axisymmetric velocity field due to different non-axisymmetric perturbations and compares it to APOGEE data.
- The LMC geometry and outer stellar populations from early DES data, Eduardo Balbinot, B. X. Santiago, L. Girardi, et al. (2015), Mon. Not. Roy. Astron. Soc., 449, 1129 (2015MNRAS.449.1129B):
- Employs
galpy.potential.MWPotential
as a mass model for the Milky Way to constrain the mass of the LMC.
- Generation of mock tidal streams, Mark A. Fardal, Shuiyao Huang, & Martin D. Weinberg (2015), Mon. Not. Roy. Astron. Soc., 452, 301 (2015MNRAS.452..301F):
- Uses
galpy.potential
andgalpy.orbit
for orbit integration in creating a particle-spray model for tidal streams.
- The nature and orbit of the Ophiuchus stream, Branimir Sesar, Jo Bovy, Edouard J. Bernard, et al. (2015), Astrophys. J., 809, 59 (2015ApJ…809…59S):
- Uses the
Orbit.fit
routine ingalpy.orbit
to fit the orbit of the Ophiuchus stream to newly obtained observational data and the routines ingalpy.df.streamdf
to model the creation of the stream.
- Young Pulsars and the Galactic Center GeV Gamma-ray Excess, Ryan M. O’Leary, Matthew D. Kistler, Matthew Kerr, & Jason Dexter (2015), Phys. Rev. Lett., submitted (arXiv/1504.02477):
- Uses galpy orbit integration and
galpy.potential.MWPotential2014
as part of a Monte Carlo simulation of the Galactic young-pulsar population.
- Phase Wrapping of Epicyclic Perturbations in the Wobbly Galaxy, Alexander de la Vega, Alice C. Quillen, Jeffrey L. Carlin, Sukanya Chakrabarti, & Elena D’Onghia (2015), Mon. Not. Roy. Astron. Soc., 454, 933 (2015MNRAS.454..933D):
- Employs galpy orbit integration,
galpy.potential
functions, andgalpy.potential.MWPotential2014
to investigate epicyclic motions induced by the pericentric passage of a large dwarf galaxy and how these motions give rise to streaming motions in the vertical velocities of Milky Way disk stars.
- Chemistry of the Most Metal-poor Stars in the Bulge and the z ≳ 10 Universe, Andrew R. Casey & Kevin C. Schlaufman (2015), Astrophys. J., 809, 110 (2015ApJ…809..110C):
- This paper employs galpy orbit integration in
MWPotential
to characterize the orbits of three very metal-poor stars in the Galactic bulge.
- The Phoenix stream: a cold stream in the Southern hemisphere, E. Balbinot, B. Yanny, T. S. Li, et al. (2015), Astrophys. J., 820, 58 (2016ApJ…820…58B).
- Discovery of a Stellar Overdensity in Eridanus-Phoenix in the Dark Energy Survey, T. S. Li, E. Balbinot, N. Mondrik, et al. (2015), Astrophys. J., 817, 135 (2016ApJ…817..135L):
- Both of these papers use galpy orbit integration to integrate the orbit of NGC 1261 to investigate a possible association of this cluster with the newly discovered Phoenix stream and Eridanus-Phoenix overdensity.
- The Proper Motion of Palomar 5, T. K. Fritz & N. Kallivayalil (2015), Astrophys. J., 811, 123 (2015ApJ…811..123F):
- This paper makes use of the
galpy.df.streamdf
model for tidal streams to constrain the Milky Way’s gravitational potential using the kinematics of the Palomar 5 cluster and stream.
- Spiral- and bar-driven peculiar velocities in Milky Way-sized galaxy simulations, Robert J. J. Grand, Jo Bovy, Daisuke Kawata, Jason A. S. Hunt, Benoit Famaey, Arnaud Siebert, Giacomo Monari, & Mark Cropper (2015), Mon. Not. Roy. Astron. Soc., 453, 1867 (2015MNRAS.453.1867G):
- Uses
galpy.df.evolveddiskdf
to calculate the mean non-axisymmetric velocity field due to the bar in different parts of the Milky Way.
- Vertical kinematics of the thick disc at 4.5 ≲ R ≲ 9.5 kpc, Kohei Hattori & Gerard Gilmore (2015), Mon. Not. Roy. Astron. Soc., 454, 649 (2015MNRAS.454..649H):
- This paper uses
galpy.potential
functions to set up a realistic Milky-Way potential for investigating the kinematics of stars in the thick disk.
- Local Stellar Kinematics from RAVE data - VI. Metallicity Gradients Based on the F-G Main-sequence Stars, O. Plevne, T. Ak, S. Karaali, S. Bilir, S. Ak, Z. F. Bostanci (2015), Pub. Astron. Soc. Aus., 32, 43 (2015PASA…32…43P):
- This paper employs galpy orbit integration in
MWPotential2014
to calculate orbital parameters for a sample of RAVE F and G dwarfs to investigate the metallicity gradient in the Milky Way.
- Dynamics of stream-subhalo interactions, Jason L. Sanders, Jo Bovy, & Denis Erkal (2015), Mon. Not. Roy. Astron. Soc., 457, 3817 (2016MNRAS.457.3817S):
- Uses and extends
galpy.df.streamdf
to build a generative model of the dynamical effect of sub-halo impacts on tidal streams. This new functionality is contained ingalpy.df.streamgapdf
, a subclass ofgalpy.df.streamdf
, and can be used to efficiently model the effect of impacts on the present-day structure of streams in position and velocity space.
- Extremely metal-poor stars from the cosmic dawn in the bulge of the Milky Way, L. M. Howes, A. R. Casey, M. Asplund, et al. (2015), Nature, 527, 484 (2015Natur.527..484H):
- Employs galpy orbit integration in
MWPotential2014
to characterize the orbits of a sample of extremely metal-poor stars found in the bulge of the Milky Way. This analysis demonstrates that the orbits of these metal-poor stars are always close to the center of the Milky Way and that these stars are therefore true bulge stars rather than halo stars passing through the bulge.
- Detecting the disruption of dark-matter halos with stellar streams, Jo Bovy (2016), Phys. Rev. Lett., 116, 121301 (2016PhRvL.116l1301B):
- Uses galpy functions in
galpy.df
to estimate the velocity kick imparted by a disrupting dark-matter halo on a stellar stream. Also employsgalpy.orbit
integration andgalpy.actionAngle
functions to analyze N-body simulations of such an interaction.
- Identification of Globular Cluster Stars in RAVE data II: Extended tidal debris around NGC 3201, B. Anguiano, G. M. De Silva, K. Freeman, et al. (2016), Mon. Not. Roy. Astron. Soc., 457, 2078 (2016MNRAS.457.2078A):
- Employs
galpy.orbit
integration to study the orbits of potential tidal-debris members of NGC 3201.
- Young and Millisecond Pulsar GeV Gamma-ray Fluxes from the Galactic Center and Beyond, Ryan M. O’Leary, Matthew D. Kistler, Matthew Kerr, & Jason Dexter (2016), Phys. Rev. D, submitted (arXiv/1601.05797):
- Uses
galpy.orbit
integration inMWPotential2014
for orbit integration of pulsars kicked out of the central region of the Milky Way.
- Abundances and kinematics for ten anticentre open clusters, T. Cantat-Gaudin, P. Donati, A. Vallenari, R. Sordo, A. Bragaglia, L. Magrini (2016), Astron. & Astrophys., 588, A120 (2016A&A…588A.120C):
- Uses
galpy.orbit
integration inMWPotential2014
to characterize the orbits of 10 open clusters located toward the Galactic anti-center, finding that the most distant clusters have high-eccentricity orbits.
- A Magellanic Origin of the DES Dwarfs, P. Jethwa, D. Erkal, & V. Belokurov (2016), Mon. Not. Roy. Astron. Soc., submitted (arXiv/1603.04420):
- Employs the C implementations of
galpy.potential
s to compute forces in orbit integrations of the LMC’s satellite-galaxy population.
- PSR J1024-0719: A Millisecond Pulsar in an Unusual Long-Period Orbit, D. L. Kaplan, T. Kupfer, D. J. Nice, et al. (2016), Astrophys. J., submitted (arXiv/1604.00131):
- A millisecond pulsar in an extremely wide binary system, C. G. Bassa, G. H. Janssen, B. W. Stappers, et al. (2016), Mon. Not. Roy. Astron. Soc., submitted (arXiv/1604.00129):
- Both of these papers use
galpy.orbit
integration inMWPotential2014
to determine the orbit of the milli-second pulsar PSR J1024−0719, a pulsar in an unusual binary system.
- The first low-mass black hole X-ray binary identified in quiescence outside of a globular cluster, B. E. Tetarenko, A. Bahramian, R. M. Arnason, et al. (2016), Astrophys. J., in press (arXiv/1605.00270):
- This paper employs
galpy.orbit
integration of orbits within the position-velocity uncertainty ellipse of the radio source VLA J213002.08+120904 to help characterize its nature (specifically, to rule out that it is a magnetar based on its birth location).
- Action-based Dynamical Modelling for the Milky Way Disk, Wilma H. Trick, Jo Bovy, & Hans-Walter Rix (2016), Astrophys. J., in press (arXiv/1605.08601):
- Makes use of potential models, the Staeckel actionAngle modules, and the quasiisothermal DF to develop a robust dynamical modeling approach for recovering the Milky Way’s gravitational potential from kinematics of disk stars.
- A Dipole on the Sky: Predictions for Hypervelocity Stars from the Large Magellanic Cloud, Douglas Boubert & N. W. Evans (2016), Astrophys. J. Lett., in press (arXiv/1606.02548):
- Uses
galpy.orbit
integration to investigate the orbits of hyper-velocity stars that could be ejected from the Large Magellanic Cloud and their distribution on the sky.
- Linear perturbation theory for tidal streams and the small-scale CDM power spectrum, Jo Bovy, Denis Erkal, & Jason L. Sanders (2016), Mon. Not. Roy. Astron. Soc., submitted (arXiv/1606.03470):
- Uses and extends
galpy.df.streamdf
andgalpy.df.streamgapdf
to quickly compute the effect of impacts from dark-matter subhalos on stellar streams and investigates the structure of perturbed streams and how this structure relates to the CDM subhalo mass spectrum.
- Local Stellar Kinematics from RAVE data - VII. Metallicity Gradients from Red Clump Stars, O. Onal Tas, S. Bilir, G. M. Seabroke, S. Karaali, S. Ak, T. Ak, & Z. F. Bostanci, Pub. Astron. Soc. Aus., in press (arXiv/1607.07049):
- Employs galpy orbit integration in
MWPotential2014
to calculate orbital parameters for a sample of red clump stars in RAVE to investigate the metallicity gradient in the Milky Way.
- Study of Eclipsing Binary and Multiple Systems in OB Associations IV: Cas OB6 Member DN Cas, V. Bakis, H. Bakis, S. Bilir, Z. Eker, Pub. Astron. Soc. Aus., in press (arXiv/1608.00456):
- Uses galpy orbit integration in
MWPotential2014
to calculate the orbit and orbital parameters of the spectroscopic binary DN Cas in the Milky Way.