Workbook for SLD Offline Users - First Day

Plan for the First Day

This section of the workbook takes you through your first day with SLD offline software. By the end of this first day you will have examined, histogrammed and made event displays from real data.

This section is somewhat different from the other sections of the workbook in that it asks you to type some commands without explaining exactly what they do. All later sections of the workbook will introduce concepts in a more detailed way. We hurry you through some explanations in this first day because we want you to get your hands on actual SLD data right away, and we want you to get a general sense of how few commands it takes to work in SLD.

X and Web: What You Need to Use This Workbook

To get started with the SLD Offline Users Workbook, you need an X terminal capable of running World Wide Web. Detailed instructions are provided in the document First Day: X and Web for those who are not yet familiar with X Windows or World Wide Web.

VMS: The Operating System

SLD software runs on the DEC VMS and IBM VM operating systems. IBM VM is being phased out and should be avoided (why fill your mind with information that will soon be obsolete?). Some amounts of SLD analysis work can also be performed on Unix systems, however the full set of SLD software will not be available on Unix for a long time, if ever. As a new user, you should start learning SLD software on VMS.

Detailed instructions on how to obtain and configure a VMS account are provided in the detailed document First Day: Getting an Account.

IDA: The Interactive Data Analysis Shell

Go to your newly created [.FIRST] directory by typing SET DEFAULT [.FIRST]

SLD Offline Software runs in a shell called IDA (Interactive Data Analysis).

Start the system by typing IDA

VMS should respond with some initialization statements ending with the IDA prompt.


           **************************
           ** SLD IDA version 1.40 **
           **************************
           **************************
           ** JAZELLE version 3.50 **
           **************************

   HANDYPAK  --  RELEASE 6.58 --  HCOM SIZE =  200000
   %UPROC-I-INIT Processor support package (UPROC version 1.20) initialized
   Ida>

Open Some Data

SLD data is stored on disk or on tape, depending on how large or how popular a given data set is. A single command is used to open either kind of data. For the first few examples, to keep your job running fast, we will use data that happens to be on disk.

Type OPENTAPE READ REC94_MDST STAGE WAIT

IDA should respond with a statement telling you that it has found the requested data.

   READCAT: Catalog entry found for the requested data
   Catalog Name: DUCSROOT:[SLD.DATACAT]NEWUSERS.DATACAT;1 Dataset Name: REC94_MDST

          Medium      : DISK
          Disk name   : DISK$SLD_FAC0:[SLDWWW.WORKBOOK]
          Disk Address:
          File name   : REC94V11_MDST
          File type   :
          Status      : OK
          Entry Date  :
          Comments    :

The particular data set we have opened contains a collection of events from the 1994 run which passed a very loose Z filter.

Now tell IDA to read in the first event from the data set.

Type GO 1

IDA should respond with a statement that an event has been read.

   %IDA-I-GOSTART Start GO for 1 records
   %IDA-I-STOPEDAT Event loop terminated after run 27840 event 59
   %IDA-I-GOEND End GO after 6.9399 seconds and 1 records (6.9399 seconds/record)

         Summary of GO
     Type    Count     Procedure
    INPUT        1     IJREAD
    EVENT        1     EVANAL

Jazelle: The Data Manager

