PyTransit 2.9.1__py3-none-any.whl → 2.9.2__py3-none-any.whl

pytransit/__init__.py

@@ -41,7 +41,7 @@ Date
 
 """
 
-__version__ = '2.9.1'
+__version__ = '2.9.2'
 
 # Generic
 # -------

pytransit/contamination/contamination.py

@@ -194,8 +194,9 @@ class BBContamination(_BaseContamination):
         self._delta_l = delta_l
         self._wl_grids = []
         for f in self.instrument.filters:
-            nwl = int(ceil((f.wl_max - f.wl_min) / self._delta_l))
-            self._wl_grids.append(linspace(f.wl_min, f.wl_max, nwl))
+            wl_min, wl_max = f.bbox
+            nwl = int(ceil((wl_max - wl_min) / self._delta_l))
+            self._wl_grids.append(linspace(wl_min, wl_max, nwl))
 
     @staticmethod
     def absolute_flux(teff: float, wl: Union[float, Iterable]) -> ndarray:
@@ -294,9 +295,17 @@ class SMContamination(_BaseContamination):
         Parameters
         ----------
         instrument
-            Instrument configuration
+            Instrument configuration.
         ref_pb
-            name of the reference passband
+            Name of the reference passband, i.e. the passband in which the contamination is
+            parametrised.
+        data
+            Stellar spectrum grid to use, either ``'BT-SETTL'`` (default) or ``'Husser2013'``.
+
+        Raises
+        ------
+        ValueError
+            If `data` is neither ``'BT-SETTL'`` nor ``'Husser2013'``.
         """
         super().__init__(instrument, ref_pb)
 

pytransit/contamination/filter.py

@@ -20,6 +20,23 @@ from scipy.interpolate import interp1d
 
 
 class Filter:
+    """Base class for the passband transmission profiles.
+
+    A filter is a callable that maps a wavelength in nanometres to a transmission between 0 and
+    1. Subclasses implement `__call__` and `sample`; this class only defines the interface.
+
+    Parameters
+    ----------
+    name : str
+        Passband name. Used as the passband identifier by :class:`~pytransit.contamination.instrument.Instrument`.
+
+    Attributes
+    ----------
+    bbox : ndarray
+        Wavelength bounding box ``[wl_min, wl_max]`` in nm, outside which the transmission is
+        zero.
+    """
+
     def __init__(self, name: str):
         self.name: str = name
         self.bbox: ndarray = array([250, 1000], dtype='d')
@@ -32,6 +49,19 @@ class Filter:
 
 
 class DeltaFilter(Filter):
+    """Monochromatic filter transmitting at a single wavelength.
+
+    Useful for modeling spectroscopic bins narrow enough that the transmission profile does
+    not matter, and as the default passband of the gravity-darkened model.
+
+    Parameters
+    ----------
+    name : str
+        Passband name.
+    wl : float
+        Central wavelength in nm.
+    """
+
     def __init__(self, name: str, wl: float):
         super().__init__(name)
         self.wl: float = wl
@@ -60,9 +90,12 @@ class BoxcarFilter(Filter):
         """
         Parameters
         ----------
-        :param name: passband name
-        :param wl_min: minimum wavelength
-        :param wl_max: maximum wavelength
+        name : str
+            Passband name.
+        wl_min : float
+            Minimum wavelength in nm.
+        wl_max : float
+            Maximum wavelength in nm.
         """
         super().__init__(name)
         self.bbox = array([wl_min, wl_max], dtype='d')
@@ -84,10 +117,18 @@ class TabulatedFilter(Filter):
         """
         Parameters
         ----------
-
-        name  : string      passband name
-        wl    : array_like  a list of wavelengths
-        tm    : array_like  a list of transmission values
+        name : str
+            Passband name.
+        wl : array-like
+            Wavelengths in nm. Must increase monotonically.
+        tm : array-like
+            Transmission values in [0, 1], one per wavelength. Interpolated with a cubic spline.
+
+        Raises
+        ------
+        AssertionError
+            If the arrays differ in size, the wavelengths are not monotonically increasing, or
+            a transmission value falls outside [0, 1].
         """
         super().__init__(name)
         self.wl = array(wl)

