Config Documentation

This documentation is for version 1.1. For the v1.0 documenation, see Config Documentation-v1.0.

1. Overview
2. Top level fields

• psf
• gal
• image
• input
• output

3. Setting values

• float_value
• int_value
• bool_value
• str_value
• angle_value
• shear_value
• pos_value

4. The Eval type
5. TODO list

Overview

The basic configuration method is to use a dictionary which can be parsed in python. Within that structure, each field can either be a value, another dictionary which is then further parsed, or occasionally a list of items (which can be either values or dictionaries). The hierarchy can go as deep as necessary.

Our example config files are all yaml files, which get read using the executable galsim. This is a nice format for config files, but it is not required. Anything that can represent a dictionary will do. For example, the executable galsim also reads in and processes json-style config files if you prefer.

If you would like a kind of tutorial that goes through typical uses of the config files, there are a series of demo config files in the GalSim examples directory. See Tutorials for more information. This documentation is meant to be more of a reference once you already have the basic idea of how the config files generally work.

For a concrete example of what a config file looks like, here is demo1.yaml (the first file in the aforementioned tutorial) stripped of most of the comments to make it easier to see the essence of the structure:

gal :
    type : Gaussian
    sigma : 2  # arcsec
    flux : 1.e5  # total counts in all pixels

psf :
    type : Gaussian
    sigma : 1  # arcsec

image :
    pixel_scale : 0.2  # arcsec / pixel
    noise :
        type : Gaussian
        sigma : 30  # standard deviation of the counts in each pixel

output :
    dir : output_yaml
    file_name : demo1.fits

Finally, in addition to reading from a config file, the galsim executable can also take config items on the command line. The typical command line is just something like

galsim demo1.yaml

but sometimes it is convenient (e.g. when batch running a bunch of different things that are all almost identical, but differ in one or two things) to add or edit parameters on the command line. e.g.

galsim demo1.yaml gal.flux=1.e4 output.file_name=demo1_1e4.fits
galsim demo1.yaml gal.flux=2.e4 output.file_name=demo1_2e4.fits
galsim demo1.yaml gal.flux=3.e4 output.file_name=demo1_3e4.fits
galsim demo1.yaml gal.flux=4.e4 output.file_name=demo1_4e4.fits

This lets you use shell scripting functionality in conjunction with galsim, which can be rather handy. Notice that the . is used to separate levels within the config hierarchy. So gal.flux represents config['gal']['flux'].

The top level fields

At the top level, there are 6 basic fields:

• psf defines what kind of PSF profile to use.
• gal defines what kind of galaxy profile to use.
• image defines extra information about the images to draw for each object.
• input defines any necessary input files or things that need some kind of initialization.
• output defines the names and format of the output files.

None of these are technically required, although it is an error to have neither psf nor gal. (You need to draw something!) But the most common usage would be to use psf, gal, image and output. It is not uncommon for there to be no input files, so you will often omit the input field. And sometimes you will omit the gal field to draw an image with just stars.

We will go through each one in turn. As we do, some values will be called float_value, int_value, etc. These can either be a value directly (e.g. float_value could just be 1.5), or they can be a dict that describes how the value should be generated each time (e.g. a random number or a value read from an input catalog). We defer the descriptions of those to the next section "Setting values" that explains how you can specify each kind of value.

In addition each value will have one of (required) or (optional) or (default = something) to indicate whether the item is required or if there is some sensible default value. The (optional) tag usually means that the action in question will not be done at all, rather than done using some default value. Also, sometimes no item is individually required, but one of several is.

Sometimes a particular option is only available in conjunction with a particular type. e.g. If the PSF type is 'Gaussian', then the size could be specified as sigma. But sigma is not avalable for other PSF types. This is indicated by putting the sigma item underneath the 'Gaussian' option. On the other hand, other things may be available for all types. e.g. all PSF types can be given some ellipticity with the ellip option. This is indicated by putting the ellip item at the same intentation level as type.

psf

The psf field defines the profile of the PSF. Technically, any profile can be used for either psf or gal (or even pix). Internally, we do not restrict which profiles are valid for psf and which are valid for gal. However, most of the profiles are really more relevant for one or the other, so here we describe the types that are more likely to be used as a PSF, and the others will be described in the gal section.

Valid psf fields are:

• type = str (required) Valid options are:
  • 'Gaussian' A circular Gaussian profile: I(r) ~ exp(-r^2 / (2 sigma^2)).
    • sigma = float_value (exactly one of sigma, fwhm or half_light_radius is required)
    • fwhm = float_value (exactly one of sigma, fwhm or half_light_radius is required)
    • half_light_radius = float_value (exactly one of sigma, fwhm or half_light_radius is required)
  • 'Moffat' A Moffat profile: I(r) ~ (1 + (r/scale_radius)^2)^(-beta).
    • beta = float_value (required)
    • scale_radius = float_value (exactly one of scale_radius, fwhm or half_light_radius is required)
    • fwhm = float_value (exactly one of scale_radius, fwhm or half_light_radius is required)
    • half_light_radius = float_value (exactly one of scale_radius, fwhm or half_light_radius is required)
    • trunc = float_value (optional) The profile can be truncated to 0 at some radius if desired. The default is no truncation.
  • 'Airy' A simple Airy disk. (Typically one would convolve this by some model of the atmospheric component of the PSF. cf. 'Convolution' below.)
    • lam_over_diam = float_value (required) Lambda / telescope_diameter.
    • obscuration = float_value (default = 0) The linear size of an obstructing secondary mirror as a fraction of the full mirror size.
  • 'Kolmogorov' A Kolmogorov turbulent spectrum: T(k) ~ exp(-1/2 D(k)), where D(k) = 6.8839 (lambda/r0 k/2Pi)^(5/3).
    • lam_over_r0 = float_value (exactly one of lam_over_r0, fwhm or half_light_radius is required)
    • fwhm = float_value (exactly one of lam_over_r0, fwhm or half_light_radius is required)
    • half_light_radius = float_value (exactly one of lam_over_r0, fwhm or half_light_radius is required)
  • 'OpticalPSF' A PSF from aberrated telescope optics.
    • lam_over_diam = float_value (required)
    • defocus = float_value (default = 0) The defocus value, using the Noll convention for the normalization. (Noll index 4)
    • astig1 = float_value (default = 0) The astigmatism in the y direction, using the Noll convention for the normalization. (Noll index 5)
    • astig2 = float_value (default = 0) The astigmatism in the x direction, using the Noll convention for the normalization. (Noll index 6)
    • coma1 = float_value (default = 0)The defocus value, using the Noll convention for the normalization. (Noll index 7)
    • coma2 = float_value (default = 0)The defocus value, using the Noll convention for the normalization. (Noll index 8)
    • trefoil1 = float_value (default = 0)The defocus value, using the Noll convention for the normalization. (Noll index 9)
    • trefoil2 = float_value (default = 0) The defocus value, using the Noll convention for the normalization. (Noll index 10)
    • spher = float_value (default = 0)The defocus value, using the Noll convention for the normalization. (Noll index 11)
    • aberrations = list (optional) This is an alternative way to specify the above aberrations. You can just give them as a list of values using the Noll convention for the ordering, starting with defocus (Noll index 4). Eventually, this will be the way to specify aberrations past spherical (Noll index 11), but for now that is as high as you are allowed.
    • circular_pupil = bool_value (default = True) Whether the pupil should be circular (True, the default) or square (False).
    • obscuration = float_value (default = 0) The linear dimention of a central obscuration as a fraction of the pupil linear dimension.
    • nstruts = int_value (default = 0) How many support struts to include.
    • strut_thick = float_value (default = 0.05) How thick the struts should be as a fraction of the pupil diameter.
    • strut_angle = angle_value (default = 0 degrees) The counter-clockwise angle between the vertical and one of the struts. The rest will be spaced equally from there.
    • oversampling = float_value (default = 1.5) How much oversampling of the internal image is needed relative to the Nyquist scale of the corresponding Airy profile. The more aberrated the PSF, the higher this needs to be.
    • pad_factor = float_value (default = 1.5) How much padding to put around the edge of the internal image of the PSF.
    • max_size = float_value (optional) If the PSF will only be used to draw images of some size, you can set the OpticalPSF class to not build the internal image of the PSF (much) larger than that. This can help speed up calculations if GalSim natively decides to build a very large image of the PSF, when the wings never actually affect the final image.
  • 'Sum' or 'Add' Add several profiles together.
    • items = list (required) A list of profiles to be added.
  • 'Convolution' or 'Convolve' Convolve several profiles together.
    • items = list (required) A list of profiles to be convolved.
  • 'List' Select profile from a list.
    • items = list (required) A list of profiles.
    • index = int_value (default = 'Sequence' from 0 to len(items)-1) Which item in the list to select each time.
