The DIRAC Offline User Guide

Daniel Drijard and Michel Hansroul
<CERN>
Valery Yazkov
<DUBNA>
April 2000
 
 

Table of Contents

 

Introduction

Table of Contents

This guide describes the structure of the offline DIRAC reconstruction program (called Ariane) and the instuctions to build an executable module. The user interface to the program is also fully documented.

As this is a document in constant evolution, the user is welcomed to send comments and suggestions; please Email at
michel.hansroul@cern.ch.

The latest version can be obtained from the DIRAC Web page http://www.cern.ch/DIRAC/.
 

Programming language, libraries and tools

Table of Contents

The FORTRAN language is used for almost all of the present code, with the exception of a few C functions used for reading and writing data records.

Except for a few instructions (e.g. cycle, exit ...) the code is written in the FORTRAN 77 language in order to guarantee the portability to various platforms. In addition, the usage of the CERN library code maintenance package PATCHY requires a limitation of the line lengths to 72 characters only (this restriction is no longer valid for the latest version of PATCHY but remains for certain compilers).

The program uses various utilities and packages of the CERN library, such as FFREAD, HBOOK, HEPDB, ZEBRA. These are usually available for a large variety of platforms.

Presently, the code maintenance is done with the PATCHY system (version 5) which is available in the CERN library. As PATCHY was not implemented on MacIntosh, a version of PATCHY with a reduced set of functionalities has been written by D.Drijard for that machine. However, the standard version of PATCHY has by now (April 2000) also been implemented on Macs as well as most of the CERN library.

Code present status and location

Table of Contents

The program has been developped and implemented on the UNIX, LINUX and the Mac OS systems.

The functionalities provided are the following:

  1. geometry and calibration data decoding
  2. data records reading from disk
  3. storing of data blocks
  4. decoding and storing of decoded data blocks
  5. track reconstruction
  6. encoding of data and writing of output records
  7. display of detectors, data and reconstructed tracks (package provided by Jean-Louis Narjoux)

It is expected that the groups in charge of the detectors will provide the appropriate code to be inserted in the program.

The source code (in the form of a "car" file for PATCHY), the libraries, the executable module, test events and scripts are located in the following directory on the CERN AFS system:

/afs/cern.ch/user/d/diracoff/public/offline/ariane

An explanation of the various sub-directories and their contents is given in the file AREADME which the user is invited to consult for the latest information. Below follows a brief summary of the directories structure:

"ariane" directory

For the MacIntosh version, contact
Daniel.Drijard@cern.ch.

Program structure

Table of Contents

As required by the PATCHY maintenance tool, the code is stored in what is called a PAM or CAR file, from which PATCHY will extract the C or FORTRAN code to be compiled and linked with appropriate libraries. The extraction of the code follows instructions contained in a CRADLE file to be provided by the user, an example of which being included in the "buildlib" script described in a later section.
REMARK: For users familiar with CMZ (interactive code maintenance system), the CAR file can also be read by CMZ, thus providing the CMZ tools to perform various tasks as needed.

The CAR file is divided into "PATCHES", each containing a set of "DECKS" which themselves consist of subroutines or functions. The patches CDES, CDEDATABASE and TRCDES are special and consist of KEEP sequences whose contents are the common blocks or parameters definitions; these sequences are referred to in the subroutines or functions whenever needed. In addition, one can define flags which may be used to select pieces of code specific to different platforms.

A full description of the functionalities of PATCHY can be obtained from the CERN library; however, later in this guide, examples of usage of PATCHY will be given for the convenience of users not wanting to invest much time in getting familiar with the PATCHY system.

General code organisation

Table of Contents

The following patches are presently defined in the CAR file:

The usage of the selection flags will be explained in the examples in a later section. They are:  

Main job phases

Table of Contents

The principal tasks, identified by a "job phase level", performed by the program are outlined below:

The number of presently predefined job phase levels (variable 'LevelJob' in the code) is expected to increase in the future as new processors will be included in the program.

The tasks to be performed are steered within the main program, called 'DiracB' and 'DiracI' for the batch and interactive versions, respectively. A simplified listing of 'DiracB' is given below. 

Program DiracB
c
c------------- Initialisation ---------------

call InitPhase(JobInitialisation)
call DateAndTime
call Initialisation
call InitPackages
call ffset
call InitFFKeys
call ffgo
call SetupJob
call UserAction
call SetupPrint

c----- begin Event loop ---------------------

    call InitPhase(jobInputReading)
    call FetchEvent
    call UserAction

c------------- Event decoding ---------------

    call InitPhase(jobBlocksDecoding)
    call DecodeAll
    call GetMeasFromData
    call FilterAllMeas
    call UserAction