pytransit/contamination/instrument.py

@@ -19,6 +19,32 @@ from .filter import Filter, BoxcarFilter
 
 
 class Instrument:
+    """A set of passbands with optional detector quantum efficiency curves.
+
+    An `Instrument` bundles the passbands a contamination model integrates stellar spectra
+    over. The order of `filters` fixes the passband order used everywhere downstream: the
+    columns of the contamination arrays and the passband indices (`pbids`) given to a transit
+    model refer to this order.
+
+    Parameters
+    ----------
+    name : str
+        Instrument name.
+    filters : sequence of Filter
+        The passband transmission profiles, one per passband.
+    qes : Filter or sequence of Filter, optional
+        Detector quantum efficiency profiles. A single `Filter` is applied to every passband,
+        a sequence gives one profile per passband. Defaults to a flat unit response over
+        0-10000 nm, i.e. no quantum efficiency weighting.
+
+    Attributes
+    ----------
+    pb_n : int
+        Number of passbands.
+    pb_names : list of str
+        Passband names, taken from the filter names, in the order given.
+    """
+
     def __init__(self, name, filters, qes=None):
         self.name = name
 

pytransit/contamination/plotting.py

@@ -99,9 +99,9 @@ def _jplot(hte, cte, cnr, imp, rho, fw=10, nb=30, gs=25, simulation=False, **kwa
     ax_rm.hist(rho, bins=nb, alpha=0.5, range=rlim)
     ax_cnm.hist(cnr, bins=nb, alpha=0.5, range=clim, orientation='horizontal')
 
-    pl.setp(ax_tt, xlabel='Host $T_\mathrm{Eff}$', ylabel='Contaminant $T_\mathrm{Eff}$')
-    pl.setp(ax_chj, xlabel='Host $T_\mathrm{Eff}$', ylabel='Contamination in $i\'$')
-    pl.setp(ax_ccj, xlabel='Contaminant $T_\mathrm{Eff}$')
+    pl.setp(ax_tt, xlabel=r'Host $T_\mathrm{Eff}$', ylabel=r'Contaminant $T_\mathrm{Eff}$')
+    pl.setp(ax_chj, xlabel=r'Host $T_\mathrm{Eff}$', ylabel=r"Contamination in $i'$")
+    pl.setp(ax_ccj, xlabel=r'Contaminant $T_\mathrm{Eff}$')
     pl.setp(ax_cbj, xlabel='Impact parameter')
     pl.setp(ax_crj, xlabel='Stellar density')
 

pytransit/lpf/baselines/legendrebaseline.py

@@ -14,7 +14,7 @@
 #  You should have received a copy of the GNU General Public License
 #  along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
-from numpy import atleast_2d, zeros, concatenate, ones, inf, full, squeeze, c_
+from numpy import atleast_2d, zeros, concatenate, ones, inf, full, squeeze, c_, ptp
 from numba import njit, prange
 
 from ...param import LParameter, NormalPrior as NP
@@ -52,7 +52,7 @@ class LegendreBaseline:
         """Baseline parameter initialisation.
         """
 
-        self._baseline_times = [(t - t.mean()) / t.ptp() for t in self.times]
+        self._baseline_times = [(t - t.mean()) / ptp(t) for t in self.times]
         self._baseline_timea = concatenate(self._baseline_times)
 
         if isinstance(self.nlegendre, int):

pytransit/lpf/logposteriorfunction.py

@@ -19,9 +19,12 @@ import pandas as pd
 import xarray as xa
 import astropy.io.fits as pf
 
+from contextlib import contextmanager
+from multiprocessing import get_all_start_methods, get_context
 from pathlib import Path
 from time import strftime
 from typing import Union, Iterable
+from warnings import warn
 
 from astropy.table import Table
 from scipy.optimize import minimize
@@ -35,6 +38,57 @@ from pytransit.utils.de import DiffEvol
 from pytransit.param import ParameterSet, UniformPrior as UP, NormalPrior as NP
 
 
+def _init_pool_worker():
+    """Initialise a worker process in a pool created by PyTransit.
+
+    Restricts Numba to a single thread per worker process. Without this, every worker
+    would spawn its own set of Numba threads, oversubscribing the machine badly (an
+    n-core pool would end up running n x n threads).
+    """
+    try:
+        from numba import set_num_threads
+        set_num_threads(1)
+    except (ImportError, ValueError):
+        pass
+
+
+def _check_parallelisation(pool, ncores, vectorize) -> None:
+    """Raise an error if a pool is requested together with a vectorised posterior.
+    """
+    if vectorize and (pool is not None or (ncores is not None and ncores > 1)):
+        raise ValueError("Parallelisation using a multiprocessing pool cannot be combined with a vectorised log "
+                         "posterior function because both DiffEvol and emcee bypass the pool when 'vectorize=True'. "
+                         "Either set 'vectorize=False' to parallelise the posterior evaluation over the population "
+                         "using the pool, or drop the 'pool' and 'ncores' arguments and rely on the vectorised "
+                         "posterior.")
+
+
+@contextmanager
+def _resolve_pool(pool=None, ncores: int = None, start_method: str = None):
+    """Yield the parallelisation pool to use, creating and closing one if necessary.
+
+    A user-provided pool takes precedence and is never closed here: its lifetime belongs
+    to whoever created it. A pool created from ``ncores`` is owned by this context
+    manager and is always terminated on exit, also if the run raises or is interrupted.
+    """
+    if pool is not None:
+        if ncores is not None:
+            warn("Both 'pool' and 'ncores' were given: using the user-provided pool and ignoring 'ncores'.")
+        yield pool
+    elif ncores is not None and ncores > 1:
+        if start_method is None:
+            methods = get_all_start_methods()
+            start_method = 'forkserver' if 'forkserver' in methods else 'spawn'
+        pool = get_context(start_method).Pool(ncores, initializer=_init_pool_worker)
+        try:
+            yield pool
+        finally:
+            pool.terminate()
+            pool.join()
+    else:
+        yield None
+
+
 class LogPosteriorFunction:
     _lpf_name = 'LogPosteriorFunction'
 
@@ -63,6 +117,27 @@ class LogPosteriorFunction:
         self._old_de_fitness = None
         self._old_de_population = None
 
+    def __getstate__(self):
+        """Return the picklable state of the log posterior function.
+
+        The DE optimiser and the MCMC sampler are excluded from the pickled state. Both
+        hold a reference to the parallelisation pool while running, and pool objects
+        cannot be pickled, which would make the whole log posterior function unpicklable
+        (and thus unusable with a multiprocessing pool) as soon as either exists. The
+        workers need only to evaluate the posterior, so neither is of any use to them.
+        """
+        state = self.__dict__.copy()
+        for key in ('de', 'sampler', '_old_de_population', '_old_de_fitness'):
+            state.pop(key, None)
+        return state
+
+    def __setstate__(self, state):
+        self.__dict__.update(state)
+        self.de = None
+        self.sampler = None
+        self._old_de_population = None
+        self._old_de_fitness = None
+
     def print_parameters(self, columns: int = 2):
         columns = max(1, columns)
         for i, p in enumerate(self.ps):
@@ -136,18 +211,56 @@ class LogPosteriorFunction:
 
     def optimize_global(self, niter=200, npop=50, population=None, pool=None, lnpost=None, vectorize=True,
                         label='Global optimisation', leave=False, plot_convergence: bool = True, use_tqdm: bool = True,
-                        plot_parameters: tuple = (0, 2, 3, 4), min_ptp: float = 1e-2):
+                        plot_parameters: tuple = (0, 2, 3, 4), min_ptp: float = 1e-2, ncores: int = None,
+                        start_method: str = None):
+        """Optimise the log posterior function globally using Differential Evolution.
 
+        Parameters
+        ----------
+        pool
+            A parallelisation pool providing a `map` method (`multiprocessing.Pool`,
+            `schwimmbad.MPIPool`, etc.). The pool is used only for the duration of this
+            call and is not closed: its lifetime belongs to the caller. Requires
+            `vectorize=False`.
+        ncores
+            Number of processes in a pool created for the duration of this call and
+            closed afterwards. Ignored if `pool` is given. Requires `vectorize=False`.
+        start_method
+            Multiprocessing start method used for a pool created from `ncores`. Defaults
+            to 'forkserver' if available and 'spawn' otherwise. Forking is avoided by
+            default because it is unsafe to fork a process that has already run
+            multithreaded Numba code or initialised an OpenCL context. Note that these
+            start methods import the calling script in the worker processes, so a script
+            using `ncores` must guard its main code with `if __name__ == '__main__':`.
+        vectorize
+            If True (default), the whole population is passed to the log posterior
+            function in a single call and the parallelisation is left to Numba. This is
+            usually the fastest option on a single machine, but it is incompatible with
+            `pool` and `ncores`.
+        """
         lnpost = lnpost or self.lnposterior
         if self.de is None:
+            _check_parallelisation(pool, ncores, vectorize)
             self.de = DiffEvol(lnpost, clip(self.ps.bounds, -1, 1), npop, maximize=True, vectorize=vectorize,
-                               pool=pool, min_ptp=min_ptp)
+                               min_ptp=min_ptp)
             if population is None:
                 self.de._population[:, :] = self.create_pv_population(npop)
             else:
                 self.de._population[:, :] = population
-        for _ in tqdm(self.de(niter), total=niter, desc=label, leave=leave, disable=(not use_tqdm)):
-            pass
+        else:
+            _check_parallelisation(pool, ncores, self.de.vectorize)
+
+        # The pool is attached to the optimiser only for the duration of the run. Storing
+        # it permanently would leave the optimiser holding a reference to a pool that may
+        # already have been closed by the caller, and would make the log posterior
+        # function unpicklable.
+        with _resolve_pool(pool, ncores, start_method) as run_pool:
+            self.de.pool = run_pool
+            try:
+                for _ in tqdm(self.de(niter), total=niter, desc=label, leave=leave, disable=(not use_tqdm)):
+                    pass
+            finally:
+                self.de.pool = None
 
         if plot_convergence:
             fig, axs = subplots(1, 1 + len(plot_parameters), figsize=(13, 2), constrained_layout=True)
