TRYING GEANT4 EXAMPLES
Geant4 toolkit comes with a set of examples of various complexity; they are part of standard distribution tarball and are located in the hierarchy of subdirectories under the /examples directory.
As any other area of Geant4, the examples domain periodically becomes a subject of updates, improvements, or even certain restructuring.
In this document we will focus on the most current structure, which has been in effect starting Geant4.9.5 release cycle.
Starting Geant4.9.5 release cycle and onwards, we would like to advertise the /examples/basic group of applications as the best beginning point for new Geant4 users. Also, we would like to stress that the application build system has transitioned to the new cmake-based machinery, as already mentioned in the Geant4 Versions and Environment Variables document. To cover the latest developments, these materials will includes useful links and tips, to facilitate the learning curve.
For historical and practical reasons we will also preserve some tips and suggestions applicable to earlier releases of Geant4.
Materials are organized in the chronologically reverse order.
To access Examples documentation at the CERN web site follow this link.
FROM GEANT4.9.5 and ONWARD
As it has been mentioned above, we would like to recommend that new Geant4 users start their experience with the toolkit frim the /examples/basic group of applications.
For illustrative purpose it is good enough to consider /examples/basic/B1; the process of building and running is similar for other examples.
Geant4 relies on cmake to build core package libraries and applications. All standard examples have been outfitted with CMakeList.txt scripts for this purpose. However, the Geant4 team has also implemented a collection of cmake-based functionalities, to wrap up commonly used groups of cmake directives; this is way a user may see in a CMakeList.txt certain directives that do not look like "plain cmake".
Changes in the use of environment variables may be summarized as follows:
Geant4 native documentation on this matter has been improved recently, and provides a good amount of information on the cmake scripts and functionalities; it is highly recommended.
This document only highlights several practical details and steps in the procedure of building an example.
The step-by-step procedure is very well described in subsection 3.2.1 of the Geant4 Installation Guide; users are strongly advised to go through those materials, as they also provide various details of the Geant4 specific, cmake-based scripts.
Here we would only like to stress that the Geant4 cmake policy strongly encourages so called out-of-source build. In particular, if a user tries to execute cmake in the same area where the example code is located, the resulting Makefile may conflict with the legacy GNUmakefile, and the build procedure will not work correctly.
Note that older groups of examples (/novice, /advanced, and /extended) are also preserved; some of them have been reworked and some have been not.
UP TO GEANT4.9.4P03
Up to release Geant4.9.4.p03 a good starting point for new users is the /examples/novice group of applications, gradually raising in complexity from N01 to N07.
Every example comes with its own README file, which reasonably describes the involved details of the involved software components, the run-time application configuration macros, etc.
This document will give several additional instructions, mainly to help building the applications. Once again, please bear in mind that the build system is based on gmake and related scripts, and relies on a number of environment variables.
We will concentrate on the 2 easiest examples, N01 and N02; however, the building procedure is the same for other examples.
Bear in mind that instructions are shown for a c-shell environment. Users who prefer bash will need to replace
setenv <variable> <value>
with the appropriate language:
How to build and run novice exampleN02 with the OpenGL visualization
The instructions are similar to those for exampleN01.
However, there are several differences.
First of all, you will need to make sure that Geant4 toolkit is build with the OpenGL activated; however, this is the default option at least for centrally available builds of the whole Geant4.9.4 family of releases.
You will also need to set several environment variables specific
to the OpenGL use:
> setenv G4VIS_BUILD_OPENGLX_DRIVER 1
> setenv G4VIS_USE_OPENGLX 1
> setenv OGLHOME /usr/X11R6
> setenv OGLFLAGS "-I$OGLHOME/include"
> setenv OGLLIBS "-L/usr/X11R6/lib -lGL -lGLU"
Now you can copy exampleN02 and build it following the instructions
provided above for exampleN01.
Visualization is initialized and controlled via a set of /vis/ user
interface commands provided in the example input file vis.mac.
The vis.mac will be automatically read by the main() if you
run exampleN02 without any input argument:
This mode is called ``interactive'', and at the end of the job you will
need to type exit at the program command prompt:
Alternatively, you can run exampleN02 with either vis.mac , or run1.mac,
or run2.mac explicitlyy on input, for example:
> $G4EXE/exampleN02 vis.mac
This mode is called ``batch''. Please note that if you run in the ``batch''
mode with the vis.mac file on input, the OpenGL window
will be closed automatically upon the program termination.
Running with run1.mac or run2.mac will NOT employ OpenGL visualization.