Oblate planet model

Oblate planet model#

OblatePlanetModel – also exported as OPModel – is the RoadRunner model for a planet whose sky projection is an ellipse rather than a circle.

Why oblateness matters#

A rapidly rotating planet is flattened at its poles. Saturn’s oblateness is about 0.1, Jupiter’s about 0.06. A flattened planet projected on the sky is an ellipse, and an ellipse crossing a limb-darkened disk produces a slightly different light curve than the circle of equal area: the difference is largest at ingress and egress, where the projected shape changes what is covered fastest.

The signal is small – tens of parts per million (Seager & Hui, 2002; Barnes & Fortney, 2003) – which is why the model offers several accuracy levels. At that amplitude the numerical error of the model itself is a real consideration, not a formality.

The planet’s projection is described by three parameters beyond the usual ones:

k

The projected semi-major axis in stellar radii, i.e. the radius ratio.

f

The flattening, \(f = (a - b)/a\), where \(a\) and \(b\) are the projected semi-major and semi-minor axes. Zero for a spherical planet.

alpha

The projected obliquity in radians, measured from the sky-plane x-axis – the direction of orbital motion at mid-transit – to the projected semi-major axis.

Accuracy levels#

Setting

Intersection areas

Limb darkening

default

θ-sampled scanlines

Mean intensity over an area-equivalent circle

exact_areas=True

Analytic ellipse-circle

Mean intensity over an area-equivalent circle

exact_ld=True

θ-sampled scanlines

Integrated over the exact elliptical footprint

both

Analytic ellipse-circle

Integrated over the exact elliptical footprint

The default is below the ppm level for a spherical planet, but its error grows roughly in proportion to the flattening and is concentrated at ingress and egress: about 30 ppm for \(f = 0.1\) and up to about 80 ppm for \(f = 0.3\). This is enough when the oblateness is a nuisance parameter, but not when it is the measurement; Oblate planet model compares the settings with the oblateness signal itself.

``exact_areas`` replaces the scanline intersection areas with an analytic ellipse-circle intersection algorithm accurate to machine precision, removing the geometric discretisation error but keeping the mean-intensity limb darkening approximation.

``exact_ld`` integrates the limb darkening over the planet’s exact elliptical footprint, which brings the model error below the ppm level for every tested geometry at roughly 25 times the cost of the default. Combined with exact_areas, the integration is also free of the scanline resolution floor.

Both can be set in the initialiser and overridden per call in evaluate, which makes it easy to run a fit with the fast settings and check the result with the accurate ones.

The scanline discretisation error falls as nlines**-2 in ordinary geometries and nlines**-1.5 in grazing ones; the annulus error of the exact-footprint integration falls as nannuli**-2.

Note

The accuracy levels are validated against direct numerical integration of the limb-darkened stellar disk in tests/test_opmodel.py.

Usage#

from numpy import pi, linspace
from pytransit import OPModel

time = linspace(-0.1, 0.1, 1000)

tm = OPModel('quadratic')
tm.set_data(time)

flux = tm.evaluate(k=0.1, f=0.1, alpha=0.3, ldc=[0.2, 0.1],
                   t0=0.0, p=1.0, a=3.0, i=0.5*pi)

# Check the result with the accurate settings
flux_exact = tm.evaluate(k=0.1, f=0.1, alpha=0.3, ldc=[0.2, 0.1],
                         t0=0.0, p=1.0, a=3.0, i=0.5*pi,
                         exact_areas=True, exact_ld=True)

API#

class pytransit.models.roadrunner.opmodel.OblatePlanetModel(ldmodel='quadratic', precompute_weights=None, klims=None, nk=None, nzin=None, nzlimb=None, zcut=None, ng=100, nlines=100, nthreads=1, small_planet_limit=0.05, exact_areas=False, exact_ld=False, nannuli=20, nz=None, nq=8, **kwargs)[source]#

Bases: RoadRunnerModel

Transit model for an oblate planet.

A RoadRunner-type transit model (Parviainen, 2020) for a planet whose sky projection is an ellipse with a semi-major axis k (in units of the stellar radius), flattening f, and projected obliquity alpha, rather than a circle. Planetary oblateness imprints signals of tens of ppm on the transit light curve (Seager & Hui, 2002; Barnes & Fortney, 2003), so the model offers several accuracy levels that can be chosen to match the precision needs:

  1. The default model calculates the planet-star intersection areas with a θ-sampled scanline method and approximates the limb darkening blocked by the planet with the mean intensity over the footprint of an area-equivalent circular planet. The model error is below the ppm level for a spherical planet but can reach tens of ppm for strongly oblate planets in grazing geometries.

  2. exact_areas replaces the scanline intersection areas with an analytic ellipse-circle intersection area algorithm that is accurate to machine precision. This removes the geometric discretization error but keeps the mean-intensity limb darkening approximation.

  3. exact_ld integrates the limb darkening over the planet’s exact elliptical footprint, which reduces the model error below the ppm level for all tested geometries at roughly 25 times the computational cost of the default model. Combined with exact_areas, the integration is also free of the scanline resolution floor.

The accuracy levels are validated against direct numerical integration of the limb-darkened stellar disk in the test suite (tests/test_opmodel.py).

The model follows the standard PyTransit API: initialize, call set_data to set the observation times (and optionally the light curve, passband, and epoch indices), and call evaluate to calculate the model fluxes. Any radially symmetric limb darkening model is supported.

__init__(ldmodel='quadratic', precompute_weights=None, klims=None, nk=None, nzin=None, nzlimb=None, zcut=None, ng=100, nlines=100, nthreads=1, small_planet_limit=0.05, exact_areas=False, exact_ld=False, nannuli=20, nz=None, nq=8, **kwargs)[source]#

