MCFast work

Contents:

Recent changes: Sep 15, 1995
dbin: Users guide and reference. (dbin underlies much of the work discussed here.)
Geometry input: [dbin geometry file] - [Mcfio/XDR geometry output]
Detector/Geometry organization: [Generic geometries] - [Data structures]
Tracking: [Si disks] - [Alternative approach: Volume based]
Data Structures: [Definition via dbin] - [XDR filters] - McFio I/O - f77/C(++) access
Program control: [dbin command mode]
Graphics packages: [Geomview, X11 version] - VOGL
Geomview graphics: [Pictures] - [Approach] - [Detector] - [Event] - [MCFast interface] - [User interface] - [Picking] - [Output]
Status reports: [What's new] - [Todo list] - [7/25/95] - [8/8] - [8/24] - [8/29]
Code: Descriptions and utility programs (xdrrd, dbrd, mcdraw)

---

Recent changes

---

Sep 15, 1995

• All my (finished) code installed in MCFast CVS distribution.
  • Si disks
  • XDR based geometry IO
  • dbin-based data structure definitions (src/dst)
  • XDR IO for dbin-defined data structures (src/dst, src/io)
  • Geomview-based detector and event graphics (src/graph)
  • Utility code for printing geometry, hits, traces (prgeom, prhit, prtrace)
  • Standalone utility programs xdrrd, dbrd, mcdraw (described in this file)
• Standalone programs installed in fnalu:~wenaus/util/, ready for installation in ~bphyslib/util
• Fix to geometry database (real->int) in the HitsOnTrack structure): .db files used with this version have to reflect this correction (see src/dbin/template.db in the CVS archive)
• Include files in inc/event modified for dbin-based structure definition compatibility (where needed). Changes:
  • _s structure name suffix rather than _struct. This change was not made for structures used frequently in .F files to avoid breaking code.
  • single common blocks, with a dummy word to preserve alignment, rather than two common blocks to hold a structure and its count
  • _c suffix convention on common block names.
  With these changes, conversion of a structure to a dbin-based definition (eg. to automatically produce the XDR code to send it to the output file) won't involve changes to the existing common block.
