High-level Expansion3D class API

This page renders the full API of Expansion3D from its docstrings. See Expansion3D 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.expansion3d.Expansion3D(tc: float, p: float, a: float, i: float, e: float, w: float, lan: float = 0.0, te: float = 0.0, derivatives: bool = False, parallel: bool = False)

Bases: object

High-level wrapper over the single-expansion-point 3D Taylor evaluators.

set_pars(*, tc: float, p: float, a: float, i: float, e: float, w: float, lan: float = 0.0)

Bind orbital elements and (re-)solve the single-expansion-point Taylor coefficients.

All parameters are keyword-only, so the call site always names the elements explicitly. The expansion-point time te is a construction-time constant and is reused on every call.

Parameters:

tcfloat

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

pfloat

Orbital period [days].

afloat

Scaled semi-major axis [R_star].

ifloat

Inclination [rad].

efloat

Eccentricity.

wfloat

Argument of periastron [rad].

lanfloat, optional

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

Notes

After this call, self._coeffs holds the (3, 5) coefficient matrix (and self._dcoeffs the (7, 3, 5) derivative tensor when the instance is in derivative mode), and self._ep_time holds the absolute time of the expansion point (tc + te).

set_data(times)

Bind a time grid evaluated by the per-quantity methods.

Parameters:

timesndarray, shape (N,)

Absolute observation times [days] at which the evaluation methods (position(), projected_separation(), …) evaluate the orbit.

position()

Planet (x, y, z) position at the times bound via set_data().

Returns:

tuple

(xs, ys, zs) if the instance was created with derivatives=False; (xs, ys, zs, dxs, dys, dzs) otherwise, where the gradients are shape (N, 7) arrays of partial derivatives with respect to (tc, p, a, i, e, w, lan). xs, ys are the sky-plane coordinates and zs the line-of-sight depth (positive toward the observer); all in units of the stellar radius.

z_position()

Line-of-sight (z) position at the times bound via set_data().

Returns:

zsndarray, shape (N,)

Line-of-sight depth per time (positive toward the observer), in units of the stellar radius. Returned alone if derivatives=False.

dzsndarray, shape (N, 7)

Only returned if derivatives=True: partial derivatives of zs with respect to (tc, p, a, i, e, w, lan).

projected_separation()

Sky-projected star-planet separation at the times bound via set_data().

The sky-projected separation between the centers of the star and planet, in units of the stellar radius.

Returns:

dndarray, shape (N,)

Projected separation per time, returned alone if derivatives=False.

ddndarray, shape (N, 7)

Only returned if derivatives=True: partial derivatives of d with respect to (tc, p, a, i, e, w, lan).

velocity()

Planet (vx, vy, vz) velocity at the times bound via set_data().

Returns:

tuple

(vxs, vys, vzs) if derivatives=False; otherwise (vxs, vys, vzs, dvxs, dvys, dvzs) with shape-(N, 7) gradients with respect to (tc, p, a, i, e, w, lan). Velocities are in units of stellar radii per day.

z_velocity()

Line-of-sight (z) velocity at the times bound via set_data().

Returns:

vzndarray, shape (N,)

Line-of-sight velocity per time, in units of stellar radii per day. Returned alone if derivatives=False.

dvzndarray, shape (N, 7)

Only returned if derivatives=True: partial derivatives of vz with respect to (tc, p, a, i, e, w, lan).

cos_phase()

Cosine of the orbital phase angle at the times bound via set_data().

\(\cos\alpha = -z / r\), equal to +1 at superior conjunction (full phase, planet behind the 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]\). Returned alone if derivatives=False.

dcandarray, shape (N, 7)

Only returned if derivatives=True: partial derivatives of ca with respect to (tc, p, a, i, e, w, lan).

radial_velocity(k: float)

Stellar radial velocity at the times bound via set_data().

Scales the planet’s line-of-sight velocity by the closed-form Perryman (2018, Eq. 2.23) factor so the result is the observed stellar RV.

Parameters:

kfloat

Radial-velocity semi-amplitude of the star, in physical velocity units (e.g. m/s); the output inherits these units.

Returns:

rvsndarray, shape (N,)

Radial velocity per time, in the units of k. Returned alone if derivatives=False.

drvsndarray, shape (N, 7)

Only returned if derivatives=True: partial derivatives of rvs with respect to (tc, p, a, i, e, w, lan).

Notes

The value-path 3D radial velocity has no dedicated parallel kernel (rv is scalar-inline and routes arrays through the zvel vector kernel), so value-mode evaluation ignores the parallel flag.

lambert_phase_curve(ag: float, k: float)

Reflected-light (Lambertian) phase curve at the times bound via set_data().

Parameters:

agfloat

Geometric albedo.

kfloat

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

Returns:

fluxndarray, shape (N,)

Reflected planet-to-star flux ratio per time. Returned alone if derivatives=False.

dfluxndarray, shape (N, 9)

Only returned if derivatives=True: partial derivatives of flux with respect to (tc, p, a, i, e, w, lan, ag, k).

ellipsoidal_variation(alpha: float, mass_ratio: float)

Ellipsoidal-variation signal at the times bound via set_data().

Relative flux variation induced by the tidally distorted primary (Lillo-Box et al. 2014). The orbital inclination is taken from the bound parameters and need not be passed.

Parameters:

alphafloat

Gravity-darkening coefficient.

mass_ratiofloat

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

Returns:

evndarray, shape (N,)

Relative flux variation per time. Returned alone if derivatives=False.

devndarray, shape (N, 9)

Only returned if derivatives=True: partial derivatives of ev with respect to (tc, p, a, i, e, w, lan, alpha, mass_ratio).

emission_phase_curve(k: float, fratio: float, offset: float)

Thermal-emission (cosine model) phase curve at the times bound via set_data().

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.

offsetfloat

Hotspot offset [radians], shifting the peak away from secondary eclipse.

Returns:

fluxndarray, shape (N,)

Emitted planet-to-star flux ratio per time. Returned alone if derivatives=False.

dfluxndarray, shape (N, 10)

Only returned if derivatives=True: partial derivatives of flux with respect to (tc, p, a, i, e, w, lan, k, fratio, offset).

duration(k: float, kind: int = 14) → float

Transit duration of the requested type [days].

Parameters:

kfloat

Planet-to-star radius ratio.

kindint, optional

Which duration to return: 14 (total, first-to-fourth contact; the default), 23 (full, second-to-third contact), 12 (ingress, first-to-second contact), or 34 (egress, third-to-fourth contact).

Returns:

float

The requested transit duration [days].

contact_point(k: float, point: int) → float

Absolute time of a transit contact point [days].

Parameters:

kfloat

Planet-to-star radius ratio.

pointint

Contact point, one of 1, 2, 3, or 4.

Returns:

float

Absolute time of the requested contact point.

bounding_box(k: float)

Absolute first- and fourth-contact times bracketing the transit.

Parameters:

kfloat

Planet-to-star radius ratio.

Returns:

tuple

(T1, T4) absolute contact times [days].

min_separation(guess: float = 0.0)

Locate the minimum projected separation near the expansion point.

Parameters:

guessfloat, optional

Initial guess for the time of minimum separation, as an offset in days from the expansion point. Defaults to 0.0 (the expansion point itself).

Returns:

t_minfloat

Absolute time of minimum projected separation [days].

z_minfloat

Projected separation at the minimum, in units of the stellar radius.