**********************************************************************

   FIS 1.0  -- FMOS Image Simulator --                    

                          20030830 Masayuki Akiyama
**********************************************************************

   With the simulation software, you can make simulated FMOS FITS 
   images. You can check your reduction methods, evaluate detection
   sensitivity, and estimate survey limitations with the simulated 
   images. Reduced sample images and sample reduction procedure are 
   also provided in the package.

**********************************************************************
0. Environment *******************************************************
**********************************************************************

Developed Environment
---------------------
         Pentiam III 700MHz +
            gcc version 2.96 20000731 (Kondara MNU/Linux 2.1)
            cfitsio version 2.420

Requirements
------------
         "cfitsio" library is used. Retrieve the library from
         http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html
         In the Makefile for FIS, it is assumed that cfitsio library 
         and header files are reachable without any special path 
         settings (like installed in /usr/local/lib and  
         /usr/local/include). If not, you have to modify Makefile
         (like add -I<Your Installed Directory>, 
          -L<Your Installed Directory>).

Tested Environment
------------------
         SunBlade 1000 workstation +
            gcc version 2.95.3 20010315 (Solaris SunOS 5.8)
            cfitsio version 2.300

**********************************************************************
1. Compile Source Codes **********************************************
**********************************************************************

  At first unzip and untar the distributed file by

     % gzip -cd FIS-***.tar.gz | tar xvf - 

  The source files will be extracted in the directory FIS-*****.
  Move in to the directory by
  
     % cd FIS-***

  If you are installing to Solaris machine, uncommnet the line
   # LIBSOL = -lnsl -lsocket
  in the Makefile.

  You can make the executable file of FIS with

     % make all

  (The basic parameters for FIS is written in the header file 
  "fmos_model.h". If you changed parameters in the file, you need 
   to recompile the "FIS" to reflect the change.)

  You can make sample FITS image with
 
    % ./FIS SAMPLE1

  For LOW resolution mode frames, it will take about 10 min to make 
  one image on Linux machine with Pentiam III 700MHz. It will take 
  about 8 min to make one image on SunBlade1000. For HIGH resolution
  frames, the required time is SHORTER, because gaussian convolution
  process is not required for HIGH resolution case.

  You can make 8 sample FITS images at once with
   
    % source SAMPLE_low.sh
    % source SAMPLE_high.sh

  It will take 1-2 hours to make 8 images.

  The sample procedures will make fits files in "sample" directory.
  You can check the FITS file with

   % skycat sample/fibre_flat.fits

  You can open ASCII header information on fibres, by clicking 
  FMOS_FIBRE entry in the skycat "FITS HDUs" sub-window.

**********************************************************************
2. Usage of FIS ******************************************************
**********************************************************************

 FIS [INPUT_PARAMETER_FILE_NAME] 

   [INPUT_PARAMETER_FILE_NAME] have to have the entries, SPECLIST, 
   FLATIMAGE, ATMABS, EFFIFILE, MASKFILE, MODE, SEEING, AIRMASS, EXPT,
   WAVEMIN, and FITSNAME. The format is like,
     <FORMAT>
       SPECLIST   sample/fibre_flat.list         /* Spectral template list etc. */
       ATMABS     datafiles/MK_atm_abs.dat       /* Atmospheric Absorption data */
       FLATIMAGE  datafiles/FMOS_flat_model.fits /* Detector flat-field image */
       EFFIFILE   datafiles/FMOS_effi_model.dat  /* System efficiency model */
       MASKFILE   datafiles/FMOS_mask_model.dat  /* OH suppression mask model */
       MODE              LOW                     /* Spectroscopy mode HIGH or LOW */
       SEEING            0.5                     /* Seeing FWHM (arcsec) */
       AIRMASS           0.0                     /* Airmass sec(z) */
       EXPT             10.0                     /* Exposure time (s) */
       WAVEMIN        10000.0                    /* Minumum wavelength coverage */
       FITSNAME   sample/fibre_flat.fits         /* Output FITS file name */

   Details of input parameters are explained below. Sample data
   entries are available SAMPLE1, SAMPLE2, ... SAMPLE7.

