Skip to content

Config Documentation

Jump to bottom
Mike Jarvis edited this page Sep 6, 2013 · 210 revisions
WARNING: This documentation is now being prepared for the forthcoming version 1.0 release. Some features described here are not in the last release (0.5). Some are even still in pull requests and are not merged into master yet.
  1. Overview
  2. Top level fields
  1. Setting values
  1. The Eval type
  2. 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

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.
  • pix defines what kind of pixel 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 at least 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 the default pixel profile is normally what you want (a square pixel using the same pixel_scale that the drawn image will use), so you will almost never want to bother with the pix field.

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 either (required) or (default = something) to indicate whether the item is required or if there is some sensible default value. Occasionally, the default will be None which 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.

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)). This uses the following fields:
      • 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). This uses the following fields:
      • 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 (default = 0) The profile can be truncated to 0 at some radius if desired. The default = 0 means no truncation.
    • 'Airy' A simple Airy disk. (Typically one would convolve this by some model of the atmospheric component of the PSF.) This uses the following fields:
      • 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). This uses the following fields:
      • 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. This uses the following fields:
      • lam_over_diam = float_value (required)
      • defocus = float_value (default = 0)
      • astig1 = float_value (default = 0)
      • astig2 = float_value (default = 0)
      • coma1 = float_value (default = 0)
      • coma2 = float_value (default = 0)
      • trefoil1 = float_value (default = 0)
      • trefoil2 = float_value (default = 0)
      • spher = float_value (default = 0)
      • circular_pupil = bool_value (default = True)
      • obscuration = float_value (default = 0)
      • oversampling = float_value (default = 1.5)
      • pad_factor = float_value (default = 1.5)
      • nstruts = int_value (default = 0)
      • strut_thick = float_value (default = 0.05)
      • strut_angle = angle_value (default = 0 degrees)
    • 'Sum' or 'Add' Add several profiles together. This uses the following field:
      • items = list (required) A list of profiles to be added.
    • 'Convolution' or 'Convolve' Convolve several profiles together. This uses the following field:
      • items = list (required) A list of profiles to be convolved.
    • 'List' Select profile from a list. This uses the following fields:
      • 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 (default = 1.0) Dilate the profile by a given scale, preserving the flux.
  • ellip = shear_value (default = None) 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)). This uses the following fields:
      • 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). This uses the following fields:
      • 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)). This uses the following fields:
      • 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 (default = 0) The profile can be truncated to 0 at some radius if desired. The default = 0 means 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). This uses the following field:
      • 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 (default = 0) The profile can be truncated to 0 at some radius if desired. The default = 0 means 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. 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 = 0) 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 doesn't matter in most cases, but if you are whitening, the most coherent noise profile is Gaussian, since that works seamlessly.
      • noise_pad_size = float (default = 0) If non-zero, 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.
    • 'InterpolatedImage' A profile described simply by a provided image (given in a fits file). This uses the following fields:
      • 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').
      • dx = 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 (default = 0; 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 (default = ''; 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 (default = '') Filename 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. This uses the following fields:
      • 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.
    • 'Sum' or 'Add' Add several profiles together. This uses the following field:
      • items = list (required) A list of profiles to be added.
    • 'Convolution' or 'Convolve' Convolve several profiles together. This uses the following field:
      • items = list (required) A list of profiles to be convolved.
    • 'List' Select profile from a list. This uses the following fields:
      • 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 (default = 1.0) Dilate the profile by a given scale, preserving the flux.
  • ellip = shear_value (default = None) Shear the profile by a given shear to give the galaxy some non-round intrinsic shape.
  • rotate or rotation = angle_value (default = 0) Rotate the profile by a given angle.
  • magnify or magnification = float_value (default = 1.0) Magnify the profile by a given scale, preserving the surface brightness.
  • shear = shear_value (default = None) Shear the profile by a given shear.
  • shift = pos_value (default = None) 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 (default = None) 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 (default = None) 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 (default = None) 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.

pix

The pix field defines the profile of the pixel. However, you will almost never need to specify this one. The default is to use the same pixel shape as the image uses, namely a square pixel whose size is image.pixel_scale. However, if you want to model something a bit unusual like a slightly non-square pixel, or a non-uniform response across the pixel or something, then you might want to use this. Of course, any profile type that is valid for psf or gal is technically allowed here as well. But there is really only one that probably makes sense to use.

Valid pix fields are:

  • type = str (required) Valid options are:
    • 'Pixel' A rectangular boxcar profile. This uses the following fields:
      • xw = float_value (required)
      • yw = float_value (default = xw)
    • 'None' means no pixel response should be included in the effective PSF. Typically, this would only be used when the PSF already has the pixel response included, e.g. because it is an image of an actual observed PSF. Note: This cannot be used with the photon shooting method of drawing the image.

All of the modifiers like flux, ellip, etc. that gal has are also valid here.

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). This uses the following fields:
      • size = int_value (default = 0) 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 = 0 means that GalSim should 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. This uses the following fields:
      • 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). This uses the following fields:
      • 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 (default = 0) The stamp size attributes work like the size attributes for 'Single'.
      • stamp_xsize = int_value (default = stamp_size)
      • stamp_ysize = int_value (default = stamp_size)
      • sky_pos = pos_value (only one of sky_pos and image_pos is allowed) The position in sky 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 sky_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 (default = 0) 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 = 0 means to use the time as the initial seed.

  • 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. This uses the following fields:
      • max_extra_noise = float_value (default = 0.01) If the image is sky 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.

  • noise = dict (default = None) 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). This uses the following fields:
        • 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. This uses the following fields:
        • 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 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. This uses the following fields:
        • 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 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. This uses the following fields:
        • 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.

  • 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.

  • wcs = dict (default = None) Specify a WCS shear to apply to the image.

    • type = str (default = Shear)
      • 'Shear' is the currently the only valid type. And since it is the default, you do not need to specify type for wcs. However, this leaves open the possibility of adding other, more sophisticated WCS schemes someday. This uses the following field:
        • shear = shear_value (required) The shear to apply.

  • 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. This uses the following fields:
    • file_name = str_value (required) Filename of the input catalog.
    • dir = str_value (default = '.') Directory catalog is in.
    • file_type = str_value (default = automatically determined from extension of file_name) Valid options are:
      • 'ascii' Read from an ASCII file. This uses the following field:
        • 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. This uses the following field:
        • hdu = int_value (default = 1) Which hdu to use within the FITS file.
  • dict defines an input dictionary, such as a YAML or JSON file. Connected with Dict value type described below. This uses the following fields:
    • file_name = str_value (required) Name of the dictionary file.
    • dir = str_value (default = '.') Directory 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. This uses the following fields:
    • file_name = str_value (required) Name of the FITS file.
    • dir = str_value (default = '.') Directory the file is in.
  • real_catalog defines a catalog of real galaxy images. Connected with RealGalaxy profile described above. This uses the following fields:
    • file_name = str_value (required) Filename of the input catalog.
    • dir = str_value (default = .) Directory catalog is in.
    • image_dir = str_value (default = dir) Directory containing the real galaxy images.
    • noise_dir = str_value (default = dir) 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 rather than reopen the fits file each time a galaxy is requested.
  • nfw_halo defines an NFW halo. Connected with NFWHaloShear and NFWHaloMagnification value types described below. This uses the following fields:
    • 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 sky coordinates relative to 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. This uses the following fields:
    • 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 fields is that they may optionally be lists. So you can have multiple input catalogs for instance; one for object parameters and one for overall image parameters perhaps. When using them, you would specify which item in the list to use with num.

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. This uses the following field:
      • 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. This uses the following field:
      • 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 a my_test.yaml configuration file would output to 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 (default = None) You can optionally output noiseless images of the PSF used for each galaxy. This uses the following fields:
    • 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')
    • dir = str_value (default = output.dir if provided, else None) (Only relevant if file_name is provided.)
  • weight = dict (default = None) You can optionally output the weight image (an inverse variance map of the noise properties). This uses the following fields:
    • 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')
    • dir = str_value (default = output.dir if provided, else None) (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 (default = None) 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. This uses the following fields:
    • 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')
    • dir = str_value (default = output.dir if provided, else None) (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).

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. This uses the following fields:
        • min = float_value (required)
        • max = float_value (required)
      • 'RandomGaussian' Generate random values from a Gaussian deviate. This uses the following fields:
        • sigma = float_value (required)
        • mean = float_value(default = 0)
        • min = float_value (default = None)
        • max = float_value (default = None)
      • 'RandomDistribution' Generate random values from a given probability distribution. This uses the following fields:
        • 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. Note: Sequence items in the input and output fields are indexed by the file_num, in the image field by the image_num, and otherwise by the obj_num. This uses the following fields:
        • 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 (default = None; 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 (default = None; at most one of last and nitems is allowed) The number of items in the sequence.
      • 'List' Select items from a list. This uses the following fields:
        • 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 for 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. This uses the following field:
        • 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'.
      • 'Eval' Evaluate a string. See 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. This uses the following fields:
        • min = int_value (required)
        • max = int_value (required) Note: the range includes both min and max.
      • 'Sequence' Generate a sequence of values. Note: Sequence items in the input and output fields are indexed by the file_num, in the image field by the image_num, and otherwise by the obj_num. This uses the following fields:
        • 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 = int_value (default = None; at most one of last and nitems is allowed) Note: if last is provided, the sequence includes last (assuming the step value lets it be included). After this value, the sequence will repeat starting with first again.
        • nitems = int_value (default = None; at most one of last and nitems is allowed) The number of items in the sequence.
      • 'List' Select items from a list. This uses the following fields:
        • items = list (required) A list of int_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.) This uses the following field:
        • key = str_value (required) The key name of the item to use.
      • 'Eval' Evaluate a string. See 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. Note: Sequence items in the input and output fields are indexed by the file_num, in the image field by the image_num, and otherwise by the obj_num. This uses the following fields:
        • first = bool_value (default = 0) For bool, the only two values in the sequence are 0 and 1, so step and last are not needed.
        • repeat = int_value (default = 1) How many times to repeat the same value before moving on.
      • 'List' Select items from a list. This uses the following fields:
        • 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.) This uses the following field:
        • key = str_value (required) The key name of the item to use.
      • 'Eval' Evaluate a string. See 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. This uses the following fields:
        • 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 = as many as needed) 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 other 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. This uses the following fields:
        • 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. This uses the following fields:
        • 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.) This uses the following field:
        • key = str_value (required) The key name of the item to use.
      • 'Eval' Evaluate a string. See 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. This uses the following field:
        • theta = float_value (required)
      • 'Degrees' or 'Deg' Use a float_value as an angle in degrees. This uses the following field:
        • theta = float_value (required)
      • 'Random' Generate a random angle uniformly distributed from 0 to 2pi radians.
      • 'List' Select items from a list. This uses the following fields:
        • 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.) This uses the following field:
        • key = str_value (required) The key name of the item to use.
      • 'Eval' Evaluate a string. See below.

