API Reference

Public model wrappers live in redback_csm.models and are also registered with redback’s model library after installation.

Exploration utilities

explore.py — Utility for computing and plotting CSM interaction light curves from an arbitrary user-supplied density profile.

Intended for exploration and visualisation (e.g. stellar-evolution density profiles), not for Bayesian inference. The supernova ejecta can be either a broken power law (BPL) or an exponential profile.

Example

>>> import numpy as np
>>> from redback_csm.explore import csm_lightcurve_from_density

>>> # Simple r^{-2} wind profile
>>> r = np.geomspace(1e13, 1e17, 500)          # cm
>>> rho = 5e16 / r**2                           # g/cm^3

>>> fig = csm_lightcurve_from_density(
...     radius=r, density=rho,
...     t_ref=365.0,            # days — sets r = v * t_ref
...     sn_profile='bpl',
...     delta=1.0, nn=12.0,
...     mexp=10.0, eexp=1.0,
...     eff=0.3, kappa=0.34,
... )
>>> fig.savefig('my_lightcurve.png')

redback_csm.explore.csm_lightcurve_from_density(radius, density, t_ref, mexp, eexp, eff, sn_profile='bpl', delta=1.0, nn=12.0, kappa=None, mode='simple', n_rad_zones=40, efficiency_mode=0, ax=None, label=None, color=None, show_shock=False, xlabel='Time (days)', ylabel='Bolometric luminosity (erg s$^{-1}$)', title=None)

Compute and plot a CSM interaction light curve from an arbitrary density profile.

The CSM density profile ρ(r) is interpolated onto the internal Fortran velocity grid using r = v × t_ref (the reference epoch at which the profile is evaluated). This is the same convention used throughout redback-csm: t_ref is the time between CSM formation and the supernova.

Parameters:

radius (array-like) – Radial grid of the CSM density profile, in cm. Should span at least the region of interest (typically 1e13–1e17 cm).
density (array-like) – Density at each radius, in g cm⁻³.
t_ref (float) – Reference epoch at which the density profile is evaluated, in days. Sets the mapping r = v × t_ref between the velocity grid and radius. For a pre-SN wind, this is typically the time between the end of mass loss and the supernova.
mexp (float) – Supernova ejecta mass in M☉.
eexp (float) – Supernova explosion energy in foe (10⁵¹ erg).
eff (float) – Shock-to-radiation efficiency (0–1).
sn_profile ({'bpl', 'exponential'}) – Supernova ejecta density profile. 'bpl' — broken power law (inner index delta, outer nn). 'exponential' — exponential profile.
delta (float, optional) – Inner power-law index for BPL ejecta (ignored for exponential). Default 1.0.
nn (float, optional) – Outer power-law index for BPL ejecta (ignored for exponential). Default 12.0.
kappa (float or None, optional) – Opacity in cm² g⁻¹ for photon diffusion. If provided, the returned (and plotted) luminosity is the diffuse (observed) luminosity; otherwise it is the raw shock luminosity. Common values: 0.34 (electron scattering), 0.1 (lower bound).
mode ({'simple', 'transport'}, optional) – Runtime mode. 'simple' uses the thin-shell luminosity/post-processed diffusion path. 'transport' uses the radiation transport solver with the sampled CSM density grid. Default 'simple'.
n_rad_zones (int, optional) – Number of radiation zones for mode='transport'. Default 40.
efficiency_mode (int, optional) – Fortran shock-efficiency mode. Default 0.
ax (matplotlib.axes.Axes or None, optional) – Axes to plot on. If None, a new figure is created.
label (str or None, optional) – Line label for the legend.
color (str or None, optional) – Line colour.
show_shock (bool, optional) – If True and kappa is provided, also plot the underlying shock luminosity as a dashed line. Default False.
xlabel (str, optional) – Axis labels.
ylabel (str, optional) – Axis labels.
title (str or None, optional) – Axes title.

Returns:

fig (matplotlib.figure.Figure) – The figure containing the light curve.
lc (namedtuple) – Raw Fortran output with fields time (s), lbol, lbol_shock, lbol_diffuse (erg/s), rph (cm), temperature (K).

Examples

Plot a simple r⁻² wind profile interacting with a BPL supernova:

>>> import numpy as np
>>> from redback_csm.explore import csm_lightcurve_from_density
>>> r = np.geomspace(1e13, 1e17, 500)
>>> rho = 5e16 / r**2
>>> fig, lc = csm_lightcurve_from_density(
...     radius=r, density=rho,
...     t_ref=365.0, mexp=10.0, eexp=1.0, eff=0.3, kappa=0.34,
... )

Overlay multiple profiles on the same axes:

>>> fig, ax = plt.subplots()
>>> for A in [1e15, 5e15, 1e16]:
...     csm_lightcurve_from_density(
...         radius=r, density=A / r**2,
...         t_ref=365.0, mexp=10.0, eexp=1.0, eff=0.3,
...         ax=ax, label=f'A={A:.0e}',
...     )
>>> ax.legend()

CSM analysis utilities

Spline MLE utilities

JAX static CSM backend

class jax_csm.model.StaticPowerlawBPLParams(eta, r_inner, r_outer, delta_sn, nn_sn, mej_sn, esn, eff, m_csm, kappa=0.34, vej_max_ratio=3.0)

Parameters for a static finite power-law CSM shell hit by BPL ejecta.

Parameters:

eta (float)
r_inner (float)
r_outer (float)
delta_sn (float)
nn_sn (float)
mej_sn (float)
esn (float)
eff (float)
m_csm (float)
kappa (float)
vej_max_ratio (float)

eta: float: Alias for field number 0

r_inner: float: Alias for field number 1

r_outer: float: Alias for field number 2

delta_sn: float: Alias for field number 3

nn_sn: float: Alias for field number 4

mej_sn: float: Alias for field number 5

esn: float: Alias for field number 6

eff: float: Alias for field number 7

m_csm: float: Alias for field number 8

kappa: float: Alias for field number 9

vej_max_ratio: float: Alias for field number 10

jax_csm.model.solve_static_powerlaw_bpl(time_days, params, mode='transport', n_steps=16384, n_zones=40)

Evaluate a JAX-native static-power-law CSM light curve.

mode='simple' returns the instantaneous radiative shock luminosity. mode='transport' evolves a finite-volume radiation grid over the full static shell, then homologously expands that grid after shock emergence. The hydrodynamics and density normalizations are shared by both modes and match the current static finite-shell convention.

Parameters:

params (StaticPowerlawBPLParams)
mode (str)
n_steps (int)
n_zones (int)

jax_csm.model.static_powerlaw_csm_bpl_bolometric(time, **kwargs): Convenience wrapper with the same static BPL parameter names as redback_csm.models.

jax_csm.model.get_csm_lightcurve(params_dict)

High-level compatibility wrapper for the JAX static CSM model.

The preferred path is static_powerlaw_csm_bpl_bolometric with the same parameter names as redback_csm.models.generic_powerlaw_csm_bpl_bolometric. This wrapper also accepts the older {"dyn": ...} dictionary used by the original branch and maps it onto the current static finite-shell convention.

jax_csm.model.get_static_powerlaw_csm_bpl_lightcurve(time, return_diagnostics=False, **kwargs): Evaluate the JAX static finite-power-law CSM + BPL-ejecta model.

jax_csm.model.vmapped_static_powerlaw_csm_bpl(time, params_batch, mode='transport', n_steps=16384, n_zones=40): Vectorized static CSM evaluation for batches of StaticPowerlawBPLParams.