An introduction to the FINUDA
Monte Carlo and Reconstruction Programs
(responsible: A. Filippi)
Index
  1. Introduction
  2. Installation
  3. Compiling and linking
  4. Running
  5. Running inputs
  6. Running outputs
  7. Download
  8. Code Development Policy
  9. Correction Cradles & Test Macros
  10. Work in Progress and Achievements (link to fog_work page)
  11. FINUDA Offline Journal

1. Introduction

The FINUDA Monte Carlo and Off-line Reconstruction programs are stored in a CMZ format. In order to be able to install them on your machine you must have  installed first (see wwwcmz.web.cern.ch/wwwcmz/ for more information about CMZ or print this quick postscript CMZ guide ). Please read the CMZ manual to learn about CMZ commands.
The Monte Carlo program simulates the entire detector and can be used to generate physics processes to study the response of the full apparatus.
The reconstruction program allows the events of the experiment both from the Monte Carlo and from the Raw data to be reconstructed. The reconstruction program can also be run interactively along with an event display. To see some of the history of the software development, download the following PDF files: Bari_1.pdf and Bari_2.pdf .

2. Installation

After you downloaded * the latest versions of the programs, the files geane321.cmz and geang321.cmz, you can install them with the commands:

These commands install both the Monte Carlo and the Reconstruction Program.
Here "321" refers to the GEANT version used, 3.21, and "pro" should be defined as a link in the /cern/ directory which points to the latest cern library release (at present, pro -> 2000). The CERN library must therefore be in /cern/pro/lib/
The programs have been tested successfully on Alpha Digital Unix 4.0E, Linux RedHat 6.0 Unix, and VMS (to be abandoned).
The following subdirectory tree will be created starting from the directory where you copied the 2 CMZ files:
 
        off        
geant inputs outputs histos rdtapes dstapes scratch share work
           
batch inter
   

The installation procedure also compiles and links the Monte Carlo program. The executable is ready for the first run that MUST be performed to create the geometry file needed by the reconstruction program. For further information check the Running and the Running inputs sections.

* To download a particular CMZ file, go to the Download section, point your mouse above the file you want, click your right mouse button and use the "Save link as" option

** Versions 3.02 and higher are capable of reconstructing real data (raw data). In order to do that you should install mSQL and the Finuda on-line database first. You must then define the symbol MSQLDIR to point to the directory where you installed  .
 

3. Compiling and linking

All the compile and link commands must be executed inside the CMZ environment. First of all you should go to the subdirectory work:

After you entered the CMZ environment (with the simple cmz command at your computer prompt) there are specific commands to compile and link the Monte Carlo and the Reconstruction Program. Here is a table of such commands along with the name of the executables created and the directory where they are placed:
 
Program CMZ command Executable name Executable directory
Monte Carlo exec rebuild fidamc batch
Interactive Monte Carlo exec rebuild_int fidamc inter
Reconstruction exec rebuild_rc fidarc batch
Interactive Reconstruction exec rebuild_rc_int fidarc inter

* The compiling has been tested with fort77 (interface for f2c) on a Linux system and with f77 on a Alpha Unix system.

Note:


4. Running

To run a program you must exit from the CMZ environment (with the command exit) and type commands from your computer prompt.
Before running a program you should set some logicals/environments. In the directory work use the following command:

* In Unix systems there are many shells. In order to allow the file to set correctly your environments you should work in the csh or tcsh shell.

These are the logical/environment settings:
 

logical/environment value 
TOP  directory where you installed the programs
OWN  off directory 
WRK  work directory 
SCB  batch directory 
SCI  inter directory 
SHR  share directory
INP  inputs directory
RDT  rdtapes directory
OUT  outputs directory
DST  outputs directory
HIS  outputs directory

You can use them interactively to move around in the directory tree, to see the listing of a directory, to edit or run a program. Just a few examples:

After calling the logical/environment settings you can run the programs with the following commands:
 
Program VMS command Unix command
Monte Carlo run/nodeb SCB:fidamc $SCB/fidamc
Interactive Monte Carlo run/nodeb SCI:fidamc $SCI/fidamc
Reconstruction run/nodeb SCB:fidarc $SCB/fidarc
Interactive Reconstruction run/nodeb SCI:fidarc $SCI/fidarc

Notes:

  1. In order to run the reconstruction program correctly you MUST run the Monte Carlo first to create the geometry file needed (see Running inputs for more details).

    2.  
  2. In order to run the reconstruction program on a Monte Carlo output you MUST reenter the CMZ environment, type the command sel mcarlo and recompile and relink the reconstruction program with the following commands:
5. Running inputs

The input files for the Monte Carlo and the reconstruction programs are stored in the directory inputs and are called fidamc.dat and fidarc.dat respectively. They control the running settings of the 2 programs and can be modified by the user according to his/her wish.
The Monte Carlo MUST be run at least once to generate the geometry file needed by the reconstruction program. To do that the MC input file must be modified properly (see the fidamc.dat example file). If the FIGEOM flag is on, the Monte Carlo creates the geometry file. If the flag is off (C FIGEOM) then the Monte Carlo doesn't create the geometry file. Once the geometry file is created (in the share directory), there is no need to redo this unless the geometry of the detector is changed inside the code. The FIGEOM flag should then be commented out and the DIGIT flag should be set for event digitization, as explained below.
 

6. Running outputs

The 2 programs generate some output files. Here's a table of the output file names, directories and comments:
 

Monte Carlo output file name directory comment
fidamc_his.rzf histos zebra ntuple file
fidamc_out.lis outputs log file
fida_geo.dat share geometry file for the reconstruction program *
runXXXXX_rdt.dat rdtapes events file for the reconstruction program **

* Only if the FIGEOM flag has been set in the fidamc.dat file.
** Only if the DIGIT flag has been set in the fidamc.dat file.
 

