============
Models
============

In :code:`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 :code:`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 :code:`redback`,
we recommend using them through :code:`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:

- Afterglow models

    - Surrogate built on top of `tophat_redback <https://redback.readthedocs.io/en/latest/api/redback.transient_models.afterglow_models.tophat_redback.html#redback.transient_models.afterglow_models.tophat_redback>`_.

- Kilonova models

    - Surrogate for Kasen BNS using `kilonovanet <https://github.com/klukosiute/kilonovanet>`_.
    - Surrogate for Bulla BNS using `kilonovanet <https://github.com/klukosiute/kilonovanet>`_.
    - Surrogate for Bulla NSBH using `kilonovanet <https://github.com/klukosiute/kilonovanet>`_.

- Supernova models

    - Surrogate for r-process from collapsars (`Barnes and Metzger 2022 <https://ui.adsabs.harvard.edu/abs/2022ApJ...939L..29B/abstract>`_) (Not yet implemented into master).
    - Surrogates for Type II supernovae (Sarin et al. 2025), based on simulations in `Moriya et al. 2024 <https://ui.adsabs.harvard.edu/abs/2023PASJ...75..634M/abstract>`_

For a full upto date list of models implemented in :code:`redback_surrogates`, look at the `API <https://redback_surrogates.readthedocs.io/en/latest/>`_.
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 :code:`redback` package as that provides the interface to convert the spectra to magnitudes/fluxes.

Downloading additional data
-------------------------

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

.. code:: python

    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 :code:`redback_surrogates`, please follow the instructions in the `contributing guide <https://redback.readthedocs.io/en/latest/contributing.html>`_.
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 :code:`download_surrogate_data()` function.

Using :code:`redback_surrogate` models as functions
-------------------------

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

For example:

.. code:: python

    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 :code:`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 :code:`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 :code:`redback` for the models in :code:`redback_surrogates` to avoid this issue.
Reading the papers is generally a nice place to start :)



