SOFTWARE COMPONENTS FOR BUILDING PHYSICS LISTSIn this document we would like to provide useful tips on the code elements needed to compose a physics list. We will concentrate on the areas where official Geant4 documentation is sparse.
This document is organized as follows:
Beware that the links to the example Geant4 classes in this document correspond to the current structure of the Geant4 software package, as of release Geant4.9.6.p02, and may change in the future development cycle(s).
Instantiating a Physics List
A physics list can be instantiated individually, for example:
FTFP_BERT* phylist = new FTFP_BERT();
or it can be retrieved from a collective holder of all standard Geant4 physics lists, know as G4PhysListFactory; initial tips on it are given in the Section 6.1.3 of the User Guide for Application Developers.
View the Physics Content
Before going to details of composing a physics list, it may be useful to simply view what a given physics list is made of. For this purpose, "master" G4VUserPhysicsList class offers two helpful methods: DumpList() and DumpCutValueTable(G4int flag).
speaking, one can implement physics list in a "flat-out" manner, i.e.
specify all necessary particles and associated processes in a single
piece of code. However,
for practical purposes such as, for example, maintenance or
re-usability, it may be more convenient to group together certain
categories and make implementation more modular.
One very useful concept is a Modular Physics List, G4VModularPhysicsList,
that is a sub-class of G4VUserPhysicsLists and allows a user to
organize physics processes into "building blocks", or "modules", then
compose a physics list of such modules.
The concept allows
to group together, at a relatively high level, desired combinations of selected particles and related
processes. One of the advantages of such approach is that it allows to
combine pre-fabricated physics modules that are centrally distributed
with the Geant4 core code with user's implementation of selected
processes and/or even custom models.
G4ModularPhysicsList has all the functionalities as G4VUserPhysicsList class, plus several additional functionalities. One of the important methods is RegisterPhysics(G4VPhysicsConstructor* ) for "registering" the above mentioned prefabriced physics modules. There also methods for removing or replacing physics modules.
A "module" in a Modular Physics List will be a G4VPhysicsConstructor
(or derived) object, and it can be "registered" with a
For example, if one looks through the implementation of the traditional QGSP_FTF_BERT physics lists, source/physics_lists/lists/include/QGSP_FTFP_BERT.icc,
one will see that it's composed from several building blocks, such as
standard and "extra" EM physics, hadronic physics modules, etc.
Those modules are
G4VPhysicsConstructors, i.e. "sublists" to hold groups of particles and
accompanying physics processes. They are also part of Geant4 standard
distribution. A user can find these and other similar modules in the
source/physics_lists/list area of Geant4 core code, and can combine
selected ones with custom modules, if desired.
The idea can be illustrated by looking through any alternative physics lists, for example, source/physics_lists/lists/include/FTFP_BERT.icc, one will see it composed of the same module except for one: HadronPhysicsFTFP_BERT now replaces HadronPhysicsQGSP_FTF_BERT.
Other modules, such as G4HadronElasticPhysics, G4EmStandardPhysics, etc., are the same in both lists (as well as a number of other lists).
The two mandatory methods of a Physics Constructor
that must be implemented are ConstructParticle() and ConstructProcess();
beyond that the implementation can be structured according to
the developer's taste.
Example 1: G4EmStandardPhysics
As an example, one can review implementation of the Electromagnetic (EM) physics module, source/physics_lists/builders/src/G4EmStandardPhysics.cc.
This module is an example of somewhat "bulky" implementation, as a variety of particles and all essential EM process are all instantiated in a single piece of code (and
even in a single method), and it is arranged through a chain of
if-statements which processes need to be associated with what
The particles included in this module are:
Particles such as hadrons and ions are included because there are associated EM processes.
Note-1: It is important for a user to remember is that the core Geant4 code itself often relies on the fact that processes and the particles are interconnected. For example, it is impossible to register muon pair production without defining first e-/e+ and the processes for them - it will lead to a segfault in the initialization, as the system will try to check consistency of the particle list (this check can be optionally disabled but by default it is ON).
Note-2: In principle, a list does not have to be a 100% complete in order to run - it only needs to be self-consistent. The minimal required set of particles ro run, for example, a photon-induced EM shower with a partial EM physics list will be a photon itself, a pair of e-/e+ and a proton (in the depth of G4VUserPhysicsList the "expectation" of a minimum of these 4 particles is hardcoded, and the system will not function otherwise - good design or bad, but that is a fact of life).
After the particles are created, the code calls for EM processes, and properly associate processes with specific particles.
An EM process can be:
An EM process may:
The concept of multiple models applicable to one particle type is much wider used through the hadronic physics domain, as described in the next section.
The association of a processes with a particle is typically done via helper components called G4PhysicsListHelper, which is briefly described later in this document.
Example 2: HadronicPhysicsFTFP_BERT
As an example of a hadronic physics module implementation one can consider source/physics_lists/lists/HadronPhysicsFTFP_BERT.cc.
One can immediately see that the structure of the code is quite different from the one of the EM module. Instead of explicit instantiation of particles and processes, this code operates on so called "builders" for particles and for hadronic models.
In principle, a hadronic module can also be implemented in a more "flat-out" way, similar to the EM module. However, the concept of builders illustrates how certain implementation details can be encapsulated into smaller-scale software components, and it offers the flexibility of re-using those component in different modules.
At the general level, the scheme is this:
Details about builders are given later in this document.
G4PhysicsListHeler is a service class that wraps around the technicalities of the physics process registering in Geant4 and allows a user to easily associate a process with a particles, without knowing many details about various types of processes (discrete, continuous, etc.) and their internal ordering with G4ProcessManager.
Curious users may eventually want to go deeper into details of G4ProcessManager class and, in particular, its group of AddProcess(...) methods, as it is the basis of G4PhysicsListHelper implementation. But for practical purposes, the use of G4PhysicsListHelper is likely to be sufficient in most cases.
As already stated earlier in this document, builders encapsulate coding details of specifying a particles or a group of particles and associated physics process defined by selected hadronic physics models.
This concept is widely used through the Geant4 hadronic domain, but the idea would be equally applicable in the electromagnetic area; there's no particular reason, except for historical, for different coding approaches.
All builders can be found in the source/physics_lists/builders directory.
There are basically two types of builders:
A particle builder is somewhat "superior" here, as it specifies a particle or a group of particles, what category of processes are applicable, how to outfit a process with specified model(s), and how processes are to be registered with the Process Manager.
A particle-model builder instantiates a given model and implements details of associating it with one or more processes applicable to a given particle type. Some models can not be instantiated through a single interface class, but instead they need, in turn, to be composed from several components; examples are QGS and FTF.
Useful example bulders to review and to consider as inspirations can be the following:
One detail to remember is that, in principle, the validity range for a given model can be setup for each particle type individually. But in these referenced applications the validity range is setup to be the same for a group of particles (i.e. for a number of corresponding inelastic hadronic processes). Once a builder is instantiated, one can override the default validity range (via SetMinEnery or SetMaxEnergy methods), but the new value will be, again, given to a group of particles/processes. Also note that the validity range can be overriden only before calling the Build() method of a builder. Again, the approach is just a specifics of this particular implementation.
Obviously, if a limited validity range is selected for a specific particle/model/process, one has to supplement another model or several models, to cover the entire range.
Knowing these details may come handy in various situations. For example, if a
to try how two neighboring models inrterplay for a given particle
type in a given energy range, the user may slide left or right the
validity range for one or another model. A user may also choose to implement a custom builder (or an equivalent) that will group particles but will allow setting validity range for each particle type individually. Unfortunately, once composed, a
physics list can not be extensively reconfigured at run time (no such API exists at present); thus
the only way to make modifications in a physics list would be to
implement a custom G4VPhysicsConstructor and combine it with other