source: trunk/documents/UserDoc/DocBookUsersGuides/ForApplicationDeveloper/xml/Appendix/pythonInterface.xml @ 1222

<!-- ******************************************************** -->
<!--                                                          -->
<!--  [History]                                               -->
<!--    Created by Koichi Murakami, Dec-2008                  -->
<!--    Correct typo by KM Dec-2009                           -->
<!--                                                          -->
<!-- ******************************************************** -->

<!-- ******************* Section (Level#1) ****************** -->
<sect1 id="sect.PythonInterface">
<title>
Python Interface
</title>

<para>
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.
</para>

<para>
Geant4Py is located in the directory <literal>environments/g4py/</literal>.
</para>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.Installation">
<title>
Installation
</title>

<sect3 id="sect.SoftwareRequirements">
<title>
Software Requirements
</title>

<para>
Geant4Py requires
<ulink url="http://www.boost.org/">Boost-C++ external library</ulink>,
which helps Python binding of C++ codes.
A Precompiled package is available for many Linux distributions
(SL, SuSE, Ubuntu, etc) and Mac OSX.
</para>

<para>
Geant4 libraries can be built as "static" and "granular",
where library components (variables, functions, ...)
used in the application are linked statically and shipped
with the application.
On the other hands, in dynamic binding, the library components
are not included in the application, and their binding is
carried out at run time.
The modular approach of Python is based on dynamic binding mechanism,
so you have Geant4 shared libraries are required instead.
</para>

<para>
For generic information about building Geant4 libraries,
please refer to the <ulink url="http://cern.ch/geant4/G4UsersDocuments/UsersGuides/InstallationGuide/html/">Installation Guide</ulink>.
</para>

<para>
Here are some tips for manually building "global" and "shared" libraries
from an already existing "static + granular" installation.
After setting additional environment variables like:
<table id="table.additionalEnvs">
<title>
Additional environment variables for building global and shared library
</title>
<tgroup cols="3">
  <tbody>
  <row>
    <entry>
      <emphasis role="bold">Environment Variable</emphasis>
    </entry>
    <entry>
      <emphasis role="bold">Description</emphasis>
    </entry>
    <entry>
      <emphasis role="bold">Value (example)</emphasis>
    </entry>
  </row>
  <row>
    <entry>
      <emphasis role="bold">G4LIB</emphasis>
    </entry>
    <entry>
      Path where the Geant4 libraries are installed
    </entry>
    <entry>
      $G4INSTALL/slib
    </entry>
  </row>
  <row>
    <entry>
      <emphasis role="bold">G4TMP</emphasis>
    </entry>
    <entry>
      Path where temporary files are placed
    </entry>
    <entry>
      $G4INSTALL/tmp-slib
    </entry>
  </row>
  <row>
    <entry>
      <emphasis role="bold">G4LIB_BUILD_SHARED</emphasis>
    </entry>
    <entry>
      Flag for building shared libraries
    </entry>
    <entry>
      1
    </entry>
  </row>
  </tbody>
</tgroup>
</table>

execute the following:

<informalexample>
<programlisting>
# cd $G4INSTALL/source
# make
# make global
</programlisting>
</informalexample>

In addition, it is required that all header files are installed
in a single directory.

<informalexample>
<programlisting>
# cd $G4INSTALL/source
# make includes
</programlisting>
</informalexample>

This will collect all relevant header files
in <literal>$G4INSTALL/include</literal> (or <literal>$G4INCLUDE</literal>).
</para>

<para>
There are additional tools for helping building a Geant4 library in
the directory <literal>g4py/tools/</literal>.
</para>
</sect3>

<sect3 id="sect.BuildingGeant4Py">
<title>
Building Geant4Py module
</title>

<para>
Geant4Py provides a configure scrtipt for building modules.

<informalexample>
<programlisting>
# ./configure --help
`configure' configures Geant4Py to adapt to many kinds of systems.

Usage:  ./configure SYSTEM [OPTION]... [VAR=VALUE]...

SYSTEM: System type (see Supported Arhitectures)

Options:
  -h, --help                Display this help and exit

Installation directories:
  --prefix=PREFIX           Installation prefix  [./]
  --libdir=DIR              Python modules dir [PREFIX/lib]

Fine tuning of the library path:
  --with-g4-incdir=DIR      Geant4 header dir [$G4INCLUDE]
  --with-g4-libdir=DIR      Geant4 library dir [$G4LIB/$G4SYSTEM]
  --with-clhep-incdir=DIR   CLHEP header dir [$CLHEP_INCLUDE_DIR]
  --with-clhep-libdir=DIR   CLHEP library dir [$CLHEP_LIB_DIR]
  --with-clhep-lib=LIB      library name of libCLHEP.so [CLHEP|$CLHEP_LIB]

  --with-python-incdir=DIR  Python header dir [/usr/include/python(2.#)],
                            (location of pyconfig.h)
  --with-python-libdir=DIR  Python library dir [/usr/lib(64)]

  --with-boost-incdir=DIR   BOOST-C++ header dir [/usr/include],
                            (location of boost/)
  --with-boost-libdir=DIR   BOOST-C++ library dir [/usr/lib]
  --with-boost-python-lib=LIB library name of libboost_python.so [boost_python]

  --with-package-dir=DIR    Geant4 Package dir

  --with-extra-dir=DIR      Install path for extra packages [/usr/local]

  --with-xercesc-incdir=DIR Xerces-C header dir [/usr/include]
  --with-xercesc-libdir=DIR Xerces-C library dir [/usr/lib(64)]

Enable/disable options: prefix with either --enable- or --disable-
  openglx      OpenGLX support    [auto]
  openglxm     OpenGLXm support   [disable, $G4VIS_USE_OPENGLXM]
  raytracerx   RayTracerX support [disable, $G4VIS_USE_RAYTRACERX]

Supported Architectures:
  linux           for Linux gcc 3.x and 4.x (32bit)
  linux64         for Linux gcc 3.x and 4.x (64bit, alias to linuxx8664gcc)
  linuxx8664gcc   for AMD Opteron and Intel EM64T Linux gcc 3.x and 4.x
  macosx          for MacOSX with gcc (Tiger/Leopard and Xcode)
</programlisting>
</informalexample>

For example, you run it like
<informalexample>
<programlisting>
# ./configure linux64
  --with-g4-incdir=/opt/heplib/Geant4/geant4.9.3/include
  --with-g4-libdir=/opt/heplib/Geant4/geant4.9.3/slib/Linux-g++
  --with-clhep-incdir=/opt/heplib/CLHEP/2.0.4.5/include
  --with-clhep-libdir=/opt/heplib/CLHEP/2.0.4.5/lib
  --with-clhep-lib=CLHEP-2.0.4.5
</programlisting>
</informalexample>

The configure script automatically check your environment,
and create <literal>config/config.gmk</literal>,
which describes your envrionment.

After executing the configure script successfully, then

<informalexample>
<programlisting>
# make
# make install
</programlisting>
</informalexample>
</para>
</sect3>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.UsingGeant4Py">
<title>
Using Geant4Py
</title>

<para>
<emphasis role="bold">PYTHONPATH</emphasis> environment variable
should be set at tun time.
<emphasis role="bold">PYTHONPATH</emphasis> environment variable indicates
Python module search directories, given by a colon-separated list
of directories. Practically, the variable is
<literal>(your g4py directory)/lib</literal>.
</para>

<sect3 id="sect.ImportGeant4">
<title>
Import Geant4
</title>

<para>
To use Geant4Py, you start with importing the module called "Geant4".
<informalexample>
<programlisting>
# python
Python 2.6.2 (r262:71600, Oct 24 2009, 03:15:21) 
[GCC 4.4.1 [gcc-4_4-branch revision 150839]] on linux2
Type "help", "copyright", "credits" or "license" for more information.
&gt;&gt;&gt; from Geant4 import *

*************************************************************
 Geant4 version Name: geant4-09-03         (18-December-2009)
                      Copyright : Geant4 Collaboration
                      Reference : NIM A 506 (2003), 250-303
                            WWW : http://cern.ch/geant4
*************************************************************

Visualization Manager instantiating...
&gt;&gt;&gt;
</programlisting>
</informalexample>
</para>
</sect3>

<sect3 id="sect.AccessToG4Globals">
<title>
Access to Geant4 Globals
</title>

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

<informalexample>
<programlisting>
                        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
</programlisting>
</informalexample>
</para>
</sect3>

<sect3 id="sect.CallGeant4Methods">
<title>
Call Geant4 Methods
</title>

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

<informalexample>
<programlisting>
&gt;&gt;&gt; from Geant4 import *

*************************************************************
 Geant4 version Name: geant4-09-03         (18-December-2009)
                      Copyright : Geant4 Collaboration
                      Reference : NIM A 506 (2003), 250-303
                            WWW : http://cern.ch/geant4
*************************************************************

Visualization Manager instantiating...

&gt;&gt;&gt; print gRunManager.GetVersionString()
 Geant4 version Name: geant4-09-03    (18-December-2009)
</programlisting>
</informalexample>
</para>
</sect3>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.Site-modules">
<title>
Site-modules
</title>

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

<sect3 id="sect.ezgeomModule">
<title>
<emphasis>ezgeom</emphasis> module
</title>

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

<informalexample>
<programlisting>
import g4py.ezgeom
from g4py.ezgeom import G4EzVolume

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

  # a target box is placed
  global target
  target= G4EzVolume("Target")
  au= G4Material.GetMaterial("G4_Au")
  target.CreateTubeVolume(au, 0., 1.*cm, 1.*mm)
  target.PlaceIt(G4ThreeVector(0.,0.,-10.*cm))
</programlisting>
</informalexample>
</sect3>


<sect3 id="sect.NISTmaterialsModule">
<title>
<emphasis>NISTmaterials</emphasis> module
</title>

<para>
The <emphasis>NISTmaterials</emphasis> module provides an instant
use of Geant4 NIST materials.
An example code for creating NIST materials:
</para>

<informalexample>
<programlisting>
from Geant4 import *
import g4py.NISTmaterials

g4py.NISTmaterials.Construct()
print Geant4.gMaterialTable
</programlisting>
</informalexample>
</sect3>

<sect3 id="sect.ParticleGunModule">
<title>
<emphasis>ParticleGun</emphasis> module
</title>

<para>
The <emphasis>ParticleGun</emphasis> module provides
a primary generator action with <literal>G4ParticleGun</literal>.
An example code is shown here:
</para>

<informalexample>
<programlisting>
import g4py.ParticleGun

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

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

# set parameters of particle gun
pg.SetParticleByName("e-")
pg.SetParticleEnergy(300.*MeV)
primary_position= G4ThreeVector(0.,0., -14.9*cm)
primary_direction= G4ThreeVector(0.2, 0., 1.)
pg.SetParticlePosition(primary_position)
pg.SetParticleMomentumDirection(primary_direction)
</programlisting>
</informalexample>
</sect3>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.Examples">
<title>
Examples
</title>

<para>
There are some examples of Geant4Py in the directories
<literal>"tests/"</literal> and <literal>"examples/"</literal>.
</para>

In the <literal>"tests/"</literal> directory,

<informalexample>
<programlisting>
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
</programlisting>
</informalexample>

The <literal>"examples/"</literal> directory contains
a set of examples of Geant4Py.

<variablelist>
<varlistentry>
<term>demos/water_phantom</term>
<listitem>
<para>
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;
<itemizedlist>
<listitem>dose calculation in a water phantom</listitem>
<listitem>Python overloading of user actions</listitem>
<listitem>on-line histogramming with Root</listitem>
<listitem>visualization</listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
</variablelist>

<variablelist>
<varlistentry>
<term>education</term>

<listitem>
<para>
Educational examples with Graphical User Interface using
<literal>TKinter</literal>
</para>

<para>
* lesson1
</para>

<para>
The first version of the courseware of the mass attenuation coefficient.
</para>

<para>
* lesson2
</para>

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

</listitem>
</varlistentry>
</variablelist>


<variablelist>
<varlistentry>
<term>emplot</term>
<listitem>
<para>
Examples of plotting photon cross sections and stopping powers with Root.
</para>
</listitem>
</varlistentry>
</variablelist>


<variablelist>
<varlistentry>
<term>gdml</term>
<listitem>
<para>
Examples of writing/reading user's geometry to/from a GDML file
</para>
</listitem>
</varlistentry>
</variablelist>

</sect2>
</sect1>