Mandatory User Actions and Initializations¶
Three user initialization class objects are registered with the run
manager (Manage the run procedures) in the user’s main()
program, which takes ownership. The user must not delete these objects
directly, and they must be created using ‘new’. Within the
G4UserActionInitialization class (
User Action Initialization), the user must instantiate and
register a concrete G4VUserPrimaryGeneratorAction subclass, which
generates the primary particles for each event.
G4VUserDetectorConstruction¶
class G4VUserDetectorConstruction
{
public:
G4VUserDetectorConstruction();
virtual ~G4VUserDetectorConstruction();
public:
virtual G4VPhysicalVolume* Construct() = 0;
virtual void ConstructSDandField() = 0;
};
In the Construct() method, material and geometry has to be
described. Detailed discussions on material and geometry are given in
How to Specify Materials in the Detector and How to Define a Detector Geometry.
Detector sensitivity and electromagnetic field should be defined in
ConstructSDandField(), as objects defined in this method are
thread-local if they are used in multi-threaded mode. Detailed
discussions on Detector sensitivity and electromagnetic field are given
in Hits and Electromagnetic Field.
Physics Lists¶
The concept of a physics list arises from the fact that Geant4 can not offer a single modeling algorithm to cover the entire energy domain from zero to the TeV scale, for all known processes and particles. Instead, a combination of ideas and approaches is typically used to perform a simulation task.
A schematic view of the Geant4 modeling of the processes of particle passage through matter may be presented as follows:
Physics Model = final state generator
Physics Process = cross section + model
Physics List = list of processes for each particle
The “patchwork” concept is especially true in the Geant4 hadronic physics domain: models are valid only over finite energy ranges, and there maybe competing models in the same range or one model maybe working better than the other for a specific group of particles, while its competitor may be better for other species. For this reason models have to be combined to cover the large energy range; every two adjacent models may have an overlap in their validity range.
G4VUserPhysicsList¶
This is an abstract class for constructing particles and processes. An introduction into the concept of the Geant4 Physics List and the Geant4 Physics Processes is also given in How to Specify Physics Processes and further in Physics Processes.
While the fabrication of a physics list is, in principle, a choice of a user, the toolkit is distributed with a number of pre-fabricated physics lists for the convenience of many user applications. These physics lists are supported by the Geant4 development team and can be recommended for specific physics tasks. However, based on the interests and needs of a specific project, a user may want to implement her or his own custom physics list.
The following sections offer several examples that show how to instantiate or select one or another pre-fabricated Physics List from the Geant4 standard collection, as well as guidance composing a custom Physics List from pre-fabricated components or even entirely from scratch.
To view the contents of a Physics List, there are two useful methods:
DumpList() and DumpCutValueTable(G4int flag).
Reference Physics Lists¶
Number of ready to use Physics Lists are available with Geant4 kernel. Below an example of instantiation of FTFP_BERT Physics List class is shown. The full set of reference Physics Lists is described in Geant4 web.
G4int verbose = 1;
FTFP_BERT* physlist = new FTFP_BERT(verbose);
runManager->SetUserInitialization(physlist);
Building Physics List Using Factory¶
Geant4 provides a class G4PhysListFactory allowing to defined
Physics List by its name. The last for characters in the name defines an
electromagnetic (EM) physics options. By default standard EM physics is
used, “_EMV” corresponding to standard option1, “_EMX” - to standard
option2, “_LIV” to EM Livermore physics, “_PEN” - to EM Penelope
physics.
G4int verbose = 1;
G4PhysListFactory factory;
G4VModularPhysicsList* physlist = factory.GetReferencePhysList("FTFP_BERT_EMV");
physlist.SetVerboseLevel(verbose);
runManager->SetUserInitialization(physlist);
The class G4PhysListFactory provides also another interface allowing
to defined Physics List by the environment variable PHYSLIST.
G4int verbose = 1;
G4PhysListFactory factory;
G4VModularPhysicsList* physlist = factory.ReferencePhysList();
physlist.SetVerboseLevel(verbose);
runManager->SetUserInitialization(physlist);
Building Physics List from Physics Builders¶
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, as it will be shown later in this document. However, for practical purposes it is often 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 provided by Geant4
kernel with user’s applications.
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 pre-fabricated physics modules. There also methods for removing
or replacing physics modules.
Example below shows how G4VModularPhysList can be implemented.
MyPhysicsList::MyPhysicsList():G4VModularPhysicsList()
{
G4DataQuestionaire it(photon, neutron, no, no, no, neutronxs);
G4cout << "<<< Geant4 Physics List: MyPhysicsList " <<G4endl;
G4cout <<G4endl;
defaultCutValue = 0.7*mm;
G4int ver = 1;
SetVerboseLevel(ver);
// EM Physics
RegisterPhysics( new G4EmStandardPhysics(ver) );
// Synchroton Radiation & GN Physics
RegisterPhysics( new G4EmExtraPhysics(ver) );
// Decays
RegisterPhysics( new G4DecayPhysics(ver) );
// Hadron physics
RegisterPhysics( new G4HadronElasticPhysicsXS(ver) );
RegisterPhysics( new G4QStoppingPhysics(ver) );
RegisterPhysics( new G4IonBinaryCascadePhysics(ver) );
RegisterPhysics( new G4HadronInelasticQBBC(ver));
// Neutron tracking cut
RegisterPhysics( new G4NeutronTrackingCut(ver) );
}
Note that each module to be registered with a Modular Physics List is a
G4VPhysicsConstructor (or a derived object), i.e. a “sublist” that
holds groups of particles and accompanying physics processes. 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.
In order to compose a custom physics module, two mandatory methods of a
G4VPhysicsConstructor must be implemented: ConstructParticle()
and ConstructProcess(); beyond that the implementation can be
structured according to the developer’s taste.
Another useful concept in the modular approach to composing a Physics List is the concept of so called “builders”. This concept allows to encapsulate certain implementation details into smaller-scale software components, and 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.
This concept is widely used through the Geant4 hadronic domain, but the idea would be equally applicable in the electromagnetic area.
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 G4ProcessManager. 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 builders 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) - instantiates 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.
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 outfitted 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 SetMinEnergy 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 overridden 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.
One more useful class is the `` G4PhysicsListHelper`` which 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.
Other useful details, including several elements of the software design philosophy and class diagrams, are given in How to Specify Physics Processes.
Building Physics List from Scratch¶
The user must derive a concrete class from G4VUserPhysicsList and
implement three virtual methods:
ConstructParticle()to instantiate each requested particle type;ConstructPhysics()to instantiate the desired physics processes and register each of them;SetCuts(G4double aValue)to set a cut value in range for all particles in the particle table, which invokes the rebuilding of the physics table.
At early stage of the initialisation of Geant4 the method
ConstructParticle() of G4VUserPhysicsList is invoked. The
ConstructProcess() method must always invoke the
AddTransportation() method in order to insure particle
transportation. AddTransportation() must never be overridden. This
is done automatically if G4VUserPhysicsList inherits of
G4VModularPhysicsList. It is recommended for users as the most
robust interface to Physics List. Geant4 examples demonstrate different
methods how to create user Physics List.
User Action Initialization¶
All user action classes must be defined through the protected method
SetUserAction(). Build() methods should be used for defining user
action classes for worker threads as well as for the sequential mode.
BuildForMaster() should be used only for defining UserRunAction for
the master thread. BuildForMaster() is not invoked in the sequential
mode. In case the user uses his/her own SteppingVerbose class, it
must be instantiated in the method InitializeSteppingVerbose() and
returned.
G4VUserActionInitialization¶
class G4VUserActionInitialization
{
public:
G4VUserActionInitialization();
virtual ~G4VUserActionInitialization();
public:
virtual void Build() const = 0;
virtual void BuildForMaster() const;
virtual G4VSteppingVerbose* InitializeSteppingVerbose() const;
protected:
void SetUserAction(G4VUserPrimaryGeneratorAction*) const;
void SetUserAction(G4UserRunAction*) const;
void SetUserAction(G4UserEventAction*) const;
void SetUserAction(G4UserStackingAction*) const;
void SetUserAction(G4UserTrackingAction*) const;
void SetUserAction(G4UserSteppingAction*) const;
};