source: trunk/documents/UserDoc/DocBookUsersGuides/ForToolkitDeveloper/xml/GuideToExtendFunctionality/HadronicPhysics/hadronics.xml @ 904

<!-- ******************************************************** -->
<!--  Docbook Version:  For Toolkit Developers Guide          -->
<!-- ******************************************************** -->

<!-- ******************* Section (Level#1) ****************** -->
<sect1 id="sect.ExtdFuncHadPhys">
<title>
Hadronic Physics
</title>

<!-- 
  This is a verbatim of a paper published in a refereed journal.
  A suggestion by one of the documentation referees to re-write 
  completely seems quite inappropriate.
-->

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

<para>
Optimal exploitation of hadronic final
states played a key role in successes of all recent collider experiment in HEP,
and the ability to use hadronic final states will continue to be one of the
decisive issues during the analysis phase of the LHC experiments.
Monte Carlo programs like Geant4 facilitate the use of 
hadronic final states, and have been developed for many years.
</para>

<para>
We give an overview of the Object Oriented frameworks for hadronic generators 
in Geant4, and illustrate the physics models underlying hadronic shower 
simulation on examples, including the three basic types of modeling; 
data-driven, parametrisation-driven, and theory-driven modeling, and their 
possible realisations in the Object Oriented component system of Geant4. 
We put particular focus on the level of extendibility that can and has been 
achieved by our Russian dolls approach to Object Oriented design, and the
role and importance of the frameworks in a component system.
</para>

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.ExtdFuncHadPhys.PrncCnsd">
<title>
Principal Considerations
</title>

<para>
The purpose of this section is to explain the implementation frameworks used 
in and provided by Geant4 for hadronic shower simulation as in the 1.1 
release of the program. The implementation frameworks follow the Russian dolls 
approach to implementation framework design.
A top-level, very abstracting implementation framework provides the basic
interface to the other Geant4 categories, and fulfils the most general
use-case for hadronic shower simulation. It is refined for more specific
use-cases by implementing a hierarchy of implementation frameworks, each level
implementing the common logic of a particular use-case package in a concrete 
implementation of the interface specification of one framework level above, 
this way refining the granularity of abstraction and delegation.  This defines 
the Russian dolls architectural pattern.
Abstract classes are used as the delegation mechanism

<footnote>
  <para>
  The same can be achieved with template specialisations
  with slightly improved CPU performance but at the cost of significantly more 
  complex designs and, with present compilers, significantly reduced 
  portability.
  </para>
</footnote>
.
</para>

<para>
All framework functional requirements were obtained through use-case analysis. 
In the following we present for each framework level the compressed use-cases, 
requirements, designs including the flexibility provided, and illustrate the 
framework functionality with examples. All design patterns cited are to
be read as defined in 
<citation><xref linkend="biblio.Gamma1995" endterm="biblio.Gamma1995.abbrev" /></citation>.
</para>

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.ExtdFuncHadPhys.L1_Proc">
<title>
Level 1 Framework - processes
</title>

<para>
There are two principal use-cases of the level 1 framework. A user will 
want to choose the processes used for his particular simulation run, and a 
physicist will want to write code for processes of his own and use these 
together with the rest of the system in a seamless manner.
</para> 

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Requirements
</bridgehead>

<para>
<orderedlist spacing="compact">
  <listitem><para>
    Provide a standard interface to be used by process implementations.
  </para></listitem>
  <listitem><para>
    Provide registration mechanisms for processes.
  </para></listitem>
</orderedlist>
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Design and interfaces
</bridgehead>

<para>
Both requirements are implemented in a sub-set of the tracking-physics 
interface in Geant4}. The class diagram is shown in 
<xref linkend="fig.ExtdFuncHadPhys_1" />.

<figure id="fig.ExtdFuncHadPhys_1">
<title>
Level 1 implementation framework of the hadronic category of GEANT4.
</title>
<mediaobject>
  <imageobject role="fo">
    <imagedata fileref="./AllResources/GuideToExtendFunctionality/HadronicPhysics/Level1.gif" 
               format="GIF" align="center" contentwidth="10.0cm" />
  </imageobject>
  <imageobject role="html">
    <imagedata fileref="./AllResources/GuideToExtendFunctionality/HadronicPhysics/Level1.gif" 
               format="GIF" align="center" />
  </imageobject>
