WARNING: This is an old page. No warranty is given for its correctness.

This page describes HepGismo, one of the predeccessors of Gismo 2.0.

HepGismo -the CLHEP version of SLAC's Gismo

Last update:index.html,v 1.2 1994/04/19 23:01:50 burnett Exp

Toby Burnett

Introduction

HepGismo is a version of SLAC's Gismo to which I have made extensive modifications, including a conversion to use CLHEP. Unfortunately, the NeXTStep (3.1) GUI used by the gismo collaborators is not consistent with the use of C++ templates.

The code, which has numerous improvements (IMHO) in the particle physics part of gismo, may eventually be merged into gismo. This cannot happen as long as gismo demands the NextStep environment and NeXT is out of step with the C++ standard.

Availability

The code, in tar'ed and gzip'ed form, can be found here as the file hepgismo.tar.gz. Those with access to the SLAC unix system can do a cvs checkout by the sequence 
	setenv CVSROOT /usr/local/gismo/repo
	cvs export hep
This will create a directory hep containing all the source. The installation notes should then be consulted for building a system. Finally, local users can see the code and try out the test programs by looking under ~burnett/hep.

Notes

The following notes were written by Paul Rensing for gismo, but are applicable to HepGismo as well

The code: a tour

This a description of the HepGismo code, organized according the the structure of the code, containing links to the directories containing all the code, as well as specific source files. When examining subdirectories, be aware that you must use the "Back" button to return; The "parent directory" link works, but then the server gets confused, and will not allow you to return to a subdirectory.

The kernel

All the basic particle properties, particle physics, geometry, and propagation is in the kernel. A list of the appropriate subdirectories follows.
geometry
The geometry-related classes, base classes are Also has Track, a sequence of Rays used to store an actual trajectory.

Note that at the moment I only am using gismo's Box. Since hepgismo uses gismo's definition of volume, all of the gismo geometry project can be easily copied. info break

medium
Defines as well as various simple detectors as subclasses of Medium.
particle
Classes here support particle physics:

A MCParticle subclass, Generator, is a data member of BaseApp, and is responsible for generating events.

See test/decay.cc and test/mscat.cc for test programs.

support
Collect various suport classes, including
view
The 3-d wire-frame graphics. Viewable is a base class for any class that "draws itself"; VwControl manages a display list and display commands; VwDraw is an abstract base class for device drivers.

GDisplay is a subclass VwControl, that provides display control. It is subclassed again to generate the actual display, and handle interactive viewing.

Interactions in matter

Each particle data entry in the PDT has a pointer to an Interactor. The base class Interactor handles multiple scattering and energy loss, and defines virtual methods to implement interactions. These subprojects, which are not part of the HepGismo kernel, are:
egs
The C++ implementation of EGS4. The EGS "particle" is encapsulated by the class EGS, which handles all EM interactions. The interface is EGSInteractor, a subclass of particle/Interactor. Material properties and cross sections are in the class PEGSData, a subclass of medium/MatData
gheisha
The Gheisha Interactor, implementing hadronic interactions. A thin layer, the Gheisha class wraps the Gheisha fortran code. The Gheisha system (also used by GEANT) contains a lot of fortran, that I do not include in the basic source distribution. If you want to use it, copy or link to the .f files in Gismo.

See the test program test/mscat.cc to see how the above interactors are defined and used.

Application level and GUIs

application
Application-level support, especially the BaseApp class which is the base class for application classes. One useful subclass is SlabApp which makes it easy to define planar geometries. A test program that constructs a simple detector is testapp.
gsuit
Interface to SUIT version 2.3, the Simple User Interface Toolkit from the University of Virginia. This provides a nice GUI that is portable across unix (X11), Windows, and the Mac. Contents are:

Test Programs: the test directory

This suite of programs tests progressivly more complex aspects of particle physics and the application environment.

CLHEP: Class Library for High Energy Physics

 This version of Gismo uses CLHEP version 0.13. The local list of .h files can be found here. Classes used are:

go to top

Gismo

