Models

In redback we have already implemented a lot of different models, which can be combined or modified to create another model easily. These models range from phenomenological, to analytical, semi-analytical to numerical surrogates built with machine learning techniques. Implementing a new model is probably the easiest way to contribute to redback!

Specifically, some models already included are as follows. For a full up to date list of models implemented in redback, look at the API

  • Afterglow models: Can output in flux density/magnitude

    • Several varieties of afterglow models implemented directly in redback following Lamb et al. 2018 and other work. Includes wind-like mediums and complex jet structures

    • Several jet structures but with refreshed shocks and the suite of options available for the set of models above.

    • All structured jet models implemented in afterglowpy. Must install afterglowpy to use these models.

    • Some varieties of Kilonova afterglow models e.g., Sarin et al. 2022, Nakar and Piran 2011

  • Kilonova models: Can output in flux density/magnitude/flux

    • One/two/three component kilonova models

    • two_layer_stratified_kilonova

    • power_law_stratified_kilonova

    • kilonova heating rate

    • One component BNS ejecta relation

    • Two component BNS ejecta relation

    • One component NSBH ejecta relation

    • Two component NSBH ejecta relation

    • Polytrope EOS ejecta relation

    • Aspherical kilonova

    • Three component model ejecta relation

    • Three component model temperature floor

    • Three component model temperature floor and diffusion

    • Metzger 2017

    • Surrogates of different numerical simulations

  • Supernova models: Can output in flux density/magnitude/bolometric luminosity

    • Arnett

    • CSM

    • CSM + Ni

    • Basic magnetar powered

    • General magnetar powered

    • magnetar + nickel

    • SLSN

    • exponential powerlaw

    • SNcosmo

    • Shock cooling + Arnett

  • Shock models: Can output in flux density/magnitude/bolometric luminosity

    • Shock cooling

    • Thermal synchrotron

    • Shocked cocoon

  • Magnetar driven ejecta models:

    • Metzger magnetar driven kilonova

    • Mergernova

    • Trapped magnetar

    • General magnetar driven kilonova

    • General mergernova

    • Magnetic field mergernova

    • Magnetic field metzger driven kilonova

  • Millisecond magnetar models

    • vacuum dipole magnetar

    • basic magnetar

    • gw + em magnetar

    • magnetar with variable braking index

    • evolving magnetar

    • magnetar with radiative losses

    • collapsing magnetar

    • piecewise magnetar

  • Tidal disruption models

    • Simple analytic fallback

    • Cooling envelope (Metzger 2022)

    • Gaussian rise + cooling envelope (Sarin and Metzger 2023)

  • Phenomenological and fireball models

    • 1-6 component piecewise power law

    • exponential_powerlaw

    • Gaussian rise

  • Combined models

    • Interface to combine any optical transient and afterglow model

    • Tophat + Stratified kilonova

    • Tophat + Two component kilonova

    • Tophat + Arnett

We note that these models can output in flux_density or magnitude set by the keyword argument output_format or in integrated flux or luminosity using the appropriate luminosity/flux function.

Alongside these models we also include some general models which can many of the above models as a base_model

  • Homologous expansion

  • Thin shell

  • Extinction models

  • Phase models

  • Phase + extinction models

  • Integrated flux afterglow models

  • Gaussian process base model:

Using redback models as functions

All models in redback are implemented as functions with minimal dependencies. This means that users can simply use these functions by themselves as you would any other python function. All users need to do is pass into the function a time array and any other parameter required by the function. In this way, users can use redback to just explore the impact of different parameters on the light curve and better understand the physics.

For example:

from redback.constants import day_to_s
from redback.model_library import all_models_dict
import numpy as np

model = 'arnett_bolometric'

function = all_models_dict[model]
time = np.logspace(2, 8, 100)/day_to_s
bolometric_luminosity = function(time, f_nickel=0.6,
                    mej=30, vej=1000, kappa=2, kappa_gamma=1e2)

Here we use all_models_dict to provide a simple way to access the relevant function. A user could of course just import the function themselves.

Users can also use the prior objects to get a simulation of the light curves predicted by the function for randomly drawn samples from the prior.

from redback.constants import day_to_s
from redback.model_library import all_models_dict
from redback.priors import get_priors
import numpy as np
import pandas as pd

model = 'arnett_bolometric'
priors = get_priors(model=model, data_mode='luminosity')
samples = pd.DataFrame(priors.sample(100))
function = all_models_dict[model]
time = np.logspace(2, 8, 100)/day_to_s

bolometric_luminosity = function(time, **samples.iloc[0])

Remember that the priors are simply a dictionary so users could also just pass a dictionary/dataframe they created themselves as well.

Users could also sample a lot of different draws from the prior at once (in the above we randomly drew 100 samples) and then loop through them to simulate a population. Remember that we can also place arbitrary constraints on the priors to make a really specific population/simulation. For example, we could make a constraint that all priors in the population were brighter than 24th mag at peak or something else. Almost any time of constraint is possible, as long as it can be written mathematically. Please look at prior documentation for more details on constraints. We could also use the redback simulation module to simulate realistic lightcurves of these drawn parameters in a real survey. Helping capture selection effects in even more detail.

Modifying redback models

A lot of the physics in different redback models is set by default. However, several pieces of physics in various models can be changed by either passing your own function/class (see dependency injections), by switching the default argument with something else already implemented in redback, or changing a keyword argument.

The specific physics that can be changed:

  • Jet spreading on/off

  • Whether to infer lorentz factor in afterglow models

  • Whether to turn on/off pair cascades

  • Whether to turn on/off neutron precursor emission

  • Different ejecta relations: See relations already implemented here.

  • Different equations of states: See eos already implemented here.

  • Different interaction process: See processes already implemented here.

  • Different photosphere: See photospheres already implemented here.

  • Different SED: See SED’s already implemented here.

  • Gamma-ray leakage

  • Engines with different energy injection rates

We encourage users to add more of these physics switches, which is another easy way to contribute to redback.

Extra kwargs and output formats in redback models

All redback models have a set of extra keyword arguments that can be passed to the function. For a specific model, users can see the extra keyword arguments by looking at the docstring of the function. These extra variables are passed in as a dictionary via

extra_kwargs = {'key1': value1, 'key2': value2}
function(time, **extra_kwargs)

And can allow for more flexibility in the models while keeping the interface of the function simple for the end user.

For several models we also allow users to output the light curve in different formats. For example, users can output the light curve in flux_density or magnitude by passing in those via the keyword argument output_format. Or spectra itself which will output a multidimensional array of the spectra at each time. Or sncosmo_source which will output the sncosmo source object for the model and the users can then use this to make their own plots or look at model with an SNCosmo interface.

We note that for afterglow models we generally assume the magnitude conversion is a simple conversion from flux density to magnitude, ignoring the affect of the full spectrum. This can be done in the proper way for the afterglow_sed model variants. While for other transient models, the magnitude/flux values are calculated using the full bandpass/spectrum. The flux_density output for all models is the flux density at the effective frequency of the filter.

Redback assumes flux_density is always in mJy, luminosity is always in erg/s, and magnitude is always in AB mag. Flux is always in erg/s/cm^2.