dolphin.processor package#

Submodules#

dolphin.processor.config module#

This module loads settings from a configuration file.

class dolphin.processor.config.Config[source]#

Bases: object

This class contains the methods to load and read YAML configuration files.

This is a parent class for other classes that needs to load a configuration file. If the file type of the configuration files changes, then only this class needs to be modified.

classmethod load_config_from_yaml(file)[source]#

Load configuration from file.

Parameters:: file (str) – path to the YAML configuration file
Returns:: a dictionary containing the loaded settings
Return type:: dict

class dolphin.processor.config.ModelConfig(lens_name, file_system=None, io_directory=None, settings=None)[source]#

Bases: Config

This class contains the methods to load and interact with modeling settings for a particular system.

static check_init_params_in_bounds(component, init_dict_list, fixed_dict_list, lower_dict_list, upper_dict_list)[source]#

Checks that initial parameters are within the specified bounds. If not, a warning is raised for each parameter that is not within bounds. This check is only performed on parameters that are not fixed.

Parameters:

component (str) – name of the model component for which the check is done
init_dict_list (list of dict) – the list of dictionaries containing the initial parameter values of the specified model component
fixed_list (list of dict) – list of dictionaries containing fixed params
lower_dict_list (list of dict) – the list of dictionaries which contains the lower bounds of the specified model component
upper_dict_list (list of dict) – the list of dictionaries which contains the upper bounds of the specified model component

Returns:

None

Return type:

None

custom_logL_addition(kwargs_lens=None, kwargs_source=None, kwargs_lens_light=None, kwargs_ps=None, kwargs_special=None, kwargs_extinction=None, kwargs_tracer_source=None)[source]#

Provide additional likelihood terms to be sent to lenstronomy.

Parameters:

kwargs_lens (list of dict or None) – list of dictionaries containing lens model keyword arguments
kwargs_source (list of dict or None) – list of dictionaries containing source model keyword arguments
kwargs_lens_light (list of dict or None) – list of dictionaries containing lens light model keyword arguments
kwargs_ps (list of dict or None) – list of dictionaries containing point source model keyword arguments
kwargs_special (dict or None) – dictionary containing special model keyword arguments
kwargs_extinction (dict or None) – dictionary containing extinction model keyword arguments
kwargs_tracer_source (list of dict or None) – list of dictionaries containing tracer source model keyword arguments

Returns:

prior

Return type:

float

property deflector_center_dec#

The dec offset for the deflector’s center from the zero-point in the coordinate system of the data. Default is 0.

Returns:: the declination offset in arcseconds
Return type:: float

property deflector_center_ra#

The RA offset for the deflector’s center from the zero-point in the coordinate system of the data. Default is 0.

Returns:: the RA offset in arcseconds
Return type:: float

property deflector_centroid_bound#

Half of the box width to constrain the deflector’s centroid. Default is 0.5 arcsec.

Returns:: the centroid bound in arcseconds
Return type:: float

fill_in_fixed_from_settings(component, fixed_list)[source]#

Fill in fixed values from settings for lens, source light and lens light.

Parameters:

component (str) – name of component, ‘lens’, ‘lens_light’, or ‘source_light’
fixed_list (list of dict) – list of fixed params

Returns:

updated list of fixed params

Return type:

list of dict

get_image_data(band)[source]#

Get image data.

Parameters:: band (str) – name of the band
Returns:: image data
Return type:: ImageData

get_index_lens_light_model_list()[source]#

Create a list of indices for the different lens light profiles (for multiple filters).

Returns:: nested list of profile indices for each band
Return type:: list of list of int

get_index_list(light_type='lens_light')[source]#

Create a list of indices for the different light profiles (for multiple filters).

Parameters:: light_type (str) – key specifying which light model to use from self.settings[“model”]
Returns:: list of indices
Return type:: list of list of int

get_index_source_light_model_list()[source]#

Create a list of indices for the different source light profiles (for multiple filters).

Returns:: nested list of profile indices for each band
Return type:: list of list of int

get_joint_lens_light_with_lens_light()[source]#

Create joint_lens_light_with_lens_light list for constraints.

Returns:: list of linked parameters among lens light models
Return type:: list

get_joint_lens_with_light()[source]#

Create joint_lens_with_light list for constraints.

Returns:: list of linked parameters between lens mass and lens light models
Return type:: list

get_joint_source_with_point_source(num_source_profiles)[source]#

Create joint_source_with_point_source list for constraints.

Parameters:: num_source_profiles (int) – number of source light profiles
Returns:: list of linked parameters between source light and point source models
Return type:: list

get_joint_source_with_source()[source]#

Create joint_source_with_source list for constraints.

Returns:: a tuple containing the list of linked parameters among source models and the number of source profiles
Return type:: tuple (list, int)

get_kwargs_constraints(use_jax=False)[source]#

Create kwargs_constraints dictionary for lenstronomy.

Parameters:: use_jax (bool) – if True, performs modeling through JAXtronomy instead of lenstronomy
Returns:: dictionary containing the constraint configuration
Return type:: dict

get_kwargs_likelihood(custom_logL_addition=None, use_jax=False)[source]#

Create kwargs_likelihood dictionary for lenstronomy.

Parameters:

custom_logL_addition (callable function) – a callable function that takes in the optional arguments kwargs_lens, kwargs_source, kwargs_lens_light, kwargs_ps, kwargs_special, kwargs_extinction, kwargs_tracer_source and outputs a float. If use_jax is also True, this function must be compatible with jax.jit
use_jax (bool) – If set to True, uses JAXtronomy for modeling instead of lenstronomy

Returns:

dictionary containing the likelihood configuration

Return type:

dict

get_kwargs_model()[source]#

Create kwargs_model dictionary for lenstronomy.

Returns:: dictionary containing the model configuration
Return type:: dict