• flux = float_value (default = 1.0) Set the flux. This is usually not needed (or desired), since PSFs should always have unit flux. However, if you add two profiles together, you should either set flux=1.0 explicitly for the compound profile, or make sure the component profiles have (relative) fluxes set that sum to 1.0.
• dilate or dilation = float_value (optional) Dilate the profile by a given scale, preserving the flux.
• ellip = shear_value (optional) Shear the profile by a given shear to give the PSF some non-round shape.

Note: There are more ways to modify a profile than the two I listed above, dilate and ellip. Most of the other ways do not really apply to a PSF, but technically all the modifications described for gal below are also valid here.

gal

The gal field defines the profile of the galaxy. As described above for psf, any profile can be used for either psf or gal. Here we describe the types that are more likely to be used as a galaxy profile.

Valid gal fields are:

• type = str (required) Valid options are:
  • 'Gaussian' A circular Gaussian profile: I(r) ~ exp(-r^2 / (2 sigma^2)).
    • sigma = float_value (exactly one of sigma, fwhm or half_light_radius is required)
    • fwhm = float_value (exactly one of sigma, fwhm or half_light_radius is required)
    • half_light_radius = float_value (exactly one of sigma, fwhm or half_light_radius is required)
  • 'Exponential' A radial exponential profile: I(r) ~ exp(-r/scale_radius).
    • scale_radius = float_value (exactly one of scale_radius or half_light_radius is required)
    • half_light_radius = float_value (exactly one of scale_radius or half_light_radius is required)
  • 'Sersic' A Sersic profile: I(r) ~ exp(-(r/scale_radius)^(1/n)) = exp(-b (r/half_light_radius)^(1/n)).
    • n = float_value (required)
    • half_light_radius = float_value (exactly one of half_light_radius or scale_radius is required)
    • scale_radius = float_value (exactly one of half_light_radius or scale_radius is required)
    • trunc = float_value (optional) The profile can be truncated to 0 at some radius if desired. The default is no truncation.
    • flux_untruncated = bool_value (default = False) Set the profile such that the specified flux corresponds to that of the untruncated profile. Valid only when trunc > 0; ignored otherwise.
  • 'DeVaucouleurs' A DeVaucouleurs profile: I(r) ~ exp(-(r/scale_radius)^(1/4)) = exp(-b (r/half_light_radius)^(1/4)) (aka n=4 Sersic).
    • half_light_radius = float_value (exactly one of half_light_radius or scale_radius is required)
    • scale_radius = float_value (exactly one of half_light_radius or scale_radius is required)
    • trunc = float_value (optional) The profile can be truncated to 0 at some radius if desired. The default is no truncation.
    • flux_untruncated = bool_value (default = False) Set the profile such that the specified flux corresponds to that of the untruncated profile. Valid only when trunc > 0; ignored otherwise.
  • 'RealGalaxy' A real galaxy image, typically taken from a deep HST image, deconvolved by the original PSF. Note that the deconvolution implies that this cannot be draw with photon shooting (image.draw_method = 'phot'). This requires that input.real_catalog be specified and uses the following fields:
    • index = int_value (default = 'Sequence' from 0 to real_catalog.nobjects-1; only one of id or index may be specified) Which item in the catalog to use. Special: If index is either a 'Sequence' or 'Random' and last or max (respectively) is not specified, then it is automatically set to real_catalog.nobjects-1. (Even more special: If index is a 'Sequence' with step < 0 and first is not specified, then first is set to this and last is set to 0.)
    • id = str_value (only one of id or index may be specified) The ID in the catalog of the object to use.
    • x_interpolant = str_value (default = 'Quintic') 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.
    • k_interpolant = str_value (default = 'Quintic') What to use for interpolating between pixel centers in Fourier space, for convolution. 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. See docstring for this class for caveats about changing this parameter.
    • flux = float_value (default = catalog value) If set, this works as described below. However, RealGalaxy has a different default. If flux is omitted, the flux of the actual galaxy in the catalog is used.
    • pad_factor = float_value (default = 4) Amount of zero-padding to use around the image when creating the InterpolatedImage. See docstring for this class for caveats about changing this parameter.
    • whiten = bool_value (default = False) Whether or not a noise-whitening procedure should be done on the image after it is drawn to make the noise uncorrelated (white noise). Note: After the whitening process, there is white Gaussian noise in the image. We subtract this much noise from the variance of whatever is given in the image.noise field. However, unless this is type = Gaussian, the final noise field will not precisely match what you request. e.g. 'Poisson' noise would have a portion of the variance be Gaussian rather than Poisson. This probably does not matter in most cases, but if you are whitening, the most coherent noise profile is 'Gaussian', since that works seamlessly.
    • noise_pad_size = float (optional) If provided, then the original image is padded to a larger image of this size using the noise profile of the original image. This is important if you are using whiten=True. You want to make sure the image has the original noise all the way to the edge of the postage stamp. Otherwise, the edges will have the wrong noise profile.
    • num = int_value (default = 0) If input.real_catalog is a list, this indicates which number catalog to use.
  • 'RealGalaxyOriginal' This is the same as RealGalaxy except that the profile is not deconvolved by the original PSF. So this is the galaxy as observed in the original image. This requires that input.real_catalog be specified and uses the same fields as RealGalaxy. This may be more useful than the deconvolved version. For example, unlike RealGalaxy, it can be drawn with photon shooting (image.draw_method = 'phot').
  • 'InterpolatedImage' A profile described simply by a provided image (given in a fits file).
    • image = str_value (required) The file name from which to read the image.
    • x_interpolant = str_value (default = 'Quintic') 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.
    • k_interpolant = str_value (default = 'Quintic') What to use for interpolating between pixel centers in Fourier space, for convolution. 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. See docstring for this class for caveats about changing this parameter.
    • normalization = str_value (default = 'flux') What normalization to assume for the input image. Options are ('flux' or 'f') or ('surface brightness' or 'sb').
    • scale = float_value (default = 'GS_SCALE' entry from the fits header, or 1 if not present) What pixel scale to use for the image pixels.
    • pad_factor = float_value (default = 4) Amount of zero-padding to use around the image when creating the SBInterpolatedImage. See docstring for this class for caveats about changing this parameter.
    • noise_pad_size = float_value (optional; required if noise_pad is provided) If non-zero, then the original image is padded to a larger image of this size using the noise specified in noise_pad.
    • noise_pad = str_value (optional; required if noise_pad_size is provided) Either a filename to use for padding the image with noise according to a noise correlation function, or a variance value to pad with Gaussian noise.
    • pad_image = str_value (optional) The name of an image file to use for directly padding the image (deterministically) rather than padding with noise.
    • calculate_stepk = bool_value (default = True) Recalculate optimal Fourier space separation for convolutions? Can lead to significant optimization compared to default values.
    • calculate_maxk = bool_value (default = True) Recalculate optimal Fourier space total k range for convolutions? Can lead to significant optimization compared to default values.
  • 'Ring' Generate galaxies in a ring for a ring test. (Use num=2 to get pairs of 90 degree rotated galaxies.) The Ring type is only available for a top-level galaxy -- not for an element of a Sum, Convolution, List or Ring, and not for psf or pix.
    • first = dict (required) The profile to use for the first element in each ring.
    • num = int_value (required) How many objects to include in the ring.
    • full_rotation = angle_value (default = 180 degrees) What angle should be spanned by the full rotation? The default of 180 degrees is appropriate for the typical case of a rotationally symmetric galaxy (e.g. a sheared Exponential), but if the first profile does not have rotational symmetry, then you probably want to set this to 360 degrees.
    • index = int_value (default = 'Sequence' from 0 to num-1) Which item in the Ring is this.
  • 'Sum' or 'Add' Add several profiles together.
    • items = list (required) A list of profiles to be added.
  • 'Convolution' or 'Convolve' Convolve several profiles together.
    • items = list (required) A list of profiles to be convolved.
  • 'List' Select profile from a list.
    • items = list (required) A list of profiles.
    • index = int_value (default = 'Sequence' from 0 to len(items)-1) Which item in the list to select each time.
