Configuration Files#

This document provides a detailed explanation of all the allowed options in the config.yaml files for dolphin, but some of them are optional, as indicated. Check out the io_directory_example/settings folder for some example config files.

Top-level information#

  • lens_name: The name of the lens system being modeled.

    • Type: string

    • Example:

      lens_name: "DESJ0408-5354"

  • band: List of photometric bands used for modeling.

    • Type: list of strings

    • Example:

      band: ["F475X", "F600LP"]

  • psf_supersampled_factor: (Optional) Factor by which the Point Spread Function (PSF) is supersampled. Default is 1.

    • Type: float

    • Example:

      psf_supersampled_factor: 3

  • pixel_size: (Optional) Pixel size for each band. If not provided, it will be inferred from the image data.

    • Type: list of floats

    • Example:

      pixel_size: [0.04, 0.04]

Model Section#

  • model: Defines the components of the lens model.

    • Suboptions:

      • lens: List of lens mass profiles. Supported models include: EPL, SIE, SIS, SPEP, PEMD, SHEAR_GAMMA_PSI, FLEXION.

        • Type: list of strings

        • Example:

          lens: ["EPL", "SHEAR_GAMMA_PSI"]

      • lens_light: List of lens light profiles. Supported models include: SERSIC, SERSIC_ELLIPSE, MGE_SET, MGE_SET_ELLIPSE, UNIFORM. The list will be duplicated for each band.

        • Type: list of strings

        • Example:

          lens_light: ["SERSIC_ELLIPSE", "SERSIC_ELLIPSE"]

      • source_light: List of source light profiles. Supported models include: SERSIC_ELLIPSE, SHAPELETS. The list will be duplicated for each band.

        • Type: list of strings

        • Example:

          source_light: ["SERSIC_ELLIPSE", "SHAPELETS"]

      • point_source: (Optional) List of point source models. Supported models include: LENSED_POSITION, SOURCE_POSITION. Can be an empty list for galaxy-galaxy lenses.

        • Type: list of strings

        • Example:

          point_source: ["LENSED_POSITION"]

      • special: (Optional) String or list of special parameter types.

        • Type: string or list of strings

        • Example:

          special: ["astrometric_uncertainty"]

Lens Options#

  • lens_options: Additional options for the lens model.

    • Suboptions:

      • centroid_init: Initial guess for the lens centroid. This will apply to all lens model components. For more fine-tuned control of individual lens model positions, see initial_guesses below.

        • Type: list of floats

        • Example:

          centroid_init: [0.04, -0.04]

      • centroid_bound: Half of the box width to constrain the deflector’s centroid. This will apply to all lens model components. For more fine-tuned control of the bounds for individual lens model positions, see uniform_prior below.

        • Type: float

        • Default: 0.5

        • Example:

          centroid_bound: 0.5

      • initial_guesses: (Optional) Adjust dolphin’s default initial lens parameters.

        • Type: dictionary

        • Example:

          initial_guesses:
  0:
    theta_E: 1.3
    gamma: 2.0
  1:
    e1: 0.3
    e2: -0.1

      • gaussian_prior: (Optional) Gaussian priors for lens parameters.

        • Type: dictionary

        • Example:

          gaussian_prior:
  0: [[gamma, 2.11, 0.03], [theta_E, 1.11, 0.13]]

      • uniform_prior: (Optional) Adjust dolphin’s default lower and upper bounds for lens parameters.

        • Type: dictionary

        • Example:

          uniform_prior:
  0: [[theta_E, 0.2, 1.4], [center_x, 0.5, 0.9]]
  1: [[gamma_ext, 0.02, 0.8]]

      • fix: (Optional) Fix specific parameters for the lens model.

        • Type: dictionary

        • Example:

          fix:
  0:
    gamma: 2.0

      • limit_mass_pa_from_light: (Optional) Maximum allowed difference between the position angle of the mass and light profiles.

        • Type: float

        • Example:

          limit_mass_pa_from_light: 10.0

      • limit_mass_q_from_light: (Optional) Maximum allowed difference between the axis ratio of the mass and light profiles.

        • Type: float

        • Example:

          limit_mass_q_from_light: 0.1

