API Reference

All strategies are importable directly from the top-level package:

from lightcurve_strategies import transit_orbits, centrals, bodies, systems
from lightcurve_strategies import surfaces, surface_systems
from lightcurve_strategies import light_curves, white_noise, red_noise

Transit

lightcurve_strategies.transit_orbits(*, period=None, duration=None, time_transit=None, impact_param=None, radius_ratio=None)[source]

Generate random jaxoplanet.orbits.TransitOrbit instances.

Each keyword accepts a Hypothesis strategy. When None, a sensible default strategy is used. Strategies may yield astropy.units.Quantity values — they will be converted to plain floats in the expected units (days for time parameters, dimensionless for ratios).

Parameters:

  • period (SearchStrategy[float] | None) – Strategy for orbital period (days). Default: floats(0.5, 365.0).

  • duration (SearchStrategy[float] | None) – Strategy for transit duration (days). Default: floats(0.001, min(0.5 * period, 2.0)).

  • time_transit (SearchStrategy[float] | None) – Strategy for mid-transit time (days). Default: floats(0.0, period).

  • impact_param (SearchStrategy[float] | None) – Strategy for impact parameter (dimensionless, 0–1). Default: floats(0.0, 1.0).

  • radius_ratio (SearchStrategy[float] | None) – Strategy for planet-to-star radius ratio (dimensionless). Default: floats(0.001, 0.3).

Return type:

SearchStrategy[TransitOrbit]

Keplerian

lightcurve_strategies.centrals(*, mass=None, radius=None)[source]

Generate random jaxoplanet.orbits.keplerian.Central instances.

Each keyword accepts a Hypothesis strategy. When None, a sensible default strategy is used. Strategies may yield astropy.units.Quantity values — they will be converted to plain floats in the expected units (M_sun for mass, R_sun for radius).

Parameters:

  • mass (SearchStrategy[float] | None) – Strategy for stellar mass (M_sun). Default: floats(0.1, 10.0).

  • radius (SearchStrategy[float] | None) – Strategy for stellar radius (R_sun). Default: floats(0.1, 10.0).

Return type:

SearchStrategy[Central]

lightcurve_strategies.bodies(*, period=None, time_transit=None, impact_param=None, eccentricity=None, omega_peri=None, mass=None, radius=None)[source]

Generate random jaxoplanet.orbits.keplerian.Body instances.

Circular orbits by default. Providing eccentricity or omega_peri enables eccentric orbits (the other gets a default strategy if not explicitly supplied).

Each keyword accepts a Hypothesis strategy. When None, a sensible default strategy is used. Strategies may yield astropy.units.Quantity values — they will be converted to plain floats in the expected units (days for time parameters, dimensionless for ratios).

Parameters:

  • period (SearchStrategy[float] | None) – Strategy for orbital period (days). Default: floats(0.5, 365.0).

  • time_transit (SearchStrategy[float] | None) – Strategy for mid-transit time (days). Default: floats(0.0, period).

  • impact_param (SearchStrategy[float] | None) – Strategy for impact parameter (dimensionless, 0–1). Default: floats(0.0, 1.0).

  • eccentricity (SearchStrategy[float] | None) – Strategy for eccentricity (0–0.9). Default: None (circular).

  • omega_peri (SearchStrategy[float] | None) – Strategy for argument of periastron (radians). Default: None (circular).

  • mass (SearchStrategy[float] | None) – Strategy for body mass (solar masses, dimensionless in jaxoplanet’s internal unit system). Default: None (omitted).

  • radius (SearchStrategy[float] | None) – Strategy for body radius (solar radii, dimensionless in jaxoplanet’s internal unit system). Default: None (omitted).

Return type:

SearchStrategy[Body]

lightcurve_strategies.systems(*, central=None, body=None, min_bodies=0, max_bodies=5)[source]

Generate random jaxoplanet.orbits.keplerian.System instances.

Parameters:

  • central (SearchStrategy[Central] | None) – Strategy for the central star. Default: centrals().

  • body (SearchStrategy[Body] | None) – Strategy for each body. Default: bodies().

  • min_bodies (int) – Minimum number of bodies. Default: 0.

  • max_bodies (int) – Maximum number of bodies. Default: 5.

Return type:

SearchStrategy[System]

Starry

lightcurve_strategies.surfaces(*, y=None, inc=None, obl=None, period=None, amplitude=None, u=None)[source]

Generate random jaxoplanet.starry.Surface instances.

Conservative defaults matching the Surface() constructor defaults.

Unlike the keplerian strategies, surfaces() does not perform astropy.units.Quantity conversion — all parameters are in radians or dimensionless and are passed through to Surface() directly.

