Custom instrument packages for SimCADO

Warning

This format will only work with SimCADO v0.4 and later versions

This way of specifying files and parameters has been depreciated for newer versions of SimCADO. A new API description will be available by June 2019.

SimCADO is a (reasonably) flexible framework for simulating telescope and instrument optical trains. It was primarily developed for use with the ELT telescope and the MICADO / MAORY instrument, however many other instruments can be simulated with SimCADO if the proper configuration files are provided.

This page aims to give a short overview of which files SimCADO needs in order to simulate a custom optical train.

Note

We’re happy to help implement other instruments with SimCADO

If you would like to use SimCADO to model another telescope / instrument system, and would like some help with how to do this, please contact the SimCADO team. We’re more that happy to help out.

Config Files

The default SimCADO configuration file can be found in the data folder of the installation directory: simcado/data/default.config. This folder can be found by calling:

import simcado
simcado.__data_dir__

To create a custom instrument package, we will need to create our own .config file. We can dump the default file by calling:

simcado.commands.dump_defaults("my_new_instrument.config", selection="all")

Next we will need to alter the values to fit our instrument. For some keywords we will need to provide file paths to a (correctly formatted) file describing the given effect. The most important files are described below.

File paths

Note

Use simcado.__search_path__ to store files in multiple places

SimCADO contains a function (find_file) which looks for file names in the directories contained in the list simcado.__search_path__. By default this list contains the working directory, and the two main folders in the installation directory:

>>> simcado.__search_path__
['./', '<pkg_dir>/simcado', '<pkg_dir>/simcado/data']

By adding directory names to the __search_path__ list at the beginning of a python script/session, we can tell SimCADO to look in other directories for the relevant files.

Required Files

PSF files

Keywords : SCOPE_PSF_FILE

This file should contain a (series of) PSF kernel(s) as FITS image extensions. Each extension must contain the keyword WAVE0 which tells SimCADO the wavelength for which the PSF kernel is relevant (in m or in um).

For MICADO, the default PSF FITS file contains extensions for each of the major broadband filters: I [0.87um], z [1.05um], J [1.25um], H [1.65um], Ks [2.15um]. For filters with central wavelengths which fall between these PSF kernels, SimCADO takes the extension with the closest wavelength.

In case we need to include field-variations in the PSF cube, the new PSF format is also accepted by SimCADO. It’s description can be found here :

Mirror transmission curves

Keywords : SCOPE_M1_TC, INST_MIRROR_AO_TC, INST_MIRROR_TC, INST_FILTER_TC

TC (transmission curve) files are ASCII table files with two columns. The transmission profile can be as simple or as detailed as we want. Here is an example of a very simple filter transmission file:

# TC_filter_Ks.dat
Wavelength  Transmission
0.1         0
1.89        0
1.9         1
2.4         1
2.41        0
3.0         0

SimCADO uses astropy.table to read the file, so if astropy can read it, SimCADO can too.

Mirror lists

Keywords : SCOPE_MIRROR_LIST, INST_MIRROR_AO_LIST

These list files contain information on the geometry of the mirrors included in either the telescope section, or AO section of the optical system. Below we have the first 3 lines of the ELT’s mirror list file:

# EC_mirrors_scope.tbl
Mirror      Outer   Inner   Angle  Temp    Coating
M1          37.3    11.1    0.     0.      TC_mirror_mgf2agal.dat

where Outer, Inner [m] refer to the diameter of the mirror, Angle [deg] is the angle at which the plane of the mirror differs from that of the light beam, Temp [deg C] is the mirror temperature for determining the thermal background, and Coating is the filename of the Transmission Curve (TC) file describing the spectral response of the mirror coating material (see above: Mirror transmission curves).

The internal mirror configuration of the actual instrument is a special case. It is assumed that the cryostat temperature is sufficiently low that the blackbody emission from the internal mirrors is negligible. Hence only the mirror transmission is important and can therefore be described with the following two parameters:

INST_NUM_MIRRORS
INST_MIRROR_TC

For instruments without AO module, we can force SimCADO to ignore the AO components by setting the following keyword:

INST_USE_AO_MIRROR_BG = False

Wavefront errors

Keywords : INST_WFE

The current version of SimCADO (v0.6) includes only the reduction in strehl ratio induced by wave front error. It does this by calculating the peak of a normalised 2D Gaussian kernel (i.e. between 1 and 0) for each wavelength in the final system transmission curve, and applying an effective transmission loss based on the Gaussian peak value. This is very much a ‘first order approximation’ to including wavefront errors in the optical train. It should be noted that this has been improved upon in SimCADO v1.0.

The file passed to FPA_QE should follow this table format (taken from the MICADO+ELT INST_wfe.tbl file):

# wfe_rms   no_surfaces     material    optics
# [nm]      [#]             [str]       [str]
20          11              gold        mirror
10          4               glass       entrance_window
10          2               glass       filter
10          8               glass       ADC

Optional files

Atmospheric spectra

Keywords : ATMO_TC, ATMO_EC

By default SimCADO uses precalculated output from the ESO skycalc tool for the atmospheric emission and transmission curves. The default tables (EC_sky_25.tbl and TC_sky_25.tbl) are for PWV = 2.5mm and include columns for various airmasses over a wavelength range or [0.3, 3.0]um.

Additional transmission curves

Keywords : INST_DICHROIC_TC, INST_ENTR_WINDOW_TC, INST_PUPIL_TC

In case the transmission properties of any dichroics, entrance windows or pupil optics need to be included. The file format is the same as above for Mirror transmission curves

Detector noise images

Keywords : FPA_NOISE_PATH

By default SimCADO uses a FITS file containing an image of the detector noise pattern for the HAWAII-4RG detectors. We can include pre-calculated noise maps by passing a FITS file to FPA_NOISE_PATH. No special header keywords are needed.

Detector linearity curve

Keywords : FPA_LINEARITY_CURVE

Detector linearity can be included by passing an ASCII table with two columns which relate the real incoming flux to the measured photon flux as measured by the read-out electronics. The table should look like this:

# real_flux measured_flux
0           0
1           1
1000        998
3500        3200
...         ...
200000      180000
1000000     180000

Note

Linearity is applied to any imaging observation, regardless of length

Yes, this shouldn’t be, but we haven’t got around to fixing that yet. Hence to model long exposure observations (i.e. >1 min), it’s best just to set FPA_LINEARITY_CURVE = False