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.


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:

  1. Cmake-based approach makes obsolete a number of environment variables that used to be mandatory. A user may still set some of those variables as they may be convenient shortcuts with cmake directives.
  2. Environmental variables to point at the Geant4 datasets are still requited, at run-time.
  3. Cmake-based build system does not eliminate use of environment variables, but it rather make it more specific to activating certain feature of one or another application, for example use of visualization features. In other words, a user no longer need to worry about setting a number of "traditional" environmental variables, but the user is highly encouraged to learn what specific environment variables may be used with a particular example.

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 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:

   export <variable>=<value>

How to build and run novice exampleN01

This is the first - and the simplest - example that introduces users to the basics of implementing a Geant4 application code; please see the README for useful information, in particular on the software components.
The instructions below show how to build and run it.
First of all, you will need to set up Geant4, including the group of mandatory environmental variables. Do not forget the group of variables to point at the relevant data sets.
After that, you will create your local work directory MyG4Test (or any name of your choice):
> mkdir   MyG4Test
and will copy into it all sources of the exampleN01:
> cp   -r   $G4INSTALL/examples/novice/N01   MyG4Test/.
Next, you will need to prepare your environment:
> cd   MyG4Test/N01
> setenv   G4WORKDIR $PWD
Please note that you must set environment variable G4WORKDIR, and you should set it to point explicitly to your work area; otherwise the build (gmake) procedure will fail because it will try to create ``service'' /tmp and /bin subdirectories in the ``default'' $G4INSTALL area, where a typical user does not have the ``write'' access.
Next step is to build the executable, which will be done via issuing statement:
> gmake
This will produce binary file exampleN01 in the $G4WORKDIR/bin/$G4SYSTEM subdirectory (G4SYSTEM
is one of the environment variables defined upon Geant4 setup; for details, see here).
It may also be useful to define an environment variable to point to the area where your executable is located, for example:
> setenv   G4EXE   $G4WORKDIR/bin/$G4SYSTEM
This example does not need any input; you can run it as follows:
> $G4EXE/exampleN01
which will produce an output on your screen, or you can redirect output into a file FileName.out (any name of your choice):
> $G4EXE/exampleN01   >&   FileName.out
You may compare your output with the ``standard'' output file exampleN01.out provided along with the example (you will find it in your $G4WORDIR area).

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_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:
> $G4EXE/exampleN02
This mode is called ``interactive'', and at the end of the job you will need to type exit at the program command prompt:
Idle> exit
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.