get_kwargs_numerics()[source]#

Create kwargs_numerics list for lenstronomy.

Returns:: list containing the numerics configuration
Return type:: list of dict

get_kwargs_params()[source]#

Create kwargs_params.

Returns:: dictionary containing the parameter configurations for all models
Return type:: dict

get_kwargs_psf_iteration()[source]#

Create kwargs_psf_iteration dictionary for lenstronomy.

Returns:: dictionary containing the PSF iteration configuration
Return type:: dict

get_lens_light_model_list()[source]#

Return lens_light_model_list.

Returns:: list of lens light models
Return type:: list of str

get_lens_light_model_list_with_flags()[source]#

Return lens_light_model_list and satellite_flags.

Returns:: list of lens light models and satellite flags
Return type:: tuple (list, list)

get_lens_light_model_params()[source]#

Create lens_light_params.

Returns:: a list of lists containing the initial, sigma, fixed, lower, and upper values for the lens light model parameters
Return type:: list of list of dict

get_lens_model_list()[source]#

Return lens_model_list.

Returns:: list of lens mass models
Return type:: list of str

get_lens_model_list_with_flags()[source]#

Return lens_model_list and satellite_flags.

Returns:: list of lens models and satellite flags
Return type:: tuple (list, list)

get_lens_model_params(theta_E_upper_factor=1.5, theta_E_lower_factor=0.3, theta_E_satellite=0.1)[source]#

Create lens_params.

Parameters:

theta_E_upper_factor (float) – factor to multiply the initial Einstein radius for the upper bound
theta_E_lower_factor (float) – factor to multiply the initial Einstein radius for the lower bound
theta_E_satellite (float) – initial guess for the satellite’s Einstein radius, if exists

Returns:

a list of lists containing the initial, sigma, fixed, lower, and upper values for the lens model parameters

Return type:

list of list of dict

get_masks()[source]#

Create masks based on settings or load them from files.

Returns:: a list of masks for each band, or None if not specified
Return type:: list of numpy.ndarray or None

get_measured_time_delays()[source]#

Get time delays and uncertainties if specified in the configuration.

Returns:: dictionary with time delays and uncertainties, or an empty dictionary if not specified
Return type:: dict

get_point_source_model_list()[source]#

Return point_source_model_list.

Returns:: list of point source models
Return type:: list of str

get_point_source_params()[source]#

Create ps_params.

Returns:: a list of lists containing the initial, sigma, fixed, lower, and upper values for the point source model parameters
Return type:: list of list of dict

get_psf_supersampled_factor()[source]#

Retrieve PSF supersampling factor if specified in the config file.

Returns:: PSF supersampling factor
Return type:: int

get_source_light_model_list()[source]#

Return source_model_list.

Returns:: list of source light models
Return type:: list of str

get_source_light_model_params()[source]#

Create source_params.

Returns:: a list of lists containing the initial, sigma, fixed, lower, and upper values for the source light model parameters
Return type:: list of list of dict

get_special_list()[source]#

get_special_params()[source]#

Create special_params.

Returns:: list of parameters
Return type:: list of dict

property lens_name#

The name of the lens system.

Returns:: the name of the lens system
Return type:: str

static load_mask(mask_file_path)[source]#

Load mask from file.

Parameters:: mask_file_path (str) – path to the mask file
Returns:: mask
Return type:: numpy.ndarray

property num_satellites#

Get the number of satellite galaxies in the system.

Returns:: the number of satellite galaxies
Return type:: int

property number_of_bands#

The number of bands.

Returns:: the number of observing bands
Return type:: int

property pixel_size#

The pixel size.

Returns:: a list of pixel sizes for each band
Return type:: list of float

update_initial_guesses(component, init_dict_list)[source]#

Update the default initial parameter values with those provided by the user in the config file.

Parameters:

component (str) – name of the model component for which the initial parameter values will be updated
init_dict_list (list of dict) – the list of dictionaries containing the default initial parameter values of the specified model component

Returns:

a modified list of dictionaries containing the updated initial parameter values

Return type:

list of dict

update_uniform_priors(component, lower_dict_list, upper_dict_list)[source]#

Update the default uniform prior bounds with those provided by the user in the config file.

Parameters:

component (str) – name of the model component for which the uniform bounds will be altered
lower_dict_list (list of dict) – the list of dictionaries which contains the default lower bounds of the specified model component
upper_dict_list (list of dict) – the list of dictionaries which contains the default upper bounds of the specified model component

Returns:

a tuple containing the modified lower and upper parameter bound dictionary lists

Return type:

tuple (list of dict, list of dict)

dolphin.processor.core module#

This module handles the execution of modeling sequences for lens systems.

class dolphin.processor.core.Processor(io_directory)[source]#

Bases: object

This class contains methods to model a single lens system or a batch of systems using settings loaded from configuration files.

get_image_data(lens_name, band)[source]#

Get the ImageData instance for a given lens and observing band.

Parameters:

lens_name (str) – name of the lens system
band (str) – observing band or filter name

Returns:

loaded image data object

Return type:

ImageData

get_kwargs_data_joint(lens_name, psf_supersampled_factor=1)[source]#

Create a joint kwargs_data dictionary combining data and PSFs across filters.

Parameters:

lens_name (str) – name of the lens system
psf_supersampled_factor (int) – supersampling factor applied to the PSF

Returns:

joint kwargs data mapping suitable for lenstronomy

Return type:

dict

get_lens_config(lens_name)[source]#

Get the ModelConfig object populated with settings for a specific lens.

Parameters:: lens_name (str) – name of the lens system
Returns:: instance of ModelConfig containing the lens configurations
Return type:: ModelConfig

get_psf_data(lens_name, band)[source]#

Get the PSFData instance for a given lens and observing band.

Parameters:

lens_name (str) – name of the lens system
band (str) – observing band or filter name

