PyTransit 2.10.0__tar.gz → 2.10.1__tar.gz

{pytransit-2.10.0 → pytransit-2.10.1}/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [2.10.1] - 2026-10-20
+
+### Added
+
+- `GravityDarkenedModel.evaluate`, the supported replacement for the deprecated `evaluate_ps`. It also accepts a
+  scalar `k` and a list `ldc`.
+
+### Changed
+
+- **Breaking**: The `GravityDarkenedModel` default resolution is now `sres=160, pres=20` (was `sres=80, pres=5`),
+  reducing the model error from about 165 ppm to 30-50 ppm at about five times the cost.
+
+### Fixed
+
+- `GravityDarkenedModel` computing the planet-star overlap as if the flattened star were circular, which delayed the
+  contacts of paths crossing near the stellar poles and gave errors of up to ~300 ppm for misaligned orbits.
+- `GravityDarkenedModel.evaluate_brute(plot=True)` drawing the star upside down relative to the planet's path.
+
 ## [2.10.0] - 2026-10-19
 
 ### Changed

{pytransit-2.10.0 → pytransit-2.10.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyTransit
-Version: 2.10.0
+Version: 2.10.1
 Summary: Fast and painless exoplanet transit light curve modelling.
 Author-email: Hannu Parviainen <hpparvi@gmail.com>
 License: GPLv2

{pytransit-2.10.0 → pytransit-2.10.1}/PyTransit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyTransit
-Version: 2.10.0
+Version: 2.10.1
 Summary: Fast and painless exoplanet transit light curve modelling.
 Author-email: Hannu Parviainen <hpparvi@gmail.com>
 License: GPLv2

{pytransit-2.10.0 → pytransit-2.10.1}/PyTransit.egg-info/SOURCES.txt

@@ -38,9 +38,13 @@ docs/source/installation.rst
 docs/source/io.rst
 docs/source/stars.rst
 docs/source/_figures/__init__.py
+docs/source/_figures/chromosphere.py
 docs/source/_figures/dataset_arrays.py
+docs/source/_figures/gdmodel.py
 docs/source/_figures/highlights.py
+docs/source/_figures/opmodel.py
 docs/source/_figures/roadrunner.py
+docs/source/_figures/rr_benchmark.py
 docs/source/_figures/tsmodel.py
 docs/source/_static/.gitkeep
 docs/source/api/deprecated.rst
@@ -261,8 +265,10 @@ pytransit/utils/io/rvdata.py
 tests/__init__.py
 tests/conftest.py
 tests/reference_flux.npz
+tests/test_chromosphere_model.py
 tests/test_contamination.py
 tests/test_ecintersection.py
+tests/test_gdmodel.py
 tests/test_lcdata.py
 tests/test_limb_darkening.py
 tests/test_lpf_plotting.py

{pytransit-2.10.0 → pytransit-2.10.1}/PyTransit.egg-info/scm_file_list.json

@@ -17,9 +17,13 @@
     "docs/Makefile",
     "docs/requirements.txt",
     "docs/source/_figures/__init__.py",
+    "docs/source/_figures/chromosphere.py",
     "docs/source/_figures/dataset_arrays.py",
+    "docs/source/_figures/gdmodel.py",
     "docs/source/_figures/highlights.py",
+    "docs/source/_figures/opmodel.py",
     "docs/source/_figures/roadrunner.py",
+    "docs/source/_figures/rr_benchmark.py",
     "docs/source/_figures/tsmodel.py",
     "docs/source/_static/.gitkeep",
     "docs/source/api/deprecated.rst",
@@ -254,8 +258,10 @@
     "tests/__init__.py",
     "tests/conftest.py",
     "tests/reference_flux.npz",
+    "tests/test_chromosphere_model.py",
     "tests/test_contamination.py",
     "tests/test_ecintersection.py",
+    "tests/test_gdmodel.py",
     "tests/test_lcdata.py",
     "tests/test_limb_darkening.py",
     "tests/test_lpf_plotting.py",

pytransit-2.10.1/PyTransit.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "2.10.1",
+  "distance": 0,
+  "node": "g230da4937d7622270a55295e5691517aef9c6444",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-10-20"
+}

pytransit-2.10.1/docs/source/_figures/chromosphere.py

