High-level Orbit class API

This page renders the full API of Orbit from its docstrings. See Orbit class overview for the conceptual tour and a quickstart, and Analytic parameter derivatives for the gradient math when the class is used in derivative mode.

class meepmeep.orbit.Orbit(npt: int = 15, ep_placement: str = 'ea', derivatives: bool = False, parallel: bool = False)

Bases: object

Evaluate Keplerian orbits at arbitrary times, with optional analytic gradients.

Bind a handful of orbital elements once via set_pars(), hand it a time grid via set_data(), and then ask for any of the quantities that exoplanet light-curve and radial-velocity modelling typically need: planet position, velocity, sky-projected separation, phase angle, radial velocity, reflected-light and thermal phase curves, ellipsoidal variation, light travel time. Construct with derivatives=True to additionally receive the analytic gradient of each quantity w.r.t. the seven orbital parameters (and any method-specific extras such as k or ag), which is what a gradient-based optimiser or HMC sampler wants.

Workflow: Orbit(npt, ep_placement, derivatives) → set_pars(tc=..., p=..., a=..., i=..., e=..., w=...) → set_data(times) → call any observable. Pass tp=... instead of tc=... to anchor the orbit at periastron passage instead of transit center.

Parameters:

nptint

Number of expansion points used by the multi-expansion-point Taylor expansion (default 15). Includes the periodic-image slot; raise this when the orbit is eccentric enough that 15 expansion points no longer cover periastron with adequate per-expansion-point accuracy.

ep_placementstr

Expansion point placement strategy: 'mm' (uniform in mean motion), 'ea' (uniform in eccentric anomaly; default and preferred for eccentric orbits), or 'ta' (uniform in true anomaly).

derivativesbool

If True, every evaluator method also returns parameter derivatives in addition to its value(s). The derivative ordering is (tc, p, a, i, e, w, lan) followed by per-method physical extras (e.g. k for radial_velocity(); ag, k for lambert_phase_curve(); k, fratio, offset for emission_phase_curve(); alpha, mass_ratio, inc for ellipsoidal_variation(); see the underlying *_od routines in meepmeep.backends.numba.orbit3dd for the full signatures).

The timing slot and the shape derivatives follow the timing parameter bound via set_pars(). Bind tc (the default) and slot 0 is \(\partial/\partial t_c\) with the e, w, p derivatives taken at constant tc; bind tp and the gradient is returned in the periastron basis (tp, p, a, i, e, w, lan) (constant tp). See the “Transit-centre vs periastron parametrisation” section of the derivatives documentation for the exact relationship.

With derivatives=True, multi-coordinate returns are extended with derivative arrays (e.g. xyz() returns (xs, ys, zs, dxs, dys, dzs) with each d*s of shape (N, 7)); single-value returns become (value, dvalue).

rstar derivatives for light_travel_time() are not returned (per package spec); only the seven orbital derivatives.

parallelbool

If True, evaluations over time arrays with at least _PARALLEL_NMIN_GRAD (gradient mode) or _PARALLEL_NMIN_VALUE (value mode) samples route to multi-threaded prange kernel twins; smaller arrays always take the serial kernels, which are faster below those sizes. The results are identical either way. Defaults to False: leave it off when the surrounding application already parallelises at a higher level (e.g. one process per MCMC chain), where nested thread pools oversubscribe the machine.

Attributes:

nptint

Number of expansion points, set at construction.

timesndarray or None

Time grid bound via set_data(). None until set.

_tcfloat

Transit-center time, set by set_pars() (directly if you pass tc, or derived from tp otherwise). Used by the Newton-Raphson diagnostic paths and by plot(show_exact=True)().

_tpfloat

Periastron-anchor time. Passed straight through to every orbit3d / orbit3dd dispatcher as their tpa argument. Set by set_pars() (directly if you pass tp, or derived from tc otherwise).

_timingstr

Which timing convention was last bound via set_pars(), "tc" (transit centre) or "tp" (periastron passage). In derivative mode it selects the gradient basis: "tp" triggers a reparametrisation of _dcoeffs into the periastron basis.

_coeffsndarray, shape (npt, 3, 5)

Taylor coefficient matrices at every expansion point, built in set_pars().

_dcoeffsndarray, shape (npt, 7, 3, 5) or None

Parameter-derivative coefficient tensors at every expansion point. None unless the instance was constructed with derivatives=True.

_ep_timesndarray, shape (npt,)