Returns:

loaded PSF data object

Return type:

PSFData

swim(lens_name, model_id, log=True, mpi=False, recipe_name='galaxy-quasar', thread_count=1, custom_logL_addition=None, use_jax=False)[source]#

Run lens modeling optimizations for a single lens system.

Parameters:

lens_name (str) – name of the lens system to model
model_id (str) – identifier for this specific model run
log (bool) – if True, standard output is logged to a file. Set to False in notebooks.
mpi (bool) – enable MPI for parallel processing
recipe_name (str) – recipe for pre-sampling optimization. Supported: ‘galaxy-quasar’, ‘galaxy-galaxy’, ‘custom’, ‘skip’. ‘custom’ will use the fitting_kwargs_list directly from the yaml settings for pre-sampling optimization. ‘skip’ will skip pre-sampling optimization and directly sample the full model. See Recipe class for details.
thread_count (int) – number of threads to use if multiprocess is enabled
custom_logL_addition (callable function) – a callable function that takes in the optional arguments kwargs_lens, kwargs_source, kwargs_lens_light, kwargs_ps, kwargs_special, kwargs_extinction, kwargs_tracer_source and outputs a float. If use_jax is also True, this function must be compatible with jax.jit
use_jax (bool) – if True, performs modeling through JAXtronomy instead of lenstronomy

Returns:

None

Return type:

None

dolphin.processor.data module#

This module loads data and PSFs from HDF5 data files.

class dolphin.processor.data.Data[source]#

Bases: object

This is a superclass to load data files securely and consistently.

static load_from_file(file_path)[source]#

Load data dictionary from an HDF5 file.

Parameters:: file_path (str) – path to the HDF5 data file
Returns:: a dictionary containing the data loaded from the file
Return type:: dict

class dolphin.processor.data.ImageData(data_file_path)[source]#

Bases: Data

This class manages the image data of a lens system.

get_image()[source]#

Get the image ndarray saved in the class instance.

Returns:: a numpy array representing the image data
Return type:: numpy.ndarray

get_image_coordinate_system()[source]#

Get the coordinate system of the image data.

Returns:: an instance representing the image coordinate system
Return type:: lenstronomy.Data.coord_transforms.Coordinates

get_image_pixel_scale()[source]#

Get the pixel scale of the image in arcseconds.

Returns:: pixel scale width
Return type:: float

get_image_size()[source]#

Get the number of pixels along one axis in the image.

Returns:: the dimension of the square image data
Return type:: int

property kwargs_data#

Get a deep copy of the kwargs_data dictionary.

Returns:: a dictionary with the image configuration and data
Return type:: dict

class dolphin.processor.data.PSFData(psf_file_path)[source]#

Bases: Data

This class manages the Point Spread Function (PSF) data for a lens system.

property kwargs_psf#

Get a deep copy of the kwargs_psf dictionary with correct formatting.

Returns:: a dictionary containing the PSF settings and kernel
Return type:: dict

dolphin.processor.files module#

This module provides a class for maintaining the file system and directory architecture.

class dolphin.processor.files.FileSystem(io_directory)[source]#

Bases: object

This class contains methods to handle the file system, directory paths, and standard IO operations.

classmethod decode_numpy_arrays(obj)[source]#

Recursively decode a list or dictionary, converting encoded dictionary representations back to numpy arrays.

Parameters:: obj (object) – the object containing encoded representations of arrays
Returns:: the decoded object with true numpy.ndarray objects
Return type:: object

classmethod encode_numpy_arrays(obj)[source]#

Recursively encode a list or dictionary containing numpy arrays to allow JSON serialization. This function can also handle objects with a callable tolist() function and a ‘shape’ property, such as JAX arrays.

Parameters:: obj (object) – the object (list, dictionary, or array) to be encoded
Returns:: the encoded object with `numpy.ndarray`s replaced by dictionaries
Return type:: object

get_config_file_path(lens_name)[source]#

Get the file path to the configuration YAML file for a given lens.

Parameters:: lens_name (str) – name of the lens
Returns:: path to the configuration file
Return type:: str

get_data_directory()[source]#

Get the path to the data directory.

Returns:: path to the data folder
Return type:: str

get_image_file_path(lens_name, band)[source]#

Get the file path for the HDF5 image data file for a specific lens and band.

Parameters:

lens_name (str) – name of the lens
band (str) – observing band name

Returns:

file path to the image data

Return type:

str

get_lens_list()[source]#

Get the list of lenses from the lens_list.txt file.

Lines starting with # are ignored as comments.

Returns:: list of lens names
Return type:: list of str

get_lens_list_file_path()[source]#

Get the file path for the lens_list.txt file.

Returns:: path to the lens_list.txt file
Return type:: str

get_log_file_path(lens_name, model_id)[source]#

Get the file path for the log text file for a specific modeling run.

Parameters:

lens_name (str) – name of the lens
model_id (str) – identifier for the model run

Returns:

file path to the log file

Return type:

str

get_logs_directory()[source]#

Get the path to the logs directory.

Returns:: path to the logs folder
Return type:: str

get_mask_file_path(lens_name, band)[source]#

Get the file path for the mask data for a specific lens and band.

Parameters:

lens_name (str) – name of the lens
band (str) – observing band name

Returns:

file path to the mask numpy file

Return type:

str

get_output_file_path(lens_name, model_id, file_type='json')[source]#

Get the file path for the output file of a specific modeling run.

Parameters:

lens_name (str) – name of the lens
model_id (str) – identifier for the model run
file_type (str) – extension type of the file. Options: ‘json’, ‘h5’.

Returns:

file path to the output file

Return type:

str

get_outputs_directory()[source]#

Get the path to the outputs directory.

Returns:: path to the outputs folder
Return type:: str

get_photometry_file_path(lens_name, model_id)[source]#

