src/core/phasecurve.js
Secondary eclipses, phase curves and eclipse mapping.
============================== INTEGRATION ==================================
For the owner of src/core/model.js. Nothing here edits model.js; three small changes there
switch the light curve from "transit" to "transit + planet":
1. Keys. Add the phase keys to the fields a planet may scope, so "fpfs@c" works:
import { makePhaseCurve, PHASE_PARAMS, PHASE_FIELDS, toPhaseParams } from './phasecurve.js';
export const PLANET_FIELDS = ['rprs', ..., 'K', ...PHASE_FIELDS];
and add PHASE_PARAMS to PARAM_BY_KEY (and to activeParams with group: 'phase' when the fit
has spec.phase set). None of the keys collides with PARAMS, RV_PARAMS, MASS_PARAMS or
STAR_PARAMS today. If one ever does, rename it in PHASE_PARAMS only: every other place in
this file reads keys through PHASE_PARAMS / MAP_KEYS, apart from the literal property
names in resolvePhase() (one line each).
`pv[p]` in buildProblem needs the same fields: copy them with
for (const k of PHASE_FIELDS) q[k] = v[nm[k]];
2. Inside evaluate(), where the transit is compiled (the line `fluxes[p] = makeTransit(tp);`):
if (spec.phase) {
const pc = makePhaseCurve(toPhaseParams(q, tp, v), spec.phaseOpts); // q = pv[p], tp = transit params
if (!pc.ok) return null; // negative planet flux (or map, with phaseOpts.positiveMap): outside the prior
fluxes[p] = pc; // pc(t) = star x transit + planet, 1 + Fp/F* out of eclipse
} else fluxes[p] = makeTransit(tp);
Everything downstream is unchanged: exposure averaging calls fluxes[p](t) per sub-sample,
a1 (and per-epoch a1_s) is still integrated out, airmass still multiplies. pc(t) is the
system flux relative to the star alone, so a1 is the stellar flux, not the out-of-eclipse level.
With several planets model.js uses pc.two(t): flux = prod_p star_p(t) + sum_p planet_p(t), so the
star's light is counted once and no planet's light is dimmed by another planet's transit of the star.
Light-travel time is off unless spec.phaseOpts = { ltt: true }; it needs R* in solar radii, which
toPhaseParams copies from v.rstar (without it the delay is zero).
3. pieces(): `transit: tr` is now transit + planet. For plots use pc.parts(t), which returns
{ star, planet, visible, phase } per time.
What the session format (docs/FORMAT.md) lacks for this: a place to say the model is on
(`"phase": { "mode": "harmonic" | "map", "ltt": bool, "band": [lo, hi] }` at the top level is what
the example sessions in public/examples/phasecurve use; readers ignore unknown keys) and a
band per light curve (the planet's flux ratio and the limb darkening both depend on it).
Planet parameters already accept the extra keys.
=============================================================================
MODEL
F(t) = S(t) * T(t) + Fp(t) * V(t) relative to the star alone
T: transit (same kernel and limb darkening as transit.js). S = 1 unless the stellar terms are
used. Fp: planet flux over stellar flux. V: fraction of the planet's light that reaches the
observer (1 except behind the star). The orbit is the one the transit uses; phi is the orbital
angle from superior conjunction, phi = omega + nu + 90 deg, so phi = 0 at mid-eclipse and 180 deg
at mid-transit for every eccentricity (opts.phase = 'time' uses 2 pi (t - t_eclipse) / P instead,
which is what EXOTIC does; the two are the same for circular orbits).
Harmonic model (no map coefficients set), D = fpfs * rprs^2 the eclipse depth:
Fp(phi) = off + amp cos(phi + hotspot) + D [h2c (cos 2 phi - 1) + h2s sin 2 phi]
amp = D C / (2 - C + C cos hotspot), off = D (2 - C) / (2 - C + C cos hotspot), C = contrast
so that Fp(0) = D exactly, (max - min) / max = C for the first-order curve, and Fp >= 0 for
every C in [0, 1]. hotspot > 0 is an eastward hot spot: the curve peaks `hotspot` degrees of
phase before mid-eclipse. V is the uniform-disc occultation (exact lens area, any eccentricity).
EXOTIC (multi_fitter.phasecurve, joint_fitter.phasecurve):
1 + c0 + c1 cos(phi) + c2 sin(phi) + c3 cos(2 phi) + c4 sin(2 phi), c0 = D - c1 - c3
c1 = amp cos(hotspot) c2 = -amp sin(hotspot) c3 = D h2c c4 = D h2s
c0 = off - D h2c (harmonicCoefficients() does this)
Differences from EXOTIC, on purpose: (1) EXOTIC makes the eclipse with a transit of a body of
radius rprs sqrt(fpfs), so its ingress is sqrt(fpfs) times too short; here ingress lasts as long
as the planet's limb takes to cross the star's. (2) EXOTIC switches from the harmonic series to
a constant-depth eclipse where its eclipse model leaves 1, a step of Fp(phi_contact) - D; here Fp
is continuous and multiplied by V. (3) EXOTIC multiplies the planet's light by the transit; here
only the star is transited. (4) EXOTIC's phasecurve reads u1..u4 and calls the quadratic law with
four Claret coefficients; here limb darkening is the transit's (params.ldLaw, params.ld).
(5) c1, c2 free allow negative flux; contrast in [0, 1] cannot.
Stellar terms (second order in phase, not eclipsed, may have either sign), in ppm:
S = 1 - ellip 1e-6 (a/r)^3 cos(2 phi) - beam 1e-6 [cos(omega + nu) + e cos(omega)]
ellipsoidal: brightest at quadrature; beaming: brightest when the star approaches (a quarter
of an orbit after transit). beam is degenerate with hotspot in a single band, as c2 is.
Map model (any of y1m1 ... y33 set): the planet's brightness is
I(lat, lon) = I0 [1 + sum_lm y_lm Ylm(lat, lon)], lon east from the substellar point
with real spherical harmonics normalised as in starry (Luger et al. 2019): Y00 = 1,
Y10 = sqrt(3) * (cosine of the angle from the substellar point), Y11 = sqrt(3) * east,
Y1-1 = sqrt(3) * north, ... (table at MAP_BASIS). The planet keeps the same face to the star
(synchronous; for an eccentric orbit this is a map fixed to the star-planet line). I0 is set so
that the unocculted flux at phi = 0 is D = fpfs * rprs^2, as in the harmonic model.
Out of eclipse (Funk-Hecke): Fp = Dn [1 + (2/3) v.o + (1/4) o.Q.o], o the direction of the
observer in the planet's frame, v and Q the degree 1 and 2 parts of the map. Degree 3 is
invisible in the phase curve and visible only while the star's limb crosses the planet.
During ingress and egress the map is integrated over the part of the disc outside the star's
limb: ten moments of x^a y^b z^c over the lens, each a line integral (Green's theorem) with a
closed form on the planet's limb and 12 Gauss-Legendre nodes on the star's limb.
contrast and hotspot remain valid in map mode: they are turned into y10 and y11
(firstOrderToMap) and added to whatever y10, y11 are given.
Exoplanet-Mapping (fit_map.py, starry ydeg = 1, theta0 = 180): its parameters are in flux units,
y00 = Dn y10 = Dn * y10 y11 = Dn * y11 y1m1 = Dn * y1m1 (exoplanetMappingCoefficients())
with Dn = D / (1 + (2/sqrt 3)(y10 sin i + y1m1 cos i) + ...), y10 the day-night term, y11 the
hot-spot offset (east positive), y1m1 latitude. It interpolates precomputed starry curves on an
inclination grid; here the curves are computed at the sampled orbit.
Light-travel time (opts.ltt, needs params.rstar in R_sun): the planet is evaluated at
t' = t - [Z_transit - Z(t)] R* / c, so the transit stays at tmid and the eclipse arrives late by
(r_transit + r_eclipse) sin i / c: 2a/c for a circular orbit. lightTravelDelay() returns it:
50 s for a = 0.05 au, 13.5 s for WASP-43 b, 166 s for HD 80606 b (not the 460 s of 2a/c: its
eclipse is near periastron). One fixed-point step; the neglected term is under 0.05 s.Import: import { … } from './src/core/phasecurve.js' — no DOM, runs in Node and the browser.
RSUN_LIGHT_DAYS
const RSUN_LIGHT_DAYSDays light takes to cross one solar radius (IAU nominal R_sun = 695700 km).MAP_BASIS
const MAP_BASISReal spherical harmonics of the map, starry normalisation (each is Y_lm / Y_00), in the planet's frame: x east (longitude +90 deg on the equator), y north (the orbit normal), z toward the star (substellar point).
mapKeys
const mapKeysKeys of the map coefficients up to degree lmax (1 to 3).
MAP_KEYS
const MAP_KEYSNo description in the source.
PHASE_PARAMS
const PHASE_PARAMSParameter registry in the style of PARAMS in model.js, with a default prior for each (uniform over [prior.a, prior.b]) and the value a new fit starts from (def). All are planet-level keys: "fpfs" for the first planet, "fpfs@c" for planet c.
PHASE_FIELDS
const PHASE_FIELDSField names to append to PLANET_FIELDS in model.js.
PHASE_BY_KEY
const PHASE_BY_KEYNo description in the source.
toPhaseParams
function toPhaseParams(q, tp, v = {})Parameters for makePhaseCurve from model.js's objects: q = one planet's resolved values (pv[p], with
the phase fields copied in), tp = its transit parameters (toTransitParams), v = all values (for rstar).lensFraction
function lensFraction(d, R)Area common to a unit circle and a circle of radius R whose centre is d away, divided by pi.
visibleMoments
function visibleMoments(d, R, out)Moments of the visible part of the planet's disc, (1/pi) int x^a y^b z^c dA over the unit disc outside a
circle of radius R centred at (-d, 0), z = sqrt(1 - x^2 - y^2). Needs |R - d| < 1 (partial occultation).
out = [m000, m100, m200, m020, m300, m120, m001, m101, m201, m021]; odd powers of y vanish by symmetry.mapTensors
function mapTensors(y)Degree 1, 2 and 3 parts of the map as a vector, a symmetric matrix and a symmetric rank-3 tensor in the
planet's frame (east, north, substellar): I/I0 = 1 + v.b + b.Q.b + T(b, b, b).
y: object with any of the MAP_KEYS. Returns { v, Q (9), T (27) | null, lmax }.mapIntensity
function mapIntensity(y, latDeg, lonDeg)Brightness of the map relative to its uniform term at latitude and longitude (degrees, east from the substellar point).
mapMinimum
function mapMinimum(y)Smallest brightness of a map over the whole sphere, relative to its uniform term (negative: the map is unphysical).
Degree 1: 1 - |v| exactly. Degree 2: min of 1 + v.b + b.Q.b on |b| = 1, a trust-region problem solved exactly: with
Q = sum q_k e_k e_k^T (q ascending) and w_k = e_k.v, the minimiser is b = -sum w_k e_k / (2 (q_k - mu)) with the
multiplier mu < q_1 the root of sum w_k^2 / (4 (q_k - mu)^2) = 1 (bisection), or, when w_1 is too small for a root
(the "hard case"), that point plus the multiple of e_1 that puts it on the sphere. Degree 3: a 5 degree grid and a
pattern search from its lowest point. The whole sphere is tested, including the polar cap an inclined orbit never
turns toward the observer (latitudes beyond i from the visible pole: under 3 degrees for a transiting planet).firstOrderToMap
function firstOrderToMap(contrast, hotspotDeg, incDeg = 90)y10 and y11 that give a first-order phase curve with this contrast and hot-spot offset at inclination inc (deg):
1 + a cos(phi + hotspot), a = C / (2 - C). A map of degree 1 is non-negative only for C <= 0.8 at 90 deg.makePhaseCurve
function makePhaseCurve(params, opts = {})Compile a parameter set into a fast evaluator of the system flux relative to the star alone.
params: { rprs, per, tmid, ars, inc (deg), ecc, omega (deg), ldLaw, ld: [...], the transit's own
fpfs, contrast, hotspot (deg), h2c, h2s, ellip (ppm), beam (ppm), PHASE_PARAMS
y1m1, y10, y11, y2m2 ... y33, map coefficients (MAP_KEYS)
rstar (R_sun, only for light-travel time) }
opts: { phase: 'orbit' (default) | 'time', phase angle from the true anomaly, or linear in time as in EXOTIC
ltt: bool, light-travel delay of the planet's light (needs params.rstar)
map: bool, force the map model on or off (default: on when a y_lm is non-zero)
positiveMap: bool, ok = false when the map is negative anywhere (default: only flux is checked)
clamp: bool } false: let the planet's flux go negative instead of flooring it at 0 (basis curves)
Returns a function flux(t) with properties:
star(t) transit x stellar terms planet(t) planet flux reaching the observer
parts(t) { star, planet, visible (0..1), phase (rad from mid-eclipse) }
two(t, out) the same two numbers without an allocation: out[0] = star, out[1] = planet
phaseFlux(phi) unocculted planet flux at phase phi (rad), for a circular orbit at this inclination
depth fpfs rprs^2 tecl mid-eclipse time (with the delay when ltt)
lttDelay days the eclipse is late mode 'harmonic' | 'map'
minFlux smallest unocculted planet flux over the orbit (clamped to 0 in flux(t) if negative)
minIntensity smallest map brightness over the sphere relative to its mean (map mode and harmonic first order)
negative minFlux < 0 negativeMap minIntensity < 0
ok !negative (and !negativeMap with opts.positiveMap)
y, tensors the map coefficients in use (including those from contrast / hotspot)phaseCurveModel
function phaseCurveModel(times, params, out, opts = {})Evaluate the model on an array of times; opts.exptime (days) and opts.supersample average over each exposure.
makeEclipse
function makeEclipse(params, opts = {})Eclipse of a uniformly bright planet only (no phase variation): 1 + depth outside, 1 during totality.
lightTravelDelay
function lightTravelDelay(params)Days by which light-travel time delays mid-eclipse relative to mid-transit: (r_transit + r_eclipse) sin i R* / c.
harmonicCoefficients
function harmonicCoefficients(params)EXOTIC's c0..c4 for the harmonic model at these parameters (phase from mid-eclipse).
fromHarmonicCoefficients
function fromHarmonicCoefficients(c)The reverse: fpfs, contrast, hotspot, h2c, h2s from EXOTIC's { fpfs, rprs, c1, c2, c3, c4 }.
exoplanetMappingCoefficients
function exoplanetMappingCoefficients(params)Exoplanet-Mapping's flux-unit coefficients (y00, y10, y11, y1m1, ...) for these parameters.
basisCurves
function basisCurves(times, params, lmax = 2, opts = {})Light curve of each basis function at fixed orbit: what Exoplanet-Mapping tabulates with starry.
Returns { star: Float64Array (transit x stellar terms), keys: ['y00', ...], curves: { y00: uniform planet of unit
flux (1 outside eclipse), y10: flux of Y10 alone, ... } }. The system flux is
star + Dn (curves.y00 + sum y_lm curves.y_lm).solveMap
function solveMap(data, params, opts = {})Weighted linear least squares for the map coefficients at fixed non-linear parameters (orbit, rprs, limb darkening).
data: { t, f, e, epoch? } flux normalised to about 1 in every epoch; each epoch gets its own stellar level
opts: { lmax (default 2), keys (subset of the map keys to solve for), ridge (lambda: adds lambda * y_lm^2 / sigma_D^2-free
penalty in units of the fitted uniform term; default 0), ltt, phase }
Returns { fpfs, depth, y: { y10: ... }, yErr, depthErr, a1: [levels], chi2, dof, cov, keys, model: Float64Array,
rankDeficient, minIntensity, negativeMap, params (input params with fpfs and the y_lm filled in) }.
Degree 3 (and y1m1, y2m2, y2m1 for an edge-on orbit) is constrained only by points in ingress and egress.BANDS
const BANDSBand edges in micron (top-hat), the ranges Exoplanet-Mapping integrates over for IRAC.
planck
const planckPlanck function B_lambda (arbitrary constant factor) at wavelength in micron.
bandPlanck
function bandPlanck(T, band)Band-integrated Planck function (energy), by Simpson's rule. band: micron, [lo, hi], a name in BANDS, or { wl: [], resp: [] }.
brightnessTemperature
function brightnessTemperature(ratio, tstar, band)Brightness temperature: T with B_band(T) = ratio x B_band(tstar), ratio the planet's surface brightness over the
star's (fpfs, or flux ratio / rprs^2). The star is a blackbody at its effective temperature, as in Exoplanet-Mapping's
brightnessTemp. Returns NaN for a negative ratio, 0 for 0.heatRedistribution
function heatRedistribution({ tday, tnight, tstar, ars })Heat budget from dayside and nightside temperatures (Cowan & Agol 2011, ApJ 729, 54, eqs. 4 and 5):
T0 = T* / sqrt(a/R*) irradiation temperature at the substellar point
Td = T0 (1 - A_B)^(1/4) (2/3 - 5 eps / 12)^(1/4) Tn = T0 (1 - A_B)^(1/4) (eps / 4)^(1/4)
inverted: A_B = 1 - (3 Td^4 + 5 Tn^4) / (2 T0^4), eps = 8 Tn^4 / (3 Td^4 + 5 Tn^4).
Also Teq = T0 / sqrt(2) (zero albedo, full redistribution) and the dayside factor f of
Td = T0 [f (1 - A_B)]^(1/4) (Lopez-Morales & Seager 2007: 1/4 uniform, 2/3 no redistribution), here for A_B = 0.
These equate brightness temperature in one band with effective temperature: A_B < 0 means the band is brighter
than a blackbody in equilibrium could be.dayNightTemperatures
function dayNightTemperatures({ bondAlbedo, epsilon, tstar, ars })The forward relations: { tday, tnight } for a Bond albedo and redistribution efficiency.
temperatureMap
function temperatureMap(params, opts = {})Brightness and temperature of the planet on a latitude-longitude grid.
params as for makePhaseCurve (harmonic first order is drawn as its degree-1 map; h2c, h2s have no map).
opts: { tstar (K), band, nlat (default 45), nlon (default 90) }
Returns { lat[nlat], lon[nlon] (deg, cell centres, lon -180..180 east of the substellar point),
ratio: Float64Array(nlat*nlon) planet/star surface brightness (row = latitude from south),
temp: Float64Array | null (K; NaN where the map is negative), tmin, tmax,
hotspot: { lat, lon, temp, ratio } brightest point, negativeFraction (of the sphere's area), nlat, nlon }.phaseSummary
function phaseSummary(params, opts = {})Everything derived from a phase curve or map at given parameters.
opts: { tstar, band, ltt, phase, nphase (default 361) }
Returns {
depth, fday (flux ratio at phi = 0), fnight (phi = 180 deg), fmax, fmin, amplitude ((fmax - fmin) / 2),
contrast ((fmax - fmin) / fmax), phaseOfMax (deg from mid-eclipse, negative = before eclipse),
hotspotOffset (deg east: -phaseOfMax),
phase: Float64Array (deg, -180..180), flux: Float64Array (unocculted planet/star flux at each phase),
temp: Float64Array | null (disc-integrated brightness temperature the observer sees at each phase),
tday, tnight, tmaxPhase, tminPhase, T0, teq, bondAlbedo, epsilon (heatRedistribution),
map: temperatureMap(...) (hotspot.lon / .lat is the brightest point of the map, which differs from hotspotOffset),
lttDelay (days), mode, negative, negativeMap, minIntensity,
physical (flux >= 0 at every phase, and in map mode brightness >= 0 everywhere) }
opts.requirePositive: true -> the derived temperatures, albedo, redistribution and hot-spot numbers are NaN when the model is
not physical; 'map' -> also when the degree-1 map equivalent of a harmonic curve is negative somewhere.