Skip to content

src/core/observability.js ​

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

js
const AU_KM

No description in the source.

AU_LIGHT_DAYS ​

js
const AU_LIGHT_DAYS

Light-travel time over one astronomical unit, in days.

SIDEREAL_DEG_PER_DAY ​

js
const SIDEREAL_DEG_PER_DAY

Sidereal rate: degrees of Earth rotation per UT day.

jdFromDate ​

js
const jdFromDate

Julian date (UTC) of a JS Date or of milliseconds since the Unix epoch.

dateFromJd ​

js
const dateFromJd

JS Date of a Julian date (UTC).

ttMinusUtc ​

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

js
function gmst(jd)

Greenwich mean sidereal time in degrees (Meeus eq. 12.4) for a Julian date in UT.

gast ​

js
function gast(jd)

Greenwich apparent sidereal time in degrees: mean sidereal time plus the equation of the equinoxes.

lmst ​

js
const lmst

Local mean sidereal time in degrees at east longitude lon.

precess ​

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

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

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

js
function angularSeparation(ra1, dec1, ra2, dec2)

Angle between two directions on the sky, in degrees (Vincenty formula: good at all separations).

secz ​

js
const secz

Secant of the zenith distance. Infinity at or below the horizon.

airmass ​

js
const airmass

Relative optical air mass of Kasten & Young (1989, Appl. Opt. 28, 4735): 1 at the zenith, 38 at the horizon. NaN below the horizon.

refraction ​

js
const refraction

Atmospheric refraction in degrees to ADD to a geometric altitude (Saemundsson 1986, sea level, 10 C; Meeus eq. 16.4).

sunPosition ​

js
function sunPosition(jd)

Geocentric apparent position of the Sun: { ra, dec, dist [au], lon (apparent ecliptic longitude of date) }. Meeus ch. 25.

sunAltAz ​

js
function sunAltAz(jd, site)

Altitude and azimuth of the Sun from a site: { alt, az }.

moonPosition ​

js
function moonPosition(jd)

Geocentric apparent position of the Moon: { ra, dec, dist [km], lon, lat (ecliptic of date) }.

moonAltAz ​

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

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

js
const jdUtcToBjdTdb

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

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

js
function intersectIntervals(a, b)

Intersection of two sorted lists of [start, end] intervals.

sunCrossings ​

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

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

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

js
const noonBefore

The last local mean noon at or before jd for east longitude lon (the start of the "observing day").

upIntervals ​

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

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

js
const midTimeUncertainty

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

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

js
function eclipsePhase(ecc, omega)
text
Time from mid-transit to the next mid-eclipse as a fraction of the period, in (0, 1). 0.5 for e = 0.

eclipseLightDelay ​

js
function eclipseLightDelay(aAU, ecc = 0, omega = 90, inc = 90)
text
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 ​

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

js
const EVENT_KINDS

The event kinds the planner knows, in the order they are listed.

eventGeometry ​

js
function eventGeometry(tg, kind, o = {})
text
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 ​

js
function assessTransit(ingress, egress, intervals)
text
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 ​

js
function subtractIntervals(a, b)

The parts of the sorted interval list a that are not in the sorted list b.

assessRegion ​

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

js
function findObservableTransits(targets, site, opts)
text
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 ​

js
function findObservableEvents(targets, site, opts)
text
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 ​

js
function scoreTransit(ev, { minAlt = 30, baseline = 1 / 24 } = {})
text
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 ​

js
const _internals

No description in the source.

MIT licensed · Kyle A. Pearson