Internals

These are various modules, classes and functions that are probably not useful directly, as they are for internal use only. They are included in this documentation, well, to be able to view the documentation.

grale.inversionparams module

This module contains classes which will contain various settings for the lens inversion method. They form the bridge between the Python side of the code, and the C++ one.

class grale.inversionparams.ConfigurationParametersException

This exception is raised in case somethings goes wrong in the ConfigurationParameters class.

class grale.inversionparams.ConfigurationParameters

This class describes configuration parameters for a specific lens inversion module. It is the Python link to the similarly named C++ class.

__init__(parameterDict=None)

Initializes this object, storing the key/value entries from parameterDict (if present). Note that not all dictionaries are valid: the keys should be strings, and the values can be integers, strings, floating point values or boolean values, or 1D arrays thereof.

asDict()

This returns the key/value pairs stored in this instance as a dictionary.

static fromBytes(paramBytes)

This method takes in the binary representation of the key/value pairs in paramBytes, and stores them internally. It is needed to load the information from a C++ version of the class.

class grale.inversionparams.ConvergenceParametersException

This exception is raised in case somethings goes wrong in the ConvergenceParameters class.

class grale.inversionparams.ConvergenceParameters

This class is used to control the settings that determine when the GA switches between large and small mutations, what the small mutation size is, and when the GA should terminate. It is controlled with a dictionary with these entries:

  • maximumgenerations: if the number of generations of the GA exceeds this number, it will stop (defaults to 16384).

  • historysize: to determine how the fitness measures are converging, the current fitness values are compared to those of a number of generations ago. This number is what’s described by the historysize value (defaults to 250). If the relative change of all fitness measures (in a multi-objective setting) are below a certain threshold, the convergence system resets and the GA advances to the next mutation size (or stops if none are left). Note that each time the convergence system starts or resets, nothing can happen untill historysize generations have passed since no other fitness values can be compared to yet.

  • convergencefactors: this contains the thresholds mentioned above; the default is [ 0.1, 0.05 ]. This arrays needs to have the same length as the following one, which controls the mutation sizes.

  • smallmutationsizes: this array, of the same length as convergencefactors, controls the size of the mutations that are allowed. A negative value means that mutated basis function weights will simply be reinitialized, a positive value means that the value of a basis function weight will be changed randomly by an amount that is proportional to the weight, where this positive value specifies the proportionality factor. The default value is [ -1.0, 0.1 ].

