# Welcome to galpy’s documentation¶

galpy is a Python 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. galpy is an astropy affiliated package and provides full support for astropy’s Quantity framework 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 how to contribute to the code, please head over to galpy’s GitHub page for more information.

As a preview of the kinds of things you can do with galpy, here’s a video introducing some of the new features in galpy v1.5:

Excited to announce the new version (v1.5) of galpy!https://t.co/sVlP7utkc6

— Jo Bovy (@jobovy) September 16, 2019

Many new features, see them all here:https://t.co/KZ6ZaQCNvv

Watch the video below for a quick intro to some of the most exciting new capabilities: pic.twitter.com/HqUgAeVz24

## Quick-start guide¶

- Installation
- What’s new?
- Introduction
- Potentials in galpy
- Potentials and forces
- Densities
- Modifying potential instances using wrappers
- Close-to-circular orbits and orbital frequencies
**UPDATED IN v1.7**Using interpolations of potentials- Initializing potentials with parameters with units
**UPDATED IN v1.7**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
- 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 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
- 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
- Dynamical modeling of tidal streams

## Library reference¶

- Orbit (
`galpy.orbit`

) - Potential (
`galpy.potential`

) - actionAngle (
`galpy.actionAngle`

) - DF (
`galpy.df`

)- Jeans modeling tools (
`galpy.df.jeans`

) - General instance routines for all df classes
**NEW in v1.7**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

- Jeans modeling tools (
- Utilities (
`galpy.util`

)

## 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:

`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 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¶

`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: