MAKING NTUPLES IN IDA

INTRODUCTION

It is possible to make PAW/HBOOK-style ntuples directly in IDA (on VMS) and write them to a file for external processing by PAW. This is implemented as a command processor, NTUPLCMD, which responds to IDA commands of the form

IDA> NTUPLE command parameter-list.

With the NTUPLE command you can make row-wise ntuples and fixed and variable column-wise ntuples. For full details on these ntuple concepts see the CERN HBOOK manual.

HOW TO MAKE NTUPLES

Making ntuples is a two part process. First, the ntuple itself has to be defined in the form of a Jazelle bank template. Then, in IDA, code is executed which fills the bank and then transfers the bank contents into the ntuple. The IDA interface has been implemented in two forms, a simple (EZ) form with lots of automatic defaults and a full form that allows the user to get most of the functionality available in direct HBOOK ntuple making fortran routines.

EZ example

Here is the definition of a Jazelle bank which would go in a file called CWATEST.TEMPLATE;

BANK CWATEST  CONTEXT = TEST  MAXID = 1
   INTEGER NTOT                        
   REAL ENERGY
   REAL IP(3)
ENDBANK

Here is the IDA code to make a five element column-wise ntuple consisting of an integer*4, NTOT, for the number of final state particles, a real*4, ENERGY, for the total energy of final state particles in the event and a fixed array, IP(3), of three real*4 for the x,y and z IP position of the event.

OPEN READ GENERATE   
CMDPROC NTUPLCMD                 
PROCESSOR MCL74

CWATEST = _CWATEST(ADD)           ! tell IDA about the template.

NTUPLE EZcw "$scr:[grb]" CWATEST  ! define the cw-ntuple based on
                                  ! CWATEST and write it to directory
                                  ! $scr:[grb].

DEF EVANAL
   CALL MCL74
   J = 0
   CWATEST%(ENERGY) = 0
   BANKLOOP MCPART
      IF ^BTEST(MCPART%(ORIGIN),P%(MCPART,DECAYED)) & -   
         ^BTEST(MCPART%(ORIGIN),P%(MCPART,PREFRAG))
        J = J + 1
        CWATEST%(ENERGY) = CWATEST%(ENERGY) + MCPART%(E)
      ENDIF
   ENDLOOP
   CWATEST%(NTOT) = J
   DO I = 1 TO 3
      CWATEST%(IP(I)) = _MCHEAD%(IP(I))
   ENDDO
   NTUPLE EZfill                  ! fill the ntuple from the bank.
ENDDEF                
           
GO 200
                                 
NTUPLE EZend                      ! write the ntuple to disk at
                                  ! $scr:[grb]cwatest.rzdat.

Making other kinds of ntuples

The CERN PAW/HBOOK ntuple concept also includes row-wise ntuples and variable column-wise ntuples and both these types are implemented with the NTUPLE command. Again, for details see the HBOOK manual. The template for a row-wise ntuple consists simply of a list of single (ie, no arrarys) real*4 variables. The template for a variable column-wise ntuple requires a little more explanation.

The typical application for a variable ntuple would be properties of particles in an event where what varies is the number of particles per event. An example template definition would be

BANK CWVTEST  CONTEXT = TEST  MAXID = 1
  INTEGER NPARTS
  REAL PX(300)
  REAL PY(300)
  REAL PZ(300)
  REAL E(300)
ENDBANK

The first item in the bank is an integer element, NPARTS, which is the variable. All the other elements are arrays of the same fixed size which is the maximum value the variable element, NPARTS, can take. In this example, NPARTS is the number of final state particles per event and we are assuming that the largest value it will ever reach is no more than 300.

For each event in the event loop NPARTS will be set to the number of final state particles particles and the first NPARTS members of each array will be filled with values for each final state particle in the event. When the bank is read out every event into the ntuple only the first NPARTS elements in each array are kept thus producing a variable length ntuple. Sample code would be:

OPEN READ GENERATE   
CMDPROC NTUPLCMD                 
PROCESSOR MCL74

CWVTEST = _CWVTEST(ADD)
NTUPLE EZcwV "$scr:[grb]" CWVTEST    ! NOTE: the NTUPLE command is EZCWV.

