Transit models (lazuli_exo.transit)

Instrument-agnostic transit light-curve models and the NASA Exoplanet Archive cache, formerly the standalone lazuli-transit package. An instrument simulator (the WCC ETC, the IFS) consumes a FluxModel through relative_flux(time); nothing here imports an instrument package.

Needs the transit extra (astropy, pandas, jaxoplanet); the archive download needs archive (astroquery). Every backend is MIT/BSD licensed; the GPL exomoon model (pandoramoon) deliberately stays out of this package.

Instrument-agnostic transit models + NASA Exoplanet Archive helpers.

Formerly the standalone lazuli-transit package. FluxModel maps time to normalized relative flux; instrument simulators (the WCC ETC, the IFS) consume it through relative_flux(time) and never the other way round: nothing here may import an instrument package.

class lazuli_exo.transit.FluxModel

Bases: object

Base class: map time -> relative flux, normalized to 1.0 out of event.

relative_flux(time)

plot(time, ax=None, **kw)

Plot relative_flux(time). Delegates to plotting.plot_flux_model.

class lazuli_exo.transit.TransitModel(t0=0.0, per=1.0, rp=0.1, a=15.0, inc=87.0, ecc=0.0, w=90.0, limb_dark='quadratic', u=(0.1, 0.3))

Bases: FluxModel

Exoplanet transit light-curve model backed by jaxoplanet.

Parameters follow the batman.TransitParams convention: t0 (center), per (period), rp (Rp/R*), a (a/R*), inc (deg), ecc, w (deg), limb_dark, u (coeffs). Only polynomial limb-darkening laws are supported (“uniform”, “linear”, “quadratic”).

classmethod from_planet(name, df=None, require_transit=True, limb_dark='quadratic', u=(0.1, 0.3))

Build a TransitModel from a NASA Exoplanet Archive (PSCompPars) row.

Looks up name in df (or the local cache via load_exoplanet_archive if None) and maps archive columns to transit-model parameters. pl_orbper is required; other fields fall back to circular-orbit / direct-ratio defaults when missing. Limb-darkening is not in the archive, so it stays a user argument.

If require_transit is True (default), a planet flagged as non-transiting in the archive (tran_flag == 0) raises ValueError — a transit model is not meaningful for it. Pass require_transit=False to build one anyway. When tran_flag is absent/unknown, the check is skipped.

Note: t0 is taken from pl_tranmid (absolute BJD). For a relative-time light curve, pass a time array spanning that epoch or set t0=0 after construction.

build_system()

Return (system, light_curve_fn) for the jaxoplanet backend.

Note this enables jax’s float64 mode globally: without it jax runs in float32 and the light curve is only accurate to ~1e-4.

check_params()

Reject non-finite or unphysical orbital parameters.

Requires finite t0, per, rp, a, inc, ecc, w with per, rp, a > 0 and 0 <= ecc < 1. Checked on construction and again before evaluation, so an archive row with missing values (NaN rp or a) fails loudly.

check_limb_dark()

Validate limb_dark and u against the supported polynomial laws.

relative_flux(time)

lazuli_exo.transit.plot_flux_model(model, time, ax=None, **kw)

Plot any FluxModel’s relative_flux(time) curve. Returns the Axes.

lazuli_exo.transit.download_exoplanet_archive(path=None, refresh=False)

Download the PSCompPars table to a local CSV cache and return it.

If the cache file exists and refresh is False, load it from disk instead of querying the archive. Otherwise query astroquery, write the CSV (creating parent directories), and return the DataFrame.

lazuli_exo.transit.load_exoplanet_archive(path=None)

Read the cached PSCompPars CSV into a DataFrame.

Does not hit the network. Raises FileNotFoundError (pointing at download_exoplanet_archive) if the cache file does not exist.

lazuli_exo.transit.default_archive_path()

Default cache location for the downloaded PSCompPars CSV.

Instrument-agnostic transit / flux models.

FluxModel maps time to normalized relative flux; TransitModel wraps the jaxoplanet package. These models carry no dependency on any specific instrument: a WCC or IFS simulator consumes a FluxModel through its relative_flux(time) interface.

class lazuli_exo.transit.models.FluxModel

Bases: object

Base class: map time -> relative flux, normalized to 1.0 out of event.

relative_flux(time)

plot(time, ax=None, **kw)