@@ -0,0 +1,129 @@
+#  PyTransit: fast and easy exoplanet transit modelling in Python.
+#  Copyright (C) 2010-2026  Hannu Parviainen
+#
+#  This program is free software: you can redistribute it and/or modify
+#  it under the terms of the GNU General Public License as published by
+#  the Free Software Foundation, either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License
+#  along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+"""Plotting helpers for the chromosphere feature page.
+
+The page is about a limb-brightened stellar disk, so the figures show its intensity profile beside
+the transit it produces, and how far the best limb darkening laws fall from reproducing it.
+"""
+
+from matplotlib.pyplot import subplots, setp
+from numpy import arccos, linspace, sqrt
+from scipy.optimize import least_squares
+
+from pytransit import RoadRunnerModel
+
+__all__ = ['plot_profiles_and_transits', 'plot_limb_darkening_fits']
+
+P, A = 4.0, 13.0
+
+
+def _despine(ax):
+    ax.spines['top'].set_visible(False)
+    ax.spines['right'].set_visible(False)
+
+
+def plot_profiles_and_transits(time, fluxes, ldc):
+    """Draw the shell, uniform, and quadratic intensity profiles beside the transits they produce.
+
+    The profiles are normalised to the same disk-integrated flux, so that they compare the
+    distribution of the light rather than its total.
+
+    Parameters
+    ----------
+    time : ndarray
+        The mid-exposure times the fluxes were computed for.
+    fluxes : dict
+        The fluxes for the keys 'shell', 'uniform', and 'quadratic'.
+    ldc : list
+        The quadratic limb darkening coefficients the quadratic flux was computed with.
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+    """
+    r = linspace(0.0, 0.995, 500)
+    mu = sqrt(1.0 - r ** 2)
+    u1, u2 = ldc
+    profiles = {'shell': 0.5 / mu,
+                'uniform': 1.0 + 0.0 * mu,
+                'quadratic': ((1.0 - u1 * (1.0 - mu) - u2 * (1.0 - mu) ** 2)
+                              / (1.0 - u1 / 3.0 - u2 / 6.0))}
+    labels = {'shell': 'Optically thin shell', 'uniform': 'Uniform disk',
+              'quadratic': 'Limb-darkened photosphere'}
+    styles = {'shell': dict(c='k'), 'uniform': dict(c='0.6', ls=':'),
+              'quadratic': dict(c='C0', ls='--')}
+
+    fig, (al, ar) = subplots(1, 2, figsize=(9, 3.6))
+    for key in ('shell', 'uniform', 'quadratic'):
+        al.plot(r, profiles[key], label=labels[key], **styles[key])
+        ar.plot(24 * time, fluxes[key], label=labels[key], **styles[key])
+    setp(al, xlabel='Distance from disk centre $z$ [$R_\\star$]', ylabel='Relative intensity',
+         ylim=(0, 3),
+         title='Intensity profile')
+    setp(ar, xlabel='Time - $t_c$ [h]', ylabel='Normalised flux', title='Resulting transit')
+    ar.autoscale(axis='x', tight=True)
+    al.legend(fontsize='small', frameon=False, loc='upper left')
+    _despine(al)
+    _despine(ar)
+    fig.tight_layout()
+    return fig
+
+
+def _best_fit(time, flux, law, ldc0):
+    """The best fit of a limb-darkened transit to `flux`, with every parameter free.
+
+    The limb darkening coefficients have wide bounds, so a law is free to brighten towards the limb
+    as far as its functional form allows.
+    """
+    tm = RoadRunnerModel(law)
+    tm.set_data(time)
+    n = len(ldc0)
+
+    def residuals(x):
+        k, a, b, t0 = x[:4]
+        return tm.evaluate(k, x[4:], t0, P, a, arccos(b / a)) - flux
+
+    bounds = ([0.03, 3.0, 0.0, -0.01] + [-50.0] * n, [0.3, 40.0, 0.95, 0.01] + [50.0] * n)
+    best = None
+    for bs in (0.05, 0.3, 0.5):
+        fit = least_squares(residuals, [0.1, A, bs, 0.0] + list(ldc0), bounds=bounds, x_scale='jac',
+                            xtol=1e-14, ftol=1e-14)
+        if best is None or fit.cost < best.cost:
+            best = fit
+    return best.fun
+
+
+def plot_limb_darkening_fits(time, flux):
+    """Draw the residuals left when limb darkening laws are fitted to a limb-brightened transit.
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+    """
+    laws = {'quadratic': [-0.3, 0.0], 'power-2': [-0.5, 1.0], 'nonlinear': [0.0, 0.0, 0.0, -0.5]}
+    fig, ax = subplots(figsize=(9, 3.4))
+    for law, ldc0 in laws.items():
+        residual = -_best_fit(time, flux, law, ldc0)            # data minus model
+        ax.plot(24 * time, 1e6 * residual, label=f"'{law}'")
+    ax.axhline(0.0, c='0.8', lw=0.5, zorder=-1)
+    setp(ax, xlabel='Time - $t_c$ [h]', ylabel='Shell - best fit [ppm]',
+         title='Residuals of the best-fitting limb-darkened transits')
+    ax.autoscale(axis='x', tight=True)
+    ax.legend(fontsize='small', frameon=False, loc='lower center', ncols=3)
+    _despine(ax)
+    fig.tight_layout()
+    return fig

pytransit-2.10.1/docs/source/_figures/gdmodel.py

@@ -0,0 +1,126 @@
+#  PyTransit: fast and easy exoplanet transit modelling in Python.
+#  Copyright (C) 2010-2026  Hannu Parviainen
+#
+#  This program is free software: you can redistribute it and/or modify
+#  it under the terms of the GNU General Public License as published by
+#  the Free Software Foundation, either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License
+#  along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+"""Plotting helpers for the gravity-darkened star feature page.
+
+The page is about what a gravity-darkened star does to a transit that an ordinary limb-darkened
+star cannot. The figure therefore shows the stellar disk with the planet's path beside the
+residuals left after fitting a standard transit model.
+"""
+
+from math import cos, sin
+
+from matplotlib.pyplot import subplots, setp
+from numpy import arccos, atleast_2d, degrees, nanmax
+from scipy.optimize import least_squares
+
+from meepmeep.backends.numba.point2d import solve2d
+
+from pytransit import RoadRunnerModel
+from pytransit.models.numba.gdmodel import create_star_luminosity, create_star_xy, map_osm, xy_taylor_vt
+
+__all__ = ['plot_gravity_darkening_signal']
+
+
+def _despine(ax):
+    ax.spines['top'].set_visible(False)
+    ax.spines['right'].set_visible(False)
+
+
+def _standard_fit(time, flux, p, a0):
+    """The light curve of the best-fitting spherical, limb-darkened star.
+
+    The radius ratio, scaled semi-major axis, impact parameter, transit centre, and quadratic limb
+    darkening coefficients are all free, so whatever remains is what gravity darkening adds.
+    """
+    tm = RoadRunnerModel('quadratic')
+    tm.set_data(time)
+
+    def residuals(x):
+        k, a, b, t0, u1, u2 = x
+        return tm.evaluate(k, [u1, u2], t0, p, a, arccos(b / a)) - flux
+
+    bounds = ([0.03, 2.0, 0.0, -0.01, -1.0, -1.0], [0.3, 20.0, 0.95, 0.01, 2.0, 2.0])
+    best = None
+    for bs in (0.05, 0.3, 0.5, 0.7):
+        fit = least_squares(residuals, [0.1, a0, bs, 0.0, 0.3, 0.2], bounds=bounds, x_scale='jac',
+                            xtol=1e-14, ftol=1e-14)
+        if best is None or fit.cost < best.cost:
+            best = fit
+    return flux + best.fun          # `fun` is the model minus the data
+
+
+def _draw_star(ax, tm, time, rho, rperiod, tpole, phi, beta, ldc, t0, p, a, i, l, res=300):
+    """Draw the gravity-darkened stellar disk and the planet's path, as `evaluate` sees them."""
+    mstar, ostar, gpole, f, feff = map_osm(tm.rstar, rho, rperiod, phi)
+    st, sx, sy = create_star_xy(res)
+    image = create_star_luminosity(res, sx, sy, mstar, tm.rstar, ostar, tpole, gpole, f, sin(phi),
+                                   cos(phi), beta, atleast_2d(ldc), tm._flux_table, tm._teff0,
+                                   tm._dteff, tm.accurate_mu)[0]
+    ax.imshow(image / nanmax(image), extent=(-1, 1, -1, 1), origin='lower', cmap='inferno',
+              vmin=0.4, vmax=1.0)
+    px, py = xy_taylor_vt(time - t0, l, solve2d(0.0, p, a, i, 0.0, 0.0))
+    ax.plot(px, py, c='w', lw=1, ls='--')
+    # An arrowhead where the path leaves the star shows the direction of motion.
+    j = max(n for n in range(px.size) if px[n] ** 2 + py[n] ** 2 < 1.0)
+    ax.annotate('', xy=(px[j], py[j]), xytext=(px[j - 15], py[j - 15]),
+                arrowprops=dict(arrowstyle='-|>', color='w', lw=1))
+    setp(ax, xlim=(-1.15, 1.15), ylim=(-1.15, 1.15))
+    ax.set_aspect('equal')
+    ax.axis('off')
+
+
+def plot_gravity_darkening_signal(time, fluxes, models, rho, rperiod, tpole, phi, beta, ldc,
+                                  t0, p, a, i):
+    """Draw the stellar disk and the residuals of a standard transit model fit for several orbits.
+
+    Parameters
+    ----------
+    time : ndarray
+        The mid-exposure times the fluxes were computed for.
+    fluxes : dict
+        Mapping from ``(band, l)`` to the modelled flux, where `band` names a passband and `l` is
+        the projected spin-orbit angle in radians.
+    models : dict
+        Mapping from the passband names to the `GravityDarkenedModel` instances used. The stellar
+        disk is drawn in the first passband.
+    rho, rperiod, tpole, phi, beta, ldc, t0, p, a, i
+        The parameters the fluxes were computed with.
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+    """
+    bands = list(models)
+    ls = sorted({l for _, l in fluxes})
+    colours = {'blue': 'C0', 'red': 'C3'}
+
+    fig, axs = subplots(2, len(ls), figsize=(9, 5.4), height_ratios=(2, 3), sharey='row')
+    for l, at, ab in zip(ls, axs[0], axs[1]):
+        _draw_star(at, models[bands[0]], time, rho, rperiod, tpole, phi, beta, ldc, t0, p, a, i, l)
+        at.set_title(f'$\\lambda$ = {degrees(l):.0f}°')
+        for band in bands:
+            flux = fluxes[band, l]
+            residual = flux - _standard_fit(time, flux, p, a)
+            ab.plot(24 * time, 1e6 * residual, c=colours.get(band), label=band)
+        ab.axhline(0.0, c='0.8', lw=0.5, zorder=-1)
+        ab.autoscale(axis='x', tight=True)
+        setp(ab, xlabel='Time - $t_c$ [h]')
+        _despine(ab)
+    setp(axs[1, 0], ylabel='Residual of a standard fit [ppm]')
+    axs[1, 0].legend(fontsize='small', frameon=False, loc='lower left')
+    fig.tight_layout()
+    return fig