Normalised expansion-point phases in [0, 1] from create_expansion_points(). Built at construction for e = _EP_GRID_E_FLOOR and rebuilt by set_pars() when the bound eccentricity drifts more than _EP_GRID_E_TOL from the grid’s construction eccentricity ('ea'/'ta' placements only; the 'mm' grid is eccentricity-independent).

_grid_efloat

Eccentricity the current expansion-point grid was built for, max(e, _EP_GRID_E_FLOOR) at the last rebuild.

_dtfloat

Width of one _ep_table bucket in fraction of the period.

_ep_tablendarray of int

Time-to-expansion-point lookup table.

Notes

Convention bridge: this class accepts either tc (transit-center time) or tp (periastron-passage time) via set_pars(). The underlying orbit3d / orbit3dd dispatchers anchor their expansion-point grid at periastron, so set_pars() converts once via \(t_p = t_c - M_\mathrm{tr}(e, w) \cdot p / (2\pi)\) and stores both values: self._tc (transit center) and self._tp (periastron anchor). Every dispatcher call uses self._tp; self._tc is used only by the Newton-Raphson diagnostic paths (_xyz_error(), _cos_phase_error(), mean_anomaly(), true_anomaly(exact=True)()) and by plot(show_exact=True)().

set_data(times)

Bind a time grid to the instance.

The bound grid is used as the default times argument by every evaluator that takes a times=None parameter, and unconditionally by methods that don’t expose times at all (vxyz(), cos_phase(), phase(), theta(), light_travel_time(), radial_velocity()).

Parameters:

timesndarray, shape (N,)

Times at which to evaluate the orbit [days].

set_pars(*, tc=None, tp=None, p, a, i, e, w, lan=0.0)

Bind orbital parameters and (re-)compute the per-expansion-point Taylor coefficients.

The time anchor is specified by exactly one of tc (transit center) or tp (periastron passage); the two are related by \(t_p = t_c - M_\mathrm{tr}(e, w) \cdot p / (2\pi)\). Whichever is supplied, the other is derived and stored, so the diagnostic paths that need t_c (e.g. the Newton-Raphson reference) and the orbit3d / orbit3dd dispatchers that need t_pa are both satisfied from one call.

All parameters are keyword-only, so the call site always names the convention explicitly.

Parameters:

tcfloat, optional

Time of inferior conjunction (transit center) [days].

tpfloat, optional

Time of periastron passage [days].

pfloat

Orbital period [days].

afloat

Scaled semi-major axis \(a/R_\star\).

ifloat

Inclination [radians]. \(i = \pi/2\) is edge-on.

efloat

Eccentricity, \(0 \le e < 1\).

wfloat

Argument of periastron [radians].

lanfloat, optional

Longitude of the ascending node [radians]. A constant rotation of the sky-plane (x, y) coordinates about the line of sight; the line-of-sight (z) coordinate is unaffected. Defaults to 0.0. In derivative mode the gradient w.r.t. lan is returned as the seventh orbital-parameter column.

Raises:

TypeError

If both tc and tp are supplied, or if neither is.

Notes

After this call, self._tc holds the transit-center time and self._tp holds the periastron-anchor time, regardless of which input was used.

For the 'ea' and 'ta' expansion point placements the expansion-point grid is rebuilt when max(e, 0.2) differs from the eccentricity the current grid was built for by more than _EP_GRID_E_TOL, so the expansion points stay clustered near periastron as the bound orbit changes. Small eccentricity jitter (e.g. between MCMC steps) does not trigger a rebuild.

mean_anomaly()

Mean anomaly at every bound time, wrapped into \([0, 2\pi)\).

Computed analytically from self._tc (transit-center time) via the mean-anomaly-at-transit offset, so this method does not use the Taylor backend at all.

Returns:

mndarray, shape (N,)

Mean anomaly per time in radians, in \([0, 2\pi)\).

true_anomaly(exact: bool = False)

True anomaly at every bound time.

Parameters:

exactbool, default False

If True, use the Newton-Raphson reference solver (ta_newton_v()) instead of the Taylor backend. The exact path is meant for validation; it does not support parameter derivatives.

Returns:

fndarray, shape (N,)

True anomaly per time in radians, in \([0, 2\pi)\).

dfndarray, shape (N, 7)

Gradient w.r.t. (tc, p, a, i, e, w, lan). Only returned when self._derivatives is True (and exact is False).

Raises:

NotImplementedError

If exact=True is combined with derivatives=True; the Newton-Raphson reference does not produce parameter gradients.

xyz(times: ndarray | None = None)