Plot relative_flux(time). Delegates to plotting.plot_flux_model.

class lazuli_exo.transit.models.TransitModel(t0=0.0, per=1.0, rp=0.1, a=15.0, inc=87.0, ecc=0.0, w=90.0, limb_dark='quadratic', u=(0.1, 0.3))

Bases: FluxModel

Exoplanet transit light-curve model backed by jaxoplanet.

Parameters follow the batman.TransitParams convention: t0 (center), per (period), rp (Rp/R*), a (a/R*), inc (deg), ecc, w (deg), limb_dark, u (coeffs). Only polynomial limb-darkening laws are supported (“uniform”, “linear”, “quadratic”).

classmethod from_planet(name, df=None, require_transit=True, limb_dark='quadratic', u=(0.1, 0.3))

Build a TransitModel from a NASA Exoplanet Archive (PSCompPars) row.

Looks up name in df (or the local cache via load_exoplanet_archive if None) and maps archive columns to transit-model parameters. pl_orbper is required; other fields fall back to circular-orbit / direct-ratio defaults when missing. Limb-darkening is not in the archive, so it stays a user argument.

If require_transit is True (default), a planet flagged as non-transiting in the archive (tran_flag == 0) raises ValueError — a transit model is not meaningful for it. Pass require_transit=False to build one anyway. When tran_flag is absent/unknown, the check is skipped.

Note: t0 is taken from pl_tranmid (absolute BJD). For a relative-time light curve, pass a time array spanning that epoch or set t0=0 after construction.

build_system()

Return (system, light_curve_fn) for the jaxoplanet backend.

Note this enables jax’s float64 mode globally: without it jax runs in float32 and the light curve is only accurate to ~1e-4.

check_params()

Reject non-finite or unphysical orbital parameters.

Requires finite t0, per, rp, a, inc, ecc, w with per, rp, a > 0 and 0 <= ecc < 1. Checked on construction and again before evaluation, so an archive row with missing values (NaN rp or a) fails loudly.

check_limb_dark()

Validate limb_dark and u against the supported polynomial laws.

relative_flux(time)

Download and load NASA Exoplanet Archive planet parameters.

download_exoplanet_archive fetches the PSCompPars table (one complete row per confirmed planet) to a local CSV cache; load_exoplanet_archive reads it. TransitModel.from_planet consumes the result to build transit models for real planets.

lazuli_exo.transit.archive.ARCHIVE_COLUMNS = ['pl_name', 'hostname', 'pl_orbper', 'pl_ratror', 'pl_ratdor', 'pl_orbincl', 'pl_tranmid', 'pl_orbeccen', 'pl_orblper', 'pl_radj', 'pl_orbsmax', 'tran_flag', 'st_rad', 'st_teff', 'sy_gaiamag', 'sy_vmag', 'sy_tmag', 'sy_jmag', 'sy_hmag', 'sy_kmag']

Identifier + transit columns we select and persist.

Brightness/Teff columns chosen for high completeness (~95% populated in PSCompPars): Gaia G, Johnson V, TESS T, and 2MASS J/H/K. The Sloan ugriz bands that the WCC filters map to are only ~half-populated, so they are not included by default. tran_flag (1 = transiting, 0 = not) is fully populated and drives TransitModel.from_planet’s transit check.

lazuli_exo.transit.archive.default_archive_path()

Default cache location for the downloaded PSCompPars CSV.

lazuli_exo.transit.archive.load_exoplanet_archive(path=None)

Read the cached PSCompPars CSV into a DataFrame.

Does not hit the network. Raises FileNotFoundError (pointing at download_exoplanet_archive) if the cache file does not exist.

lazuli_exo.transit.archive.download_exoplanet_archive(path=None, refresh=False)

Download the PSCompPars table to a local CSV cache and return it.

If the cache file exists and refresh is False, load it from disk instead of querying the archive. Otherwise query astroquery, write the CSV (creating parent directories), and return the DataFrame.

Reusable matplotlib plotting helpers for lazuli_exo.transit flux models.

matplotlib is an optional dependency, lazy-imported here so the package core stays numpy/astropy/pandas-only. Each function takes an optional ax and returns the matplotlib Axes so results compose and embed (e.g. in an applet).

lazuli_exo.transit.plotting.plot_flux_model(model, time, ax=None, **kw)

Plot any FluxModel’s relative_flux(time) curve. Returns the Axes.