Get the file path for Photometry outputs.

Parameters:

lens_name (str) – name of the system to analyze
model_id (str) – model ID of the lens system being analyzed

Returns:

path to the Photometry output HDF5 file

Return type:

str

get_psf_file_path(lens_name, band)[source]#

Get the file path for the HDF5 PSF data file for a specific lens and band.

Parameters:

lens_name (str) – name of the lens
band (str) – observing band name

Returns:

file path to the PSF data

Return type:

str

get_semantic_segmentation_file_path(lens_name, band)[source]#

Get the file path for the semantic segmentation data for a specific lens and band.

Parameters:

lens_name (str) – name of the lens
band (str) – observing band name

Returns:

file path to the semantic segmentation numpy file

Return type:

str

get_settings_directory()[source]#

Get the path to the settings directory as a Path object.

Returns:: path to the settings folder
Return type:: pathlib.Path

get_trained_nn_model_file_path(source_type='galaxy')[source]#

Get the local file path for the trained neural network model. Downloads the model from Google Drive if it doesn’t exist locally.

Parameters:: source_type (str) – the type of lens source. Expected ‘galaxy’ or ‘quasar’. Default is ‘galaxy’.
Returns:: absolute file path to the downloaded model .h5 file
Return type:: str

load_flux_chain(photometry_class)[source]#

Load flux chain as computed by do_linear_inversion().

Parameters:: photometry_class (class) – Photometry class instance
Returns:: dictionary containing flux chains. Format: {filter: {"image1": array, "image2": array, "lens": array, ...}}
Return type:: dict

load_magnitude_chain(photometry_class)[source]#

Load magnitude chain.

Parameters:: photometry_class (class) – Photometry class instance
Returns:: dictionary containing AB magnitude chains. Format: {filter: {"image1": array, "image2": array, "lens": array, ...}}
Return type:: dict

load_mask(lens_name, band)[source]#

Load mask data from its .npy file.

Parameters:

lens_name (str) – name of the lens
band (str) – observing band name

Returns:

the loaded mask array

Return type:

numpy.ndarray

load_morphology_chain(photometry_class)[source]#

Load morphology chains as computed by do_linear_inversion().

Returns:: dictionary containing morphological parameter chains for each filter. Format: {filter: {"phi": array, "q": array, "r_eff": array}}
Return type:: dict

load_output(lens_name, model_id, file_type='h5')[source]#

Load output modeling results from a previously saved file.

Parameters:

lens_name (str) – name of the lens
model_id (str) – identifier for the model run
file_type (str) – type of file. Options: ‘h5’ or ‘json’. Default is ‘h5’.

Returns:

the loaded output dictionary

Return type:

dict

load_output_h5(lens_name, model_id)[source]#

Load output modeling results from an HDF5 file.

Parameters:

lens_name (str) – name of the lens
model_id (str) – identifier for the model run

Returns:

the loaded output dictionary

Return type:

dict

load_output_json(lens_name, model_id)[source]#

Load output modeling results from a JSON file.

Parameters:

lens_name (str) – name of the lens
model_id (str) – identifier for the model run

Returns:

the loaded output dictionary

Return type:

dict

load_semantic_segmentation(lens_name, band)[source]#

Load semantic segmentation data from its .npy file.

Parameters:

lens_name (str) – name of the lens
band (str) – observing band name

Returns:

the loaded semantic segmentation array

Return type:

numpy.ndarray

static path2str(path)[source]#

Converts a pathlib.Path object into an absolute string path.

Parameters:: path (pathlib.Path) – path to a file or directory
Returns:: absolute string path
Return type:: str

save_mask(lens_name, band, mask)[source]#

Save a mask array to a .npy file.

Parameters:

lens_name (str) – name of the lens
band (str) – observing band name
mask (numpy.ndarray) – the mask array to save

Returns:

None

Return type:

None

save_output(lens_name, model_id, output, file_type='h5')[source]#

Save the results output from the fitting sequence to disk.

Parameters:

lens_name (str) – name of the lens
model_id (str) – identifier for the model run
output (dict) – output dictionary containing modeling results
file_type (str) – type of file to save format. ‘h5’ or ‘json’.

Returns:

None

Return type:

None

save_output_h5(lens_name, model_id, output)[source]#

Save the fitting sequence output as an HDF5 (.h5) file.

Parameters:

lens_name (str) – name of the lens
model_id (str) – identifier for the model run
output (dict) – output dictionary containing modeling results

Returns:

None

Return type:

None

save_output_json(lens_name, model_id, output)[source]#

Save the fitting sequence output as a JSON file.

Parameters:

lens_name (str) – name of the lens
model_id (str) – identifier for the model run
output (dict) – output dictionary containing modeling results

Returns:

None

Return type:

None

save_photometry_to_hdf5(photometry_class, flux_chain, magnitude_chain=None, morphology_chain=None)[source]#

Save linear inversion outputs in HDF5 format for later analysis.

Parameters:

photometry_class (class) – Photometry class instance
flux_chain (np.ndarray) – Flux chain as computed from Photometrydo_linear_inversion()
magnitude_chain (np.ndarray) – (Optional) AB magnitude chain as computed from calculate_ab_magnitude()
morphology_chain (dict) – (Optional) Morphology chain as computed from do_linear_inversion()

save_semantic_segmentation(lens_name, band, semantic_segmentation)[source]#

Save a semantic segmentation array to a .npy file.

Parameters:

lens_name (str) – name of the lens
band (str) – observing band name
semantic_segmentation (numpy.ndarray) – the semantic segmentation mask to save

Returns:

None

Return type:

None

dolphin.processor.recipe module#

This module creates fitting_kwargs_list for FittingSequence.fit_sequence() with pre-defined recipes.

class dolphin.processor.recipe.Recipe(config, thread_count=1)[source]#