@@ -174,8 +287,32 @@ class LogPosteriorFunction:
 
     def sample_mcmc(self, niter: int = 500, thin: int = 5, repeats: int = 1, npop: int = None, population=None,
                     label='MCMC sampling', reset=True, leave=True, save=False, use_tqdm: bool = True, pool=None,
-                    lnpost=None, vectorize: bool = True):
+                    lnpost=None, vectorize: bool = True, ncores: int = None, start_method: str = None):
+        """Sample the log posterior function using emcee.
 
+        Parameters
+        ----------
+        pool
+            A parallelisation pool providing a `map` method (`multiprocessing.Pool`,
+            `schwimmbad.MPIPool`, etc.). The pool is used only for the duration of this
+            call and is not closed: its lifetime belongs to the caller. Requires
+            `vectorize=False`.
+        ncores
+            Number of processes in a pool created for the duration of this call and
+            closed afterwards. Ignored if `pool` is given. Requires `vectorize=False`.
+        start_method
+            Multiprocessing start method used for a pool created from `ncores`. Defaults
+            to 'forkserver' if available and 'spawn' otherwise. Forking is avoided by
+            default because it is unsafe to fork a process that has already run
+            multithreaded Numba code or initialised an OpenCL context. Note that these
+            start methods import the calling script in the worker processes, so a script
+            using `ncores` must guard its main code with `if __name__ == '__main__':`.
+        vectorize
+            If True (default), the whole ensemble is passed to the log posterior function
+            in a single call and the parallelisation is left to Numba. This is usually the
+            fastest option on a single machine, but it is incompatible with `pool` and
+            `ncores`.
+        """
         if save and self.result_dir is None:
             raise ValueError('The MCMC sampler is set to save the results, but the result directory is not set.')
 
@@ -194,18 +331,31 @@ class LogPosteriorFunction:
                 pop0 = self.sampler.chain[:, -1, :].copy()
 
         if self.sampler is None:
