Skip to content

src/core/exomoon.js ​

text
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 ​

js
const MOON_PARAMS

Registry 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 ​

js
const MOON_FIELDS

The unscoped moon keys.

MOON_PARAM_BY_KEY ​

js
const MOON_PARAM_BY_KEY

No description in the source.

moonKey ​

js
const moonKey

Key of a moon parameter of the planet with suffix sfx ('' for the first planet): "rmoon", "rmoon@c".

moonParamsFrom ​

js
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 ​

js
function moonGeometry(p)
text
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 ​

js
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 ​

js
function moonSupersample(exptimeDays, p)

Sub-samples per exposure that resolve the moon's ingress (see autoSupersample in model.js for the planet's).

overlapBlocked ​

js
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 ​

js
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 ​

js
function makePlanetMoonTransit(params)
text
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 radii

moonComponents ​

js
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 ​

js
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 ​

js
function planetPosition(el, moonParams, t, out = [0, 0, 0])
text
The planet's position at time t, displaced from its Keplerian orbit by the moon's pull (equal to orbitPosition() when mmoon = 0).

moonOrbitPath ​

js
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 ​

js
function ttvTdvAmplitudes(params)
text
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 ​

js
function moonTimings(params, epochs)
text
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 ​

js
function moonSearch(data, planet, opts = {})
text
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 ​

js
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 ​

js
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.

MIT licensed · Kyle A. Pearson