pytransit-2.10.1/docs/source/_figures/opmodel.py

@@ -0,0 +1,204 @@
+#  PyTransit: fast and easy exoplanet transit modelling in Python.
+#  Copyright (C) 2010-2026  Hannu Parviainen
+#
+#  This program is free software: you can redistribute it and/or modify
+#  it under the terms of the GNU General Public License as published by
+#  the Free Software Foundation, either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License
+#  along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+"""Plotting helpers for the oblate planet feature page.
+
+The page is about how small the oblateness signal is, how much of it a spherical planet can absorb,
+and how accurate the model must be to see the rest. The figures therefore compare an oblate planet
+with the best-fitting spherical one, and the model accuracy settings with a direct numerical
+integration of the stellar disk.
+"""
+
+import warnings
+from math import cos, sin, sqrt
+
+from matplotlib.patches import Circle, Ellipse
+from matplotlib.pyplot import subplots, setp
+from numpy import abs as npabs, arccos, arcsin, array, degrees, linspace, pi
+from scipy.integrate import IntegrationWarning, quad
+from scipy.optimize import least_squares
+
+from meepmeep.backends.numba.point2d import pos_c, solve2d
+
+from pytransit import OPModel, RoadRunnerModel
+
+__all__ = ['plot_oblateness_signal', 'plot_accuracy_levels']
+
+# The example transit used throughout the page: a Saturn-like planet on a ten-day orbit.
+P, A = 10.0, 15.0
+LDC = (0.4, 0.25)
+
+
+def _despine(ax):
+    ax.spines['top'].set_visible(False)
+    ax.spines['right'].set_visible(False)
+
+
+def _sphere_fit(time, flux, k0, ldc):
+    """The spherical planet that best reproduces a light curve, with the limb darkening fixed.
+
+    The radius ratio, scaled semi-major axis, impact parameter, and transit centre are free. The
+    fit starts from several impact parameters, since an elongated planet can mimic a spherical one
+    on a quite different chord.
+    """
+    tm = RoadRunnerModel('quadratic')
+    tm.set_data(time)
+
+    def residuals(x):
+        k, a, b, t0 = x
+        return tm.evaluate(k, ldc, t0, P, a, arccos(b / a)) - flux
+
+    bounds = ([0.5 * k0, 5.0, 0.0, -0.01], [2 * k0, 40.0, 0.95, 0.01])
+    best = None
+    for bs in (0.05, 0.3, 0.5, 0.7, 0.85):
+        fit = least_squares(residuals, [k0, A, bs, 0.0], bounds=bounds, x_scale='jac',
+                            xtol=1e-15, ftol=1e-15, gtol=1e-15)
+        if best is None or fit.cost < best.cost:
+            best = fit
+    return tm.evaluate(best.x[0], ldc, best.x[3], P, best.x[1], arccos(best.x[2] / best.x[1]))
+
+
+def _draw_geometry(ax, b, alpha, k=0.3, f=0.3):
+    """Sketch the planet crossing the stellar limb, with its shape exaggerated so that it is visible."""
+    ax.add_patch(Circle((0, 0), 1.0, fc='0.94', ec='0.5', lw=0.8))
+    xyc = solve2d(0.0, P, A, arccos(b / A), 0.0, 0.0)
+    xs = array([pos_c(t, xyc) for t in linspace(-0.4, 0.4, 200)])
+    ax.plot(xs[:, 0], xs[:, 1], c='0.6', lw=0.8, ls='--')
+    yc = pos_c(0.0, xyc)[1]
+    for x in (-sqrt(1 - yc ** 2), 0.0, sqrt(1 - yc ** 2)):
+        ax.add_patch(Ellipse((x, yc), 2 * k, 2 * k * (1 - f), angle=degrees(alpha), fc='k', ec='none'))
+    ax.set_xlim(-1.4, 1.4)
+    ax.set_ylim(-1.15, 1.15)
+    ax.set_aspect('equal')
+    ax.axis('off')
+
+
+def plot_oblateness_signal(time, fluxes, k, f, b, ldc=LDC):
+    """Draw the oblate planet's light curve against an equal-area and a best-fitting spherical planet.
+
+    Parameters
+    ----------
+    time : ndarray
+        The mid-exposure times the fluxes were computed for.
+    fluxes : dict
+        Mapping from the projected obliquity in radians to the oblate planet's flux.
+    k, f, b : float
+        The radius ratio, flattening, and impact parameter the fluxes were computed with.
+    ldc : tuple, optional
+        The quadratic limb darkening coefficients the fluxes were computed with.
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+    """
+    ldc = list(ldc)
+    rr = RoadRunnerModel('quadratic')
+    rr.set_data(time)
+    keq = k * sqrt(1.0 - f)
+    equal_area = rr.evaluate(keq, ldc, 0.0, P, A, arccos(b / A))
+
+    n = len(fluxes)
+    fig, axs = subplots(2, n, figsize=(9, 5), height_ratios=(2, 3), sharey='row')
+    for (alpha, flux), at, ab in zip(fluxes.items(), axs[0], axs[1]):
+        _draw_geometry(at, b, alpha)
+        at.set_title(f'$\\alpha$ = {degrees(alpha):.0f}°')
+        fitted = _sphere_fit(time, flux, keq, ldc)
+        ab.plot(24 * time, 1e6 * (flux - equal_area), c='0.6', ls='--', label='Equal-area sphere')
+        ab.plot(24 * time, 1e6 * (flux - fitted), c='k', label='Best-fitting sphere')
+        ab.axhline(0.0, c='0.8', lw=0.5, zorder=-1)
+        ab.autoscale(axis='x', tight=True)
+        setp(ab, xlabel='Time - $t_c$ [h]')
+        _despine(ab)
+    setp(axs[1, 0], ylabel='Oblate - spherical [ppm]')
+    axs[1, 0].legend(fontsize='small', frameon=False, loc='lower left')
+    fig.tight_layout()
+    return fig
+
+
+def _intensity(x, y, u1, u2):
+    r2 = x * x + y * y
+    if r2 >= 1.0:
+        return 0.0
+    mu = sqrt(1.0 - r2)
+    return 1.0 - u1 * (1.0 - mu) - u2 * (1.0 - mu) ** 2
+
+
+def _reference_flux(cx, cy, k, f, alpha, u1, u2):
+    """Oblate planet transit flux from nested adaptive quadrature over the exact overlap region.
+
+    The same reference the test suite validates the model against (``tests/test_opmodel.py``).
+    """
+    bb = 1.0 - f
+    ca, sa = cos(alpha), sin(alpha)
+    hh = k * sqrt(sa * sa + bb * bb * ca * ca)
+
+    def scanline(y):
+        if abs(y) >= 1.0:
+            return 0.0
+        yp = (y - cy) / k
+        d = bb * bb * ca * ca + sa * sa - yp * yp
+        if d <= 0.0:
+            return 0.0
+        sd = sqrt(d) / bb
+        u = yp * ca * sa * (1.0 / (bb * bb) - 1.0)
+        v = sa * sa / (bb * bb) + ca * ca
+        w = sqrt(1.0 - y * y)
+        lo = max(cx + k * (u - sd) / v, -w)
+        hi = min(cx + k * (u + sd) / v, w)
+        if hi <= lo:
+            return 0.0
+        return quad(_intensity, lo, hi, args=(y, u1, u2), epsabs=1e-13, epsrel=1e-12, limit=200)[0]
+
+    ylo, yhi = max(cy - hh, -1.0), min(cy + hh, 1.0)
+    blocked = quad(scanline, ylo, yhi, epsabs=1e-12, epsrel=1e-11, limit=500)[0] if yhi > ylo else 0.0
+    return 1.0 - blocked / (pi * (1.0 - u1 / 3.0 - u2 / 6.0))
+
+
+def plot_accuracy_levels(k=0.1, f=0.1, alpha=pi / 4, bs=(0.5, 1.0), ldc=LDC):
+    """Compare the model's accuracy settings against direct numerical integration of the stellar disk.
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+    """
+    settings = {'Default': {},
+                '``exact_ld``': dict(exact_ld=True),
+                '``exact_ld`` and ``exact_areas``': dict(exact_ld=True, exact_areas=True)}
+    fig, axs = subplots(1, len(bs), figsize=(9, 3.6), sharey=True)
+    for b, ax in zip(bs, axs):
+        # From mid-transit to slightly past the last contact, which is where all the error lives.
+        half_duration = P / (2 * pi) * arcsin(sqrt((1 + k) ** 2 - b ** 2) / A)
+        time = linspace(0.0, 1.05 * half_duration, 150)
+        tm = OPModel('quadratic')
+        tm.set_data(time)
+
+        inc = arccos(b / A)
+        xyc = solve2d(0.0, P, A, inc, 0.0, 0.0)
+        with warnings.catch_warnings():
+            warnings.simplefilter('ignore', IntegrationWarning)
+            reference = array([_reference_flux(*pos_c(t, xyc), k, f, alpha, *ldc) for t in time])
+        for label, kwargs in settings.items():
+            flux = tm.evaluate(k, f, alpha, list(ldc), 0.0, P, A, inc, **kwargs)
+            ax.plot(24 * time, 1e6 * npabs(flux - reference), label=label.replace('``', ''))
+        ax.axhline(1.0, ls='--', c='0.75', zorder=-1)
+        setp(ax, xlabel='Time - $t_c$ [h]', yscale='log', ylim=(1e-3, 1e2),
+             title=f'Impact parameter {b:g}' + (' (grazing)' if b + k >= 1.0 else ''))
+        ax.autoscale(axis='x', tight=True)
+        _despine(ax)
+    setp(axs[0], ylabel='Model error [ppm]')
+    axs[0].legend(fontsize='small', frameon=False, loc='upper left')
+    fig.tight_layout()
+    return fig

pytransit-2.10.1/docs/source/_figures/rr_benchmark.py

@@ -0,0 +1,114 @@
+#  PyTransit: fast and easy exoplanet transit modelling in Python.
+#  Copyright (C) 2010-2026  Hannu Parviainen
+#
+#  This program is free software: you can redistribute it and/or modify
+#  it under the terms of the GNU General Public License as published by
+#  the Free Software Foundation, either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License
+#  along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+"""RoadRunner against the quadratic Mandel & Agol model: evaluation time against the exposure count.
+
+Timings depend on the machine, and measuring them takes minutes, so the documentation does not
+rerun the benchmark at build time. Running this file as a script measures the timings and writes
+them to ``rr_benchmark.csv`` next to it, and the documentation plots that file:
+
+    python docs/source/_figures/rr_benchmark.py
+
+Both models run on a single thread, for a light curve where about half of the exposures are in
+transit.
+"""
+
+from pathlib import Path
+
+from matplotlib.pyplot import subplots, setp
+from numpy import arccos, array, linspace, loadtxt, pi
+
+__all__ = ['SETTINGS', 'run_benchmark', 'plot_benchmark']
+
+CSV = Path(__file__).with_name('rr_benchmark.csv')
+
+# The RoadRunner accuracy levels, each the cheapest (nq, ng) whose worst-case error against the
+# exact quadratic model stays below the target for radius ratios up to 0.2 and impact parameters
+# up to 0.9, with the measured worst-case error in ppm.
+SETTINGS = {'RoadRunner (1 ppm)': dict(nq=5, ng=300, error=0.93),
+            'RoadRunner (default)': dict(nq=8, ng=100, error=5.9),
+            'RoadRunner (10 ppm)': dict(nq=4, ng=75, error=7.2),
+            'RoadRunner (100 ppm)': dict(nq=3, ng=20, error=48.0),
+            'RoadRunner (500 ppm)': dict(nq=2, ng=10, error=316.0)}
+
+NPTS = (10, 30, 100, 300, 1_000, 3_000, 10_000, 30_000, 100_000, 300_000, 1_000_000)
+
+
+def _models():
+    from pytransit import QuadraticModel, RoadRunnerModel
+    models = {'Quadratic (exact)': QuadraticModel(interpolate=False),
+              'Quadratic (interpolated)': QuadraticModel(interpolate=True)}
+    for name, s in SETTINGS.items():
+        models[name] = RoadRunnerModel('quadratic', nq=s['nq'], ng=s['ng'])
+    return models
+
+
+def run_benchmark(npts=NPTS, path=CSV):
+    """Time every model for every number of exposures and write the results to `path`."""
+    import numba
+    from timeit import repeat
+    numba.set_num_threads(1)
+
+    p, a, k, b, ldc = 4.0, 13.0, 0.1, 0.3, [0.4, 0.25]
+    models = _models()
+    names = list(models)
+    rows = []
+    for npt in npts:
+        time = linspace(-0.1, 0.1, npt)
+        row = [npt]
+        for name in names:
+            tm = models[name]
+            tm.set_data(time)
+            f = lambda: tm.evaluate(k, ldc, 0.0, p, a, arccos(b / a))
+            f()
+            number = max(1, int(2e5 // npt))
+            row.append(min(repeat(f, number=number, repeat=7)) / number)
+        rows.append(row)
+        print(npt, ' '.join(f'{t * 1e3:9.4f}' for t in row[1:]))
+    with open(path, 'w') as out:
+        out.write('npt,' + ','.join(names) + '\n')
+        for row in rows:
+            out.write(f'{row[0]},' + ','.join(f'{t:.6e}' for t in row[1:]) + '\n')
+
+
+def plot_benchmark(path=CSV):
+    """Plot the evaluation time per exposure against the number of exposures.
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+    """
+    with open(path) as f:
+        names = f.readline().strip().split(',')[1:]
+    data = loadtxt(path, delimiter=',', skiprows=1)
+    npt = data[:, 0]
+
+    styles = {'Quadratic (exact)': dict(c='k', lw=2),
+              'Quadratic (interpolated)': dict(c='k', ls='--')}
+    fig, ax = subplots(figsize=(9, 4.2))
+    for i, name in enumerate(names):
+        ax.plot(npt, 1e9 * data[:, i + 1] / npt, label=name, **styles.get(name, {}))
+    setp(ax, xscale='log', yscale='log', xlabel='Number of exposures',
+         ylabel='Time per exposure [ns]', title='Single-threaded evaluation time')
+    ax.legend(fontsize='small', frameon=False, ncols=2)
+    ax.spines['top'].set_visible(False)
+    ax.spines['right'].set_visible(False)
+    fig.tight_layout()
+    return fig
+
+
+if __name__ == '__main__':
+    run_benchmark()