gfilt.doc
G. E. Cooper 10-10-97
----------------------------------------------------------------------

gfilt is a program for filtering selected tracks and their associated
detector hits and vertices from DSPACK format Monte Carlo events
processed through GNA49 and G2DS.  Filtering is desirable to limit
saved output to only that information which is relevant to the event
physics and/or detectors or for generating files for embedding into
raw data (i.e. particle decays).  There are several included track
selection criteria of general utility which can be specified from the
command line.  In addition, only minor code modifications are needed
to implement custom track selection functions.  How to do this is
described below.

gfilt may be run in one of two modes.  A multi-event file may be
processed in file mode, by specifying an input and output file and a
number of events to process in the command line.  In server mode, a
single event held in a running DSPACK server may be processed.

Note that gfilt does not renumber tracks and vertices but retains the
original numbers assigned by g2ds, so that after filtering the track
and vertex numbers are no longer consecutive.  However, all pointers
are properly updated.

gfilt has a verbose option (-v) and an option for printing usage (-h).
The full list of arguments accepted by gfilt is:

     gfilt [-i input-file] [-o output-file] [-n events]
           [-s server-name]
           [-d(escendents marked also)]
           [-f track-select-function] [-x arg-1] [-y arg-2] [-z arg-3]
           [-v(erbose)][-h(elp)]

The additional arguments are used to customize the filtering.  The
track selection criteria are specified with the -f option.  Up to
three arguments may be passed to the selection function.  Normally, a
selected track and all of its ancestor tracks and vertices are saved.
However, with the -d option, it is possible to specify that the
descendants of selected tracks are also saved.  The available selection
functions are:

          -f 0 (default - no arguments):
               all primary tracks and all tracks, and their ancestors, which
               have detector hits are saved.
          -f 1 [-x z-cut]:
               only primary tracks which decay after z=z-cut (default=357.9)
               and all their descendents are kept.
          -f 2 [-x z-cut-1] [-y z-cut-2]:
               only primary tracks which decay after z=z-cut-1 into a
               neutral particle that then decays after z=z-cut-2 and
               all their descendents are kept.
          -f 3 (no arguments):
               all primary tracks only are saved.

The default function has the following effect on central fritiof
events processed through the full-physics GNA49:

                        before filtering        after filtering
   tracks/event              25,000                  8,800
   vertices/event            6,100                   2,100
   file size/event           10.5 MB                 8.5 MB
   non-point size/event      4.0 MB                  2.0 MB

For DSTs without saved points, filtering halves the size of the Monte
Carlo information saved with a reconstructed event.

To add a custom selection function, one function in source code file
gfilt_main.c (int select_function()) must be modified and the custom
selection function must be added.  The modification to
select_function() only involves adding an additional case to the
switch statement handling the custom argument to the -f option.  The
custom selection function must have the prototype

     int custom_function(track_mc_t*);

where "custom_function" can be any name you choose.  This prototype
should be added near the beginning of the file and the function may be
defined anywhere in the file.  The three additional optional arguments
may be accessed from the variable uarg1, uarg2, and uarg3.  There are
a couple of utility routines for testing whether a vertex is the
primary vertex (int primary_vertex(vertex_mc_t*)), and for testing
whether a track has detector hits (int detector_hits(track_mc_t*)) or
calorimeter hits (int cal_hits(track_mc_t*)).  Use the already
included selection functions as templates for your custom function.