Skip to content

Architecture ​

index.html            landing page; plan/ observe/ analyze/ search/ validation/ each hold a page
src/site/             shared navigation bar and tokens
src/sky/ src/plan/ src/search/ src/photometry/ src/validation/   page code (DOM), one folder per page
src/main.js           the analyzer: state (S), panels, fit orchestration, undo, exports
src/core/             science, no DOM  ── importable from Node
  kepler.js           Kepler solver, orbit position, event times, contact durations
  limbdark.js         laws, conversions to Claret coefficients, validity
  transit.js          flux kernel (Green's theorem line integral) and light curve
  model.js            parameter registry, buildProblem() = the likelihood
  priors.js           unit-cube transforms
  nested.js           MiniNest sampler (MLFriends region, plateau handling, lnZ error)
  fitRunner.js        runs a fit in slices (worker or main thread)
  derive.js           system table quantities
  ldest.js            limb darkening from stellar parameters, tables, star-tied LD
  stellar.js          mass/radius from Teff, logg, [Fe/H]
  hz.js               habitable zone
  data.js             file reader, simulator, epochs (combine, remove, split by orbit, fold)
  config.js           priors to/from JSON and YAML
  rv.js               stellar reflex velocity, K, a/R* from Kepler's law
  catalog.js          archive snapshot reader: reference selection, physical checks, provenance, priors
  ephemeris.js        ephemeris fits to mid-transit times, epoch counting, timing-list reader
  stats.js            RNG, quantiles, special functions
  session.js          the session document (docs/FORMAT.md): validate, spec for buildProblem, headless runSession
  exportScript.js     a session as a Python script, a Markdown report, LaTeX tables
  phasecurve.js       the planet's own light: eclipse, phase curve, spherical-harmonic maps, temperatures
  exomoon.js          planet + moon transit, moon search
  nbody.js            Wisdom-Holman and IAS15 integrators, dynamical transit times and RVs, stability, perturber grid
  periodogram.js      generalised Lomb-Scargle for timing residuals; psd.js: power spectra and noise diagnostics
  astro.js observability.js horizon.js     sky positions, transit observability, terrain horizon
  fits.js photometry.js gp.js              images to light curves
  sources/ relations.js                    catalogue plug-ins, merging, gap-filling relations
  pyentry.js pyshim.js                     entry points of the Python bundle (tools/build_core_bundle.mjs)
src/assistant/        in-page assistant: tool table, handlers over window.__esl.api, the loop, the panel
mcp/                  MCP server: the same handlers on session documents
python/               the esl package: this core run from Python
src/worker/           Web Worker entries: fits, photometry frames, the N-body perturber grid
src/ui/               canvas plots, export (PNG/PDF/LaTeX/JSON), movie recorder, timingTab.js (first per-tab module)
src/viz/              three.js scene, GLSL, 2D fallback
src/data/             bundled datasets and tables
test/                 Node tests + headless-browser drivers
tools/                offline builders (limb darkening, catalogues, observatories, example results, Python bundle); tools/README.md
validation/           redirect to methods/#validation; the validation recipe is validation/README.md
methods/              Methods page: methods, validation, reproducibility, references, how to cite (src/methods/, src/validation/)

How a fit flows ​

startFit() builds a spec {data, values, ldLaw, free[{key, prior}], exptime, supersample, ldTie, sampler} → posted to fit.worker.js → runFit → buildProblem(spec) gives {transform, loglike} → MiniNest → weighted samples + lnZ back to finishFit(), which derives the system table on posterior draws.

Where new capability plugs in ​

CapabilityExtension point
Another light-curve component (eclipse, phase curve, moon)a module in src/core/ returning flux(t); multiply/add inside evaluate() in buildProblem
Several planetsloop makeTransit over a planets[] list in the spec; parameters become key@planet
Several datasets / instrumentsspec.datasets[], each with its own baseline, exposure, limb darkening band; sum lnL
Radial velocities, timing constraintsextra likelihood terms in buildProblem, sharing orbital parameters
New sampled parameteradd to PARAMS (or a new registry like STAR_PARAMS), give it a default prior in main.js
N-bodyreplace orbitPosition with an integrator behind the same position(t) interface
Heavy numericskeep the JS reference implementation and its test; add WASM behind the same function signature

The Timing tab is the pattern for per-tab modules: buildTimingTab(el, app) in src/ui/timingTab.js receives what it needs from main.js (S, h, pushUndo, rebuild, ...) and returns a redraw function.

Namespacing has started with the baseline: a dataset with several epochs carries epoch (index per point) and segments, and activeParams(ldLaw, [flags]) returns one airmass coefficient per epoch with key a2@n (epochKey, paramFor). Keys of the form name@scope are the convention to extend to planets and instruments.

State for several planets and datasets (src/main.js): S.planets lists { sfx, letter } and S.pl is the planet on show; all values, priors and free flags live in flat maps keyed name@scope (first planet unscoped, per@c, a2@3, jit@rv2). planetValues(values, sfx) turns that into the plain single-planet object that drawing and derived quantities use. Light-curve observations are the epochs of S.data; velocity datasets are S.rv; S.use says which kinds of data enter the fit. A "session" (src/ui/examples.js) is the plain description of a system and its data that applySession loads; examples and catalog look-ups both produce one.

Optional models hang off the same keys. A planet has its own light when fpfs (or fpfs@c) is defined, a moon when rmoon is; S.phase and spec.phase hold the options shared by the planets (mode, lmax, ltt, band). S.nbody / spec.nbody ({ epoch, linear, ... }) switches mid-transit times and velocities to an N-body integration. activeParams(..., { moons, phase }) lists their parameters in groups moon and phase.

Plot views other than the light curve go through plotFor(view) in main.js, which returns { data, render(ctx, W, H, data, theme, opts) }; the screen, the exported figure and the movie all draw that, and data.setTime(t) moves a figure's time cursor. Per-tab modules receive an app object: buildTimingTab and buildDynamics (src/ui/dynamics.js) are the pattern.

window.__esl.api (createAPI(app) in src/ui/api.js, wrapped by makeAPI() in main.js; describe() lists every call) is the scripted surface of the analyzer, used by the headless checks, the stored-results builder and the assistant.

src/main.js is about 2,100 lines. The split still to do: state and undo; session import/export; one module per tab (System, Data, Fit, Results) on the pattern above; plot views.

MIT licensed · Kyle A. Pearson