source: trunk/MagicSoft/Simulation/Detector/Starfield/README@ 11169

$Id: README,v 1.2 2000-09-21 10:08:10 harald Exp $

STARFIELD README

D. Petry, IFAE, Campus UAB, Spain


This is the first useful version of the starfield generator (SG).

Purpose:

The SG is needed to simulate the non-diffuse part of the night
sky background (NSB) in images taken by Cherenkov telescopes.
It reads data from star catalogues (presently only SKY2000, see below)
and calculated from the given position of the telescopes optical
axis (in celestial coordinates), the positional and spectral data 
for each star from the catalog, how many photons of which wavelength 
(presently 290 nm - 800 nm are simulated) will hit a circular surface 
of given radius ("mirror radius") in a given time ("integration time").
For each photon the director cosines are calculated.
Arrival time, wavelength and ground position are randomized within the 
integration time, the four wavebands (U, B, V, R) and the mirror area
respectively with flat distributions. 

SG finally writes the generated photons into a binary file of
CORSIKA format which can be read by the "Reflector" simulation.
The output form the Reflector can then be fed to the camera.

The camera will pixelize the photons and calculate the average
NSB photon rate for each pixel. From this, the camera can then
generate the NSB contribution in each shower image using a Poisson
random generator and also taking into account the
atmospheric extinction and its dependence on the zenith angle.


Installation and first test:

1) Adjust the Makefile to your system and type
 
           make depend
           make

   The result should be an executable named "starfield"

2) Download the star catalog:

     ftp cdsarc.u-strasbg.fr

     (log in as user anonymous)

     cd pub/cats/V/102
     prompt
     hash
     bin
     mget sky*.dat.gz
     bye

3) Unzip the 24 files you have downloaded and put them into some permanent
   directory e.g. the Data directory of the Monte Carlo source code.

4) Edit the parameter file. The distribution includes an
   example file named "starfield.par" which looks like this:

     Starfield Generator Parameters, Date: 21-1-2000, Comment: Example (Crab Nebula)
     Center of FOV: ira_hours ira_min ira_sec  idec_degrees  idec_arcmin dec_arcsec:
     05 34 32 +22 00 52.1 
     Radius of the FOV for the catalog readout (degrees):
     2.0
     Integration time for the calculation of the number of photons (seconds):
     50e-9
     Mirror radius for the generation of random impact points (meters):
     10.0
     Path inside which the star catalog data can be found:
     /usr/users/xf/stardata
     Verbosity level (0 = not verbose, 1 = verbose, 2 = very verbose, 3 = very very ...):
     0
     Output file name, starfiel will generate cerXXXX and staXXXXX
     CrabNebula

   Note that the there is a header line followed by pairs of an explanatory
   line and a data line. You may write in the header line and the explanaroy 
   lines whatever you like, but the data lines matter. The lines may be as long
   as you like but don't add any carriage returns.

   For a first test run, you will only have to edit the path for the   
   star data which is the one defined by yourself in step (3).


5) Test run.
   Run the program by entering

     starfield

   The diagnostic output to the screen should be ending with

     Opened starfield.par for reading ...
     Starfield Generator Parameters, Date: 21-1-2000, Comment: Example (Crab Nebula)
     Position RA DEC: 5 34 32 22 0 52.1
     FOV Radius:2 degrees
     Integration Time:5e-08 s
     Mirror Radius:10 m
     Catalog Data Path: ... your path ...
     Verbosity: 0
     SKY2000 - Master Star Catalog - Star Catalog Database, Version 2
     Sande C.B., Warren W.H.Jr., Tracewell D.A., Home A.T., Miller A.C.
     <Goddard Space Flight Center, Flight Dynamics Division (1998)>
     Opened file ...your path.../sky04.dat for reading ...
     EOF reached; accepted 0 stars from this segment.
     Opened file ...your path.../sky05.dat for reading ...
     Warning: star no. 53701440 is bright (Vmag =3, Bmag = 2.85)
              and has no Umag measurement. Estimated Umag is 2.2395
     EOF reached; accepted 120 stars from this segment.
     Opened file ...your path .../sky06.dat for reading ...
     EOF reached; accepted 0 stars from this segment.
     Accepted 120 stars in total.
     Writing binary Cherenkov file ./cerCrabNebula ...
     Done.
     Writing binary statistics file  ./staCrabNebula ...
     Done.

6) Using the output.
   The two output files (in this case cerCrabNebula and staCrabNebula) are
   of the same format as the file for a single event in the CORSIKA
   shower simulation. The number in the name is generated from the
   RA (h) and DEC (deg) of the telescope position in order to allow
   a distinction.

   The further processing has to be done with the reflector.
   A sample parameter file for the reflector is the following:

       reflector 0.3                                 -*- sh -*-
     #
     # Sample parameters file 
     #
     verbose_level 2
     #
     fixed_target  0. 0.
     ct_file        ../Data/magic.def 
     output_file   starfield.rfl
     atm_model     ATM_NOATMOSPHERE
     data_paths 1
     ... the diretory in which the output of starfield is found
     end_file

   Note that the line "fixed_target  0. 0." is a must.
   Also the line "atm_model     ATM_NOATMOSPHERE" is necessary
   because the extinction will be simulated in the camera (see above).

7) Notes on the input parameters of starfield

   a) Center of FOV: ira_hours ira_min ira_sec  idec_degrees  idec_arcmin dec_arcsec:
     
      Here you can put any valid celestial coordinates on the sky.
      The program doesn't veto invalid coordinates yet, but the result
      is undefined.

   b) Radius of the FOV for the catalog readout (degrees):
     
      This should be a number larger than the outermost radius of the
      CT's field of view (FOV), but not too much larger because there
      is a limit to the number of photons which can be stored by the 
      program and the number of generated photons grows with the number 
      of stars in the FOV. If you hit the limit, try decreasing the 
      integration time. 

   c) Integration time for the calculation of the number of photons (seconds):

      Since we are dealing with a ray-tracing approach, we need actual
      individual photons, not just rates. This integration time is needed
      in order to normalize the numbers of generated photons for each star.
      The camera program will later calculate the photon rates for each
      pixel by dividing by this number. 

      Not that this number is given in seconds, but only up to about 100 ns
      make sense, i.e. you have to write something like 100e-9 

   d) Mirror radius for the generation of random impact points (meters):

      This number is needed for the flux normalization and the generation
      of the ground impact points of the photons. Adjust it to the size
      of the simulated telescope.

   e) Path inside which the star catalog data can be found:

      This is the directory containing the SKY2000 data (see point 3)

   f) Verbosity level (0 = not verbose, 1 = verbose, 2 = very verbose, 3 = very very ...):

      Set this value to 0 for normal usage. Increase it to discover
      what is going on in detail.

   g) Output file name, starfiel will generate cerXXXX and staXXXXX

      This the key name for the output files

8) parameter file name

   starfield accepts as its only command line argument the name
   of the parameter file. Typing

         starfield my.par          

   will make starfield look for the parameter file "my.par" in 
   the current directory. If no argument is given, it assumes the
   name of the parameter file is "starfield.par".