(char) SPECLIST
-------------------
   Specify name of the file which contains data for each fibre.
   The format of the file is,

    <FORMAT>
     TEMP_FILE SKY_CONT_FILE SKY_LINE_FILE WSHIFT TRANS PROF TARG_NAME TARG_RA TARG_DEC TARG_TYPE
                              :
                              :   
                                (NFIBRE lines)

   Each entry in this file corresponds to one fibre in the final image.
   The number of lines in the file has to match the number of fibres
   (NFIBRE=200) in the parameter file. The first three parameters point 
   the file names for each spectrum. The next two parameters simulate 
   the properties of each fibre. The last four parameters are dummy 
   target data for ASCII header. 

   Sample SPECLIST files are available in the directory "sample" with file 
   postfix with ".list". For example, "sample/fibre_flat.list"  is the SPECLIST 
   used to make the "fibre_flat.fits" sample FITS image (Details of each sample 
   files, please see 4. Sample Files., below).

   Col 1: (char) TEMP_FILE 
      Specify name of a spectral data file of target object (like, model
      galaxies, average QSO spectrum and so on). The format of the file 
      is 
   
      <FORMAT>
        WAVELENGTH(angstrom) FLUX DENSITY(erg/s/cm2/A)

      You can find sample template files in "template" directory.

   Col 2: (char) SKY_CONT_FILE (MK_sky_cont.dat)
      Specify name of a spectrum file of continuum emission from 
      night sky. The format of the file is

      <FORMAT>
        WAVELENGTH(angstrom) FLUX DENSITY(erg/s/cm2/A/arcsec2)

      The sample "datafiles/MK_sky_cont.dat" file is made assuming
      300 (photons/s/m2/micron/arcsec2) in the J-band. The value
      based on 
         Tokunaga 2000 "Astrophysical Quantities, Infrared Astronomy" (NIR) 
         Massay et al. 1997 "Low-to-Moderate Resolution 
              Optical Spectroscopy Manual for Kitt Peak" (Optical)

   Col 3: (char) SKY_LINE_FILE (MK_sky_line.dat)
      Specify name of a night sky line list. It describes the
      wavelength and the strength of each OH night sky line.
      The format of the file is

      <FORMAT>
         WAVELENGTH(angstrom) FLUX(!!photons!!/s/!!m2!!/A/arcsec2)

      The sample "datafiles/MK_sky_line.dat" file is
           made based on 
          Maihara et al. 1993 PASP 105 940 (NIR)  
          Osterbrock et al. 1997 PASP 109 614 (Optical)
          Osterbrock and Martel 1992 PASP 104 76 (Optical)  
          http://www.ucolick.org/jfulb/OH.html (Optical)

      (You can use different SKY_CONT_FILE and SKY_LINE_FILE for
      different fibre (for example to simulate spacial variation 
      of sky lines). In the case, you need to prepare sets of 
      SKY_CONT_FILE and SKY_LINE_FILE for each fibre by yourself.)   

   Col 4: (float) WSHIFT (angstrom)
      It is set to simulate the offset of each fibre in the slit. 
      The shift is at the detector in unit of angstrom, i.e. 20 
      micron shift at the fibre slit means 6.3 micron shift on the 
      detector and that corresponds to 0.3 and 1.3 angstrom shift 
      in high- and low-resolutoin mode, respectively. 

   Col 5: (float) TRANS (max=1, min=0)
      It is the transmittance of each fibre (max=1 min=0).
      You can simulate the fibre to fibre variation of the 
      transmittance with the parameter. 

      In the sample ".list" files, WSHIFT and TRANS
      are calculated with "add_fibre_data.awk" script. See 
      "add_fibre_data.sh" to check how to use the script.

   Col 6: (char) PROF (GAU, M23, M24)
      Specify type of profile of the model object.
        GAU : Gaussian
        M23 : Median profile of V=23mag galaxies
        M24 : Median profile of V=24mag galaxies
      The profile will be used to calculate loss at aperture
      entrance.

   Col 7: (char) TARG_NAME
   Col 8: (char) TARG_RA
   Col 9: (char) TARG_DEC
   Col 10: (char) TARG_TYPE
        Dummy data for ASCII header.

