DF (galpy.df)

galpy.df contains tools for dealing with distribution functions of stars in galaxies. It mainly contains a number of classes that define different types of distribution function, but galpy.df.jeans also has some tools for solving the Jeans equations for equilibrium systems.

Jeans modeling tools (galpy.df.jeans)

General instance routines for all df classes

Spherical distribution functions

Isotropic and anisotropic distribution functions for spherical systems. Documentation of these is limited at this point, but generally, one can use them as:

from galpy import potential
from galpy.df import isotropicNFWdf
np= potential.NFWPotential(amp=1.2,a=2.3)
ndf= isotropicNFWdf(pot=np)
# sample
sam= ndf.sample(n=int(1e6))
print(numpy.std(sam[numpy.fabs(sam.r()-1.2) < 0.1].vr()))
# 0.2156787374302913
# Compute vel. dispersion
print(ndf.sigmar(1.2))
# 0.21985277878647172

or:

from galpy.df import kingdf
kdf= kingdf(M=2.3,rt=1.4,W0=3.)
sam= kdf.sample(n=int(1e6))
print(numpy.amax(sam.r()))
# 1.3883460662897116
print(numpy.std(sam[numpy.fabs(sam.r()-0.2) < 0.01].vr()))
# 1.081298923132113
print(kdf.sigmar(0.2))
# 1.0939934290993467

Various spherical DFs are explicitly implemented (e.g., Hernquist, NFW using a new approximation, King, Plummer, power-law) in isotropic and various anisotropic forms. General methods for computing isotropic, constant-beta anisotropic, and Osipkov-Merritt anisotropic for any potential/density pair are also included. Use of interpolated spherical potentials (galpy.potential.interpSphericalPotential) is also supported with DFs, however numerical issues can arise during sampling or calculation of moments of the DF, and so caution is recommended when using these potentials. It is advisable to use a very finely spaced radial grid, and ensure that it spans a range of radii much larger than the radii of interest for the DF.

General instance routines

Sampling routines

Specific distribution functions

The following are isotropic distribution functions

Anisotropic versions also exist:

Two-dimensional, axisymmetric disk distribution functions

Distribution function for orbits in the plane of a galactic disk.

General instance routines

Sampling routines

Specific distribution functions

Two-dimensional, non-axisymmetric disk distribution functions

Distribution function for orbits in the plane of a galactic disk in non-axisymmetric potentials. These are calculated using the technique of Dehnen 2000, where the DF at the current time is obtained as the evolution of an initially-axisymmetric DF at time to in the non-axisymmetric potential until the current time.

General instance routines

Three-dimensional disk distribution functions

Distribution functions for orbits in galactic disks, including the vertical motion for stars reaching large heights above the plane. Currently only the quasi-isothermal DF.

General instance routines

Specific distribution functions

The distribution function of a tidal stream in action-angle coordinates

From Bovy 2014; see stream-tutorial.

General instance routines

The distribution function of a gap in a tidal stream

From Sanders, Bovy, & Erkal 2015; see streamgap-tutorial. Implemented as a subclass of streamdf. No full implementation is available currently, but the model can be set up and sampled as in the above paper.

General instance routines

Helper routines to compute kicks

The distribution function of a tidal stream using a particle-spray technique

Model from Chen et al. (2024) and Fardal et al. (2015) with full details of the galpy implementation given in Qian et al. (2022); see streamspray-tutorial.

General instance routines

Specific particle-spray models

Stripping-time distributions

Helpers that build the stripping_pdf= callable accepted by every streamspraydf subclass, for non-uniform tidal-stripping rates over the disruption window [-tdisrupt, 0].

Smooth stream-track object

A StreamTrack is a smooth, dense interpolation of the mean position-and-velocity of a tidal stream as a function of a curve parameter tp (proxy for stripping time / arc length along the stream). It exposes accessors for every standard galpy coordinate (x, y, z, R, ra, dec, ll, bb, proper motions, line-of-sight velocity, …), a covariance cov of the underlying particle distribution in any of those bases, and a plot helper. A StreamTrackPair bundles the leading and trailing tracks built together (tail='both') into a single object that mirrors the per-arm API and broadcasts shared operations to both arms.

The recommended way to build a track is streamspraydf.streamTrack, which samples the spray DF and fits the smooth track in one step. For users that already have stream particles (e.g. from a simulation or an external sampler), StreamTrack.from_particles exposes the particle-fitting machinery directly. There is no separate StreamTrackPair.from_particles classmethod: building a pair from particles means calling StreamTrack.from_particles() once per arm and then constructing a StreamTrackPair from the two — or, equivalently, calling streamspraydf.streamTrack(particles=..., tail='both') so the spray-DF wrapper handles the per-arm split.

StreamTrack

The particles attribute ((xv, dt) of the particles the track was fit to) is available on tracks built via from_particles(); see the class docstring above.

Methods:

The phi1/phi2/pmphi1/pmphi2 accessors require custom_sky_transform to have been set (either at construction or by assigning to the custom_sky_transform property).

StreamTrackPair

Attribute:

  • StreamTrackPair.particles[source]

    Concatenated xv array from both arms in the leading-first order that streamspraydf.streamTrack(tail='both', particles=...) expects, so a pair built with tail='both' can be re-fit at different smoothing / iteration settings without re-sampling:

    pair = spdf.streamTrack(n=3000, tail='both')
pair_smoother = spdf.streamTrack(particles=pair.particles,
                                 tail='both',
                                 smoothing_factor=2.0)

    Available only when the underlying arms were built via StreamTrack.from_particles() (the streamspraydf.streamTrack path); raises AttributeError otherwise.

Methods: