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()
redback_csm.explore.mass_loss_history(model_name, time_before_sn, **kwargs)

Return the wind mass-loss history used by a redback-csm wind model.

This helper is intended for visualisation and sanity checks. The time coordinate is the wind look-back time before explosion in years. For a constant-velocity wind, material at radius r at explosion corresponds to time_before_sn = r / vwind.

Supported models are the wind-history families: wind_*, *_wind, boxwind_*, gausswind_*, triple_powerlaw_wind_*, *_triple_powerlaw_wind and smooth_triple_powerlaw_wind_*.

For boxwind_* with t1 < t2:

  • mdot_0 applies for time_before_sn <= t1; this is the most recent wind material and maps to the smallest radii.

  • mdot_1 applies for t1 < time_before_sn < t2; this is the box enhancement.

  • mdot_2 applies for time_before_sn >= t2; this is older material and maps to larger radii.

Parameters:

  • model_name (str) – Base model name, e.g. "boxwind_bpl". Suffixes such as "_bolometric" and "_radio" are accepted and stripped.

  • time_before_sn (array-like) – Look-back time before explosion in years.

  • **kwargs – Model parameters, including the relevant mdot values.

Returns:

Mass-loss rate in M_sun yr^-1 sampled at time_before_sn.

Return type:

numpy.ndarray

redback_csm.explore.csm_density_profile(model_name, radius, time_since_explosion=0.0, **kwargs)

Return the CSM density profile for wind-history models.

The density is computed from the same wind convention used by the solver,

rho(r, t) = mdot(|r / vwind - t|) / (4 pi r^2 vwind).

Parameters:

  • model_name (str) – Wind-history model name, e.g. "boxwind_bpl".

  • radius (array-like) – Radius in cm.

  • time_since_explosion (float, optional) – Epoch at which to evaluate the profile, in days. Default 0 evaluates the pre-SN profile at explosion.

  • **kwargs – Model parameters. Must include vwind in km/s and the relevant mass-loss history parameters.

Returns:

CSM density in g cm^-3.

Return type:

numpy.ndarray

redback_csm.explore.plot_mass_loss_history(model_name, time_before_sn, ax=None, label=None, color=None, xlabel='Look-back time before explosion (yr)', ylabel='$\\dot{M}$ ($M_\\odot\\,{\\rm yr}^{-1}$)', title=None, **kwargs)

Plot the wind mass-loss history Ṁ(t) used by a redback-csm wind model.

This is a thin plotting wrapper around mass_loss_history(), intended to help sanity-check what a model’s parameters mean before fitting.

Parameters:

  • model_name (str) – Wind-history model name, e.g. "boxwind_bpl".

  • time_before_sn (array-like) – Look-back time before explosion in years, over which to evaluate and plot Ṁ(t).

  • 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.

  • xlabel (str, optional) – Axis labels.

  • ylabel (str, optional) – Axis labels.

  • title (str or None, optional) – Axes title.

  • **kwargs – Model parameters, forwarded to mass_loss_history() (e.g. for boxwind_bpl: t1, t2, mdot_0, mdot_1, mdot_2).

Returns:

  • fig (matplotlib.figure.Figure) – The figure containing the plot.

  • mdot (numpy.ndarray) – Mass-loss rate in M_sun yr^-1 sampled at time_before_sn.

Examples

>>> import numpy as np
>>> from redback_csm.explore import plot_mass_loss_history
>>> t = np.geomspace(1e-2, 20.0, 500)
>>> fig, mdot = plot_mass_loss_history(
...     "boxwind_bpl", t,
...     t1=1.0, t2=3.0, mdot_0=1e-4, mdot_1=1e-2, mdot_2=2e-4,
... )
redback_csm.explore.plot_csm_density_profile(model_name, radius, time_since_explosion=0.0, ax=None, label=None, color=None, xlabel='Radius (cm)', ylabel='CSM density (g cm$^{-3}$)', title=None, **kwargs)

Plot the CSM density profile ρ(r) used by a redback-csm wind model.

This is a thin plotting wrapper around csm_density_profile(), intended to help sanity-check what a model’s parameters mean before fitting, e.g. to see exactly what CSM structure mdot_0, mdot_1, mdot_2 (for boxwind_*) or other wind-history parameters produce, without running a light-curve fit.

Parameters:

  • model_name (str) – Wind-history model name, e.g. "boxwind_bpl".

  • radius (array-like) – Radius in cm, over which to evaluate and plot ρ(r).

  • time_since_explosion (float, optional) – Epoch at which to evaluate the profile, in days. Default 0 evaluates the pre-SN profile at explosion.

  • 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.

  • xlabel (str, optional) – Axis labels.

  • ylabel (str, optional) – Axis labels.

  • title (str or None, optional) – Axes title.

  • **kwargs – Model parameters, forwarded to csm_density_profile() (must include vwind in km/s and the relevant mass-loss history parameters).

Returns:

  • fig (matplotlib.figure.Figure) – The figure containing the plot.

  • rho (numpy.ndarray) – CSM density in g cm^-3 sampled at radius.

Examples

>>> import numpy as np
>>> from redback_csm.explore import plot_csm_density_profile
>>> r = np.geomspace(1e14, 1e18, 500)
>>> fig, rho = plot_csm_density_profile(
...     "boxwind_bpl", r,
...     t1=1.0, t2=3.0, mdot_0=1e-4, mdot_1=1e-2, mdot_2=2e-4, vwind=100.0,
... )

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:
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.