The 23 March 1994 release of Gismo (0.4.1) is here. Documentation (transparencies from Bill Atwood's lectures) corresponding to the released version is here. A paper I wrote for the MC93 conference is here. Alan Breakstone has written a very detailed explanation of the geometry project that is available from him on request.

Authors of Gismo
Bill Atwood
(SLAC) atwood@ebnextk.slac.stanford.edu
Alan Breakstone
(U of Hawaii) alanb@bzero.slac.stanford.edu
David Britten
(McGill U.) brit@wagner.physics.mcgill.ca
Toby Burnett
(U of Washington) burnett@quark.phys.washington.edu
Paul Rensing
(CERN) rensing@slac.stanford.edu
Gary Word
(SSCL) word@pdsf.ssc.gov

go to top

Major changes from gismo

The major improvements are:

More specific comments follow.

The view project

I have eliminated several obsolete classes and headers. The interface classes are Viewable, VwAxes, VwControl, and VwText3d. Internally, View3D now inherits from, rather than containing a pointer to, VwProject.

the particle project

EMInt has been removed, replaced by EGSInteractor in the egs project.

PDT now has a new method, static PDT* PDT::createPDT(Interactor* =0, Interactor* =0) which is intended to replace the static function of the same name, providing a mechanism to initialize the PDT with our built-in list of particles, and flexibly specify Interactors to be used for electromagnetic and hadronic interations. (This is discussed further under egs.)

GParticle now inherits from HepLorentzVectorF, which gives it all the four vector properties that it used to get from FourVec. It has a new method, void scatterBy(double theta, double phi), a rotation not supported by the clhep three vector classes. GParticle, MCTrack and MCVertex have been combined, and made compatible with the clhep particle. Interactor has been extensively modified, and its relation to MCParticle changed. Its interface is: 

   virtual int interact(GParticle*,const Medium*);
   // interact the particle in the Medium

   virtual float interactionLength(const GParticle*,const Medium*);
   // return the interaction length for the particle in the Medium

   virtual void afterStep(float, GParticle*, const Medium*);
   // peform after step modification of particle: lose energy and
   // multiple scatter

   virtual float maxStepSize(const GParticle*, const Medium*);
   // determine maximum step allowed. Determined by eLossFraction
   // and Medium::maxStep()

   virtual float ecut(const GParticle*, const Medium*);
   // return minimum energy (KE+rest) of the particle allowed

   static float eLossFraction;
   // the maximum energy Loss allowed for a step (user-settable)
This takes the calculation of the step size out of MCTrack, and allows an Interactor subclass to control the step size and energy cutoff, which is used by egs.

The afterStep above has a more accurate calculation of the multiple scattering.

The Medium project

The class Material has been moved to this project, and its dependence on egs removed. It now has a function to calculate a default energy loss for the material.

A new class MatData allows an Interactor to associate additional data and methods with materials. The function Material::hatch reads a file, in PEGS format, to define the mixture. It then constructs a list of MatData objects attached to the material object. See egs for more discussion.

The egs project

This has been extensively restructured, as a part of the new implementation of Material and MatData. The previous PEGSMaterial has become a MatData subclass, PEGSData. When the EGSInterator constructor is run as part of the PDT initialization, Material is told about PEGSData. Then, when each new material file is read, a new PEGSData object is created, by making a copy, to read the cross section data.

The only interface class is now EGSInteractor.

The EGS4 routines edgeset and fixtmx, which implement fluorescence and a scheme for adjusting the step size, respectively, have been added.

The gheisha project

The class Gheisha is an adaptation of Atwoods's HadInt. It has an associated MatData class, GheishaData, to calculate cross sections.

The math project: moved to support

All of these classes have been converted to simply inherit from the corresponding clhep classes, implementing any additional functions required by the previous interface.

The application project

A new BaseApp class is equivalent to gismo's GismoApp. It was defined to simplify the eventual merge, since GismoApp has too many GUI-dependent features. It also use the unix signal facility to trap control-c and floating point exceptions.

I have defined a SlabApp class, inheriting from BaseApp, that I find very useful for studing showers in layered detectors, and which I optimized for execution speed, gaining a factor of four. This is a category of code that is not strictly part of Gismo, since it is not required by the kernel, and would not be a part of the standard GUI application. Thus I don't think it really belongs in the project, but would like to have some mechanism for making it available.

The support project: persistence

This has been essentially removed, to make way for eventual use of the the very similar CLHEP scheme. All references in the code have been bracketed with #ifdef __STREAMABLE_Hto identify them for conversion.

go to top

Installation of Gismo

Introduction to Imake

Imake is a standard tool from the X Consortium which builds Makefiles out of Imakefiles. The idea was to simplify the writing of the local Imakefiles and to provide a platform-independent way of specifying in the dependencies of a project. Imake is (essentially) the C preprocessor, with the computer architecture compiled in. It reads a "template" file, which in turn includes configuration files from a search path of directories. At the end, it includes the file "Imakefile" from the local directory, and expands all the macros it knows. The result is a Makefile which is run by make.

If you do not have the imake program, first check that you really do have your X windows binaries in your path. If it really is not on your system, you can get imake as part of the X distribution. You will need to build imake and install the configuration files that come with it.

See notes on installation before building anything for an installed copy of Gismo.

Gismo's Imake

The Gismo Imakefiles use the environment variable ARCHNAME to determine where to put binary files, such as .o files and libraries. Note that this environment variable does NOT determine the actual architecture (that is compiled into imake); rather, it determines the name of the directories where binaries are placed.

To build Gismo from scratch, do the following steps.

  1. Make sure the environment variable ARCHNAME is set to something sensible. At SLAC, this is set by the default .cshrc script with a line like 
       setenv ARCHNAME `/usr/local/bin/archname`
    The script "archname" is different on each architecture.
  2. Make sure that your site's X windows binaries are in your path. In particular, the programs imake and xmkmf need to be present. If you have imake but no xmkmf, find out where the X configuration files are (typical places are /usr/local/X11/config or /usr/lib/X11/config) and use in step (3).
  3. Build the top level Makefile. Use the command 
    	    bin/mkmf [-x ]
    This will create a file "site.config" if it does not exist and then create the top level Makefile. "[-x ]" is an optional parameter to specify where the X configuration files are (see step (2)). (Note that you don't actually type the "[]" characters!)
  4. Build the project: 
    	    make Makefiles
	    make includes
	    make depend
	    make all
    If you would rather build debug libraries, use: 
    	    make Makefiles_debug
	    make includes
	    make depend_debug
	    make all_debug
If you have troubles, look in Imake.config for parameters that might be set wrong for your site. Type "make -f Makefile help" for some help on the make targets.

site.config

Imake.config, which is a global project customization file, includes the file site.config at the end. If site.config does not exist when mkmf is run, an empty copy will be created. If you need to modify variables which are in Imake.config (eg. because hippo include files are in a different place on your system), put the new definition in site.config and it will win. You should note that this file is only needed when running imake to create Makefiles ("bin/mkmf" or "make Makefiles"); therefore, if you compile on very different systems in the same work directory, you can create two site.config files (with different names) and use a symbolic link (ln -s) to point to the correct one when building the Makefiles.

Installing Gismo

Gismo's Imakefiles include an install target which should handle all the work for you. Look through Imake.config to see where the different parts will be installed; if you need to change these, put the correct definition in site.config. Note that you should set the PEGS4 data path in Imake.config correctly BEFORE compiling Gismo (if you screw up, fix Imake.config/site.config, rebuild the Makefiles, and recompile medium/MatData.cc)

The Imake install target will concatenate all the individual libraries into one large library call libgismo.a.

When a user runs into problems with his code, it is very frequently necessary to step into the Gismo kernel to find the bug, even when the bug is in the user's code. Therefore, it is recommended that the installed copy of Gismo be compiled "-g -O" as a compromise on speed and ease of use (if you have the space for two copies, you can do that). This is done with the following set of make commands (see step (4) above). 

	    make Makefiles_debugopt
	    make includes
	    make depend_debugopt
	    make all_debugopt
	    make install_debugopt

Adding files

If a developer adds a file to the GISMO project, the Imakefile of the appropriate directory should be modified to include the file. Then repeat step (4) above to rebuild the library. The "make Makefiles" and "make depend" steps can be executed from the changed directory to save time, but be careful of executing the actual build from the subdirectory. go to top

Developer Notes

Since Gismo is installed as a single directory for the user, the developer is left with a question of how to operate. Here are my suggestions.

Test Programs inside the Gismo Hierarchy

This section describes how to build a test program as part of the gismo hierarchy. However, if the code is not part of the Gismo kernel (apart from temporary test code), I strongly recommend that you read README_USER and the section below and build your project outside the Gismo hierarchy.
  1. Always do the initial "bin/mkmf" and "make Makefiles" from the top directory. This gets all the directories in the Makefiles correct. Once the tree of Makefiles is built, you can work in an individual directory.
  2. If you want to build only a particular library (eg. application), cd into that directory and build from there (but see (1)).
  3. If you want to build a test program using a same set of your libraries plus the installed library, you can modify site.def in the top level directory to set the appropriate library list (site.def does *not* get checked into CVS and so is safer to modify than Imake.config or an Imakefile). You will want to set the make variable GISMO_LDLIBS to have the right value; for example, in site.def, you could put: GISMO_LDLIB = -lapplication -lgismo You may also have to add a -L flag to indicate where libgismo.a is if it is not in a "standard" place at your site.

Programs outside the Gismo Hierarchy

See the user instructions to see how to write an Imakefile for a project which uses Gismo. If you are a developer and want to use some or all of your libraries, use the make variables listed below to add the extra libraries and search directories; they will be put ahead of the predefined Gismo variables. 
     APP_CCINCLUDES       - your special -I flags
     APP_CCLDFLAGS        - your special -L and other flags
     APP_CCLDLIBS         - any extra libraries
You can also use the "flags" and "libs" fields in the appropriate build macros (eg. MakeCCProgram(name,libs), ProgramCCModuleWithFlags(name,module,flags) ).

Anomalies ....

The Fortran standard for gismo is to use f2c. Unfortunately when using this with the debug option the #line compilier directives sometime screw up. The "fix" is to overwrite STANDARD_FFLAGS so that you always get the -O option. This is done ONLY in the /gheisha directory's Imakefile. go to top

User Notes

Header Files

Gismo header files should be included using the format: #include "gismo/GismoApp.h" The <...> form is fine as well.

At SLAC, the include files are installed in /usr/local/gismo/gismo, and therefore, you need to include the flag -I/usr/local/gismo when compiling.

If you have a number of files with the old style #include lines, you can use the script /usr/local/gismo/bin/fixIncludes (also in top level of gismo project). The syntax is 

   > fixIncludes a.h b.h
   > fixIncludes *.h

Libraries

At SLAC, Gismo is presently installed as one library (libgismo.a). It is located at /usr/local/gismo/lib.xxx (where xxx is the usual name for the architecture) and there are links from /usr/local/lib. Therefore, you only need the flag -L/usr/local/lib when linking.

Remember that Gismo does require the standard Fortran library (listed after -lgismo): 

	AIX             -> -lxlf
	Sun, Next (f2c) -> -lf2c

PEGS Files

The PEGS data files from the project have been installed in /usr/local/gismo/PEGS4. This directory should be automatically search when Gismo is looking for a PEGS file. If you want Gismo to look somewhere else first, use a call like 
	Material::addPath("/u/eb/rensing/PEGS4");
to prepend a directory to the search path.

Imake System

If you want to use the Gismo Imake macros, someone on your system will have to install them correctly. At SLAC, the program /usr/local/gismo/bin/mkmf (or bfmkmf in the BFactory directory) will generate the top level Makefile. From then on, you can use the Makefile targets (make Makefile; make Makefiles; etc). Note that the Imake macros use some scripts (makedepend, libdepend, fdepend) which need to be in your path. At SLAC, they are installed under /usr/local/gismo/bin.

Some macros, of the form UseXXX(), are available to automate the use of packages. Currently, there is UseGismo(), UseHippo(), UseCLHEP(), and UseCheetah(). Below is a sample Imake file which uses these macros. 

XCOMM
XCOMM Gismo test directory
XCOMM

#ifdef InObjectCodeDir

/* specify where libparticleID.a can be found */
APP_CCLDFLAGS = -L$(TOP)/lib.$(ARCHNAME)

/* specify where my include files are (these are links) */
APP_CCINCLUDES = -I$(TOP)/include

UseGismo()
UseCLHEP()
UseHippo()

ProgramCCModule(TestBarForDIRC,TestBarForDIRC)
MakeCCProgram(TestBarForDIRC,-lparticleID)

#else

MakeInObjectCodeDir()

#endif

Also, when using the Imake package, you will need to have some programs/scripts in your path; in particular: imake, makedepend (from X11R4 or later, or the script from the Gismo distribution), fdepend (if you use Fortran), and some scripts provided with the X distribution (eg. mkdirhier).

THB