</mediaobject>
</figure>
</para>

<para>
All processes have a common base-class <literal>G4VProcess</literal>, 
from which a set of specialised classes are derived. Three of them are 
used as base classes for hadronic processes for particles at rest 
(<literal>G4VRestProcess</literal>), for interactions in flight 
(<literal>G4VDiscreteProcess</literal>), and for processes like
radioactive decay where the same implementation can represent both these 
extreme cases (<literal>G4VRestDiscrete-Process</literal>).
</para>

<para>
Each of these classes declares two types of methods; one for calculating the
time to interaction or the physical interaction length, allowing tracking to 
request the information necessary to decide on the process responsible for 
final state production, and one to compute the final state.  These are pure 
virtual methods, and have to be implemented in each individual derived class, 
as enforced by the compiler.
</para>


<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Framework functionality
</bridgehead>

<para>
The functionality provided is through the use of process base-class pointers 
in the tracking-physics interface, and the
<literal>G4Process-Manager</literal>. 
All functionality is implemented in abstract, and registration of derived process 
classes with the <literal>G4Process-Manager</literal> of an individual particle 
allows for arbitrary combination of both Geant4 provided processes, and 
user-implemented processes. This registration mechanism is a modification on a 
Chain of Responsibility.  It is outside the scope of the current paper, and its
description is available from 
<ulink url="http://geant4.web.cern.ch/geant4/support/userdocuments.shtml">
G4Manual</ulink>.
</para>

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.ExtdFuncHadPhys.L2F_CrssSctMdl">
<title>
Level 2 Framework - Cross Sections and Models
</title>

<para>
At the next level of abstraction, only processes that occur for particles
in flight are considered. For these, it is easily observed that the sources 
of cross sections and final state production are rarely the same.  Also, 
different sources will come with different restrictions.  The principal 
use-cases of the framework are addressing these commonalities.  A user might 
want to combine different cross sections and final state or isotope production
models as provided by Geant4, and a physicist might
want to implement his own model for particular situation, and add cross-section
data sets that are relevant for his particular analysis to the system in a
seamless manner.
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Requirements
</bridgehead>

<para>
<orderedlist spacing="compact">
  <listitem><para>
    Flexible choice of inclusive scattering cross-sections.
  </para></listitem>
  <listitem><para>
    Ability to use different data-sets for different parts of
    the simulation, depending on the conditions at the point of interaction.
  </para></listitem> 
  <listitem><para>
    Ability to add user-defined data-sets in a seamless manner.
  </para></listitem> 
  <listitem><para>
    Flexible, unconstrained choice of final state production models.
  </para></listitem> 
  <listitem><para>
    Ability to use different final state production codes 
    for different parts of the simulation, depending on the conditions at the 
    point of interaction.
  </para></listitem> 
  <listitem><para>
    Ability to add user-defined final state production models in
    a seamless manner.
  </para></listitem> 
  <listitem><para>
    Flexible choice of isotope production models, to run in
    parasitic mode to any kind of transport models.
  </para></listitem>
  <listitem><para>
    Ability to use different isotope production codes 
    for different parts of the simulation, depending on the conditions at the 
    point of interaction.
  </para></listitem> 
  <listitem><para>
    Ability to add user-defined isotope production models in a seamless manner.
  </para></listitem> 
</orderedlist>
</para>


<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Design and interfaces
</bridgehead>

<para>
The above requirements are implemented in three framework components, one 
for cross-sections, final state production, and isotope production each.
The class diagrams are shown in 
<xref linkend="fig.ExtdFuncHadPhys_2" />
for the cross-section aspects, 
<xref linkend="fig.ExtdFuncHadPhys_3" /> 
for the final state production aspects, and figure 
<xref linkend="fig.ExtdFuncHadPhys_4" /> 
for the isotope production aspects.

