grale.paramdesc

This module contains tools for parametric inversion: something to analyze a description of a lens model that can be optimized parametrically, and a routine to start such a description based on an existing lens model.

grale.paramdesc.getSupportedLensTypes()

List which gravitational lens types are recognized in the parametric description.

grale.paramdesc.createParametricDescription(lens, massUnitString='MASS_SUN', angularUnitString='ANGLE_ARCSEC', asString=True, convertValueFunction=None)

Create a basic representation of a parametric lens model, based on the lens model in lens. The result is a string which represents python code and can be saved to a file for further editing. This result has no parameters that can change, so it will need to be adjusted.

To make the description more readable, values for masses will be represented as a value times the mass unit, which needs to be represented as string in massUnitString. Similarly, angular values will be represented using angularUnitString.

By default a single large string is returned, if a list of separate lines is more covenient, the asString parameter can be set to False.

The convertValueFunction is a callback that can be used to convert a fixed value to a variable one. The parameters are:

  • value: the value itself

  • lensName: this is a list, of which the last entry specifies the name of the current (sub) model. This list could simply be [ "NSIELens" ] for a simple lens, or e.g. [ "CompositeLens", "lens_0", "NSIELens" ] for a more complex model.

  • paramName: the name of the parameter, for example "mass"

  • fullParams: the full lens model parameters of the current (sub) model. This could be helpful if you need more information about which submodel is being considered.

The return value can be:

  • a value: in that case this is a fixed parameter

  • a list [ value, fraction ] to initialize the parameter to vary between bounds specified by the fraction, or just [ value ] if the default fraction is to be used when calling analyzeParametricLensDescription(). If a third fraction is specified, e.g. [ value, fraction, hardfraction ], then that will be used for the hard bounds.

  • a dictionary containing entries for "initmin" and "initmax", and optionally "hardmin" and "hardmax".

grale.paramdesc.analyzeParametricLensDescription(parametricLens, Dd, defaultFraction, clampToHardLimits=False)

Analyze the parametric lens description in parametricLens, which should be a dictionary, for a lens at angular diameter distance Dd. In case a parameter is set to change with some fraction about a value, defaultFraction is used if no specific fraction is specified. By default, an error will be generated if some initial value bounds exceed the hard bounds, but if clampToHardLimits is set to True, the hard limit will be used as bound for the initial value.

Returns a dictionary with the following entries:

  • templatelens: a lens model constructed from the description

  • floatparams: the floating point parameters for the model, some of which can be changed.

  • scales: itself a dictionary with entries for the angular and potential scales that are used.

  • variablefloatparams: describes which of the floating point parameters can be changed, and within which boundaries.

An example parametricLens object:

parametricLens = {
  "type": "MultiplePlummerLens",
  "params": [
     { 
        # This represents a fixed value 
        "x": 2*ANGLE_ARCSEC, 
        # This specifies an initial value that can change within 20% of the specified one.
        # During optimization these bounds can be exceeded
        "y": [ 1*ANGLE_ARCSEC, 0.20 ] 
        # Also a variable that can change, the amount determined by `defaultFraction`
        "mass": [ 1e13*MASS_SUN ],
        # When three entries are specified, the second is again to determine the
        # range of initial values, the last one is a fraction to fix hard limits.
        "width": [ 3*ANGLE_ARCSEC, 0.1, 0.5 ]
     },
     {
         # Here the initial values will be chosen in the specified interval
         "x": { "initmin": -2*ANGLE_ARCSEC, "initmax": 2*ANGLE_ARCSEC },
         # Similar, but hard bounds for the parameter are specified as well
         # In case none are specified, default values are used for these,
         # depending on the parameter type. Specifying them overrides the
         # defaults.
         "y": { "initmin": -2*ANGLE_ARCSEC, "initmax": 2*ANGLE_ARCSEC,
                "hardmin": -3*ANGLE_ARCSEC, "hardmax": 3*ANGLE_ARCSEC },
         # And some fixed values
         "mass": 1e13*MASS_SUN,
         "width": 2*ANGLE_ARCSEC
     }
  ]
}