src/core/exomoon.js
A planet with a moon in front of a limb-darkened star: geometry, photometry, timing, search.
---------------------------------------------------------------------------------------------
INTEGRATION (for the owner of src/core/model.js; nothing here edits that file)
import { makePlanetMoonTransit, moonParamsFrom, MOON_FIELDS } from './exomoon.js';
In evaluate(), where a planet's light curve is compiled, replace
fluxes[p] = makeTransit(tp);
with
const moon = moonParamsFrom(v, sfx[p], { mplanet: q.mplanet, mstar: v.mstar });
if (moon) {
const f = makePlanetMoonTransit({ ...tp, ...moon }); // tp: what toTransitParams() returns, with q.ars
if (!f.ok) return null; // separation not computable, or the moon inside the planet
// optional, stricter prior: if (!f.validity.bound) return null; (outside the Hill sphere)
fluxes[p] = f;
} else fluxes[p] = makeTransit(tp);
f(t) has the signature of makeTransit's result (relative flux, 1 out of transit), so the exposure
averaging, the product over planets and the a1 / airmass baseline need no change.
* Keys. A moon belongs to one planet: planet b reads rmoon, permoon, phmoon, mmoon, imoon, amoon;
planet c reads rmoon@c, permoon@c, ... moonParamsFrom() does NOT fall back from "rmoon@c" to
"rmoon" (that would hand planet b's moon to planet c), unlike the fallback buildProblem uses for
PLANET_FIELDS. So do not add MOON_FIELDS to PLANET_FIELDS; read them through moonParamsFrom().
A planet has a moon when its rmoon key is present (a number, 0 included) in values or in free.
* Registry. MOON_PARAMS has the entries in the style of PARAMS (plus `prior`, the default prior);
add them to PARAM_BY_KEY so paramFor('rmoon@c') resolves, and to activeParams() for planets that
have a moon (group 'moon').
* Separation. With mplanet [M Jup] and mstar [M Sun] given (they already exist as keys) the
planet-moon separation follows from the moon's period by Kepler's third law. Without masses,
give amoon (stellar radii) or amoonrp (planet radii). See moonGeometry().
* Exposure. autoSupersample() looks at the planet's ingress only. The moon's ingress is shorter
by about rmoon / rprs; for long exposures use max(planet's, moonSupersample(exptime, params)).
* Masses. With spec.kepler, a/R* comes from M* + Mp; the moon's mass is not added (a relative change of
Mm / 3 M* in a/R*, 6e-6 for a 6 Earth-mass moon of a Jupiter). The moon's separation does use Mp + Mm.
* fitRunner.runFit() only takes a buildProblem spec, so until model.js has the moon a fit needs its own
likelihood on MiniNest (test/exomoon.test.mjs does this). Start it from moonSearch(): the period has
aliases at 1/P + k/per that the search lists in `peaks`, and one narrow prior per peak is the safe way.
* Plots. f.components(t) gives the isolated pieces; moonComponents(times, params) gives arrays.
* 3D view. moonPosition(el, params, t), planetPosition(el, params, t) and moonOrbitPath(el, params, t)
use the frame of orbitPosition() in kepler.js.
---------------------------------------------------------------------------------------------
THE MODEL
Geometry. The barycentre of planet and moon moves on the planet's Keplerian orbit (kepler.js: sky
plane X, Y in stellar radii, +Z toward the observer, mid-transit at inferior conjunction, where the
barycentre moves toward +X). The moon's orbit about the planet is circular, with radius a_m:
moon - planet = a_m (cos theta e1 + sin theta e2), theta = pi/2 + 2 pi (phmoon + (t - tmid) / permoon)
e1 = (-1, 0, 0), e2 = (0, -cos(i + imoon), sin(i + imoon))
With imoon = 0 these are the axes of the planet's own orbit, so the moon is coplanar and prograde
(it circles the planet in the same sense as the planet circles the star). theta is measured like
the planet's omega + nu: phmoon = 0 puts the moon between the planet and the observer at the
planet's mid-transit, 0.25 ahead of the planet (it transits first), 0.5 behind the planet, 0.75
trailing. imoon tilts the moon's orbit about the axis along the transit chord: the moon's orbit
is then inclined i + imoon to the sky, and imoon = 180 is a coplanar retrograde orbit. One angle
only: the line of nodes is fixed along the chord (a longitude of the node would be the next step).
planet = barycentre - q/(1+q) (moon - planet), moon = barycentre + 1/(1+q) (moon - planet), q = Mm/Mp
q = 0 (the default) switches the barycentric wobble off: depth and period can be searched first.
Separation (moonGeometry). Default, when the planet's and the star's masses are known: Kepler's
third law for both orbits gives, with mu = (Mp + Mm) / M*,
a_m / R* = (a/R*) (permoon / per)^(2/3) (mu / (1 + mu))^(1/3)
which needs no stellar radius, and makes the moon's period the single quantity that sets both when
and where the moon appears. It is the default because the period is what a search finds, and a
separation that is free of the period lets the sampler put the moon anywhere. Without masses, or
to override: amoonrp (planet radii) or amoon (stellar radii), in that order of precedence.
Photometry. Both bodies are opaque discs, so the blocked flux is that of the union of the discs:
blocked = B(planet) + B(moon) - B(planet AND moon AND star)
B of one disc is transit.js's blockedFraction. The last term (the lens where the discs overlap,
clipped by the stellar limb) uses the same Green's theorem as the kernel: the region is convex and
bounded by at most one arc of each of the three circles, and
B = (1 / 2 pi F(1)) * sum over arcs of int F(r)/r^2 (x dy - y dx)
An arc of the stellar limb contributes F(1) times its angle. An arc of a disc's limb is split at
the point furthest from the star's centre (if it holds one), each piece is halved, and each half
gets 20 Gauss-Legendre nodes after the phi -> u^2 substitution that clusters them at its outer
end, where the arc may touch the stellar limb. Whether the moon is in front of or behind the
planet makes no difference. A moon wholly inside the planet's disc leaves the light curve of the
planet alone, exactly. Accuracy against scipy adaptive quadrature: see test/exomoon.test.mjs.
What is left out: an eccentric moon orbit, a second orientation angle, precession, the planet's
oblateness, light-travel time across the moon's orbit, the moon's own light, three-body effects
(the moon's orbit is a fixed circle), and the TDV from a changing impact parameter (Kipping 2009b),
which the geometry produces when imoon is not 0 but which has no closed form here.Import: import { … } from './src/core/exomoon.js' — no DOM, runs in Node and the browser.
MOON_PARAMS
const MOON_PARAMSRegistry entries in the style of PARAMS in model.js, plus prior (default prior) and group. Keys take the planet scope like any planet-level key: rmoon for the first planet, rmoon@c for planet c.
MOON_FIELDS
const MOON_FIELDSThe unscoped moon keys.
MOON_PARAM_BY_KEY
const MOON_PARAM_BY_KEYNo description in the source.
moonKey
const moonKeyKey of a moon parameter of the planet with suffix sfx ('' for the first planet): "rmoon", "rmoon@c".
moonParamsFrom
function moonParamsFrom(v, sfx = '', extra = {})The moon's parameters of one planet from a flat table of values (keys as in the analyzer), or null when that planet has no moon (no rmoon key). No fallback to another planet's moon. extra: { mplanet [M Jup], mstar [M Sun] } of this planet and its star, for the Kepler separation.
moonGeometry
function moonGeometry(p)Resolve the moon's orbit and check that it is physical.
p: the planet's { rprs, per, ars, inc, ecc } and the moon's { rmoon, permoon, phmoon, mmoon, imoon,
amoon | amoonrp (optional), mplanet [M Jup], mstar [M Sun] (optional), rhoRatio (optional) }
returns {
aMoon [R*], aMoonRp [planet radii], mode: 'kepler' | 'rstar' | 'rp' | 'none',
q (Mm/Mp), aWobble [R*] (radius of the planet's orbit about the barycentre),
mu: (Mp + Mm)/M* used, or the value implied by the given separation and period,
hill [R*], hillFrac (aMoon / Hill radius), stableFrac (limit for this orbit, in Hill radii),
maxPeriod [d] (longest stable period), roche [R*] and rocheRp (fluid Roche limit),
bound, stable, outsideRoche, clear (not touching the planet), ok (all four), reasons: [strings] }
Hill radius r_H = a (1 - e) (mu / 3)^(1/3). With Kepler's law for both orbits
aMoon / r_H = (3 / (1 + mu))^(1/3) (permoon / per)^(2/3) / (1 - e): a statement about the period
ratio alone. A prograde moon inside 0.4895 r_H has permoon < 0.198 per (Kipping 2009: about P/5).
Roche limit for a fluid moon: 2.44 Rp (rho_p / rho_m)^(1/3). rho_p / rho_m is rhoRatio if given,
else (rmoon / rprs)^3 / q when the mass ratio is known, else 1.moonPeriodFor
function moonPeriodFor(aMoon, p)Moon period [d] that puts the moon at separation aMoon [R*] by Kepler's law (inverse of the default in moonGeometry).
moonSupersample
function moonSupersample(exptimeDays, p)Sub-samples per exposure that resolve the moon's ingress (see autoSupersample in model.js for the planet's).
overlapBlocked
function overlapBlocked(x1, y1, r1, x2, y2, r2, ld)Fraction of the stellar flux inside both discs at once: disc 1 at (x1, y1) with radius r1, disc 2 at (x2, y2) with radius r2 (stellar radii, star at the origin with radius 1), clipped by the star. ld: prepareLD(toClaret(law, coefficients)).
unionBlocked
function unionBlocked(x1, y1, r1, x2, y2, r2, ld, out)Fraction of the stellar flux blocked by the union of two opaque discs (stellar radii, star at the origin). out, if given, receives { first, second, overlap }: each disc alone and the part counted twice.
makePlanetMoonTransit
function makePlanetMoonTransit(params)Compile a planet + moon parameter set into a fast evaluator: the function for the likelihood.
params: everything makeTransit takes { rprs, per, tmid, ars, inc, ecc, omega, ldLaw, ld: [...] }
plus the moon { rmoon, permoon, phmoon, mmoon = 0, imoon = 0,
amoon | amoonrp (optional), mplanet [M Jup], mstar [M Sun] }
plus switches, all true by default { wobble, moonTransit, mutual }
wobble: false the planet stays on the barycentre's orbit whatever mmoon is (no TTV / TDV)
moonTransit: false the moon blocks no light (only its pull on the planet remains)
mutual: false the discs' overlap is not corrected: planet and moon dips are simply added
returns flux(t) -> relative flux (1 out of transit), with these properties:
flux.ok false when the separation cannot be computed or the moon would be inside the planet
(flux(t) is then the moonless transit); a likelihood should reject the point
flux.geometry moonGeometry(params): separation, Hill and Roche checks, reasons
flux.validity the same object (alias, reads better in a prior: flux.validity.bound)
flux.components(t, out = {}) -> { total, planet, moon, overlap, moonless, diff, wobble }
planet flux with the planet alone, where the wobble puts it (1 - B_planet)
moon flux with the moon alone (1 - B_moon)
overlap flux given back because the discs overlap, >= 0 (B of the lens)
total planet + moon - 1 + overlap = flux(t)
moonless the planet on the barycentre's orbit, no moon: makeTransit(params)(t)
diff total - moonless: everything the moon does to the light curve
wobble planet - moonless: the timing and duration signature alone
flux.positions(t, planet = [0,0,0], moon = [0,0,0]) -> writes both positions [X, Y, Z] in stellar radiimoonComponents
function moonComponents(times, params, opts)The isolated pieces on an array of times, for plotting. opts: { exptime (days), supersample } average every piece over the exposure, as transitModel does. returns Float64Arrays { total, planet, moon, overlap, moonless, diff, wobble } (see makePlanetMoonTransit) and ok.
moonPosition
function moonPosition(el, moonParams, t, out = [0, 0, 0])The moon's position [X, Y, Z] in stellar radii at time t, in the frame of orbitPosition(). Writes into out.
planetPosition
function planetPosition(el, moonParams, t, out = [0, 0, 0])The planet's position at time t, displaced from its Keplerian orbit by the moon's pull (equal to orbitPosition() when mmoon = 0).moonOrbitPath
function moonOrbitPath(el, moonParams, t, n = 128, opts = {})The moon's orbit as n points, Float32Array(3n), for drawing. The ring is centred on the planet where it is at time t, so the moon's position at t lies on it. opts.center: 'planet' (default), 'barycentre' (the moon's circle about the common centre) or 'none' (offsets from the planet, not positions).
ttvTdvAmplitudes
function ttvTdvAmplitudes(params)Analytic amplitudes of the planet's transit timing and duration variations caused by the moon
(Kipping 2009a, MNRAS 392, 181, for a circular coplanar moon orbit). With a_w = a_m q / (1 + q) the
radius of the planet's orbit about the barycentre and v_B the barycentre's sky velocity at mid-transit,
(2 pi a / P)(1 + e sin omega) / sqrt(1 - e^2):
TTV: the planet is displaced a_w cos(theta) along its path peak a_w / v_B
TDV: its velocity changes by a_w (2 pi / permoon) sin(theta) peak Tbar (2 pi a_w / permoon) / v_B
For a circular planet orbit these are Kipping's a_w P / (2 pi a) and Tbar a_w P / (a permoon); his
delta_TTV and delta_TDV are the rms values, peak / sqrt(2). The two are a quarter of a cycle apart, and
their ratio 2 pi Tbar / permoon gives the moon's period without knowing its mass.
returns { aWobble [R*], vSky [stellar radii per day], tbar [d] (centre on the limb to centre on the limb), ttv, tdv (peaks, d),
ttvRms, tdvRms, ratio (tdv / ttv) }moonTimings
function moonTimings(params, epochs)The planet's transit times and durations measured from the geometry, transit by transit.
epochs: array of whole orbit numbers E (the transit near tmid + E per).
A transit runs from the planet's centre crossing the stellar limb inward to crossing it outward
(Kipping's Tbar); its mid-time is the mean of the two.
returns { epoch, tlin (tmid + E per), tmid (measured), ttv (tmid - tlin), dur, tdv (dur - moonless dur),
theta (the moon's orbital angle at tlin, rad), durMoonless }, arrays; NaN where the centre never crosses the limb.moonSearch
function moonSearch(data, planet, opts = {})Search a light curve for a moon's own transits, with the planet's transit model already fitted.
For a trial moon (period, phase at the planet's mid-transit) the moon's dips have a known shape, and
their depth is very nearly proportional to rmoon^2. With residuals r = planet model - data and the
template m = flux blocked by a moon of the reference radius, the best amplitude is A = sum(w r m) /
sum(w m^2) and the fit improves by delta chi2 = (sum w r m)^2 / sum(w m^2): a matched filter. The map
returned is the signed signal-to-noise snr = sum(w r m) / sqrt(sum w m^2) (so delta chi2 = snr^2,
positive snr = a dimming moon), with rmoon = rmoonRef sqrt(A).
To make the grid cheap the sums are built per transit: for a coarse set of periods (which fix the
separation and the moon's motion during a transit) and a grid of moon phases at each transit's own
mid-time, sum(w r m) and sum(w m^2) of every transit are tabulated once. A fine period then only
decides which phase each transit has, and costs one table lookup per transit.
The planet's depth is refitted with every trial moon (opts.fitDepth, on by default): a planet-only fit to
a light curve that holds a moon has already absorbed part of the moon into the planet's depth, and
without this the search prefers moons that stay clear of the planet. In effect the template is made
orthogonal to the planet's dip p = 1 - model: snr = (S_rm - S_mp S_rp / S_pp) / sqrt(S_mm - S_mp^2 / S_pp).
The planet's mid-time in every transit is refitted as well (opts.fitTiming, on by default), by projecting
d(model)/dt out of each transit: a moon massive enough to be seen also shifts the planet's transits by
minutes, and the residuals of that shift at ingress and egress are larger than the moon's own dip. The
duration is not refitted.
Aliases. Transits sample the moon once per planet period, so periods with 1/P' = 1/P + k/per put the moon
at the same phase at every transit. They differ only through the separation (Kepler) and the moon's
motion during a transit, and show as a comb of peaks in `profile`.
Assumptions: coplanar moon (opts.imoon to change), no wobble (mmoon = 0: the planet model is the
fitted one), the moon contributes nothing while its disc is wholly inside the planet's, partial
overlaps are not corrected, white Gaussian noise with the given error bars.
data: { t, f, e } normalised flux (baseline 1), times as in the planet's tmid
planet: makeTransit's parameters, plus mplanet [M Jup] and mstar [M Sun] (or amoon / amoonrp for a
fixed separation)
opts: { periods: [min, max] in days (default: from the fluid Roche limit to the longest stable prograde period),
nPhases (48), oversample (12: fine periods per 1 / baseline in frequency), maxPeriods (20000),
nCoarse (coarse periods, default 12 per octave), rmoonRef (reference radius, default 0.3 rprs),
model (Float64Array: the planet model at data.t, default makeTransit(planet)), imoon (0), fitDepth (true), fitTiming (true),
nNull (0): noise-only realisations searched in the same pass, seed (1) }
returns { periods, phases, snr (Float32Array, index ip * nPhases + ih), rmoon (same shape, 0 where snr <= 0),
profile (max snr over phase for each period), peaks: [{ permoon, snr }] (its 8 strongest separate maxima),
best: { permoon, phmoon, rmoon, snr, dchi2, amoon }, inverted: { permoon, phmoon, snr } (the strongest
brightening "moon"; on noise it is about as large as best.snr, and it goes negative when every trial moon
dims the star, which is the orbital sampling effect of a real one),
nullMax (largest snr of each noise realisation), fap ((1 + number of nulls >= best) / (1 + nNull)),
ntransits, npoints, ms }oseStack
function oseStack(data, planet, opts = {})Orbital sampling effect (Heller 2014, ApJ 787, 14): over many transits a moon is seen at every phase of its orbit, so the residuals from the planet's model, stacked on the planet's period, show its average dimming: wings before and after the planet's transit, out to the moon's separation. data: { t, f, e }; planet: makeTransit's parameters; opts: { nbins (40), window (half-width in days, default: the data's largest offset from a mid-transit), model } returns { x (days from mid-transit, bin centres), y (weighted mean of data - model), e, n } with empty bins left out.
oseModel
function oseModel(params, x, nPhase = 48)What the orbital sampling effect looks like for a given moon: the difference from the moonless light curve averaged over nPhase equally spaced moon phases, at offsets x (days) from mid-transit.