Config Input Field

The input field indicates where to find any files that you want to use in building the images or how to set up any objects that require initialization.

Input Types

The input fields defined by GalSim are:

• catalog defines an input catalog that has values for each object. Connected with ‘Catalog’ value type described in Config Values.

  • file_name = str_value (required) The name of the file with the input catalog.

  • dir = str_value (default = ‘.’) The directory the file is in.

  • file_type = str_value (default = automatically determined from extension of file_name) Valid options are:

    • ‘ascii’ Read from an ASCII file.

      • comments = str_value (default = ‘#’) The character used to indicate the start of a comment in an ASCII catalog.

    • ‘fits’ Read from a FITS binary table.

      • hdu = int_value (default = 1) Which hdu to use within the FITS file. Note: 0 means the primary HDU, the first extension is 1.

• dict defines an input dictionary, such as a YAML or JSON file. Connected with ‘Dict’ value type described in Config Values.

  • file_name = str_value (required) The name of the dictionary file.

  • dir = str_value (default = ‘.’) The directory the file is in.

  • file_type = str_value (default = automatically determined from extension of file_name) Valid options are:

    • ‘yaml’ Read from a YAML file.

    • ‘json’ Read from a JSON file.

    • ‘pickle’ Read from a python pickle file.

  • key_split = str_value (default = ‘.’) For specifying keys below the first level of the dictionary, use this string to split the key value into multiple strings. e.g. If key_split = ‘.’ (the default) then key : galaxy_constants.redshift would be parsed as dict['galaxy_constants']['redshift']. Usually ‘.’ is an intuitive choice, but if some of your key names have a ‘.’ in them, then this would not work correctly, so you should pick something else.

• fits_header lets you read from the header section of a FITS file. Connected with ‘FitsHeader’ value type described in Config Values.

  • file_name = str_value (required) The name of the FITS file.

  • dir = str_value (default = ‘.’) The directory the file is in.

  • hdu = int_value (optional) Which HDU to read from the input file. Default is 0 (the primary HDU), unless the compression implies that the first extension should be used.

  • compression = str_value (optional) The kind of compression if any. The default is to base the compression on the file extension. e.g. ‘blah.fits.fz’ implies Rice compression. But it can also be specified explicitly. Supported values are ‘none’, ‘rice’, ‘gzip’, ‘bzip2’, ‘gzip_tile’, ‘hcompress’, ‘plio’.

  • text_file = bool_value (default = False) Whether the input file is actually a text file, rather than a binary FITS file. Normally the file is taken to be a FITS file, but if this is True, then it will read it as a text file containing the header information, such as the .head file output from SCamp.

• real_catalog defines a catalog of real galaxy images. Connected with ‘RealGalaxy’ profile described in Config Objects.

  • file_name = str_value (optional) The name of the file with the input catalog. If omitted, it will try to use the standard catalog in the $PREFIX/share/galsim directory. You can download the COSMOS catalog to that directory with the executable galsim_download_cosmos.

  • sample = str_value (optional) A string that can be used to specify the sample to use, either “23.5” or “25.2”. At most one of file_name and sample should be specified.

  • dir = str_value (optional) The directory the file is in (along with related image and noise files).

  • preload = bool_value (default = False) Whether to preload all the header information from the catalog fits file into memory at the start. If preload=True, the bulk of the I/O time happens at the start of the processing. If preload=False, there is approximately the same total I/O time (assuming you eventually use most of the image files referenced in the catalog), but it is spread over the various RealGalaxy objects that get built.

• cosmos_catalog defines an input catalog that has values for each object. Connected with ‘COSMOSCatalog’ profile described in Config Objects.

  • file_name = str_value (optional) The name of the file with the input catalog. If omitted, it will try to use the standard catalog in the $PREFIX/share/galsim directory. You can download the COSMOS catalog to that directory with the executable galsim_download_cosmos.

  • sample = str_value (optional) A string that can be used to specify the sample to use, either “23.5” or “25.2”. At most one of file_name and sample should be specified.

  • dir = str_value (optional) The directory the file is in (along with related image and noise files).

  • preload = bool_value (default = False) Whether to preload all the header information from the catalog fits file into memory at the start. If preload=True, the bulk of the I/O time happens at the start of the processing. If preload=False, there is approximately the same total I/O time (assuming you eventually use most of the image files referenced in the catalog), but it is spread over the various RealGalaxy objects that get built.

  • use_real = bool_value (default = True) Whether load the RealGalaxy catalog. If this is True, you can request either real or parametric galaxies from the catalog. But if you are only going to use parametric galaxies, then you may set this to False, and it will not bother to load the real galaxies.

  • exclusion_level = str_value (default=’marginal’) Level of additional cuts to make on the galaxies based on the quality of postage stamp definition and/or parametric fit quality [beyond the minimal cuts imposed when making the catalog - see Mandelbaum et al. (2012, MNRAS, 420, 1518) for details]. Valid options are:

    • “none”: No cuts.

    • “bad_stamp”: Apply cuts to eliminate galaxies that have failures in postage stamp definition. These cuts may also eliminate a small subset of the good postage stamps as well.

    • “bad_fits”: Apply cuts to eliminate galaxies that have failures in the parametric fits. These cuts may also eliminate a small subset of the good parametric fits as well.

    • “marginal”: Apply the above cuts, plus ones that eliminate some more marginal cases.

  • min_hlr float_value (optional) Exclude galaxies whose fitted half-light radius is smaller than this value (in arcsec).

  • max_hlr float_value (optional) Exclude galaxies whose fitted half-light radius is larger than this value (in arcsec).

  • min_flux float_value (optional) Exclude galaxies whose fitted flux is smaller than this value (in arcsec).

  • max_flux float_value (optional) Exclude galaxies whose fitted flux is larger than this value (in arcsec).

• galaxy_sample is a generalization of cosmos_catalog that provides similar functionality for arbitrary input sample catalogs. Connected with ‘SampleGalaxy’ profile described in Config Objects.

  • file_name = str_value (required) The name of the file with the input catalog.

  • dir = str_value (optional) The directory the file is in (along with related image and noise files).

  • preload = bool_value (default = False) Whether to preload all the header information from the catalog fits file into memory at the start. If preload=True, the bulk of the I/O time happens at the start of the processing. If preload=False, there is approximately the same total I/O time (assuming you eventually use most of the image files referenced in the catalog), but it is spread over the various RealGalaxy objects that get built.

  • orig_exptime = float_value (default = 1.) The exposure time (in seconds) of the original observations.

  • orig_area = float_value (default = 1.) The effective collecting area (in cm^2) of the original observations.

  • use_real = bool_value (default = True) Whether load the RealGalaxy catalog. If this is True, you can request either real or parametric galaxies from the catalog. But if you are only going to use parametric galaxies, then you may set this to False, and it will not bother to load the real galaxies.

  • exclusion_level = str_value (default=’none’) Level of additional cuts to make on the galaxies based on the quality of postage stamp definition and/or parametric fit quality. Valid options are:

    • “none”: No cuts.

    • “bad_stamp”: Apply cuts to eliminate galaxies that have failures in postage stamp definition. These cuts may also eliminate a small subset of the good postage stamps as well.

    • “bad_fits”: Apply cuts to eliminate galaxies that have failures in the parametric fits. These cuts may also eliminate a small subset of the good parametric fits as well.

    • “marginal”: Apply the above cuts, plus ones that eliminate some more marginal cases.

  • min_hlr = float_value (optional) Exclude galaxies whose fitted half-light radius is smaller than this value (in arcsec).

  • max_hlr = float_value (optional) Exclude galaxies whose fitted half-light radius is larger than this value (in arcsec).

  • min_flux = float_value (optional) Exclude galaxies whose fitted flux is smaller than this value (in arcsec).

  • max_flux = float_value (optional) Exclude galaxies whose fitted flux is larger than this value (in arcsec).

  • cut_ratio = float_value (optional) For the “bad_stamp” exclusions, cut out any stamps with average adjacent pixels larger than this fraction of the peak pixel count.

  • sn_limit = float_value (default = 10.) For the “bad_stamp” exclusions, cut out any stamps with estimated S/N for an elliptical Gaussian less than this limit.

  • min_mask_dist = float_value (default = 10.) For the “bad_stamp” exclusions, remove any stamps that have some masked pixels closer to the center than this minimum distance (in pixels).

• nfw_halo defines an NFW halo. Connected with ‘NFWHaloShear’ and ‘NFWHaloMagnification’ value types described in Config Values.

  • mass = float_value (required) The mass of the halo in units of (Msolar / h).

  • conc = float_value (required) The concentration parameter, defined as the virial radius / scale radius.

  • redshift = float_value (required) The redshift of the halo.

  • halo_pos = pos_value (default = 0,0) The position of the halo in world coordinates relative to the origin of the world coordinate system. (Typically you would want to to set wcs.origin to ‘center’ to get the halo in the center of the image.)

  • omega_m = float_value (default = 1 - omega_lam)

  • omega_lam = float_value (default = 1 - omega_m or 0.7 if neither is specified)

• power_spectrum defines a lensing power spectrum. Connected with ‘PowerSpectrumShear’ and ‘PowerSpectrumMagnification’ value types described in Config Values.

  • e_power_function = str_value (at least one of e_power_function and b_power_function is required) A string describing the function of k to use for the E-mode power function. e.g. 'k**2'. Alternatively, it may be a file name from which a tabulated power spectrum is read in.

  • b_power_function = str_value (at least one of e_power_function and b_power_function is required) A string describing the function of k to use for the B-mode power function. e.g. 'k**2'. Alternatively, it may be a file name from which a tabulated power spectrum is read in.

  • delta2 = bool_value (default = False) Whether the function is really Delta^2(k) = k^2 P(k)/2pi rather than P(k).

  • units = str_value (default = ‘arcsec’) The appropriate units for k^-1. The default is to use our canonical units, arcsec, for all position variables. However, power spectra are often more appropriately defined in terms of radians, so that can be specified here to let GalSim handle the units conversion. Other choices are arcmin or degrees.

  • grid_spacing = float_value (required for ‘Scattered’ image type, automatic for ‘Tiled’) The distance between grid points on which the power spectrum shears are instantiated.

  • interpolant = str_value (default = ‘Linear’) What to use for interpolating between pixel centers. Options are ‘Nearest’, ‘Linear’, ‘Cubic’, ‘Quintic’, ‘Sinc’, or ‘LanczosN’, where the ‘N’ after ‘Lanczos’ should be replaced with the integer order to use for the Lanczos filter.

  • ngrid = int_value (optional) The number of grid points to use. The default is to use image_size * scale / grid_spacing.

  • center = pos_value (optional) The center point of the grid. The default is to use the image center.

  • index = str_value (optional) If set, the power spectrum will only be computed when this index changed. E.g. if index is ‘file_num’, then it will only update with each new file, not with each image.

  • variance = float_value (optional) If set, rescale the overall variance of the generated shears to this value.

• initial_image specifies an initial image (read from an FITS file) to draw onto, rather than create a new blank image.

  • file_name = str_value (required) The name fo the file with the desired initial image.

  • dir = str_value (default = ‘.’) The directory the file is in.

  • read_header = bool_value (default = False) Whether to read the header as well.

Another feature of the input field is that it may optionally be a list. So you can have multiple input catalogs for instance; one for object parameters and one for overall image parameters perhaps. When using values with the type ‘InputCatalog’, you would specify which catalog to use with num. If you only have a single item for one of the inputs, you can omit the num parameter when you are using it.

Custom Input Types

To define your own input type, you will need to write an importable Python module (typically a file in the current directory where you are running galsim, but it could also be something you have installed in your Python distro) with a class that will be used to load whatever information you want loaded:

class MyInputData(object):
    """A class that knows how to load some information from a file or maybe build some
    structure in advance that will be used repeatedly in the simulation.
    """
    def __init__(self, ...):
        pass

Next you need to write a Loader class that is a subclass of galsim.config.InputLoader, which the config code will use to build your input object with the right initialization kwargs.

class galsim.config.InputLoader(init_func, has_nobj=False, file_scope=False, takes_logger=False, use_proxy=True, worker_init=None, worker_initargs=None)

Define how to load a particular input type.

The base class is often sufficient for simple types, but you may derive from it and override some of the functions to deal with special handling requirements.

The loader object defines a few attributes that will be used by the processing framework, so any derived class should make sure to define them as well.

init_func

The class or function that will be used to build the input object.

has_nobj

Whether the object can be used to automatically determine the number of objects to build for a given file or image. For example, a galsim.Catalog has a specific number of rows in it. In many cases, you will just want to run through the whole catalog for each output file. So the number of objects to build will just be the number of objects in the input catalog. [default: False]

If this is True, the constructed input object must have a getNObjects() method. The constructor may (if practical) only load enough to figure out how many objects there are. Other attributes may use lazy properties to delay finishing the read if that is efficient.

It may optionally also have a getApproxNObjects() method, which may return an approximate estimate of the number of objects. This is used for the initial calculation of what object numbers to use for each file/image, and it is generally acceptable if this is an over-estimate, even a pretty egregious over-estimate if necessary.

file_scope

Whether the input object might be relevant at file scope when the file and image is initially being set up. [default: False]

If this is False, then the input object won’t be loaded until after the initial file setup. For example, you might store the file names you want to use for the output files in a YAML file, which you plan to read in as a dict input object. Thus, dict is our canonical example of an input type for which this parameter should be True.

takes_logger

Whether the input object has a logger attribute. If so, and a proxy is being used, then the logger will be replaced with a logger proxy. [default: False]

use_proxy

Whether to use a proxy for commicating between processes. This is normally necessary whenever multiprocessing is being used, but there are cases where it is not necessary and just slows things down. [default: True]

worker_init

One way to avoid using a proxy is to follow the shared memory model decsribed in the doc string of AtmosphericScreen. This mode uses a global dict, which is initialized for each worker at the start of multi-processing. To use this method, one needs to provide an initialization function that gets run when each worker starts. [default: None]

worker_initargs

A function to provide the necessary arguments to worker_init. [default: None] This is required whenever worker_init is not None.

getKwargs(config, base, logger)

Parse the config dict and return the kwargs needed to build the input object.

The default implementation looks for special class attributes called:

_req_params

A dict of required parameters and their types.

_opt_params

A dict of optional parameters and their types.

_single_params

A list of dicts of parameters such that one and only one of parameter in each dict is required.

_takes_rng

A bool value saying whether an rng object is required.

See galsim.Catalog for an example of a class that sets these attributes.

In addition to the kwargs, we also return a bool value, safe, that indicates whether the constructed object will be safe to keep around for multiple files (True) of if it will need to be rebuilt for each output file (False).

Parameters:

• config – The config dict for this input item

• base – The base config dict

• logger – If given, a logger object to log progress. [default: None]

Returns:

kwargs, safe

initialize(input_objs, num, base, logger)

Do any global setup for input objects right after they are loaded.

In the base class, this function does not do anything. It can be used to do things like load an input object and then assign it to an eval variable in the base configuration dictionary.

When writing this method, remember that the entries in input objs are set to None initially. This can cause problems for some operations on them and so you may want to test for this condition with code like all(iobj is not None for iobj in input_objs).

Parameters:

• input_objs – The (current) list of input objects.

• num – The entry in the list that was loaded.

• base – The base configuration dict.

• logger – If given, a logger object to log progress. [default: None]

setupImage(input_obj, config, base, logger)

Do any necessary setup at the start of each image.

In the base class, this function does not do anything. But see PowerSpectrumLoader for an example that does require some setup at the start of each image.

Parameters:

• input_obj – The input object to use

• config – The configuration dict for the input type

• base – The base configuration dict.

• logger – If given, a logger object to log progress. [default: None]

useProxy(config, logger=None)

Return whether to use a proxy for the input object.

The default behavior is to return self.use_proxy, which is set by the constructor parameters. But if you want to decide whether to use a proxy based on something in the config dict, you can override this and decide at run time.

Parameters:

• config – The base configuration dict.

• logger – If given, a logger object to log progress. [default: None]

The main thing you might want to override is the galsim.config.InputLoader.getKwargs function to determine what kwargs you want to pass to your initialization function or class based on the parameters in the config dict. The base class, galsim.config.InputLoader uses special class attributes, which most GalSim classes have defined (for precisely this purpose). If you want to follow that same model, and there is no special setup to do at the start of each image, then you can just use the InputLoader itself rather than defining your own subclass.

In either case, in your Python module, you need to register this function with some name, which will be the name of the attribute in the input field that triggers the use of this Loader object:

galsim.config.RegisterInputType('CustomInput', CustomInputLoader(MyInputData))

or:

galsim.config.RegisterInputType('CustomInput', InputLoader(MyInputData))

galsim.config.RegisterInputType(input_type, loader)

Register an input type for use by the config apparatus.

Parameters:

• input_type – The name of the type in config[‘input’]

• loader – A loader object to use for loading in the input object. It should be an instance of InputLoader or a subclass thereof.

In the above functions, the base parameter is the original full configuration dict that is being used for running the simulation. The config parameter is the local portion of the full dict that defines the object being built, which would in this case be base['input']['CustomInput'].

Finally, to use this custom type in your config file, you need to tell the config parser the name of the module to load at the start of processing. e.g. if this function is defined in the file my_custom_input.py, then you would use the following top-level modules field in the config file:

modules:
    - my_custom_input

This modules field is a list, so it can contain more than one module to load if you want. Then before processing anything, the code will execute the command import my_custom_input, which will read your file and execute the registration command to add the builder to the list of valid input types.

Then you can use this as a valid value type:

input:
    CustomInput:
        ...

For examples of custom inputs, see des_wcs.py , which is used by meds.yaml .

Also The DES Module uses custom inputs for the DES_PSFEx and DES_Shapelet object types, which are used by draw_psf.yaml .

It may also be helpful to look at the GalSim implementation of our various included input types (click on the [source] links):

class galsim.config.input_cosmos.SampleLoader(cls, input_field)

galsim.config.input_cosmos._BuildCOSMOSGalaxy(config, base, ignore, gsparams, logger)

Build a COSMOS galaxy using the cosmos_catalog input item.

class galsim.config.input_nfw.NFWLoader(init_func, has_nobj=False, file_scope=False, takes_logger=False, use_proxy=True, worker_init=None, worker_initargs=None)

galsim.config.input_nfw._GenerateFromNFWHaloShear(config, base, value_type)

Return a shear calculated from an NFWHalo object.

galsim.config.input_nfw._GenerateFromNFWHaloMagnification(config, base, value_type)

Return a magnification calculated from an NFWHalo object.

class galsim.config.input_powerspectrum.PowerSpectrumLoader(init_func, has_nobj=False, file_scope=False, takes_logger=False, use_proxy=True, worker_init=None, worker_initargs=None)

galsim.config.input_powerspectrum._GenerateFromPowerSpectrumShear(config, base, value_type)

Return a shear calculated from a PowerSpectrum object.

galsim.config.input_powerspectrum._GenerateFromPowerSpectrumMagnification(config, base, value_type)

Return a magnification calculated from a PowerSpectrum object.

galsim.config.input_real._BuildRealGalaxy(config, base, ignore, gsparams, logger, param_name='RealGalaxy')

Build a RealGalaxy from the real_catalog input item.

galsim.config.input_real._BuildRealGalaxyOriginal(config, base, ignore, gsparams, logger)

Return the original image from a RealGalaxy using the real_catalog input item.