# User guide¶

## Purpose¶

TIPS is a simulation tool which produce the expected images of an observation for a given instrument.
The current version of TIPS is based on aXeSIM, an image simulator developed for HST (aXeSIM, Kuemmel et al. 2007 and 2009, aXeSIM web page).
TIPS is a prototype which is able to simulate the 16 detectors the spectrometer of EUCLID/NISP.
The current version include an automatic mode which was think to be easy to use.
TIPS is able to manage several inputs formats.

## Usage¶

TIPS have to be run in python.
The automated usage of TIPS was think to be as simple as possible.
Unfortunately all the feature of TIPS are not yet able in the full automated usage mostly because they are not documented.

The first think to do is to load the tips module.

import tips


### The inputs¶

In the automated mode, TIPS need as input only the sky sources which are defined in two files, the catalog of sources and the spectra file.
The catalog of sources contains for each sources, the position on the sky and the shape parameters (ellipse as in sextractor).
The spectra file contains the spectra of the sources.
You can load TIPS with for example a catalog of sources './cat.fits’ and a spectra file './spc.fits’ with the following command.

obs = tips.Observation(inCatDir='cat.fits', inSpcDir='spc.fits')


#### The catalog of sources¶

Internally TIPS have its own data model but it’s easy to load data from over format.
TIPS can read catalog of sources in ascii (with a sextractor header) and fits.
Currently to format of data are loadable.

• The TIPS format which needs the following columns:
• NUMBER (integer) : identifier of the sources
• RA (float) : Right ascension in degree
• DEC (float) : Declination in degree
• A_SKY (float) : Major axis of shape ellipse in arcsec
• B_SKY (float) : Minor axis of shape ellipse in arcsec
• THETA_SKY (float) : angle of shape ellipse in degree
• MODSPEC (int) : spectrum index in the spectra file
• The CMC format (see CMC web page):
• Id (integer) : identifier of the sources
• RA (float) : Right ascension in degree
• DEC (float) : Declination in degree
• A_IMAGE (float) : Major axis of shape ellipse in arcsec/0.03
• B_IMAGE (float) : Minor axis of shape ellipse in arcsec/0.03
• THETA_IMAGE (float) : angle of shape ellipse in degree
• SpcExt (int) : spectrum index in the spectra file

obs = tips.Observation(inCatDir='cat.fits', inSpcDir='spc.fits', inCatForm='CMC')


#### The spectra file¶

The spectra have to be stock separately of the source catalog in a fits file.
The fits file have to contain one spectra by Header/Data Units (HDU).
A spectrum in the spectra file is link to a source with the number of its HDU which is the spectrum index in the catalog of sources.
All the HDUs of one spectra file have to be in the same format.
TIPS manage to format of spectrum.

• The CMC/TIPS format:
• lambda (float) : wavelength in Angstrom
• flux (float) : flux in erg/s/cm/A
• The aXeSIM format:
• WAV_NM (float) : wavelength in nanometer
• FLUX (float) : flux in erg/s/cm/A

To load a spectra in aXeSIM format you have set the option inSpcForm to 'aXeSIM’:

obs = tips.Observation(inCatDir='cat.fits', inSpcDir='spc.fits', inSpcForm='aXeSIM')


Currently, in the full automatized mode of TIPS, you can only load predefine observation mode.
This predefine observation mode are simple and don’t use all the feature of TIPS, in particular we simulate detector with identical pixel while TIPS can simulate much more complex detector.
The predefine observation mode in TIPS are the four spectroscopic mode of EUCLID/NISP (Gblue/Gred, 0/90 degree).
In these examples we assumed :
• a constant sky backgroud based on the zodiacal light model of Aldering et al. 2002
• a sensitivity define from files in “tips/data”:
• Gblue_noDET.sens.fits for Gblue
• Gred_noDET.sens.fits for Gred
• a constant scattering equal to 10% zodiacal light
• a constant thermal noise equal to 10% zodiacal light
• a constant dispersion equal to 0.54 Angstrom/um (= 9.8 Angstrom/pixel)
• 4x4 detector in the focal plan :
• gap in the X direction is 3mm
• gap in the Y direction is 6mm
• 2040x2040 pixel for each detector
• a pixel size equal to 18um
• a pixel scale equal to 0.3 arcsec
• a constant read noise equal to 6.0 electron/pixel
• a constant quantum efficiency equal to 0.75
• a constant dark current equal to 0.1 electron/pixel/second

A predefine observation mode of the spectro of EUCLID/NISP could be load with the method loadEUCLIDDefault.
The option grismName able you to choose the spectro mode: Gblue0, Gblue90, Gred0 or Gred90
When you load the observation mode you have to specify the exposure time and the pointing in (ra,dec) with the options exptim, ra0 and dec0.
The reference of the pointing is define as the lower left pixel of the lower left detector.

This example load the observation mode Gblue / 0 degree, with an exposure time of 560s and a pointing reference (150.1, 2.7)

obs.loadEUCLIDDefault(grismName='Gblue0', exptime=560.0, ra0=150.1, dec0=2.7)


