Geant4: 5.  Python Interface

5.  Python Interface

Python is a popular scripting language with an interactive interpreter. Geant4Py, a Geant4-Python bridge, provides a bridge for Geant4 classes. This enables to directly access Geant4 classes from Python scripting. User applications can be easily configured with many Python third-party modules, such as PyROOT, on the Python software bus.

Geant4Py is supplied in the directory environments/g4py/ of the Geant4 source package.

5.1.  Installation

5.1.1.  Software Requirements

Geant4Py requires the Boost-C++ external library, which helps Python binding of C++ codes.

5.1.2.  Building Geant4Py module

Building system is completely migrated to CMake system. Before building library, GEANT4_INSTALL environment variable should be set to the path specified by "CMAKE_INSTALL_PREFIX" when building Geant4.

# export GEANT4_INSTALL="Geant4 install path" (zsh, bash)
# setenv GEANT4_INSTALL "Geant4 install path" (csh)


# mkdir build
# cd build
# cmake ..   
# make
# make install

If you want to run the testing component,

# cd build/tests
# make; make install

By default, Geant4Py is installed in "g4py"/lib(64) directory.

5.2.  Using Geant4Py

PYTHONPATH environment variable should be set at tun time. PYTHONPATH environment variable indicates Python module search directories, given by a colon-separated list of directories. Practically, the variable is (your g4py directory)/lib:(your g4py directory)/lib/examples:(your g4py directory)/lib/tests.

5.2.1.  Import Geant4

To use Geant4Py, you start with importing the module called "Geant4".

# python
Python 2.7.5 (default, Mar  9 2014, 22:15:05) 
[GCC 4.2.1 Compatible Apple LLVM 5.0 (clang-500.0.68)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> from Geant4 import *

 Geant4 version Name: geant4-10-01         (5-December-2014)
                      Copyright : Geant4 Collaboration
                      Reference : NIM A 506 (2003), 250-303
                            WWW :

Visualization Manager instantiating...

5.2.2.  Access to Geant4 Globals

When importing the Geant4 module, the G4RunManager object will be automatically instantiated. Geant4 singleton objects are also automatically instantiated. These singleton objects can be accessed by "gXXXX" variables, like "gRunManager".

                        gLossTableManager       gTerminate
gApplyUICommand         gMaterialTable          gTrackingManager
gControlExecute         gNistManager            gTransportationManager
gElementTable           gParticleIterator       gUImanager
gEmCalculator           gParticleTable          gVisManager
gEventManager           gProcessTable
gExceptionHandler       gProductionCutsTable
gG4Date                 gRunManager
gG4VERSION_NUMBER       gRunManagerKernel
gG4Version              gStackManager
gGeometryManager        gStartUISession
gGetCurrentValues       gStateManager

5.2.3.  Call Geant4 Methods

Once a Python object of a Geant4 class instantiated, Geant4 methods can be directly called the same way as in C++.

>>> from Geant4 import *

 Geant4 version Name: geant4-10-01         (5-December-2014)
                      Copyright : Geant4 Collaboration
                      Reference : NIM A 506 (2003), 250-303
                            WWW :

Visualization Manager instantiating...

>>> print gRunManager.GetVersionString()
 Geant4 version Name: geant4-10-01         (5-December-2014)

5.3.  Site-modules

Geant4Py provides additional utility modules called "g4py" in the directory site-modules. It consists of predifined geometries, materials, physics lists, primary generator actions, and so on.

5.3.1.  ezgeom module

The ezgeom module provides an alternative way of defining simple geometry. An example code for defining a simple geometry is shown here:

import g4py.ezgeom
from g4py.ezgeom import G4EzVolume

def ConstructGeom():
  print "* Constructing geometry..."
  # reset world material
  air= G4Material.GetMaterial("G4_AIR")

  # a target box is placed
  global target
  target= G4EzVolume("Target")
  au= G4Material.GetMaterial("G4_Au")
  target.CreateTubeVolume(au, 0., 1.*cm, 1.*mm)

5.3.2.  NISTmaterials module

The NISTmaterials module provides an instant use of Geant4 NIST materials. An example code for creating NIST materials:

from Geant4 import *
import g4py.NISTmaterials

print Geant4.gMaterialTable

5.3.3.  ParticleGun module

The ParticleGun module provides a primary generator action with G4ParticleGun. An example code is shown here:

import g4py.ParticleGun

# normal way for constructing user primary generator action
#pgPGA= g4py.ParticleGun.ParticleGunAction()
#pg= pgPGA.GetParticleGun()

# 2nd way, short-cut way
pg= g4py.ParticleGun.Construct()

# set parameters of particle gun
primary_position= G4ThreeVector(0.,0., -14.9*cm)
primary_direction= G4ThreeVector(0.2, 0., 1.)

5.4.  Examples

There are some examples of Geant4Py in the directories "tests/" and "examples/".

In the "tests/" directory,
gtest01 : exposes a user application
gtest02 : test for using site-module packages
gtest03 : test for ezgeom package
gtest04 : test for getting command tree and command information
gtest05 : test for constructing CSG geometries in Python
gtest06 : test for constructing/visualizing boolean geoemtries
gtest07 : test for checking overlapped geometries
The "examples/" directory contains a set of examples of Geant4Py.

An example of "water phantom dosimetry". This demo program shows that a Geant4 application well coworks with Root on Python front end. VisManager, PrimaryGeneratorAction, UserAction-s, histogramming with Root are implemented in Python;

  • dose calculation in a water phantom
  • Python overloading of user actions
  • on-line histogramming with Root
  • visualization


Educational examples with Graphical User Interface using TKinter

* lesson1

The first version of the courseware of the mass attenuation coefficient.

* lesson2

GUI interface of ExN03, which can control geometry configuration, intial particle condition, physics processes, cut value, magnetic field and visualization outputs.


Examples of plotting photon cross sections and stopping powers with Root.


Examples of writing/reading user's geometry to/from a GDML file

<-- 4. Development and Debug Tools  6. Geant4 Material Database --> "