Parameters:

  • y (SearchStrategy[Ylm | None] | None) – Strategy for spherical harmonic map. Default: just(None) (uniform map). Typically use st.just(ylm_instance) with a pre-built Ylm rather than generating randomly.

  • inc (SearchStrategy[float] | None) – Strategy for inclination (radians). Default: just(π/2).

  • obl (SearchStrategy[float | None] | None) – Strategy for obliquity (radians). Default: just(None).

  • period (SearchStrategy[float | None] | None) – Strategy for rotation period. Default: just(None).

  • amplitude (SearchStrategy[float] | None) – Strategy for luminosity amplitude. Default: just(1.0).

  • u (SearchStrategy[tuple] | None) – Strategy for limb-darkening coefficients tuple. Default: just(()).

Return type:

SearchStrategy[Surface]

lightcurve_strategies.surface_systems(*, central=None, central_surface=None, body=None, min_bodies=0, max_bodies=5)[source]

Generate random jaxoplanet.starry.orbit.SurfaceSystem instances.

Parameters:

  • central (SearchStrategy[Central] | None) – Strategy for the central star. Default: centrals().

  • central_surface (SearchStrategy[Surface] | None) – Strategy for the central surface. Default: surfaces().

  • body (SearchStrategy[tuple[Body, Surface | None]] | None) – Strategy producing (Body, Surface | None) tuples. Default: st.tuples(bodies(), surfaces()).

  • min_bodies (int) – Minimum number of bodies. Default: 0.

  • max_bodies (int) – Maximum number of bodies. Default: 5.

Return type:

SearchStrategy[SurfaceSystem]

Light Curves

class lightcurve_strategies.LightCurveData(flux, flux_with_noise, noise, system)[source]

Container returned by light_curves().

Parameters:

  • flux (ndarray)

  • flux_with_noise (ndarray)

  • noise (ndarray)

  • system (SurfaceSystem)

flux

Clean stellar flux, shape (n_times,).

Type:

numpy.ndarray

flux_with_noise

flux + noise, shape (n_times,).

Type:

numpy.ndarray

noise

Noise realisation, shape (n_times,).

Type:

numpy.ndarray

system

The generated SurfaceSystem.

Type:

jaxoplanet.starry.orbit.SurfaceSystem

lightcurve_strategies.light_curves(*, time, system=None, order=10, noise=None, seed=None)[source]

Generate a light curve with optional noise.

Parameters:

  • time (np.ndarray) – Time grid in days.

  • system (SearchStrategy[SurfaceSystem] | None) – Strategy for the stellar system. Default: surface_systems(min_bodies=1, max_bodies=1).

  • order (int) – Spherical harmonic expansion order for light-curve computation.

  • noise (SearchStrategy[NoiseFn] | None) – Strategy that draws a NoiseFn. When None (default), no noise is added.

  • seed (SearchStrategy[int] | None) – Strategy for the RNG seed. Default: st.integers(0, 2**32 - 1). Only drawn when noise is not None.

Return type:

SearchStrategy[LightCurveData]

lightcurve_strategies.white_noise(scale)[source]

Independent Gaussian noise.

Parameters:

scale (float) – Standard deviation of the noise.

Returns:

noise(rng, time) -> rng.normal(0, scale, len(time))

Return type:

NoiseFn

lightcurve_strategies.red_noise(kernel, jitter=0.0)[source]

Correlated (GP-like) noise via Cholesky decomposition.

Parameters:

  • kernel (Callable[[ndarray], ndarray]) – Covariance kernel function (e.g. from sq_exp_kernel()).

  • jitter (float) – Diagonal regularisation added to the covariance matrix.

Returns:

Draws correlated samples L @ z where L = cholesky(K + jitter*I).

Return type:

NoiseFn

lightcurve_strategies.combined_noise(*noise_fns)[source]

Additive combination of multiple noise sources.

Parameters:

*noise_fns (Callable[[Generator, ndarray], ndarray]) – One or more NoiseFn callables.

Returns:

Sums the output of every constituent noise function.

Return type:

NoiseFn

lightcurve_strategies.sq_exp_kernel(amplitude, length_scale)[source]

Squared-exponential (RBF) covariance kernel.

Parameters:

  • amplitude (float) – Signal amplitude a.

  • length_scale (float) – Characteristic length scale ℓ.

Returns:

K(dt) = a² exp(-dt² / 2ℓ²)

Return type:

KernelFn

lightcurve_strategies.matern32_kernel(amplitude, length_scale)[source]

Matérn-3/2 covariance kernel.

Parameters:

  • amplitude (float) – Signal amplitude a.

  • length_scale (float) – Characteristic length scale ℓ.

Returns:

K(dt) = a² (1 + √3|dt|/ℓ) exp(-√3|dt|/ℓ)

Return type:

KernelFn