orblet

Atoms for Keplerian orbit analysis. Forward models, likelihoods, design matrices and linear solves, period search, element conversion, plotting — each a function that takes arrays and returns a result, with its units, frames and assumptions stated in its docstring.

orblet is not a solver. It does not know what a Gaia epoch is, does not read files, and does not contact the network. You build the pipeline; orblet supplies the pieces.

from orblet import ti_design_matrix, linear_solve_ti, ti_to_kepler

X = ti_design_matrix(t_mjd, psi_rad, parallax_factor_al, P_days, e, tau, epoch_ref_mjd)
fit = linear_solve_ti(along_scan_mas, sigma_mas, X)
elements = ti_to_kepler({"A": fit.beta[0], "B": fit.beta[1], "F": fit.beta[2], "G": fit.beta[3]})

Install

pip install "orblet[all]"

To follow the repository instead of a release, install from GitHub:

pip install "orblet[all] @ git+https://github.com/saharsh1/orblet.git"

or from a local clone, which is the right choice while you are editing it:

git clone https://github.com/saharsh1/orblet.git
pip install -e "./orblet[all]"

Drop [all] for the four core dependencies only — numpy, scipy, astropy, matplotlib — which is all a fresh install needs to run the atoms and the quickstarts. The extras (emcee, corner, pandas, tqdm; also available one at a time as [sampling], [plots], [tables], [progress]) are each imported inside the one function that uses them, so a missing extra fails that call with a message naming it and leaves everything else working.

What is here

The front door — from orblet import <name> — exposes 35 names and imports nothing heavy: import orblet pulls in no scipy, no matplotlib, no astropy. Each name resolves on first use.

Conventions

Every public function states them in its docstring. The ones that bite:

• radial velocity: positive is receding; omega is the primary's argument of periastron
• period in days at the public surface (Keplerian years only inside the Kepler solver)
• tau is the periastron phase in [0, 1); tp = tau * P + epoch_ref_mjd
• astrometric amplitudes A, B, F, G are photocentre amplitudes in mas, positive-amplitude convention; the parallax term enters as parallax_mas * parallax_factor_al, additive
• Gaia's pmra is already mu_alpha* — never apply cos(dec) again
• a seed is initialisation, never a prior: a starting point for a sampler carries no evidence

Four laws, each a test

1. A public name is the object it claims to be — no silent wrappers.
2. The numerical core does not move: byte-identity baselines pin the forward models, the likelihoods and the design columns.
3. Conventions hold: RV sign, primary-frame ω, τ → tp, time scales.
4. orblet imports nothing outside itself, the four dependencies and the standard library.

Status

Grew inside the gaia-orbits repository until 2026-09-24; developed here since, and consumed there as an installed dependency.

Three simulator presets ship. OrbitSimulator.bh1_like() is the one the quickstarts use, through load_simulated_inputs(scenario="bh1"): an illustrative orbit on an invented sky position, with a cadence whose parallax factor is coupled to that position, so injecting and removing the parallax signal use the same array and closure is exact. toy_orbit() is a compact short-period orbit for quick smoke tests. bh3_like() carries orbital numbers rounded from a published system and is useful for a realistic-looking truth; pair it with DemoParallaxConsistentCadence for anything closure-grade. The scenario= parameter and the bh1/toy naming are slated to be simplified.

Licence

MIT.