galpy Documentation Release v1.8.0.dev0 Jo Bovy Sep 08, 2021 Contents 1 Quick-start guide 3 1.1 Installation................................................3 1.2 What’s new?............................................... 10 1.3 Introduction............................................... 16 1.4 Potentials in galpy............................................ 30 1.5 A closer look at orbit integration..................................... 58 1.6 Two-dimensional disk distribution functions.............................. 88 1.7 Action-angle coordinates......................................... 111 1.8 Three-dimensional disk distribution functions.............................. 144 1.9 Dynamical modeling of tidal streams.................................. 153 2 Library reference 171 2.1 Orbit (galpy.orbit)......................................... 171 2.2 Potential (galpy.potential).................................... 213 2.3 actionAngle (galpy.actionAngle)................................. 333 2.4 DF (galpy.df)............................................. 345 2.5 Utilities (galpy.util)......................................... 417 3 Acknowledging galpy 455 4 Papers using galpy 457 5 Indices and tables 459 Index 461 i ii galpy Documentation, Release v1.8.0.dev0 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: Contents 1 galpy Documentation, Release v1.8.0.dev0 2 Contents CHAPTER 1 Quick-start guide 1.1 Installation 1.1.1 Dependencies galpy requires the numpy, scipy, and matplotlib packages; these must be installed or the code will not be able to be imported. Optional dependencies are: • astropy for Quantity support (used throughout galpy when installed), • astroquery for the Orbit.from_name initialization method (to initialize using a celestial object’s name), • numexpr for plotting arbitrary expressions of Orbit quantities, • JAX for use of constant-anisotropy DFs in galpy.df.constantbetadf, and • pynbody for use of SnapshotRZPotential and InterpSnapshotRZPotential. To be able to use the fast C extensions for orbit integration and action-angle calculations, the GNU Scientific Library (GSL) needs to be installed (see below). 1.1.2 With conda The easiest way to install the latest released version of galpy is using conda or pip (see below): conda install galpy-c conda-forge or: conda config--add channels conda-forge conda install galpy 3 galpy Documentation, Release v1.8.0.dev0 Installing with conda will automatically install the required dependencies (numpy, scipy, and matplotlib) and the GSL, but not the optional dependencies. 1.1.3 With pip galpy can also be installed using pip. Since v1.6.0, the pip installation will install binary wheels for most major operating systems (Mac, Windows, and Linux) and commonly-used Python 3 versions. When this is the case, you do not need to separately install the GSL. When you are on a platform or Python version for which no binary wheel is available, pip will compile the source code on your machine. Some advanced features require the GNU Scientific Library (GSL; see below). If you want to use these with a pip-from-source install, install the GSL first (or install it later and re-install using the upgrade command. Then do: pip install galpy or to upgrade without upgrading the dependencies: pip install-U--no-deps galpy Installing with pip will automatically install the required dependencies (numpy, scipy, and matplotlib), but not the optional dependencies. On a Mac/UNIX system, you can make sure to include the necessary GSL environment variables by doing (see below): export CFLAGS="$CFLAGS -I`gsl-config --prefix`/include"&& export LDFLAGS="$LDFLAGS - ,!L`gsl-config --prefix`/lib"&& pip install galpy 1.1.4 Latest version The latest updates in galpy can be installed using: pip install-U--no-deps git+git://github.com/jobovy/galpy.git #egg=galpy or: pip install-U--no-deps--install-option="--prefix=~/local" git+git://github.com/ ,!jobovy/galpy.git#egg=galpy for a local installation. The latest updates can also be installed from the source code downloaded from github using the standard python setup.py installation: python setup.py install or: python setup.py install--prefix=~/local for a local installation. Note that these latest-version commands all install directly fromm the source code and thus require you to have the GSL and a C compiler installed to build the C extension(s). If you are having issues with this, you can also download a binary wheel for the latest master version, which are available here for Mac/Windows wheels and here for Linux wheels (note that you need to be logged into GitHub to access the artifacts, which otherwise just show up as a gray non-link). To install these wheels, click on the latest run, download the “artifact” for the platform/Python version that you are using, unzip the file, and install the wheel with: 4 Chapter 1. Quick-start guide galpy Documentation, Release v1.8.0.dev0 pip install WHEEL_FILE.whl 1.1.5 Installing from a branch If you want to use a feature that is currently only available in a branch, do: pip install-U--no-deps git+git://github.com/jobovy/galpy.git @dev#egg=galpy to, for example, install the dev branch. Note that we currently do not build binary wheels for branches other than master. If you really wanted this, you could fork galpy, edit the GitHub Actions workflow file that generates the wheel to include the branch that you want to build (in the on: section), and push to GitHub; then the binary wheel will be built as part of your fork. 1.1.6 Installing from source on Windows Tip: You can install a pre-compiled Windows “wheel” of the latest master version that is automatically built on AppVeyor for all recent Python versions. Navigate to the latest master build, click on the first job and then on “Artifacts”, download the wheel for your version of Python, and install with pip install WHEEL_FILE.whl. Similar wheels are also available here (see above), but require you to be logged into GitHub. Versions >1.3 should be able to be compiled on Windows systems using the Microsoft Visual Studio C compiler (>= 2015). For this you need to first install the GNU Scientific Library (GSL), for example using Anaconda (see below). Similar to on a UNIX system, you need to set paths to the header and library files where the GSL is located. On Windows, using the CDM commandline, this is done as: set INCLUDE=%CONDA_PREFIX%\Library\include;%INCLUDE% set LIB=%CONDA_PREFIX%\Library\lib;%LIB% set LIBPATH=%CONDA_PREFIX%\Library\lib;%LIBPATH% If you are using the Windows PowerShell (which newer versions of the Anaconda prompt might set as the default), do: $env:INCLUDE="$env:CONDA_PREFIX\Library\include" $env:LIB="$env:CONDA_PREFIX\Library\lib" $env:LIBPATH="$env:CONDA_PREFIX\Library\lib" where in this example CONDA_PREFIX is the path of your current conda environment (the path that ends in \ENV_NAME). If you have installed the GSL somewhere else, adjust these paths (but do not use YOUR_PATH\include\gsl or YOUR_PATH\lib\gsl as the paths, simply use YOUR_PATH\include and YOUR_PATH\lib). To compile with OpenMP on Windows, you have to install Intel OpenMP via: conda install-c anaconda intel-openmp and then to compile the code: python setup.py install If you encounter any issue related to OpenMP during compilation, you can do: 1.1. Installation 5 galpy Documentation, Release v1.8.0.dev0 python setup.py install--no-openmp 1.1.7 Installing from source with Intel Compiler Compiling galpy with an Intel Compiler can give significant performance improvements on 64-bit Intel CPUs. More- over students can obtain a free copy of an Intel Compiler at this link. To compile the galpy C extensions with the Intel Compiler on 64bit MacOS/Linux do: python setup.py build_ext--inplace--compiler=intelem and to compile the galpy C extensions with the Intel Compiler on 64bit Windows do: python setup.py build_ext--inplace--compiler=intel64w Then you can simply install with: python setup.py install or other similar installation commands, or you can build your own wheels with: python setup.py sdist bdist_wheel 1.1.8 Installing the TorusMapper code Warning: The TorusMapper code is not part of any of galpy’s binary distributions (installed using conda or pip); if you want to gain access to the TorusMapper, you need to install from source as explained in this section and above. Since v1.2, galpy contains a basic interface to the TorusMapper code of Binney & McMillan (2016). This interface uses a stripped-down version of the TorusMapper code, that is not bundled with the galpy code, but kept in a fork of the original TorusMapper code. Installation of the TorusMapper interface is therefore only possible when installing from source after downloading or cloning the galpy code and using the python setup.py install method above. To install the TorusMapper code, before running the installation of galpy, navigate to the top-level galpy directory (which contains the setup.py file) and do: git clone https://github.com/jobovy/Torus.git galpy/actionAngle/actionAngleTorus_c_ ,!ext/torus cd galpy/actionAngle/actionAngleTorus_c_ext/torus git checkout galpy cd- Then proceed to install galpy using the python setup.py install technique or its variants as usual. 1.1.9 Installation FAQ What is the required numpy version? galpy should mostly work for any relatively recent version of numpy, but some advanced features, including cal- culating the normalization of certain distribution functions using Gauss-Legendre integration require numpy version 6 Chapter 1.