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.