API reference - progenax — differentiable initial conditions for N-body simulations

This section is auto-generated from progenax source. The pages in this section are produced by scripts/build_api_reference.py, which walks progenax.__all__ for each public submodule, extracts signatures and docstrings via inspect, and emits one MyST page per module plus an alphabetical full-symbol index.

Browse by module¶

Module	Scope
`progenax.profiles`	Spatial density profiles: `PlummerProfile`, `KingProfile`, `EFFProfile`
`progenax.kinematics`	Velocity DFs and Eddington-inverted samplers
`progenax.imf`	Initial mass functions: power-law, Maschberger, Chabrier, binary-aware, environment-dependent
`progenax.binaries`	Kepler elements, period and eccentricity distributions, joint binary populations
`progenax.analytical`	Analytical IC test cases: two-body Kepler, three-body figure-eight, harmonic oscillator
`progenax.builders`	IC pipeline utilities: `virial_scale`, `to_com_frame`, energy diagnostics
`progenax.tidal`	Jacobi-radius computation and tidal truncation
`progenax.cluster`	Multi-component equilibrium clusters: `MultiComponentCluster` (Engines A and B), primordial `energy_sorted_segregation`, turbulence physics
`progenax.diagnostics`	Cluster diagnostics: Λ_MSR, CW04 Q parameter, differentiable segregation observables
`progenax.dynamics`	Virial and energy utilities: kinetic/potential energy, per-group virial ratios
`progenax.protocols`	Runtime-checkable protocols: `SpatialProfile`, `VelocityDF`, `IMFProtocol`

Browse alphabetically¶

The full symbol index lists every public symbol across all submodules, sorted alphabetically, with classification (class / function / protocol / value) and link to the per-module page. This counts every symbol in each submodule’s __all__; the top-level progenax package re-exports a curated subset for convenience (e.g. from progenax import PlummerProfile), so len(progenax.__all__) is smaller. Use the index when you know the symbol name but don’t remember which module it lives in.

How the API reference is built¶

The scripts/build_api_reference.py script:

Imports each module in PUBLIC_MODULES and walks __all__.
For each public symbol, extracts:
- Class / function / protocol classification
- Signature via inspect.signature
- Cleaned docstring via inspect.getdoc
- Source-file link via inspect.getsourcefile
Emits one MyST page per module, with anchored sections per symbol.
Builds the alphabetical full-symbol index from the same data.

The script uses only Python stdlib (no Griffe / pdoc / sphinx-autoapi dependency) and runs in $\\sim 5$ seconds. To regenerate after public-API changes:

cd docs/website
python scripts/build_api_reference.py

The script is idempotent: re-running with no source changes produces no diff. CI verifies this by running the script on every PR and checking for unstaged changes.

What the API reference does not contain¶

Tutorials — see Getting started.
Theory derivations — see Theory & methods.
How-to recipes — see How-to recipes.
Validation criteria — see Validation.

The API reference is deliberately minimal: signature + docstring + source link. For richer pedagogical context on any symbol, follow the cross-link in its docstring to the relevant theory or how-to chapter.

Stable-vs-unstable API¶

Status	Convention	Example
Stable (default)	In `progenax.__all__`; covered by tests	`PlummerProfile`, `MultiComponentCluster`
Experimental	Repo-only packages under `src/experimental/`; not in the released wheel	`gravoturb` (turbulent/fractal ICs + inference)
Internal	Underscore-prefixed; not in `__all__`	`_grid_density_components`

Only stable-API symbols appear in this reference. Experimental and internal symbols are documented in their own modules’ docstrings but do not show up here.

Reporting issues¶

If you find an API reference page that is wrong (missing symbol, wrong signature, stale docstring), the cause is almost always a docstring problem in the source rather than a script problem. Open an issue against the relevant progenax/<module>/<file>.py rather than against the docs site. Then re-run the build script to update the reference page.