source: trunk/MagicSoft/Simulation/Detector/Camera/README@ 5110

README for "camera"

Warning: this file contains information on the first versions of camera
program. Please refer to the manual (see MAGIC web pages) for up to date 
information.

(for camera.cxx version 1.5/camera.h 1.4/creadparam.cxx 1.2/
       creadparam.h 1.2/camera-v.h 1.2)

D. Petry, 18-2-2000 

This version includes drastic changes compared to camera.cxx 1.4.
It is not yet finished and not immediately useful because the
trigger simulation is not yet re-implemented. I had to take it
out together with some other stuff in order to tidy the whole 
program up. This is not meant as an insult to anyone. I needed
to do this in order to be able to work on it.

This version has been put in the repository in order to be
able to share the further development with others.

If you need something working, wait or take an earlier one.

Summary of the changes compared to  camera.cxx 1.4:

1) General removal of all the #defines which activate/deactivate
   features of the program. This program is to simulate a Cherenkov
   telescope and it is going to have all the features it needs.
   If features have to be deactivated, this should happen via the
   parameters file. The #defines only lead to confusion and errors
   on the side of the users.

2) Removal of the old implementation of the trigger. The future
   trigger will be implemented in the class MTrigger or somewhere
   else.

3) In order to simulate the NSB, it was necessary to introduce the
   array 

        class Photoelectron photoe[iMAXNUMPHE]

   One instance of  Photoelectron contains the arrival time and the
   the pixelnumber for a photoelectron. No distinction is made whether
   the photoelectron came from Cherenkov light or from the NSB.

   This array is filled with photoelectrons first by the new function
   
        int produce_phes( ... )

   and then (if simulateNSB == TRUE) by the second new function

        int produce_nsb_phes( ... )

   The filled array photoe[] can then be given to the trigger
   and FADC simulation. The time of the first phe and the time
   of the last phe is available in two float variables
   (arrtmin_ns, arrtmax_ns). 

   If the NSB simulation is switched on (simulateNSB == TRUE),
   arrtmin_ns and arrtmax_ns are modified such that
   there is at least SLICES*WIDTH_TIMESLICE simulated NSB. 
   In this way, the FADC simulation obtains realistic data.
   If the event is longer than the foreseen digitization time,
   the offset SIMTIMEOFFSET_NS is added such that there is
   some NSB before and after the Cherenkov information.

4) In order to prepare the NSB simulation (read the starfield,
   calculate rates etc.) a third new function had to be written:

        produce_nsbrates( ... )

   It is used before the start of the loop which reads the
   Cherenkov data. Internally it uses produce_phes(...) in
   order to turn the starfield file into photoelectrons.
   In this way, I made sure that exactly the same code is
   used to simulate the NSB response and the Cherenkov light
   response.

5) The function  produce_nsb_phes( ... ), mentioned above, 
   also produces the baseline shift voltage baseline_mv[]
   for each pixel. This is necessary for the Trigger and 
   FADC simulation.

6) All three functions produce_nsbrates( ... ), produce_phes( ... ),
   and produce_nsb_phes( ... ) are defined in camera.cxx .
   Since they cannot really be used anywhere else except in the
   camera simulation, it didn't make sense to put them in a 
   separate file.

7) The outputfile in ".phe" format was removed. People will in future
   use the ROOT output file or the data ASCII file. Careful: the
   ROOT raw data part - like the trigger - does not properly work in this
   version. Please wait until the next one.

   Correspondingly, the parameter output_file in the parameters
   file was removed. 

8) A new parameter was added to the parameters file:

       starfield_file

   The new version code of the camera parameter file is 0.3 !

9) The old parameters "nsb_mean" and "nsb_on/off" continue to
   control the NSB generation.
 
   nsb_mean contains the mean number of photoelectrons caused
     by diffuse NSB per ns for one of the central pixels (small
     pixels). The value is automatically scaled for the larger
     pixels.

   nsb_on switches the NSB generation on. 

   nsb_off switches it off. In this case, no starfield file
     is read.

10) The starfield file which is needed for the NSB generation, has
    to be produced using the present version of the reflector with
    input from the starfield generator.

    The integration time which is needed for the normalization of
    the non-diffuse NSB, is taken from the "primary energy" field
    of the MCeventheader of the starfield file! This is where the
    starfield generator puts it. If you take the input from reflector
    output not produced with starfield generator data, you will 
    have to take care of this.

11) The Cherenkov data is now read via a normal C-style filepointer.
    This makes it more easy to read from stdin and to reposition the
    filepointer. This is not a change in the reflector format.

12) The function read_pixels(...) was improved such that it notices if
    a faulty QE-file is given. The old version read a truncated QE file
    without complaining and used house-numbers for the QE as a result.

    The read QE table is now at least checked for completeness and if
    all values are inside the limits.

13) The pixelization is now done in produce_phes(...) and should be
    correct. 

14) The QE simulation is done in produce_phes(...) as well. In 
    order to save time, a linear interpolation was used instead of
    the Lagrangian. Additional safety checks were added. The new
    function lin_interpol(...) was created.

15) If you need to use this program for CT1, you have to
    produce a .def file which describes it. Most of the direct references to
    CT1 were removed. The rest will hopefully be tidied up soon.
    As a general program, camera should be able to simulate any
    CT if the right .def file is given.


Probably I have forgotten something. But I think these are the main points.
The program contains some debugging "couts" which are commented out. They
can be deleted soon.