TWIST MOFIA MANUAL


. Initialization Branch

The MOFIA initialization branch may be divided into two parts:
geometry implementation and histogram definitions.


.1 Geometry

The MOFIA XYZ coordinate system is defined to be right handed with the
+Y direction pointing upwards and the +Z direction defined by the beam
direction. The UVZ coordinate system is obtained through a clockwise
rotation of the XYZ system by a +450 rotation around the Z-axis.  Good
diagrams of the coordinate system and the definitions of U and V
planes are linked from the main TWIST Mofia page.

The geometry description of the TWIST detector is read in from an
ascii data file common to both the Monte Carlo and MOFIA to ensure
consistency. The geometry input file name has the form dt_geo.NNNNN,
where NNNNN is the indicator number. The geometry input file is
managed through the Calibration File Manager CFM, where the
association between version numbers and run numbers is made. This
allows us to keep track of any geometry changes in the TWIST detector.

The module mainf90/det_geom_mod.f90 contains the PUBLIC subroutines
OpenGeom, which opens the appropriate geometry data file for the run
number at hand (by consulting with CFM), and calls the function
read_det_geom which reads in the geometry data. The geometry data file
contains four sections for drift chamber geometry, proportional
chamber geometry, scintillator geometry, and target geometry. Each of
these sections is read by a function called by read_det_geom:
read_dc_geom, read_pc_geom, read_sc_geom, and read_tg_geom. These
functions are all PRIVATE and internal to the module det_geom_mod. The
geometry information is saved in PUBLIC variables declared in this
module which carry the same names as the corresponding Monte Carlo
variables. In the Monte Carlo these variables are stored in the common
block det_geom.inc and the parameter file det_geom.par.

The module mainf90/chambers_mod.f90 is where all the geometry
structures for the drift chamber and proportional chamber are defined
and filled.

The two types of structures, plane_type and wire_type, include the
plane and wire geometry structures, respectively. Each type has two
instantiations, one for the drift chamber and one for the proportional
chamber: DCplane(iPlane), PCplane(iPlane), DCwire(iPlane,iWire), and
PCwire(iPlane,iWire).  The definitions for plane_type and wire_type
are well documented in chambers_mod.f90.

The following are examples of how the first four components of
plane_type are used. See chambers_mod for more details.

IF (DCplane(iPlane)%dir == dir%u) THEN

IF (PCplane(iPlane)%stream == stream%up) THEN  

DO iWire = DCplane(iPlane)%MinWire, DCplane(iPlane)%MaxWire 

The structures, dir with components u and v (dir%u,dir%v) and stream
with components up and down (stream%up,stream%down), have also been
publicly declared in chambers_mod and are available for usage by any
module or procedure that uses chambers_mod. The planes are labeled
according to the coordinate they measure so that "U-planes" measure a
U coordinate while "V-planes" measure a V coordinate. The component
rotation contains the angular orientation of the plane. Four different
angle orientations appear in the geometry file. This implementaion is
necessary to achieve consistency with the hardware labeling of wires.
In order to define a single coordinate system for all planes (upstream
and downstream) as well as maintain the wire numbering scheme assigned
in hardware, DC V-planes in the upstream half of the detector must
have increasing wire numbers in the -V direction, and DC U-planes in
the downstream half of the detector must have increasing wire numbers
in the -U direction. The U and V planes are made out of X- planes by
rotating them around the Z-axis; again see the diagrams linked from
the main Mofia pages.

While the component iPlane is obviously redundant when used in the
form DCplane(iPlane)%iPlane, the reason for putting it in the
structure is to allow accessing the plane number through a pointer in
the hit structure, and its usefulness will become evident when the hit
structure is discussed below.

The components iWire and planeP were introduced in this structure for
the same reason that iPlane was introduced in the plane_type
structure, and their usefulness will also become evident when the hit
structure is discussed.

Access to chambers_mod is achieved through a call from
mainf90/begin_run.f90 to chambers_mod PUBLIC subroutine SetupChambers,
which in turn calls PRIVATE subroutines within chambers_mod that do
the job of filling up the geometry structures (SetupDCplanes,
SetupPCplanes, SetupDCwires, SetupPCwires and SetupSCdisks). This
reflects a general philosophy employed in developing the code, namely
minimizing the number of entry points to the module by having a few
(preferably one) PUBLIC subroutines to be called from outside the
module, while the remaining subroutines in the module are made PRIVATE
and can, therefore, only be called from within the module. The
chambers_mod has a second entry point for testing purposes. The PUBLIC
subroutine PrintGeom, is accessed through a call from the subroutine
func, and may be invoked by typing func 6 at the MOFIA command
line. When invoked, PrintGeom calls private subroutines within
chambers_mod that create geometry ouput data files for purposes of
testing the geometry information (dc_planes_geom.out,
pc_planes_geom.out, dc_wires_geom.out, and pc_wires_geom.out).

It is worth noting that the geometry file does not contain any
information on wire positions and orientations. These values are
calculated in the subroutines SetupDCwires and SetupPCwires using
plane positions and orientations provided in the geometry data file
and the wires nominal separation (of 0.4 cm for the DCs and 0.2 cm for
the PCs). Corrections to both, planes nominal positions and wires
nominal positions, are read in from calibration files and implemented
in chambers_mod as corrections to the nominal positions. Procedures in
the module mainf90/calibrations_mod.f90 are accessed through a call
from mainf90/begin_run.f90 to the module's PUBLIC subroutine
ReadCalibFiles, which in turn calls PRIVATE procedures within the
module to open the appropriate calibration files for the run at hand
(through calls to CFM) and read them in. Currently 11 subroutines are
called from ReadCalibFiles corresponding to 11 calibration types that
are defined in CFM, these subroutines are: CalibPlaneCorrUV,
CalibPlaneCorrZ, CalibPlaneCorrRot, CalibWireCorrUV, CalibWireCorrZ,
CalibWireCorrRot, CalibSTR, CalibT0, CalibEff, CalibRes,
CalibADC. Some of these calibrations, however are either not
implemented in MOFIA or contain trivial data since their contents have
not been determined yet.