• flux = float_value (default = 1.0) Set the flux of the galaxy in ADU. Note that the component items in a Sum can also have fluxes specified, which can be used as fractional fluxes (e.g. 0.6 for the disk and 0.4 for the bulge). Then the outer level profile can set the real flux for the whole thing.
• dilate or dilation = float_value (optional) Dilate the profile by a given scale, preserving the flux.
• ellip = shear_value (optional) Shear the profile by a given shear to give the galaxy some non-round intrinsic shape.
• rotate or rotation = angle_value (optional) Rotate the profile by a given angle.
• magnify or magnification = float_value (optional) Magnify the profile by a given scale, preserving the surface brightness.
• shear = shear_value (optional) Shear the profile by a given shear.
• shift = pos_value (optional) Shift the centroid of the profile by a given amount relative to the center of the image on which it will be drawn.
• resolution = float_value (optinal) Special: if the base profile allows a half_light_radius parameter, and the psf is able to calculate a half_light_radius, then it is permissible to specify a resolution: resolution = r_gal / r_psf (where r_gal and r_psf are the half-light radii) in lieu of specifying the half_light_radius of the galaxy explicitly. This is especially useful if the PSF size is generated randomly.
• signal_to_noise = float_value (optional) You may specify a signal-to-noise value rather than a flux. Our definition of the S/N derives from a weighted integral of the flux in the drawn image: S = sum W(x,y) I(x,y) / sum W(x,y) where W(x,y) is taken to be a matched filter, so W(x,y) = I(x,y). (Note: This currently requires draw_method = 'fft'. It is a bit trickier to do this for photon shooting, and we have not enabled that yet.)
• redshift = float_value (optional) The redshift of the galaxy. This is required when using NFWHaloShear or NFWHaloMagnification.

Note: The modification items, flux through shift, are done in the above order. Some of these operations do not commute with each other, so the order is important. The first few, flux, dilate, ellip, and rotate, are typically used to define the intrinsic profile of the galaxy. The next two, magnify and shear, are typically used to define how the profile is modified by lensing. The last one, shift, is used to provide variations in the sub-pixel position of the galaxy on the image.

Also, resolution and signal_to_noise are only valid for the top level gal -- not for objects that are part of a 'Sum', 'Convolution', 'List' or 'Ring' and not for psf or pix.

image

The image field defines some extra information about how to draw the images.

Valid image fields are:

• type = str (default = 'Single') Valid options are:
  • 'Single' The image contains a single object at the center (unless it has been shifted of course -- see shift attribute above).
    • size = int_value (optional) If you want square images for each object (common), you just need to set this one value and the images will be size x size. The default is for GalSim to automatically determine a good size for the image that will encompass most of the flux of the object.
    • xsize = int_value (default = size) If you want non-square images, you can specify xsize and ysize separately instead. It is an error for only one of them to be non-zero.
    • ysize = int_value (default = size)
  • 'Tiled' The image consists of a tiled array of postage stamps.
    • nx_tiles = int_value (required)
    • ny_tiles = int_value (required)
    • stamp_size = int_value (either stamp_size or both stamp_xsize and stamp_ysize are required) The size of square stamps on which to draw the objects.
    • stamp_xsize = int_value (either stamp_size or both stamp_xsize and stamp_ysize are required) The xsize of the stamps on which to draw the objects.
    • stamp_ysize = int_value (either stamp_size or both stamp_xsize and stamp_ysize are required) The ysize of the stamps on which to draw the objects.
    • border = int_value (default = 0) number of pixels between tiles. Note: the border value may be negative, in which case the tiles will overlap each other.
    • xborder = int_value (default = border) number of pixels between tiles in the x direction
    • yborder = int_value (default = border) number of pixels between tiles in the y direction
    • order = str_value (default = 'row') Which order to fill the stamps. 'row' means to proceed row by row starting at the bottom row (each row is filled from left to right). 'column' means to fill the columns from left to right (each column is filled from bottom to top). 'random' means to place the tiles in a random order.
  • 'Scattered' The image consists of a large contiguous area on which postage stamps of each object are placed at arbitrary positions, possibly overlapping each other (in which case the fluxes are added together for the final pixel value).
    • size = int_value (either size or both xsize and ysize are required)
    • xsize = int_value (either size or both xsize and ysize are required)
    • ysize = int_value (either size or both xsize and ysize are required)
    • nobjects = int_value (default if using an input catalog and the output type is 'Fits' is the number of entries in the input catalog; otherwise required)
    • stamp_size = int_value (optional) The stamp_size attribute works like the size attribute for 'Single'.
    • stamp_xsize = int_value (default = stamp_size)
    • stamp_ysize = int_value (default = stamp_size)
    • world_pos = pos_value (only one of world_pos and image_pos is allowed) The position in world coordinates relative to the center of the image at which to place the center of the postage stamp for each object.
    • image_pos = pos_value (only one of world_pos and image_pos is allowed; default if neither is given = XY with x = 'Random' from 1..xsize, y = 'Random' from 1..ysize) The position on the image at which to place the center of the postage stamp for each object.
