Skip Ribbon Commands
Skip to main content

SOFTWARE COMPONENTS FOR BUILDING PHYSICS LISTS

In 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).

G4VModularPhysicsList

Technically 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.

G4VPhysicsConstructor

A  "module" in a Modular Physics List will be a G4VPhysicsConstructor (or derived) object, and it can be "registered" with a G4VModularPhysicsList. 

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 particle(s).

The particles included in this module are:

  • Photon and leptons
  • Several mesons and baryons
  • Several ions

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:

  • Specific only to a given particle type (example: G4GammaConversion and photon)
  • Common across a group of particles (example: G4hIonisation and a variety of hadrons)

An EM process may:

  • Be self-contained (examples: G4hIonisation or G4GammaConversion )
  • Need to be supplemented with additional component(s), such a physics model(s). For example, Multiple Scattering process for most particles in this implementation is outfitted is G4WentzelVIModel, and it is valid the entire energy range. However, Multiple Scattering for e+/e- is outfitted with G4UrbanMscModel up to 100MeV, followed by G4WentzelVIModel from 100MeV onward.

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:

  • Particles (hadrons) are created, and physics models to be used to simulate applicable processes are specified, usually in a particular range of validity.
  • Physics processes for each particle type in the builder are created, and each process is outfitted with one or more hadronic physics models, as specified.
  • If necessary, a cross section data set for a given particle type is added.

Details about builders are given later in this document.

G4PhysicsListHelper

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. 

Particle-Process-Model(s) Builders

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:

  • Particle Builders
  • Particle-Model 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:

  • G4PiKBuilder (.hh and .cc) -  groups pions and kaons, together with a list of associated hadronic processes.
  • G4BertiniPiKBuilder (.hh and .cc) - instrantiates Bertini cascade model and implements how to outfit pion and kaon physics processes with this model. It also sets default validity range for the model (although later overriden in HadronPhysicsFTFP_QGSP.cc).
  • G4FTFPPiKBuilder (.hh and .cc) - composes a high energy FTF-based model and implements how to outfit hadronic processes for pions and kaons with the model. This example illustrates that a hadronic model does not always have a single interface class, but it needs to be created from several components. In particular, in this builder a "high energy generator" object (G4TheoFSGenerator) is created and is outfited with G4FTFModel string model (which also gives this builder its name), we well as string fragmentation algorithm and intra-nuclear transport model. Please note that the quasi-elastic scattering is not set as FTF model has its own mechanism for it. A cross-section data set is specified for pions. A default validity range is also specified.

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 user wants 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 "standard" modules. 

Some Constraints

  1. Once a physics list is composed, standard Geant4 machinery offers little flexibility of reconfiguring it at run time. A user may choose to turn on/off selected EM processes (for specific studies), but this is about it.
  2. Geant4 physics models are provided to end-users with very few, if any, configuration parameters. This is especially true for Geant4 hadronic physics domain. All parameters that define the tune of one or another physics model are typically hardcoded, and can not be changed without modifying and recompiling Geant4 core code. Even very advanced Geant4 users are strongly discouraged from making such modifications, as model configuration parameters may be correlated, thus changing one or another parameter may lead to a serious bias in the simulation results.
  3. A physics module in a form of G4VPhysicsConstructor can be, as a whole, removed from a physics list and/or replaced in a physics list by another similar module, again of a G4VPhysicsConstructor type. In practice it means that a user can take one of the standard physics lists distributed with the Geant4 toolkit and replace one of another module in its with a custom one. However, such action would require certain familiarity with the implementation details of standard physics lists, for example, knowing internal naming conventions for the physics modules.
  4. A physics process can NOT be easily de-registered from from a physics list (general or modular).
  5. A physics model can, in principle, be de-registered from a physics process, but at present the machinery is far from perfect and may lead to "damages" in a physics list.


‚Äč