Planet (x, y, z) position in the sky frame.

Parameters:

timesndarray or None

Times at which to evaluate the position. If None, uses the grid bound via set_data().

Returns:

xs, ys, zsndarray, shape (N,)

Position components in units of the stellar radius. xs, ys are the sky-plane coordinates; zs is the line-of-sight depth (positive toward the observer).

dxs, dys, dzsndarray, shape (N, 7)

Gradients w.r.t. (tc, p, a, i, e, w, lan). Only returned when self._derivatives is True.

vxyz()

Planet (vx, vy, vz) velocity in the sky frame.

Returns:

vxs, vys, vzsndarray, shape (N,)

Velocity components in \(R_\star/\mathrm{day}\).

dvxs, dvys, dvzsndarray, shape (N, 7)

Gradients w.r.t. (tc, p, a, i, e, w, lan). Only returned when self._derivatives is True.

cos_phase()

Cosine of the phase angle, \(\cos\alpha = -z/r\).

Equals +1 at superior conjunction (full phase, planet behind star) and -1 at inferior conjunction (new phase, planet in front).

Returns:

candarray, shape (N,)

Cosine of the phase angle per time, in \([-1, 1]\).

dcandarray, shape (N, 7)

Gradient w.r.t. (tc, p, a, i, e, w, lan). Only returned when self._derivatives is True.

phase()

Phase angle \(\alpha = \arccos(\cos\alpha)\).

Returns:

phndarray, shape (N,)

Phase angle per time in radians, in \([0, \pi]\). Zero at superior conjunction, \(\pi\) at inferior conjunction.

dphndarray, shape (N, 7)

Gradient w.r.t. (tc, p, a, i, e, w, lan). Only returned when self._derivatives is True.

Notes

When derivatives=True, the gradient is computed via the \(\arccos\) chain rule \(d\alpha/d\theta = -d\cos\alpha/d\theta / \sqrt{1 - \cos^2\alpha}\). At the transit/eclipse extrema \(|\cos\alpha| \to 1\) the derivative diverges; the implementation clamps \(\cos\alpha\) slightly inside (-1, 1) so the returned gradient stays finite but loses physical meaning at the clamped points.

theta()

Supplement angle \(\theta = \arccos(-\cos\alpha) = \pi - \alpha\).

Useful when the natural reference direction is the line from the star to the observer rather than the line from the planet to the observer.

Returns:

thndarray, shape (N,)

Supplement angle per time in radians, in \([0, \pi]\).

dthndarray, shape (N, 7)

Gradient w.r.t. (tc, p, a, i, e, w, lan). Only returned when self._derivatives is True.

Notes

See phase() for the derivative-clamping caveat near \(|\cos\alpha| = 1\).

star_planet_distance(times: ndarray | None = None)

3D star-planet separation \(r = \sqrt{x^2 + y^2 + z^2}\).

Distinct from projected separation() (currently only available through the low-level sep_o dispatcher), which drops the line-of-sight component.

Parameters:

timesndarray or None

Times at which to evaluate the separation. If None, uses the grid bound via set_data().

Returns:

rndarray, shape (N,)

3D star-planet separation per time, in stellar radii.

drndarray, shape (N, 7)

Gradient w.r.t. (tc, p, a, i, e, w, lan). Only returned when self._derivatives is True.

light_travel_time(rstar: float)

Light-travel-time correction, referenced to primary transit.

The correction is \(\mathrm{ltt}(t) = -(z(t) - z(t_\mathrm{transit})) \cdot r_\star \cdot (R_\odot/c)\) with \(z\) in stellar radii and the result in days. The reference is the primary transit, so ltt(t_transit) = 0.

Parameters:

rstarfloat

Stellar radius [R_sun].

Returns:

lttndarray, shape (N,)

Light travel time correction per time [days].

dlttndarray, shape (N, 7)

Gradient w.r.t. (tc, p, a, i, e, w, lan). Only returned when self._derivatives is True. The derivative w.r.t. rstar is intentionally not returned (per package spec).

radial_velocity(k: float)

Stellar radial velocity (Perryman 2018, Eq. 2.23).

Scales the line-of-sight planet velocity by the closed-form factor \(K / [(2\pi/p)\,(a\sin i)/\sqrt{1-e^2}]\) so the result is the observed stellar RV in m/s.

Parameters:

kfloat

Radial-velocity semi-amplitude [m s^-1].

Returns:

rvsndarray, shape (N,)

Radial velocity per time [m s^-1].

drvsndarray, shape (N, 8)