• top level GNUmakefile mods (junk error messages eliminated, mods for src/* files with C routines to compile)
• Mike Procario's vertex fit structures added to dbin-defined data structures in src/dst/mcfdat.dst (and fixes made to dbin.lex to make it work)
• Customizing the dbin-defined data structure list sent to the XDR output: By default, all dbin-defined data structures are written to the XDR output file, because the controller routine managing sending these structures to the file (which is automatically generated by dbin) contains code for all the defined structures, and this controller routine is presently used directly by MCFast for IO on dbin-defined data structures. To modify the list of structures sent, this controller routine has to be modified (ie. IO calls for unwanted structures commented out). The controller routine is src/dst/mcfdatXDRall.c It is a very simple routine, with one line (function call) per defined structure.
• The XDR record type IDs I use are 880 (geometry) and 881 (dbin-defined data structures: structures are all handled under this ID, not individually). The #defines are hardwired in the code. mcfio_GetBlockNam currently reports an 'unrecognized' message for these blocks as it doesn't know about them; this doesn't affect their IO.

---

Geometry input

---

dbin geometry file

The new scheme is more flexible because the coding burden to introduce changes or additions to the geometry is greatly reduced. It is easier to maintain for the same reason; also the amount of code is less, and its clarity is improved through the use of named structures rather than buffers with hardwired indices (eg. buffer(13) becomes sibarrel(i).rmax). It is also coupled to new capabilities in Mcfio geometry output, X-based graphics, concurrent Fortran and C/C++ data access, and GUI-based geometry editing. Documentation is improved because the database file provides a complete, documented specification of the data organization, guaranteed to be correct because the database file itself drives the generation of the data structures appearing in the program.

Dbin uses a file format very similar to the old one, but with the important addition that the dbin file specifies not only the data, but its structure. It simultaneously serves as a data repository and a data definition file. Immediately prior to the declaration ('instantiation') of data objects with their data values in the file, their structure is specified via a 'template' very similar to a C or extended-Fortran structure.

An important feature of dbin is that it supports database access from Fortran and C/C++. Given that MCFast is already a Fortran/C hybrid, and may evolve towards C++, democratic access to the geometry database between the languages with no additional coding overhead (dbin generates C++ code automatically, as it does Fortran code) makes a hybrid program practical and makes it possible to implement standalone components accessing the database (eg. graphics code) entirely in C/C++.

Until recently, dbin used the Strings class from CLHEP to store strings on the C/C++ side. Because of this the Fortran and C/C++ data structures could not be mapped directly onto one another; they were implemented as separate data spaces. This has now been changed: dbin does not use CLHEP Strings any longer, it uses char[] arrays that map directly to Fortran CHARACTER strings. This enabled the unification of the Fortran and C/C++ data spaces, which has now been done.

Together with this, all use of C++ in dbin has been eliminated, such that dbin can be used without a C++ compiler. All use of C++ in MCFast (which was all code associated with dbin) has been eliminated as well. (C++ code may well reappear, however, at a later date!)

The unification of Fortran and C/C++ data spaces means that for databases and data structures defined via dbin, the two languages have completely transparent access to the same data in the same program. Components of the program can be coded in different languages without raising data sharing issues.

Mcfio/XDR geometry output

The dbin database carries a version ID, and the I/O code checks the version ID on an input file against that of the executing program to ensure consistency between a database being read and the code trying to interpret it.

The geometry I/O call in MCFast is in usr_mcfio_output.F.

A standalone program that reads and checks (prints out) the geometry database from the XDR file is ~wenaus/mcfast/local/xdrrd.*. It is in C.

A similar program that reads from the dbin file rather than the XDR file is ~wenaus/mcfast/local/dbrd.*.

---

Detector/Geometry organization

---

Generic geometries

• Box, perhaps with a central hole at the beam line
• Cone, defined by rmin and rmax at low and high z
• Cylinder, a special (simple) case of a cone; distinguished from a cone
• Silicon detectors, barrel and forward, are not so simply represented and are treated as a special case.

The geometry data structures do not make explicit this commonality in the geometries, the recognition of which is important for a volume-oriented approach to tracking, graphics, etc.

In order to view the geometry as a collection of generic volumes with, secondarily, specialized detector attributes I have introduced a generic detector data structure to describe a detector volume which contains

• the geometric shape, as above
• the detector type (muon, ecal, etc.)
• a pointer to the specialized detector structure (not a real pointer, sadly; the index number within the structure, eg. to point to the 3rd absorber in the absorber structure)
• the geometry parameters. Parameters for all volume types are in the structure; they are never all used at once. Could of course be more efficiently and elegantly implemented in C++.
• a 'sensitive detector' flag
• a detector response code, to identify the response model for a detector; in Geant, analogous to a 'sets' declaration associating a hit-generation model with a detector.
• volume fill material

I declare an array of these structures and, looping over all the instantiations of all detectors, fill it with all declared detectors to build a generic master detector/volume list.

There is no provision for a volume hierarchy a la Geant. With the already noted exception of Si detectors, my assumption is that (if we are to keep this truly a fast and relatively simple simulation) explicit volume substructure is to be avoided. Within a detector, volume tracking is handled by plane-to-plane tracking as in the present implementation, with planes defined appropriately for the detector type and configuration, with hit generation provided by an appropriate response model.

The detector substructure for tracking purposes has to be added to this structure; that is, the list of tracking planes for the detector. With a master plane list available as in MCFast now, the plane list can be defined by pointing into the master list.

This structure was created with a modular, volume-oriented, single-pass approach to tracking in mind, but it is also clearly applicable to graphics and that's where I've first used it in a finished (in the 'zeroth version is working' sense) application. The graphics builder loops over the volume list building graphics objects, referring to detector type and specialized detector information for assignment of visibility, rendering attributes, and in the case of Si detectors, access to the Si plane substructure.

Here is some relevant code:

• the include file defining the generic structure
• the routine that fills the structure from the db
• a routine that uses the structure to build the Geomview geometry

---

Tracking

---

Si Disks:

• Si disk planes added to geo_trkorder
• Si disk plane detection added to trk_trace_forward
• trk_find_sidisk_plane added for hit detection
• trk_make_sidisk_hit added for hit generation.

Alternative approach to tracking:

• Starting point is master list of detector volumes (see previous section) which references the existing specialized detector structures and the master plane list.
• For all detectors except Si, well-defined volume boundaries exist. For Si, plane list is used to determine approximate boundaries for nearby volume binning (see next point).
• Using the volume list, the detector is subdivided into eta/radius bins and for each bin, a list of nearby volumes is built. Or, as grid boundaries are used as tracking planes under some conditions, use z rather than eta (achieve finer granularity near IP via non-uniform bin size or discrete changes in bin size).
• All tracking is done to planes in a plane list, as in the present version, using existing move routines.
• The life of a track, from birth:
  1. Whaa!? Where am I!? What does it all mean? Am I in a volume?
     • Nearby volume list for current grid element is queried; 'am I inside' query to volumes in list.
  2. Not in a volume?
     • Nearby volume list defines local plane list: the volume boundaries, except in the case of Si. If Si is a nearby detector, its constituent planes go on the local plane list (it does not have a volume boundary).
     • Add grid element boundaries to plane list.
     • Track until a volume is reached or grid cell is exited; on grid cell exit obtain new nearby vol list for new cell and repeat until volume is reached.
     • By adding the grid cell boundaries to the plane list when tracking to the next volume, cases where the next volume is far away are handled properly.
  3. Now in a volume...
     • Detector characteristics, parameters obtained from the generic and specialized detector structures (associated plane list, fill material, etc.; the 'context' info for tracking).
     • Tracking within volume is performed using volume-internal tracking plane list and the volume boundaries.
     • Hit generation, detector response determined by response model associated with the detector.
  4. In a Si detector or cone (awkward detector edges)...
     • Maximum step size is defined within the volume; step size is, say, 2x plane-plane separation.
     • Quick, approximate estimation of distance to closest detector boundary is maintained. Or, in initialization, 'safe zone' is calculated for the detector; within this zone, boundary is 'far away'. For a cone, safe zone could be defined by binning in z and defining safe rmin, rmax in each bin.
     • If distance is well above the step size, or location is within safe zone, don't have to check for volume exit; for Si, don't have to include neighbouring detector planes in the plane list.
     • Thus, faster tracking through most of the volume by avoiding boundary considerations.
     • If near boundary, for Si, have to add to the plane list the plane lists (or volume boundaries) of nearby detectors, and the grid cell boundaries.
  5. Reached volume boundary...
     • Back to (2) above: find current grid cell, nearby volume list,...

This approach can be layered over the existing code for moving plane-to-plane. It integrates treatment of the detector into a single-pass tracking procedure that doesn't distinguish at the tracking engine level between central and forward. Tracking differences are handled by using detector volumes to set up the detector-local context.

---

Data Structures

---

Definitions via dbin

To date, the hit data structure and substructures ( hit_trk) has been defined using dbin, and is output to the XDR file using the dbin-generated filter and interface code.

Advantages of using dbin to define data structures:

• XDR filter code and McFio interface code is automatically generated, making it very simple to add data structures to the McFio output
• interface code for both Fortran and C/C++ is generated, giving all these languages transparent access to the data, all referencing the same data space
  • structure definitions need be maintained in only one place, the definition file
  • .inc and .h files don't need to be independently maintained
  • consistency between files guaranteed
• one-stop shopping for the data structure definitions -- a self-documenting dbin file (or file set) -- makes finding structure definitions easy

Fortran, C and C++ access

XDR filters and McFio I/O

The auto-generated XDR filter code does not address data compaction prior to XDR output. This would have to be implemented via user written code to move data from the standard structure to a compactified structure (separately defined via dbin) which is then output by dbin generated code.

The present scheme in which dbin generates custom code for the defined set of data structures offers no support for changes in the structure of the defined types. An alternative implementation is in the works, in which intead of generating XDR code, dbin generates for each structure an array of keywords specifying its makeup. These keyword sets are saved in the header of the XDR file. They make the data structures in the file self-describing. When the XDR file is read, the keywords drive an interpreter to properly decode the data. Thus XDR files containing old versions of data structures can be read with up to date software.

Data structure code is presently in ~wenaus/mcfast/local/dst/ .

---

Program Control

---

dbin command mode

---

Graphics Packages

---

Geomview

Pros:

• Good set of rendering features. 3D illuminated solids.
• Fully controllable via external commands.
• Geometry as well as commands are entered as ASCII from STDIN. No need for a subroutine library.
• Reasonably good GUI, but not so good that the next item isn't important
• A user-defined GUI (eg. based on Tcl/Tk) can easily be implemented to replace the provided one
• Picking is available, with feedback of pick info to an external program, eg. to provide info screens on picked objects
• How objects are drawn can be changed on the fly by the external program providing the graphics; eg. in response to a zoom, external program could increase the phi segmentation of a rendered cone.
• Multiple graphics windows are supported.
• Postscript output is available, and works for relatively elaborate geometries (eg. CDF)
• Well documented (manual.ps and man pages) and lots of examples.
• Seems to be actively used and well maintained by its developers (U Minn).
• Size of the complete source distribution, fully built, is over 100 MB. But then it is a sophisticated package with lots of examples.

• No transparency. According to the doc, not only is transparency not available in the X version, it does not work under GL on SGIs (or 'most' of them, at least) either.
• Cones are not primitives. Must be built from planar pieces.
• X interface is incomplete. eg, 'File open' doesn't work.
• Postscript driver makes mistakes in which planes are behind which. Sometimes views that are fine on the screen generate crashes when postscript output is attempted.

• Zoom, translate, rotate slow on a color X terminal. Usable as-is for full-detector viewing
• Close-in manipulation is nightmarish with present tools. Very slow refresh, very fast translation/rotation rates == constant overshoot
• Geomview's command support would make a simple GUI (Tcl/Tk?) to address this problem easy to implement
  • pick objects to translate to
  • pick re-center point
  • discrete zoom steps
• Deficiencies:
  • Very awkward (and not done in present implementation) to subdivide the detector into objects (subdetectors, hits, tracks)
    • Geomview deposits every object centered at the origin
  • No way to make cross sectional slices to see interiors
  • Tracks (polylines) vanish at small angles
• Even setting speed aside, certainly can't supplant Inventor etc. for sophisticated 3D apps
  • and such commercial tools are probably a lot more pleasant to work with
• A very good low-manpower debug/prototyping tool
• With more manpower, clever use of interactivity and well-designed view options could make it powerful and responsive

VOGL

---

Geomview-based MCFast graphics

---

Picture Gallery

Approach:

• User code is plugged into MCFast at the initialization stage (after the geometry is read in, of course; MCFast needs an official post-geometry user init routine. I added usr_setup for this purpose.)
• This code scans the generic detector geometry structure (see preceding discussion on geometry) and builds 3D graphical representations of detector elements.
• If events are processed, trace and hit graphics are generated and written to the file.
• The geometry and events are written as ASCII to an output file, geom-graph.out.
• Geomview is then run with this file: geomview geom-graph.out.
• (buggy) postscript output available

Also provided is a standalone program, , that reads a dbin geometry file and sends the corresponding graphics output to STDOUT for piping to Geomview. It is used as follows:

The standalone program (which is in C) is a first step towards a proper implementation of Geomview-based graphics, which should look something like this...

Planned implementation:

• Standalone C or C++ program reads detector geometry from database
  • Because dbin provides auto-generated C code, full database access is already available
  • Reason to use C rather than C++ is the Geomview distribution provides the asynchronous read code needed to receive feedback info (eg. pick info) from Geomview. I wouldn't know how to do it in C++.
• The program reads events from McFio
  • McFio C port is already there: cf. the xdrrd standalone program that reads the geometry from a McFio file.
• Program is started by Geomview as a module. Interaction is via STDIN, STDOUT ASCII.
• Provide simple GUI interaction via Tcl/Tk (or something else?)
• Superpose events from McFio stream over the detector

Desirable features:

• modular control over graphics via named groupings of graphical elements (tracks, hits, subdets,...)
• 'save current view'
• view selectable from standard list or user-defined views
• selectable dynamic views ('look along this track')
• guiding principle: most graphical operations a user will want to do can be implemented via picks and clicks, rather than the user having to manually roll and swim around with view controls. eg.
  • align the line of sight along this track
  • look at this track where it enters the ecal
  • step along this track, from its point of origin to its decay, from a viewpoint 30 degrees and 1 meter away from the current trace point
• build up-front thinking about optimal representation of information into predefined, easily selectable views (best exemplified by hans dreverman's aleph graphics presented in the workshop)
• informative hit objects
  • include piece of the hit plane around the marker
  • pickable
  • representation reflects characteristics
• how to deal with 3d representation of events in the absence of transparency?
• how to do 2d?

detector graphics:

• 3d solid detector model, no transparency
• very aesthically pleasing on the screen
• 1st quadrant cutaway for interior view (hard wired in graphics generation code)
  • no geomview support for cutaways, so had to do it myself
  • clearly not appropriate for a true event display program, but gets this program's job done
• opaque detector can be turned off interactively to fully view tracks and hits
• standalone program provided to generate graphics from a .db file (see above)

Event graphics:

• Traces (polylines) with color keyed to particle type (e=yellow, mu=green, gamma=blue)
• Detector hits (3D diamonds) with color keyed to detector type

MCFast interface

User interface

Geomview's ASCII command interface makes it easy to implement a custom GUI/control program, eg. via Tcl/Tk, for customized GUI control and event input. This hasn't been done.

Picking

This all requires that the detector be subdivided by objects (subdetectors, hits, tracks, etc.) As mentioned above, this is made difficult by Geomview's behaviour: when an object is installed in the graphic, Geomview ignores its absolute position and deposits it centered at the origin. Could be resolved by figuring out from where Geomview has moved it, and moving it back. Not trivial, and not done.

Geomview provides the C code needed to handle in the control program asynchronous ASCII pick and command feedback coming from Geomview.

Output

---

To do

---

To do:

• volume based tracking
• self-describing XDR data structure output
• look at dbin 'command' apps in MCFast
• new STRUCTURE section of database for constants. Look at XDR I/O of structures; needed to save run parameters in database.
• modularize graphics objects by detector
• add wireframe detector polylines to graphics

Done: (reverse chronological)

• data struct migration to dbin definitions/compatibility
• geomview-out card for graphics output control
• trace array added to dbin-defined structs and XDR output
• 'structure' code in dbin updated. A structure is a template with only one instance, values declared within the structure definition.
• hep_trace structure integrated in XDR output
• XDR output of arrays: VARIABLE declaration option after the array declaration stipulates that the most recent integer is to be regarded as containing the number of valid elements.
• implement hits output to McFio
• test data struct output to XDR. Nested structures OK? Yes.
• standalone quickie detector graphics pgm 'mcdraw' written. mcdraw geom.db | geomview to display geom.db geometry.
• C++ completely eliminated from dbin and MCFast. Eliminates weird sporadic crashes in destructors on program termination.
• hits added to graphics. Diamond representation. Color keyed to detector type.
• tracks (traces) added to graphics. Color keyed to particle type. Represented such that detector display (faces and edges) can be turned off for full view of tracks and hits.
• Fortran and C data spaces in dbin unified: C structures map onto the Fortran common blocks. One now has simultaneous access from the two languages (and C++) to dbin-defined databases and data structures. Cray support included.
• dbin and associated code modified to use char[] rather than the CLHEP Strings class for strings. CLHEP no longer needed.
• Si disks added to tracking
  • Modified: geo_trkorder, trk_trace_forward
  • New: trk_find_sidisk_plane, trk_make_sidisk_hit
• central, disk Si graphics
• Si disks added to dbin geometry
• convert D0 geometry
• Geomview based detector graphics
• install Tcl/Tk and do Hello World GUI
• implement char string handling in XDR code
• test geom output to XDR
• C++ routine to read McFio XDR file and check geometry
• C++ routine to read dbin database and check C++ geom data structures
• data structure def'n support with XDR filter generation added to dbin
• CDF run 2, BTeV9, CDTeV geom files converted to dbin
• geometry input converted to use dbin
  • geo_fill_*.F replaced with load_*.F
• pre-declared template array sizes in dbin
• arrays within templates in dbin
• dbin converted to use VMS Fortran structures

---

What's New

---

What's new in this document:

• everything

---

Code

---

Sep 15: all code is now installed in the MCFast CVS archive. The utility programs (dbrd, xdrrd, mcdraw) are in fnalu:~wenaus/util/, ready for installation in ~bphyslib/util.

• xdrrd: Standalone program. Read and print contents of a McFio XDR file. At present it dumps information on the geometry, hits, and traces. Usage: xdrrd fname.xdr
• dbrd: Standalone program. Read and print geometry database from a dbin file. Reads the dbin file into the internal program data structures and calls a standard geometry dump routine (that is in the MCFast distribution) to dump the geometry. Usage: dbrd geom.db
• mcdraw: Standalone program. Read a db file and send the ASCII graphics commands to STDOUT for piping to Geomview. Usage: mcdraw geom.db | geomview
• dbin: src/dbin directory. Contains the dbin utility and dbin generated geometry code. Managed by a GNUmakefile (only used for rebuilding the dbin application when the lex source changes). When any geometry templates change, dbin template.db has to be run from this directory to regenerate the interface code.
• data structure code: src/dst directory. Contains the data structure definition file, mcfdat.dst, and the files generated when this file is run through dbin. Managed by a GNUmakefile. When the dst definition file is changed, do gmake in this directory to regenerate everything needed (header files, XDR code etc.)
• *.db geometry template files: db/ directory.
• *.db detector geometry files: example directory. Geometry definition files for CDF, D0, etc.
• template.db src/dbin directory. Master template file for definition of new detector geometries. See dbin item above re: changes to subsystem templates.
• mcfdat.dst: src/dst directory. Master data structure definition file. Run gmake in this dir when this file is changed to regenerate auto-generated code.

Add to doc:

. sample graphics
- document procedure for migrating data structure to dbin definition
- dbin data structure support discussion
- discussion of dynamic self-describing XDR files