-            self.sampler = EnsembleSampler(pop0.shape[0], pop0.shape[1], lnpost, vectorize=vectorize, pool=pool)
-
-        for i in tqdm(range(repeats), desc=label, disable=(not use_tqdm), leave=leave):
-            if (self.sampler is not None and reset) or i > 0:
-                self.sampler.reset()
-            for _ in tqdm(self.sampler.sample(pop0, iterations=niter, thin=thin, skip_initial_state_check=False),
-                          total=niter, desc='Run {:d}/{:d}'.format(i + 1, repeats), leave=False,
-                          disable=(not use_tqdm)):
-                pass
-            if save:
-                self.save(self.result_dir)
-            pop0 = self.sampler.chain[:, -1, :].copy()
+            _check_parallelisation(pool, ncores, vectorize)
+            self.sampler = EnsembleSampler(pop0.shape[0], pop0.shape[1], lnpost, vectorize=vectorize)
+        else:
+            _check_parallelisation(pool, ncores, self.sampler.vectorize)
+
+        # The pool is attached to the sampler only for the duration of the run. Storing it
+        # permanently would leave the sampler holding a reference to a pool that may
+        # already have been closed by the caller, and would make the log posterior
+        # function unpicklable.
+        with _resolve_pool(pool, ncores, start_method) as run_pool:
+            self.sampler.pool = run_pool
+            try:
+                for i in tqdm(range(repeats), desc=label, disable=(not use_tqdm), leave=leave):
+                    if (self.sampler is not None and reset) or i > 0:
+                        self.sampler.reset()
+                    for _ in tqdm(self.sampler.sample(pop0, iterations=niter, thin=thin,
+                                                      skip_initial_state_check=False),
+                                  total=niter, desc='Run {:d}/{:d}'.format(i + 1, repeats), leave=False,
+                                  disable=(not use_tqdm)):
+                        pass
+                    if save:
+                        self.save(self.result_dir)
+                    pop0 = self.sampler.chain[:, -1, :].copy()
+            finally:
+                self.sampler.pool = None
 
     def posterior_samples(self, burn: int = 0, thin: int = 1):
         fc = self.sampler.chain[:, burn::thin, :].reshape([-1, len(self.ps)])

pytransit/lpf/lpf.py

@@ -26,7 +26,7 @@ from numba import njit, prange
 from numpy import (inf, sqrt, ones, zeros_like, concatenate, diff, log, ones_like, all,
                    clip, argsort, any, s_, zeros, arccos, nan, full, pi, sum, repeat, asarray, ndarray, log10,
                    array, atleast_2d, isscalar, atleast_1d, where, isfinite, arange, unique, squeeze, ceil, percentile,
-                   floor, diag, nanstd, seterr, median)
+                   floor, diag, nanstd, seterr, median, ptp)
 from numpy.random import uniform, normal, permutation, multivariate_normal
 from scipy.stats import norm
 
@@ -606,6 +606,20 @@ class BaseLPF(LogPosteriorFunction):
             dd.add_groups({'derived_parameters': ds})
             return dd
 
+    def _planet_pids(self, planet: int = 1):
+        """Parameter indices of a planet's zero epoch and period.
+
+        `BaseLPF` names its single planet's parameters `tc` and `p`, while the multiplanet LPFs
+        number theirs from one (`tc_1`, `p_1`, ...). Both are accepted, so that the plotting
+        methods work whichever parametrisation the LPF uses.
+        """
+        names = self.ps.names
+        if f'tc_{planet}' in names:
+            return self.ps.find_pid(f'tc_{planet}'), self.ps.find_pid(f'p_{planet}')
+        if planet == 1 and 'tc' in names:
+            return self.ps.find_pid('tc'), self.ps.find_pid('p')
+        raise KeyError(f'Could not find the zero epoch and the period of planet {planet}.')
+
     def plot_light_curves(self, method='de', ncol: int = 3, width: Optional[float] = None, planet: int = 1,
                           max_samples: int = 1000, figsize=None, data_alpha=0.5, ylim=None):
 
@@ -615,13 +629,13 @@ class BaseLPF(LogPosteriorFunction):
 
         if width is None:
             if self.nlc == 1:
-                width = 24 * self.timea.ptp()
+                width = 24 * ptp(self.timea)
             else:
                 width = 2.0
 
         ncol = min(ncol, self.nlc)
         nrow = int(ceil(self.nlc / ncol))