(char) FLATIMAGE (FMOS_flat_model.fits)
----------------------------------------
    Specify name of the flat-field (reflect pixel to pixel sensitivity
    difference of the detector) image of FMOS. The sample flat-field 
    image "datafiles/FMOS_flat_model.fits" is made from a CISCO H-band flat-field 
    image "flat_OPNS_H.011103.fits". In order to make 2048*2048 image, 
    the CISCO 1024*1024 image is 2*2 tiled with "imtile" command in IRAF.     

   !! NOTE !! 
       With FMOS we can not take an imaging flat-field image. We can
       only take a fibre flat-field image.

(char) ATMABS (MK_atm_abs.dat) 
------------------------------------
   Specify name of the file which contains data of atmospheric
   transmittance at airmass of 1.0. The format of the file is

   <FORMAT>
     WAVELENGTH(angstrom) TRANSMITTANCE(max:1,min:0)

   The transmittance is adjusted to input arimass
   value in the software. The sample "datafiles/MK_atm_abs.dat" is made 
   based on 
        http://www.ast.cam.ac.uk/science/mkmodels
        http://www.jach.hawaii.edu/UKIRT.new/astronomy/exts.html
        Stevenson 1994 MNRAS 267 904

(char) EFFIFILE (FMOS_effi_model.dat)
--------------------------------------
   Specify name of the file which contains data for FMOS instrument
   efficiency (w/o aperture loss, atmorpheric absorption).
   The format of the file is,

   <FORMAT>
     WAVELENGTH(angstrom) EFFICIENCY(max=1; min=0)

   The sample data is based on the efficiency estimate made by
   Ian Lewis. The original file is available in 
       datafiles/FMOSthroughput2.xls  (Exel file)

(char) MASKFILE (FMOS_mask_model.dat)
--------------------------------------
   Specify name of the file which contains data for masked 
   wavelength range. The format of the file is,

   <FORMAT>
     WAVELENGTH_STR(angstrom) WAVELENGTH_END(angstrom)

   The sample file will mask +-6A of strong night sky lines.
   You can make your own mask by the command like below

     % awk '{if($2>1) $1-6,$1+6}' MK_sky_line.dat > YOUR_MASK

(char) MODE (HIGH or LOW)
-------------------------
   Specify mode of spectroscopic observation. LOW resolution 
   mode is with R=500 and 4A/pixel and HIGH resolution mode is
   with R=2200 and 1A/pixel.

(float) EXPT
--------------------
   Exposure time of the simulation in second.

(float) AIRMASS
---------------
   Airmass value in sec(z)

(float) SEEING
--------------
   Seeing FWHM value in arcsec.

(float) WAVEMIN
---------------
   Short edge of wavelength range.

(char) FITSNAME
--------------------
   Output FITS file name.

************************************************************************
3. Inside FMOS Image Simulator and Input Parameters ********************
************************************************************************

The simulator will do the following steps. Some parameters written in
capical letters are explained above. Remaining capical parameters are 
written in "fmos_model.h". The default values are shown in parenthesis.

Step 1: Make array of NFIBRE fibre spectra reading SPECLIST

    Array of NFIBRE(=200) fibre spectra is made based on SPECLIST.
   
    At first, spectrum data of a model object is read from TEMP_FILE. 
    The spectrum data is resampled into DLAMBDA(=1.0angstrom) bin from 
    WAVEMIN to NBIN(=11000) bins, i.e., if WAVEMIN=9000, 9000-20000A 
    wavelength range will be covered in the initial spectrum. The 
    spectrum data of a model sky continuum is also read from 
    SKY_CONT_FILE and resampled into the same binning.

    The object and sky coont. spectra data and the OH sky line strength, 
    read from SKY_LINE_FILE are multiplied by atmospheric absorption
    (ATMABS file) normalized to specified airmass value (AIRMASS), and 
    FMOS system efficiency model (EFFIFILE).

    To simulate the resolution at the OH supression mask, the object and 
    sky cont. spectra are convolved by Gaussian with SIGMA_OHS(=2.0angstrom)
    +Top-hat with DIA_IMAGE(=4.0angstrom). It is assumed that all the
    fibres have the same PSF in the dispertion direction. OH lines with 
    the same profiles are added to sky continuum spectrum.

    Next OH line rejection is simulated. The information on the wavelength 
    range masked is provided in MASKFILE. The wavelength range described 
    in the file is masked. It is assumed that in the wavelengrh range only 
    OHSUP_FRACTION(=0.001) of light will transmit to the next step.

    Finally, the spectra are convolved with Gaussian with SIGMA_SPE(=14.0angstrom)
    representing the resolution on the detector (i.e., after VPH-grating).

    Re-sampled based on sampling rate on detector, DPIXEL(=4.0angstrom/pix).

