Skip to content

src/core/physical.js ​

text
Physical-viability priors for multi-planet fits: configurations that cannot exist (crossing orbits, planets inside
each other's Hill spheres, too much angular-momentum deficit, a planet inside the star or its own Roche limit, chaotic
orbits) get zero prior mass. buildProblem (model.js) calls makePhysicalCheck once and the check at every likelihood
call, before any model is computed; a point that fails returns the same "outside the prior" value as an unbound orbit.

Each test is off unless spec.physical switches it on:
  spec.physical = {
    crossing: true,          radial ranges must not overlap: periastron of every outer planet beyond the apastron of
                             the planet inside it, a_out (1 - e_out) > a_in (1 + e_in) for every adjacent pair (sorted by period)
    hill: true,              Gladman (1993) two-planet Hill stability, eccentric and coplanar (eq. 21 there), for every
                             adjacent pair:  mu^-3 (mu1 + mu2 / l^2) (mu1 g1 + mu2 g2 l)^2 > 1 + 3^(4/3) mu1 mu2 / mu^(4/3),
                             mu_i = m_i / M*, mu = mu1 + mu2, l = sqrt(a_out / a_in), g_i = sqrt(1 - e_i^2). For circular
                             orbits this is a_out - a_in > 2 sqrt(3) R_H with R_H = ((m1 + m2) / 3 M*)^(1/3) (a1 + a2) / 2
                             to leading order in the masses.
    hillSpacing: 8,          every adjacent pair at least this many mutual Hill radii apart, (a_out - a_in) / R_H
                             (Chambers et al. 1996 style; about 10 for systems of three or more planets to survive ~1e8 orbits)
    amd: true,               AMD stability (Laskar & Petit 2017) with coplanar orbits (sky inclinations do not give mutual
                             ones): C = sum Lambda_k (1 - sqrt(1 - e_k^2)), Lambda_k = m_k sqrt(G M* a_k); every adjacent
                             pair needs C / Lambda_out < C_c(alpha, gamma) (their eqs. 35, 39; amdCritical in nbody.js) and
                             the innermost planet C / Lambda_1 < 1 (collision with the star, their eq. 42)
    roche: true,             periastron of every planet outside the star (a (1 - e) > 1 + Rp/R*) and outside its Roche
                             limit, a (1 - e) > f Rp/R* (M* / Mp)^(1/3) (all in stellar radii); f = rocheFactor
    rocheFactor: 2.16,       Rappaport et al. 2013 (centrally condensed planet); 2.44 is the fluid-body value
    megno: { orbits: 300, max: 2.5 }   (expensive) integrate the variational equations (megno() in nbody.js) for that
                             many orbits of the outermost planet; reject a failed integration or <Y> above max
                             (2 for regular motion). Run last, only for points that passed everything else.
  }

Semi-major axes for the pairwise tests come from Kepler's third law with each planet's period and mass and M*
(a in au), so they are consistent with the periods even when a/R* is fixed separately. The Roche test uses the
planet's own a/R* (fitted, fixed or from spec.kepler). Masses are mplanet [M_Jup], or follow from K when a planet
has K instead; a planet with no mass counts as massless (Hill radius 0: only crossing is then tested for it).

Evidence. A truncated prior removes prior mass: the sampler's Z is then the integral of L pi over the allowed region,
i.e. the evidence of the model "this prior AND the system is viable" (the constraint acts like data with likelihood
0 or 1). The evidence of the renormalised prior pi / V is Z / V, V = the prior mass that passes. physicalPriorVolume()
estimates V by Monte Carlo from prior draws; ln Z - ln V is the evidence with the renormalised prior. Which to quote
depends on the question: ln Z compares "viable" models fairly against each other; ln Z - ln V compares one model's
truncated prior with its untruncated self (it always wins by about -ln V when the data already sit in the allowed region).

Import: import { … } from './src/core/physical.js' — no DOM, runs in Node and the browser.

physicalOptions ​

js
function physicalOptions(o)

Which tests a physical-options object switches on (normalises booleans and numbers).

gladmanMargin ​

js
function gladmanMargin(mu1, mu2, a1, a2, e1 = 0, e2 = 0)

Gladman (1993) Hill-stability margin of two planets on coplanar orbits: LHS / RHS - 1 of his eq. 21 (positive: Hill stable, close encounters impossible). mu1, mu2: masses over the star's; a1 < a2 (any unit); e1, e2 eccentricities.

mutualHillRadius ​

js
const mutualHillRadius

Mutual Hill radius ((m1 + m2) / 3 M*)^(1/3) (a1 + a2) / 2 (masses over the star's).

amdStability ​

js
function amdStability(planets)
text
AMD stability of coplanar orbits (Laskar & Petit 2017). planets: [{ m (any unit, same for all), a (any unit), e }]
sorted by a. Returns { amd (in units of m sqrt(a), G M* = 1), betaStar (C / Lambda_1), pairs: [{ beta, Cc, alpha, gamma }],
stable }. beta = C / (Lambda_out C_c(alpha, gamma)); stable when every beta < 1.

makePhysicalCheck ​

js
function makePhysicalCheck(raw)
text
Compile the checks. opts: physicalOptions(spec.physical) (or the raw object). Returns null when nothing is on, else
check(planets, mstar) -> null when viable or a short reason string ('crossing', 'hill', 'hillSpacing', 'amd', 'roche',
'surface', 'megno'). planets: [{ per, ecc, omega, inc, mplanet (M_Jup), K, rprs, ars, tmid }], mstar [M_sun].

physicalPriorVolume ​

js
function physicalPriorVolume(prob, { n = 20000, seed = 11 } = {})

Prior mass V that passes the optional prior tests: the fraction of n draws from the prior (unit cube through the problem's transform) that pass the physical tests and, with spec.phase.positive_map, the positivity of the map, among the draws that pass the model's own checks (a bound orbit, a planet flux that is nowhere negative, ...). prob: from buildProblem (needs prob.priorCheck). Returns { V, lnV, lnVerr (binomial), n, nBase, nPass, reasons }.

MIT licensed · Kyle A. Pearson