The calibrations data structures related to the chamber's geometry
include U or V and Z position shifts for each DC plane and wire, as
well as rotation corrections for each DC plane and wire. These
corrections are included in the geometry structures in chambers_mod,
so that the components Zshift, UVshift and rotation in the plane_type
structure already have these corrections built in.

The contents of the calibrations structures are accessed in
chambers_mod through a USE statement (USE calibrations_mod), and the
appropriate corrections are made to the geometry variables.


.2 Histogramming

TWIST adopted HBOOK for histogramming purposes since it is a package
that many members of the collaboration are familiar with. Since users
tend to define a large number of histograms for purposes of testing
their code or analyzing some specific data, in many cases keeping
these histograms as part of the official TWIST code is not
practical. For one thing, CPU time will be wasted filling in
histograms that most users don't need; and for another, the number of
histograms created becomes large so that sorting through the histogram
list to find the desired histogram becomes tedious. The decision was
therefore made to provide two histogramming modules. The first,
mainf90/hists_mod.f90, is the module that contains the official
histograms that are to be kept and used by all users. The second
module, user/user_hists_mod.f90, is where each user defines their own
histograms. The user is responsible for keeping and maintaining their
own copy of this module. If you add your own histograms make sure you
don't overwrite your own copy of user_hists_mod.f90 when you update
your code; save this module under a different name before updating
your code.

The subroutine main/define_hists.F makes two calls, one to the PUBLIC
subroutine DefineMainHists in mainf90/hists_mod.f90, and the other to
its counterpart, DefineUserHists in user/user_hists_mod.f90. These
subroutines, in turn, call PRIVATE subroutines within the module, one
for each section of the code: DefineRawHists to define raw histograms,
DefineHists to define histograms after initial filtering,
DefineXtalkHists to define cross talk histograms, DefinePatternHists
to define pattern recognition histograms, DefineFirstGuessHists to
define helix fit "first guess" histograms, DefineTrackHists to define
tracking histograms, and DefinePhysicsHists to define physics analysis
histograms. As seen from figure 5 these subroutines have similar names
in the hists_mod and user_hists_mod except that the letter "u" (for
user) is pre-pended to the name in the user_hists_mod. The call to
each one of these sections is controlled by a namelist flag in the
namelist hist which allows the user to turn off that section so that
histograms are neither defined nor filled. For example setting
"FillRawHists = .FALSE." will bypass the call to DefineXtalkHists. The
namelist hist contains several other useful variables; the command
"show name hist" displays the list.

To avoid conflicts between the user defined histogram numbers and the
main histogram numbers, values between 1 and 50,000 are reserved for
the main histograms; user histograms should always have numbers higher
than 50,000. To avoid conflicting histogram numbers between the main
histograms themselves, a range of histogram numbers has been reserved
for each section of the code, as specified on the chart of Figure
8. Histogram numbers are assigned to variables in the declaration
section of the histogramming modules. This has two advantages. First,
if a histogram number is to be changed it only needs to be done once
(rather than once where the histogram is defined and once where the
histogram is filled) which reduces the potential for
mismatches. Second, if this list is maintained in ascending order it
becomes easy to see which histogram numbers have already been used and
reduces the risk of conflicts.

The module hists_mod.f90 (user_hists_mod.f90) also contains a set of
PUBLIC subroutines for filling histograms. These are FillRawHists,
FillHists, FillXtalkHists, FillPatternHists, DefineFirstGuessHists,
FillTrackHists, and FillPhysicsHists. Each of these subroutines is (or
otherwise should be) called from the appropriate module where the
corresponding calculations are made.

To define a new histogram the user should start by declaring an ID
parameter for the histogram in mainf90/hists_mod.f90 (or
user/user_hists_mod.f90 if the histogram is not intended to become
part of the official code). For example, to define a raw histogram
containing the TDC spectra of all the wires in one histogram we
declare the parameter IDH_TDC_ALL to be the histogram's ID

INTEGER (i4), PARAMETER :: IDH_TDC_ALL  = 3

We then install a call to the HBOOK subroutine "HBOOK1" to define a
1-D histogram in the subroutine DefineRawHists

!  TDC time (total) 
CALL HBOOK1 (IDH_TDC_ALL, 'DC TDC TIME', TDC_MAX-TDC_MIN, TDC_MIN, TDC_MAX, 0.)

The first parameter in the call to hbook1 is the histogram ID. The
second is a description of the contents of this histogram to be
displayed as a histogram label. The third parameter is the number of
bins, which in this example is the expression TDC_MAX-TDC_MIN. The
next two parameters are the histogram's lower and upper limits,
respectively (TDC_MIN and TDC_MAX).  To fill this histogram a call is
made to the HBOOK subroutine HFILL from the subroutine FillRawHists

        !  RAW TDC spectra for all wires in one histogram             
        CALL hfill (IDH_TDC_ALL, timeP, 0.0, 1.0)

The first parameter in this call is the histogram ID (as in the call
to hbook1). The second parameter is the variable containing the TDC
time, in this case a pointer to the TDC time, timeP. Note that this
variable has to be real, if an integer is to be plotted the variable
has to be converted to real first. For example if timeP was a pointer
to an integer variable the second parameter in the hfill call should
be REAL(timeP) rather than timeP. Failure to do so will result in run
time errors.