DEF EVANAL
   CALL MCL74
   J = 0
   BANKLOOP MCPART                                  
      IF ^BTEST(MCPART%(ORIGIN),P%(MCPART,DECAYED)) & -   
         ^BTEST(MCPART%(ORIGIN),P%(MCPART,PREFRAG))
        J = J + 1
        CWVTEST%(E(J)) = MCPART%(E)
        CWVTEST%(PX(J)) = MCPART%(P(1))
        CWVTEST%(PY(J)) = MCPART%(P(2))
        CWVTEST%(PZ(J)) = MCPART%(P(3))
      ENDIF
   ENDLOOP
   CWVTEST%(NPARTS) = J
   NTUPLE EZfill
ENDDEF                
           
GO 200

NTUPLE EZend

OTHER USEFUL INFORMATION

ALLOWED ELEMENT TYPES

For row-wise ntuples the only allowed element type is REAL*4. For fixed column-wise ntuples allowed types are LOGICAL, INTEGER*4, REAL*4, and REAL*8. For variable column-wise ntuples the same types are allowed but special considerations must be made in constructing the jazelle template if REAL*8 arrays are included (see Gary for help.)

ERROR CONDITIONS

In addition to the usual IDA errors you will be notified with the NOBANK error if you try to define an ntuple without first defining to IDA the jazelle template with the ADD operation.

The error message INCONAR means you are attempting to create a variable column-wise ntuple and not all of your arrays are of the same length.

If you get the error NOKEY it probably means you have not given enough parameters to the last NTUPLE command.

You may get the error message that you have run out of free contexts. This is probably because you have made several syntax errors in issuing NTUPLE commands or some other IDA command processor commands. The system eats up a limited resource when this happens and you need to start a new IDA session.

USAGE TIPS

If you decide to change your template and ADD it again and have already done an HROPEN or EZCW, etc you should probably do an HREND or EZEND or things will get mixed up.

IMPLEMENTATION INFORMATION

The gist of how it works is the Jazelle bank is a defined piece of COMMON where the data is placed. Then fortran calls to HBOOK routines that create ntuples are made. These HBOOK routines expect to be told where the data is with the address of some COMMON storage area. The rest is grungy details.

FULL NTUPLE COMMAND SYNTAX and EXAMPLE USAGE

What follows is a series of examples using all of the available NTUPLE commands. In IDA you can do HELP to get the details of the commands and their syntax.

Note that the command sequences and arguments for creating row_wise ntuples using the Hxxx type of NTUPLE commands is somewhat different than that for column-wise ntuples. This is a reflection of the differences in the underlying calls to HBOOK for the two types of ntuples. To fully understand the meaning of the Hxxx type commands one should consult the HBOOK manual. The command names used by NTUPLE are virtually identical to those of HBOOK and the reader should have no trouble making the correlations.

!
!!! Row-wise examples
!!
!! The template                         
BANK RWTEST  CONTEXT = TEST  MAXID = 1
   REAL ENERGY
   REAL NPARTS                        
   REAL IPX
   REAL IPY
   REAL IPZ
ENDBANK
!!
!! EZrw example
!!
CMDPROC NTUPLCMD
 
OPEN READ GENERATE   
RWTEST = _RWTEST(ADD)
 
NTUPLE EZrw "$scr:[grb]" rwtest
PROCESSOR MCL74
 
DEF EVANAL
   CALL MCL74
   RWTEST%(NPARTS) = _MCHEAD%(NTOT)
   RWTEST%(IPX) = _MCHEAD%(IP(1))
   RWTEST%(IPY) = _MCHEAD%(IP(2))
   RWTEST%(IPZ) = _MCHEAD%(IP(3))
   RWTEST%(ENERGY) = 0
   BANKLOOP MCPART
      RWTEST%(ENERGY) = RWTEST%(ENERGY) + MCPART%(E)
   ENDLOOP
   NTUPLE EZfill 
ENDDEF                
           
GO 500
 
NTUPLE EZend                 
!!
!! Full syntax RW example
!!
CMDPROC NTUPLCMD
 
OPEN READ GENERATE   
RWTEST = _RWTEST(ADD)
 
NTUPLE Hlimit 500000
NTUPLE Hropen RWSAMPLE "$SCR:[GRB]MYRW.RZDAT" NQX 1024
NTUPLE Hbookn 10 "Event stuff" RWSAMPLE 1000 RWTEST 
PROCESSOR MCL74
 
