Anisotropic spherical models, truncated in phase space
PIANISTpy builds spherical, non-rotating, velocity-anisotropic equilibrium models, self-consistently truncated in phase space, for dark matter (sub)halos, dwarf galaxies, stellar spheroids and star clusters. The package provides distribution functions, particle initial conditions, radial and tangential velocity dispersion profiles and line-of-sight observables, with JAX-based end-to-end differentiability for gradient-based Monte Carlo inference.
Install
pip install pianistpy. Python 3.11 or later. PIANISTpy runs on the CPU on Linux, macOS and Windows, and on a CUDA GPU under Linux.
Quick start
A few lines of code go from an input density profile and an anisotropy model to the distribution function, a model truncated in phase space, particle initial conditions and velocity observables.
Run the example →Examples
Jupyter notebooks for generating particle initial conditions and for computing observables from a model.
Examples →Accuracy
For each model of a fixed grid, the relative error of the density computed back from the distribution function, and the tier that the result reports, or the exception that the package raises for a model that the package does not build.
Accuracy tables →What PIANISTpy does
- Density profiles. Analytical double-power-law density profiles with a finite central potential, including the Navarro-Frenk-White, Hernquist and Plummer profiles.
- Velocity anisotropy. Isotropic, constant-anisotropy, Osipkov-Merritt and Cuddeford-Osipkov-Merritt (COM) models. The Osipkov-Merritt and COM models are radially (Type I) or tangentially (Type II) biased.
- Distribution functions. Each anisotropy model’s distribution function, inverted from the input density with exact symbolic expressions up to the final numerical integration, with extensively validated numerical accuracy (Accuracy tables) and checks that the distribution function is non-negative (physical) and monotonic (a sufficient condition for dynamical stability).
- Truncation in phase space. Model truncation performed in phase space. The truncation boundary is self-consistent and in dynamical equilibrium. Method I preserves the model’s anisotropy profile, and Method II gives different anisotropy models an identical truncated density.
- Particles. Particle initial conditions drawn from the truncated distribution function, with a finite, dynamically stable truncation boundary. The particles are given in internal, model or physical units.
- Observables. Radial, tangential and line-of-sight velocity dispersions, line-of-sight velocity distributions and their Gauss-Hermite moments, and the local velocity distribution at a 3D radius. Projected quantities are averaged over centered or offset circular and rectangular apertures.
- Superposition. Distribution functions of different anisotropy models on one truncated density, linearly superposed into one equilibrium model. The superposed model’s anisotropy profile can differ from every analytical family, for example an anisotropy profile fitted to simulated halos.
- Inference. End-to-end differentiable in JAX: the likelihood of a model against kinematic data, with gradients in the superposition weights, the mass and length scales (M0 and r0) and, for Method II components, the anisotropy parameters, for gradient-based Monte Carlo inference.
Release notes (ver. 1.0.0)
Ver. 1.0.0 is the initial public release of PIANISTpy, described in Chiang, van den Bosch and Schive (2026d), MNRAS submitted, arXiv:2610.28758, henceforth Chiang+(2026d). Ver. 1.0.0 provides the distribution functions and their truncation, particle sampling with draws restricted to a user-specified range of radii or velocities, the observables (sigma_r, sigma_t, sigma_los, losvd, aperture_losvd, pdf_v), a report of the numerical accuracy with every result, and gradients in the superposition weights, the mass and length scales and, for Method II components, the anisotropy parameters. Ver. 1.0.0 runs on the CPU and, with a CUDA build of JAX under Linux, on the GPU. The dependencies, standard and minimum, are listed on the Install page.
Citation
PIANISTpy is described in Chiang+(2026d).