What is an initial condition?

An initial condition (IC) for an N-body simulation is a complete specification of the phase-space coordinates of every particle at $t = 0$: positions $\{\mathbf{r}_i\}$, velocities $\{\mathbf{v}_i\}$, and masses $\{m_i\}$ for $i = 1, \ldots, N_\star$. progenax produces ICs that are simultaneously physically realistic, exactly reproducible (given a JAX PRNG key), and differentiable with respect to every continuous control parameter — the radial scale, the IMF slope, the virial ratio, the substructure strength, and so on.

This chapter establishes the conventions and core concepts that every subsequent theory chapter assumes. Read it first if you are new to the package.

Three things every progenax IC fixes¶

A progenax IC is built up from three orthogonal ingredients:

Each ingredient satisfies a runtime-checkable protocol — IMFProtocol, SpatialProfile, VelocityDF — that defines its mathematical contract. Any IMF can pair with any spatial profile, which can pair with any velocity DF, so long as physical compatibility is maintained (e.g. a King profile pairs with a King DF for equilibrium; mixing a Plummer profile with a King DF produces an out-of-equilibrium starting state, which can be useful for studying violent relaxation but is not “the King cluster” in the equilibrium sense).

The composability is documented in Protocol-based composition; the equilibrium-vs-mismatch question is documented per-velocity-DF in Velocity distribution functions.

The virial theorem and $Q_{\mathrm{vir}} = 0.5$¶

A bound, gravitationally self-interacting N-body system in steady state satisfies the virial theorem:

where $T = \tfrac{1}{2}\sum_i m_i |\mathbf{v}_i|^2$ is the total kinetic energy and $V = -G\sum_{i<j} m_i m_j / |\mathbf{r}_i - \mathbf{r}_j|$ is the total gravitational potential energy. Solving for the ratio $Q_{\mathrm{vir}} \equiv T/|V|$ gives $Q_{\mathrm{vir}} = 0.5$ at equilibrium.

This $Q_{\mathrm{vir}} = T/|V|$ convention is what every progenax builder, kinematics function, and validation test uses. Three of the non-equilibrium states that show up in the literature have direct physical meaning:

The progenax convention, the algorithm that enforces it, and the alternative $\alpha_{\mathrm{vir}} = 2T/|U|$ form are documented at length in Virial Q convention (Q = T/|V|).

The half-mass radius $r_h$¶

The natural length scale for a gravitating system is its half-mass radius:

i.e. half the mass lies inside $r_h$. progenax parameterises every spatial profile by $r_h$ rather than by the scale-radius parameter internal to that profile (which differs between Plummer, King, EFF). This makes ICs comparable across profile choices: a Plummer cluster with $r_h = 1$ pc and a King cluster with $r_h = 1$ pc occupy the same physical extent, even though their internal scale radii differ.

The Plummer scale-radius–to–half-mass-radius relation is

The factor $\sqrt{2^{2/3} - 1}$ recurs in every Plummer-related derivation; misinverting it produces a 1.7× error in cluster size, and this exact bug existed in an earlier version of progenax. It is now locked by tests/validation/test_plummer_physics.py::test_half_mass_radius. See Plummer profile for the derivation.

For King and EFF profiles, the $r_h$↔scale-radius mapping has no closed form and is computed via numerical integration of the cumulative mass profile.

The centre-of-mass frame¶

Every progenax IC is returned in the centre-of-mass (COM) frame:

The transform that achieves this — progenax.builders.to_com_frame — is just a mass-weighted shift of positions and velocities. It is applied as the last step of every builder; ICs leave the package with zero net momentum and zero net displacement.

Units policy: explicit, no globals¶

progenax adopts a strict explicit-units convention: no global state, no implicit unit defaults, no get_G()-style context managers in core APIs. Every function that consumes a gravitational constant takes either an explicit G value or an explicit units argument carrying one.

Three unit systems appear most often:

Convenience wrappers may accept units=None and resolve to the package-level DEFAULT_UNITS = STELLAR, but this resolution happens only at the API surface; once inside the call stack, $G$ is an explicit parameter. The architectural rationale and the dropped context-manager idiom are documented in Units policy.

What “differentiable IC” actually means¶

A progenax IC is a function

mapping continuous control parameters $\boldsymbol{\theta} = (r_h,\, \alpha_{\mathrm{IMF}},\,Q_{\mathrm{vir}},\,\lambda_{\mathrm{seg}},\ldots)$ and a JAX PRNG key to a phase-space realisation. Differentiable means

is well-defined and computable via jax.grad, for any observable $\mathcal{O}$ — energy, kinetic-energy ratio, half-mass radius, two-point correlation function, the post-evolution snapshot a few crossing times later, the mock observation through an instrument forward model. Every step that turns $\boldsymbol{\theta}$ into a particle realisation must satisfy three constraints:

1. No jax.lax.while_loop. Convergence-based loops have variable step counts that are not differentiable. Use jax.lax.scan with a fixed iteration count instead. Inverse-CDF samplers in progenax solve the cumulative integrals to a fixed accuracy in a fixed number of Newton or bisection steps.

2. No mutation, no array[i] = val. Every state update creates a new immutable array. progenax uses Equinox modules for stateful classes, so all state lives in PyTree leaves.

3. No discrete-without-smoothing. Sorts, argmin, hard thresholds, and where selections all produce gradient discontinuities. Where they are unavoidable (rank-based radial remapping in Fractal substructure), gradients flow through the values being sorted rather than the permutation. Where smoothing is possible (the Fundamental Plane threshold in Environment-dependent IMFs), progenax substitutes a sigmoid for the hard where.

The architectural rules are documented at length in JAX-native philosophy and Differentiability rules. Every theory chapter in this section flags the steps where differentiability needed special care.

Reading order¶

This page is step 1 of the section’s canonical path — the full seven-step ramp (profiles → velocity DFs → IMFs → binaries → modifiers → composite populations) lives in one place: the theory index’s suggested reading order. (An earlier revision kept a second, divergent ordering here that routed first-pass readers into experimental and since-removed material; there is now ONE ramp, and this is its trailhead.)

Implementation, validation & references¶

• In code: the conventions on this page are enforced in src/progenax/builders.py (build_spatial_ic, to_com_frame, virial_scale) and src/progenax/dynamics/virial.py (the $Q_{\mathrm{vir}} = T/|V|$ energy utilities); units come from jaxstro.units. See the builders API and the dynamics API.

• Validated in: end-to-end equilibrium & energy checks exercise the COM-frame, virial, and units conventions through the full IC pipeline; each ingredient’s own validation page (Plummer, King, EFF, IMF) is linked from the chapters below.

• Primary sources: the virial theorem and Eddington/lowered-model machinery are standard textbook material; the non-equilibrium states cited here are Allison et al. (2009) (subvirial cool-fractal) and Goodwin & Whitworth (2004) (supervirial post-gas-expulsion), and the substructure-$Q$ caution is Cartwright & Whitworth (2004) — full notes in the bibliography.