Initialize the oblate planet transit model.

Parameters:

  • ldmodel – Limb darkening model: either the name of a built-in model (‘uniform’, ‘linear’, ‘quadratic’, ‘quadratic-tri’, ‘nonlinear’, ‘general’, ‘square_root’, ‘logarithmic’, ‘exponential’, ‘power-2’, or ‘power-2-pm’), a callable returning the stellar intensity profile as a function of µ, a tuple of callables returning the intensity profile and its integral over the stellar disk, or an LDModel instance.

  • precompute_weights – Precompute a 3D limb darkening weight table for the radius ratio range set by klims. Speeds up repeated evaluations at the cost of initialization time.

  • klims – Radius ratio limits (kmin, kmax) for the precomputed weight table.

  • nk – Radius ratio grid size for the precomputed weight table.

  • nz – Number of annuli the stellar disk is discretised into, uniform in the viewing angle and sampled at their area-weighted mean µ. This sets the resolution of the tabulated intensity profile used by all the model versions, including the profile interpolation in the exact-footprint limb darkening mode.

  • nzin – Deprecated; see RoadRunnerModel.

  • nzlimb – Deprecated; see RoadRunnerModel.

  • zcut – Deprecated; see RoadRunnerModel.

  • ng – Size of the grazing value table used by the mean limb darkening interpolation.

  • nlines – Number of scanlines used by the θ-sampled scanline planet-star intersection area calculation. The scanline discretization error decreases as nlines**-2 in ordinary transit geometries and as nlines**-1.5 in grazing geometries.

  • nthreads – Number of threads to use for the model computation. Values above one enable the parallel model version and set the numba thread count. The numba thread count is process-global, so the model created last defines the thread count for all models, and the value cannot exceed numba’s launch-time maximum (NUMBA_NUM_THREADS).

  • small_planet_limit – The radius ratio limit below which to use a small planet approximation.

  • exact_areas – Calculate the planet-star intersection areas using the exact analytic algorithm instead of the θ-sampled scanline approximation. The exact algorithm is accurate to machine precision but several times slower to evaluate. Can be overridden per call in evaluate.

  • exact_ld – Integrate the limb darkening over the planet’s exact elliptical footprint (a Stieltjes sum over nannuli stellar annuli with the annulus areas from the ellipse-disk intersection routine) instead of using the circular-footprint mean intensity approximation. Reduces the model error from tens of ppm to below the ppm level for strongly oblate planets at roughly 25 times the computational cost. When combined with exact_areas, the annulus areas are calculated with the exact analytic algorithm (slower, but free of the scanline resolution floor). Can be overridden per call in evaluate.

  • nannuli – Number of stellar annuli used by the exact-footprint limb darkening integration. The annulus discretization error decreases as nannuli**-2.

evaluate(k, f, alpha, ldc, t0, p, a, i, e=0.0, w=0.0, copy=True, exact_areas=None, exact_ld=None)[source]#

Evaluate the transit model for a set of scalar or vector parameters.

Parameters:

  • k – Radius ratio(s) either as a single float, 1D vector, or 2D array. The radius ratio gives the planet’s projected semi-major axis in units of the stellar radius. A 2D array should have a shape [npv, 1] or [npv, npb], where npv is the number of parameter vectors and npb the number of passbands, and allows for passband-dependent radius ratios.

  • f – Flattening(s) of the planet’s projection as a float or a 1D vector. The flattening, f = (a - b) / a, where a and b are the projected semi-major and semi-minor axes, ranges from 0 (spherical planet) to values below 1.

  • alpha – Projected obliquity (obliquities) of the planet in radians as a float or a 1D vector. The angle is measured from the x-axis of the sky plane (the direction of orbital motion at mid-transit) to the projected semi-major axis of the planet.

  • ldc – Limb darkening coefficients as a 1D or 2D array. For multiple parameter vectors with multiple passbands, the coefficients should be given as a 3D array with a shape [npv, npb, ncoef].

  • t0 – Transit center(s) as a float or a 1D vector.

  • p – Orbital period(s) as a float or a 1D vector.

  • a – Orbital semi-major axis (axes) divided by the stellar radius as a float or a 1D vector.

  • i – Orbital inclination(s) as a float or a 1D vector.

  • e (optional) – Orbital eccentricity as a float or a 1D vector.

  • w (optional) – Argument of periastron as a float or a 1D vector.

  • copy (optional) – Kept for compatibility with the PyTransit transit model API; currently unused.

  • exact_areas (optional) – Calculate the planet-star intersection areas using the exact analytic algorithm instead of the θ-sampled scanline approximation. If None (default), uses the value given in the model initializer.

  • exact_ld (optional) – Integrate the limb darkening over the planet’s exact elliptical footprint instead of using the circular-footprint mean intensity approximation. If None (default), uses the value given in the model initializer.

Returns:

ndarray – Modelled flux either as a 1D or 2D ndarray with a shape [npt] or [npv, npt], where npt is the number of time samples given in set_data.

Raises:

ValueError – If the radius ratios are given as a 2D array with a shape other than [npv, 1] or [npv, npb].

Notes

The model can be evaluated either for one set of parameters or for many sets of parameters simultaneously. In the first case, the orbital parameters should all be given as floats. In the second case, the orbital parameters should be given as a 1D array-like, and the fluxes are calculated for all the parameter vectors in one call (parallelized over the numba threads if the model was initialized with nthreads > 1).

The exact_areas and exact_ld arguments select the model accuracy level per call without touching the model defaults: for example, an MCMC run can sample with the fast default model and the posterior can be validated by re-evaluating the samples with exact_ld=True.