• pixel_scale = float_value (default = 1.0) The pixel scale, typically taken to be arcsec/pixel. Most size parameters for the profiles are taken to be specified in arcsec. If you would rather specify everything in pixels, just leave off the pixel_scale (or set it to 1.0) and then 1 pixel = 1 arcsec, so everything should work the way you expect. Or if you want all your units to be degrees or radians or something else, then just set this pixel scale in the same units.
• sky_level = float_value (default = 0.0; only one of sky_level and sky_level_pixel is allowed) The background level of the image in ADU/arcsec^2
• sky_level_pixel = float_value (default = 0.0; only one of sky_level and sky_level_pixel is allowed) The background level of the image in ADU/pixel
• index_convention = str_value (default = 'FITS') The convention for what to call the lower left pixel of the image. The standard FITS convention is to call this pixel (1,1). However, this can be counter-intuitive to people used to C or python indexing. So if index_convention is 'C' or 'python' or '0', then the image origin will be considered (0,0) instead. (While unnecessary to specify explicitly since it is the default, the (1,1) convention may be called 'FITS', 'Fortran' or '1'.)
• random_seed = int_value (optiona) The initial random seed value to use for the first object. Each successive object gets the next integer value in sequence. We do it this way rather than just continue the random numbers from the random number generator so that the output is deterministic even when using multiple processes to build each image. The default is to pick a seed based on the system time.
• draw_method = str_value (default = 'fft') Valid options are:
  • 'fft' Use fast fourier transforms to calculate the convolution of the psf, the pixel and the galaxy to draw on the image. (Technically, for some profiles, GalSim will choose to use real_space convolutions when that is expected to be faster and/or more accurate.)
  • 'phot' Use photon shooting instead, which may be faster for low S/N objects.
    • max_extra_noise = float_value (default = 0.01) If the image is sky noise dominated, then it is efficient to stop shooting photons when the photon noise of the galaxy is much less than the sky noise. This parameter specifies how much extra noise, as a fraction of the sky noise, is permissible.
    • n_photons = int_value Specifies the total number of photons to shoot as a hard, fixed number. If both n_photons and max_extra_noise are specified in the options, max_extra_noise is ignored and a warning is generated.
  • 'real_space' Try to use real-space convolution using Gauss-Kronrod-Patterson integration. This is only possible if there is only a single, relatively simple profile being convolved with the pixel response. If GalSim is unable to do the real-space convolution, this default to 'fft'.
  • 'no_pixel' Do not convolve the object by a pixel response (how GalSim implements integrating over the size of the pixel). This can be useful if you just want sampled values of the surface brightness profile, rather than how the object would look on a real image (where the light is of course integrated over the pixels). Also, if the PSF already has the pixel response included (e.g. from an observed image of a PSF), then this would keep GalSim from applying an additional pixel convolution.
• noise = dict (optional) Specify the kind of noise you want added to the image.
  • type = str (default = 'CCDNoise') Valid options are:
    • 'Gaussian' is the simplest kind of noise. Just Gaussian noise across the whole image with a given sigma (or variance).
      • sigma = float_value (either sigma or variance is required) The rms of the noise in ADU.
      • variance = float_value (either sigma or variance is required) The variance of the noise in ADU^2.
    • 'Poisson' adds Poisson noise for the flux value in each pixel, with an optional sky background level and an optional readout gain.
      • sky_level = float_value (default = image.sky_level if provided, otherwise either sky_level or sky_level_pixel is required) The sky level in ADU/arcsec^2 to use for the noise. If both this and image.sky_level are provided, then they will be added together for the purpose of the noise, but the background level in the final image will just be image.sky_level.
      • sky_level_pixel = float_value (default = image.sky_level_pixel if provided, otherwise either sky_level or sky_level_pixel is required) The sky level in ADU/pixel to use for the noise.
      • gain = float_value (default = 1.0) The CCD gain in e-/ADU.
    • 'CCDNoise' is usually what you want, so it is the default. It includes both Poisson noise for the flux value in each pixel (with an optional gain) and an optional Gaussian read noise.
      • sky_level = float_value (default = image.sky_level if provided, otherwise either sky_level or sky_level_pixel is required) The sky level in ADU/arcsec^2 to use for the noise. If both this and image.sky_level are provided, then they will be added together for the purpose of the noise, but the background level in the final image will just be image.sky_level.
      • sky_level_pixel = float_value (default = image.sky_level_pixel if provided, otherwise either sky_level or sky_level_pixel is required) The sky level in ADU/pixel to use for the noise.
      • gain = float_value (default = 1.0) The CCD gain in e-/ADU.
      • read_noise = float_value (default = 0.0) The CCD read noise in ADU.
    • 'COSMOS' provides spatially correlated noise of the sort found in the F814W HST COSMOS science images described by Leauthaud et al (2007). The point variance (given by the zero distance correlation function value) may be normalized by the user as required, as well as the dimensions of the correlation function.
      • file_name = str_value (required) The path and filename of the FITS file containing the correlation function data used to generate the COSMOS noise field. The relevant file 'acs_I_unrot_sci_20_cf.fits' is included in the GalSim repository in the examples/data/ directory, so file_name will very commonly simply need to be '/YOUR/REPO/PATH/GalSim/examples/data/acs_I_unrot_sci_20_cf.fits'.
      • dx_cosmos = float_value (default=0.03) The ACS coadd images in COSMOS have a pixel scale of 0.03 arcsec, and so the pixel scale dx_cosmos adopted in the representation of of the correlation function takes a default value of 0.03. If you wish to use other units ensure that dx_cosmos takes the value corresponding to 0.03 arcsec in your chosen system.
      • variance = float_value (default=0.) Scale the point variance of the noise field to the desired value, equivalent to scaling the correlation function to have this value at zero separation distance. Choosing the default scaling of 0. uses the variance in the original COSMOS noise fields.
• wcs = dict (optional) Specify a WCS shear to apply to the image.
  • type = str (default = PixelScale)
    • 'PixelScale' implements a regular square pixel grid. If you do not specify any wcs item, this is what will be used, and the scale will be the image.pixel_scale value.
      • scale = fload_vale (default = image.pixel_scale) The scale size of the pixels. The area is scale * scale.
    • 'Shear' implements a uniform shear of a regular square pixel grid. After the shear, the pixel area will still be scale * scale, but they will be parallelograms (rhombi actually) rather than squares.
      • scale = float_value (required) The pixel scale of the grid before being sheared.
      • shear = shear_value (required) The shear to apply.
    • 'Jacobian' or 'Affine' implements an arbitrary affine transform. This is the most general WCS that has a uniform pixel shape. The world (u,v) coordinates are linearly related to the image (i.e. pixel) (x,y) coordinates.
      • dudx = float_value (required) du/dx
      • dudy = float_value (required) du/dy
      • dvdx = float_value (required) dv/dx
      • dvdy = float_value (required) dv/dy
    • 'UVFunction' implements an arbitrary transformation from image coordinates (x,y) to world coordinates (u,v) via two functions u(x,y) and v(x,y). You can also provide the inverse functions x(u,v) and y(u,v). They are not required, but if they are not given, then positions of objects cannot be given in world coordinates via image.world_pos for the 'Scattered' image type.
      • ufunc = str_value (required) A string that can be turned into the function u(x,y) via the python command eval('lambda x,y : ' + ufunc).
      • vfunc = str_value (required) A string that can be turned into the function v(x,y) via the python command eval('lambda x,y : ' + vfunc).
      • xfunc = str_value (optional) A string that can be turned into the function x(u,v) of the inverse transformation via the python command eval('lambda u,v : ' + xfunc).
      • yfunc = str_value (optional) A string that can be turned into the function y(u,v) of the inverse transformation via the python command eval('lambda u,v : ' + yfunc).
    • 'RaDecFunction' implements an arbitrary tranformation from image coordinates (x,y) to celestial coordinates (ra,dec) via two functions ra(x,y) and dec(x,y).
      • ra_func = str_value (required) A string that can be turned into the function ra(x,y) via the python command eval('lambda x,y : ' + rafunc).
      • dec_func = str_value (required) A string that can be turned into the function dec(x,y) via the python command eval('lambda x,y : ' + decfunc).
    • 'Fits' reads a WCS from a FITS file. Most common WCS types are implemented, but if the file uses something a bit unusual, the success of the read may depend on what other python packages you have installed. See the documentation of FitsWCS for more details.
      • file_name = str_value (required) The name of the FITS file.
      • dir = str_value (default='.')
  • origin = pos_value (default = (0,0)) Optionally set the image coordinates to use as the origin position, if not (x,y) = (0,0). Special: You can also specify origin to be 'center', in which case the origin is taken to be the center of the image rather than the corner.
  • world_origin = pos_value (default = (0,0)) Optionally set the world coordinates to use as the origin position, if not (u,v) = (0,0). (Not available for the celestial WCS types, 'RaDecFunction', 'Fits', and 'Tan'.)
