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 and semi-analytical models. In redback_surrogates we provide access to surrogates built with machine learning techniques to hydrodynamical simulations. This package provides the interface and the data to use such surrogate models. While this package is standalone and all models can be used through just this package, without using redback, we recommend using them through redback anyway. We note that many of these surrogates are available elsewhere, but this package just provides one convenient interface and location.

Specifically, the surrogate models included in this package are:

For a full upto date list of models implemented in redback_surrogates, look at the API. Note that many of these models can either output the spectra or the magnitude/flux at specific bands due to the limitations of the surrogates. These are noted in the documentation but for models with spectra, we recommend using these models through redback package as that provides the interface to convert the spectra to magnitudes/fluxes.

Downloading additional data

Some models in redback_surrogates require additional data to be downloaded before they can be used. This can be done simply by using the redback_surrogates.download_data() function. This function will download the data required for all models in redback_surrogates that require additional data.

import redback_surrogates as rs
data_dir = rs.data_management.download_surrogate_data()
if data_dir:
    print(f"Surrogate data is available at: {data_dir}")

This will download the data to the surrogate_data folder where redback_surrogates is installed. The files are hosted on Zenodo, and the download will be cached so that it does not need to be downloaded again and checked against a hash to ensure integrity.

Contributing new models

If you want to contribute a new model to redback_surrogates, please follow the instructions in the contributing guide. If your surrogate model requires additional data e.g., large torch files to be used, please ensure that you provide a way to download this data using the download_surrogate_data() function.

Using redback_surrogate models as functions

All models in redback_surrogate 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. Note that we are showing the interface through redback here to take advantage of redback allowing output in any band/output_format. The raw spectra interface is available through redback_surrogates as well. Please look at the examples and the API documentation for more details on how to use the models directly through redback_surrogates.

For example:

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

model = 'bulla_bns_kilonovanet'

function = all_models_dict[model]
output_format = 'magnitude'
bands = 'lsstu'
priors = redback.priors.get_priors(model=model)
time = np.logspace(2, 8, 100)/day_to_s
magnitude = function(time, output_format=output_format, bands=bands, **priors.sample())

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. We also use priors.sample() to randomly sample a set of parameters from the prior distributions for the model. Each function provided in code:redback_surrogates has a corresponding prior provided in redback.

Users can also use the prior objects to get a simulation of the light curves predicted by the function for many more randomly drawn samples from the prior. The priors are simply a dictionary so users could also just pass a dictionary/dataframe they created themselves as well. Furthermore, 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 through the redback documentation for more details on how to do these extra tricks.

Note that with surrogates, the prior ranges are determined by the trained model. Setting priors outside this validity domain will either not work or potentially give unreliable results. We recommend using the priors provided by redback for the models in redback_surrogates to avoid this issue. Reading the papers is generally a nice place to start :)