<figure id="fig.ExtdFuncHadPhys_2">
<title>
Level 2 implementation framework of the hadronic category of Geant4; 
cross-section aspect.
</title>
<mediaobject>
  <imageobject role="fo">
    <imagedata fileref="./AllResources/GuideToExtendFunctionality/HadronicPhysics/Level2_1.gif" 
               format="GIF" align="center" contentwidth="10.0cm" />
  </imageobject>
  <imageobject role="html">
    <imagedata fileref="./AllResources/GuideToExtendFunctionality/HadronicPhysics/Level2_1.gif" 
               format="GIF" align="center" />
  </imageobject>
</mediaobject>
</figure>

<figure id="fig.ExtdFuncHadPhys_3">
<title>
Level 2 implementation framework of the hadronic category of Geant4; 
final state production aspect.
</title>
<mediaobject>
  <imageobject role="fo">
    <imagedata fileref="./AllResources/GuideToExtendFunctionality/HadronicPhysics/Level2_2.gif" 
               format="GIF" align="center" contentwidth="10.0cm" />
  </imageobject>
  <imageobject role="html">
    <imagedata fileref="./AllResources/GuideToExtendFunctionality/HadronicPhysics/Level2_2.gif" 
               format="GIF" align="center" />
  </imageobject>
</mediaobject>
</figure>

<figure id="fig.ExtdFuncHadPhys_4">
<title>
Level 2 implementation framework of the hadronic category of Geant4; 
isotope production aspect
</title>
<mediaobject>
  <imageobject role="fo">
    <imagedata fileref="./AllResources/GuideToExtendFunctionality/HadronicPhysics/Level2_3.gif" 
               format="GIF" align="center" contentwidth="10.0cm" />
  </imageobject>
  <imageobject role="html">
    <imagedata fileref="./AllResources/GuideToExtendFunctionality/HadronicPhysics/Level2_3.gif" 
               format="GIF" align="center" />
  </imageobject>
</mediaobject>
</figure>
</para>

<para>
The three parts are integrated in the <literal>G4Hadronic-Process</literal> 
class, that serves as base-class for all hadronic processes of particles in flight.
</para>


<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Cross-sections
</bridgehead>

<para>
Each hadronic process is derived from <literal>G4Hadronic-Process}</literal>, 
which holds a list of ``cross section data sets''. 
The term ``data set'' is
representing an object that encapsulates methods and data for calculating 
total cross sections for a given process in a certain range of validity.
The implementations may take any form.  It can be a simple equation as well as 
sophisticated parameterisations, or evaluated data.
All cross section data set classes are derived from the abstract class 
<literal>G4VCrossSection-DataSet}</literal>, which declares methods that allow
the process inquire, about the applicability of an individual data-set through
<literal>IsApplicable(const G4DynamicParticle*, const G4Element*)</literal>,
and to delegate the calculation of the actual cross-section value through
<literal>GetCrossSection(const G4DynamicParticle*, const G4Element*)</literal>.
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Final state production
</bridgehead>

<para>
The <literal>G4HadronicInteraction</literal> base class is provided for final state 
generation.  It declares a minimal interface of only one pure virtual method:
<literal>G4VParticleChange* ApplyYourself(const G4Track &amp;, G4Nucleus &amp;)}.
</literal>

<literal>G4HadronicProcess</literal> provides a registry for final state
production models inheriting from <literal>G4Hadronic-Interaction</literal>.  
Again, final state production model is meant in very general terms.  This can 
be an implementation of a quark gluon string model 
<citation><xref linkend="biblio.QGSM" endterm="biblio.QGSM.abbrev"/></citation>, 
a sampling code  for ENDF/B data formats 
<citation><xref linkend="biblio.ENDFForm" endterm="biblio.ENDFForm.abbrev"/></citation>, 
or a parametrisation describing only 
neutron elastic scattering off Silicon up to 300~MeV.
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Isotope production
</bridgehead>

<para>
For isotope production, a base class (<literal>G4VIsotope-Production</literal>) 
is provided.  It declares a method 
<literal>G4IsoResult * GetIsotope(const G4Track &amp;, const G4Nucleus &amp;)</literal>
that calculates and returns the isotope production information.  Any concrete 
isotope production model will inherit from this class, and implement the 
method.  Again, the modeling possibilities are not limited, and the 
implementation of concrete production models is not restricted in any way. 
By convention, the <literal>GetIsotope</literal> method returns NULL, if the model
is not applicable for the current projectile target combination.
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect3'>
Framework functionality:
</bridgehead>

