STAF - Physics Analysis Modules

  The term ``Physics Analysis Module'' is used in STAF to refer to the user written frunctions in C, C++ or Fortran 77 which do detector response simulation, event reconstruction, calibration, Monte Carlo evaluation, trigger simulation and post-DST physics analysis. Each software package in the STAR Library may contain 0, 1, 2 or more PAMs.

The PAMs must conform to an interface standard which will be explained and illustrated by example in the following tutorials. The PAM interface includes the list of tables which are used (input, output or update) by the module. In addition the module, which is defined as an integer function, returns a STAF condition value indicating to STAF the success or failure of the module's execution.

The information which the user provides in order to interface a module to STAF is contained in an Interface Definition Language (IDL) file. Remember there are two IDL file types (i.e. for modules and tables). The module idl file type defines which table types are input and output from a given module. The tool used for interfacing analysis modules in STAF is the STAR IDL Compiler (Stic). Stic produces glue code. Stic also generates template files in both C and Fortran for the analysis modules in the package, making it quite easy for the user to get started, even if he or she is totally unfamiliar with the STAF programming interface.

PAMs are linked to STAF package-by-package rather than individually. In other words, when building a SL97b STAF executable, the user selects package libraries to link, not the individual PAMs. The PAMs may require tables which belong to other packages. Likewise, a given table might be defined in one package but used by a module in a different package. At run time, however, PAMs are called individually using the AMI ASP via the ami/module/call STAF command. Some PAMs might be linked in the STAF executable but do not have to be called at run time.

Example Physics Analysis Modules and IDL files are available in Fortran, C and C++.

PAMs are named according to the STAF callable function name in the module definition. For Fortran modules the function name is defined in the statement:

Integer Function PAM_function_name(table1_h, table1, ...)

and in C modules by,

long PAM_function_name_(

     TABLE_HEAD_ST     *table1_h, PKG_typename_ST *table1 , ...)

The source codes are saved as UNIX files in the PKG/src subdirectory and are named:

     PAM_function_name.F     for Fortran,

     PAM_function_name.c     for C, and

     PAM_function_name.cc    for C++.

The PAM idl files for SL97b are placed in the PKG/src subdirectory. They are named PAM_function_name.idl and contain an interface statement,

interface PAM_function_name : amiModule {...};

which refers to the STAF callable function name. At run time the STAF command

ami/module/call PAM_function_name table1 table2 ...

invokes the named PAM and provides the list of current table instance names as arguments, where the table order is critical. In SL97b all the preceding reference names for a PAM and the associated files have the same root name.

Referring to the example PAM idl file tpt.idl note that the structure and syntax of the idl file is independent of the programming language. The essential elements of the PAM idl file are:

• Comments and description setoff by `/* ... */'
• #include statements - PAM.idl is required in order that the module gain access to system variables such as the STAF condition value parameters; all necessary table type idl files must also be listed.
• The interface statement giving the module function name and listing the tables in the module's argument list in the order listed in the STAF callable function definition statement. The information listed for each table is the I/O status (in, out, or inout), the table type name, and the local table name used internally in the module.

Table header and variable definitions are passed to the PAMs via the argument list in the function declaration statement. References to the table header and variables inside the PAM are to the local table names as defined in the function declaration statement. In Fortran modules the table variables are referred to as (exactly like Fortran STRUCTURES):

local_table_name(i).variable_name

where i = 1,2,... is the table row number, and in C/C++ codes as

local_table_name[i].variable_name

where i = 0,1,... is the table row number. From the KUIP command line table variables are referred to as

table_instance_name[i].variable_name

where i = 0,1,... For all cases tables with only 1 row must be referred to as

table(1).variable_name in Fortran modules

table[0].variable_name in C/C++ codes and KUIP commands.

Table attributes (i.e. maximum number of rows and number of rows used) are referred to in PAMs as:

local_table_name_h.maxlen in Fortran and C (read only)

local_table_name_h.nok in Fortran and C

local_table_name_h->nok in C++

Several useful STAF PAM programming guides are available:

• Fortran 77 and C analysis module Templates generated by Stic from specific PAM.idl files. The salient features of these templates include the (1) documentation header, (2) the STAF callable function declaration statement, (3) required #include statements, (4) variable type declarations, (5) an example of how to return the STAF condition value, and (6) some trivial, example lines of code. These templates can be generated from the PAM.idl file by typing `stic PAM.idl' at the UNIX prompt in the PKG/src subdirectory.
• STAR Coding Style Manual for Fortran 77, C and C++ analysis modules in STAF. This version was revised in Sept. 1996 and specifies the current, adopted coding standards for offline STAR software. The manual attempts to spell out the agreed upon style for code which is to be contributed to the STAR software library. It consists mostly of encouragement to use good coding practices for ease of code readability, maintenance and compilability on different machines. The reasons for the coding rules are given along with each rule. The accepted programming languages are FORTRAN 77 (with VAX extensions), C and C++ (preferred). FORTRAN 77 with VAX extensions are acceptable except for the prohibitions listed in this manual. Fortran90 is not an accepted language in STAR. Sample code templates are also provided in this manual but are incomplete. Please use the Stic generated templates instead.
• The STAR Coding Style Checker is a SOFI tool which provides automated checking of Fortran 77 and C analysis modules for compliance with the STAR Coding Style Manual rules. It issues error messages and warnings. Compliance with these standards is voluntary so far. Documentation is available HERE or explicitly at the URL:

  
  

           http://www.rhic.bnl.gov/STAR/html/ssd_l/cds_l/cds_usage.html
  
  
  

  or by following the path from the STAR Home page, to Computing, to Offline Software, to Offline Software Packages - SYS, to cds, and finally to Usage.

• Useful tips and important rules for proper initialization of analysis modules and for correct usage of the STAF table keys is given HERE or at the URL:

  
  

    http://www.rhic.bnl.gov/STAR/html/sofi_l/info/margetis/key-usage.html
  
  
  

  or by following the path from the STAR Home page, to Computing, to Offline Software, and to Design and Development - ``Rules and tools for PAM Intialization and Foreign Key Usage.''