Architecture & design

This section documents why progenax is shaped the way it is. Where the theory section covers what the package computes, this section covers what the package is as software: the JAX-native patterns, the protocol-based composition, the units policy, the conventions every contributor needs to know, and the historical decisions that shaped the current API.

Map of the section¶

What this section is not¶

These chapters describe implementation choices — the patterns that let progenax be JAX-native, differentiable, and composable. They do not describe the underlying physics (that is the theory section) or the per-symbol API (that is the API reference reference). A chapter belongs in this section if its content is invariant under swapping the implemented physics: “use jax.lax.scan not while-loops” is true for any progenax module, while “the King profile satisfies $2T + V = 0$ at equilibrium” is specific to King.

Reading paths¶

For new contributors: read JAX-native philosophy → Differentiability rules → Protocol-based composition → Contributor guide in that order. The first two establish the constraints; the third shows the composition pattern; the fourth walks through adding new modules.

For users coming from McLuster or NBODY6: read Units policy and Virial Q convention (Q = T/|V|) first — these are the convention-mismatches most likely to bite.

For paper-writers wanting to cite progenax’s design choices: Three-brick state pattern and IC redesign history are the chapters most worth referencing.

How architecture and theory interact¶

Some progenax decisions sit on the boundary between architecture and physics. The convention is:

• Pure architecture — patterns invariant under physics swap. e.g. “use Equinox modules for state” applies whether you are sampling Plummer, King, or EFF. Lives here.

• Pure physics — derivations and parameter values that depend only on the underlying model. Lives in the theory section.

• Coupled — the soft-mask sigmoid for the BM19 transition density: it is a physics choice (using a soft threshold instead of hard) but motivated by a JAX constraint (autodiff needs smooth thresholds). Lives in Differentiability rules here, with the scientific consequences in The magnification factor ζ — three ways to compute it.

When in doubt about which section a topic belongs in, the test is: “would this discussion still be true if we ported progenax to PyTorch or NumPy?” If yes → theory. If no → architecture.

References¶

The JAX programming model is documented at the JAX docs. Equinox is Kidger & Garcia (2021). The broader JAX ecosystem progenax sits in (jaxstro, gravax, stellax) is described in the jaxstro README.