Models

MOSFiT has been designed to be modular and easily modifiable by users to alter, combine, and create physical models to approximate the behavior of observed transients. On this page we walk through some basics on how a user might alter an existing model shipped with the code, and how they could go about creating their own model.

List of built-in models

Model name	Description	Reference(s)
`default`	Nickel-cobalt decay	1994ApJS…92..527N
`csm`	Interacting CSM-SNe	2013ApJ…773…76C, 2017ApJ…849…70V, 2020RNAAS…4…16J
`csmni`	CSM + NiCo decay	See `default` & `csm`
`exppow`	Analytical engine
`ia`	NiCo decay + I-band (EXPERIMENTAL) [*]
`ic`	NiCo decay + radio (EXPERIMENTAL) [*]
`magnetar`	Magnetar engine w/ simple SED	2017ApJ…850…55N
`magni`	Above + NiCo decay
`rprocess`	Kilonova	2017ApJ…851L..21V
`kilonova`	Kilonova	2017ApJ…851L..21V
`bns`	Kilonova + binary params + angle	2021MNRAS.505.3016N
`bns_generative`	bns model but NS radius rather than deformability	2021MNRAS.505.3016N
`bns_magnetar`	bns_generative with magnetar remnant	2023arXiv230911340S
`nsbh`	Kilonova from NS-BH binary parameters	2023MNRAS.526.4585G
`nsbh_generative`	nsbh model but masses and radii rather than deformability	2023MNRAS.526.4585G
`slsn`	Magnetar + modified SED + constraints	2017ApJ…850…55N
`slsnni`	Magnetar + NiCo decay	See `slsn` & `default`
`shockni`	Shock cooling + NiCo decay	Moore et al., in preparation
`fallback`	Fallback accretion engine
`sesn_sedona`	SESN with SEDONA SED emulator	Yadavalli et al. 2026
`tde`	Tidal disruption events	2018arXiv180108221M

sesn_sedona needs the optional sedona extra (PyTorch): uv sync --extra sedona or pip install 'mosfit[sedona]'. Other models do not import torch. A local TDE catalog fixture for tests and examples is mosfit/tests/PS1-10jh.json (Open TDE Catalog JSON; no network fetch).

Every other model in the table has a small simulated event under mosfit/tests/events (sim_<model>.json), which the test suite fits to keep each transient type covered. Those fixtures are light curves the models generated themselves, not observations, and are regenerated with python mosfit/tests/make_event_fixtures.py. sim_default is also mirrored as sim_default.csv to exercise the ASCII converter.

Altering an existing model

For many simple alterations to a model, such as adjusting input priors, setting variables remain free and which should be fixed, and adding/removing modules to the call stack, the user only needs to modify copies of the model JSON files. For these sorts of minor changes, no Python code should need to be modified by the user!

For this example, we’ll presume that the user will be modifying the slsn model. First, the user should create a new run directory and run MOSFiT there once to copy the model JSON files to that run directory:

mkdir slsn_run
cd slsn_run
python -m mosfit -m slsn

After running, the user will notice four directories will have been created in the run directory: models, modules, jupyter, and products. models will contain a clone of the models directory structure, with the parameters.json files for each model copied into each model folder, modules contains a clone of the modules directory structure, etc.

Changing parameter priors

From your run directory, navigate into the models/slsn directory and edit the parameters.json file in your favorite text editor:

cd models/slsn
vim parameters.json

You’ll notice that parameters.json file is fairly bare-bones, containing only a list of model parameters and their allowed value ranges:

{
    "nhhost":{
        "min_value":1.0e16,
        "max_value":1.0e23,
        "log":true
    },
    "Pspin":{
        "min_value":1.0,
        "max_value":10.0
    },
    "Bfield":{
        "min_value":0.1,
        "max_value":10.0
    },
    "Mns":{
        "min_value":1.0,
        "max_value":2.0
    },
}

Now, change the range of allowed neutron star masses to something else:

{
    "Mns":{
        "min_value":1.5,
        "max_value":2.5
    },
}

Congratulations! You have just modified your first MOSFiT model. Even a small prior change yields a distinct model fingerprint from the bundled default—which is desirable when you version or publish fits so others can verify which physics setup was run.

You can also use more complex priors within the same file. For example:

{
"Mns":{
    "class":"gaussian",
    "mu":1.4,
    "sigma":0.4,
    "min_value":0.1,
    "max_value":3.0,
    "log":false
}
}

A list of available priors is below; for all prior types, min_value and max_value specify the minimum and maximum allowed parameter values, and log will apply the prior to the log transform of the parameter.