shear_value

Options are:

  • A dict with:
    • type = str (required) Valid options are:
      • 'E1E2' Specify as a distortion in cartesian coordinates. This uses the following fields:
        • e1 = float_value (required)
        • e2 = float_value (required)
      • 'EBeta' Specify as a distortion in polar coordinates. This uses the following fields:
        • e = float_value (required)
        • beta = angle_value (required)
      • 'G1G2' Specify as a reduced shear in cartesian coordinates. This uses the following fields:
        • g1 = float_value (required)
        • g2 = float_value (required)
      • 'GBeta' Specify as a reduced shear in polar coordinates. This uses the following fields:
        • g = float_value (required)
        • beta = angle_value (required)
      • 'Eta1Eta2' Specify as a conformal shear in cartesian coordinates. This uses the following fields:
        • eta1 = float_value (required)
        • eta2 = float_value (required)
      • 'EtaBeta' Specify as a conformal shear in polar coordinates. This uses the following fields:
        • eta = float_value (required)
        • beta = angle_value (required)
      • 'QBeta' Specify as an axis ratio and position angle. This uses the following fields:
        • 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. This uses the following fields:
        • 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.) This uses the following field:
        • key = str_value (required) The key name of the item to use.
      • 'Eval' Evaluate a string. See 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. This uses the following fields:
        • x = float_value (required)
        • y = float_value (required)
      • 'RTheta' Specify using polar coordinate. This uses the following fields:
        • 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.) This uses the following fields:
        • 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. This uses the following fields:
        • 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.) This uses the following field:
        • key = str_value (required) The key name of the item to use.
      • 'Eval' Evaluate a string. See 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 * (sky_pos.x**2 + sky_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:

  • sky_pos = the position of the object in sky coordinates relative to the center of the image.
    • Only available if image type is 'Tiled' or 'Scattered'.
    • 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
  • 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 gridded version of getShear 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 : '(sky_pos.x**2 + sky_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)

  • Add more WCS types than just a shear value. (Issue #364)

  • Add shear_type = 'Sum' to add two shears correctly. (Issue #457)

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

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

Home

Installation Instructions

Installation FAQ

RealGalaxy Data Download Page

Building GalSim with the LSST stack

Tutorials

Config Documentation

Rowe et al, 2015

Roman module diagrams

Developer Information

Documentation of version 2.2

Checklist for making a pull request

Checklist for making a new tagged release

Clone this wiki locally