-        tid, pid = self.ps.find_pid(f"tc_{planet}"), self.ps.find_pid(f"p_{planet}")
+        tid, pid = self._planet_pids(planet)
         if method in ('mcmc', 'mc', 'posterior'):
             pvp = self.posterior_samples().posterior.to_array().values.copy().T.reshape([-1, len(self.ps)])
             t0, p = median(pvp[:, tid]), median(pvp[:, pid])

pytransit/lpf/ocltdvlpf.py

@@ -19,8 +19,8 @@ import pyopencl as cl
 import seaborn as sb
 
 from matplotlib.pyplot import subplots, setp
-from numpy import sqrt, array, inf, int, s_, percentile, median, mean, round, zeros, isfinite, where, atleast_2d, ceil, \
-    newaxis
+from numpy import sqrt, array, inf, s_, percentile, median, mean, round, zeros, isfinite, where, atleast_2d, ceil, \
+    newaxis, ptp
 
 from ..param.parameter import GParameter, LParameter
 from ..param.parameter import UniformPrior as UP, NormalPrior as NP
@@ -53,7 +53,7 @@ class OCLTDVLPF(OCLTTVLPF):
         def create_tc_prior(t, f, p=5):
             m = f > percentile(f, p)
             m = ~ndi.binary_erosion(m, iterations=6, border_value=1)
-            return NP(t[m].mean(), 0.25 * t[m].ptp())
+            return NP(t[m].mean(), 0.25 * ptp(t[m]))
 
         self.tnumber = round((array([t.mean() for t in self.times]) - self.zero_epoch) / self.period).astype(int)
         for t, f, tn in zip(self.times, self.fluxes, self.tnumber):

pytransit/lpf/oclttvlpf.py

@@ -16,7 +16,7 @@
 
 
 from matplotlib.pyplot import subplots, setp
-from numpy import sqrt, array, inf, int, s_, percentile, median, mean, round, zeros, atleast_2d, ceil, poly1d, polyfit
+from numpy import sqrt, array, inf, s_, percentile, median, mean, round, zeros, atleast_2d, ceil, poly1d, polyfit
 from numpy.random.mtrand import permutation
 from uncertainties import ufloat, UFloat
 

pytransit/lpf/tdvlpf.py

@@ -15,8 +15,8 @@
 #  along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 from matplotlib.pyplot import subplots, setp
-from numpy import pi, sign, cos, sqrt, sin, array, arccos, inf, round, int, s_, percentile, concatenate, median, mean, \
-    arange
+from numpy import pi, sign, cos, sqrt, sin, array, arccos, inf, round, s_, percentile, concatenate, median, mean, \
+    arange, ptp
 
 import scipy.ndimage as ndi
 
@@ -74,7 +74,7 @@ class TDVLPF(TTVLPF):
         def create_tc_prior(t, f, p=5):
             m = f > percentile(f, p)
             m = ~ndi.binary_erosion(m, iterations=6, border_value=1)
-            return N(t[m].mean(), 0.25 * t[m].ptp())
+            return N(t[m].mean(), 0.25 * ptp(t[m]))
 
         self.tnumber = round((array([t.mean() for t in self.times]) - self.zero_epoch) / self.period).astype(int)
         for t, f, tn in zip(self.times, self.fluxes, self.tnumber):

pytransit/lpf/transitanalysis.py

@@ -24,7 +24,7 @@ import numpy as np
 from matplotlib.pyplot import subplots, setp
 from numba import njit
 from numpy import inf, squeeze, atleast_2d, sqrt, zeros_like, \
-    ones, arange, argsort, arctan2, ndarray, median, percentile, ceil
+    ones, arange, argsort, arctan2, ndarray, median, percentile, ceil, ptp
 from numpy.random import permutation
 
 from .tesslpf import downsample_time
@@ -136,7 +136,7 @@ class TransitAnalysis(BaseLPF):
 
         if width is None:
             if self.nlc == 1:
-                width = 24 * self.timea.ptp()
+                width = 24 * ptp(self.timea)
             else:
                 width = 2.0
 

pytransit/models/_deprecation.py

