Theory & methods

This section is the scientific heart of progenax: every model the package implements, derived from first principles, anchored on its canonical references, and accompanied by the implementation choices that made the model practical to differentiate through.

Every chapter follows the same template:

1. Physical motivation — what observational phenomenon the model captures and why it matters.

2. Mathematical formulation — closed-form derivations, ODEs, or sampling procedures, written so a non-specialist astronomer can follow the argument without needing to fall back on the source paper.

3. Implementation in progenax — the class signature, the JAX patterns used to keep it differentiable, and any historical bugs that future readers should know about.

4. Domain of validity and caveats — where the model fails, numerical-safety clips, and which alternative model to reach for when this one breaks.

5. References — {cite}-rendered links to the canonical paper(s), at least one pedagogical review, and any progenax-internal note the chapter draws on.

Suggested reading order¶

The map below is the index; this is the path. If you are learning the science from scratch, read the chapters in this order — each step builds on the conventions and models of the ones before it:

1. What is an initial condition? — start here. Defines what an “initial condition” is in progenax (the three orthogonal ingredients — density, velocity DF, masses), the virial-$Q$ convention, units, and the COM frame. Everything downstream assumes these conventions.

2. Spatial profiles, in increasing generality: Plummer profile (the closed-form baseline) → King profile (tidal truncation via an ODE) → EFF profile (a free outer slope) → The differentiable lowered-model family (Engine A) (the unified Woolley/King/Wilson family) → Multimass equipartition saturation — the derived m_eq (multi-mass equilibrium). Plummer first because it is the analytic anchor the others are calibrated against; the family and multimass pages last because they generalize King.

3. Velocity distribution functions — how each density is given velocities. A profile only becomes an equilibrium IC once paired with a matching velocity DF, so read this directly after the profiles it completes.

4. Initial mass functions — how stars get masses. The third IC ingredient, independent of the spatial/velocity structure; from canonical IMFs to binary-aware and environment-dependent variants.

5. Binary populations — multiplicity. Builds on the IMF: orbital elements, period/eccentricity distributions, and resolving binaries into component kinematics.

6. Tidal physics & substructure — modifiers and diagnostics. Tidal truncation, fractal/substructured ICs, and mass-segregation layers that act on top of a base profile, plus the diagnostics that measure them.

7. Multi-component populations — composite clusters. The capstone: multi-component populations sharing one self-consistent potential, which assembles everything above into a single equilibrium model.

For developers extending the package, pair each theory chapter with the architecture section — see Reading paths below.

Map of the section¶

What this section is not¶

Theory chapters describe what the package computes and why it is correct. They deliberately do not describe how to use the API — that lives in API reference. They also do not describe what the package chose not to do; that level of architectural rationale lives in Architecture & design. When a chapter needs to point at an implementation detail, it cross-links to the API page rather than duplicating signatures.

The boundary between theory and architecture is sometimes fuzzy. As a working rule: if the chapter content is invariant under a JAX-to- PyTorch port, it belongs in theory. If it depends on JAX-specific patterns (lax.scan, stop_gradient, smart dispatch), it belongs in architecture.

Reading paths¶

For students: read What is an initial condition? first, then any one chapter family that matches what you want to learn. Each family is self-contained.

For developers extending progenax: read the architecture section (Architecture & design) alongside the relevant theory chapter — theory tells you what physics to preserve, architecture tells you the patterns that preserve it under JAX.

For paper-writing: every theory chapter ends with a References block containing {cite} keys you can copy directly into your manuscript. The full bibliography (with DOIs / arXiv links) lives at Bibliography.