c------------- Event processing ---------------

    call InitPhase(jobEventProcessing)
    call Processing
    call UserAction

c------------- Event output ---------------

    call InitPhase(jobOutputWriting)
    call PutEvent
    call UserAction

c------------- Event wrap up actions ---------------

    call InitPhase(jobEventEnding)
    call FillHistograms
    call EventPrint (LevelJob)
    call UserAction

c----- finish Event loop ---------------------------

c------------- End of operations ---------------

call InitPhase(JobTerminating)
call UserAction
call EndOfJob
END

Initialisation

Table of Contents

The main program successively calls a series of subroutines as indicated in the following flow chart:

Event loop

Table of Contents

The event loop flow chart is shown below for the successive phases of actions:

 Event blocks decoding level 6  Event processing level 7  Event output level 8  Event ending level 9

Job Termination

Table of Contents

List of subroutines

Table of Contents

Here follows the list of decks for each patch in the CAR file:

  1. Patch DiracMain
    2.  
  2. Patch USERTEST
    3.  
  3. Patch USERCODE
    4.  
  4. Patch INIT
    5.  
  5. Patch GENERAL
    6.  
  6. Patch DECODING

    7. click here for a full description
     
  7. Patch INOUT
    8.  
  8. Patch PRINTING
    9.  
  9. Patch TITLES
    10.  
  10. Patch UTIL
    11.  
  11. Patch UTILHP
    12.  
  12. Patch CUtils
    13.  
  13. Patch MONTECARLO
    14.  
  14. Patch TitlesData

    15. This patch contains the "Detector.Data" file defining the detector geometry, some calibration data and various other constants needed by the decoding and reconstruction procedures.

List of common blocks

Table of Contents

 The description of the common blocks can be found in the following links:
In patch CDES click here
In patch TRCDES click here

User interface

Table of Contents

The user has the possiblity to interact with the program through a set of directives controlling the job conditions and by means of a user routine which is called at each predefined job phase.

Job directives with FFREAD package

Table of Contents

 FFREAD provides a facility for input of format free data. It is a tool suitable to transmit or modify variables at run time without recompilation.

The variables to be set by FFREAD must reside in common blocks and to each variable or set of variables (for arrays) the system associates a key, its location, its length and type. All this being defined at initialisation time, the directives are read by FFREAD which sets or modifies the variables in memory accordingly.

A full description of FFREAD can be consulted at
http://consult.cern.ch/writeups/ffread/ffread.html.

 

User subroutines

Table of Contents

 

The interaction of the user with the flow of tasks performed by the program has been implemented by means of a subroutine called "UserAction". This routine is normally empty, but when needed the user has the possibility of writing, for the job levels desired, his own special code as is outlined in the next section.



Debug printing

Table of Contents


Input and output files

Table of Contents

Data formats

A FILE is made of RECORDS that are made of EVENTS, which in turn are made of BLOCKS. The following gives an explicit definition of these entities.

In a disk file, all bits are contiguous, without hardware record markers in between, as would be the case for standard binary FORTRAN files. The records mentioned here are only software concepts that are written/read by C-routines (or FORTRAN on Macintosh).
The order of bytes in a word is the same as that (network byte order) used on the HP, RS6000(AIX) and Mac machines.
However, other machines having a different byte order in a computer word such as PC(Linux) and Alpha machines, require byte swapping in order to write/read those data, this operation being taken care of by the program.

On tape, a hardware structure is superimposed, but we need not worry about it provided we properly use the stageout/stagein commands.

A record has a variable length and holds many events but no event is split across successive records.

An event consists of different blocks , starting with an Offset-block followed by a "general" Event-block and one or several data blocks. Each block starts with a packed word that holds its size and type (identifier).
A graphical representation of an event is stored in the postscript file event_format.ps
A run is defined as a collection of events starting by a record with a single event that has a Run-block.

A PS burst (1,2 or maybe 3 in a supercycle of 14.4 seconds or so) is sandwiched between a Start-Of-Burst and an End-Of-Burst block.

On raw-data (on-line) there are further constraints: On processed-data files these restrictions are removed.

The word "event" is unfortunately used with three different meanings. In the previous paragraph, it means an element of record (a set of blocks) and an other meaning is in the special block called EVENT-block. To avoid the confusion this block is called 'General' in Ariane. The third meaning, the most natural one, is that of a set of measurements representing an interaction. Again to avoid confusion Ariane uses (in principle) DataEvt in this case.

