Tutorials Step 2: First Super-K Code Example (Fortran version)

A First Super-K Code Example

Here is a first Super-K program example. It’s in Fortran (not exactly the language of the future) but should serve well to illustrate some of the ideas and tools.

All this program does is to take a raw Super-K data file, and dump to the screen a list of events; for each event, it then loops through the ID PMT hits and writes to the screen: hit number, cable number, charge, time.

Setup

Hopefully by now you have done the setup steps.  If you don’t have your .tcshrc set up yet (and you really should, and you should be running tcsh), you’ll need to type the following before doing this example (on the Duke machines).  See the setup steps for the corresponding commands on the Kamioka machines.  For future, tutorials, this part will be assumed to already be done.

setenv PROJECT /var/phy/project/hep/neutrino
source $PROJECT/soft-SL6/SK-Duke.login
setenv TUTEXAMPLES /disk/usr2/jalbert/tutorial-example-files

Files for this example

Copy the following files from

$TUTEXAMPLES/tutorials

into your tutorials subdirectory of your work directory (or anywhere in your work directory you want, really):

  • example1.F: contains the source code for the program
  • GNUmakefile: used to compile the program

First, before doing anything else, take a look at example1.F, and see if you can follow generally what it’s doing. We put numerous comments in it (labeled by “*” or “C” in the first column) which we hope will help somewhat.

  • First, there are some variable declarations.
  • Then it reads in the command line input (see below) to find out what file(s) it should open
  • Next, it performs some initializations.
  • Then, it loops over input files, and uses SKOPENF (a routine in the SK libraries) to open a file.  The routine SET_RFLIST is also used, this is a helper routine also in the SK libraries to let SKOPENF know what file to open, and how to open it.
  • Then, it loops over events in the file, and uses SKREAD (another SK routine) to read each event. What “reading an event” means: SKREAD copies information (after a bit of processing) from the ZBS banks of the files into Fortran “common blocks” (regions in memory). After the read of the event, you can access the event’s information via variables. For instance, after the read, the nqisk variable contains the number of ID hits in the event, and the qisk array contains the charge values for each PMT of the event.  The full lists of these variables are in the header files.
  • For each event, it prints the run number, subrun number and event number. Then, for each event, it loops over the hits in the event, and writes to the screen: hit number, cable number (same as tube number), charge (in photoelectrons), and time (in nanoseconds). In the loop: 
                   do ihit=1,nqisk

* Output hit number, cable number, charge, time
                  write(6,*) ihit,ihcab(ihit),qisk(ihcab(ihit)),
     &                            tisk(ihcab(ihit))

               enddo

    ihit is the hit number, ihcab(ihit) is the tube number, and qisk and tisk are the charge and time, respectively, for that tube.

  • When it reaches the end of the events in a file, it starts the next file, if there is another file; otherwise, it stops.

Note that this program will be run with one or more arguments the command line.  That’s what the whole iargc() and getarg business is about.  Thus, the program will read whatever file you tell it to read when you start it.  If you input multiple files (one after another), it will read them in order.

Finally, look at the GNUmakefile. This is a file which contains information for compiling and linking the program. Needed libraries and includes are linked against automatically using information specifed in $(SKOFL_ROOT)/config.gmk. The OBJS line of this file specifies programs to compile.

Running this example

  • Compile the program by doing 
    make example1

    This compiles and links the source code (example1.F) according to the GNUmakefile instructions. The resulting executable (called example1, compiled programs traditionally don’t have file extensions in linux) is created in your working directory.

  • Next you should be able to run the executable using the script, with 
     ./example1 filename

    where the filename argument is the SK data file you want to run on. For this test, I suggest you do

     ./example1  $TUTEXAMPLES/rfm_run060960.000096.tqr.zbs

    This file is a nearly unprocessed raw data file, without any reconstructed information and all triggers.

  • Look at the output. You might want to “pipe into less” to see it more slowly: 
    ./example1 $TUTEXAMPLES/rfm_run060960.000096.tqr.zbs | less

    and hit the space bar for paging output, “b” to go back.

  • Try seeing what you get by modifying the source code (say, adding a print statement), recompiling and rerunning.

Now you’ve gotten to see some code that reads SK data, compiled it into an executable, and used that to read some data.  Then, you played around with the code to get a better feel for it.

The next example will be to make some histograms.

Back to the tutorials top page