Idem with the observation mode Gblue / 90 degree.

obs.loadEUCLIDDefault(grismName='Gblue90', exptime=560.0, ra0=150.1, dec0=2.7)


Idem with the observation mode Gred / 0 degree.

obs.loadEUCLIDDefault(grismName='Gred0', exptime=560.0, ra0=150.1, dec0=2.7)


Idem with the observation mode Gred / 90 degree.

obs.loadEUCLIDDefault(grismName='Gred90', exptime=560.0, ra0=150.1, dec0=2.7)


### Run the simulation¶

The last step is to compute the simulation.
To do that, simply run the method runSimulation.

obs.runSimulation()


By default runSimulation write the results of the simulation in the current directory.
You can change the path with the option workDir.

obs.runSimulation(workDir='/data/julien/workdir/')


### The output¶

The result of TIPS simulation for given observation mode is one image for each detector of the focal plan.
In the the case of the predefine observation mode currently implemented, TIPS will produce 16 images, one for each detector of the EUCLID/NISP.

The result is organized in the aXeSIM software way.
After running the method runSimulation, you will have 6 directories in your working path:
• “CONF/” contains all the individual configuration files used by TIPS/aXeSIM to simulate the images.
• “DATA/” contains all the individual data needed by TIPS/aXeSIM to simulate the images.
• “OUTSIM/” contains the images produce by TIPS/aXeSIM.
• “DRIZZLE/”, “OUTPUT/” and “DRIZZLE/” are needed directory for the computation and have to be empty (if not something doesn’t work in the simulation).

If all run fine, you should not care about the files in “CONF/” and “DATA/”.
If you care, the format of the files in “CONF/” and “DATA/” are described in the aXe documentation

All the ouput images are in the directory “OUTSIM/”.
In EUCLID default mode, the simulation of one observation produce 16 images, one by detector.
Each detector have an identifier with 2 digits, the first digit count the detector from left to right, the second digit count the detector from down to up.
Simply, still in the EUCLID/NISP case, the identifier of the 16 detectors in the focal plan will be:

 03 13 23 33 02 12 22 32 01 11 21 31 00 10 20 30

The name of the images produced by TIPS contains explicitly the information of the input catalog name, the instrument name, the grism used and the detector identifier.
For example, the image of the detector “23”, with the grism Gblue and an dispersion orientation of 90 degree, and based on an input catalog “sky_783562.fits”, will be named

sky_783562_NISP_GBLUE_90.0_23_IMG.fits


The format of the images is the standard HST/aXe format (see aXe documentation).
In summary, the output are in fits files.
Each output fits contains four HDU:

• HDU 0 empty
• HDU 1, named “SCI”, contains the science image
• HDU 2, named “ERR”, contains the error image
• HDU 3, named “DQ”, contains the mask image

#### Science image¶

Keyword Value exemple Description
XTENSION 'IMAGE’ IMAGE extension
BITPIX 64 number of bits per data pixel
NAXIS 2 number of data axes
NAXIS1 2040 length of data axis 1
NAXIS2 2040 length of data axis 2
PCOUNT 0 required keyword; must = 0
GCOUNT 1 required keyword; must = 1
EXTNAME 'SCI’ name of this extension
DATE '2012-07-04T17:14:02’ file creation date (YYYY-MM-DDThh:mm:ss UT)
WCSAXES 2 number of World Coordinate System axes
CRPIX1 0.0 x-coordinate of reference pixel
CRPIX2 0.0 y-coordinate of reference pixel
CRVAL1 150.1 first axis value at reference pixel
CRVAL2 2.7 second axis value at reference pixel
CTYPE1 'RA---TAN’ the coordinate type for the first axis
CTYPE2 'DEC--TAN’ the coordinate type for the second axis
CD1_1 8.3E-05 partial of first axis coordinate w.r.t. x
CD1_2 0.0 partial of first axis coordinate w.r.t. y
CD2_1 0.0 partial of second axis coordinate w.r.t. x
CD2_2 8.3E-05 partial of second axis coordinate w.r.t. y
LTV1 0.0 offset in X to subsection start
LTV2 0.0 offset in Y to subsection start
LTM1_1 1.0 reciprocal of sampling rate in X
LTM2_2 1.0 reciprocal of sampling rate in Y
EXPNAME 'None’ calibration exposure identifier
INSTRUME 'NISP’ instrument name
GRISM 'GBLUE’ name of the grim
ORIENTAT 90.0 position angle of image y axis (deg. e of n)
EXPTIME 560.0 exposure time
DETECTOR '23’ detector identifier
GAIN 1.0 detector gain
QE 0.75 detector quantum efficiency
DC 0.1 detector dark current
Data :
• Image of 2040x2040 pixels
• Pixels values are float in electrons/second

#### Error image¶

Header : same as science image

Data :
• Image of 2040x2040 pixels
• Pixels values are float in electrons/second

#### DQ image¶

Header : same as science image

Data :
• Image of 2040x2040 pixels
• Pixels values are integer

Go to top