Using the Simulation Class

Overview

The simulation.Simulation.create_simulation function creates one of four different types of images, taking a variety of parameters for these simulations. Most are specific to one simulation type, but some are more general. The star_galsim and star_simple types share many parameters.

sim_type: the type of simulaton created (donut, star_galsim, star_simple, spectrograph)

image_size: the size of the simulated image, a tuple. Note: most of the simulations currently overwrite this variable, like donut’s 2000x1000 image and spectrograph’s 4000x4000 images.

nObj: the number of objects, or spectra lines, simulated (default 20). For the donut simulations the code puts nObj donuts on each half.

Simulation Types

Donut

If the parameter ‘sim_type’ is set to ‘donut’, the method creates an image of simulated donuts. This makes use of the makedonut function contained in the Donut library. The code creates two separate arrays of donuts, with the second array having a defococus (z4) coefficient negative of that of the first. These arrays both have nObj donuts. It combines these arrays together in a 2000x1000 pixel image.

Parameters used this simulation are:

zernCoeffs: array of coefficients which distorts the donuts as they are created (default [0., 0., 0., 10., .3, .4, .2, .1, -.3, .05, .5]). This list starts with z1 and can have as many as 39 terms; however not all are necessary.

Star_Galsim

The ‘star_galsim’ type simulates stars using the GalSim package. This package must be installed first and be available as an eups product. The code creates Gaussian profiles of the stars using flux and half-light radius values and places them randomly on the image, unless otherwise specified. Then it puts a certain amount of noise imitating CCDNoise onto the image.

Parameters used in this simulation are:

roi_list: list of star locations where the simulation places specific stars. The simulation first adds all the stars in roi_list to their given locations and then puts in the rest of the stars (either randomly or with a fixed seed) and makes sure they don’t overlap with the roi_list locations.

psf_flux: flux of stars (PSFs) created (default 1e6). GalSim computes this by integrating over the changing flux in each pixel.

psf_size: approximate size of stars (PSFs) created, in arcsec (default 1).

psf_flux_deviation: amount of deviation between flux values chosen. The simulation chooses flux values between (psf_flux - psf_flux_deviation) and psf_flux + psf_flux_deviation).

galsim_pixel_scale: pixel scale (arcsec / pixel) used in the images (default .127).

galsim_sky_level: sky level of the CCDNoise (ADU / arcsec ^ 2) used in the simulations (default 2.5e4).

fixed_positions: a boolean to tell the simulation to keep stars in the same locations in the simulation. The positions do vary slightly by random amounts. The code does this by using a fixed random seed which can be specified. This allows images to remain similar over multiple fake exposures (default False).

fixed_random_seed: the random seed used if fixed_positions is set to True (default 6673476).

fixed_pixel_deviation: the standard deviation (pixels) during each simulation allowed for the stars if fixed_positions is set to True (default 10). This uses a Gaussian distribution for both the x and y deviations and combines them. (mean = 0, sigma = fixed_pixel_deviation).

Star_Simple

The ‘star_simple’ type simulates stars using simple NumPy operations.

Parameters used in this simulation are:

exptype: type of exposure (light, dark) for the simple star simulation. Should be set as ‘light’ to simulate stars (default ‘light’).

roi_list: list of star locations where the simulation places specific stars. The simulation first adds all the stars in roi_list to their given locations and then puts in the rest of the stars (either randomly or with a fixed seed) and makes sure they don’t overlap with the roi_list locations.

fixed_positions: a boolean to tell the simulation to keep stars in the same locations in the simulation. The positions do vary slightly by random amounts. The code does this by using a fixed random seed which can be specified. This allows images to remain similar over multiple fake exposures (default False).

fixed_random_seed: the random seed used if fixed_positions is set to True (default 6673476).

fixed_pixel_deviation: the standard deviation (pixels) during each simulation allowed for the stars if fixed_positions is set to True (default 10). This uses a Gaussian distribution for both the x and y deviations and combines them. (mean = 0, sigma = fixed_pixel_deviation).

Spectrograph

The ‘spectrograph’ type simulates spectra of stars using the desimodel software to project arrays of photons and wavelengths onto a fake CCD. Next it adds a given amount of noise to the image, varying the noise added based on the quadrant (data section) of the image. Additionally it adds prescan and overscan regions to the image to simulation the pixel readout style of the actual images. Note: in order to add the correct prescan and overscan regions, the ‘image_size’ parameter is not used, as the images must have fixed sizes.

The desimodel, desiutil, and specter software must be downloaded before this type of simulation will run. Currently they are all located at https://github.com/desihub. Additionally, either in the code or outside of it, the ‘DESIMODEL’ environment variable must be set to the location of the desimodel software. Currently, the software is in /n/des/talford/spectra_simulation/desimodel.

Parameters used in this simulation are:

spectrograph_channel: channel (‘r’, ‘b’, or ‘z’) of the spectrograph used in the simulations (default ‘r’).

spectrum_fraction: fraction (1 / x) of spectra (amount of dots in line) to plot to reduce runtime. For instance, a spectrum fraction of 10 projects every tenth spectra onto the CCD (default 1).

