Welcome to galpy’s documentation (2024)

galpy is a Python package for galacticdynamics. It supports orbit integration in a variety of potentials,evaluating and sampling various distribution functions, and thecalculation of action-angle coordinates for all staticpotentials. galpy is an astropy affiliated package andprovides full support for astropy’s Quantityframework for variables with units.

galpy is developed on GitHub. If you are looking to report an issue, join the galpy slack community, or for information on howto contribute to the code,please head over to galpy’s GitHub page for more information.

Try `galpy`¶

Give galpy a try in the interactive IPython-like shell below!

Plot the rotation curve of the Milky Way

>>> from galpy.potential import (plotRotcurve, MWPotential2014 as mwp14)>>> import matplotlib.pyplot as plt>>> plotRotcurve(mwp14)>>> plotRotcurve(mwp14[0],label='Bulge',overplot=True)>>> plotRotcurve(mwp14[1],label='Disk',overplot=True)>>> plotRotcurve(mwp14[2],label='Halo',overplot=True)>>> plt.legend()

or calculate the Sun's orbital actions, frequencies, and angles

>>> from galpy.orbit import Orbit>>> from galpy.potential import ( MWPotential2014 as mwp14)>>> o= Orbit()>>> print(o.jr(pot=mwp14),o.Lz(),o.jz(pot=mwp14))>>> print(o.Or(pot=mwp14),o.Op(pot=mwp14),o.Oz(pot=mwp14))>>> print(o.wr(pot=mwp14),o.wp(pot=mwp14),o.wz(pot=mwp14))

and much more... Start your journey below

(This interactive shell runs using the pyodide Python kernel, a version of Python that runs in your browser. galpy runs in your browser at compiled-C-like speed! Please open an Issue for any problems that you find with the interactive session.)

Quick-start guide¶

Installation
- TL;DR
- Dependencies
- Detailed installation instructions
- Development installation
- More esoteric installations
- Installation FAQ
- Configuration file
What’s new?
- v1.10
- v1.9
- v1.8
- v1.7
- v1.6
- v1.5
- Pre-v1.5
Introduction
- Rotation curves
- Units in galpy
- Orbit integration
- Escape velocity curves
Potentials in galpy
- Potentials and forces
- Densities
- Modifying potential instances using wrappers
- Close-to-circular orbits and orbital frequencies
- Using interpolations of potentials
- Initializing potentials with parameters with units
- General density/potential pairs with basis-function expansions
- The potential of N-body simulations
- Conversion to NEMO potentials
- Conversion to AMUSE potentials
- Dissipative forces
- Adding potentials to the galpy framework
- Adding wrapper potentials to the galpy framework
- Adding dissipative forces to the galpy framework
A closer look at orbit integration
- Orbit initialization
- Orbit integration
- Orbit integration in non-inertial frames
- Displaying the orbit
- Animating the orbit
- Orbit characterization
- Fast orbit characterization
- Accessing the raw orbit
- Fast orbit integration and available integrators
- Surfaces of section
- Integration of the phase-space volume
- Example: The eccentricity distribution of the Milky Way’s thick disk
- Example: The orbit of the Large Magellanic Cloud in the presence of dynamical friction
- Example: Including the Milky Way center’s barycentric acceleration due to the Large Magellanic Cloud in orbit integrations
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
Action-angle coordinates
- Action-angle coordinates for the isochrone/harmonic potentials
- Forward action-angle transformations (x, v) –> (J, O, a)
- Reverse action-angle transformations (J, a) –> (x, v, O)
- 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
- Setting up the DF and basic properties
- Evaluating moments
- Evaluating and sampling the full probability distribution function
Dynamical modeling of tidal streams
- Modeling streams in action-angle coordinates with streamdf
- Particle-spray modeling of streams with streamspraydf

Library reference¶

Orbit (galpy.orbit)
- Initialization
- Plotting
- Attributes
- Methods
Potential (galpy.potential)
- 3D potentials
- Milky-Way-like potentials
- 2D potentials
- 1D potentials
- Potential wrappers
actionAngle (galpy.actionAngle)
- (x, v) –> (J, O, a)
- (J, a) –> (x, v, O)
DF (galpy.df)
- Jeans modeling tools (galpy.df.jeans)
- General instance routines for all df classes
- Spherical distribution functions
- Two-dimensional, axisymmetric disk distribution functions
- Two-dimensional, non-axisymmetric disk distribution functions
- Three-dimensional disk distribution functions
- The distribution function of a tidal stream in action-angle coordinates
- The distribution function of a gap in a tidal stream
- The distribution function of a tidal stream using a particle-spray technique
Utilities (galpy.util)
- config: galpy configuration module
- plot: general wrappers for matplotlib plotting
- conversion: transformation between *natural* units and *physical* units
- coords: coordinate transformation functions
- ars: adaptive-rejection sampling

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’sfunctionality is introduced in separate papers:

galpy.actionAngle.EccZmaxRperiRap and galpy.orbit.Orbit methods with analytic=True: Fast method for computing orbital parameters from this section: please cite Mackereth & Bovy (2018).
galpy.actionAngle.actionAngleAdiabatic: please cite Binney (2010).
galpy.actionAngle.actionAngleStaeckel: please cite Bovy & Rix (2013) and Binney (2012).
galpy.actionAngle.actionAngleIsochroneApprox: please cite Bovy (2014).
galpy.df.streamdf: please cite Bovy (2014).
galpy.df.streamgapdf: please cite Sanders, Bovy, & Erkal (2016).
galpy.df.streamspraydf: please cite Fardal et al. (2015) for the method and Qian et al. (2022) for the galpy implementation
galpy.potential.ttensor and galpy.potential.rtide: please cite Webb et al. (2019a).
galpy.potential.to_amuse: please cite Webb et al. (2019b).

Please also send me a reference to the paper or send a pull requestincluding your paper in the list of galpy papers on this page (thispage is at doc/source/index.rst). Thanks!

Papers using galpy¶

galpy has been used in more than 200 scientific publications in the astrophysical literature. Covering topics as diverse as the properties of planetary systems around distant stars, the kinematics of pulsars and stars ejected from the Milky Way by supernova explosions, binary evolution in stellar clusters, chemo-dynamical modeling of stellar populations in the Milky Way, and the dynamics of satellites around external galaxies, galpy is widely used throughout astrophysics.

Check out the gallery below for examples:

Index
Module Index
Search Page