Step 2: Make 2048*2048 ideal Image of fibre spectra based on the array.

    2048*2048 image is made from the array of the 200 spectra. Each fibre
    spectrum is not a straight line, but a curve with bending. The amount
    of bending is assumed to have 2nd-order polynomial (ax^2+by+x). The 
    spectra are parallel at x=0. The separation of fibres at x=0 is 
    FIB_SEP(= 10.0 pixel). The amount of bend is linear function of fibre 
    number: the central fibre (fibre#=100=NFIBRE/2) has bend=0, and fibres 
    at edge (fibre#=0,200=NFIBRE) have bend of BEND_EDGE(=26.0pixel). The
    amount of bend increases linearly from the centre to the edge.

    In the spatial direction, each fibre spectrum has profile of Top-hat 
    profile with DIA_FIMA_PIX(=4.0pixel) convolved with Gaussian profile 
    with a sigma. The sigma value depends on fibre#: the central fibre
    has SIGMA_FIB_CEN(=0.4pixel) and fibres at edge have 
    SIGMA_FIB_EDGE(=0.8pixel). The size of the sigma increases linearly
    from the centre to the edges.

Step 3: Simulate Pixel-to-pixel Sensitivity Difference with Flat Image.

    The simulated image is multiplied by the simulated flat image 
    FLATIMAGE.

Step 4: Add noise on the Ideal Image

    Thermal background is added to the ideal image. The countrate
    of the background is assumed to be BACKGROUND(=0.05 photons/s/pixel).
    After that poisson and read out noise is added on the ideal image. 
    The noise is assumed to follow Gaussian distribution. The read out 
    noise is READ_ON(=10.0e). 

Step 5: Simulate Detector Linearity Limit and GAIN correction

    The calculations so far made in float. The noise-added (float) image 
    is devided by GAIN(=3.5) and all the values are made to short integer
    value. The linearity of the detector is also considered. The counts
    (CTS) above LIN_LIMIT(=20000) follows the equation below,
        (CORRECTED CTS) = (LIN_LIMIT) + ((CTS) - (LIN_LIMIT))**(POW_LIMIT)

Step 6: Cosmic Rays
    
    Cosmic rays are added at this step. Number of cosmic rays are
    determined by NCOSMIC(=0.5) * EXPT. The counts of cosmicrays are
    COS_VALUE(=30000ADU).

Step 7: Make FITS file

    The image (short) data array is converted to FITS image by cfitsio functions.
    The final image name is FITSNAME.

******************************************************************************
4. Sample Data ***************************************************************
******************************************************************************

You can make sample simulated data by

 % ./FIS SAMPLE1   (low resolution mode SAMPLE 1)

or 
 
 % source SAMPLE_low.sh   (low resolution mode SAMPLE 1-9)
 % source SAMPLE_high.sh  (high resolution mode SAMPLE 1-9)

The sample FITS image will be written in the directory "sample".
Extension of the image data is [0], and ASCII table is [1].
In IRAF, when you display a frame, you must specify extension of the
file,

 cl> display fibre_flat.fits[0]

You can check the ASCII table with "tdump" command in stsdas.ttools
with,

 tt> tdump fibre_flat.fits[1]

The short description of the SAMPLE images are listed below.

SAMPLE1. Fibre Flat Field Image (Flat Lamp = obj_flat_AB10, NO atm. abs. nor sky emissions)
   fibre_flat.fits

SAMPLE2. Fibre Flat Field OFF Image (Flat Lamp = obj_none, NO atm. abs. nor sky emissions)
   fibre_flat_off.fits

SAMPLE3. Calibration Lamp Image (Input Lamp Lines instead of sky lines)
   fibre_calib.fits

SAMPLE4. Sky Data Sample (30min integration at airmass 1.5)
   obj_none_30_15.fits

SAMPLE5. QSO template at z=1.4 with H=19.0 (30min integration at arimass 1.5)
   obj_QSOz14_H19_30_15.fits

SAMPLE6. Emission line at 16000A with 1e-15 erg/s/cm2 (30min integ. at airmass 1.5)
   obj_Em_15_16_30_15.fits

SAMPLE7. Emission line at 16000A with 1e-16 erg/s/cm2 (30min integ. at airmass 1.5)
   obj_Em_16_16_30_15.fits

SAMPLE8. AB=20mag (Hvega=18.6mag) Flat Spectrum Objects (30min integration at airmass 1.5)
  obj_flat_AB20_30_15.fits

SAMPLE9. AB=21mag (Hvega=19.6mag) Flat Spectrum Objects (30min integration at airmass 1.5)
  obj_flat_AB21_30_15.fits

The SAMPLE3-8 frames contain relatively bright (J=15) F0V star model in 
1st, 51st, 101st, and 200th fibre. You can use the spectra to correct
the atmospheric absroption lines.

The fibre slit shift and fibre-to-fibre transmittance variation is
modeled with "add_fibre_data.awk" for these SAMPLE data.

******************************************************************************
5. Example of Reduction of the Sample Data ***********************************
******************************************************************************

The examples of reduced spectra are also available in "sample" directory.
   "obj_QSOz14_H19_cal.fits", "obj_Em_15_16_30_15_cal.fits"
   "obj_Em_16_16_30_15_cal.fits", "obj_flat_AB20_30_15_cal.fits", 
   "obj_flat_AB21_30_15_cal.fits"
Each image has 200 lines and each line represent extracted one fibre spectrum. 
You can compare the resulting spectra with the input template files in
"template" directory,
    "obj_QSOz14_H19", "obj_Em_15_16", "obj_Em_16_16", 
    "obj_flat_AB20", "obj_flat_AB21".

The reduction method used in the reduction is described below.

<< Reduction Receipe >>

Step 0 : Remove cosmicrays

imred.crutil.cosmicrays is used to remove cosmicrays on the images.

Step 1 : Subtract sky-frames from target frames

CR-removed sky-data frames are subtracted from CR-removed target frames.
Both images should have same integration times.

Step 2 : Extract 1D spectra from 2D frames + Flat-fielding + Wavelength Calibration

Two handred 1D spectra are extracted from the sky-subtracted frame
using imred.hydra.dohydra routine. In the routine, flat-fielding and
wavelelgnth calibration are also done.

Step 3 : Atmospheric Absorption line correction and flux calibration

The flat-fielded target spectra are divided by a flat-fielded 
standard-star spectrum (50th fibre). The resulting frame is multiplied by a
model spectrum of the standard star (template/obj_F0V_J15). Finally, we 
obtain the flux-calibrated spectra of targets.

Command lines and parameters used in the above processes are 
recorded in the file "IRAF_reduce_log". For details of the reduction of 
fibre multi-object spectrograph data, refer these pages,

http://taltos.pha.jhu.edu/~rrg/science/norris/norris_reduction.html
http://iraf.noao.edu/tutorials/dohydra/dohydra.html
http://www.noao.edu/kpno/docs.html

******************************************************************************
5. Remaining Issues **********************************************************
******************************************************************************

1. No scattering in the spectrograph is considerd.
2. Non-uniform fibre separation.

******************************************************************************
6. Revision Memo *************************************************************
******************************************************************************

20030830 Ver.1.0 Released. 
   from http://www.subaru.naoj.org/staff/akiyama/FMOS/FIS-20030830.tar.gz
                             
       Masayuki Akiyama  akiyama@subaru.naoj.org