SLD data is stored in a tightly packed format known as Jazelle (a descendent of SLD's prototype data format, Gazelle, which is in turn a descendent of a data format developed at CERN called Zebra). Jazelle data is composed of units called "banks."

To see what banks are contained in the current event, type INDEX

IDA should respond with a long list of text that begins

   Family   Number Context  Title
   PHPSUM       28 DST      Particle parameters
   MCPQRK        0 MCEVENT  MC primary quark
   PHWIC         0 DST      WIC Muon id information for PHTRK
   PHPOINT      28 DST      Pointers to Particle Information
   IEVENTH       1 IDA      SLD event header

The first line tells us that there are 28 banks of a kind called PHPSUM banks.

The fifth line tells us that there is one bank of a kind called IEVENTH.

Type PEEK IEVENTH

IDA responds by dumping the contents of the IEVENTH bank in a convenient readable format.

   Family: IEVENTH    ID:     1   Template Version: 0.00
   Title:  SLD event header

   Name     Value      Name     Value      Name     Value      Name     Value
   ----     -----      ----     -----      ----     -----      ----     -----
   RUN      27840      EVENT    59         TIME     Below      WEIGHT   1.0000
   TYPE     Below      TRIGGER        6A   MCEVENT  0          RAWDATA  0
   RECON    0          DST      0          USER     0          NFLAG    0

   TIME      :19-AUG-1994 00:42:37.01
   TYPE      :0(PHYSICS)

The data is actually stored as a tightly packed integer array. The Jazelle data management system converts this information to a readable format on the fly when you type the PEEK command. More on this later.

This particular bank, as we see from the Title line, is the Event Header bank. There is one and only one such bank for each event. It tells us the run number, the event number, the time and date of the event, and other information such as the type of trigger that caused this event to be written out by the SLD data acquisition system.

Notice in the results of the INDEX command that IDA reported having 15 PHCHRG banks. Type PEEK PHCHRG(1)

IDA responds by dumping the contents of the first PHCHRG bank. This bank contains detailed information for the first of 15 charged tracks found in this event. You will later learn how to find out the meaning of the more obscure parts of this output. For now, just take it on faith that the six HLXPAR quantities shown in the PEEK are the fit parameters that result from reconstruction of Drift Chamber and Vertex Detector data.

You can use the PEEK command to look at a single element within a bank rather than the entire bank.

Type PEEK PHCHRG(5).HLXPAR(2)

IDA responds with the value of the second element of the HLXPAR array for the charged track number five. This value is equal to one over the transverse momentum of the particle.

   PHCHRG(5).HLXPAR(2) (R*4) .52824 "*  track parameters and error matrix   *"

The INDEX command reported that there were 21 banks of a type called PHKLUS. These banks contain the findings of the Calorimeter. Again, PEEK shows you the details.

EVANAL: The Event Loop

You can define a procedure for IDA to execute once for each event. You define such a procedure using the DEF EVENAL and ENDDEF commands. Any code you specify between these two commands will be executed once per event the next time you type a GO command.

For example, type


   DEF EVANAL
     PEEK PHCHRG(1).HLXPAR(2)
   ENDDEF
And then type GO 4

IDA will read in the next four events, and for each event it will execute your PEEK command.

You can replace your event loop with a new event loop any time by just typing a new DEF EVANAL. To remove the event loop entirely, just define an EVANAL procedure with no commands inside it.

Handypak: The Histogramming Package

SLD currently uses a histogramming package that was written at SLAC called Handypak. SLD has plans to eventually switch over to using the CERN package, HBOOK, but the IDA command interface will remain roughly the same.

You use a single command in IDA to both book a histogram (that is, to define it), and to fill that histogram. IDA gets these two functions out of a single command because it treats the command differently the first time it sees it.

Type the following to create an event loop that creates and fills a histogram. We've added a PEEK in just so you can see the loop run. We've added another new construction here, the BANKLOOP. This construction causes a loop over all the banks of the specified kind. Thus the BANKLOOP here causes a loop over all of the PHCHRG banks in the event.

Don't worry about the meaning of the detailed syntax. We'll discuss all that later. The point for now is just to give you an idea of how much can be done with how few commands.


   DEF EVANAL

     PEEK IEVENTH.EVENT

     BANKLOOP PHCHRG
       HIST PHCHRG%(HLXPAR(2)) FROM 0 TO 10 ID 1 TITLE "HLXPAR(2)"
     ENDLOOP

   ENDDEF

The histogram defined here will show the inverse of the transverse momentum for all charged tracks. To create this histogram using the next fifty events, type

GO 50

You get a PEEK of the first charged track found in each event.

To output the histogram to a graphics window, type

HOUT 1 SDDXWDO

Your results should be as follows

HOUT has many options that will be discussed later. For now, type HOUT 1 POSTSCR to leave a PostScript copy on your disk. You will use this later when you learn details about VMS file handling.

Before you go on. use the following command to again set IDA to read events from the beginning of the data set.

Type REWIND

If you now type GO 1 and the PEEK IEVENTH you will see that you have again read the first event from this data set.

DSP: The Event Display Package

SLD uses an event display package written at SLAC called DSP. The package can display data seen in any part of the detector and can also draw the geometry of any detector element to any level of detail. DSP can draw to a wide variety of display devices including X terminals, other 2D display devices, some 3D display devices and many hard copy devices.

To load the one event display package,

type CMDPROC DSPCMD

The CMDPROC command will be discussed later in detail. Basically it is used to load a new package of commands into IDA. Once you have issued this command, IDA will recognize a wide variety of event display commands. All of these commands begin with DSP.

Tell the event display that you want your output on an X terminal.

Type DSP SELECT SDDXWDO

Now that you have selected an output device, to see a display

Type DSP DRAW

The display that is drawn will so far be empty except for some event information in the upper left corner and an SLD logo in the lower right.

Add the outlines of the Warm Iron Calorimeter to the drawing.


   DSP ADD DETWIC
   DSP DRAW

You should now see the outline of the detector.

Add the outline of the Liquid Argon Calorimeter.


   DSP ADD DETLAC
   DSP DRAW

More outlines are now visible.

Now overlay the found charged tracks on the display.


   DSP USERDATA DSTUDSP
   DSP ADD PHCHRG
   DSP DRAW

The DSP USERDATA command above will be discussed in detail later. But basically it was required, one time only, to tell the event display package to make a certain package of DSP ADD objects available.

The first time you draw a particular type of object, the draw may take some time. This is because a variety of constants need to be loaded before the object can be drawn. The next time you draw, these constants are already available so the code can run faster. This feature is true of many parts of the SLD offline software universe. The first time you take a particular action, initialization work is done that does not need to be done again later.

You can put the DSP DRAW command inside of an EVANAL procedure to make IDA draw each event in turn. Try typing the following:


   DEF EVANAL
     DSP DRAW
   ENDDEF

And run it for five events.

GO 5.

You will learn more about the event display package later. For now, you might try adding some other things to the display. For a list of the types of things that you can add right now,

type DSP SHOW TYPES

Pick an "Ident" from the left hand column, and use it in a DSP ADD command.

For example, DSP ADD PHKLUS

You can add as many items as you like before a DSP DRAW.

The opposite of DSP ADD is DSP DELETE.

To see what you have currently added, type DSP SHOW ADDED

As your last task for this section of the workbook, make a hard copy of an event display. Use the DSP SELECT command to select color PostScript output:

DSP SELECT COLPOST

Each DSP DRAW will now draw to a file of PostScript images on your disk.

To close the PostScript file and return to X terminal output:

DSP CLOSE COLPOST

When you get to the workbook section about VMS file handling, you will learn how to print your PostScript event display file.

Recap of the First Day

You have reached the end of the "First Day" section of the SLD Offline Users Workbook. You have started up the IDA data analysis shell, you have opened some SLD data and you have examined, histogrammed and made event displays from this data.

Most of the commands that you have used have many more options than you have been shown. The event display manual alone is more than a hundred pages. The next sections of this workbook will give you more detail on the commands that you have used and will introduce many more SLD offline analysis tools. You will come out having used most of the more important tools and you will be given pointers to the detailed manuals available for these tools.


Back to Workbook Front Page

Joseph Perl
31 May 1995