Reconstruction output file name directory comment
runXXXXX_his.rzf histos zebra ntuple file
runXXXXX_out.lis outputs log file
run00001_dst.dat dstapes dst file

 

7. Download

Download the following 2 geant cmz files:

geang321.cmz

geane321.cmz (---> "new geane" as of august 2008 <---).
For the records you can find the old version here geane321-2002-2008.cmz (DO NOT USE IT FOR PRODUCTION ... IT IS HERE JUST TO ARCHIVE IT).

IMPORTANT!!! download the correct geant321.cmz file and copy it in your $CERN/src/cmz directory (if the directory is not present, create it on purpose to host the correct file). The file must be copied prior to installation. It contains corrections to help alignment of geant include files with the geant library for cernlib versions later than 2002. Needed to expand GCKING common and transport in the code information on Montecarlo tracks.

geant321.cmz

the magnetic field map file field.map (to be placed in the top installation directory with all the cmz files) and the latest version of the Monte Carlo and Reconstruction programs:
 

Version Monte Carlo Reconstruction Release notes
6.05/04 (11/12/08) fidamc60504.cmz * fidarc60504.cmz + field.map v.605/04 release notes 
6.05/01 (28/04/08) fidamc60501.cmz * fidarc60501.cmz + field.map v.605/01 release notes 
6.05/00 (24/04/08) fidamc605.cmz * fidarc605.cmz + field.map v.605/00 release notes 
6.04/03 (06/12/07) fidamc60403.cmz * fidarc60403.cmz + field.map v.604/03 release notes 
6.04/01 (19/10/07) fidamc60401.cmz * fidarc60401.cmz + field.map v.604/01 release notes 
6.04/00 (26/09/07) fidamc604.cmz * fidarc604.cmz + field.map v.604 release notes 
6.03/00 (08/08/07) fidamc603.cmz * fidarc603.cmz + field.map v.603 release notes 
6.02/00 (24/04/07) fidamc602.cmz * fidarc602.cmz + field.map v.602 release notes 
6.01/00 (18/01/07) fidamc601.cmz * fidarc601.cmz + field.map v.601 release notes 
6.00/00 (07/12/06) fidamc600.cmz * fidarc600.cmz + field.map v.600 release notes 
5.21/00 (13/10/06) fidamc521.cmz * fidarc521.cmz + field.map v.521 release notes 
5.20/00 (27/07/06) fidamc520.cmz * fidarc520.cmz + field.map v.520 release notes 

IMPORTANT




* All versions assume the CERN library to be in the directory /cern/pro/lib .
For the Linux Operating System, the program is automatically compiled with g77 to allow the use of the gdb debugger and of the graphical interface DDD .
Versions 4.00 and higher have been tested for Linux RedHat 6.0 and 6.1, Digital UNIX 4.0E and VMS. For Linux systems, additional debugging tools are automatically included and compiled for the gdb debugger. After entering gdb (or DDD), the user should load a few definitions from the file exam.gdb (by typing "source exam.gdb") which allow examination of COMMON and EQUIVALENCE variables. A list of these commands is obtained by typing "help user-defined". There is a help menu available for each of them.
When one runs version 4.05 (either the Monte Carlo or the reconstruction), the program prints out "version 4.04". The version is 4.05 regardless of this printout. This bug has been fixed in 4.06.
 

8. Code Development Policy

Since the code will be developed in parallel by several users, a well coordinated effort is essential. In order to participate in the development of the FINUDA off-line code, please observe the following rules:
 

  1. Coordinate your effort with the FINUDA off-line software group. You can send mail to this group using the following mailing list: Finuda.Offline@lnf.infn.it
  2. Get the latest official release from this site.
  3. Use * correction cradles provided below if you want to.
  4. Produce your own cradles always with respect to the unmodified latest release. Other users can then use your cradles without updating or modifying the cmz files.
  5. Send your cradles to Germano Bonomi ) and to the software group coordinator (Alessandra Filippi Once the different cradles have been introduced and certified by the software master and coordinator, a new version will eventually be released.
* Do not update your code. Simply load the correction cradles in the use bank and rebuild your programs. This will ensure that correction cradles from all users are with respect to the unmodified latest released version of the code.
 

9. Correction Cradles & Test Macros

Subsequent code development will be incorporated through correction cradles as outlined above. Certified cradles will appear on the following table: 
Cradle Date Author Comments
  filippi_generatori_tgt_06.cra   (v. 5.20)
 15/09/06  A. Filippi
 Generators for the 2006 targets

To test the reconstruction code the following macro may be useful. They are simply templates to help the users to test their code looking to "standard" numbers and plots. If you want to contribute to this list please send your macros to the the offline responsible A. Filippi and G. Bonomi:

Macro Date Author Comments
  toRoot.C
 09/06/05  G. Bonomi
 to translate from .rzf to .root
  merge.C
 09/06/05  G. Bonomi
 to merge many runs (ntuple 127)
  hypeMerge.C
 09/06/05  G. Bonomi
 to merge many runs (ntuple 126)
  testEff.C
 09/06/05  G. Bonomi
 to count K-, K+ stops and mu+
  testMom.C
 09/06/05  G. Bonomi
 to check mu+ momentum distributions
  hype.C
 long time ago A. Zenoni to produce "standard" plots


IMPORTANT

* In order for the Monte Carlo to compile correctly using the cradles above, one needs to modify by hand the file rebuild.kumac, by adding the line
ccompile $USE
right after the line
ccompile -b.
Otherwise, the new geometry routine ugetof2 is not automatically included. 


Please send any comment or question 
to the FINUDA Software Master
Dr. A. Filippi 		 Web master  
Germano Bonomi 		Last update 
15-Feb-2007