<para>
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Cross Sections
</bridgehead>

<para>
<literal>G4HadronicProcess</literal> provides registering possibilities 
for data sets. A default is provided covering all possible 
conditions to some approximation. The process stores and retrieves 
the data sets through a data store that acts like a FILO stack 
(a Chain of Responsibility with a 
First In Last Out decision strategy). This allows the user to map out 
the entire parameter space by overlaying cross section data sets to optimise 
the overall result.  Examples are the cross sections for low energy neutron 
transport. If these are registered last by the user, they will be used
whenever low energy neutrons are encountered. In all other conditions the 
system falls back on the default, or data sets with earlier registration dates.
 The fact that the registration is done through abstract base classes with no 
side-effects allows the user to implement and use his own cross sections. 
Examples are special reaction cross sections of 
&kappa;<superscript>0</superscript>-nuclear interactions 
that might be used for &epsi;/&epsi;' analysis at LHC to control the 
systematic error.
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Final state production
</bridgehead>

<para>
The <literal>G4HadronicProcess</literal> class provides a 
registration service for classes deriving from 
<literal>G4Hadronic-Interaction</literal>, and delegates final state 
production to the applicable model. 
<literal>G4Hadronic-Interaction</literal>provides the functionality needed 
to define and enforce the applicability of a particular model.  
Models inheriting from <literal>G4Hadronic-Interaction</literal> 
can be restricted in applicability in projectile 
type and energy, and can be activated/deactivated for individual materials and 
elements.  This allows a user to use final state production models in 
arbitrary combinations, and to write his own models for 
final state production. The design is a variant of a Chain of Responsibility.
An example would be the likely CMS scenario - the combination of low energy 
neutron transport with a quantum molecular dynamics 
<citation><xref linkend="biblio.QMD" endterm="biblio.QMD.abbrev"/></citation>, 
invariant phase space decay
<citation><xref linkend="biblio.CHIPS" endterm="biblio.CHIPS.abbrev"/></citation>, 
and fast parametrised models for calorimeter materials, with user defined 
modeling of interactions of spallation nucleons with the most abundant 
tracker and calorimeter materials. 
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Isotope production
</bridgehead>

<para>
The <literal>G4HadronicProcess</literal> by default calculates the isotope production 
information from the final state given by the transport model. In addition, it 
provides a registering mechanism for isotope production models that run in 
parasitic mode to the transport models and inherit from 
<literal>G4VIsotope-Production</literal>.  The registering mechanism behaves like a FILO 
stack, again based on Chain of Responsibility.  The models will be asked for 
isotope production information in inverse order of registration. The first 
model that returns a non-NULL value will be applied.  In addition, the 
<literal>G4Hadronic-Process</literal> provides the basic infrastructure for accessing and
steering of isotope-production information. It allows to enable and disable 
the calculation of isotope production information globally, or for individual 
processes, and to retrieve the isotope production information through the 
<literal>G4IsoParticleChange * GetIsotopeProductionInfo()}</literal>
method at the end of each step.  The <literal>G4HadronicProcess</literal> is a finite state
machine that will ensure the <literal>GetIsotope-ProductionInfo</literal> returns a 
non-zero value only at the first call after isotope production occurred.  An 
example of the use of this functionality is the study of activation of a 
Germanium detector in a high precision, low background experiment.
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.ExtdFuncHadPhys.L3F_ThrtMdl">
<title>
Level 3 Framework - Theoretical Models
</title>

<para>
<figure id="fig.ExtdFuncHadPhys_5">
<title>
Level 3 implementation framework of the hadronic category of Geant4; 
theoretical model aspect.
</title>
<mediaobject>
  <imageobject role="fo">
    <imagedata fileref="./AllResources/GuideToExtendFunctionality/HadronicPhysics/Level3_1.gif" 
               format="GIF" align="center" contentwidth="10.0cm" />
  </imageobject>
  <imageobject role="html">
    <imagedata fileref="./AllResources/GuideToExtendFunctionality/HadronicPhysics/Level3_1.gif" 
               format="GIF" align="center" />
  </imageobject>
</mediaobject>
</figure>

Geant4 provides at present one implementation framework for theory 
driven models.  The main use-case is that of a user wishing to use theoretical 
models in general, and to use various intra-nuclear transport or pre-compound 
models together with models simulating the initial interactions at very high 
energies. 
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Requirements
</bridgehead>

<para>
<orderedlist spacing="compact">
  <listitem><para>
    Allow to use or adapt any string-parton or parton transport
    <citation><xref linkend="biblio.VNI" endterm="biblio.VNI.abbrev"/></citation>, 
  </para></listitem>
  <listitem><para>
    Allow to adapt event generators, ex. 
    <citation><xref linkend="biblio.PYTHIA7" endterm="biblio.PYTHIA7.abbrev"/></citation>, 
    state production in shower simulation.
  </para></listitem>
  <listitem><para>
    Allow for combination of the above with any intra-nuclear transport (INT).
  </para></listitem>
  <listitem><para>
    Allow stand-alone use of intra-nuclear transport.
  </para></listitem>
  <listitem><para>
    Allow for combination of the above with any pre-compound model.
  </para></listitem>
  <listitem><para>
    Allow stand-alone use of any pre-compound model.
  </para></listitem>
  <listitem><para>
    Allow for use of any evaporation code.
  </para></listitem>
  <listitem><para>
    Allow for seamless integration of user defined components for any of the above.
  </para></listitem>
</orderedlist>
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Design and interfaces
</bridgehead>

<para>
To provide the above flexibility, the following abstract base classes have been
implemented:

<itemizedlist spacing="compact">
  <listitem><para>
    <literal>G4VHighEnergyGenerator</literal>
  </para></listitem>
  <listitem><para>
    <literal>G4VIntranuclearTransportModel</literal>
  </para></listitem>
  <listitem><para>
    <literal>G4VPreCompoundModel</literal>
  </para></listitem>
  <listitem><para>
    <literal>G4VExcitationHandler</literal>
  </para></listitem>
</itemizedlist>
</para>

<para>
In addition, the class <literal>G4TheoFS-Generator</literal> is provided to orchestrate 
interactions between these classes.  The class diagram is shown in 
<xref linkend="fig.ExtdFuncHadPhys_5" />. 
</para>

<para>
<literal>G4VHighEnergy-Generator</literal> serves as base class for parton transport or 
parton string models, and for Adapters to event generators.  This class 
declares two methods, <literal>Scatter</literal>, and 
<literal>GetWoundedNucleus</literal>.
</para>

<para>
The base class for INT inherits from <literal>G4Hadronic-Interaction</literal>, 
making any concrete implementation usable as a stand-alone model.  In doing so, it 
re-declares the <literal>ApplyYourself</literal> interface of 
<literal>G4Hadronic-Interaction</literal>,
and adds a second interface, <literal>Propagate</literal>, for further propagation
after high energy interactions. <literal>Propagate</literal>  takes as arguments a 
three-dimensional model of a wounded nucleus, and a set of secondaries with 
energies and positions.
</para>

<para>
The base class for pre-equilibrium decay models, <literal>G4VPre-CompoundModel</literal>,
inherits from <literal>G4Hadronic-Interaction</literal>, again making any concrete 
implementation usable as stand-alone model. It adds a pure virtual  
<literal>DeExcite</literal> method for further evolution of the system when 
intra-nuclear transport assumptions break down. 
<literal>DeExcite</literal> takes a <literal>G4Fragment</literal>,
the Geant4 representation of an excited nucleus, as argument.
</para>

<para>
The base class for evaporation phases, <literal>G4VExcitation-Handler</literal>, 
declares an abstract method, <literal>BreakItUP()</literal>, for compound decay.
</para>


<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Framework functionality
</bridgehead>

<para>
The <literal>G4TheoFSGenerator</literal> class inherits from 
<literal>G4Hadronic-Interaction</literal>, 
and hence can be registered as a model for final state production with a 
hadronic process.  It allows a concrete implementation of 
<literal>G4VIntranuclear-TransportModel</literal> and 
<literal>G4VHighEnergy-Generator</literal> to be 
registered, and delegates initial interactions, and intra-nuclear transport
of the corresponding secondaries to the respective classes. The design is a 
complex variant of a Strategy.  The most spectacular application of this 
pattern is the use of parton-string models for string excitation, quark 
molecular dynamics for correlated string decay, and quantum molecular dynamics 
for transport, a combination which promises to result in a coherent 
description of quark gluon plasma in high energy nucleus-nucleus interactions. 
</para>

