`progenax.cluster`

`progenax.cluster`¶

Auto-generated by scripts/build_api_reference.py from progenax source. Re-run after public-API changes; the script is idempotent.

Module path: progenax/cluster/

Public symbols: 15

Contents¶

MultiComponentCluster
energy_sorted_segregation
G_KMS
C_S_DEFAULT
B_DEFAULT
BETA_KOLMOGOROV
BETA_BURGERS
SIGMA_V0_DEFAULT
ALPHA_LARSON
sigma_ln_rho_from_mach
spectral_slope_from_mach
cloud_radius_from_density
larson_sigma_v
turbulent_mach_from_cloud
b_from_environment

`cluster.MultiComponentCluster`¶

class

📇 model card · ∇ gradient-verified — 9 audit cases

MultiComponentCluster(alpha_j=None, w_j=None, m_j=None, W0=None, g=None, r_c=None, xi_grid=None, psi_grid=None, ra_hat_j=None, residual=0.0, n_grid: int = 1000, rho_on_xi=None, dens_fn=None, psi_raw=None, *, _fields=None)

Multi-component cluster in shared-potential equilibrium (two engines).

Engine A (DF-defined, lowered-isothermal/LIMEPY family): construct with from_components (direct per-component velocity-scale ratios w_j -- the general case), from_mass_segregation (the equipartition law w_j = mu_j^(-delta)), or from_imf (bin an IMF, eigenvalue-solve for alpha_j).

Engine B (density-defined, Eddington inversion): construct with from_density_profiles (Plummer/EFF/King density components in ONE shared self-consistent potential, per-component DFs via Eddington inversion, optional per-component Osipkov-Merritt r_a_j).

Either way, sample_cluster returns an :class:~progenax.builders.ICResult whose component_id labels each star’s generating component.

Differentiable in every per-component parameter (Engine A: alpha_j, w_j, ra_hat_j, W0, g; Engine B: profile scales, mass fractions, r_a_j) through construction AND sampling.

Attributes

Parameter	Description
`r_t`	tidal/truncation radius (shared by both engines).
`m_j`	representative stellar mass per component [M_sun] (labels only).
`N_frac_j`	number fraction of stars per component.
`engine`	“A” or “B” (static; resolves dispatch at trace time).
`engine_a`	grouped Engine A state (`_EngineAState`; None on B models).
`engine_b`	grouped Engine B state (`_EngineBState`; None on A models). Engine-A-only quantities (W0, g, r_c, mu_tot, alpha_j, w_j, ra_hat_j, xi_grid, psi_grid, residual) are exposed as delegating properties reading through `engine_a`: W0, g, r_c: structural parameters / scales.
`alpha_j`	central density fractions (sum to 1).
`w_j`	per-component velocity-scale ratios s_j/s (rescale_j = w_j^-2).
`ra_hat_j`	per-component anisotropy radii r_{a,j}/r_c (inf = isotropic).
`mu_tot`	total dimensionless mass integral (sets the velocity scale).
`residual`	eigenvalue-solve residual (0 for direct constructors). xi_grid, psi_grid: shared coupled-Poisson solution W(xi). On an Engine B model each raises an informative AttributeError naming the engine (this replaced the NaN-sentinel tripwires).

Source: src/progenax/cluster/multicomponent.py#L143

`cluster.energy_sorted_segregation`¶

function

📇 model card

energy_sorted_segregation(key: PRNGKeyArray, masses: Float[Array, 'N'], positions_pool: Float[Array, 'N_pool 3'], velocities_pool: Float[Array, 'N_pool 3'], potential_fn: Callable[[Float[Array, 'N_pool 3']], Float[Array, 'N_pool']]) -> Tuple[Float[Array, 'N'], Float[Array, 'N 3'], Float[Array, 'N 3']]

Assign positions/velocities to masses using Baumgardt energy-ordered method.

This implements full energy-ordered segregation (S=1 at the bin level) — a PRIMORDIAL generator. For partial/continuous segregation use the equilibrium family (MultiComponentCluster.from_mass_segregation), not a blend of this function’s output.

