Source-linked AI summary
AGAMA: Action-based galaxy modelling architecture
Eugene Vasiliev
TL;DR
Galaxy modelling requires flexible potentials and distribution functions that support observations, equilibrium N-body initial conditions, and simulation analysis. Agama addresses this with action-based modelling tools, improved potential representations, and iterative self-consistent construction, while remaining limited by integrability assumptions and specific model deficiencies.
Problem
Galaxy modelling needs flexible gravitational potentials and distribution-function methods to describe stellar systems and derive observable properties from them.
Method
Agama combines potential solvers, action/angle transformations, action-based distribution functions, and iterative construction of multicomponent self-consistent models.
Results
Agama provides improved potential representations, a novel Stäckel fudge implementation, action-based distribution functions, and a more flexible framework for iterative self-consistent model construction.
Takeaways & Limitations
The framework supports smooth potential construction from analytic densities or N-body snapshots, action-based galaxy modelling, and equilibrium N-body model creation.
Takeaways & Limitations
The action/angle formalism relies on integrability, which is violated in triaxial systems and complicated by chaotic orbit families even in some axisymmetric systems.
Abstract
from arXiv · showhide
Agama is a publicly available software library for a broad range of applications in the field of stellar dynamics. It provides methods for computing the gravitational potential of arbitrary analytic density profiles or N-body models; orbit integration and analysis; transformations between position/velocity and action/angle variables; distribution functions expressed in terms of actions and their moments; iterative construction of self-consistent multicomponent galaxy models. Applications include the inference about the structure of Milky Way or other galaxies from observations of stellar kinematics; preparation of equilibrium initial conditions for N-body simulations; analysis of snapshots from simulations. The library is written in C++, provides a Python interface, and can be coupled to other stellar-dynamical software: Amuse, Galpy and Nemo.
1 INTRODUCTION
Agama is a modular software framework for constructing customized galaxy models, centered on action-space distribution functions and flexible gravitational potentials. It combines potential solvers, action/angle transformations, distribution functions, self-consistent modelling, and interfaces for practical stellar-dynamics work.
- Agama provides tools for constructing customized dynamical models described by distribution functions in action space.
- The framework includes gravitational potentials from analytical density profiles or N-body models, including versatile potential expansions.
- Agama implements transformations between coordinate/velocity and action/angle variables, including a new Stäckel fudge implementation.
- It supplies action-based distribution functions, routines for computing their moments, and tools for creating N-body representations in a given potential.
- The library supports iterative construction of self-consistent galaxy models and compares its applications with other software projects.
- Written primarily in C++ with a Python interface, Agama includes examples and interfaces to Amuse, Galpy, and Nemo.
2 POTENTIALS
Agama provides general-purpose methods for constructing gravitational potentials from analytic densities or N-body snapshots. Its complementary harmonic expansions trade accuracy, flexibility, and construction cost across galaxy geometries and density components.
- 20 Agama provides standard potential–density pairs and two general-purpose potential solvers for obtaining potentials from arbitrary density profiles.
- Direct Green’s-function evaluation is computationally challenging because each point requires a singular triple integral over an infinite domain.
- Spherical-harmonic expansions restrict angular terms through lmax and mmax; strongly flattened systems may require many terms, such as lmax = 36.
- The azimuthal-harmonic solver can truncate the expansion at a moderate mmax ≲10 and uses two-dimensional integrals for each harmonic.
- Agama pre-computes expansion coefficients on one- or two-dimensional grids and uses interpolating splines for efficient potential and derivative evaluation.
- The two harmonic approaches are complementary: spherical harmonics suit spheroidal components, while azimuthal harmonics better handle discs but require more intensive construction.The azimuthal approach is more accurate for highly flattened densities, whereas spherical harmonics better represent power-law behavior beyond the grid.
- Both expansions can smooth analytic densities or N-body point masses, producing potentials that can be faster to evaluate than direct N-body methods.
3 ACTION/ANGLE VARIABLES
Agama represents stellar systems with action/angle variables and provides efficient methods for converting between phase-space and action/angle coordinates. Its Stäckel-fudge implementation improves focal-distance selection and achieves higher efficiency and accuracy, while interpolation offers major speedups with accuracy and bias trade-offs.
- General properties: Actions are canonical integrals of motion with independently ranged variables, making them convenient for describing distribution functions.Their canonical equations give constant actions and frequencies, while the phase-space transformation has unit determinant.
- Action/angle transformations: Agama provides several methods for converting between position/velocity and action/angle variables, including a new axisymmetric Stäckel-fudge implementation.The framework also includes the TorusMapper package for the reverse transformation from action/angles to position/velocity.
- Stäckel fudge: Agama’s Stäckel fudge estimates actions in arbitrary axisymmetric potentials by assuming locally separable motion in prolate spheroidal coordinates.The approximation depends on the focal distance ∆, which may vary across phase space.
- Stäckel fudge: Equation 9’s focal-distance choice is more accurate than the two methods used in Sanders & Binney (2016), while requiring 1.5−2× fewer potential evaluations.The accuracy improvement comes from assigning ∆ more judiciously across phase space, rather than from different numerical procedures.
- Interpolation: Interpolated actions provide a 10× computational-efficiency increase but introduce small, non-negligible systematic biases that can vary across action space.These biases make interpolated actions unsuitable for unbiased potential comparisons, although moderate accuracy loss may be acceptable in other applications.
- Summary: Agama’s axisymmetric Stäckel fudge is both more efficient and accurate than existing implementations, while its interpolated version trades accuracy for substantial speedup.The reported gains combine the new focal-distance method with algorithmic improvements.
4 DISTRIBUTION FUNCTIONS
Agama represents stellar populations with distribution functions of actions, providing models, moments, sampling, fitting, and self-consistent construction tools. It includes quasi-isothermal and exponential disc DFs alongside spheroidal models, with explicit trade-offs between potential-dependent flexibility and simpler action-only parameterization.
- DF framework: Agama uses action-based distribution functions to describe steady-state stellar systems and normalize their phase-space integral to mass.The framework also supports extended population arguments and superpositions of single-component DFs.
- DF framework: Its DF tools cover spheroidal and disky components, moment computation, particle sampling, and best-fit inference from discrete samples.These capabilities support density, velocity-dispersion, marginalized velocity-distribution, and likelihood-based analyses.
- Quasi-isothermal discs: The quasi-isothermal disc DF is potential-dependent and can deviate from its target density and dispersions for warm discs, especially when max(Jr, Jz) ≳ Jφ.The implementation relies on recomputing the potential for self-consistency rather than applying further profile adjustments.
- Exponential discs: The exponential disc DF is specified entirely by scale actions, uses extra small-radius parameters, and has a relatively simple functional form with interpretable parameters.Jφ,0 sets scale radius, Jz,0 sets scale height and vertical dispersion, Jr,0 sets radial dispersion, and Jd,0 and Jv,0 modify central behavior.
- Disc-model comparison: Both disc DF families produce similar and realistic density profiles and velocity distributions in a typical Milky Way potential.The exponential model is an alternative when avoiding reference to a potential is more convenient, whereas the quasi-isothermal model uses length- and velocity-based parameters.
5 SELF-CONSISTENT MODELS
Agama constructs self-consistent multicomponent galaxy models by iteratively coupling action-based distribution functions, component densities, and the total gravitational potential. The method recomputes densities and potentials without simplifying approximations, supports arbitrary component combinations within axisymmetry, and produces models comparable to established approaches.
- Iterative formulation: The model solves a circular dependency in which actions depend on the potential, densities are integrals of distribution functions, and the potential follows from total density through Poisson’s equation.An iterative procedure begins from a suitable initial potential guess and repeats the updates until convergence.
- Iterative formulation: Agama recomputes each component’s density from its distribution function on every iteration rather than assuming an approximate distribution function generates the desired density.This explicitly updates the density profiles during self-consistent construction.
- Iterative formulation: The total potential is recalculated from all component densities without simplifying approximations such as separable exponential-disc profiles.The approach accommodates multiple components, including discs, bulges, haloes, and optional external potentials.
- The present method: Actions facilitate models with arbitrary combinations of components and accelerate convergence of the iterative construction.The framework is presently restricted to axisymmetric systems because of the available action finders.
- The present method: For prescribed density profiles, quasi-isotropic spheroidal and quasi-isothermal disky distribution functions typically produce resulting profiles within ≲10% of the inputs.These distribution functions must be constructed from the desired density profiles in the corresponding total potential.
- Example: In the disc–bulge–halo comparison, Agama, GalactICs, and mkgalaxy all reproduced the intended rotation curve with minor deviations, while their evolved dispersion profiles changed mainly through moderate outer-disc spiral instability.The comparison used initial and evolved velocity-dispersion profiles and found the three models broadly comparable.
- Example: Agama’s self-consistent distribution-function method produced models at least as good as commonly used alternatives while allowing greater flexibility in parameters and component number and type.The example required about one minute of wall-clock time on a 16-core workstation.
6 DISCUSSION
Agama is a publicly available stellar-dynamics framework that combines general-purpose potential solvers, action/angle transformations, action-based distribution functions, and iterative self-consistent modelling. Its improvements target flexible modelling of analytic and N-body systems, while its action-based approach remains bounded by integrability and axisymmetric action-computation assumptions.
- Framework scope: Agama provides general-purpose methods for smooth potentials, action/angle conversion, distribution functions and moments, and iterative multicomponent self-consistent models.The library accepts arbitrary density distributions or N-body snapshots for potential construction.
- Potential solvers: Spherical- and azimuthal-harmonic potential expansions represent flexible analytic density profiles and smooth N-body potentials, including strongly non-axisymmetric disky systems.The N-body expansion preserves global features while discarding small-scale noise, supporting orbit analysis in frozen potentials.
- Action computation: Agama’s Stäckel-fudge implementation computes approximate actions and angles in arbitrary axisymmetric potentials more accurately and efficiently than existing codes.The implementation improves focal-distance selection to increase practical accuracy and efficiency.
- Distribution functions: The framework includes action-based DFs, a new action-only disc DF, optimized moment and marginalized-velocity calculations, and general multidimensional sampling tools.These tools support both constructing N-body realizations and analysing distribution-function models.
- Self-consistent models: Its iterative self-consistent modelling framework extends previous DF-based approaches by improving performance and flexibility while avoiding an ad hoc separable disc-density approximation.DF-based models also provide smooth phase-space representations useful for equilibrium N-body construction and likelihood-based comparisons with data.
- Scope and limitations: Agama complements or supersedes existing galaxy-modelling libraries, but its action formalism assumes integrability and its present action computation is restricted to axisymmetric systems.These limitations matter for triaxial or chaotic systems, although the authors state that the restrictions may be lifted in future.