Skip to content

src/core/phasecurve.js ​

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

js
const RSUN_LIGHT_DAYS
text
Days light takes to cross one solar radius (IAU nominal R_sun = 695700 km).

MAP_BASIS ​

js
const MAP_BASIS

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

js
const mapKeys

Keys of the map coefficients up to degree lmax (1 to 3).

MAP_KEYS ​

js
const MAP_KEYS

No description in the source.

PHASE_PARAMS ​

js
const PHASE_PARAMS

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

js
const PHASE_FIELDS

Field names to append to PLANET_FIELDS in model.js.

PHASE_BY_KEY ​

js
const PHASE_BY_KEY

No description in the source.

toPhaseParams ​

js
function toPhaseParams(q, tp, v = {})
text
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 ​

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

js
function visibleMoments(d, R, out)
text
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 ​

js
function mapTensors(y)
text
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 ​

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

js
function mapMinimum(y)
text
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 ​

js
function firstOrderToMap(contrast, hotspotDeg, incDeg = 90)
text
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 ​

js
function makePhaseCurve(params, opts = {})
text
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 ​

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

js
function makeEclipse(params, opts = {})

Eclipse of a uniformly bright planet only (no phase variation): 1 + depth outside, 1 during totality.

lightTravelDelay ​

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

js
function harmonicCoefficients(params)

EXOTIC's c0..c4 for the harmonic model at these parameters (phase from mid-eclipse).

fromHarmonicCoefficients ​

js
function fromHarmonicCoefficients(c)

The reverse: fpfs, contrast, hotspot, h2c, h2s from EXOTIC's { fpfs, rprs, c1, c2, c3, c4 }.

exoplanetMappingCoefficients ​

js
function exoplanetMappingCoefficients(params)

Exoplanet-Mapping's flux-unit coefficients (y00, y10, y11, y1m1, ...) for these parameters.

basisCurves ​

js
function basisCurves(times, params, lmax = 2, opts = {})
text
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 ​

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

js
const BANDS

Band edges in micron (top-hat), the ranges Exoplanet-Mapping integrates over for IRAC.

planck ​

js
const planck

Planck function B_lambda (arbitrary constant factor) at wavelength in micron.

bandPlanck ​

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

js
function brightnessTemperature(ratio, tstar, band)
text
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 ​

js
function heatRedistribution({ tday, tnight, tstar, ars })
text
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 ​

js
function dayNightTemperatures({ bondAlbedo, epsilon, tstar, ars })

The forward relations: { tday, tnight } for a Bond albedo and redistribution efficiency.

temperatureMap ​

js
function temperatureMap(params, opts = {})
text
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 ​

js
function phaseSummary(params, opts = {})
text
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.

MIT licensed · Kyle A. Pearson