<para>
The class <literal>G4VIntranuclearTransportModel</literal> provides 
registering mechanisms for concrete implementations of 
<literal>G4VPreCompound-Model</literal>, and provides 
concrete intra-nuclear transports with the possibility of delegating 
pre-compound decay to these models. 
</para>

<para>
<literal>G4VPreCompoundModel</literal> provides a registering mechanism 
for compound decay through the 
<literal>G4VExcitation-Handler</literal> interface, and provides concrete 
implementations with the possibility of delegating the decay of a compound 
nucleus.
</para>

<para>
The concrete scenario of <literal>G4TheoFS-Generator</literal> using a 
dual parton model 
and a classical cascade, which in turn uses an exciton pre-compound model that 
delegates to an evaporation phase, would be the following: 
<literal>G4TheoFS-Generator</literal> receives the conditions of the interaction; 
a primary particle and a nucleus. It asks the dual parton model to perform the 
initial scatterings, and return the final state, along with the by then 
damaged nucleus.  The nucleus records all information on the damage sustained.
<literal>G4TheoFS-Generator</literal> forwards all information to the classical cascade, 
that propagates the particles in the already damaged nucleus, keeping track of 
interactions, further damage to the nucleus, etc.. Once the cascade assumptions
break down, the cascade will collect the information of the current state of 
the hadronic system, like excitation energy and number of excited particles, 
and interpret it as a pre-compound system.  It delegates the decay of this to 
the exciton model.  The exciton model will take the information provided, and 
calculate
transitions and emissions, until the number of excitons in the system equals
the mean number of excitons expected in equilibrium for the current excitation 
energy. Then it hands over to the
evaporation phase. The evaporation phase decays the residual nucleus, and the Chain of
Command rolls back to <literal>G4TheoFS-Generator</literal>, accumulating the 
information produced in the various levels of delegation.
</para>

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.ExtdFuncHadPhys.L4F_StgPartIntNuc">
<title>
Level 4 Frameworks - String Parton Models and Intra-Nuclear Cascade
</title>

<para>
<figure id="fig.ExtdFuncHadPhys_6">
<title>
Level 4 implementation framework of the hadronic category of Geant4; 
parton string aspect.
</title>
<mediaobject>
  <imageobject role="fo">
    <imagedata fileref="./AllResources/GuideToExtendFunctionality/HadronicPhysics/Level4_1.gif" 
               format="GIF" align="center" contentwidth="10.0cm" />
  </imageobject>
  <imageobject role="html">
    <imagedata fileref="./AllResources/GuideToExtendFunctionality/HadronicPhysics/Level4_1.gif" 
               format="GIF" align="center" />
  </imageobject>
</mediaobject>
</figure>

<figure id="fig.ExtdFuncHadPhys_7">
<title>
Level 4 implementation framework of the hadronic category of Geant4; 
intra-nuclear transport aspect.
</title>
<mediaobject>
  <imageobject role="fo">
    <imagedata fileref="./AllResources/GuideToExtendFunctionality/HadronicPhysics/Level4_2.gif" 
               format="GIF" align="center" contentwidth="10.0cm" />
  </imageobject>
  <imageobject role="html">
    <imagedata fileref="./AllResources/GuideToExtendFunctionality/HadronicPhysics/Level4_2.gif" 
               format="GIF" align="center" />
  </imageobject>
</mediaobject>
</figure>
</para>

<para>
The use-cases of this level are related to commonalities and detailed choices 
in string-parton models and cascade models. They are use-cases of an expert
user wishing to alter details of a model, or a theoretical physicist, wishing 
to study details of a particular model.
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Requirements
</bridgehead>

<para>
<orderedlist spacing="compact">
  <listitem><para>
    Allow to select string decay algorithm 
  </para></listitem>
  <listitem><para>
    Allow to select string excitation.
  </para></listitem>
  <listitem><para>
    Allow the selection of concrete implementations of three-dimensional 
    models of the nucleus
  </para></listitem>
  <listitem><para>
    Allow the selection of concrete implementations of final state and 
    cross sections in intra-nuclear scattering.
  </para></listitem>