@@ -0,0 +1,62 @@
+#  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/>.
+
+"""Deprecation helpers for the legacy transit model evaluation API.
+
+The `evaluate_ps` and `evaluate_pv` methods are the pre-2.9 evaluation interface, superseded by
+the single broadcasting `evaluate` method. They are deprecated in PyTransit 2.9 and will be
+removed in PyTransit 3.0.
+"""
+
+from astropy.utils.decorators import deprecated
+
+__all__ = ['deprecated_evaluation_method', 'DEPRECATED_IN', 'REMOVED_IN']
+
+#: The version the legacy evaluation methods were deprecated in.
+DEPRECATED_IN = '2.9'
+
+#: The version the legacy evaluation methods will be removed in.
+REMOVED_IN = '3.0'
+
+_MESSAGE = (f'The {{func}} {{obj_type}} is deprecated since PyTransit {DEPRECATED_IN} and will be '
+            f'removed in PyTransit {REMOVED_IN}.')
+
+
+def deprecated_evaluation_method(alternative: str = 'evaluate'):
+    """Mark a legacy transit model evaluation method as deprecated.
+
+    Applies `astropy.utils.decorators.deprecated` with the versions and wording PyTransit uses for
+    the legacy evaluation API. Besides raising an `AstropyDeprecationWarning` when the method is
+    called, the decorator prepends a ``.. deprecated::`` directive to the method's docstring, so
+    the deprecation is rendered in the API documentation without any extra markup.
+
+    Parameters
+    ----------
+    alternative : str, optional
+        Name of the method to use instead, quoted in the warning and in the documentation.
+
+    Returns
+    -------
+    callable
+        A decorator that marks the method deprecated.
+
+    Notes
+    -----
+    A deprecated method must never be called from inside PyTransit itself, or a user calling the
+    supported API would get the warning. Where `evaluate` shares an implementation with a
+    deprecated method, the implementation lives in a private method that both call.
+    """
+    return deprecated(DEPRECATED_IN, message=_MESSAGE, obj_type='method', alternative=alternative)

pytransit/models/eclipse_model.py

@@ -19,6 +19,7 @@ from typing import Union, Optional
 from numba import njit
 from numpy import ndarray, squeeze, zeros, asarray, ones
 from .numba.ma_uniform_nb import uniform_model_v, uniform_model_s
+from ._deprecation import deprecated_evaluation_method
 from .transitmodel import TransitModel
 
 __all__ = ['EclipseModel']
@@ -27,6 +28,33 @@ npfloat = Union[float, ndarray]
 
 
 class EclipseModel(TransitModel):
+    """Secondary eclipse (occultation) model with an explicit planet-star flux ratio.
+
+    Models the occultation of the planet by the star. The planet is treated as a uniform disk,
+    which is a good approximation for the dayside emission of most planets, and the eclipse
+    geometry is the transit geometry with the sign of the projected distance reversed.
+
+    The depth of the event is set by the planet-star flux ratio `fr` passed to `evaluate`. With
+    `fr` given, the model returns a light curve normalised to unity out of eclipse and dipping
+    to ``1 - fr`` at its bottom, so it can be multiplied straight into a transit model. Without
+    `fr`, the model returns the raw uniform-disk occultation profile, which is useful when the
+    flux ratio is applied later or fitted separately per passband.
+
+    Examples
+    --------
+    ::
+
+        from pytransit import EclipseModel
+
+        em = EclipseModel()
+        em.set_data(time)
+        flux = em.evaluate(k=0.1, t0=0.0, p=1.0, a=3.0, i=0.5*pi, fr=1e-3)
+
+    See Also
+    --------
+    UniformModel : the same geometry without the flux ratio, via ``eclipse=True``.
+    EclipseSpectroscopyModel : eclipse model for spectroscopic time series.
+    """
 
     def __init__(self) -> None:
         super().__init__()
@@ -98,6 +126,7 @@ class EclipseModel(TransitModel):
 
         return squeeze(flux)
 
+    @deprecated_evaluation_method()
     def evaluate_ps(self, k: float, t0: float, p: float, a: float, i: float, e: float = 0., w: float = 0., fr: Optional[float] = None) -> ndarray:
         """Evaluate the transit model for a set of scalar parameters.