Skip to content

Config Objects

Jump to bottom
Mike Jarvis edited this page Nov 9, 2017 · 11 revisions

GalSim defines a number of object types, which correspond to the GSObject types in the python code. Some are designed to be appropriate for describing PSFs and others for describing galaxies. GalSim does not enforce this distinction in any way; you can use any object type in the psf or gal fields. But normally, the psf field would use types from the PSF types below, and the gal field would use types from the galaxy types. There are also some generic types that can be appropriate for either.

Each object type sets a number of other items that either must or may be present in the dict for the object (i.e. in the top level psf or gal field or farther down in the dict where an object is being defined, such is in a 'List' object type). These attributes are given as bullet items for each type defined below.

There are also some other attributes that are allowed for any object (or sometimes just galaxies), regardless of what type they are.

And finally, it is possible to define your own object type, which we describe near the bottom of this page.

PSF Types

  • '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)
    • half_light_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)
    • 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 (either lam_over_diam or both lam and diam required) Lambda / telescope_diameter converted to units of arcsec (or whatever units you want your profile to use).
    • lam = float_value (either lam_over_diam or both lam and diam required). This should be the wavelength in nanometers.
    • diam = float_value (either lam_over_diam or both lam and diam required). This should be the telescope diameter in meters.
    • obscuration = float_value (default = 0) The linear size of an obstructing secondary mirror as a fraction of the full mirror size.
    • scale_unit = str_value (default = 'arcsec') Units to be used for internal calculations when calculating lam/diam.
  • '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 or both lam and r0 is required) Lambda / r0 converted to units of arcsec (or whatever units you want your profile to use).
    • lam = float_value (exactly one of lam_over_r0, fwhm or half_light_radius or both lam and r0 is required) The wavelength in nanometers.
    • r0 = float_value (exactly one of lam_over_r0, fwhm or half_light_radius or both lam and r0 is required) The Fried parameter in meters.
    • r0_500 = float_value (optional, in lieu of r0). The Fried parameter in meters at a wavelength of 500 nm. The correct r0 value will be calculated using the standard relation r0 = r0_500 * (lam/500)**1.2.
    • fwhm = float_value (exactly one of lam_over_r0, fwhm or half_light_radius or both lam and r0 is required)
    • half_light_radius = float_value (exactly one of lam_over_r0, fwhm or half_light_radius or both lam and r0 is required)
    • scale_unit = str_value (default = 'arcsec') Units to be used for internal calculations when calculating lam/r0.
  • 'OpticalPSF' A PSF from aberrated telescope optics.
    • lam_over_diam = float_value (either lam_over_diam or both lam and diam required)
    • lam = float_value (either lam_over_diam or both lam and diam required). This should be the wavelength in nanometers.
    • diam = float_value (either lam_over_diam or both lam and diam required). This should be the telescope diameter in meters.
    • 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 at Noll index 1, since there is no 0). With this syntax, you may go to as high order as you want.
    • 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 dimension of a central obscuration as a fraction of the pupil linear dimension.
    • interpolant = str_value (default = 'quintic') Which interpolant to use for the constructed InterpolatedImage object describing the PSF profile.
    • 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.
    • suppress_warning = bool_value (default = False) Whether to suppress warnings about possible aliasing problems due to the choices of oversampling and pad_factor.
    • 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.
    • 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.
    • pupil_plane_im = str_value (optional) Instead of using strut-related parameters to define the pupil plane geometry, you can use this parameter to specify a file-name containing an image of the pupil plane.
    • pupil_angle = angle_value (default = 0 degrees) When specifying a pupil_plane_im, use this parameter to rotate it by some angle defined counter-clockwise with respect to the vertical.
    • scale_unit = str_value (default = 'arcsec') Units to be used for internal calculations when calculating lam/diam.

