`progenax.tidal`

progenax.tidal¶

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

Module path: progenax/tidal/

Public symbols: 4

Contents¶

• jacobi_radius

• jacobi_radius_isothermal

• apply_tidal_truncation

• fill_factor_to_r_h

tidal.jacobi_radius¶

function

📇 model card

jacobi_radius(M_cluster: float, M_galaxy: float, R_galactic: float) -> float

Compute Jacobi (tidal) radius for a cluster in a galaxy.

The Jacobi radius is where the cluster’s gravitational pull equals the tidal force from the galaxy (point mass approximation):

r_J = R * (M_cluster / (3 * M_galaxy))^(1/3)

Beyond r_J, stars become unbound from the cluster.

Args

Returns: Jacobi radius [pc]

Note. This assumes a point-mass galaxy and circular orbit. For more realistic models, use galactic potential functions.

Reference: King (1962) AJ 67, 471 Binney & Tremaine (2008) Eq. 8.91

Source: src/progenax/tidal.py#L20

tidal.jacobi_radius_isothermal¶

function

jacobi_radius_isothermal(M_cluster: float, V_circ: float, R_galactic: float, G: float) -> float

Compute Jacobi radius for isothermal halo.

For a singular isothermal sphere with circular velocity V_circ:

r_J = (G * M_cluster / (2 * Omega^2))^(1/3)

where Omega = V_circ / R is the angular velocity. Substituting Omega = V_circ / R_galactic, this is algebraically identical to the flat-rotation-curve form r_J = (G m_c / 2 V_G^2)^(1/3) R_G^(2/3) of Baumgardt & Makino (2003), MNRAS 340, 227, Eq. 1 (the N-body-calibrated primary; the factor of 2 rather than 3 is the signature of the logarithmic / flat-rotation-curve potential).

Units (IMPORTANT): V_circ must be in the SAME length/time units as G, i.e. consistent with the rest of the unit system — pc/Myr for STELLAR, NOT km/s. The ecosystem’s display convention quotes velocities in km/s, but G is in pc^3 Msun^-1 Myr^-2, so pass V_circ in pc/Myr (1 km/s = 1.0227 pc/Myr); mixing the two biases r_J by ~1.5% per the km/s->pc/Myr factor.

Args

Returns: Jacobi radius [pc] Reference: Binney & Tremaine (2008) Section 8.3.1 Baumgardt & Makino (2003) MNRAS 340, 227, Eq. 1 - the same relation, N-body-calibrated for clusters in a logarithmic Galactic potential.

Source: src/progenax/tidal.py#L54

tidal.apply_tidal_truncation¶

function

📇 model card

apply_tidal_truncation(positions: Float[Array, 'N 3'], velocities: Float[Array, 'N 3'], masses: Float[Array, 'N'], r_t: float, grad_width: float = 0.05) -> Tuple[Float[Array, 'N 3'], Float[Array, 'N 3'], Float[Array, 'N'], Float[Array, 'N']]

Sharp tidal truncation — shape-preserving and differentiable in r_t.

Particles with r > r_t are “removed” by setting their mass to zero, so they contribute nothing to mass-weighted quantities (energy, virial, COM). The forward pass is an EXACT hard cut; the backward pass uses a logistic straight-through surrogate (width grad_width * r_t) so that r_t — and any upstream parameter feeding it (e.g. via :func:jacobi_radius) — remains differentiable. Unlike boolean-mask indexing, the output keeps a static shape N, so the function is jit / vmap / grad safe.

.. warning:: The survivors keep the velocities they were drawn with for the UNtruncated potential, so the truncated set is SUPER-VIRIAL w.r.t. its own (now shallower) potential — some stars near r_t are formally unbound and the set is not a stationary equilibrium (audit S4). Re-virialize the survivors (virial_scale / rescale_velocities_to_virial) or use an r_t-consistent equilibrium model (King / LIMEPY) if you need a stationary IC.

Args

Returns: Tuple (positions, velocities, masses_truncated, keep_mask), all length N: - positions, velocities: unchanged (truncated particles are left in place — never moved to inf, which would give 0 * inf = nan in mass-weighted sums). - masses_truncated: masses with r > r_t entries set to 0. - keep_mask: boolean (N,), True where r <= r_t (use this to filter NUMBER-based downstream quantities, which still see the zero-mass “ghost” particles).

Note. Sharp cutoff. For a physically smooth truncation consistent with King models, use the King profile directly.

Source: src/progenax/tidal.py#L128

tidal.fill_factor_to_r_h¶

function

fill_factor_to_r_h(fill_factor: float, r_J: float) -> float

Convert fill factor to half-mass radius.

The fill (Roche-filling) factor is defined as the ratio of the half-mass radius to the Jacobi radius, fill_factor = r_h / r_J; this function simply inverts that definition, r_h = fill_factor * r_J. This is a definitional ratio (the “fill factor” / “tidally filling” terminology is later community usage), NOT a relation derived from any single source.

Typical values: - fill_factor ~ 0.05-0.15: Compact, tidally underfilling - fill_factor ~ 0.15-0.30: Typical globular cluster - fill_factor ~ 0.30-0.50: Tidally filling

Args

Returns: Half-mass radius r_h [length units]

Source: src/progenax/tidal.py#L187