.. warning:: Reassigning masses by energy rank changes the mass-weighted density, so it no longer matches the parent profile the orbit pool was drawn from — the self-consistent potential of the segregated system DIFFERS, and the output is not exactly in equilibrium (audit S6). Callers should finalize with a global virial rescale (virial_scale), as the validation suite does.

Algorithm (Baumgardt+2008 Appendix, McLuster implementation): 1. Sort masses descending → m_sorted[i] for mass rank i 2. Cumulative-mass coordinate M_cum_norm[i] = sum(m_sorted[0:i+1]) / M_total, and the bin-centre target energy-rank t[i] = floor(N_pool * M_cum_mid[i]), M_cum_mid[i] = (M_cum_norm[i-1] + M_cum_norm[i]) / 2 3. Sort orbit pool by specific energy (most bound first) 4. Assign each mass rank a DISTINCT orbit by isotonic-rounding the targets to a strictly increasing integer sequence in [0, N_pool-1]: idx[i] = max(idx[i-1] + 1, min(t[i], N_pool - N + i)) (the per-rank upper clamp prevents overflow; the running max guarantees no reuse). Most massive rank 0 -> smallest index -> most bound orbit. 5. Map back to original mass ordering

This deterministic monotonic assignment replaced an earlier per-bin random sampler whose cumulative-mass bins collapsed below one orbit for steep IMFs, forcing many low-mass ranks onto the same orbit (coincident stars, V = -inf). See docs/website/50-validation/mass-segregation.md.

Args

Parameter	Description
`key`	JAX random key (retained for API stability; the assignment is now deterministic — realisation variety comes from the random orbit pool).
`masses`	Stellar masses with shape (N,). Will be sorted internally; output preserves original ordering.
`positions_pool`	Orbit pool positions with shape (N_pool, 3) from equilibrium distribution function.
`velocities_pool`	Orbit pool velocities with shape (N_pool, 3) from equilibrium distribution function. Must use consistent units with potential_fn so that E = 0.5 * v² + Φ is meaningful.
`potential_fn`	Callable computing specific potential Φ(r) (per unit mass) at positions. Must return shape (N_pool,) with same energy units as 0.5 * v². Should be the analytic profile potential (Plummer/King/EFF), NOT a direct N-body sum, ensuring consistency between the DF used to draw orbits and the energy ordering used for segregation.

Returns: Tuple of (masses_out, positions, velocities): - masses_out: Masses in original order (N,) - unchanged from input - positions: Assigned positions (N, 3) - velocities: Assigned velocities (N, 3) Shape Expectations: - masses: (N,) - positions_pool: (N_pool, 3) - velocities_pool: (N_pool, 3) - potential_fn(positions_pool) must return: (N_pool,) Pool Size Recommendations: Set N_pool = pool_factor * N with pool_factor >= 4 so the assigned orbits are a well-spread mass-weighted subsample of the pool and the segregation signal is smooth. Any N_pool >= N yields a valid no-reuse assignment; small N_pool just leaves fewer distinct orbits between mass ranks. No-Orbit-Reuse Guarantee: The isotonic-rounding assignment (Step 4) produces a strictly increasing integer sequence in [0, N_pool-1], so every mass rank receives a DISTINCT orbit and no two stars are coincident — for ANY mass spectrum, including steep IMFs. (The previous per-bin sampler did NOT guarantee this: sub-orbit bins collapsed and reused orbits.) Verified for uniform/bimodal/Kroupa/extreme-steep spectra in tests/unit/cluster/test_mass_segregation.py. Non-Differentiability: This function is NOT differentiable (argsort, floor) and is not meant to be: it is a discrete primordial-assignment generator. For gradient-based inference over segregation strength, use the first-principles equilibrium knob instead — MultiComponentCluster.from_mass_segregation(delta), which is differentiable in delta and a true shared-potential equilibrium at every value. (The historical lambda_seg catalog blend was retired: its intermediate states drift from per-mass-group virial balance — see per_group_virial_ratio and the mass-segregation validation page.) Segregation Strength: Implements full Baumgardt-style energy ordering (S=1): the most massive stars occupy the most bound orbits. The assignment is deterministic given the pool; realisation variety comes from re-drawing the random orbit pool.

Source: src/progenax/cluster/mass_segregation.py#L45