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.

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 integrate the orbit of MW satellites

>>> from galpy.orbit import Orbit
>>> from galpy.potential import MWPotential2014
>>> import numpy
>>> ts= numpy.linspace(0.,5.,2001)*u.Gyr
>>> o= Orbit.from_name('MW satellite galaxies')
>>> o.integrate(ts,MWPotential2014)
>>> o.plot(xrange=[0.,100.],yrange=[-100.,100.])
>>> o[o.name=='LMC'].plot(c='r',lw=5.,overplot=True)

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

Install galpy on Linux, Mac, or Windows via pip or conda, including optional C extensions and configuration. Development installation from source and development setup.

Installation
What’s New

High-level release notes for all galpy versions.

What’s new?
Rotation Curves, Units, and First Orbits

Set up basic potentials, plot rotation curves, understand galpy’s natural and physical unit systems, and integrate a simple orbit.

Getting Started with galpy

Potentials

Introduction to Potentials

Evaluate potentials, forces, and densities. Combine potentials, plot rotation curves and potential contours, compute orbital frequencies and Lindblad resonances.

Introduction to Potentials
Milky Way-like Potentials

Use built-in Milky Way potentials: MWPotential2014, McMillan17, Irrgang13, Cautun20, DehnenBinney98. Add a central black hole or dynamical friction.

Milky Way-like Potentials
Potential Wrappers

Modify potentials with time-dependent amplitudes, solid-body rotation, tilting, and offsetting using wrapper classes.

Potential Wrappers
SCF and Multipole Expansions

Represent arbitrary density distributions using basis-function (SCF) or multipole expansions, including time-dependent and disky potentials.

SCF and Multipole Expansions
Dissipative Forces

Use velocity-dependent forces like Chandrasekhar dynamical friction and non-inertial frame forces for orbit integration. Includes the Schwarzschild precession of S2 around Sgr A*.

Dissipative Forces
N-body Simulation Potentials

Use frozen N-body simulation potentials in galpy with pynbody for orbits, action-angle coordinates, and analysis.

The Potential of N-body Simulations
Using Potentials in Other Codes

Export galpy potentials to NEMO, AMUSE, AGAMA, and gala for use in other simulation frameworks.

Using galpy Potentials in Other Codes

Orbits

Orbit Initialization

Initialize orbits in cylindrical coordinates, with physical units, from observed coordinates (RA/Dec, Galactic), or from astropy SkyCoord objects.

Orbit Initialization
Multiple Orbits

Work with multiple orbits at once: array and SkyCoord initialization, slicing, reshaping, and parallel integration.

Multiple Orbits
Orbits of Known Objects

Initialize orbits from object names using built-in catalogs or SIMBAD. Load collections of MW globular clusters, satellite galaxies, or the solar system.

Orbits of Known Objects
Integration and Plotting

Integrate orbits, display various projections, access orbital quantities, check energy conservation, use non-inertial frames, and compute surfaces of section.

Integration and Plotting
Fast Orbit Characterization

Quickly compute eccentricity, peri/apocenter, and zmax using the Staeckel approximation without orbit integration. Also compute actions!

Fast Orbit Characterization
Orbit Examples

Detailed examples: thick-disk eccentricity distribution, LMC orbit with dynamical friction, and barycentric acceleration from the LMC.

Orbit Examples

Action-Angle Coordinates

Introduction to Action-Angle Coordinates

Overview of action-angle variables, using the Orbit interface, calculating actions for isochrone and spherical potentials, and exact inverse transforms in the isochrone case.

Introduction to Action-Angle Coordinates
Staeckel Approximation

The most accurate general method for computing actions in axisymmetric potentials, with grid-based interpolation for speed. Includes a Gaia example showing Lindblad resonances.

Action-Angle Coordinates: Staeckel Approximation
Adiabatic Approximation

Fast action calculation by separating radial and vertical motions, best for thin-disk orbits.

Action-Angle Coordinates: Adiabatic Approximation
Orbit Integration-based Method

General action-angle calculation by integrating the orbit and using a best-fit isochrone potential.

Action-Angle Coordinates: Orbit Integration-based (IsochroneApprox)
1D Actions and Inverse Transformations

One-dimensional action-angle coordinates for harmonic oscillators and vertical oscillations, and their inverse transformations.

1D Action-Angle Coordinates and Inverse Transformations
Inverse Transformations (TorusMapping)

Compute phase-space coordinates from given actions and angles using the Torus Mapper.

Action-Angle Coordinates: Inverse Transformations (actionAngleTorus)

Distribution Functions

Two-dimensional Disk DFs

Dehnen, Shu, and Schwarzschild distribution functions for razor-thin disks: moments, asymmetric drift, Oort constants, sampling, and non-axisymmetric evolution.

Two-dimensional Disk Distribution Functions
Three-dimensional Disk DFs

Quasi-isothermal distribution function for 3D disk populations using action-angle variables: moments, velocity ellipsoid tilt, and velocity sampling.

Three-dimensional Disk Distribution Functions
Spherical DFs

Isotropic and anisotropic distribution functions for spherical systems: Hernquist, NFW, King, Plummer, Power-law, and general models.

Spherical Distribution Functions

Tidal Streams

Stream Modeling with streamdf

Model tidal streams in action-angle coordinates: predict stream tracks, compute densities, sample mock data, and evaluate the full phase-space PDF. And model gaps.

Stream Modeling with streamdf
Particle-spray with streamspraydf

Generate tidal streams using particle-spray techniques with chen24spraydf and fardal15spraydf.

Particle-spray Stream Modeling with streamspraydf

Extending galpy

New Potentials in Python

Define custom potential classes and dissipative forces in Python by implementing force and potential evaluation methods, with full support for orbit integration and physical units.

Adding a New Potential in Python
New Potentials in C

Add C implementations of potentials for fast orbit integration and action-angle calculations.

Adding a New Potential in C

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:

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:

Indices and tables