PyTransit 2.9.3__tar.gz → 2.10.0__tar.gz

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

@@ -1,5 +1,16 @@
 # Changelog
 
+## [2.10.0] - 2026-10-19
+
+### Changed
+
+- `TSModel` is about four times faster with many wavelength bins, and with `nthreads > 1` parallelises over the bins
+  instead of the exposures.
+
+### Fixed
+
+- `TSModel` with `nthreads > 1` summing each in-transit exposure once per wavelength bin, giving fluxes near `npb`.
+
 ## [2.9.3] - 2026-10-15
 
 ### Changed

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

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

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

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

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

@@ -41,6 +41,7 @@ docs/source/_figures/__init__.py
 docs/source/_figures/dataset_arrays.py
 docs/source/_figures/highlights.py
 docs/source/_figures/roadrunner.py
+docs/source/_figures/tsmodel.py
 docs/source/_static/.gitkeep
 docs/source/api/deprecated.rst
 docs/source/api/index.rst
@@ -279,6 +280,7 @@ tests/test_rrmodel_cl.py
 tests/test_rrmodel_population.py
 tests/test_rrmodel_quadrature.py
 tests/test_rvdata.py
+tests/test_tsmodel.py
 tests/test_uniform_model.py
 tests/test_uniform_model_nb.py
 tests/test_z.py

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

@@ -20,6 +20,7 @@
     "docs/source/_figures/dataset_arrays.py",
     "docs/source/_figures/highlights.py",
     "docs/source/_figures/roadrunner.py",
+    "docs/source/_figures/tsmodel.py",
     "docs/source/_static/.gitkeep",
     "docs/source/api/deprecated.rst",
     "docs/source/api/index.rst",
@@ -272,6 +273,7 @@
     "tests/test_rrmodel_population.py",
     "tests/test_rrmodel_quadrature.py",
     "tests/test_rvdata.py",
+    "tests/test_tsmodel.py",
     "tests/test_uniform_model.py",
     "tests/test_uniform_model_nb.py",
     "tests/test_z.py",

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

@@ -0,0 +1,8 @@
+{
+  "tag": "2.10.0",
+  "distance": 0,
+  "node": "gd00e4aa7f2acddc4def8914ba5a45656e7419b4c",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-10-19"
+}

pytransit-2.10.0/docs/source/_figures/tsmodel.py