Prior name	Equation	Additional parameters
`parameter`	\(\Pi\sim {\rm constant}\)
`gaussian`	\(\Pi\sim \exp\left(\frac{-(x-\mu)^2}{2\sigma^2}\right)\)	\(\mu\) (`mu`), \(\sigma\) (`sigma`)
`powerlaw`	\(\Pi\sim x^{-\alpha}\)	\(\alpha\) (`alpha`)

Swapping modules

Let’s say you want to modify the SLSN model such that transform applied to the input engine luminosity is not diffusion, but instead viscosity (if the light of a SLSN was say filtered through an accretion disk rather than a dense envelope). To make this change, the user would want to swap out the diffusion module used by slsn for the viscous module. This can be accomplished by editing the slsn.json model file. The model files are not copied into the model directories by default (as they may change from version to version of MOSFiT), but a README file with the full path to the model is copied to all model folders to make it easy for the user to copy the relevant JSON files:

cd models/slsn
cp $(head -1 README)/* .
vim slsn.json

To swap diffusion for viscous, the user would remove the blocks of JSON that refer to the diffusion module:

{
    "kappagamma":{
        "kind":"parameter",
        "value":10.0,
        "class":"parameter",
        "latex":"\\kappa_\\gamma\\,({\\rm cm}^{2}\\,{\\rm g}^{-1})"
    },
    "diffusion":{
        "kind":"transform",
        "inputs":[
            "magnetar",
            "kappa",
            "kappagamma",
            "mejecta",
            "texplosion",
            "vejecta"
        ]
    },
    "temperature_floor":{
        "kind":"photosphere",
        "inputs":[
            "texplosion",
            "diffusion",
            "temperature"
        ]
    },
    "slsn_constraints":{
        "kind":"constraint",
        "inputs":[
            "mejecta",
            "vejecta",
            "kappa",
            "tnebular_min",
            "Pspin",
            "Mns",
            "diffusion",
            "texplosion",
            "redshift",
            "alltimes",
            "neutrino_energy"
        ]
    },
}

and replace them with blocks appropriate for viscous:

{
    "Tviscous":{
        "kind":"parameter",
        "value":1.0,
        "class":"parameter",
        "latex":"T_{\\rm viscous}"
    },
    "viscous":{
        "kind":"transform",
        "inputs":[
            "magnetar",
            "texplosion",
            "Tviscous"
        ]
    },
    "temperature_floor":{
        "kind":"photosphere",
        "inputs":[
            "texplosion",
            "viscous",
            "temperature"
        ]
    },
    "slsn_constraints":{
        "kind":"constraint",
        "inputs":[
            "mejecta",
            "vejecta",
            "kappa",
            "tnebular_min",
            "Pspin",
            "Mns",
            "viscous",
            "texplosion",
            "redshift",
            "alltimes",
            "neutrino_energy"
        ]
    },
}

As can be seen above, this involved removal of definitions of free parameters that only applied to diffusion (kappagamma), the addition of a new free parameter for viscous (Tviscous), and replacement of various inputs that depended on diffusion with viscous.

The user should also modify the parameters.json file to remove free parameters that are no longer in use:

{
    "kappagamma":{
        "min_value":0.1,
        "max_value":1.0e4,
        "log":true
    },
}

and to the define the priors of their new free parameters:

{
    "Tviscous":{
        "min_value":1.0e-3,
        "max_value":1.0e5,
        "log":true
    },
}

Creating a new model

If users would like to create a brand new model for the MOSFiT platform, it is easiest to duplicate one of the existing models that most closely resembles the model they wish to create.

If you go this route, we highly recommend that you fork MOSFiT on GitHub and clone your fork, with development being done in the cloned repository:

git clone https://github.com/your_github_username/MOSFiT.git
cd MOSFiT

Copy one of the existing models as a starting point:

cp -R mosfit/models/slsn mosfit/models/my_model_that_explains_everything

Inside this directory are two files: a model_name.json file and a parameters.json file. We must edit both files to run our new model.

First, the model_name.json file should be edited to include your model’s:

Parameters
Engine(s)
Diffusion prescription
Photosphere prescription
SED prescription
The photometry module

Optionally, your model file can also include an extinction prescription.

Then, you need to edit the parameters.json to include the priors on all of your model parameters. If no prior is specified, the variable will be set to a constant.

You can invoke the model using:

mosfit -m my_model_that_explains_everything

If your model requires a new engine, you can create this engine by again copying an existing engine:

cp mosfit/modules/engines/nickelcobalt.py mosfit/modules/engines/my_new_engine.py

Then plug this engine into your model’s json file.