Bases: object

This class contains methods to create fitting recipes.

It builds an optimization workflow (currently using particle-swarm optimization) to first find a good enough lens model within the total parameter space. Then, the sampling can be done starting from the neighborhood of this point.

fix_params(model_component, index=None)[source]#

Fix all the params in model_component that are not fixed by settings.

Parameters:

model_component (str) – name of params type, e.g., ‘lens’, ‘lens_light’, or ‘source’
index (list or int or None) – profile indices, if None all will be fixed

Returns:

formatted fit-sequence code to go into fitting_kwargs_list

Return type:

list

get_arc_mask(image, clear_center=0.4, mask=None)[source]#

Create a mask for lensed galaxy arcs from the image of the lens. The lens galaxy is required to be close to the center (within a few pixels) of the image.

Parameters:

image (numpy.ndarray) – image of the lensing system
clear_center (float) – radius of the central region to not mask
mask (numpy.ndarray or None) – a mask to multiply with the arc mask. If the central region is masked out in mask, then a circle with radius clear_center will be unmasked.

Returns:

mask for the lensed galaxy arcs

Return type:

numpy.ndarray

get_galaxy_galaxy_recipe(kwargs_data_joint, epochs=2)[source]#

Get the pre-sampling optimization routine for a galaxy-galaxy lens. PSF iteration is not added.

Parameters:

kwargs_data_joint (dict) – dictionary containing joint data specifications
epochs (int) – number of times to repeat the fitting sequence

Returns:

a list containing the sequence of fitting operations

Return type:

list

get_galaxy_quasar_recipe()[source]#

Get the default pre-sampling optimization routine.

Returns:: fitting kwargs list
Return type:: list

get_recipe(kwargs_data_joint=None, recipe_name='galaxy-quasar')[source]#

Get fitting_kwargs_list according to the requested recipe.

Parameters:

kwargs_data_joint (dict or None) – kwargs_data_joint dictionary for multiple bands
recipe_name (str) – recipe name, ‘galaxy-quasar’, ‘galaxy-galaxy’, ‘custom’, or ‘skip’

Returns:

fitting kwargs list

Return type:

list

get_sampling_sequence()[source]#

Get the sampling sequence. Currently MCMC with emcee and nested sampling with Nautilus are supported.

Returns:: a list containing the sampling sequence arguments
Return type:: list

unfix_params(model_component, index=None)[source]#

Unfix all the params in model_component that are not fixed from settings.

Parameters:

model_component (str) – name of params type, e.g., ‘lens’, ‘lens_light’, or ‘source’
index (list or int or None) – profile indices, if None all will be unfixed

Returns:

formatted fit-sequence code to go into fitting_kwargs_list

Return type:

list

Module contents#

Processor module for Dolphin, providing core modeling, file system management, and configuration utilities.

class dolphin.processor.FileSystem(io_directory)[source]#

Bases: object

This class contains methods to handle the file system, directory paths, and standard IO operations.

classmethod decode_numpy_arrays(obj)[source]#

Recursively decode a list or dictionary, converting encoded dictionary representations back to numpy arrays.

Parameters:: obj (object) – the object containing encoded representations of arrays
Returns:: the decoded object with true numpy.ndarray objects
Return type:: object

classmethod encode_numpy_arrays(obj)[source]#

Parameters:: obj (object) – the object (list, dictionary, or array) to be encoded
Returns:: the encoded object with `numpy.ndarray`s replaced by dictionaries
Return type:: object

get_config_file_path(lens_name)[source]#

Get the file path to the configuration YAML file for a given lens.

Parameters:: lens_name (str) – name of the lens
Returns:: path to the configuration file
Return type:: str

get_data_directory()[source]#

Get the path to the data directory.

Returns:: path to the data folder
Return type:: str

get_image_file_path(lens_name, band)[source]#

Get the file path for the HDF5 image data file for a specific lens and band.

Parameters:

lens_name (str) – name of the lens
band (str) – observing band name

Returns:

file path to the image data

Return type:

str

get_lens_list()[source]#

Get the list of lenses from the lens_list.txt file.

Lines starting with # are ignored as comments.

Returns:: list of lens names
Return type:: list of str

get_lens_list_file_path()[source]#

Get the file path for the lens_list.txt file.

Returns:: path to the lens_list.txt file
Return type:: str

get_log_file_path(lens_name, model_id)[source]#

Get the file path for the log text file for a specific modeling run.

Parameters:

lens_name (str) – name of the lens
model_id (str) – identifier for the model run

Returns:

file path to the log file

Return type:

str

get_logs_directory()[source]#

Get the path to the logs directory.

Returns:: path to the logs folder
Return type:: str

get_mask_file_path(lens_name, band)[source]#

Get the file path for the mask data for a specific lens and band.

Parameters:

lens_name (str) – name of the lens
band (str) – observing band name

Returns:

file path to the mask numpy file

Return type:

str

get_output_file_path(lens_name, model_id, file_type='json')[source]#

Get the file path for the output file of a specific modeling run.

Parameters:

lens_name (str) – name of the lens
model_id (str) – identifier for the model run
file_type (str) – extension type of the file. Options: ‘json’, ‘h5’.

Returns:

file path to the output file

Return type:

str

get_outputs_directory()[source]#

Get the path to the outputs directory.

Returns:: path to the outputs folder
Return type:: str

get_photometry_file_path(lens_name, model_id)[source]#

Get the file path for Photometry outputs.

Parameters:

lens_name (str) – name of the system to analyze
model_id (str) – model ID of the lens system being analyzed

Returns:

path to the Photometry output HDF5 file

Return type:

str

get_psf_file_path(lens_name, band)[source]#

Get the file path for the HDF5 PSF data file for a specific lens and band.

Parameters:

lens_name (str) – name of the lens
band (str) – observing band name