Satellites Option#

  • satellites: (Optional) Options for modeling satellite galaxies.

    • Suboptions:

      • centroid_init: Initial guesses for the centroids of satellites.

        • Type: list of lists of floats

        • Example:

          centroid_init: [[1, 1], [1.5, 1.5]]

      • centroid_bound: Half of the box width to constrain the centroids of satellites.

        • Type: float

        • Example:

          centroid_bound: 0.5

      • is_elliptical: Whether each satellite is elliptical.

        • Type: list of booleans

        • Example:

          is_elliptical: [true, false]

Lens Light Options#

  • lens_light_options: (Optional) Additional options for the lens light model.

    • Suboptions:

      • initial_guesses: (Optional) Adjust dolphin’s default initial lens light parameters.

        • Type: dictionary

        • Example:

          initial_guesses:
  0:
    R_sersic: 2.3
    n_sersic: 1
  1:
    R_sersic: 0.3
    n_sersic: 4

      • fix: Fix specific parameters for the lens light profile.

        • Type: dictionary

        • Example:

          fix: {0: {"n_sersic": 4.}}

      • gaussian_prior: Gaussian priors for lens light parameters.

        • Type: dictionary

        • Example:

          gaussian_prior:
  0:
    [[R_sersic, 0.21, 0.15]]

      • uniform_prior: (Optional) Adjust dolphin’s default lower and upper bounds for lens light parameters.

        • Type: dictionary

        • Example:

          uniform_prior:
  0: [[R_sersic, 0.2, 7.], [n_sersic, 0.5, 4.]]

      • mge_config: (Optional) Configuration for MGE_SET and MGE_SET_ELLIPSE light profiles. Can be used to set the number of Gaussian components.

        • Type: dictionary

        • Example:

          mge_config:
  0:
    n_comp: 20

Source Light Options#

  • source_light_options: (Optional) Additional options for the source light model.

    • Suboptions:

      • initial_guesses: (Optional) Adjust dolphin’s default initial source light parameters.

        • Type: dictionary

        • Example:

          initial_guesses:
  0:
    R_sersic: 2.3
    n_sersic: 1
  1:
    R_sersic: 0.3
    n_sersic: 4

      • gaussian_prior: Gaussian priors for source light parameters.

        • Type: dictionary

        • Example:

          gaussian_prior:
  0: [[beta, 0.15, 0.05]]

      • uniform_prior: (Optional) Adjust dolphin’s default lower and upper bounds for source light parameters.

        • Type: dictionary

        • Example:

          uniform_prior:
  0: [[R_sersic, 0.2, 7.], [n_sersic, 0.5, 4.]]

      • shapelet_scale_logarithmic_prior: Whether to apply a logarithmic prior on the shapelet scale parameter.

        • Type: boolean

        • Example:

          shapelet_scale_logarithmic_prior: true

      • n_max: Maximum number of Shapelet profiles for each band.

        • Type: integer or list of integers

        • Example:

          n_max: [2, 4]