@@ -0,0 +1,189 @@
+#  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 transmission spectroscopy feature page.
+
+The page is about many wavelength bins sharing one transit geometry, so the figures show a whole
+spectroscopic dataset at once and measure what sharing the geometry costs in accuracy. Keeping the
+plotting and the toy spectrum here lets the page show only the PyTransit calls.
+"""
+
+from matplotlib.pyplot import subplots, setp
+from matplotlib.ticker import MaxNLocator
+from meepmeep.backends.numba.point2d import sep_c, solve2d
+from numpy import abs as npabs, array, exp, geomspace, linspace, pi, stack, tile
+
+from pytransit import RoadRunnerModel, TSModel
+
+__all__ = ['toy_spectrum', 'plot_spectroscopic_transit', 'plot_accuracy']
+
+# The example transit used throughout the page.
+WINDOW = 3.5 / 24
+TIME = linspace(-0.5 * WINDOW, 0.5 * WINDOW, 1500)
+T0, P, A, INC = 0.0, 4.0, 13.0, 0.49 * pi
+
+
+def _despine(ax):
+    ax.spines['top'].set_visible(False)
+    ax.spines['right'].set_visible(False)
+
+
+def _gaussian(x, centre, width):
+    return exp(-0.5 * ((x - centre) / width) ** 2)
+
+
+def toy_spectrum(npb, k0=0.1):
+    """A toy near-infrared transmission spectrum with wavelength-dependent limb darkening.
+
+    The radius ratio has a weak scattering slope and a few absorption bands loosely placed at the
+    water and carbon dioxide features, each changing the radius ratio by one to two percent. The
+    quadratic limb darkening weakens towards the red. None of it is meant to be physical; it only
+    gives the bins something to differ by.
+
+    Parameters
+    ----------
+    npb : int
+        Number of wavelength bins between 0.6 and 5.0 micron.
+    k0 : float, optional
+        The continuum radius ratio.
+
+    Returns
+    -------
+    wl : ndarray
+        Bin centres in micron, shape ``(npb,)``.
+    k : ndarray
+        Radius ratios, shape ``(npb,)``.
+    ldc : ndarray
+        Quadratic limb darkening coefficients, shape ``(npb, 2)``.
+    """
+    wl = linspace(0.6, 5.0, npb)
+    k = k0 * (1.0 + 0.004 * (0.6 / wl) ** 4
+              + 0.010 * _gaussian(wl, 1.40, 0.10)
+              + 0.012 * _gaussian(wl, 1.90, 0.12)
+              + 0.015 * _gaussian(wl, 2.70, 0.15)
+              + 0.020 * _gaussian(wl, 4.30, 0.12))
+    ldc = stack([0.15 + 0.35 * (0.6 / wl) ** 0.9, 0.12 + 0.10 * (0.6 / wl)], axis=1)
+    return wl, k, ldc
+
+
+def plot_spectroscopic_transit(wl, k, flux, time=TIME):
+    """Draw the transmission spectrum beside the spectroscopic light curves it produces.
+
+    The spectrum is drawn as the radius ratio with its mean over the bins marked, since the model
+    shares its geometry through that mean. The light curves are shown relative to their mean over
+    wavelength, since the transit itself is the same in every bin and would otherwise hide the
+    differences between them.
+
+    Parameters
+    ----------
+    wl : ndarray
+        Bin centres in micron.
+    k : ndarray
+        Radius ratio per bin.
+    flux : ndarray
+        Modelled flux with shape ``(npb, npt)``.
+    time : ndarray, optional
+        The mid-exposure times the flux was computed for.
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+    """
+    fig, (al, ar) = subplots(1, 2, figsize=(9, 3.6), width_ratios=(2, 3))
+    al.plot(wl, k, 'k')
+    al.axhline(k.mean(), ls='--', c='0.6', zorder=-1)
+    al.text(wl[-1], k.mean(), '$\\bar{k}$', color='0.4', ha='right', va='bottom')
+
+    differential = 1e6 * (flux - flux.mean(0))
+    vmax = npabs(differential).max()
+    im = ar.pcolormesh(24 * time, wl, differential, cmap='RdBu_r', vmin=-vmax, vmax=vmax,
+                       shading='nearest', rasterized=True)
+    fig.colorbar(im, ax=ar, label='Flux - mean flux [ppm]')
+
+    setp(al, xlabel='Wavelength [$\\mu$m]', ylabel='Radius ratio $k$',
+         title='Transmission spectrum')
+    setp(ar, xlabel='Time - $t_c$ [h]', ylabel='Wavelength [$\\mu$m]',
+         title='Light curves relative to their mean')
+    al.autoscale(axis='x', tight=True)
+    al.yaxis.set_major_locator(MaxNLocator(5))
+    _despine(al)
+    fig.tight_layout()
+    return fig
+
+
+def _bin_errors(kmean, deviation, inc, ldc, time):
+    """Flux error of the two bins at ``kmean * (1 -/+ deviation)``, against per-bin RoadRunner.
+
+    The third bin sits at the mean so the spread is symmetric and the model's mean radius ratio is
+    ``kmean`` exactly.
+    """
+    k = kmean * array([1.0 - deviation, 1.0, 1.0 + deviation])
+    ts = TSModel()
+    ts.set_data(time)
+    flux = ts.evaluate(k, tile(ldc, (3, 1)), T0, P, A, inc)[0]
+
+    rr = RoadRunnerModel('quadratic')
+    rr.set_data(time)
+    reference = array([rr.evaluate(kk, ldc, T0, P, A, inc) for kk in k])
+    return 1e6 * (flux - reference)[[0, 2]]
+
+
+def plot_accuracy(kmean=0.1, deviation=0.01, ldc=(0.4, 0.2),
+                  ks=(0.05, 0.1, 0.2), deviations=geomspace(0.002, 0.2, 12)):
+    """Measure the error of sharing the geometry across bins with different radius ratios.
+
+    The reference is :class:`~pytransit.models.roadrunner.rrmodel.RoadRunnerModel` evaluated bin by
+    bin with the same discretisation, so the difference is the error of the shared geometry alone,
+    not the quadrature error both models have in common.
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+    """
+    ldc = list(ldc)
+    fig, (al, ar) = subplots(1, 2, figsize=(9, 3.8))
+
+    # Where along the transit the error lives
+    # ---------------------------------------
+    xyc = solve2d(0.0, P, A, INC, 0.0, 0.0)
+    z = array([sep_c(t, xyc) for t in TIME])
+    errors = _bin_errors(kmean, deviation, INC, ldc, TIME)
+    al.plot(24 * TIME, errors[0], label=f'$k = \\bar{{k}}\\,(1 - {deviation:g})$')
+    al.plot(24 * TIME, errors[1], label=f'$k = \\bar{{k}}\\,(1 + {deviation:g})$')
+    al.fill_between(24 * TIME, 0, 1, where=(z > 1.0 - kmean) & (z < 1.0 + kmean), color='0.92',
+                    transform=al.get_xaxis_transform(), zorder=-1, label='Ingress and egress')
+    al.axhline(0.0, c='0.6', lw=0.5, zorder=-1)
+    setp(al, xlabel='Time - $t_c$ [h]', ylabel='Flux error [ppm]',
+         title=f'$\\bar{{k}} = {kmean:g}$, bins at $\\pm${100 * deviation:g}%')
+    al.autoscale(axis='x', tight=True)
+    al.legend(fontsize='small', frameon=False, loc='upper center')
+
+    # How the error scales with the spread
+    # ------------------------------------
+    time = linspace(0.0, 0.5 * WINDOW, 1000)
+    for kk in ks:
+        ar.plot(100 * deviations, [npabs(_bin_errors(kk, d, INC, ldc, time)).max() for d in deviations],
+                'o-', ms=3, label=f'$\\bar{{k}} = {kk:g}$')
+    ar.axhline(1.0, ls='--', c='0.75', zorder=-1)
+    ar.text(100 * deviations[-1], 1.1, '1 ppm', color='0.5', fontsize='small', va='bottom', ha='right')
+    setp(ar, xlabel='Deviation from the mean radius ratio [%]', ylabel='Maximum flux error [ppm]',
+         xscale='log', yscale='log', title='Error against the radius ratio spread')
+    ar.legend(fontsize='small', frameon=False)
+
+    _despine(al)
+    _despine(ar)
+    fig.tight_layout()
+    return fig

pytransit-2.10.0/docs/source/features/roadrunner.rst

@@ -0,0 +1,193 @@
+RoadRunner model
+================
+
+:class:`~pytransit.models.roadrunner.rrmodel.RoadRunnerModel` (Parviainen, MNRAS 499, 1633, 2020)
+is PyTransit's recommended general-purpose transit model. Its distinguishing feature is that the
+stellar intensity profile is an *input* to the model rather than something built into its
+derivation. Any radially symmetric profile works, and the choice costs essentially nothing.
+
+.. plot::
+    :context:
+    :nofigs:
+
+    from _figures.roadrunner import plot_laws, plot_profile_and_transit
+
+Geometry and profile, separated
+-------------------------------
+
+The classical transit models are analytic solutions to one specific integral: a limb-darkened disk
+overlapped by an opaque circle, solved separately for each limb darkening law. A new law needs a
+new derivation, and some laws have no closed form at all.
+
+RoadRunner splits the problem in two. The **geometry** -- which parts of the stellar disk the
+planet covers -- depends only on the radius ratio and the planet's position, not on how bright the
+star is. The model turns it into a handful of points at which to read the stellar intensity, and a
+weight for each reading. The **intensity profile** enters only through those readings, from a table
+computed once per evaluation, so the model never sees the function that produced it.
+
+Nothing in this depends on the form of the profile, and the rest of this page shows what follows
+from that. :doc:`../models/roadrunner` describes how the readings and their weights are chosen.
+
+The law is a one-line choice
+----------------------------
+
+The built-in laws are selected by name in the initialiser. Nothing else about the call changes.
+
+.. plot::
+    :context: close-figs
+    :include-source:
+
+    from numpy import pi, linspace
+    from pytransit import RoadRunnerModel
+
+    window = 3.5 / 24
+    time = linspace(-0.5 * window, 0.5 * window, 1500)
+    k, t0, p, a, i = 0.1, 0.0, 4.0, 13.0, 0.49 * pi
+
+    laws = {'linear':    [0.4],
+            'quadratic': [0.3, 0.1],
+            'power-2':   [0.6, 0.5],
+            'nonlinear': [0.4, 0.3, 0.2, 0.1]}
+
+    fluxes = {}
+    for name, ldc in laws.items():
+        tm = RoadRunnerModel(name)
+        tm.set_data(time)
+        fluxes[name] = tm.evaluate(k, ldc, t0, p, a, i)
+
+    plot_laws(laws, fluxes, time)
+
+Eleven laws ship with the model, listed in :doc:`../guide/limb_darkening`. Two of them,
+``'quadratic-tri'`` and ``'power-2-pm'``, are not new physics but reparametrisations that behave
+better as free parameters in a fit.
+
+Any profile you can write down
+------------------------------
+
+Instead of a name, RoadRunner also accepts any Numba-compilable function ``f(mu, pv)`` that returns
+the intensity at :math:`\mu = \cos\gamma`. Nothing requires that function to be a sensible limb
+darkening law. Here is a profile that oscillates across the disk:
+
+.. plot::
+    :context: close-figs
+    :include-source:
+
+    from numpy import sqrt, sin, ceil
+    from numba import njit
+
+    @njit(fastmath=True)
+    def ld_wavy(mu, pv):
+        z = sqrt(1.0 - mu**2)
+        return 1.0 - (1.0 - z) * sin(ceil(pv[0]) * 2 * pi * z)
+
+    tm = RoadRunnerModel(ld_wavy, ng=200)
+    tm.set_data(time)
+    flux = tm.evaluate(k, [5], t0, p, a, i)
+
+    plot_profile_and_transit(ld_wavy, [5], flux, time, 'A wavy profile')
+
+The rings of alternating brightness show up as ripples in the light curve as the planet crosses
+them. No analytic transit model could integrate this profile, but for RoadRunner it is an ordinary
+input.
+
+A step in brightness works the same way:
+
+.. plot::
+    :context: close-figs
+    :include-source:
+
+    from numpy import tanh
+
+    @njit
+    def ld_step(mu, pv):
+        z = sqrt(1.0 - mu**2)
+        return 0.6 + 0.2 * tanh((0.5 - z) / pv[0])
+
+    tm = RoadRunnerModel(ld_step, ng=200)
+    tm.set_data(time)
+    flux = tm.evaluate(k, [0.05], t0, p, a, i)
+
+    plot_profile_and_transit(ld_step, [0.05], flux, time, 'A step profile')
+
+The light curve follows the profile directly. While the planet is entirely over the dim outer
+annulus the flux sits on a flat shelf, and it drops to a deeper minimum as the planet crosses onto
+the bright inner disk at :math:`z = 0.5`. The step is smoothed over :math:`0.05\,R_\star` on
+purpose: the model integrates the profile numerically, and a true discontinuity would leave small
+steps in the light curve.
+
+Both profiles are deliberately unphysical. If the model handles them, the realistic cases are
+straightforward: a profile tabulated from a stellar atmosphere grid, a law nobody has derived a
+transit solution for, or a profile with a feature from starspots. :doc:`../guide/limb_darkening`
+describes how to supply your own profile, and how to make it faster by also giving its disk
+integral.
+
+The law is nearly free
+----------------------
+
+Because the profile enters only through a table of fixed size, the choice of law barely affects
+the cost. Timing a 1500-point light curve on one machine, from the one-coefficient linear law to
+the six-coefficient general one:
+
+.. list-table::
+    :header-rows: 1
+    :widths: 30 20 50
+
+    * - Law
+      - Coefficients
+      - Time per evaluation
+    * - ``'linear'``
+      - 1
+      - 0.067 ms
+    * - ``'quadratic'``
+      - 2
+      - 0.067 ms
+    * - ``'power-2'``
+      - 2
+      - 0.070 ms
+    * - ``'nonlinear'``
+      - 4
+      - 0.072 ms
+    * - ``'general'``
+      - 6
+      - 0.072 ms
+
+The differences are a few microseconds, about as large as the variation between timing runs.
+Choosing a more flexible law is a modelling decision, not a performance one.
+
+Accuracy
+--------
+
+The price of the flexibility is that the profile is integrated numerically rather than
+analytically. With the default settings, RoadRunner agrees with the analytic Mandel & Agol
+solution for the quadratic law to 1.5 ppm at :math:`k = 0.1`, and the accuracy can be raised further
+when the science needs it. :doc:`../models/roadrunner` shows how the error depends on the radius
+ratio and on the integration settings.
+
+Profiles from stellar atmospheres
+---------------------------------
+
+The most physically motivated use of the flexibility is to skip analytic laws entirely.
+:class:`~pytransit.models.ldmodel.LDModel` is an interface for profiles that come from a stellar
+atmosphere model, and :class:`~pytransit.models.ldtkldm.LDTkLDModel` implements it on top of
+`LDTk <https://github.com/hpparvi/ldtk>`_, computing profiles from the Husser et al. (2013) PHOENIX
+specific intensity spectra.
+
+.. code-block:: python
+
+    from pytransit import RoadRunnerModel
+    from pytransit.models.ldtkldm import LDTkLDModel
+    from pytransit.contamination import sdss_g, sdss_r, sdss_i, sdss_z
+
+    ldm = LDTkLDModel(pbs=(sdss_g, sdss_r, sdss_i, sdss_z),
+                      teff=(5500, 100), logg=(4.5, 0.1), metal=(0.0, 0.1))
+
+    tm = RoadRunnerModel(ldm)
+
+The free parameters are then the stellar parameters rather than abstract coefficients, and the
+profile follows the model atmospheres directly.
+
+.. seealso::
+
+    :doc:`../models/roadrunner` for how the model works, its accuracy, and its API;
+    :doc:`../guide/limb_darkening` for the built-in laws and how to supply your own; and
+    :doc:`../highlights` for what the shared data setup adds on top.

pytransit-2.10.0/docs/source/features/tsmodel.rst

@@ -0,0 +1,105 @@
+Transmission spectroscopy model
+===============================
+
+A spectroscopic transit observation gives hundreds or thousands of light curves that differ in
+only two things. Every wavelength bin sees the same exposures, the same orbit and the same planet;
+only the radius ratio and the limb darkening change with wavelength.
+
+:class:`~pytransit.models.roadrunner.tsmodel.TransmissionSpectroscopyModel`, exported as
+``TSModel``, is the :doc:`RoadRunner model <roadrunner>` built around this. It computes the
+geometry once and evaluates every wavelength bin against it. For a spectrum of a thousand bins,
+this is about twenty times faster than evaluating RoadRunner bin by bin.
+
+.. plot::
+    :context:
+    :nofigs:
+
+    from _figures.tsmodel import toy_spectrum, plot_spectroscopic_transit
+
+One call, a whole spectrum
+--------------------------
+
+One radius ratio and one set of limb darkening coefficients per bin go in, and one light curve per
+bin comes out. Here for a toy near-infrared spectrum of 200 bins between 0.6 and 5 micron:
+
+.. plot::
+    :context: close-figs
+    :include-source:
+
+    from numpy import pi, linspace
+    from pytransit import TSModel
+
+    window = 3.5 / 24
+    time = linspace(-0.5 * window, 0.5 * window, 1500)
+    t0, p, a, i = 0.0, 4.0, 13.0, 0.49 * pi
+
+    wl, k, ldc = toy_spectrum(200)      # k.shape == (200,), ldc.shape == (200, 2)
+
+    tm = TSModel('quadratic')
+    tm.set_data(time)
+    flux = tm.evaluate(k, ldc, t0, p, a, i)
+    # flux.shape == (1, 200, 1500)
+
+    plot_spectroscopic_transit(wl, k, flux[0], time)
+
+The left panel is the input spectrum, and the right panel shows how each bin's light curve differs
+from the mean over all bins. The absorption bands show up as horizontal stripes where the transit
+is deeper. The largest differences, however, come from the limb darkening, which is stronger in the
+blue: those bins are deeper at mid-transit and shallower near the limb. A transmission spectrum is
+as much a question of the limb darkening in each bin as of the radius ratios, and the model takes
+both per bin.
+
+``set_data`` gets only the times. There are no light curve or passband indices to set up, and the
+number of bins is read from the arrays given to ``evaluate``, so the same model evaluates a white
+light curve, a coarse spectrum or a fine one without being set up again.
+
+Cost per wavelength bin
+-----------------------
+
+Time per evaluation for a 1000-exposure light curve with the transit covering about half of it, on
+one thread. ``RoadRunnerModel`` is timed both called once per bin and given all the bins at once as
+the passbands of a single dataset:
+
+.. list-table::
+    :header-rows: 1
+    :widths: 16 24 30 30
+
+    * - Bins
+      - ``TSModel``
+      - ``RoadRunnerModel``, one call per bin
+      - ``RoadRunnerModel``, all bins in one call
+    * - 1
+      - 0.064 ms
+      - 0.058 ms
+      - 0.054 ms
+    * - 10
+      - 0.090 ms
+      - 0.59 ms
+      - 0.50 ms
+    * - 100
+      - 0.33 ms
+      - 5.7 ms
+      - 4.8 ms
+    * - 1000
+      - 2.6 ms
+      - 57 ms
+      - 54 ms
+
+With one bin there is nothing to share. Beyond that the difference grows with the number of bins:
+about six times at ten bins, fifteen at a hundred, and twenty at a thousand. Each bin adds about
+2.6 µs to an evaluation, where a separate RoadRunner evaluation costs 55 µs. Large spectra can also
+be divided between threads with ``nthreads``: on eight threads, the thousand bins take 0.92 ms.
+
+Accuracy
+--------
+
+The geometry is shared through the mean radius ratio of the bins, so the result is exact when all
+the bins have the same radius ratio and approximate when they differ. For the toy spectrum above,
+whose radius ratios stay within 2% of their mean, the model agrees with RoadRunner evaluated bin
+by bin to within 6 ppm. :doc:`../models/tsmodel` shows how the error scales with the spread of the
+spectrum and the size of the planet.
+
+.. seealso::
+
+    :doc:`../models/tsmodel` for how the model works, its accuracy, and its API;
+    :doc:`roadrunner` for the model it is built on.