src/core/observability.js
Where a target, the Sun and the Moon are in the sky of an observing site, when it is dark, and when a planet
transits. No DOM, no dependencies; everything the observation planner computes is here.
Conventions
times Julian dates in UTC (jdFromDate / dateFromJd convert to and from JS Dates) unless a name says BJD.
UT1 - UTC (below 0.9 s) is ignored.
angles degrees. Right ascension and declination of a target are ICRS / J2000 on input.
site { lat, lon, elev }: geodetic latitude (north positive), longitude (EAST positive), elevation in m.
azimuth from north through east (N = 0, E = 90). Altitudes are geometric: no refraction (refraction() gives it).
Methods and accuracy (measured against astropy in test/observability.test.mjs; the numbers are in the README):
stars IAU 1976 precession of the J2000 position to the date, mean sidereal time (Meeus 1998, chs. 12, 21).
Nutation and annual aberration (each up to 20") and proper motion are left out.
Sun Meeus ch. 25 low-accuracy theory (0.01 deg), apparent place.
Moon the largest terms of Meeus ch. 47 (ELP-2000/82 truncated), apparent place, with topocentric parallax.
BJD BJD_TDB <-> JD_UTC with the light-travel time to the Sun instead of the barycentre (the Sun is within
0.01 au of it: a few seconds) and TT - UTC from the leap-second table; TDB - TT (below 2 ms) is ignored.
There is an overlap with src/core/astro.js (written at the same time for the sky view); this module does not
depend on it so that the planner's numbers have one tested source.Import: import { … } from './src/core/observability.js' — no DOM, runs in Node and the browser.
AU_KM
const AU_KMNo description in the source.
AU_LIGHT_DAYS
const AU_LIGHT_DAYSLight-travel time over one astronomical unit, in days.
SIDEREAL_DEG_PER_DAY
const SIDEREAL_DEG_PER_DAYSidereal rate: degrees of Earth rotation per UT day.
jdFromDate
const jdFromDateJulian date (UTC) of a JS Date or of milliseconds since the Unix epoch.
dateFromJd
const dateFromJdJS Date of a Julian date (UTC).
ttMinusUtc
function ttMinusUtc(jd)TT - UTC in seconds at a Julian date (UTC): 32.184 s + the leap seconds. Dates after the last entry (2017) use 37 leap seconds.
gmst
function gmst(jd)Greenwich mean sidereal time in degrees (Meeus eq. 12.4) for a Julian date in UT.
gast
function gast(jd)Greenwich apparent sidereal time in degrees: mean sidereal time plus the equation of the equinoxes.
lmst
const lmstLocal mean sidereal time in degrees at east longitude lon.
precess
function precess(ra, dec, jd)Precess a J2000 position to the mean equator and equinox of the date (IAU 1976; Meeus eq. 21.2-21.4). Returns { ra, dec }.
horizontal
function horizontal(raDate, decDate, lst, lat)Altitude and azimuth of a position OF DATE at local sidereal time lst [deg] and latitude lat. Returns { alt, az, ha } (hour angle in degrees, west positive).
altAz
function altAz(ra, dec, jd, site)Altitude and azimuth of a J2000 target at a Julian date (UTC) from a site. Returns { alt, az, ha }.
angularSeparation
function angularSeparation(ra1, dec1, ra2, dec2)Angle between two directions on the sky, in degrees (Vincenty formula: good at all separations).
secz
const seczSecant of the zenith distance. Infinity at or below the horizon.
airmass
const airmassRelative optical air mass of Kasten & Young (1989, Appl. Opt. 28, 4735): 1 at the zenith, 38 at the horizon. NaN below the horizon.
refraction
const refractionAtmospheric refraction in degrees to ADD to a geometric altitude (Saemundsson 1986, sea level, 10 C; Meeus eq. 16.4).
sunPosition
function sunPosition(jd)Geocentric apparent position of the Sun: { ra, dec, dist [au], lon (apparent ecliptic longitude of date) }. Meeus ch. 25.
sunAltAz
function sunAltAz(jd, site)Altitude and azimuth of the Sun from a site: { alt, az }.
moonPosition
function moonPosition(jd)Geocentric apparent position of the Moon: { ra, dec, dist [km], lon, lat (ecliptic of date) }.
moonAltAz
function moonAltAz(jd, site)The Moon as seen from a site (topocentric: its parallax is up to a degree): { alt, az, ra, dec, dist [km] }. ra and dec are of date.
moonIllumination
function moonIllumination(jd)Illuminated fraction of the Moon's disc, 0 (new) to 1 (full), and whether it is waxing. Meeus eq. 48.1-48.3.
jdUtcToBjdTdb
const jdUtcToBjdTdbBJD_TDB of an event seen at JD (UTC) on Earth, for a target at J2000 ra, dec. Good to a few seconds (heliocentric light time).
bjdTdbToJdUtc
function bjdTdbToJdUtc(bjd, ra, dec)JD (UTC) at which an event with a given BJD_TDB is seen from the Earth. The inverse of jdUtcToBjdTdb.
intersectIntervals
function intersectIntervals(a, b)Intersection of two sorted lists of [start, end] intervals.
sunCrossings
function sunCrossings(jd0, jd1, site, alt)Times in [jd0, jd1] at which the Sun's altitude crosses alt degrees: [{ jd, rising }]. Sampled every 10 minutes and refined by bisection to better than a second.
darkIntervals
function darkIntervals(jd0, jd1, site, sunLimit = -18)Intervals within [jd0, jd1] during which the Sun is below sunLimit degrees (-18 astronomical night, the default; -12 nautical; -6 civil).
twilight
function twilight(jdNoon, site)Twilight for the night that contains or follows jd: the Sun's set and rise (-0.833 deg: refraction and semi-diameter) and the evening and morning ends of civil (-6), nautical (-12) and astronomical (-18) twilight, as Julian dates; null where the Sun does not cross that altitude within 36 hours of local noon. jdNoon is the local noon before the night (noonBefore(jd, lon) gives it).
noonBefore
const noonBeforeThe last local mean noon at or before jd for east longitude lon (the start of the "observing day").
upIntervals
function upIntervals(ra, dec, jd0, jd1, site, minAlt)Intervals within [jd0, jd1] during which a J2000 target is above minAlt degrees at a site. Analytic: the altitude depends on the hour angle only, and the hour angle advances at the sidereal rate.
upIntervalsHorizon
function upIntervalsHorizon(ra, dec, jd0, jd1, site, minAlt, horizon, step = 2 / 1440)upIntervals with a terrain horizon as well: the parts of [jd0, jd1] in which the target is above minAlt AND its apparent altitude (geometric + refraction()) is above horizon(az) degrees. horizon: a function of the azimuth in degrees (from north through east) giving the apparent altitude of the skyline, optionally with a max property (its highest value: where that is below minAlt the terrain cannot matter and the analytic intervals are returned). The crossings are found on a grid of step days (default 2 min) and refined by bisection to about 1 s; a skyline feature narrower than the grid step in time can be missed (a 2 min step is 0.5 deg of hour angle).
midTimeUncertainty
const midTimeUncertainty1-sigma uncertainty [days] of the mid-time n orbits after the reference epoch: sqrt(sigma_T0^2 + (n sigma_P)^2). Assumes T0 and P are uncorrelated.
transitsBetween
function transitsBetween(eph, t0, t1)Mid-transit times of a linear ephemeris inside [t0, t1], in the time scale of the ephemeris (normally BJD_TDB). eph: { per, tmid, perErr, tmidErr } in days. Returns [{ epoch, tmid, sigma }].
eclipsePhase
function eclipsePhase(ecc, omega)Time from mid-transit to the next mid-eclipse as a fraction of the period, in (0, 1). 0.5 for e = 0.eclipseLightDelay
function eclipseLightDelay(aAU, ecc = 0, omega = 90, inc = 90)Extra light-travel time of the eclipse relative to the transit [days]: the planet is on the far side of the star
at eclipse, so its light crosses the orbit (r at transit + r at eclipse, times sin i). aAU: semi-major axis in au.
2a/c for a circular edge-on orbit (about 40 s for a = 0.04 au).eclipseDurationRatio
function eclipseDurationRatio({ ecc = 0, omega = 90, ars, inc, rprs } = {})Eclipse duration (first to fourth contact) over transit duration. With the geometry (ars, inc, rprs) known: the ratio of Winn (2010) eq. 14 with eq. 16 for the eclipse (the impact parameter of the eclipse is that of the transit times (1 + e sin w) / (1 - e sin w)); 0 when the planet misses the star at eclipse. Without it: the speed ratio (1 + e sin w) / (1 - e sin w). 1 for a circular orbit.
EVENT_KINDS
const EVENT_KINDSThe event kinds the planner knows, in the order they are listed.
eventGeometry
function eventGeometry(tg, kind, o = {})Where one kind of event of a planet falls, relative to its linear transit ephemeris: { phase (of the centre,
fraction of the orbit after mid-transit), offset (extra days, light time), before, after (days from the centre to
the start and the end of the window), sigma(n) (1-sigma of the centre time n orbits after T0, days), baseline
(whether the out-of-event baseline applies), assumed (text: what had to be assumed, '' when nothing) } or null
when that event does not exist for this planet (no eclipse, period longer than the phase-curve limit).
tg { per, tmid, perErr, tmidErr, t14, ecc, eccErr, omega, omegaErr, ars, inc, rprs, a (au) }
kind 'transit' | 'eclipse' | 'phase' | 'custom'
o phase: { span (fraction of the orbit, default 0.5), center ('eclipse' | 'transit'), maxPer (days, default 3) }
custom: { from, to } (orbital phases; to < from wraps through the transit)
Eclipse timing: t = T0 + (n + phase) P + light delay. sigma^2 = sigma_T0^2 + ((n + phase) sigma_P)^2 +
(P dphase/de sigma_e)^2 + (P dphase/domega sigma_omega)^2, all taken as uncorrelated (e and omega are usually
correlated, so this overstates it when e is small). An eccentricity that is not catalogued is taken as 0; one
catalogued without omega is placed at phase 0.5 with sigma from e cos(omega) spread over all omega.assessTransit
function assessTransit(ingress, egress, intervals)How much of a transit, and of the baseline around it, falls inside a list of observable intervals
(dark AND above the altitude limit; sorted). Times in days.
coverage fraction of [ingress, egress] that is observable
ingress, egress whether each contact is observable
before, after observable time adjoining ingress / egress on the outside (0 if that contact is not observable)
start, end first and last observable moment of the run(s) touching the transit (null when none)subtractIntervals
function subtractIntervals(a, b)The parts of the sorted interval list a that are not in the sorted list b.
assessRegion
function assessRegion(start, end, dark, up)How much of a region of interest [start, end] can be observed, and what takes the rest away. dark, up: sorted interval lists (the Sun below its limit; the target above its altitude limit). Returns { fraction (0 to 1), observable: [[s, e]], lost: [{ start, end, why }], lostTwilight, lostAltitude (days) }. why is 'twilight' where the Sun is above its limit (whatever the altitude of the target then) and 'altitude' where it is dark but the target is below the limit; the lost pieces are in time order.
findObservableTransits
function findObservableTransits(targets, site, opts)Transits of a list of targets that can be observed from a site between two dates.
"Observable" is judged on the REGION OF INTEREST of a transit: from `baseline` before ingress to `baseline`
after egress (the out-of-transit flux on both sides is what a light-curve fit normalises against). A transit
is observable (`full`) when the whole region is dark and above the altitude limit.
targets [{ ra, dec (J2000 deg), per, tmid (BJD_TDB, days), perErr, tmidErr, t14 (duration, days), ... }]
site { lat, lon, elev }
opts jd0, jd1 window (JD UTC) in which the mid-transit must fall
minAlt lowest useful altitude of the target [deg] (default 30)
sunLimit the Sun must be below this altitude [deg] (default -18, the end of astronomical twilight)
baseline out-of-transit time wanted before ingress and after egress [days] (default 1 h)
include which transits to return:
'roi' (default) only those whose whole region of interest is observable
'transit' also those observable from ingress to egress with part of the baseline lost
'partial' also those of which only a part can be observed: the ingress or the egress
must be observable and at least minCoverage (default 0.25) of the duration
(partial: true is accepted for 'partial')
dark intervals of darkness covering the window, to reuse between calls (else computed here)
horizon optional terrain: azimuth (deg) -> apparent altitude of the skyline (deg), see
upIntervalsHorizon; the target must then be above both minAlt and the skyline
Returns events sorted by time: { target, epoch, mid, ingress, egress (JD UTC, corrected from BJD_TDB for the
light-travel time), bjd, sigma (1-sigma of the mid-time, days),
roiStart, roiEnd, roiCoverage (fraction of the region of interest that is observable), full (roiCoverage = 1),
lost: [{ start, end, why: 'twilight' | 'altitude' }], lostTwilight, lostAltitude (days),
coverage (fraction of ingress to egress that is observable), transitFull, ingressObs, egressObs,
before, after (observable time adjoining ingress and egress on the outside, days; can exceed the baseline),
obsStart, obsEnd, alt/az at ingress, mid and egress, airmass at mid, moon: { sep, illum, alt },
score (0-100, see scoreTransit) }.findObservableEvents
function findObservableEvents(targets, site, opts)Transits, secondary eclipses, phase-curve windows and custom phase windows, with the rules of
findObservableTransits (the same opts, plus):
kinds which events, any of EVENT_KINDS (default ['transit'])
phase { span, center, maxPer } and custom { from, to }: see eventGeometry
padSigma true: the region of interest also covers 1 sigma of the predicted time on each side (default false)
For a transit or an eclipse the region of interest is baseline + event + baseline; a phase window is its own region
of interest (no baseline). "ingress" and "egress" are the start and end of the window for every kind.
Each event also has kind, phase and assumed (see eventGeometry), baselineWanted (days) and pad (days added on each
side for the timing).scoreTransit
function scoreTransit(ev, { minAlt = 30, baseline = 1 / 24 } = {})A 0 to 100 figure of merit for how well a transit can be observed. It is a ranking aid, not a prediction of
photometric precision (it knows nothing about the telescope, the depth or the star's brightness):
50 x fraction of the transit that is observable
20 x fraction of the wanted baseline available, averaged over the two sides (full marks if none is wanted)
20 x altitude: 0 at the limit, 1 at 60 deg or higher, taken at the lowest of ingress / mid / egress that is observable
10 x Moon: 1 if it is down or farther than 40 deg, falling with proximity in proportion to its illuminated fraction
Returns { total, coverage, baseline, altitude, moon } with the four parts in points._internals
const _internalsNo description in the source.