Returns:

file path to the PSF data

Return type:

str

get_semantic_segmentation_file_path(lens_name, band)[source]#

Get the file path for the semantic segmentation data for a specific lens and band.

Parameters:

lens_name (str) – name of the lens
band (str) – observing band name

Returns:

file path to the semantic segmentation numpy file

Return type:

str

get_settings_directory()[source]#

Get the path to the settings directory as a Path object.

Returns:: path to the settings folder
Return type:: pathlib.Path

get_trained_nn_model_file_path(source_type='galaxy')[source]#

Get the local file path for the trained neural network model. Downloads the model from Google Drive if it doesn’t exist locally.

Parameters:: source_type (str) – the type of lens source. Expected ‘galaxy’ or ‘quasar’. Default is ‘galaxy’.
Returns:: absolute file path to the downloaded model .h5 file
Return type:: str

load_flux_chain(photometry_class)[source]#

Load flux chain as computed by do_linear_inversion().

Parameters:: photometry_class (class) – Photometry class instance
Returns:: dictionary containing flux chains. Format: {filter: {"image1": array, "image2": array, "lens": array, ...}}
Return type:: dict

load_magnitude_chain(photometry_class)[source]#

Load magnitude chain.

Parameters:: photometry_class (class) – Photometry class instance
Returns:: dictionary containing AB magnitude chains. Format: {filter: {"image1": array, "image2": array, "lens": array, ...}}
Return type:: dict

load_mask(lens_name, band)[source]#

Load mask data from its .npy file.

Parameters:

lens_name (str) – name of the lens
band (str) – observing band name

Returns:

the loaded mask array

Return type:

numpy.ndarray

load_morphology_chain(photometry_class)[source]#

Load morphology chains as computed by do_linear_inversion().

Returns:: dictionary containing morphological parameter chains for each filter. Format: {filter: {"phi": array, "q": array, "r_eff": array}}
Return type:: dict

load_output(lens_name, model_id, file_type='h5')[source]#

Load output modeling results from a previously saved file.

Parameters:

lens_name (str) – name of the lens
model_id (str) – identifier for the model run
file_type (str) – type of file. Options: ‘h5’ or ‘json’. Default is ‘h5’.

Returns:

the loaded output dictionary

Return type:

dict

load_output_h5(lens_name, model_id)[source]#

Load output modeling results from an HDF5 file.

Parameters:

lens_name (str) – name of the lens
model_id (str) – identifier for the model run

Returns:

the loaded output dictionary

Return type:

dict

load_output_json(lens_name, model_id)[source]#

Load output modeling results from a JSON file.

Parameters:

lens_name (str) – name of the lens
model_id (str) – identifier for the model run

Returns:

the loaded output dictionary

Return type:

dict

load_semantic_segmentation(lens_name, band)[source]#

Load semantic segmentation data from its .npy file.

Parameters:

lens_name (str) – name of the lens
band (str) – observing band name

Returns:

the loaded semantic segmentation array

Return type:

numpy.ndarray

static path2str(path)[source]#

Converts a pathlib.Path object into an absolute string path.

Parameters:: path (pathlib.Path) – path to a file or directory
Returns:: absolute string path
Return type:: str

save_mask(lens_name, band, mask)[source]#

Save a mask array to a .npy file.

Parameters:

lens_name (str) – name of the lens
band (str) – observing band name
mask (numpy.ndarray) – the mask array to save

Returns:

None

Return type:

None

save_output(lens_name, model_id, output, file_type='h5')[source]#

Save the results output from the fitting sequence to disk.

Parameters:

lens_name (str) – name of the lens
model_id (str) – identifier for the model run
output (dict) – output dictionary containing modeling results
file_type (str) – type of file to save format. ‘h5’ or ‘json’.

Returns:

None

Return type:

None

save_output_h5(lens_name, model_id, output)[source]#

Save the fitting sequence output as an HDF5 (.h5) file.

Parameters:

lens_name (str) – name of the lens
model_id (str) – identifier for the model run
output (dict) – output dictionary containing modeling results

Returns:

None

Return type:

None

save_output_json(lens_name, model_id, output)[source]#

Save the fitting sequence output as a JSON file.

Parameters:

lens_name (str) – name of the lens
model_id (str) – identifier for the model run
output (dict) – output dictionary containing modeling results

Returns:

None

Return type:

None

save_photometry_to_hdf5(photometry_class, flux_chain, magnitude_chain=None, morphology_chain=None)[source]#

Save linear inversion outputs in HDF5 format for later analysis.

Parameters:

photometry_class (class) – Photometry class instance
flux_chain (np.ndarray) – Flux chain as computed from Photometrydo_linear_inversion()
magnitude_chain (np.ndarray) – (Optional) AB magnitude chain as computed from calculate_ab_magnitude()
morphology_chain (dict) – (Optional) Morphology chain as computed from do_linear_inversion()

save_semantic_segmentation(lens_name, band, semantic_segmentation)[source]#

Save a semantic segmentation array to a .npy file.

Parameters:

lens_name (str) – name of the lens
band (str) – observing band name
semantic_segmentation (numpy.ndarray) – the semantic segmentation mask to save

Returns:

None

Return type:

None

class dolphin.processor.ModelConfig(lens_name, file_system=None, io_directory=None, settings=None)[source]#

Bases: Config

This class contains the methods to load and interact with modeling settings for a particular system.

static check_init_params_in_bounds(component, init_dict_list, fixed_dict_list, lower_dict_list, upper_dict_list)[source]#

Parameters:

component (str) – name of the model component for which the check is done
init_dict_list (list of dict) – the list of dictionaries containing the initial parameter values of the specified model component
fixed_list (list of dict) – list of dictionaries containing fixed params
lower_dict_list (list of dict) – the list of dictionaries which contains the lower bounds of the specified model component
upper_dict_list (list of dict) – the list of dictionaries which contains the upper bounds of the specified model component