DEF EVANAL
   CALL MCL74
   RWTEST%(NPARTS) = _MCHEAD%(NTOT)
   RWTEST%(IPX) = _MCHEAD%(IP(1))
   RWTEST%(IPY) = _MCHEAD%(IP(2))
   RWTEST%(IPZ) = _MCHEAD%(IP(3))
   RWTEST%(ENERGY) = 0
   BANKLOOP MCPART
      RWTEST%(ENERGY) = RWTEST%(ENERGY) + MCPART%(E)
   ENDLOOP
   NTUPLE Hfn 10 
ENDDEF                
           
GO 500
 
NTUPLE Hrout 10                  
NTUPLE Hrend RWSAMPLE
!!
!!
!!  Column-wise template
!!
BANK CWATEST  CONTEXT = TEST  MAXID = 1
   REAL ENERGY
   INTEGER NPARTS                        
   REAL IP(3)
ENDBANK
!!
!!  EZcw example
!!
OPEN READ GENERATE   
CWATEST = _CWATEST(ADD)
CMDPROC NTUPLCMD                 
 
NTUPLE EZcw "$scr:[grb]" cwatest
PROCESSOR MCL74
DEF EVANAL
   CALL MCL74
   CWATEST%(NPARTS) = _MCHEAD%(NTOT)
   DO I = 1 TO 3
      CWATEST%(IP(I)) = _MCHEAD%(IP(I))
   ENDDO
   CWATEST%(ENERGY) = 0
   BANKLOOP MCPART
      CWATEST%(ENERGY) = CWATEST%(ENERGY) + MCPART%(E)
   ENDLOOP
   NTUPLE EZfill 
ENDDEF                
           
GO 200
 
NTUPLE EZend                 
!!
!!
!! Column-wise with full HBOOK syntax
!!
OPEN READ GENERATE   
CWATEST = _CWATEST(ADD)
CMDPROC NTUPLCMD                 
 
NTUPLE Hlimit 500000
NTUPLE Hropen CWASAMPL "$SCR:[GRB]MYCWA.RZDAT" NQX 1024
NTUPLE Hbnt 20 "Event Array Stuff"
NTUPLE Hbname 20 CWATEST
PROCESSOR MCL74
DEF EVANAL
   CALL MCL74
   CWATEST%(NPARTS) = _MCHEAD%(NTOT)
   DO I = 1 TO 3
      CWATEST%(IP(I)) = _MCHEAD%(IP(I))
   ENDDO
   CWATEST%(ENERGY) = 0
   BANKLOOP MCPART
      CWATEST%(ENERGY) = CWATEST%(ENERGY) + MCPART%(E)
   ENDLOOP
   NTUPLE HfnT 20 
ENDDEF                
           
GO 200
 
NTUPLE Hrout 20                  
NTUPLE Hrend CWASAMPL
!!
!!
!!  Column-wise example with variable block and full syntax
!!
!!  The template
!!
BANK CWVTEST CONTEXT = TEST MAXID = 1
  INTEGER NPARTS
  REAL PX(300)
  REAL PY(300)
  REAL PZ(300)
  REAL E(300)
ENDBANK
!!
!!  The code
!!
OPEN READ GENERATE   
CWVTEST = _CWVTEST(ADD)
CMDPROC NTUPLCMD                 
 
NTUPLE Hlimit 500000
NTUPLE Hropen CWVSAMPL "$SCR:[GRB]MYCWV.RZDAT" NQX 1024
NTUPLE Hbnt 40 "Event CWV Stuff"
NTUPLE HbnameV 40 CWVTEST
PROCESSOR MCL74
DEF EVANAL
   CALL MCL74
   CWVTEST%(NPARTS) = _MCHEAD%(NTOT)
   J = 0
   BANKLOOP MCPART
      J = J + 1
      CWVTEST%(E(J)) = MCPART%(E)
      CWVTEST%(PX(J)) = MCPART%(P(1))
      CWVTEST%(PY(J)) = MCPART%(P(2))
      CWVTEST%(PZ(J)) = MCPART%(P(3))
   ENDLOOP
   NTUPLE HfnT 40 
ENDDEF                
           
GO 200
 
NTUPLE Hrout 40                  
NTUPLE Hrend CWVSAMPL

Gary Bower
Updated Nov. 16, 1995