Galaxy Types

  • '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).
    • scale_radius = float_value (exactly one of half_light_radius or scale_radius is required)
    • half_light_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.
  • 'Spergel' A profile based on the Spergel (2010) paper with the form: I(r) ~ (r/scale_radius)^nu * K_nu(r/scale_radius) where K_nu is the modified Bessel function of the second kind.
    • nu = 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)
  • '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.
    • 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.
    • 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 noise.whiten or noise.symmetrize. 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').
  • 'COSMOSGalaxy' Either a real or parametric galaxy from the COSMOS catalog. This requires that input.cosmos_catalog be specified and uses the following fields:
    • index = int_value (default = 'Sequence' from 0 to cosmos_catalog.nobjects-1) 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.
    • gal_type = str_vale (required, unless real_catalog.use_real is False, in which case 'parametric') Which type of galaxy to use. Options are 'real' or 'parametric'.
    • deep = bool_value (default = False) Whether the flux and size should be rescaled to approximate a galaxy catalog with a limiting mag of 25 in F814W, rather than 23.5.
    • 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 noise.whiten or noise.symmetrize. 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.
    • sersic_prec = float_value (default = 0.05) The desired precision on the Sersic index n in parametric galaxies. GalSim is significantly faster if it gets a smallish number of Sersic values, so it can cache some of the calculations and use them again the next time it gets a galaxy with the same index. If sersic_prec is 0.0, then use the exact value of index n from the catalog. But if it is >0, then round the index to that precision.
    • num = int_value (default = 0) If input.real_catalog is a list, this indicates which number catalog to use.
  • 'InclinedExponential' The 2D projection of a 3D exponential profile: I(R,z) ~ sech^2 (z/h_s) * exp(-R/R_s) at an arbitrary inclination angle. The base profile is inclined along the y-axis, so if you want a different position angle, you should add a rotat field.
    • inclination = angle_value (required) The inclination angle, defined such that 0 degrees is face-on and 90 degrees is edge-on.
    • half_light_radius = float_value (exactly one of half_light_radius or scale_radius is required) The half-light radius as an alternative to scale_radius.
    • scale_radius = float_value (exactly one of half_light_radius or scale_radius is required) The scale_radius, R_s.
    • scale_height = float_value (exactly one of scale_height or scale_h_over_r is required) The scale height, h_s.
    • scale_h_over_r = float_value (exactly one of scale_height or scale_h_over_r is required) The ratio h_s/R_s as an alternative to scale_height.
  • 'InclinedSersic' 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) The half-light radius as an alternative to scale_radius.
    • scale_radius = float_value (exactly one of half_light_radius or scale_radius is required) The scale radius, R_s.
    • 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.
    • scale_height = float_value (exactly one of scale_height or scale_h_over_r is required) The scale height, h_s.
    • scale_h_over_r = float_value (exactly one of scale_height or scale_h_over_r is required) The ratio h_s/R_s as an alternative to scale_height.
  • 'DeltaFunction' A delta function profile with a specified flux. This is typically not used for galaxies, but rather for stars in a scene that includes both. So when convolved by the PSF, the stars will have the profile from the PSF, but the correct flux.
  • 'RandomWalk' A profile made of a sum of a number of delta functions distributed according to a random walk. This is intended to represent knots of star formation, so it would typically be added to a smooth disk component and have the same size and shape.
    • npoints (required) How many points to include.
    • half_light_radius (required) The expectation of the half light radius, setting the overall scale of the random walk. Note: any given realized profile will not necessarily have exactly this half-light radius.

Generic Types

  • 'Gaussian' A circular Gaussian profile: I(r) ~ exp(-r^2 / (2 sigma^2)). This is not all that appropriate for either PSFs or galaxies, but as it is extremely simple, it is often useful for very basic testing, as many measured properties of the profile have analytic values.
    • 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)
  • '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.
    • use_true_center = bool_value (default = True) Whether to use the true center of the provided image as the nominal center of the profile (True) or round up to the nearest integer value (False).
    • hdu = int_value (default = the primary HDU for uncompressed images, or the first extension for compressed images) Which HDU to use from the input FITS file.
  • 'Box' A rectangular boxcar profile: I(x,y) ~ Heaviside(width/2-|x|) Heaviside(height/2-|y|).
    • width = float_value (required) The full width of the profile.
    • height = float_value (required) The full height of the profile.
  • 'Pixel' A square boxcar profile: I(x,y) ~ Heaviside(scale/2-|x|) Heaviside(scale/2-|y|). This is equivalent to a 'Box' type with width = height (called scale here). Note however, that the default rendering method already correctly accounts for the pixel response, so normally you will not need to use this as part of the PSF (or galaxy).
    • scale = float_value The pixel scale, which is the width and height of the pixel.
  • 'TopHat' A circular tophat profile: I(r) ~ Heaviside(radius-|r|)
    • radius = float_value The radius of the circular tophat profile.
  • '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.

