Row-Wise-Ntuples (RWN)

[sec:NtupleRWN]

Booking a RWN

[HNTUBOOK] 

            +------------------------------------------------+
            |CALL  HBOOKN (ID,CHTITL,NVAR,CHRZPA,NWBUFF,TAGS) |
            +------------------------------------------------+

Action: Books a RWN in memory or with automatic overflow on an RZ file. Only single precision floating point numbers (REAL*4 on 32 bit machines) can be stored, no data compression is provided.

Input parameters:
ID
Identifier of the Ntuple.
CHTITL
Character variable containing the title associated with the Ntuple.
NVAR
Number of variables per event (NVAR<=512)
CHRZPA
Character variable containing the path name of a RZ file onto which the contents of the Ntuple can overflow.
' '
Memory resident Ntuples: A bank of NWBUFF words is created. Further banks of the same size are added in a linear chain should additional space be required at filling time.
'RZTOP'
Disk resident Ntuples: (recommended) A disk resident Ntuple is created if the CHRZPA argument specifies the top directory name of an existing RZ file that has already been opened with HROPEN or HRFILE. A bank of length NWBUFF is created, as in the case of memory resident Ntuples. However, each time the bank becomes full it is automatically flushed to the RZ file, rather than creating additional banks in memory.
NWBUFF
Number of words for the primary allocation for the Ntuple.
TAGS
Character array of length NVAR, providing a short name (up to eight characters) tagging scheme for each variable. 

        Example of the declaration of a memory resident RWN
                                  

      CHARACTER*2 TAGS(5)
      DATA TAGS/'Px','Py','Pz','Q2','NU'/
 *
      CALL HBOOKN(10,'My first NTUPLE',5,' ',1000,TAGS)

Filling a RWN

[HNTUFILL] 

                            +----------------+
                            |CALL  HFN (ID,X) |
                            +----------------+

Action: Fills a RWN.

Input parameters:
ID
Identifier of the Ntuple.
X
Array of dimension NVAR containing the values for the current event.

Memory resident Ntuples

When a RWN is booked, HBOOK reserves space in memory in which to store the data, as specified by the HBOOKN. As the RWN is filled by a call to HFN, this space will be successively used until full. At that time, a new memory allocation will be made and the process continues.

If this data is then written to disk, it appears as one enormous logical record. In addition, it most cases the last block of data will not be completely filled thus wasting space.

If one tries to reprocess this RWN at a later date, e.g. with PAW, there must be enough space in memory to store the entire Ntuple. This often gives rise to problems and so the following alternative method is recommended.

Disk resident Ntuples

Prior to booking the RWN, a new HBOOK RZ file is created using HROPEN. The top directory name of this file is passed to routine HBOOKN when the Ntuple is booked.

Filling proceeds as before but now, when the buffer in memory is full, it is written to the HBOOK file and then reused for the next elements of the Ntuple. This normally results in a more efficient utilisation of the memory, both when the Ntuple is created and when it is reprocessed. 

                 Recommended way of creating a RWN
                                  

      PROGRAM TEST
      PARAMETER (NWPAWC = 15000)
      COMMON/PAWC/PAW(NWPAWC)
      CHARACTER*8 CHTAGS(5)
      DIMENSION EVENT(5)
      EQUIVALENCE (EVENT(1),X),(EVENT(2),Y),(EVENT(3),Z)
      EQUIVALENCE (EVENT(4),ENERGY),(EVENT(5),ELOSS)
      DATA CHTAGS/'X','Y','Z','Energy','Eloss'/
*
      CALL HLIMIT(NWPAWC)
      CALL HROPEN(1,'EXAMPLE','EXAMPLE.DAT','N',1024,ISTAT)
      IF(ISTAT.NE.0)GO TO 99
*
      CALL HBOOKN(10,'A Row-Wise-Ntuple',5,'//EXAMPLE',5000,CHTAGS)
      CALL HBOOK1(100,'Energy distribution',100,0.,100.,0.)
*
      DO 10 I=1,10000
         CALL RANNOR(X,Y)
         Z=SQRT(X*X+Y*Y)

         ENERGY=50. + 10.*X
         ELOSS=10.*ABS(Y)
         CALL HFN(10,EVENT)
         CALL HFILL(100,ENERGY,0.,1.)
 10   CONTINUE
*
      CALL HROUT(0,ICYCLE,' ')
      CALL HREND('EXAMPLE')
*
 99   CONTINUE
      END
When the Ntuple is filled, routine HFN will automatically write the buffer to the directory in the RZ file, which was specified in the call to HBOOKN (the top directory //EXAMPLE in the example above). If the current directory (CD) is different, HFN will save and later automatically restore the CD.

The Ntuple created by the program shown above can be processed by PAW as follows. 

                  Reading an RWN in a PAW session
                                  

            PAW > Histo/file  1  example.dat
            PAW > Histo/plot 100
            PAW > Ntuple/plot 10.energy
            PAW > Ntuple/plot 10.eloss  energy<50
            PAW > Ntuple/plot 10.eloss%energy  x<2.and.sqrt(z)>1

By default HROPEN creates a file that can be extended up to 32000 blocks, i.e. 128 Mbytes for a record length LREC of 1024 words. If one wishes to create very large Ntuples, one should make two changes to the above procedure.

  1. A large value should be used for the record length of the file, e.g. 8192 words (the maximum on most machines). This remark does not apply to a CWN, as described later.
  2. Option Q on HROPEN should be used to override the default number of records allowed.

    This can be achieved as by changing the previous call to HROPEN as follows: 

                      Writing very large Ntuple files
                                  

    
              COMMON/QUEST/IQUEST(100)
              CALL HLIMIT(150000)
*
*     Create HBOOK file with the maximum record length (32756 bytes)
*     and maximum number of records (65000)
*
              IQUEST(10) = 65000
              CALL HROPEN(1,'EXAMPLE','EXAMPLE.DAT','NQ',8192,ISTAT)
              IF(ISTAT.NE.0)GO TO 99