</orderedlist>
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Design and interfaces
</bridgehead>

<para>
To fulfil the requirements on string models, two abstract classes are provided,
the <literal>G4VParton-StringModel</literal> and the 
<literal>G4VString-Fragmentation</literal>. 
The base class for parton string models, <literal>G4VParton-StringModel</literal>, 
declares the <literal>GetStrings()</literal> pure virtual method. 
<literal>G4VString-Fragmentation</literal>, the pure abstract base class for string 
fragmentation, declares the interface for string fragmentation.
</para>

<para>
To fulfill the requirements on intra-nuclear transport, two abstract classes 
are provided, <literal>G4V3DNucleus</literal>, and <literal>G4VScatterer</literal>.
At this point in time, the usage of these intra-nuclear transport related classes 
by concrete codes is not enforced by designs, as the details of the
cascade loop are still model dependent, and more experience has to be gathered to achieve
standardisation. It is within the responsibility of the implementers of concrete 
intra-nuclear transport 
codes to use the abstract interfaces as defined in these classes.
</para>

<para>
The class diagram is shown in  
<xref linkend="fig.ExtdFuncHadPhys_6" />
for the string parton model aspects, and in
<xref linkend="fig.ExtdFuncHadPhys_7" />
for the intra-nuclear transport. 
</para>


<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Framework functionality
</bridgehead>

<para>
Again variants of Strategy, Bridge and Chain of Responsibility are used.
<literal>G4VParton-StringModel</literal> implements the initialisation of a 
three-dimensional model of a nucleus, and the logic of scattering.  It 
delegates secondary production to string fragmentation through a 
<literal>G4VString-Fragmentation</literal> pointer. It provides a registering service for 
the concrete string fragmentation, and delegates the string excitation to 
derived classes. Selection of string excitation is through selection of 
derived class. Selection of string fragmentation is through registration.
</para>

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.ExtdFuncHadPhys.L5F_StrgDeExc">
<title>
Level 5 Framework - String De-excitation}
</title>

<para>
<figure id="fig.ExtdFuncHadPhys_8">
<title>
Level 5 implementation framework of the hadronic category of Geant4; 
string fragmentation aspect.
</title>
<mediaobject>
  <imageobject role="fo">
    <imagedata fileref="./AllResources/GuideToExtendFunctionality/HadronicPhysics/Level5_1.gif" 
               format="GIF" align="center" contentwidth="10.0cm" />
  </imageobject>
  <imageobject role="html">
    <imagedata fileref="./AllResources/GuideToExtendFunctionality/HadronicPhysics/Level5_1.gif" 
               format="GIF" align="center" />
  </imageobject>
</mediaobject>
</figure>
</para>

<para>
The use-case of this level is that of a user or theoretical physicist wishing 
to understand the systematic effects involved in combining various 
fragmentation functions with individual types of string fragmentation.  Note 
that this framework level is meeting the current state of the art, making 
extensions and changes of interfaces in subsequent releases likely.
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Requirements
</bridgehead>

<para>
<orderedlist spacing="compact">
  <listitem><para>
    Allow the selection of fragmentation function.
  </para></listitem>
</orderedlist>
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Design and interfaces
</bridgehead>

<para>
A base class for fragmentation functions, 
<literal>G4VFragmentation-Function}</literal>, is 
provided.  It declares the <literal>GetLightConeZ()</literal> interface.
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Framework functionality
</bridgehead>

<para>
The design is a basic Strategy. The class diagram is shown in 
<xref linkend="fig.ExtdFuncHadPhys_8" />.  
At this point in time, the usage of the 
<literal>G4VFragmentation-Function</literal> is not enforced by design, 
but made available from the 
<literal>G4VString-Fragmentation</literal> to an implementer of a concrete string 
decay. <literal>G4VString-Fragmentation</literal> provides a registering 
mechanism for the
concrete fragmentation function. It delegates the calculation of 
z<subscript>f</subscript> of the 
hadron to split of the string to the concrete implementation. Standardisation 
in this area is expected.
</para>

</sect2>
</sect1>