lenstronomy.Workflow package — lenstronomy 1.9.1 documentation

# lenstronomy.Workflow package

## Submodules

## lenstronomy.Workflow.alignment_matching module

class lenstronomy.Workflow.alignment_matching.AlignmentFitting(multi_band_list, kwargs_model, kwargs_params, band_index=0, likelihood_mask_list=None)

  Bases: `object`

  class which executes the different sampling methods

  pso(n_particles=10, n_iterations=10, lowerLimit=- 0.2, upperLimit=0.2, threadCount=1, mpi=False, print_key='default')

    returns the best fit for the lense model on catalogue basis with particle swarm optimizer

class lenstronomy.Workflow.alignment_matching.AlignmentLikelihood(multi_band_list, kwargs_model, kwargs_params, band_index=0, likelihood_mask_list=None)

  Bases: `object`

  computeLikelihood(ctx)
  static get_args(kwargs_data)
    Parameters

      kwargs_data –

    Returns

  likelihood(a)
  property num_param
  setup()
  update_data(args)
    Parameters

      args –

    Returns

  update_multi_band(args)
    Parameters

      args – list of parameters

    Returns

      updated multi_band_list

## lenstronomy.Workflow.fitting_sequence module

class lenstronomy.Workflow.fitting_sequence.FittingSequence(kwargs_data_joint, kwargs_model, kwargs_constraints, kwargs_likelihood, kwargs_params, mpi=False, verbose=True)

  Bases: `object`

  class to define a sequence of fitting applied, inherit the Fitting class this is a Workflow manager that allows to update model configurations before executing another step in the modelling The user can take this module as an example of how to create their own workflows or build their own around the FittingSequence

  align_images(n_particles=10, n_iterations=10, lowerLimit=- 0.2, upperLimit=0.2, threadCount=1, compute_bands=None)

    aligns the coordinate systems of different exposures within a fixed model parameterisation by executing a PSO with relative coordinate shifts as free parameters

    Parameters

      - n_particles – number of particles in the Particle Swarm Optimization

      - n_iterations – number of iterations in the optimization process

      - lowerLimit – lower limit of relative shift

      - upperLimit – upper limit of relative shift

      - compute_bands – bool list, if multiple bands, this process can be limited to a subset of bands

    Returns

      0, updated coordinate system for the band(s)

  best_fit(bijective=False)
    Parameters

      bijective – bool, if True, the mapping of image2source_plane and the mass_scaling parameterisation are inverted. If you do not use those options, there is no effect.

    Returns

      best fit model of the current state of the FittingSequence class

  property best_fit_likelihood

    returns the log likelihood of the best fit model of the current state of this class

    Returns

      log likelihood, float

  property bic

    returns the bayesian information criterion of the model. :return: bic value, float

  fit_sequence(fitting_list)
    Parameters

      fitting_list – list of [[‘string’, {kwargs}], ..] with ‘string being the specific fitting option and kwargs being the arguments passed to this option

    Returns

      fitting results

  fix_not_computed(free_bands)

    fixes lens model parameters of imaging bands/frames that are not computed and frees the parameters of the other lens models to the initial kwargs_fixed options

    Parameters

      free_bands – bool list of length of imaging bands in order of imaging bands, if False: set fixed lens model

    Returns

      None

  kwargs_fixed()

    returns the updated kwargs_fixed from the update Manager

    Returns

      list of fixed kwargs, see UpdateManager()

  property likelihoodModule
    Returns

      Likelihood() class instance reflecting the current state of FittingSequence

  mcmc(n_burn, n_run, walkerRatio, n_walkers=None, sigma_scale=1, threadCount=1, init_samples=None, re_use_samples=True, sampler_type='EMCEE', progress=True, backup_filename=None, start_from_backup=False)

    MCMC routine

    Parameters

      - n_burn – number of burn in iterations (will not be saved)

      - n_run – number of MCMC iterations that are saved

      - walkerRatio – ratio of walkers/number of free parameters

      - n_walkers – integer, number of walkers of emcee (optional, if set, overwrites the walkerRatio input

      - sigma_scale – scaling of the initial parameter spread relative to the width in the initial settings

      - threadCount – number of CPU threads. If MPI option is set, threadCount=1

      - init_samples – initial sample from where to start the MCMC process

      - re_use_samples – bool, if True, re-uses the samples described in init_samples.nOtherwise starts from scratch.

      - sampler_type – string, which MCMC sampler to be used. Options are: ‘EMCEE’

      - progress – boolean, if True shows progress bar in EMCEE

    Returns

      list of output arguments, e.g. MCMC samples, parameter names, logL distances of all samples specified by the specific sampler used

  nested_sampling(sampler_type='MULTINEST', kwargs_run={}, prior_type='uniform', width_scale=1, sigma_scale=1, output_basename='chain', remove_output_dir=True, dypolychord_dynamic_goal=0.8, polychord_settings={}, dypolychord_seed_increment=200, output_dir='nested_sampling_chains', dynesty_bound='multi', dynesty_sample='auto')

    Run (Dynamic) Nested Sampling algorithms, depending on the type of algorithm.

    Parameters

      - sampler_type – ‘MULTINEST’, ‘DYPOLYCHORD’, ‘DYNESTY’

      - kwargs_run – keywords passed to the core sampling method

      - prior_type – ‘uniform’ of ‘gaussian’, for converting the unit hypercube to param cube

      - width_scale – scale the width (lower/upper limits) of the parameters space by this factor

      - sigma_scale – if prior_type is ‘gaussian’, scale the gaussian sigma by this factor

      - output_basename – name of the folder in which the core MultiNest/PolyChord code will save output files

      - remove_output_dir – if True, the above folder is removed after completion

      - dypolychord_dynamic_goal – dynamic goal for DyPolyChord (trade-off between evidence (0) and posterior (1) computation)

      - polychord_settings – settings dictionary to send to pypolychord. Check dypolychord documentation for details.

      - dypolychord_seed_increment – seed increment for dypolychord with MPI. Check dypolychord documentation for details.

      - dynesty_bound – see https://dynesty.readthedocs.io for details

      - dynesty_sample – see https://dynesty.readthedocs.io for details

    Returns

      list of output arguments : samples, mean inferred values, log-likelihood, log-evidence, error on log-evidence for each sample

  property param_class
    Returns

      Param() class instance reflecting the current state of FittingSequence

  psf_iteration(compute_bands=None, **kwargs_psf_iter)

    iterative PSF reconstruction

    Parameters

      - compute_bands – bool list, if multiple bands, this process can be limited to a subset of bands

      - kwargs_psf_iter – keyword arguments as used or available in PSFIteration.update_iterative() definition

    Returns

      0, updated PSF is stored in self.multi_band_list

  pso(n_particles, n_iterations, sigma_scale=1, print_key='PSO', threadCount=1)

    Particle Swarm Optimization

    Parameters

      - n_particles – number of particles in the Particle Swarm Optimization

      - n_iterations – number of iterations in the optimization process

      - sigma_scale – scaling of the initial parameter spread relative to the width in the initial settings

      - print_key – string, printed text when executing this routine

      - threadCount – number of CPU threads. If MPI option is set, threadCount=1

    Returns

      result of the best fit, the chain of the best fit parameter after each iteration, list of parameters in same order

  set_param_value(**kwargs)

    Set a parameter to a specific value. kwargs are below. :param lens: [[i_model, [‘param1’, ‘param2’,…], […]] :type lens: :param source: [[i_model, [‘param1’, ‘param2’,…], […]] :type source: :param lens_light: [[i_model, [‘param1’, ‘param2’,…], […]] :type lens_light: :param ps: [[i_model, [‘param1’, ‘param2’,…], […]] :type ps: :return: 0, the value of the param is overwritten :rtype:

  simplex(n_iterations, method='Nelder-Mead')

    Downhill simplex optimization using the Nelder-Mead algorithm.

    Parameters

      - n_iterations – maximum number of iterations to perform

      - method – the optimization method used, see documentation in scipy.optimize.minimize

    Returns

      result of the best fit

  update_settings(kwargs_model={}, kwargs_constraints={}, kwargs_likelihood={}, lens_add_fixed=[], source_add_fixed=[], lens_light_add_fixed=[], ps_add_fixed=[], cosmo_add_fixed=[], lens_remove_fixed=[], source_remove_fixed=[], lens_light_remove_fixed=[], ps_remove_fixed=[], cosmo_remove_fixed=[], change_source_lower_limit=None, change_source_upper_limit=None, change_lens_lower_limit=None, change_lens_upper_limit=None)

    updates lenstronomy settings “on the fly”

    Parameters

      - kwargs_model – kwargs, specified keyword arguments overwrite the existing ones

      - kwargs_constraints – kwargs, specified keyword arguments overwrite the existing ones

      - kwargs_likelihood – kwargs, specified keyword arguments overwrite the existing ones

      - lens_add_fixed – [[i_model, [‘param1’, ‘param2’,…], […]]

      - source_add_fixed – [[i_model, [‘param1’, ‘param2’,…], […]]

      - lens_light_add_fixed – [[i_model, [‘param1’, ‘param2’,…], […]]

      - ps_add_fixed – [[i_model, [‘param1’, ‘param2’,…], […]]

      - cosmo_add_fixed – [‘param1’, ‘param2’,…]

      - lens_remove_fixed – [[i_model, [‘param1’, ‘param2’,…], […]]

      - source_remove_fixed – [[i_model, [‘param1’, ‘param2’,…], […]]

      - lens_light_remove_fixed – [[i_model, [‘param1’, ‘param2’,…], […]]

      - ps_remove_fixed – [[i_model, [‘param1’, ‘param2’,…], […]]

      - cosmo_remove_fixed – [‘param1’, ‘param2’,…]

      - change_lens_lower_limit – [[i_model, [‘param_name’, …], [value1, value2, …]]]

    Returns

      0, the settings are overwritten for the next fitting step to come

  update_state(kwargs_update)

    updates current best fit state to the input model keywords specified.

    Parameters

      kwargs_update – format of kwargs_result

    Returns

      None

## lenstronomy.Workflow.psf_fitting module

class lenstronomy.Workflow.psf_fitting.PsfFitting(image_model_class)

  Bases: `object`

  class to find subsequently a better psf The method make use of a model and subtracts all the non-point source components of the model from the data. If the model is sufficient, then the data will be a (better) representation of the actual PSF. The method cuts out those point sources and combines them to update the estimate of the PSF. This is done in an iterative procedure as the model components of the extended features is PSF-dependent (hopefully not too much).

  Various options can be chosen. There is no guarantee that the method works for specific data and models.

  ‘stacking_method’: ‘median’, ‘mean’; the different estimates of the PSF are stacked and combined together. The choices are:

    ‘mean’: mean of pixel values as the estimator (not robust to outliers) ‘median’: median of pixel values as the estimator (outlier rejection robust but needs >2 point sources in the data

  ‘block_center_neighbour’: angle, radius of neighbouring point sources around their centers the estimates is ignored.

    Default is zero, meaning a not optimal subtraction of the neighbouring point sources might contaminate the estimate.

  ‘keep_error_map’: bool, if True, does not replace the error term associated with the PSF estimate.

    If false, re-estimates the variance between the PSF estimates.

  ‘psf_symmetry’: number of rotational invariant symmetries in the estimated PSF.

    =1 mean no additional symmetries. =4 means 90 deg symmetry. This is enforced by a rotatioanl stack according to the symmetry specified. These additional imposed symmetries can help stabelize the PSF estimate when there are limited constraints/number of point sources in the image.

  The procedure only requires and changes the ‘point_source_kernel’ in the PSF() class and the ‘psf_error_map’. Any previously set subgrid kernels or pixel_kernels are removed and constructed from the ‘point_source_kernel’.

  static combine_psf(kernel_list_new, kernel_old, factor=1.0, stacking_option='median', symmetry=1)

    updates psf estimate based on old kernel and several new estimates :param kernel_list_new: list of new PSF kernels estimated from the point sources in the image (un-normalized) :param kernel_old: old PSF kernel :param factor: weight of updated estimate based on new and old estimate, factor=1 means new estimate, factor=0 means old estimate :param stacking_option: option of stacking, mean or median :param symmetry: imposed symmetry of PSF estimate :return: updated PSF estimate and error_map associated with it

  cutout_psf(ra_image, dec_image, x, y, image_list, kernel_size, kernel_init, block_center_neighbour=0)
    Parameters

      - ra_image – coordinate array of images in angles

      - dec_image – coordinate array of images in angles

      - x – image position array in x-pixel

      - y – image position array in y-pixel

      - image_list – list of images (i.e. data - all models subtracted, except a single point source)

      - kernel_size – width in pixel of the kernel

      - kernel_init – initial guess of kernel (pixels that are masked are replaced by those values)

      - block_center_neighbour – angle, radius of neighbouring point sources around their centers the estimates is ignored. Default is zero, meaning a not optimal subtraction of the neighbouring point sources might contaminate the estimate.

    Returns

      list of de-shifted kernel estimates

  static cutout_psf_single(x, y, image, mask, kernel_size, kernel_init)
    Parameters

      - x – x-coordinate of point source

      - y – y-coordinate of point source

      - image – image (i.e. data - all models subtracted, except a single point source)

      - mask – mask of pixels in the image not to be considered in the PSF estimate (being replaced by kernel_init)

      - kernel_size – width in pixel of the kernel

      - kernel_init – initial guess of kernel (pixels that are masked are replaced by those values)

    Returns

      estimate of the PSF based on the image and position of the point source

  error_map_estimate(kernel, star_cutout_list, amp, x_pos, y_pos, error_map_radius=None, block_center_neighbour=0)

    provides a psf_error_map based on the goodness of fit of the given PSF kernel on the point source cutouts, their estimated amplitudes and positions

    Parameters

      - kernel – PSF kernel

      - star_cutout_list – list of 2d arrays of cutouts of the point sources with all other model components subtracted

      - amp – list of amplitudes of the estimated PSF kernel

      - x_pos – pixel position (in original data unit, not in cutout) of the point sources (same order as amp and star cutouts)

      - y_pos – pixel position (in original data unit, not in cutout) of the point sources (same order as amp and star cutouts)

      - error_map_radius – float, radius (in arc seconds) of the outermost error in the PSF estimate (e.g. to avoid double counting of overlapping PSF erros)

      - block_center_neighbour – angle, radius of neighbouring point sources around their centers the estimates is ignored. Default is zero, meaning a not optimal subtraction of the neighbouring point sources might contaminate the estimate.

    Returns

      relative uncertainty in the psf model (in quadrature) per pixel based on residuals achieved in the image

  error_map_estimate_new(psf_kernel, psf_kernel_list, ra_image, dec_image, point_amp, supersampling_factor, error_map_radius=None)

    relative uncertainty in the psf model (in quadrature) per pixel based on residuals achieved in the image

    Parameters

      - psf_kernel – PSF kernel (super-sampled)

      - psf_kernel_list – list of individual best PSF kernel estimates

      - ra_image – image positions in angles

      - dec_image – image positions in angles

      - point_amp – image amplitude

      - supersampling_factor – super-sampling factor

      - error_map_radius – radius (in angle) to cut the error map

    Returns

      psf error map such that square of the uncertainty gets boosted by error_map * (psf * amp)**2

  image_single_point_source(image_model_class, kwargs_params)

    return model without including the point source contributions as a list (for each point source individually)

    Parameters

      - image_model_class – ImageModel class instance

      - kwargs_params – keyword arguments of model component keyword argument lists

    Returns

      list of images with point source isolated

  static mask_point_source(x_pos, y_pos, x_grid, y_grid, radius, i=0)
    Parameters

      - x_pos – x-position of list of point sources

      - y_pos – y-position of list of point sources

      - x_grid – x-coordinates of grid

      - y_grid – y-coordinates of grid

      - i – index of point source not to mask out

      - radius – radius to mask out other point sources

    Returns

      a mask of the size of the image with cutouts around the position

  static point_like_source_cutouts(x_pos, y_pos, image_list, cutout_size)

    cutouts of point-like objects

    Parameters

      - x_pos – list of image positions in pixel units

      - y_pos – list of image position in pixel units

      - image_list – list of 2d numpy arrays with cleaned images, with all contaminating sources removed except the point-like object to be cut out.

      - cutout_size – odd integer, size of cutout.

    Returns

      list of cutouts

  psf_estimate_individual(ra_image, dec_image, point_amp, residuals, cutout_size, kernel_guess, supersampling_factor, block_center_neighbour)
    Parameters

      - ra_image – list; position in angular units of the image

      - dec_image – list; position in angular units of the image

      - point_amp – list of model amplitudes of point sources

      - residuals – data - model

      - cutout_size – pixel size of cutout around single star/quasar to be considered for the psf reconstruction

      - kernel_guess – initial guess of super-sampled PSF

      - supersampling_factor – int, super-sampling factor

      - block_center_neighbour –

    Returns

      list of best-guess PSF’s for each star based on the residual patterns

  update_iterative(kwargs_psf, kwargs_params, num_iter=10, keep_psf_error_map=True, no_break=True, verbose=True, **kwargs_psf_update)
    Parameters

      - kwargs_psf – keyword arguments to construct the PSF() class

      - kwargs_params – keyword arguments of the parameters of the model components (e.g. ‘kwargs_lens’ etc)

      - num_iter – number of iterations in the PSF fitting and image fitting process

      - keep_psf_error_map – boolean, if True keeps previous psf_error_map

      - no_break – boolean, if True, runs until the end regardless of the next step getting worse, and then reads out the overall best fit

      - verbose – print statements informing about progress of iterative procedure

      - kwargs_psf_update – keyword arguments providing the settings for a single iteration of the PSF, as being passed to update_psf() method

    Returns

      keyword argument of PSF constructor for PSF() class with updated PSF

  update_psf(kwargs_psf, kwargs_params, stacking_method='median', psf_symmetry=1, psf_iter_factor=0.2, block_center_neighbour=0, error_map_radius=None, block_center_neighbour_error_map=None, new_procedure=False)
    Parameters

      - kwargs_psf – keyword arguments to construct the PSF() class

      - kwargs_params – keyword arguments of the parameters of the model components (e.g. ‘kwargs_lens’ etc)

      - stacking_method – ‘median’, ‘mean’; the different estimates of the PSF are stacked and combined together. The choices are: ‘mean’: mean of pixel values as the estimator (not robust to outliers) ‘median’: median of pixel values as the estimator (outlier rejection robust but needs >2 point sources in the data

      - psf_symmetry – number of rotational invariant symmetries in the estimated PSF. =1 mean no additional symmetries. =4 means 90 deg symmetry. This is enforced by a rotatioanl stack according to the symmetry specified. These additional imposed symmetries can help stabelize the PSF estimate when there are limited constraints/number of point sources in the image.

      - psf_iter_factor – factor in (0, 1] of ratio of old vs new PSF in the update in the iteration.

      - block_center_neighbour – angle, radius of neighbouring point sources around their centers the estimates is ignored. Default is zero, meaning a not optimal subtraction of the neighbouring point sources might contaminate the estimate.

      - block_center_neighbour_error_map – angle, radius of neighbouring point sources around their centers the estimates of the ERROR MAP is ignored. If None, then the value of block_center_neighbour is used (recommended)

      - error_map_radius – float, radius (in arc seconds) of the outermost error in the PSF estimate (e.g. to avoid double counting of overlapping PSF errors), if None, all of the pixels are considered (unless blocked through other means)

      - new_procedure – boolean, uses post lenstronomy 1.9.2 procedure which is more optimal for super-sampled PSF’s

    Returns

      kwargs_psf_new, logL_after, error_map

## lenstronomy.Workflow.update_manager module

class lenstronomy.Workflow.update_manager.UpdateManager(kwargs_model, kwargs_constraints, kwargs_likelihood, kwargs_params)

  Bases: `object`

  this class manages the parameter constraints as they may evolve through the steps of the modeling. This includes: keeping certain parameters fixed during one modelling step

  best_fit(bijective=False)

    best fit (max likelihood) position for all the model parameters

    Parameters

      bijective – boolean, if True, returns the parameters in the argument of the sampling that might deviate from the convention of the ImSim module. For example, if parameterized in the image position, the parameters remain in the image plane rather than being mapped to the source plane.

    Returns

      kwargs_result with all the keyword arguments of the best fit for the model components

  fix_image_parameters(image_index=0)

    fixes all parameters that are only assigned to a specific image. This allows to sample only parameters that constraint by the fitting of a sub-set of the images.

    Parameters

      image_index – index

    Returns

      None

  property fixed_kwargs
  property init_kwargs
    Returns

      keyword arguments for all model components of the initial mean model proposition in the sampling

  property param_class

    creating instance of lenstronomy Param() class. It uses the keyword arguments in self.kwargs_constraints as __init__() arguments, as well as self.kwargs_model, and the set of kwargs_fixed___, kwargs_lower___, kwargs_upper___ arguments for lens, lens_light, source, point source, extinction and special parameters.

    Returns

      instance of the Param class with the recent options and bounds

  property parameter_state
    Returns

      parameter state saved in this class

  set_init_state()

    set the current state of the parameters to the initial one.

    Returns

  property sigma_kwargs
    Returns

      keyword arguments for all model components of the initial 1-sigma width proposition in the sampling

  update_fixed(lens_add_fixed=[], source_add_fixed=[], lens_light_add_fixed=[], ps_add_fixed=[], special_add_fixed=[], lens_remove_fixed=[], source_remove_fixed=[], lens_light_remove_fixed=[], ps_remove_fixed=[], special_remove_fixed=[])

    adds or removes the values of the keyword arguments that are stated in the _add_fixed to the existing fixed arguments. convention for input arguments are: [[i_model, [‘param_name1’, ‘param_name2’, …], [value1, value2, … (optional)], [], …]

    Parameters

      - lens_add_fixed – added fixed parameter in lens model

      - source_add_fixed – added fixed parameter in source model

      - lens_light_add_fixed – added fixed parameter in lens light model

      - ps_add_fixed – added fixed parameter in point source model

      - special_add_fixed – added fixed parameter in special model

      - lens_remove_fixed – remove fixed parameter in lens model

      - source_remove_fixed – remove fixed parameter in source model

      - lens_light_remove_fixed – remove fixed parameter in lens light model

      - ps_remove_fixed – remove fixed parameter in point source model

      - special_remove_fixed – remove fixed parameter in special model

    Returns

      updated kwargs fixed

  update_limits(change_source_lower_limit=None, change_source_upper_limit=None, change_lens_lower_limit=None, change_lens_upper_limit=None)

    updates the limits (lower and upper) of the update manager instance

    Parameters

      - change_source_lower_limit – [[i_model, [‘param_name’, …], [value1, value2, …]]]

      - change_lens_lower_limit – [[i_model, [‘param_name’, …], [value1, value2, …]]]

      - change_source_upper_limit – [[i_model, [‘param_name’, …], [value1, value2, …]]]

      - change_lens_upper_limit – [[i_model, [‘param_name’, …], [value1, value2, …]]]

    Returns

      updates internal state of lower and upper limits accessible from outside

  update_options(kwargs_model, kwargs_constraints, kwargs_likelihood)

    updates the options by overwriting the kwargs with the new ones being added/changed WARNING: some updates may not be valid depending on the model options. Use carefully!

    Parameters

      - kwargs_model – keyword arguments to describe all model components used in class_creator.create_class_instances() that are updated from previous arguments

      - kwargs_constraints –

      - kwargs_likelihood –

    Returns

      kwargs_model, kwargs_constraints, kwargs_likelihood

  update_param_state(kwargs_lens=None, kwargs_source=None, kwargs_lens_light=None, kwargs_ps=None, kwargs_special=None, kwargs_extinction=None)

    updates the temporary state of the parameters being saved. ATTENTION: Any previous knowledge gets lost if you call this function

    Parameters

      - kwargs_lens –

      - kwargs_source –

      - kwargs_lens_light –

      - kwargs_ps –

      - kwargs_special –

      - kwargs_extinction –

    Returns

  update_param_value(lens=[], source=[], lens_light=[], ps=[])

    Set a model parameter to a specific value.

    Parameters

      - lens – [[i_model, [‘param1’, ‘param2’,…], […]]

      - source – [[i_model, [‘param1’, ‘param2’,…], […]]

      - lens_light – [[i_model, [‘param1’, ‘param2’,…], […]]

      - ps – [[i_model, [‘param1’, ‘param2’,…], […]]

    Returns

      0, the value of the param is overwritten

## Module contents