Example simulation code:

inputs = {'sim_type': 'donut',
          'nObj': 100,
          'image_size': (2000, 2000)
          }
s = Simulation(inputs)
img1 = s.create_simulation()
s.update({'sim_type' : 'star_simple',
          'fixed_positions': True,
          'image_size': (3000, 2000)
          })
img2 = s.create_simulation()

Using simulations in the Camera and FPC applications:

When using the Simulation class in these applications, the simulation parameters can be inputted through an ini file if the CONTROLLER_TYPE is set to ‘TOMMY_SIMULATOR’. Because these parameters are initially read as strings, the params zernCoeffs and image_size must be modified to be configured. zernCoeffs must be inputted as a series of numbers (i.e. 1 2 3 4 5 …), and the image_size tuple is replaced with img_length and img_width

In this example, because the sim_type parameters is set to star_galsim, parameters such as spectrograph_channel and zernCoeffs will not be used. Any parameters not set in the ini file are their default values.

You can take an exposure running the ini file by first telling the camera to configure through the console, then prepapre_for_exposure, then expose. prepare_for_exposure requires an expid, and optionally you can set the exptype to ‘ROI’ and also give it an roi_list to use for placing stars on the image. Expose only requires the same expid. Then running expose ‘next’ will repeat exposures for that expid without having to run prepare_for_exposure again. Note: the ‘ROI’ exptype will only keep and save the roi stamps from the image. Additionally, you can set the roi_list in the actual simulation parameters and it will use those in a normal full exposure.

TOMMY_SIMULATOR adds a couple new aspects to the Camera application. These only happen if the controller_type is set to TOMMY_SIMULATOR. First, it takes in specific configuration variables from the ini file. It allows to user to set and get these from the architect.

Also, when preparing for exposure, if the exptype is set to ROI, at the end it updates the simulaton parameters to include the ROI_list (you can’t configure it in the ini file because it’s a parameter for prepare_for_exposure).

Also, every time after prepare_for_exposure it changes the random seed it uses. This way images on multiple frames of the same exposure will be the same, but different exposures will produce different locations of stars in the simulatons.

Next, it takes the exposure and makes an image using the Simulation class. After it takes the exposure and creates the simulation, if the simulation is an ROI exptype, it still sets the full image to the primary[‘data’] part of the exposure dictionary. This way the GFABuilder can receive both the ROI and full stamps when it asks to get the images from the GFAs.

[[CAMERA]]
  product = Camera
  version = tommy
  application_args = --device_mode, False,
  controller_type = TOMMY_SIMULATOR
  num_obj = 10
  zernCoeffs = .1 .2 5 4 .4 .5
  img_length = 2000
  img_width = 1000
  sim_type = star_galsim
  psf_flux = 10000000
  psf_size = 2
  psf_flux_deviation = 5000000
  spectrograph_channel = r
  fixed_random_seed = 55678
  fixed_positions = True
  fixed_pixel_deviation = 5

Running simulations from the GFABuilder Application:

The GFABuilder Application tells 4-6 GFAs (running the Camera application) to take exposures of data and then packages this data into multi extension fits files. This is done through the run_exposure_loop command. This command requires an expid and can either take an exptype as ‘FULL’ or ‘ROI’.

If the exptype is set to ‘ROI’, the application looks at the variable ‘GFA_rois’ and gives each GFA its own roi_list from that dictionary. Then it prepares and takes the exposure. First it sends back all the roi stamps and a multi-extension FITS file of all of them. Then it sends back the full images and builds a FITS file of the 4-6 full GFA simulations.

If the exptype is set to ‘FULL’, the application simply prepares and takes a full exposure with each GFA. It then receives the 4-6 full images and packages them together. The GFA_rois variable is not used.

In the .ini file you can specify the amount of GFAs with the GFA_list variable. Additionally, you can give each GFA simulation parameters in its block, or make it easier using a stereotype.

  [[GFA0]]
    stereotype = CAMERA
  [[GFA1]]
    stereotype = CAMERA
  [[GFA2]]
    stereotype = CAMERA
  [[GFA3]]
    stereotype = CAMERA
  [[GFA4]]
    stereotype = CAMERA
  [[GFA5]]
    stereotype = CAMERA
  [[GFABUILDER]]
    product = GFABuilder
    version = trunk
    xterm = true
    image_dir = /n/des/talford/dos_home/architectures/osu
    fits_dir = /n/des/talford/dos_home/architectures/osu
    application_args = --device_mode, False,
    GFA_list = GFA0 GFA1 GFA2 GFA3 GFA4 GFA5

[Devices]

  [Stereotypes]
    [[CAMERA]]
      product = Camera
      version = tommy
      xterm = true
      xterm_args = -hold, -iconic
      sim_type = star_galsim
      application_args = --device_mode, False,
      controller_type = TOMMY_SIMULATOR
      num_obj = 50
      fixed_positions = True
      galsim_sky_level = 250000
      fixed_pixel_deviation = 5