• retry_failures = int_value (default = 0) How many times to retry the construction of a GSObject if there is any kind of failure. For example, you might have a random shear value that technically may come back with |g| > 1, but it should be very rare. So you might set it to retry once or twice in that case. If this is > 0, then after a failure, the code will wait 1 second (in case the failure was related to memory usage on the machine), and then try again up to this many times.
• wmult = float_value (default = 1.0) A multiplicative factor by which to enlarge (in each direction) the default automatically calculated FFT grid size used for any intermediate calculations in Fourier space. The size of the intermediate images is normally automatically chosen to reach some preset accuracy targets [see help(galsim.GSParams())]; however, if you see strange artifacts in the image, you might try using wmult > 1.
• nproc = int_value (default = 1) Specify the number of processors to use when drawing images. If nproc <= 0, then this means to try to automatically figure out the number of cpus and use that.

input

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.

Valid input fields are:

• catalog defines an input catalog that has values for each object. Connected with Catalog value type described below.
  • 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 below.
  • 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 below.
  • file_name = str_value (required) The name of the FITS file.
  • dir = str_value (default = '.') The directory the file is in.
  • 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 above.
  • file_name = str_value (required) The name of the file with the input catalog.
  • dir = str_value (default = .) The directory the file is in.
  • image_dir = str_value (default = dir) The directory containing the real galaxy images.
  • noise_dir = str_value (default = dir) The directory containing the 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.
• nfw_halo defines an NFW halo. Connected with NFWHaloShear and NFWHaloMagnification value types described below.
  • 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 below.
  • 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 specrum 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 specrum 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.

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.

output

The output field indicates where to write the output files and what kind of output format they should be.

Valid output fields are:

• type = str (default = 'Fits') Valid options are:
  • 'Fits' A simple fits file.
  • 'MultiFits' A multi-extension fits file.
    • nimages = int_value (default if using an input catalog and the image type is 'Single' is the number of entries in the input catalog; otherwise required) The number of hdu extensions on which to draw an image.
  • 'DataCube' A fits data cube.
    • nimages = int_value (default if using an input catalog and the image type is 'Single' is the number of entries in the input catalog; otherwise required) The number of images in the data cube (i.e. the third dimension of the cube).
• file_name = str_value (default = '<config file root name>.fits') You would typically want to specify this explicitly, but if you do not, then if the configuration file is called my_test.yaml, the output file would be my_test.fits.
• dir = str_value (default = '.') In which directory should the output file be put.
• nfiles = int_value (default = 1) How many files to build. Note: if nfiles > 1, then file_name and/or dir should not be a simple string. Rather it should be some generated string that provides a different save location for each file. See the section below on setting str_value.
• psf = dict (optional) You can optionally output noiseless images of the PSF used for each galaxy.
  • file_name = str_value (either file_name or hdu is required) Write the psf image to a different file (in the same directory as the main image).
  • hdu = int_value (either file_name or hdu is required) Write the psf image to another hdu in the main file. (This option is only possible if type == 'Fits') Note: 0 means the primary HDU, the first extension is 1. The main image is always written in hdu 0.
  • dir = str_value (default = output.dir if that is provided, else '.') (Only relevant if file_name is provided.)
• weight = dict (optional) You can optionally output the weight image (an inverse variance map of the noise properties).
  • file_name = str_value (either file_name or hdu is required) Write the weight image to a different file (in the same directory as the main image).
  • hdu = int_value (either file_name or hdu is required) Write the weight image to another hdu in the main file. (This option is only possible if type == 'Fits') Note: 0 means the primary HDU, the first extension is 1. The main image is always written in hdu 0.
  • dir = str_value (default = output.dir if that is provided, else '.') (Only relevant if file_name is provided.)
  • include_obj_var = bool_value (default = False) Normally, the object variance is not included as a component for the inverse variance map. If you would rather include it, set this to True.
• badpix = dict (optional) You can optionally output the bad-pixel mask image. This will be relevant when we eventually add the ability to add defects to the images. For now the bad-pixel mask will be all 0s.
  • file_name = str_value (either file_name or hdu is required) Write the bad pixel mask image to a different file (in the same directory as the main image).
  • hdu = int_value (either file_name or hdu is required) Write the bad pixel mask image to another hdu in the main file. (This option is only possible if type == 'Fits') Note: 0 means the primary HDU, the first extension is 1. The main image is always written in hdu 0.
  • dir = str_value (default = output.dir if that is provided, else '.') (Only relevant if file_name is provided.)
• nproc = int_value (default = 1) Specify the number of processors to use when building files. If nproc <= 0, then this means to try to automatically figure out the number of cpus and use that. If you are doing many files, it is more efficient to split up the processes at this level rather than when drawing the postage stamps (which is what image.nproc means).
• skip = bool_value (default = False) Specify files to skip. This would normally be an evaluated boolean rather than either True or False of course. e.g. To only do the first file, you could use skip : { type : Eval, str : f 'file_num > 0' }. This may be easier to add during debugging than to change other parts of the config file.
• noclobber = bool_value (default = False) Specify whether to skip building files that already exist. This may be useful if you are running close to the memory limit on your machine with multiprocessing. e.g. You could use nproc > 1 for a first run using multiprocessing, and then run again with nproc = 1 and noclobber = True to clean up any files that failed from insufficient memory during the multiprocessing run.
• retry_io = int_value (default = 0) How many times to retry the write command if there is any kind of failure. Some systems have trouble with multiple concurrent writes to disk, so if you are doing a big parallel job, this can be helpful. If this is > 0, then after an IOError exception on the write command, the code will wait an increasing number of seconds (starting with 1 for the first failure), and then try again up to this many times.

Setting values

float_value

Options are:

