MCFast work

Torre Wenaus, LLNL
Jul-Sep 95


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


Geometry input

dbin geometry file

MCFast now supports geometry input via an ASCII database based on the dbin DataBase INput tool. As before, in the dbin scheme the geometry is specified in an ASCII file. A user can easily switch between the old format, which is still supported, and the new. If the geometry file has a suffix of .db, it is interpreted as a dbin file. If its suffix is .geo, it is interpreted as an old-format 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

Dbin automatically generates XDR filter and associated code to implement XDR I/O of the geometry database. A small amount of code interfaces the XDR code to MCFast's McFio I/O such that the database is written out as part of the McFio file header. Thus the geometry is carried along with the data, ensuring consistency between the two.

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

The detector subsystems defined in the geometry database can be grouped into a short list of mostly generic geometrical types:

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

At present this duplicates geometry information found in the specialized detector structures, but in this approach the geometry parameters 'belong' in this structure, which contains the generic elements of a detector spec. The specialized detector structure should contain only specialized info for that detector type, and should point to the generic structure for the geometry parameters (just as the generic structure points to the specialized structure).

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:


Tracking

Si Disks:

Si disk handling has been added to the tracking; it was not previously supported. Changes made: R, phi, U and V planes are handled. Stereo angle rotation is relative to the wedge radial center line; positive in the +phi direction.

Alternative approach to tracking:

A volume-based tracking approach, designed as a layer over the present plane-based approach:

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

In addition to its original application as a geometry database, dbin can be used to define the data structures used internally by the program, ie. the MCFast structures in the inc/ include files. Templates like those used to define geometry data structures are used here to define very general data structures which can include nested structures and multi-dimensional arrays.

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:

These points are discussed further below.

Fortran, C and C++ access

As for dbin geometry databases, the Fortran and C data structures map to the same data space in the program. Data structures can be referenced transparently from either language using their standard names. Fortunately, Fortran strings and C char[] arrays use the same memory representation, making this possible. Nested structures are also fully supported. On machines tested so far, at least, nested structure storage is identical for Fortran and C so direct memory mapping works.

XDR filters and McFio I/O

Custom XDR filter code is generated by dbin for the defined data structures. A master routine is generated that, without modification, will cause all the defined data structures to be saved to the McFio output stream (via a provided interface routine to McFio). The master routine can be edited to select the set of data structures desired on the output file.

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

dbin can be used to define program control parameters and commands. The application of this to MCFast hasn't been explored yet, but it would carry advantages: eg. via dbin's XDR output facilities it would be easy (and valuable) to record run-time parameters and program control commands on the XDR output file.


Graphics Packages

Following the visualization workshop I tried out a couple of the X-capable graphics packages discussed in the workshop that sounded promising. My motivation is to have basic detector and event graphics on an X screen, for the convenience of the many that don't have an SGI on their desk. To quote one of my favorite lines from the meeting (Perl, SLAC), a graphics box on the desk is worth ten down the hall. Not that the box down the hall is unimportant, but for the person using (or not using) graphics as a tool supporting a primary task (reconstruction development and debugging, detector design, etc.), a 10:1 ratio of relative importance is probably about right.

Geomview

Explorer-like package that runs on X. Original version is SGI GL only, and the X port has its deficiencies, but is very functional.

Pros:

Cons: Further observations after some experience:

VOGL

Very Ordinary Graphics Library. Very well named. A low level graphics library with C and Fortran bindings. GKS-like. Definitely not what I want. If you want to look at it, I built the SGI version and examples at ~wenaus/graphics/vogl/.


Geomview-based MCFast graphics

Picture Gallery

Approach:

Current implementation: Standalone program:

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:

mcdraw cdf.db | geomview

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:

Desirable features:

detector graphics:

Event graphics:

Currently implemented:

MCFast interface

None, at present. MCFast generates a graphics file which can be read by Geomview. All tracks, hits generated in the MCFast run wind up in the display.

User interface

Geomview provides a basic GUI interface. Translation, rotation, zoom, free flight around the graphic are supported. BUT speed is not controllable so navigating relatively small detectors is difficult. Interactive control over rendering is available; eg. display of surfaces and edges can be turned off so hits and tracks can be seen in their entirety.

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

Geomview supports picking of graphical objects. Information on the picked objects is transmitted (as ASCII info) back to the C program acting as a controlling module for Geomview. This program can then take actions (popping up info on a picked track, zooming/translating for a good view of a picked object, etc.) based on the picked object.

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

Geomview supports postscript output. But, it is buggy. Some images are OK, but when planes are close together, their visibility ordering is often wrong. Sometimes trying to save postscript for a perfectly good screen view crashes the program. Screen dumps using xv can produce pretty good quality images. Turn off dithering in geomview (on the camera control panel). Set the background color to white (in one of the control panels). Set the image to as large a size as possible (do this after manipulating the view; motion is slower with a larger window). With xv, grab and crop the window. You may want to try the smooth option. Save it as postscript bitmap (or gif, or whatever) output.


To do

To do:

Done: (reverse chronological)


What's New

What's new in this document:


Code

All my code is in ~wenaus/mcfast/local/... on the fnpspx machines. (Geomview and VOGL are in ~wenaus/graphics/... .)

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.


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