The default values imply that initially, the random mutations are used, since smallmutationsizes[0] is negative. For the first 250 generations of the GA, no special action will be taken, but once this historysize amount of generations have passed, the fitnesses will be compared to those from 250 generations ago. If the relative change is less than 0.1 (the value in convergencefactors[0]), the mutations are set to the smaller, relative mutations with a factor of 0.1 (the value in smallmutationsizes[1]. For the first 250 generations afterwards, no special action will be taken, but beyond that the relative fitness change is calculated again. If it is less than 0.05 (convergencefactors[1]), the algorithm will stop.

By controlling all these parameters, you could add an extra step with even smaller mutations for example.

__init__(*args, **kwargs)
toBytes()

Returns a byte array that stores the settings contained in this instance.

class grale.inversionparams.InversionParametersException

This exception is raised if something goes wrong with the lens inversion parameters.

class grale.inversionparams.LensInversionParametersSinglePlaneCPU

An internal representation of the parameters for the lens inversion procedure, needed to communicate with the C++ based inversion code.

__init__(maxGen, imageList, gridInfoOrBasisFunctions, Dd, zd, massScale, allowNegativeValues=False, baseLens=None, sheetSearch='nosheet', fitnessObjectParameters=None, massScaleSearchType='regular')

Creates an instance containing the input for the lens inversion method.

Parameters:

  • imageList: this describes the input images, and should be a list of dictionaries where each dictionary has the following entries:

    • images: an ImagesData instance, containing information about the extended images, point images or null space for example.

    • Ds: angular diameter distance from source to observer for this entry

    • Dds: angular diameter distance between source and lens for this entry

    • params (optionally): extra parameters that belong to this entry, can be a list or a dictionary.

  • gridInfoOrBasisFunctions: for the inversion method you can either provide a grid as input, from which basis functions will be derived, or you can specify the basis functions directly.

    In the first case, the input should be a dictionary with the following entries:

    • gridSquares: a list of squares in the grid. Each entry is a dictionary with center and size keys. This size is used directly as the width of the used basis function.

    • useWeights (optional, defaults to False): by default, the initial mass of a basis function is the same for a small or large grid cell. If set to True, it will be adjusted based on the size of the grid cell, so that smaller cells contain less mass.

    • basisFunctions (optional, defaults to plummer): can be plummer, square or gaussian

    In the second case, it should be a list of dictionaries, where each dictionary describes a basis function and should contain the entries:

    • lens: the lens model for this basis function, interpreted as centered on the origin.

    • mass: the relevant lensing mass of this basis function. This will be used to adjust weights to lie in the relevant total mass range.

    • center: the center (x,y) coordinates at which the lens model should be positioned.

  • Dd: the angular diameter distance to the lens

  • zd: the redshift of the lens, important when using time delay information

  • massScale: a mass scale for the optimization to use. The weights of the basis functions will be adjusted to lie in a certain range around this scale (the width of the range depends on massScaleSearchType)

  • allowNegativeValues: by default, only positive weights will be assigned to the basis functions used in the optimization. If negative weights are allowed as well (can be useful when starting from a certain baseLens), this can be set to True.

  • baseLens: if present, the lens inversion method will look for additions to this model. The allowNegativeValues argument may be useful in this case.

  • sheetSearch: can be nosheet, genome or a lens model, and indicates if a mass sheet basis function should be present in the lens inversion method.

  • fitnessObjectParameters: parameters that should be passed to the inversion module that will be used.

  • massScaleSearchType: default is "regular", but if set to "wide", a

    wider range of masses will be probed around the specified massScale argument. In typical cases, this is not needed, but may be useful when trying to combine strong and weak lensing information. It can also be set to "nosearch" to disable the search for an appropriate scaling of the basis functions. It is also possible to set to a dictionary with the following entries, mainly for testing purposes:

    • startFactor

    • stopFactor

    • numIterations

    • firstIterationSteps

    • nextIterationSteps

static fromBytes(bytes b)

Creates an instance of this class based on a binary representation. This is the inverse function of toBytes().

toBytes()

Returns a byte array that stores the settings contained in this instance. This could be processed again by fromBytes().

class grale.inversionparams.LensInversionParametersMultiPlaneGPU

An internal representation of the parameters for the lens multi-plane inversion procedure, needed to communicate with the C++ based inversion code.

__init__(cosmology=cosmology.Cosmology(0.7, 0.3, 0, 0.7), basisLensesAndRedshifts=[], imagesAndRedshifts=[], massEstimate=0, sheetSearch='nosheet', fitnessObjectParameters=None, maxGen=0, allowNegativeWeights=False, massScaleSearchType='regular', deviceIndex='rotate')

Parameters:

  • cosmology: the cosmological model to use to transform redshifts into angular diameter distances.

  • basisLensesAndRedshifts: a list of dictionaries with entries z and lenses, representing the lens planes and the basis functions therein. Each entry in the lenses list should be a dictionary with lens, center and mass entries, as with the single plane inversion.

  • imagesAndRedshifts: a list of dictionaries, each having an entry z describing the redshift of the images, images with an ImagesData instance, and params listing additional parameters (such as a type).

  • baseLensForPlane: if present, this list should contain one base lens (possibly None) for each lens plane.

  • massEstimate: a mass scale for the optimization to use. The weights of the basis functions will be adjusted to lie in a certain range around this scale (the width of the range depends on massScaleSearchType)

  • sheetSearch: can be nosheet or genome.

  • fitnessObjectParameters: parameters that should be passed to the inversion module that will be used.

  • allowNegativeWeights: by default, only positive weights will be assigned to the basis functions used in the optimization. If negative weights are allowed as well, this can be set to True.

  • massScaleSearchType: default is "regular", but if set to "wide", a wider range of masses will be probed around the specified massScale argument. In typical cases, this is not needed, but may be useful when trying to combine strong and weak lensing information. It can also be set to "nosearch" to disable the search for an appropriate scaling of the basis functions. It is also possible to set to a dictionary with the following entries, mainly for testing purposes:

    • startFactor

    • stopFactor

    • numIterations

    • firstIterationSteps

    • nextIterationSteps

  • deviceIndex: this multi-plane inversion uses a GPU to back-project the image data, and by setting a specific number, a specific device can be specified. To allow multiple GPUs to be used automatically, you can leave this to "auto" and use an inverter with as many processes as you have GPUs.

static fromBytes(bytes b)

Creates an instance of this class based on a binary representation. This is the inverse function of toBytes().

toBytes()

Returns a byte array that stores the settings contained in this instance. This could be processed again by fromBytes().

class grale.inversionparams.GAParameters

General parameters for the genetic algorithm.

__init__(selectionpressure=2.5, elitism=True, alwaysincludebest=True, crossoverrate=0.9, smallmutationsize=-1)

Initializes an object representing general parameters for the genetic algorithm. For more information about the meaning of the arguments, refer to the documentation of the library that’s used for the genetic algorithm.

TODO: update this documentation