• A normal float value (e.g. 1.8)
• Anything that python can convert into a float (e.g. '1.8')
• A dict with:
  • type = str (required) Valid options are:
    • 'Catalog' Read the value from an input catalog. This requires that input.catalog be specified and uses the following fields:
      • col = int_value for ASCII catalog or str_value for FITS catalog (required)
      • index = int_value (default = 'Sequence' from 0 to input_cat.nobjects-1)
      • num = int_value (default = 0) If input.catalog is a list, this indicates which number catalog to use.
    • 'Dict' Read the value from an input dictionary. This requires that input.dict be specified and uses the following fields:
      • key = str_value (required) For specifying keys below the first level of the dictionary, the key string is split using the input.dict.key_split value (default = '.') into multiple keys. e.g. if key = galaxy_constants.redshift, this would be parsed as dict['galaxy_constants']['redshift'].
      • num = int_value (default = 0) If input.dict is a list, this indicates which number dictionary to use.
    • 'FitsHeader' Read the value from an input FITS header. This requires that input.fits_header be specified and uses the following fields:
      • key = str_value (required)
      • num = int_value (default = 0) If input.fits_header is a list, this indicates which number file to use.
    • 'Random' Generate random values uniformly distributed within a range.
      • min = float_value (required)
      • max = float_value (required)
    • 'RandomGaussian' Generate random values from a Gaussian deviate.
      • sigma = float_value (required)
      • mean = float_value(default = 0)
      • min = float_value (optional) Clip the distribution at some minimum.
      • max = float_value (optional) Clip the distribution at some maximum.
    • 'RandomDistribution' Generate random values from a given probability distribution.
      • function = str_value (required) A string describing the function of x to use for the probability distribution. e.g. 'x**2.3'. Alternatively, it may be a file name from which a tabulated function (with columns of x, p(x)) is read in.
      • x_min = float_value (required unless function is a file name) The minimum value of x to use for the distribution. (If function is a file name, the minimum value read in is taken as x_min.)
      • x_max = float_value (required unless function is a file name) The maximum value of x to use for the distribution. (If function is a file name, the maximum value read in is taken as x_max.)
      • npoints = int_value (default = 256) How many points to use for the cumulative probability distribution (CDF), which is used to map from a uniform deviate to the given distribution. More points will be more accurate, but slower.
      • interpolant = str_value (default = 'Linear') What to use for interpolating between tabulated points in the CDF. Options are 'Nearest', 'Linear', 'Cubic' or 'Quintic'. (Technically, 'Sinc' and 'LanczosN' are also possible, but they do not make sense here.)
    • 'PowerSpectrumMagnification' Calculate a magnification from a given power spectrum. This requires that input.power_spectrum be specified and uses the following fields:
      • max_mu = float_value (default = 5) The maximum magnification to allow. If the power spectrum returns a mu value greater than this or less than 0, then use max_mu instead. This is a sign of strong lensing, and other approximations are probably breaking down at this point anyway, so this keeps the object profile from going crazy.
      • num = int_value (default = 0) If input.power_spectrum is a list, this indicates which number power spectrum to use.
    • 'NFWHaloMagnification' Calculate a magnification from an NFW Halo mass. This requires that input.nfw_halo be specified and uses the following fields:
      • gal.redshift = float_value (required) Special: The redshift item must be in the gal field, not magnification.
      • max_mu = float_value (default = 5) The maximum magnification to allow. If NFWHalo returns a mu value greater than this or less than 0, then use max_mu instead. This is a sign of strong lensing, and other approximations are probably breaking down at this point anyway, so this keeps the object profile from going crazy.
      • num = int_value (default = 0) If input.nfw_halo is a list, this indicates which number halo to use.
    • 'Sequence' Generate a sequence of values.
      • first = float_value (default = 0)
      • step = float_value (default = 1) The step size between items.
      • repeat = int_value (default = 1) How many times to repeat the same value before moving on.
      • last = float_value (optional; at most one of last and nitems is allowed) Note: if last is provided, once a value passes last, the sequence will repeat starting with first again.
      • nitems = int_value (optional; at most one of last and nitems is allowed) The number of items in the sequence before starting over again at first. The default is to just keep incrementing forever.
      • index_key = str_value (default: special; see the option descriptions below) Which number to use for indexing in the sequence. Valid options are:
        • 'file_num' Index according to the running file number being worked on. This is the default for items in the input and output fields.
        • 'image_num' Index according to the running image number. This index number does not start back at 0 with each file, but rather keeps incrementing. This is the default for items in the image field that apply to the full image (i.e. not including random_seed, image_pos, world_pos, etc.).
        • 'obj_num' Index according to the running object number. This index number does not start back at 0 with each file or image, but rather keeps incrementing. This is the default for image.random_seed.
        • 'obj_num_in_file' Index according to the object number within the current file (i.e. start back at 0 again for each new file). This is the default for items in image that apply to the object (image_pos, world_pos, offset, stamp_size and related, or border and related) and also to items in psf or gal. Resetting the count back to zero at the start of each file is generally what you want when the files have different numbers of objects. E.g., when you are reading from input catalogs that contain different numbers of objects, you normally want to start back at 0 for each new catalog.
    • 'List' Select items from a list.
      • items = list (required) A list of float_value items.
      • index = int_value (default = 'Sequence' from 0 to len(items)-1)
    • 'Current' Use the current value of some other item in the config file. This is especially useful if you need to use a value from some other calculation, but the value is a random variate, so you cannot just reproduce it. You need the actual value returned by the random number generator.
      • key = str_value (required) The key name of the item to use. The nested layers in the dictionary should be separated by '.' characters. e.g. To access the current half-light radius of the galaxy, use 'gal.half_light_radius'. For list items, use the number in the list as a key (using the normal python 0-based counting convention). e.g. for the half-light radius of the third item in a galaxy List type, use 'gal.items.2.half_light_radius'.
    • 'Sum' The sum of two other float_value items.
      • items = list (required) A list of float_value items to be added together.
    • 'Eval' Evaluate a string. See the section on Eval below.

int_value

Options are:

• A normal int value (e.g. 8)
• Anything that python can convert into an int (e.g. 8.0, '8') Note: float values will silently drop any fractional part, so 8.7 will become 8.
• A dict with:
  • type = str (required) Valid options are:
    • 'Catalog' Read the value from an input catalog. This requires that input.catalog be specified and uses the following fields:
      • col = int_value for ASCII catalog or str_value for FITS catalog (required)
      • index = int_value (default = 'Sequence' from 0 to input_cat.nobjects-1)
      • num = int_value (default = 0) If input.catalog is a list, this indicates which number catalog to use.
    • 'Dict' Read the value from an input dictionary. This requires that input.dict be specified and uses the following fields:
      • key = str_value (required) For specifying keys below the first level of the dictionary, the key string is split using the input.dict.key_split value (default = '.') into multiple keys. e.g. if key = galaxy_constants.redshift, this would be parsed as dict['galaxy_constants']['redshift'].
      • num = int_value (default = 0) If input.dict is a list, this indicates which number dictionary to use.
    • 'FitsHeader' Read the value from an input FITS header. This requires that input.fits_header be specified and uses the following fields:
      • key = str_value (required)
      • num = int_value (default = 0) If input.fits_header is a list, this indicates which number file to use.
    • 'Random' Generate a random value uniformly distributed within a range.
      • min = int_value (required)
      • max = int_value (required) Note: the range includes both min and max.
    • 'Sequence' Generate a sequence of values.
      • first = int_value (default = 0)
      • step = int_value (default = 1) The step size between items.
      • repeat = int_value (default = 1) How many times to repeat the same value before moving on.
      • last = float_value (optional; at most one of last and nitems is allowed) Note: if last is provided, once a value passes last, the sequence will repeat starting with first again.
      • nitems = int_value (optional; at most one of last and nitems is allowed) The number of items in the sequence before starting over again at first. The default is to just keep incrementing forever.
      • index_key = str_value Which number to use for indexing in the sequence. (See the description of this for float_value for more details.)
    • 'List' Select items from a list.
      • items = list (required) A list of int_value items.
      • index_key = str_value Which number to use for indexing in the sequence. (See the description of this for float_value for more details.)
      • index = int_value (default = 'Sequence' from 0 to len(items)-1)
    • 'Current' Use the current value of some other item in the config file. (See the description of this for float_value for more details.)
      • key = str_value (required) The key name of the item to use.
    • 'Sum' The sum of two other int_value items.
      • items = list (required) A list of int_value items to be added together.
    • 'Eval' Evaluate a string. See the section on Eval below.

bool_value

Options are:

• A normal bool value (i.e. True or False)
• Anything that python can convert into a bool (e.g. 1, 0.0)
• Some reasonable (case-insensitive) strings: 'true'/'false', 'yes'/'no', '1'/'0'
• A dict with:
  • type = str (required) Valid options are:
    • 'Catalog' Read the value from an input catalog. This requires that input.catalog be specified and uses the following fields:
      • col = int_value for ASCII catalog or str_value for FITS catalog (required)
      • index = int_value (default = 'Sequence' from 0 to input_cat.nobjects-1)
      • num = int_value (default = 0) If input.catalog is a list, this indicates which number catalog to use.
    • 'Dict' Read the value from an input dictionary. This requires that input.dict be specified and uses the following fields:
      • key = str_value (required) For specifying keys below the first level of the dictionary, the key string is split using the input.dict.key_split value (default = '.') into multiple keys. e.g. if key = galaxy_constants.redshift, this would be parsed as dict['galaxy_constants']['redshift'].
      • num = int_value (default = 0) If input.dict is a list, this indicates which number dictionary to use.
    • 'FitsHeader' Read the value from an input FITS header. This requires that input.fits_header be specified and uses the following fields:
      • key = str_value (required)
      • num = int_value (default = 0) If input.fits_header is a list, this indicates which number file to use.
    • 'Random' Generate a random bool value.
    • 'Sequence' Generate a sequence of values.
      • first = bool_value (default = False) For bool, the only two values in the sequence are False and True, so step and last are not needed.
      • repeat = int_value (default = 1) How many times to repeat the same value before moving on.
      • index_key = str_value Which number to use for indexing in the sequence. (See the description of this for float_value for more details.)
    • 'List' Select items from a list.
      • items = list (required) A list of bool_value items.
      • index = int_value (default = 'Sequence' from 0 to len(items)-1)
    • 'Current' Use the current value of some other item in the config file. (See the description of this for float_value for more details.)
      • key = str_value (required) The key name of the item to use.
    • 'Eval' Evaluate a string. See the section on Eval below.

str_value

Options are:

• A normal str value (e.g. 'out.fits')
• A dict with:
  • type = str (required) Valid options are:
    • 'Catalog' Read the value from an input catalog. This requires that input.catalog be specified and uses the following fields:
      • col = int_value for ASCII catalog or str_value for FITS catalog (required)
      • index = int_value (default = 'Sequence' from 0 to input_cat.nobjects-1)
      • num = int_value (default = 0) If input.catalog is a list, this indicates which number catalog to use.
    • 'Dict' Read the value from an input dictionary. This requires that input.dict be specified and uses the following fields:
      • key = str_value (required) For specifying keys below the first level of the dictionary, the key string is split using the input.dict.key_split value (default = '.') into multiple keys. e.g. if key = galaxy_constants.redshift, this would be parsed as dict['galaxy_constants']['redshift'].
      • num = int_value (default = 0) If input.dict is a list, this indicates which number dictionary to use.
    • 'FitsHeader' Read the value from an input FITS header. This requires that input.fits_header be specified and uses the following fields:
      • key = str_value (required)
      • num = int_value (default = 0) If input.fits_header is a list, this indicates which number file to use.
    • 'NumberedFile' Build a string that includes a number portion: rootNNNNext. e.g. file0001.fits, file0002.fits, etc.
      • root = str_value (required) The part of the string that comes before the number.
      • num = int_value (default = 'Sequence' starting with 0) The number to use in the string.
      • digits = int_value (default = 0) How many digits to use (minimum) to write the number. The number will be left-padded with 0s as needed.
      • ext = str_value (default = '.fits' for output.file_name and the file_name entries for sub-items within output (psf, weight, badpix), and '' for all other uses) An extension to place after the number.
    • 'FormattedStr' Build a string using a format akin to the normal python %-style formatting or C/C++ printf-style formatting.
      • format = str_value (required) The formatting string to use. (e.g. 'image_%f_%d.fits')
      • items = list (required) A list of items to insert into the corresponding % items in the format string. The letter after the % indicates what kind of value each item is. So for the above example, the first item in the string should be a float_value to put into the %f spot. The second should be an int_value to put into the %d spot.
    • 'List' Select items from a list.
      • items = list (required) A list of str_value items.
      • index = int_value (default = 'Sequence' from 0 to len(items)-1)
    • 'Current' Use the current value of some other item in the config file. (See the description of this for float_value for more details.)
      • key = str_value (required) The key name of the item to use.
    • 'Eval' Evaluate a string. See the section on Eval below.

angle_value

Options are:

• A string consisting of a float followed by one of the following angle units: radians, degrees, hours, arcminutes, arcseconds. These may be abbreviated as rad, deg, hr, arcmin, arcsec. (e.g. '45 deg')
• A dict with:
  • type = str (required) Valid options are:
    • 'Radians' or 'Rad' Use a float_value as an angle in radians.
      • theta = float_value (required)
    • 'Degrees' or 'Deg' Use a float_value as an angle in degrees.
      • theta = float_value (required)
    • 'Random' Generate a random angle uniformly distributed from 0 to 2pi radians.
    • 'List' Select items from a list.
      • items = list (required) A list of angle_value items.
      • index = int_value (default = 'Sequence' from 0 to len(items)-1)
    • 'Current' Use the current value of some other item in the config file. (See the description of this for float_value for more details.)
      • key = str_value (required) The key name of the item to use.
    • 'Sum' The sum of two other angle_value items.
      • items = list (required) A list of angle_value items to be added together.
    • 'Eval' Evaluate a string. See the section on Eval below.

shear_value

Options are:

• A dict with:
  • type = str (required) Valid options are:
    • 'E1E2' Specify as a distortion in cartesian coordinates.
      • e1 = float_value (required)
      • e2 = float_value (required)
    • 'EBeta' Specify as a distortion in polar coordinates.
      • e = float_value (required)
      • beta = angle_value (required)
    • 'G1G2' Specify as a reduced shear in cartesian coordinates.
      • g1 = float_value (required)
      • g2 = float_value (required)
    • 'GBeta' Specify as a reduced shear in polar coordinates.
      • g = float_value (required)
      • beta = angle_value (required)
    • 'Eta1Eta2' Specify as a conformal shear in cartesian coordinates.
      • eta1 = float_value (required)
      • eta2 = float_value (required)
    • 'EtaBeta' Specify as a conformal shear in polar coordinates.
      • eta = float_value (required)
      • beta = angle_value (required)
    • 'QBeta' Specify as an axis ratio and position angle.
      • q = float_value (required)
      • beta = angle_value (required)
    • 'PowerSpectrumShear' Calculate a shear from a given power spectrum. This requires that input.power_spectrum be specified and uses the following field:
      • num = int_value (default = 0) If input.power_spectrum is a list, this indicates which number power spectrum to use.
    • 'NFWHaloShear' Calculate a shear from an NFW Halo mass. This requires that input.nfw_halo be specified and uses the following fields:
      • gal.redshift = float_value (required) Special: The redshift item must be in the gal field, not shear.
      • num = int_value (default = 0) If input.nfw_halo is a list, this indicates which number halo to use.
    • 'List' Select items from a list.
      • items = list (required) A list of shear_value items.
      • index = int_value (default = 'Sequence' from 0 to len(items)-1)
    • 'Current' Use the current value of some other item in the config file. (See the description of this for float_value for more details.)
      • key = str_value (required) The key name of the item to use.
    • 'Sum' The sum of two other shear_value items. Note: Unlike the other kinds of values, shears addition is not commutative. g_a + g_b is not the same as g_b + g_a. Thus, the order of the elements in the items list matters. The shear effects are applied from last to first, so the effects should be listed in order from closest to the observer to farthest along the light path. This is a somewhat standard convention for what g_a + g_b means when applied to a galaxy. g_b would be a shear that is close to the galaxy, and then g_a would be another shear closer to the observer (perhaps within the telescope).
      • items = list (required) A list of shear_value items to be added together.
    • 'Eval' Evaluate a string. See the section on Eval below.

pos_value

Options are:

• A string consisting of two floats separated by a comma and possibly white space. (e.g. '1.7, 3.0')
• A dict with:
  • type = str (required) Valid options are:
    • 'XY' Specify x and y separately.
      • x = float_value (required)
      • y = float_value (required)
    • 'RTheta' Specify using polar coordinate.
      • r = float_value (required)
      • theta = angle_value (required)
    • 'RandomCircle' Generate a random value uniformly distributed within a circle of a given radius. (Note: this is different from 'RTheta' with each one random, since that would preferentially pick locations near the center of the circle.)
      • radius = float_value (required) The size of the circle within which to draw a random value.
      • inner_radius = float_value (default = 0) If desired, an inner circle may be excluded, making this an annulus rather than a full circle.
      • center = pos_value (default = 0,0) The center of the circle.
    • 'List' Select items from a list.
      • items = list (required) A list of pos_value items.
      • index = int_value (default = 'Sequence' from 0 to len(items)-1)
    • 'Current' Use the current value of some other item in the config file. (See the description of this for float_value for more details.)
      • key = str_value (required) The key name of the item to use.
    • 'Sum' The sum of two other pos_value items.
      • items = list (required) A list of pos_value items to be added together.
    • 'Eval' Evaluate a string. See the section on Eval below.

The 'Eval' type

Every kind of value has 'Eval' as one of its allowed types. This works a little bit differently than the other types, so we describe it here in its own section.

The only required attribute to go along with an 'Eval' is str, which is the string to be evaluated using the python eval function.

For example str = '800 * 1.e-9 / 4 * 206265' will evaluate to 0.041253. (This example is taken from demo3.yaml.) This might either be easier than doing a calculation yourself or perhaps be clearer as to how the number was formed. For example, this example calculates lam_over_diam using lambda = 800 nm, D = 4 m, converting the result into arcsec. If you later wanted to change to a 6.5m telescope, it would be very clear what to change, as opposed to if the value were listed as 0.041253.

The 'Eval' type gets even more powerful when you use variables. The file demo10.yaml has some examples that use the pos variable, the position of the galaxy relative to the center of the image, which GalSim will make available for you for any 'Tiled' or 'Scattered' image. The PSF fwhm is given as '0.9 + 0.5 * (world_pos.x**2 + world_pos.y**2) / 100**2', which calculates the PSF size as a function of position on the image.

Variables that GalSim will provide for you to use:

• world_pos = the position of the object in world coordinates relative to the center of the image.
  • Always available if image type is 'Tiled' or 'Scattered'.
  • Available for type = Fits only if explicitly provided in the config file.
  • A galsim.PositionD instance
• image_pos = the position of the object on the image in pixels.
  • Only available if image type is 'Tiled' or 'Scattered'.
  • A galsim.PositionD instance
• image_center = the center of the image in pixels. This is the position on the image that corresponds to world_pos = (0,0).
  • Only available if image type is 'Tiled' or 'Scattered'.
  • A galsim.PositionD instance
• image_xsize, image_ysize = the size of the image in pixels.
• stamp_xsize, stamp_ysize = the size of the postage stamp in pixels if available.
  • Not always available, since the postage stamp is allowed to be automatically sized based on the size of final object profile.
• file_num = the number of the file currently being worked on.
• image_num = the number of the image currently being worked on.
  • If parsing a value in input or output, this may not be available, or it may be set to the last image number from the previous file (if any).
• obj_num = the number of the object currently being worked on.
  • If parsing a value in input, output, or image, this may not be available, or it may be set to the last object number from the previous image (if any).
• start_obj_num = the number of the first object in the current file.
• rng = the random number generator being used for this object.
  • A galsim.BaseDeviate instance
  • You can convert it to whatever deviate you need. e.g. galsim.GaussianDeviate(rng,1.0,0.2)()
• catalog = the current input catalog(s).
  • Only available if input has a catalog field.
  • a list of galsim.Catalog instances
• dict = the current input dictionary(ies).
  • Only available if input has a dict field.
  • a list of galsim.Dict instances
• real_catalog = the current real galaxy catalog(s).
  • Only available if input has a real_catalog field.
  • a list of galsim.RealGalaxyCatalog instances
• nfw_halo = the current NFW halo object(s).
  • Only available if input has an nfw_halo field.
  • A list of galsim.NFWHalo instances
• power_spectrum = the current power spectrum realization(s).
  • Only available if input has an power_spectrum field.
  • A list of galsim.PowerSpectrum instances
  • The method buildGrid will already have been called at the start of the image if the image type is 'Tiled' or 'Scattered'.

Python modules that GalSim will import for you to use:

• 'math'
• 'numpy'
• 'os'
• 'galsim' (obviously)

It is also possible to define your own variables to use in your expression simply by defining more attributes in addition to str. The first letter of the attribute declares what type it should be evaluated to. Then the rest of the attribute name is the name of your variable.

For example, we do not have a specific type for drawing from a Log-Normal distribution. If you want the flux, say, to be log-normally distributed, you can write something like the following:

flux :
    type : Eval
    str : '1.e5 * math.exp(normal)'
    fnormal : { type : RandomGaussian , sigma : 0.2 }

The f at the start of fnormal indicates that the variable normal should be evaluated as a float_value. In this case using type = 'RandomGaussian'.

Another example appears in demo10.yaml. There, we define the magnitude of the ellipticity as:

e:
    type : Eval
    fr : { type : Eval , str : '(world_pos.x**2 + world_pos.y**2)**0.5' }
    str : '0.4 * (r/100)**1.5'

So this declares a float variable r that evaluates as the radial distance from the center. Then the ellipticity is defined in terms of r directly rather than via pos.

Initial letters of user-defined variables for 'Eval':

• 'f' = float
• 'i' = int
• 'b' = bool
• 's' = str
• 'a' = galsim.Angle
• 'p' = galsim.PositionD
• 'g' = galsim.Shear

Sometimes it is useful to have the same variable used by multiple Eval calculations. For such cases, Eval will look for a top-level field called eval_variables. If this field is present, then anything defined there will be accessible in all Eval calculations in addition to whatever variables are defined for each specific Eval item.

This is similar to the functionality that YAML provides where a value can be named by putting a variable name with an & before it before any value. Then later, you can refer to the value by that name preceded by a *, rather than write the value again. This can lead to more maintainable config files. E.g. demo10.yaml uses this functionality for num_in_ring, since the value is needed in two different calculations.

It can be convenient to combine the YAML naming scheme with our eval_variables setup in the following way:

eval_variables :
    fpixel_scale : &pixel_scale 0.3
    istamp_size : &stamp_size 100
    infiles : &nfiles 30
    [ ... ]

This can be put near the top of the YAML file to put the important values all in one place with appropriate names. Then in the rest of the file, the variables can be used with the YAML * notation:

image:
    pixel_scale : *pixel_scale

or as part of an Eval item:

shift :
    type : RTheta
    r : { type : Eval , str : 'pixel_scale * 0.5' }
    theta : { type : Random }

TODO list:

There are a number of features that we are planning to add that are not currently implemented. If you would really like one of these features to be added, please let us know. This will help us prioritize work. We will (probably) get to everything eventually, but we would rather work on things that users actually want. :) Similarly, if there is something that you want to do that does not seem to be possible with the current configuration options, please let us know that too. The best way to do this is to post an Issue with your desired feature. Or comment on an existing issue if there is one that already deals with the topic of your feature request.

• It would be useful to be able to output the values generated for various parameters to an output catalog. (Issue #301)

• Implement psf.signal_to_noise when no galaxy is present. (Issue #459)

• Implement gal.signal_to_noise for draw_method = 'phot'. (No issue yet.)