Other Attributes:

There are a number of transformation attributes that are always allowed for any object type. Some of these operations do not commute with each other, so the order is important. The following transformations will be applied in the order given here, which corresponds roughly to when they occur to the light packet traveling through the universe.

The first few, flux, dilate, ellip, and rotate, are typically used to define the intrinsic profile of the object. 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 shift the position of the galaxy relative to the center of the postage stamp.

  • flux = float_value (default = 1.0) Set the flux of the object 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 profile some non-round intrinsic shape.
  • rotate or rotation = angle_value (optional) Rotate the profile by a given angle.
  • scale_flux = float_value (optional) Factor by which to scale the flux of the galaxy profile.
  • 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.
  • skip = bool_value (default=False) Skip this object.

There are also a few special attributes that are only allowed for the top-level gal field, not for objects that are part of an aggregate object like 'Sum', 'Convolution' or 'List' and not for psf.

  • resolution = float_value (optional) 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.

Custom Object Types

To define your own object type, you will need to write an importable Python module (typically a file in the current directory where you are running galsim, but it could also be something you have installed in your Python distro) with a function that will be used to build a GalSim GSObject.

The build function should have the following functional form:

def BuildCustomObject(config, base, ignore, gsparams, logger):
    """Build a custom GSObject of some sort

    @param config       The configuration dict of the object being built
    @param base         The base configuration dict.
    @param ignore       A list of parameters that might be in the config dict, 
                        but which may be ignored.  i.e. it is not an error for
                        these items to be present.
    @param gsparams     An optional dict of items used to build a GSParams object
                        (may be None).
    @param logger       An optional logger object to log progress (may be None).

    @returns gsobject, safe
    
    The returned gsobject is the built GSObject instance, and safe is a bool 
    value that indicates whether the object is safe to reuse for future stamps
    (e.g. if all the parameters used to build this object are constant and will
    not change for later stamps).
    """
    # If desired, log some output.
    if logger:
        logger.debug("Starting work on building CustomObject")

    # The gsparams are passed around using a dict so they can be easily added to.
    # At this point, we would typically convert them to a regular GSParams
    # instance to use when building the GSObject.
    if gsparams: 
        gsparams = galsim.GSParams( **gsparams )

    # If you need a random number generator, this is the one to use.
    rng = base['rng']

    # Build the GSObject
    # Probably something complicated that you want this function to do.
    gsobject = [...]

    safe = False  # typically, but set to True if this object is safe to reuse.
    return gsobject, safe

The base parameter is the original full configuration dict that is being used for running the simulation. The config parameter is the local portion of the full dict that defines the object being built, e.g. config might be base['gal'] or it might be farther down as an item in the items attribute of a 'List' or 'Sum' object.

Then, in the Python module, you need to register this function with some type name, which will be the value of the type attribute that triggers running this function.

galsim.config.RegisterObjectType('CustomObject', BuildCustomObject)

If the builder will use a particular input type, you should let GalSim know this by specifying the input_type when registering. E.g. if the builder expects to use an input dict file to define some properties that will be used, you would register this fact using

galsim.config.RegisterObjectType('CustomObject', BuildCustomObject, 
                                 input_type='dict')

The input object can be accessed in the build function as e.g.

    input_dict = galsim.config.GetInputObj('dict', config, base, 'CustomObject')
    ignore = ignore + ['num']

The last argument is just used to help give sensible error messages if there is some problem, but it should typically be the name of the object type being built. When you are using an input object, the 'num' attribute is reserved for indicating which of possibly several input objects (dict in this case) to use. You should not also define a num attribute that has some meaning for this object type. If you are using the ignore parameter to check for extra invalid parameters, you would thus want to add 'num' to the list.

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

modules:
    - my_custom_object

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

Then you can use this as a valid object type:

gal:
    type: CustomObject
    ...

For examples of custom objects, see des_psfex.py and des_shapelet.py in the galsim.des module, which define custom object types DES_PSFEx and DES_Shapelet. These objects are used by draw_psf.yaml in the examples/des directory. It may also be helpful to look at the GalSim implementation of the Add, Convolve, List, OpticalPSF, and None types in galsim/config/gsobject.py.

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