Words quoted here are 32-bit long. When relevant, packing is defined as [a/b] for two 16-bit and [a/b/c/d] for four 8-bit components. For example the word [Version/Size] means that "Version" is in the 16 most significant bits and "Size" in the 16 least significant ones. Size means the number of words, in 32-bit units, following this word, i.e. it does not include itself in the count.
RECORD
EVENT
BLOCK
OFFSET-block
general EVENT-block

The Trigger bit-pattern (in the Event-block) describes the trigger:
The detailed contents of the other blocks are described elsewhere.

Numbering of blocks (Type)

100 .. 199 General purpose
100 Offset
101 Event Information
102 Run block : the graphical description of this block can be found here.
This block contains sub-blocks called: Run Status, Detector list, Fera list
103 Start Of Burst
104 End Of Burst
105 Monitor
106 Tuning
107 Memory
199 Offline
200 .... 299 MSGC
201 MSGC-1
202 MSGC-2
203 MSGC-3
300 .... 399 SciFi
400 .... 499 dEdX
500 .... 599 Drift Chambers
500 DC-0
501 DC-1
502 DC-2
600 .... 699 Vertical Hodoscopes
700 .... 799 Horizontal Hodoscopes
800 .... 699 Cherenkov
900 .... 999 Pre-Shower
1000 .. 1099 Muon Counter
1100 .. 1199 DUMMY (now TDC of DNA)
2000 .. 2099 Processed data
2100 .. 2199 Monte Carlo
Apart from the General purpose blocks, 100 values are reserved for the type of each block in order to allow future variations of the format if needed.
In case a severe event selection is applied during off-line analysis, some bursts may be left empty, and possibly some runs empty. We will have to keep the relevant information, such as the integrated live-time, but it would be space consuming to keep all Run-block, Start-Of-Burst and End-Of-Burst blocks. Instead we might have to create a special Summary-block.

Scripts for building an executable module

Table of Contents

 The scripts listed below are for the UNIX system and should be adapted for other systems. They have been tested for the following platforms(systems): HP-UX, AIX, Alpha(OSF1), Linux.

1.Installation of the offline "Ariane" software

In order to install the "Ariane" program, the user should follow the steps below:
First, set up a directory structure similar to the structure implemented on the DIRAC AFS account in the directory:
"/afs/cern.ch/user/d/diracww/public/offline/"

The directory structure is represented as follows:
Then, follow the steps below: The detailed description and usage of the installation scripts is explained in the following sections. In addition, each script contains a summary of its functionalities and options which can be displayed on line by typing a command such as "buildlib -h" and similarly for the other scripts.

2. Build the library

click here for the listing
For example, on the AIX system, the command "buildlib -nd ariane113" will produce the library "ariane113.a" in the directory lib/aix obtained from the compilation of all subroutines contained in the directory src/aix/ariane113.fdir.

2. Build the graphics library

click here for the listing
For example, on the AIX system, the command "buildgraf -n graf" will produce the library "graf.a" in the directory lib/aix obtained from the compilation of all subroutines contained in the directory src/aix/graf.fdir.

3. Build the main program

click here for the listing
For example, the command "buildmain -nd ariane113" will produce the object file diracb.o ("b" for batch) in the directory exe/aix.
The interactive version including the graphics functionalities could be obtained with the command "buildmain -nig ariane113" which will produce the object file diraci.o ('i' for interactive) in the directory exe/aix.

4. Link and Build the executable module

click here for the listing
For example, the command "buildexe -n ariane113" will create the executable module "ariane113.exe" in the directory exe/aix using the (batch) main program, the library created in the previous commands and the CERN library.
Similarly, tje command "buildexe -nig ariane113" creates the executable module "ariane113.exe" in the directory exe/aix using the (interactive) main program, the ariane and graf libraries created previously and the CERN library, including graphics.

5. Extract the detector geometry

click here for the listing
For example, the command "extractDetector -n ariane113   det113" will create the file "det113.dat" in the directory from which the above command is launched.

Job example

Table of Contents

 The directory "/afs/cern.ch/user/d/diracww/public/offline/ariane/dev/demo" contains an example of input directives in the file "FFreadInput", the link "aixgo113" to the executable module and the output text file "aix113out" produced when the command "aixgo113 > aix113out" is typed on the terminal keyboard.

The directory "/afs/cern.ch/user/d/diracww/public/offline/ariane/events" contains a test sample of events from run 450 in the file "450.e1to500" which can be transferred as appropriate.

Appendices

Table of Contents
  1. Coordinates systems
    2. click here
  2. Detector File format
    3. click here
  3. Monte Carlo block format
    4. click here
  4. Detector Data File
    5. click here
  5. Some semantic considerations
    6. click here