Gradient w.r.t. (tc, p, a, i, e, w, lan, k). Only returned when self._derivatives is True.

lambert_phase_curve(k: float, ag: float, times: ndarray | None = None)

Reflected-light phase curve assuming Lambertian scattering.

Evaluates \(F(t) = (k/r(t))^2\,A_g\,f(\alpha(t))\) with the Lambert kernel \(f(\alpha) = (\sin\alpha + (\pi - \alpha)\cos\alpha)/\pi\), using the instantaneous star-planet distance \(r(t)\) (in stellar radii) for the inverse-square illumination - exact for eccentric orbits, not just the circular case \(r = a\).

Parameters:

kfloat

Planet-to-star radius ratio \(R_p/R_\star\).

agfloat

Geometric albedo.

timesndarray or None

Times at which to evaluate the flux. If None, uses the grid bound via set_data().

Returns:

fluxndarray, shape (N,)

Reflected planet-to-star flux ratio per time.

dfluxndarray, shape (N, 9)

Gradient w.r.t. (tc, p, a, i, e, w, lan, ag, k). Only returned when self._derivatives is True.

emission_phase_curve(k: float, fratio: float, offset: float, times: ndarray | None = None)

Thermal-emission phase curve from a simple cosine model.

Evaluates \(F(t) = k^2\,f_\mathrm{ratio}\,(1 + \cos\delta\,c_z(t) + \sin\delta\,s(t))/2\), where \(c_z = -z/d\) is the cosine of the phase angle and \(s\) the signed in-plane component built from the orbital normal. The flux peaks at \(k^2 f_\mathrm{ratio}\) when the hotspot faces the observer; the offset \(\delta\) shifts the peak away from secondary eclipse, breaking the curve’s time symmetry.

Parameters:

kfloat

Planet-to-star radius ratio \(R_p/R_\star\).

fratiofloat

Dayside-to-nightside per-surface-element flux ratio, scaling the phase-curve amplitude so the peak-to-peak swing is \(k^2 f_\mathrm{ratio}\).

offsetfloat

Hotspot offset [radians].

timesndarray or None

Times at which to evaluate the flux. If None, uses the grid bound via set_data().

Returns:

fluxndarray, shape (N,)

Emitted planet-to-star flux ratio per time.

dfluxndarray, shape (N, 10)

Gradient w.r.t. (tc, p, a, i, e, w, lan, k, fratio, offset). Only returned when self._derivatives is True.

ellipsoidal_variation(alpha: float, mass_ratio: float, times: ndarray | None = None)

Ellipsoidal variation signal (Lillo-Box et al. 2014, Eqs. 6-10).

Relative flux variation induced by the tidally distorted primary as a function of orbital phase. The amplitude scales with the mass ratio, the projected-area factor \(\sin^2 i\), and the inverse cube of the instantaneous 3D star-planet separation.

Parameters:

alphafloat

Gravity-darkening coefficient.

mass_ratiofloat

Planet-to-star mass ratio \(M_p/M_\star\).

timesndarray or None

Times at which to evaluate the signal. If None, uses the grid bound via set_data().

Returns:

evndarray, shape (N,)

Relative flux variation due to ellipsoidal distortion.

devndarray, shape (N, 9)

Gradient w.r.t. (tc, p, a, i, e, w, lan, alpha, mass_ratio). Only returned when self._derivatives is True.

plot(figsize: tuple | None = None, show_exact: bool = False, sr: float = 1.0, pr: float = 0.5, pc='k', npt: int = 1000)

Diagnostic three-panel plot of the orbit geometry.

Renders front (X-Y), top (X-Z), and side (Z-Y) projections with the planet drawn at the first expansion point, the orbit traced over one full period, and arrows along the X-Z trace indicating the direction of motion. Temporarily rebinds self.times to a dense grid of npt samples for the plot and restores it on exit.

Parameters:

figsizetuple or None

Matplotlib figure size; passed to subplots.

show_exactbool, default False

If True, overlay the Newton-Raphson reference trajectory (xyz_newton_v) as a black dashed line in each panel.

srfloat, default 1.0

Stellar radius drawn at the origin [stellar radii]. Used only for the cosmetic stellar disc.

prfloat, default 0.5

Planet-marker radius [stellar radii]. Cosmetic only.

pcmatplotlib color, default "k"

Planet-marker face colour.

nptint, default 1000

Number of samples used to draw the orbit trace.

Returns:

None

The figure is rendered in-place; the function does not return the Figure / Axes handles.