Data Acquistion Software for Scintillator Test Stand
WRITTEN BY: Calvin. R. Howell
Duke University and TUNL
DATE: September 13, 1994
INTRODUCTION
The software contained in this directory is an example of the Hall-A data
analysis/acquisition software using the first version of the event analyzer
program flow. There is both an on-line, "ha_onlana.f", and an off-line,
"ha_replay.f", analysis program. Though this software package was written
specifically for testing the scintillators, it was designed to facilitate the
adaptation to and expansion to include other detectors.
This data acquisition package is based on CODA (CEBAF Online Data
Acquisiion) and CTP (CEBAF Test Package). CODA is a network distributed data
acquisition system which uses commerical network hardware and standard TCP/IP
protocol. The CODA system has six major network services: (1) the Trigger
Supervisor, (2) the Read-out Controllers, (3) the Event Builder and (4) the
Analyzers, (5) Run Control and (6) Slow Control. The CTP software is a
dynamic test and parameter management package for unix computers. Its design
is similiar to that of the LAMPF Q system but more modern in detail. CTP uses
configuration files for loading information into the event analyzer and remote
procedure calls (RPC) to modify tests and parameter data in an active analyzer.
Documentation on CODA and CTP can be obtained via anonymous FTP.
SITE: ftp.jlab.org
USERNAME: anonymous
PASSWORD: abc
Once logged into the anonymous ftp account, move to the desired directory using
the cd command and transfer files using the get command. For instance, to
obtain
(1) the CODA manual execute the following commands
% cd pub/coda/docs/manual
% ls *.ps
% get coda.'ver'.ps , where 'ver' = the version number
% bye
(2) % cd pub/hallc
% get ctp_manual.ps
% bye
ANALYZER SOFTWARE OVERVIEW
The organization of the test-stand software is as follows. There are two
analyzer programs: ha_onlana for on-line data analysis and ha_replay for
off-line analysis. They are both based on the usrevent.f routine for event
by event analysis. The main difference is the software engine that drives the
usrevent and related routines. In the case of on-line analysis, execution of
the usrevent routine is dependent upon the contents of the Event Builder data
buffer. Whereas in the off-line analyzer the events are read from a file and
usrevent is called with each event until the desired number of events (usually
all) in the file are analyzed. The usrevent routine defines the flow of the
event analysis and most of the the detector specific analysis is expected to
be done in the 'det'_ana.f and 'det'_calib.f routines, i.e., scint_ana.f and
scint_calib.f. Each detector will have a 'det'.h include file to define and
store detector specific data structures, i.e., scint.h. The other needed
common use include files are decode.h, rawdata.h and run_info.h. The histograms
are booked, cleared and filled using CERN HBOOK routines. The booking and
filling of histograms is managed using CTP. Defining and evaluation of event
tests and cuts are done using CTP. CTP is also used for dynamic parameter
management. There are three general use CTP configuration files,
g_hist_ctp.config, g_test_ctp.config and g_parm_ctp.config, and one CTP
configuration file for each detector to define detector spectific paramters,
i.e., scint_parm_ctp.config. In addtion, the runsummary_ctp.config is used to
make a report of statistical information, i.e., scalers, test statistics and
specialized counters, for the run using CTP. The detector map file is
'name'_detmap.config, for example scint_detmap.config. For on-line data
acquisition, additional files are needed to configure the CODA system. See
below for brief descriptions of the needed configuration files.
Many of the general use program control flags and input-output and
configuration file names are defined in the "g_parm_ctp.config". The flags and
file names are documented in "g_parm_ctp.config". The histograms can be viewed
using either paw or paw++. In paw++ it is convenient to view the defined
histograms using the "title" option in the "view" pull-down menu in the browser
window. Hard copies of documentation on CERN library routines, HBOOK, PAW,
PAW++, HIGZ, CODA and CTP can be obtained from Bob Micheals in room C108 of
the CEBAF Center.
The organization of the analysis code described above should be interpreted
only as a starting point. We anticipate it will evolve as experience is gained.
HOW TO GET STARTED
1. ONLINE DAQ
For now it is recommended to use the adaq account on hires2 for DAQ.
The password to the adaq account is "halla000". The tstand directory has
been setup for general use Hall-A data acquistion. If you want to use
this directory then change to that directory usng the UNIX cd command:
% cd tstand
Those who do not wish to work in the tstand directory should create their
own directory using the UNIX mkdir command and copy the needed software from
the /hires2/usr/users/adaq/Asoft/examples/tstand directory. This can be done
by executing the following UNIX commands.
% mkdir 'your_directory_name'
% cd 'your_directory_name'
% cp /hires2/usr/users/adaq/Asoft/examples/tstand/* .
If you are working in the tstand directory and want the most recent
version of the test-stand software, simply execute the last of the above
three UNIX commands.
Because it is easier to start from stratch and gives a better
understanding of how to operate the CODA system, you should quit the CODA
run control service if it is running. This should kill all associated
services and processes. However, you should still check that all CODA
services were properly deleted by using the UNIX commands
% ps -fu adaq | grep coda
% ps -fu adaq | grep ha_onlana
If CODA services or the analyzer are running, delete with the UNIX command
% kill -9 'PID'
as many times is needed.
Now you are ready for what I call a ground-level start.
1. Setup the environment
% source ha_env
2. Compile and link the online analyzer and CODA crl codes
% make ha_onlana
% crl_compile
3. Run the analyzer routine in the background -- this is convenient for
code debugging
% ha_onlana &
4. Bring up the CODA run control
% RunControl &
5. Use the run control interface to
(a) configure the system
(b) download
(c) prestart - clears histograms, tests and loads new values of CTP
parameters
(d) go - clears hardware scalers and starts data accumulation
(e) pause - to temporarily pause a run; dumps histograms to the
ha_ana.hbook file
(f) end - to stop the run; dumps histograms to the ha_ana.hbook
file and reads hardware scalers.
6. The histogram file ha_ana.hbook can also be updated by executing the
command
% cdumphist ANA1
% paw++ - to view histograms
2. OFFLINE ANALYSIS
Though the adaq account can be used for data replay, it is probably
more convenient and has added flexibility if the analysis is done in the
users private account. Also, since the adaq account is open to all
Hall-A experimenters and therefore intrinsically less secure than a
private account, the probability of corruption to user developed software
is greater in the adaq account. For these reasons, we strongly
recommend replay of data in private accounts. One can get started by
following the steps given below.
1. Create the directory for data replay
% mkdir 'your_replay_directory'
2. Change directory
% cd 'your_replay_directory'
3. Copy the needed files from the /hires2/usr/users/adaq/Asoft/examples
directory and compile and link the offline analysis program
% cp /hires2/usr/users/adaq/Asoft/examples/tstand/* .
% make ha_replay
4. Setup the environment
% source ha_env
5. Run the ha_replay program - it prompts you for the needed information
% ha_replay
**** Bugs should be reported to Calvin Howell at howellc@jlab.org or
Bob Micheals at rom@jlab.org .
HALL-A SOFTWARE
A description of the software modules contained in the directory is given
below. More details are given within the codes.
FORTRAN SOURCE FILES:
event_decoder.f - This routine unpacks data from CODA bank structures into raw
detector data structures as defined in
/hires2/usr/users/adaq/Asoft/include/rawdata.h.
IT MUST NOT BE MODIFIED -- WILL BE PUT IN THE HALL-A
SOFTWARE LIBRARY AFTER FIRST ROUND OF DEBUGGING IS COMPLETED.
ha_onlana.f - This program is the on-line event analyzer engine.
ha_replay.f - This program is the off-line event analyzer engine.
init_decoder.f - This routine initializes variables and arrays used by
ha_decode.f and load_detmap.f. IT MUST NOT BE MODIFIED --
WILL BE PUT IN THE HALL-A SOFTWARE LIBRARY AFTER FIRST ROUND
OF DEBUGGING IS COMPLETED.
init_eventcounters.f - This routine initializes the event counters before each
event is unpacked into the detector raw data structures.
init_runcounters.f - This routine initializes counters that accumulate over
the period of one run. In on-line data acquistion, it is
usually executed in the usrprestart routine. In off-line
applications, it is generally executed either at the beginning
of replay and/or at the beginning of each run or each new
data file depending on the desired tabulated statistical
information. In the present off-line example it is executed
once at the beginning of the replay session.
list_detmap.f - This routine prints the current detector map in ASCII format
to either standard output or to a file. IT MUST NOT BE MODIFIED
-- WILL BE PUT IN THE HALL-A SOFTWARE LIBRARY AFTER FIRST ROUND
OF DEBUGGING IS COMPLETED.
load_detmap.f - This routine loads the detector map from an ASCII
configuration file. In the present example the detector
configuration file is scint_detmap.config. THIS ROUTINE MUST
NOT BE MODIFIED -- WILL BE PUT IN THE HALL-A SOFTWARE LIBRARY
AFTER FIRST ROUND OF DEBUGGING IS COMPLETED.
reg_ctp.f - This routine registers variables that are to be used both in the
the analyzer and in CTP. Variables that are used exclusively in
CTP need not be registered. This routine calls the routines that
that does the actual registration for each include file. Most of
the fortran routines called by reg_ctp are generated from the *.h
files using the makereg utility.
'det'_ana.f - The analysis routine for the detector packages, i.e.,
'det' = scint, vdc, phys, trace, fpp, gas, aero or shwr
usrprestart.f - This routine executes a series of tasks at the beginned of the
CODA prestarted state. This version calls the usrini routine.
See description above.
usrend.f - This routine executes a series of tasks at the end of a run.
This version dumps the histograms using the usrdump routine,
appends information to a run report summary file, and reads the
scalers.
usrdump - This routine writes the HBOOK histograms to a disk file. In the
present version it writes to the ha_ana.hbook file. In later
versions the file name will be assigned using CTP and the run
number will be appended to the name. This routine can be invoke
using the CODA utility cdumphist 'analyzer', where 'analayzer'
is the name of the analyzer component in the rcNetwork file.
append_subfix - This routine appends a numerical plus a character subfix to
the end a character name.
usrpause.f - This routine executes a series of tasks at the beginning of a
a CODA paused state. This version dumps histograms to disk using
the usrdump routine.
usrdownload.f - This routine executes a series of tasks at the beginning of a
a CODA downloaded state. This version simply returns.
usrgo.f - This routine executes a series of tasks at the beginning of a
usrevent.f - This routine defines the flow of the event analysis. A flow
diagram of this routine is given in the usrevent.ps postscript
file.
a CODA running state. This version clears the hardware scalers.
usrini.f - This routine initializes the main data structures prior to event
analysis. It registers the CTP variables and arrays, allocates
memory for HBOOK histograms, loads CTP configuration files, books
CTP tests and histograms, clears CTP tests and test scalers,
loads detector map, initiliazes raw data and run counters. In
the offline code, ha_replay, it is called at the beginning of
replay only once. In the online code, ha_onlana, it is called
at the beginning of the code and by usrprestart. In the future,
the update of information that might change from run to run
and is contained in configuration files will be controlled by
flags using CTP.
scaler_update.f - This routine updates the scaler arrays using the hardware
scaler data.
FORTRAN INCLUDE FILES:
aero.h - This files contains data structures and common blocks specific
to the analysis of the aerogel cerenkov data.
decoder.h - This files contains data structures and common blocks specific
to the event data decoder. Information is loaded into the
detector map data structure using the load_detmap routine described
above. THIS FILE SHOULD BE MODIFIED ONLY WITH THE PERMISSION OF A
MEMBER OF THE HALL-A DAQ GROUP.
fpp.h - This files contains data structures and common blocks specific
to the analysis of the FPP data.
gas.h - This files contains data structures and common blocks specific
to the analysis of the gas cerenkov data.
physics.h - This files contains data structures and common blocks specific
to the physics part of the event analysis. It is where general use
physics constants are defined.
rawdata.h - This files contains data structures and common blocks used to
store the raw digitized data. THIS FILE SHOULD BE
MODIFIED ONLY WITH THE PERMISSION OF A MEMBER OF THE HALL-A DAQ GROUP.
run_info.h - This files contains data structures and common blocks that store
general use information, such as incident beam energy, event number,
scattering angle, etc. Though not as restrictive as the rules for
modifying decoder.h and rawdata.h, modification must be approved by
a member of the Hall-A DAQ group.
scint.h - This files contains data structures and common blocks specific
to the analysis of the scintillator data.
shower.h - This files contains data structures and common blocks specific
to the analysis of the shower counter data.
trace.h - This files contains data structures and common blocks specific
to the trace back to the target.
vdc.h - This files contains data structures and common blocks specific
to the analysis of the VDC data.
CONFIGURATION FILES:
CODA
rcNetwork - This is a CODA configuration file. It defines the network
components of the distributed DAQ system. See the CODA manual for
details.
rcRunTypes - This is a CODA configuration file. It contains one entry for
each run type. For example, scint_coda and testx_coda could
represent runs for a scintillator test setup and a general
purpose test stand setup with, respectively. For each run type
there must be a configuration file that associates software with
each network component defined in rcNetwork. See the CODA manual
for details.
rcRunNumber - This is a CODA file for holding the current run number.
rcDefaults - This file contains the default values for the CODA run control
and slow control services.
scint_coda.config - Run type CODA configuration file. See above example.
testx_coda.config - Run type CODA configuration file. See above example.
CTP
g_hist_ctp.config - General use CTP configuration file for defining HBOOK
histograms.
g_parm_ctp.config - General use CTP configuration file for initializing CTP
variables. If a variable is to be used in analyzer, IT MUST BE
REGISTERED. This is done in the reg_ctp.f routine. See CTP
manual for details.
g_test_ctp.config - General use CTP test configuration file.
runsummary_ctp.config - This CTP file is used to organize the run summary
information to be printed at the end of each run.
'det'_ctp.config - This CTP file is used to initilize variables that are
specific to the 'det' detector package, where 'det' = scint,
aero, fpp, gas, phys, shwr, trace or vdc.
SHELL SCRIPT FILES:
Makefile - This file is used by the 'make' utility to compile and link the
analyzer routine. The make routine only compiles modulars that
were modified since the time of the last compilation. A description
of the make utility can be obtained using the UNIX man command. The
analyzer can be compiled and linked with the following commands.
% make - compiles and links both the online (ha_onlana) and the
offline (ha_replay) event analyzer.
% make ha_onlana - to compile and link only the online analyzer
% make ha_replay - to compile and link only the offline analyzer
% make clean - removes all dependent .o and target files; this is
useful for forcing a recompilation of all dependent modulars.
setup.com - This is a C-shell script file. It defines the RCDATABASE
environment variable used by CODA to point to the current directory and
conpiles the readout control and trigger supervisor programs. The
UNIX source command MUST be used to execute this script:
% source setup.com
CODA CONTROL PROGRAMS
tstand_roc1.crl - The readout program for readout controller 1 (ROC1) as defined
in the rcNetwork and 'runtype'.config files.
tstand_roc2.crl - The readout program for readout controller 2 (ROC2) as defined
in the rcNetwork and 'runtype'.config files.
tstand_ts.crl - The trigger supervisor configuration program. This program is
associated with the actual network component in the rcNetwork
and 'runtype'.config files.
GOOD LUCK!!!
============================================================================
APPENDIX : Some notes added by R.Michaels
How to Crawl
(~/tstand Software)
R.M. Dec 5 '94 (update Mar 31,95)
See also C.Howell's "Hall A Prog Guide",
README file above, and doc on CODA & CERNLIB.)
Assuming RunControl is up. Choose the configuration VDC_CODA unless
you know better. Click on "prestart", then "go". You're taking data.
Q: How to write data to disk file ?
A: Edit the appropriate *coda*config file (e.g. vdc_coda.config) so
that the ANA1 specifies a data file like test.dat. To turn
off data logging (so as not to fill the disk) specify NOLOG.
Q: How to analyze the data ?
A: The online analyzer is ha_onlana; the offline is ha_replay.
I suggest you forget about online for now, just write a file and
type "ha_replay" and answer the obvious questions (how many events,
what is the file name, etc). Results are histograms in a PAW
hbook file and a summary file. Histograms and summary have the
run number in them.
Q: What are the main sources ?
A: For offline analyzer, look at ha_replay.f It loops over events,
calling the routine usrevent.f for each event. Usrevent.f does a
lot of general stuff (like decoding) and calls the detector analyzers.
For scintillators this is scint_ana.f. For vdc's it is vdc_ana.f.
Initialization routines are scint_ini.f, vdc_ini.f where histograms
are booked, etc.
Q: How to compile ?
A: Type "make"
The make facility should see if a code has changed or not. (man make)
Q: How to configure an experiment ?
A: After the fastbus crate is ready, you should get an expert to help
set up the readout lists and detector maps. After that, things should
be robust enough to withstand missing gates, detector planes, etc.
Q: How to add a new histogram ?
A: New histograms can be installed in g_hist_ctp.config. They are filled
subject to logical test conditions in g_test_ctp.config. Other histo-
grams are filled in the initialization routines like vdc_ini.f
Last update 21 Apr 1995
R. Michaels, rom@jlab.org