=================
Adding New Models
=================

One goal of Gravelamps is extensibility, so we have tried to leave open ways to
add additional models to Gravelamps with minimal effort on the part of
developers.

We ask that additional models go in the same place as the currently implemented
models, which is ultimately inside of `gravelamps.models`. This is either done
directly for those models fully implemented in python, or is done by compiling
a C-extension for C/C++ implementations such as the isolated point mass or SIS
models.

What Gravelamps ultimately expects is that the model has an `amplification`
function. This function can take any number of parameters, but must take as its
first parameter a frequency array---by default this is assumed to be the
dimensionless frequency, w. This array will by default be computed using the
`frequency_to_dimensionless_frequency` function in
`gravelamps.core.conversion`, but can be overwritten by adding a
`frequency_to_dimensionless_frequency` function in your module. If you prefer
to use the frequency array directly as is the case for the phenomenological
model you need simply add `no_conversion_to_dimensionless_frequency = True` in
the `lens` section of INI files using this model.

For the remaining parameters which you intend to sample over, you simply add a
`lens_parameter_keys` set or function to your module. If none is provided, the
default list is `lens_mass`, `lens_fractional_distance`, and `source_position`
which are the defaults used by point mass, SIS, and NFW. One can instead sample
over `redshifted_lens_mass` and `source_position` by inlcuding
`use_redshifted_lens_mass = True` in the `lens` section of INI files.

If you have arguments that are *optional* for your amplification function such
as the `geo_switch` option used by the point mass model, you should not include
these in the `lens_parameter_keys` but instead through the `extra_lens_keys`
option in the INI file. Pass as a list of names, with an assoicated either
single value or full prior in the prior section of the INI and they will be
applied appropriately.

For data generation using `gravelamps_generate_lens`, additional arguments to
the amplification function can be passed through the `data_generation_kwargs`
option in the `lens` section of the INI which will take a python formatted
dictionary and pass the kwargs through to the generation function. By default
this will simply call the amplification factor function over the specified
range of dimensionless frequency and source position. However, should you have
a more specific implementation in mind, for instance the parallelised methods
used by the C++ implementations in Gravelamps, the function that is used can be
changed by including a `generate_data` function in your module which can be
used in combination with the above to significantly overhaul the functionality.
The generate data function is expected to take as its first four arguments the
dimensionless frequency, source position, amplification factor real value and
amplification factor imaginary value file paths and then may take an arbitrary
number of kwargs given using the above.