Returns:

None

Return type:

None

custom_logL_addition(kwargs_lens=None, kwargs_source=None, kwargs_lens_light=None, kwargs_ps=None, kwargs_special=None, kwargs_extinction=None, kwargs_tracer_source=None)[source]#

Provide additional likelihood terms to be sent to lenstronomy.

Parameters:

kwargs_lens (list of dict or None) – list of dictionaries containing lens model keyword arguments
kwargs_source (list of dict or None) – list of dictionaries containing source model keyword arguments
kwargs_lens_light (list of dict or None) – list of dictionaries containing lens light model keyword arguments
kwargs_ps (list of dict or None) – list of dictionaries containing point source model keyword arguments
kwargs_special (dict or None) – dictionary containing special model keyword arguments
kwargs_extinction (dict or None) – dictionary containing extinction model keyword arguments
kwargs_tracer_source (list of dict or None) – list of dictionaries containing tracer source model keyword arguments

Returns:

prior

Return type:

float

property deflector_center_dec#

The dec offset for the deflector’s center from the zero-point in the coordinate system of the data. Default is 0.

Returns:: the declination offset in arcseconds
Return type:: float

property deflector_center_ra#

The RA offset for the deflector’s center from the zero-point in the coordinate system of the data. Default is 0.

Returns:: the RA offset in arcseconds
Return type:: float

property deflector_centroid_bound#

Half of the box width to constrain the deflector’s centroid. Default is 0.5 arcsec.

Returns:: the centroid bound in arcseconds
Return type:: float

fill_in_fixed_from_settings(component, fixed_list)[source]#

Fill in fixed values from settings for lens, source light and lens light.

Parameters:

component (str) – name of component, ‘lens’, ‘lens_light’, or ‘source_light’
fixed_list (list of dict) – list of fixed params

Returns:

updated list of fixed params

Return type:

list of dict

get_image_data(band)[source]#

Get image data.

Parameters:: band (str) – name of the band
Returns:: image data
Return type:: ImageData

get_index_lens_light_model_list()[source]#

Create a list of indices for the different lens light profiles (for multiple filters).

Returns:: nested list of profile indices for each band
Return type:: list of list of int

get_index_list(light_type='lens_light')[source]#

Create a list of indices for the different light profiles (for multiple filters).

Parameters:: light_type (str) – key specifying which light model to use from self.settings[“model”]
Returns:: list of indices
Return type:: list of list of int

get_index_source_light_model_list()[source]#

Create a list of indices for the different source light profiles (for multiple filters).

Returns:: nested list of profile indices for each band
Return type:: list of list of int

get_joint_lens_light_with_lens_light()[source]#

Create joint_lens_light_with_lens_light list for constraints.

Returns:: list of linked parameters among lens light models
Return type:: list

get_joint_lens_with_light()[source]#

Create joint_lens_with_light list for constraints.

Returns:: list of linked parameters between lens mass and lens light models
Return type:: list

get_joint_source_with_point_source(num_source_profiles)[source]#

Create joint_source_with_point_source list for constraints.

Parameters:: num_source_profiles (int) – number of source light profiles
Returns:: list of linked parameters between source light and point source models
Return type:: list

get_joint_source_with_source()[source]#

Create joint_source_with_source list for constraints.

Returns:: a tuple containing the list of linked parameters among source models and the number of source profiles
Return type:: tuple (list, int)

get_kwargs_constraints(use_jax=False)[source]#

Create kwargs_constraints dictionary for lenstronomy.

Parameters:: use_jax (bool) – if True, performs modeling through JAXtronomy instead of lenstronomy
Returns:: dictionary containing the constraint configuration
Return type:: dict

get_kwargs_likelihood(custom_logL_addition=None, use_jax=False)[source]#

Create kwargs_likelihood dictionary for lenstronomy.

Parameters:

custom_logL_addition (callable function) – a callable function that takes in the optional arguments kwargs_lens, kwargs_source, kwargs_lens_light, kwargs_ps, kwargs_special, kwargs_extinction, kwargs_tracer_source and outputs a float. If use_jax is also True, this function must be compatible with jax.jit
use_jax (bool) – If set to True, uses JAXtronomy for modeling instead of lenstronomy

Returns:

dictionary containing the likelihood configuration

Return type:

dict

get_kwargs_model()[source]#

Create kwargs_model dictionary for lenstronomy.

Returns:: dictionary containing the model configuration
Return type:: dict

get_kwargs_numerics()[source]#

Create kwargs_numerics list for lenstronomy.

Returns:: list containing the numerics configuration
Return type:: list of dict

get_kwargs_params()[source]#

Create kwargs_params.

Returns:: dictionary containing the parameter configurations for all models
Return type:: dict

get_kwargs_psf_iteration()[source]#

Create kwargs_psf_iteration dictionary for lenstronomy.

Returns:: dictionary containing the PSF iteration configuration
Return type:: dict

get_lens_light_model_list()[source]#

Return lens_light_model_list.

Returns:: list of lens light models
Return type:: list of str

get_lens_light_model_list_with_flags()[source]#

Return lens_light_model_list and satellite_flags.

Returns:: list of lens light models and satellite flags
Return type:: tuple (list, list)

get_lens_light_model_params()[source]#

Create lens_light_params.

Returns:: a list of lists containing the initial, sigma, fixed, lower, and upper values for the lens light model parameters
Return type:: list of list of dict

get_lens_model_list()[source]#

Return lens_model_list.

Returns:: list of lens mass models
Return type:: list of str

get_lens_model_list_with_flags()[source]#

Return lens_model_list and satellite_flags.

Returns:: list of lens models and satellite flags
Return type:: tuple (list, list)