Point Source Options#

  • point_source_options: (Optional) Options for point source models.

    • Suboptions:

      • ra_init: Initial guess for point source RA positions.

        • Type: list of floats

        • Example:

          ra_init: [0.1, -0.1]

      • dec_init: Initial guess for point source DEC positions.

        • Type: list of floats

        • Example:

          dec_init: [0.1, -0.1]

      • bound: Bound width for searching the point source centroids.

        • Type: float

        • Example:

          bound: 0.2

      • gaussian_prior: Gaussian priors for point source parameters.

        • Type: dictionary

        • Example:

          gaussian_prior:
  0: [[ra_image, 0.1, 0.05]]

      • time_delays_measured: Relative time delays (in days) with respect to the first point-source image. If this is provided, time_delays_covariance must also be provided to compute the time-delay likelihood, which is then added to the combined likelihood.

        • Type: list of floats`

        • Example:

          time_delays_measured: [3., 2., 1.]

      • time_delays_covariance: Full covariance matrix of the provided time delay measurements.

        • Type: list of list of floats

        • Example:

          time_delays_covariance: [[1., 0., 0.], [0., 1., 0.], [0., 0., 1.]]

Special Options#

  • special_options: (Optional) Initialization of special parameters.

    • Suboptions:

      • delta_x_image: Initial spread from point source centroid in the x-axis.

        • Type: array of floats corresponding to the number of point sources

        • Example:

          delta_x_image: [0.0, 0.0]

      • delta_y_image: Initial spread from point source centroid in the y-axis.

        • Type: array of floats corresponding to the number of point sources

        • Example:

          delta_y_image: [0.0, 0.0]

      • delta_image_lower: Lower bound in spread of point source centroid sampler.

        • Type: float

        • Example:

          delta_image_lower: -0.004

      • delta_image_upper: Upper bound in spread of point source centroid sampler.

        • Type: float

        • Example:

          delta_image_upper: 0.004

      • cosmology: (Optional) Astropy cosmology model to use for time-delay computations. Supported models: FlatLambdaCDM (default), LambdaCDM, FlatwCDM, wCDM, Flatw0waCDM, w0waCDM, w0wzCDM, Flatw0wzCDM, wpwaCDM, FlatwpwaCDM.

        • Type: string

        • Example:

          cosmology: "FlatLambdaCDM"

      • H0: Fiducial Hubble constant in km/s/Mpc (required for all cosmologies).

        • Type: float

        • Example:

          H0: 70.0

      • Om0: Fiducial matter energy density at z=0 (required for all cosmologies).

        • Type: float

        • Example:

          Om0: 0.3

      • Ode0: (Optional) Fiducial dark energy density at z=0 (required for non-flat cosmologies like LambdaCDM, wCDM, w0waCDM, w0wzCDM, wpwaCDM).

        • Type: float

        • Example:

          Ode0: 0.7

      • w0: (Optional) Dark energy equation of state parameter at z=0 (used in wCDM, FlatwCDM, w0waCDM, Flatw0waCDM, w0wzCDM, Flatw0wzCDM).

        • Type: float

        • Example:

          w0: -1.0

      • wa: (Optional) Dark energy equation of state parameter derivative (used in w0waCDM, Flatw0waCDM, wpwaCDM, FlatwpwaCDM).

        • Type: float

        • Example:

          wa: 0.0

      • wz: (Optional) Dark energy equation of state parameter derivative with respect to redshift (used in w0wzCDM, Flatw0wzCDM).

        • Type: float

        • Example:

          wz: 0.1

      • wp: (Optional) Dark energy equation of state parameter at the pivot redshift (used in wpwaCDM, FlatwpwaCDM).

        • Type: float

        • Example:

          wp: -1.0

      • zp: (Optional) Pivot redshift (used in wpwaCDM, FlatwpwaCDM).

        • Type: float

        • Example:

          zp: 0.5

      • Tcmb0: (Optional) Temperature of the CMB at z=0 in Kelvin.

        • Type: float

        • Example:

          Tcmb0: 2.725

      • general_scaling: Scale specific model parameters together across multiple profiles. Input should be a dictionary mapping parameter names to the masks defining which lens models are scaled together.

        • Type: dictionary

        • Example: Scaling theta_E for the second and third mass profiles together, but not the first.

          general_scaling:
  theta_E:
    [False, 1, 1]

      • {param_name}_scale_factor: The scaling relation factor for the specified param_name across multiple profiles. Instead of individually sampling the connected parameters, only this scale factor will be sampled, and all the connected parameters will be scaled based on the same factor.

        • Type: list

        • Example:

          theta_E_scale_factor: [1]

      • {param_name}_scale_factor_sigma: Initial paramater spread relative to {param_name}_scale_factor.

        • Type: list

        • Example:

          theta_E_scale_factor_sigma: [0.05]

      • {param_name}_scale_pow: Power-law scaling factor for the specified param_name scaling.

        • Type: list

        • Example:

          theta_E_scale_pow: [1]

      • Combining all of the above, a specified parameter, \(p\), is scaled from the sampled scale factor, \(f_p\), and sampled power-law index, \(\alpha_p\), as:

        \[p \rightarrow p_{\mathrm{scaled}} = f_p \, p^{\alpha_p}\]

Numeric Options#

  • numeric_options: Numerical settings for the modeling process.

    • Suboptions:

      • supersampling_factor: Supersampling factor for each band.

        • Type: list of integers

        • Example:

          numeric_options:
  supersampling_factor: [2]

Fitting Options#

  • fitting: Settings for the fitting process.

    • Suboptions:

      • pso: Whether to use Particle Swarm Optimization (PSO) for fitting.

        • Type: boolean

        • Example:

          pso: true

      • pso_settings: Settings for the PSO algorithm.

        • Suboptions:

          • num_particle: Number of particles in the swarm.

            • Type: integer

            • Example:

              num_particle: 50

          • num_iteration: Number of iterations for PSO.

            • Type: integer

            • Example:

              num_iteration: 50

      • sampling: (Optional) Whether to perform sampling after optimization.

        • Type: boolean

        • Example:

          sampling: true

      • sampler: The sampler to use for sampling. Supported samplers are emcee and Nautilus.

        • Type: string

        • Example:

          sampler: emcee

      • sampler_settings: Settings for the sampler. For full documentation of parameters, refer to the lenstronomy sampler documentation and the Nautilus documentation.

        • Suboptions:

          Recommended Nautilus options:

          • n_live: Number of live points used by the nested sampler.

            • Type: integer

            • Example:

              n_live: 2000

          • n_eff: Minimum targeted effective sample size. The algorithm will sample from the shells until this is reached.

            • Type: float

            • Example:

              n_eff: 10000.0

          • verbose: If True, prints detailed information about the sampler’s progress.

            • Type: boolean

            • Example:

              verbose: true

          • pass_dict: Whether to pass dictionaries to the likelihood. Usually set to false for better performance.

            • Type: boolean

            • Example:

              pass_dict: false

          • filepath: Path to a file (.h5 or .hdf5) where Nautilus will save its internal state for checkpointing.

            • Type: string

            • Example:

              filepath: "nautilus_checkpoint.hdf5"

          • resume: Whether to resume a run from the file specified in filepath.

            • Type: boolean

            • Example:

              resume: true

          Emcee-specific options:

          • n_burn: Number of burn-in steps.

            • Type: integer

            • Example:

              n_burn: 2

          • n_run: Number of sampling steps.

            • Type: integer

            • Example:

              n_run: 2

          • walkerRatio: Ratio of walkers to parameters.

            • Type: integer

            • Example:

              walkerRatio: 2

          • init_samples: (Optional) Initial samples for walkers.

            • Type: list of lists of floats

          • n_walkers: (Optional) Number of walkers of emcee. If set, this overwrites the walkerRatio input.

            • Type: integer

            • Example:

              n_walkers: 100

          • sigma_scale: (Optional) Scaling of the initial parameter spread relative to the width in the initial settings. Default is 1.0.

            • Type: float

            • Example:

              sigma_scale: 1.0

          • threadCount: (Optional) Number of CPU threads to use for multiprocessing.

            • Type: integer

            • Example:

              threadCount: 4

          • re_use_samples: (Optional) If True and init_samples is provided, re-uses the samples described.

            • Type: boolean

          • progress: (Optional) If True, shows the progress bar during sampling.

            • Type: boolean

          • backend_filename: (Optional) Name of the HDF5 file where the emcee sampling state is saved for checkpointing.

            • Type: string

            • Example:

              backend_filename: "mcmc_emcee_checkpoint.h5"

          • start_from_backend: (Optional) If True, start sampling from the state saved in backend_filename.

            • Type: boolean

      • psf_iteration: (Optional) Whether to perform iterative PSF fitting.

        • Type: boolean

        • Example:

          psf_iteration: true

      • psf_iteration_settings: Settings for iterative PSF fitting.

        • Suboptions:

          • stacking_method: Method for stacking PSFs.

            • Type: string

            • Example:

              stacking_method: "median"

          • num_iter: Number of PSF iterations.

            • Type: integer

            • Example:

              num_iter: 20

          • psf_iter_factor: Factor for PSF iteration.

            • Type: float

            • Example:

              psf_iter_factor: 0.5

          • keep_psf_variance_map: Whether to keep the PSF variance map.

            • Type: boolean

            • Example:

              keep_psf_variance_map: true

          • psf_symmetry: Symmetry of the PSF.

            • Type: integer

            • Example:

              psf_symmetry: 4

          • block_center_neighbour: Block center neighbour factor.

            • Type: float

            • Example:

              block_center_neighbour: 0.0

  • fitting_kwargs_list: (Optional) User-provided list of fitting sequences to bypass the automated recipes in dolphin.

In order to use this list, the Processor.swim() method must be called with recipe_name="custom".

  • Type: list

  • Example:

    fitting_kwargs_list:
  - ['PSO', {'sigma_scale': 1., 'n_particles': 50, 'n_iterations': 50}]

Lenstronomy Arbitrary Keyword Arguments#

Model Options#

  • kwargs_model: (Optional) Pass any arbitrary arguments strictly allowed in lenstronomy.LensModel, lenstronomy.LightModel inside this section.

  • model_options (or kwargs_model): (Optional) Pass any arbitrary arguments strictly allowed in lenstronomy.Util.class_creator.create_class_instances() inside this section.

  • kwargs_constraints: (Optional) Pass any arbitrary constraints strictly allowed in lenstronomy.Workflow.fitting_sequence inside this section.

Constraints Options#

  • constraints_options (or kwargs_constraints): (Optional) Pass any arbitrary constraints strictly allowed in lenstronomy.Sampling.parameters.Param() inside this section.

    • Example:

      kwargs_constraints:
constraints_options:
  joint_lens_with_light: [[0, 0, ['center_x', 'center_y']]]

Likelihood Options#

  • likelihood_options (or kwargs_likelihood): (Optional) Pass any arbitrary likelihood arguments strictly allowed in lenstronomy.Sampling.likelihood.Likelihood() inside this section.

Mask Options#

  • mask: (Optional) Settings for masking regions of the image.

    • Suboptions:

      • provided: Set to true to use custom .npy mask files from the settings/masks/ directory instead of using analytical masking below.

        • Type: boolean

        • Example:

          provided: false

      • centroid_offset: Offset for the centroid of the mask.

        • Type: list of lists of floats

        • Example:

          centroid_offset: [[0.0, 0.0], [0.0, 0.0]]

      • mask_edge_pixels: Number of edge pixels to mask.

        • Type: list of integers

        • Example:

          mask_edge_pixels: [0, 2]

      • radius: Radius of the mask for each band.

        • Type: list of floats

        • Example:

          radius: [20.0, 20.0]

      • a, b, angle: Elliptical mask parameters for each band. Used when radius is not provided.

        • Type: list of floats

        • Example:

          a: [10.0, 10.0]
b: [5.0, 5.0]
angle: [0.0, 0.0]

      • extra_regions: List of circular regions to mask additionally. Format is [ra, dec, radius].

        • Type: list of lists of lists of floats

        • Example:

          extra_regions:
  - [[1.0, -1.0, 0.5]]