get_lens_model_params(theta_E_upper_factor=1.5, theta_E_lower_factor=0.3, theta_E_satellite=0.1)[source]#

Create lens_params.

Parameters:

theta_E_upper_factor (float) – factor to multiply the initial Einstein radius for the upper bound
theta_E_lower_factor (float) – factor to multiply the initial Einstein radius for the lower bound
theta_E_satellite (float) – initial guess for the satellite’s Einstein radius, if exists

Returns:

a list of lists containing the initial, sigma, fixed, lower, and upper values for the lens model parameters

Return type:

list of list of dict

get_masks()[source]#

Create masks based on settings or load them from files.

Returns:: a list of masks for each band, or None if not specified
Return type:: list of numpy.ndarray or None

get_measured_time_delays()[source]#

Get time delays and uncertainties if specified in the configuration.

Returns:: dictionary with time delays and uncertainties, or an empty dictionary if not specified
Return type:: dict

get_point_source_model_list()[source]#

Return point_source_model_list.

Returns:: list of point source models
Return type:: list of str

get_point_source_params()[source]#

Create ps_params.

Returns:: a list of lists containing the initial, sigma, fixed, lower, and upper values for the point source model parameters
Return type:: list of list of dict

get_psf_supersampled_factor()[source]#

Retrieve PSF supersampling factor if specified in the config file.

Returns:: PSF supersampling factor
Return type:: int

get_source_light_model_list()[source]#

Return source_model_list.

Returns:: list of source light models
Return type:: list of str

get_source_light_model_params()[source]#

Create source_params.

Returns:: a list of lists containing the initial, sigma, fixed, lower, and upper values for the source light model parameters
Return type:: list of list of dict

get_special_list()[source]#

get_special_params()[source]#

Create special_params.

Returns:: list of parameters
Return type:: list of dict

property lens_name#

The name of the lens system.

Returns:: the name of the lens system
Return type:: str

static load_mask(mask_file_path)[source]#

Load mask from file.

Parameters:: mask_file_path (str) – path to the mask file
Returns:: mask
Return type:: numpy.ndarray

property num_satellites#

Get the number of satellite galaxies in the system.

Returns:: the number of satellite galaxies
Return type:: int

property number_of_bands#

The number of bands.

Returns:: the number of observing bands
Return type:: int

property pixel_size#

The pixel size.

Returns:: a list of pixel sizes for each band
Return type:: list of float

update_initial_guesses(component, init_dict_list)[source]#

Update the default initial parameter values with those provided by the user in the config file.

Parameters:

component (str) – name of the model component for which the initial parameter values will be updated
init_dict_list (list of dict) – the list of dictionaries containing the default initial parameter values of the specified model component

Returns:

a modified list of dictionaries containing the updated initial parameter values

Return type:

list of dict

update_uniform_priors(component, lower_dict_list, upper_dict_list)[source]#

Update the default uniform prior bounds with those provided by the user in the config file.

Parameters:

component (str) – name of the model component for which the uniform bounds will be altered
lower_dict_list (list of dict) – the list of dictionaries which contains the default lower bounds of the specified model component
upper_dict_list (list of dict) – the list of dictionaries which contains the default upper bounds of the specified model component

Returns:

a tuple containing the modified lower and upper parameter bound dictionary lists

Return type:

tuple (list of dict, list of dict)

class dolphin.processor.Processor(io_directory)[source]#

Bases: object

This class contains methods to model a single lens system or a batch of systems using settings loaded from configuration files.

get_image_data(lens_name, band)[source]#

Get the ImageData instance for a given lens and observing band.

Parameters:

lens_name (str) – name of the lens system
band (str) – observing band or filter name

Returns:

loaded image data object

Return type:

ImageData

get_kwargs_data_joint(lens_name, psf_supersampled_factor=1)[source]#

Create a joint kwargs_data dictionary combining data and PSFs across filters.

Parameters:

lens_name (str) – name of the lens system
psf_supersampled_factor (int) – supersampling factor applied to the PSF

Returns:

joint kwargs data mapping suitable for lenstronomy

Return type:

dict

get_lens_config(lens_name)[source]#

Get the ModelConfig object populated with settings for a specific lens.

Parameters:: lens_name (str) – name of the lens system
Returns:: instance of ModelConfig containing the lens configurations
Return type:: ModelConfig

get_psf_data(lens_name, band)[source]#

Get the PSFData instance for a given lens and observing band.

Parameters:

lens_name (str) – name of the lens system
band (str) – observing band or filter name

Returns:

loaded PSF data object

Return type:

PSFData

swim(lens_name, model_id, log=True, mpi=False, recipe_name='galaxy-quasar', thread_count=1, custom_logL_addition=None, use_jax=False)[source]#

Run lens modeling optimizations for a single lens system.

Parameters:

lens_name (str) – name of the lens system to model
model_id (str) – identifier for this specific model run
log (bool) – if True, standard output is logged to a file. Set to False in notebooks.
mpi (bool) – enable MPI for parallel processing
recipe_name (str) – recipe for pre-sampling optimization. Supported: ‘galaxy-quasar’, ‘galaxy-galaxy’, ‘custom’, ‘skip’. ‘custom’ will use the fitting_kwargs_list directly from the yaml settings for pre-sampling optimization. ‘skip’ will skip pre-sampling optimization and directly sample the full model. See Recipe class for details.
thread_count (int) – number of threads to use if multiprocess is enabled
custom_logL_addition (callable function) – a callable function that takes in the optional arguments kwargs_lens, kwargs_source, kwargs_lens_light, kwargs_ps, kwargs_special, kwargs_extinction, kwargs_tracer_source and outputs a float. If use_jax is also True, this function must be compatible with jax.jit
use_jax (bool) – if True, performs modeling through JAXtronomy instead of lenstronomy

Returns:

None

Return type:

None