source: trunk/documents/UserDoc/UsersGuides/ForToolkitDeveloper/latex/OOAnalysisDesign/PhysicsProcesses/Hadronic/hadronic.tex

\section{Hadronic Processes}
The purpose of this note is to publish the implementation frameworks used in and
provided by {\sc 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 {\sc 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{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.}.
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 \cite{Patterns}.
\section{Level 1 Framework - processes}
\begin{figure}[b!] % fig 1
\centerline{\includegraphics[width=14cm]{Level1.eps}}
\caption{Level 1 implementation framework of the hadronic category 
of {\sc Geant4}.}
\label{Level1}
\end{figure}
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. 
\subsection {Requirements}
\begin{enumerate}
\item \label{L1R1} Provide a standard interface to be used by process implementations.
\item \label{L1R2} Provide registration mechanisms for processes.
\end{enumerate}
\subsection {Design and interfaces}
Both requirements are implemented in a sub-set of the tracking-physics interface
in {\sc Geant4}. The class diagram is shown in figure \ref{Level1}. 
All processes have a common base-class {\tt G4VProcess}, from
which a set of specialised classes are derived. Three of them are used as base
classes for hadronic processes for particles at rest ({\tt G4VRestProcess}), for
interactions in flight ({\tt G4VDiscreteProcess}), and for processes like
radioactive decay where the same implementation can represent both these extreme cases 
({\tt G4VRestDiscreteProcess}).

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.
\subsection {Framework functionality}
The functionality provided is through the use of process base-class pointers 
in the tracking-physics interface, and the {\tt G4ProcessManager}. All
functionality is implemented in abstract, and registration of derived process classes
with the {\tt G4ProcessManager} of an individual particle allows for
arbitrary combination of both {\sc 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 \cite{G4Manual}.
\section{Level 2 Framework - Cross-sections and Models}
\begin{figure}[b!] % fig 1
\centerline{\includegraphics[width=14cm]{Level2_1.eps}}
\caption{Level 2 implementation framework of the hadronic category 
of {\sc Geant4}; cross-section aspect.}
\label{Level2_1}
\end{figure}
\begin{figure}[b!] % fig 1
\centerline{\includegraphics[width=14cm]{Level2_2.eps}}
\caption{Level 2 implementation framework of the hadronic category 
of {\sc Geant4}; final state production aspect.}
\label{Level2_2}
\end{figure}
\begin{figure}[b!] % fig 1
\centerline{\includegraphics[width=14cm]{Level2_3.eps}}
\caption{Level 2 implementation framework of the hadronic category 
of {\sc Geant4}; isotope production aspect}
\label{Level2_3}
\end{figure}
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 {\sc 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.
\subsection {Requirements}
\begin{enumerate}
\item  Flexible choice of inclusive scattering cross-sections.
\item  Ability to use different data-sets for different parts of
the simulation, depending on the conditions at the point of interaction.
\item  Ability to add user-defined data-sets in a seamless manner.
\item  Flexible, unconstrained choice of final state production models.
\item  Ability to use different final state production codes 
for different parts of the simulation, depending on the conditions at the 
point of interaction.
\item  Ability to add user-defined final state production models in
a seamless manner.
\item Flexible choice of isotope production models, to run in
parasitic mode to any kind of transport models.
\item  Ability to use different isotope production codes 
for different parts of the simulation, depending on the conditions at the 
point of interaction.
\item  Ability to add user-defined isotope production models in a 
seamless manner.
\end{enumerate}
\subsection {Design and interfaces}
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 figure \ref{Level2_1} for the cross-section aspects,
figure \ref{Level2_2} for the final state production aspects, and figure \ref{Level2_3}
for the isotope production aspects. 
The three parts are integrated in the {\tt G4HadronicProcess} class, that serves as
base-class for all hadronic processes of particles in flight.
\subsubsection{Cross-sections}
Each hadronic process is derived from {\tt G4HadronicProcess}, 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 
{\tt G4VCrossSectionDataSet}, which declares methods that allow
the process inquire, about the applicability of an individual data-set through
{\tt IsApplicable(const G4DynamicParticle*, const G4Element*)},
and to de\-le\-gate the calculation of the actual cross-section value through
\\
{\tt GetCrossSection(const G4DynamicParticle*, const G4Element*)}.
\subsubsection{Final state production}
For final state production, we provide the {\tt G4HadronicInteraction} base class.
It declares a minimal interface of only one pure virtual method for final state
production,
\\
{\tt G4VParticleChange* ApplyYourself(const G4Track \&, G4Nucleus \&)}.
\\
{\tt G4HadronicProcess} provides a registry for final state
production models inheriting from {\tt G4HadronicInteraction}. Again, final state production
model is meant in very general terms. This can be an implementation of a
quark gluon string model\cite{QGSM}, a sampling code for ENDF/B data formats\cite{ENDFForm}, or a parametrisation
describing only neutron elastic scattering off Silicon up to 300~MeV.
\subsubsection{Isotope production}
For isotope production, a base class ({\tt G4VIsotopeProduction}) is provided. It declares a
method ({\tt G4IsoResult * GetIsotope(const G4Track \&, const G4Nucleus \&)})
that calculates and returns the isotope production information. Any concrete isotope
production model will inherit from this class, and implement the method. Again, the modelling
possibilities are not limited, and the implementation of concrete production models is not
restricted in any way. By convention, the {\tt GetIsotope} method returns NULL, if the model
is not applicable for the current projectile target combination.
\subsection {Framework functionality}
\subsubsection{Cross-sections}
{\tt G4HadronicProcess} 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. An example 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. An example are special 
reaction cross-sections of $K^0$-nuclear interactions that might be used for
$\epsilon/\epsilon '$ analysis at LHC to control the systematic error.
\subsubsection{Final state production}
The {\tt G4HadronicProcess} provides a registration service for classes deriving from {\tt
G4HadronicInteraction}, and delegates final state production to the applicable model. 
{\tt G4HadronicInteraction} provides the functionality needed to define and enforce 
the applicability of a particular model. Models inheriting from {\tt G4HadronicInteraction} 
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 Responsability.
An example would be the likely CMS scenario - the
combination of low energy neutron transport with a quantum molecular
dynamics\cite{QMD} or chiral
invariant phase space decay\cite{CHIPS} model
in the case of tracker materials and fast parametrised models for calorimeter materials, 
with user defined modelling of interactions of spallation nucleons with the most abundant 
tracker and calorimeter materials. 
\subsubsection{Isotope production}
The {\tt G4HadronicProcess} 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 {\tt G4VIsotopeProduction}. 
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 {\tt G4HadronicProcess} 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 
\\
{\tt G4IsoParticleChange * GetIsotopeProductionInfo()} 
method at
the end of each step. The {\tt
G4HadronicProcess} is a finite state machine that will ensure the {\tt
GetIsotopeProductionInfo} 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.
\section{Level 3 Framework - Theoretical Models}
\begin{figure}[b!] % fig 1
\centerline{\includegraphics[width=14cm]{Level3_1.eps}}
\caption{Level 3 implementation framework of the hadronic category 
of {\sc Geant4}; theoretical model aspect.}
\label{Level3_1}
\end{figure}
{\sc 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. 
\subsection {Requirements}
\begin{enumerate}
\item Allow to use or adapt any string-parton or parton transport\cite{VNI} model.
\item Allow to adapt event generators, ex. PYTHIA\cite{PYTHIA7} for final state production in shower simulation.
\item Allow for combination of the above with any intra-nuclear transport (INT).
\item Allow stand-alone use of intra-nuclear transport.
\item Allow for combination of the above with any pre-compound model.
\item Allow stand-alone use of any pre-compound model.
\item Allow for use of any evaporation code.
\item Allow for seamless integration of user defined components for any of the above.
\end{enumerate}
\subsection {Design and interfaces}
To provide the above flexibility, the following abstract base classes have been
implemented:
\begin{itemize}
\item {\tt G4VHighEnergyGenerator}
\item {\tt G4VIntranuclearTransportModel}
\item {\tt G4VPreCompoundModel}
\item {\tt G4VExcitationHandler}
\end{itemize}
In addition, the class {\tt G4TheoFSGenerator} is provided to orchestrate interactions 
between these classes. 
The class diagram is shown in figure \ref{Level3_1}. 

{\tt G4VHighEnergyGenerator} serves as base class for parton transport or parton 
string models, and for Adapters to event generators. This class declares two methods, 
{\tt Scatter}, and {\tt GetWoundedNucleus}. 

The base class for INT inherits from
{\tt G4HadronicInteraction}, making any concrete implementation usable as
stand-alone model. In doing so, it 
re-declares the {\tt ApplyYourself} interface of {\tt
G4HadronicInteraction}, and adds a second interface, {\tt Propagate}, for further propagation
after high energy interactions. {\tt Propagate}  takes as arguments
a three-dimensions model of a wounded nucleus, and a set of secondaries with energies 
and positions.

The base class for pre-equilibrium decay models, {\tt G4VPreCompoundModel},
 inherits from {\tt G4HadronicInteraction}, again 
making any concrete implementation usable as stand-alone model. It adds a pure virtual  
{\tt DeExcite} method 
for further evolution of the system when intra-nuclear transport assumptions
break down. {\tt DeExcite} takes a {\tt G4Fragment}, the {\sc Geant4} representation of an
excited nucleus, as argument.

The base class for evaporation phases, {\tt G4VExcitationHandler}, declares an 
abstract method, {\tt BreakItUP()}, for compound decay.
\subsection {Framework functionality}
{\tt G4TheoFSGenerator} inherits from {\tt G4HadronicInteraction}, and hence can be 
registered as model for final state production with a hadronic process. It allows to
register a concrete implementation of {\tt G4VIntranuclearTransportModel} and 
{\tt G4VHighEnergyGenerator}, 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. 

{\tt G4VIntranuclearTransportModel} provides registering mechanisms for concrete
implementations of {\tt G4VPreCompoundModel}, and provides concrete intra-nuclear transports
with the possibility to delegate pre-compound decay to these models. 

{\tt G4VPreCompoundModel} provides a registering mechanism for compound decay through the
{\tt G4VExcitationHandler} interface, and provides concrete implementations with the
possibility to delegate the decay of a compound nucleus.

The concrete scenario of {\tt G4TheoFSGenerator} 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: {\tt G4TheoFSGenerator} 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.
{\tt G4TheoFSGenerator} 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 {\tt G4TheoFSGenerator}, accumulating the information produced in 
the various levels of delegation.
\section{Level 4 Frameworks - String Parton Models and Intra-Nuclear Cascade}
\begin{figure}[b!] % fig 1
\centerline{\includegraphics[width=14cm]{Level4_1.eps}}
\caption{Level 4 implementation framework of the hadronic category 
of {\sc Geant4}; parton string aspect.}
\label{Level4_1}
\end{figure}
\begin{figure}[b!] % fig 1
\centerline{\includegraphics[width=14cm]{Level4_2.eps}}
\caption{Level 4 implementation framework of the hadronic category 
of {\sc Geant4}; intra-nuclear transport aspect.}
\label{Level4_2}
\end{figure}
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.
\subsection {Requirements}
\begin{enumerate}
\item Allow to select string decay algorithm 
\item Allow to select string excitation.
\item Allow to select concrete implementation of three-dimensional model of the nucleus
\item Allow to select concrete implementation of final state and cross-sections in
intra-nuclear scattering.
\end{enumerate}
\subsection {Design and interfaces}
To fulfil the requirements on string models, two abstract classes are provided,
the {\tt G4VPartonStringModel} and the {\tt G4VStringFragmentation}. 
The base class for parton string models, {\tt G4VPartonStringModel}, 
declares the {\tt GetStrings()}
pure virtual method. {\tt G4VStringFragmentation}, the pure abstract
base class for string fragmentation, declares the interface for string fragmentation.

To fulfil the requirements on intra-nuclear transport, two abstract classes are provided,
{\tt G4V3DNucleus}, and {\tt G4VScatterer}.
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.

The class diagram is shown in figure \ref{Level4_1} for the string parton model aspects, and
in figure \ref{Level4_2} for the intra-nuclear transport. 

\subsection{Framework functionality}
Again variants of Strategy, Bridge and Chain of Responsibility are used.
{\tt G4VPartonStringModel} 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 {\tt G4VStringFragmentation} 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.

\section{Level 5 Framework - String De-excitation}

\begin{figure}[b!] % fig 1
\centerline{\includegraphics[width=14cm]{Level5_1.eps}}
\caption{Level 5 implementation framework of the hadronic category 
of {\sc Geant4}; string fragmentation aspect.}
\label{Level5_1}
\end{figure}
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.
\subsection {Requirements}
\begin{enumerate}
\item Allow the selection of fragmentation function.
\end{enumerate}
\subsection {Design and interfaces}
A base class for fragmentation functions, {\tt G4VFragmentationFunction}, is provided.
It declaring the {\tt GetLightConeZ()} interface.
\subsection {Framework functionality}
The design is a basic Strategy. The class diagram is shown in figure \ref{Level5_1}. 
At this point in time, the usage of the {\tt G4VFragmentationFunction} is not enforced 
by design, but made available from the {\tt G4VStringFragmentation} to an implementer of a
concrete string decay. {\tt G4VStringFragmentation} provides a registering mechanism for the
concrete fragmentation function. It delegates the calculation of $z_f$ of the hadron to
split of the string to the concrete implementation. Standardisation in this area is expected.
\section{Summary}
A set of implementation frameworks has been provided for hadronic shower simulation. Finding
framework functional requirements through use-case analysis has proven to be a highly
effective tool. Framework components were found through bundling use-cases. Framework
interfaces were defined by the need for delegation and flexibility; framework functionality 
was found from detailed requirements analysis.

The Russian dolls approach, as defined in this paper, to framework design has proven very effective. Having layered
implementation frameworks, and keeping abstractions in the upper levels of the framework
hierarchy simple and general has
proven to result in a structured and well suited solution to a complex problem. 
Addressing more specific use-cases in lower
level frameworks that implement the interfaces of the more general framework has kept the
system surprisingly extendible. It allows for distributed, and largely decoupled contributions 
of many scientists.
\begin{thebibliography}{999}
\bibitem{Geant4} The GEANT~4 Collaboration, \\
CERN/DRDC/94--29, DRDC/P58 1994.
\bibitem{Patterns} E. Gamm et al., Design Patterns, Addison-Wesley Professional Computing
Series, 1995.
\bibitem{G4Manual} 
{\scriptsize http://cern.ch/geant4/G4UsersDocuments/Overview/html/index.html}
\bibitem{QGSM} Kaidalov A. B., Ter-Martirosyan K. A., Phys. Lett. {\bf B117}
247 (1982); 
\bibitem{ENDFForm} 
Data Formats and Procedures for the Evaluated Nuclear Data 
 File, National Nuclear Data Center, Brookhave National Laboratory, Upton, NY, USA.
\bibitem{QMD} For example: VUU and (R)QMD model of high-energy heavy ion collisions.
H. Stocker et al., Nucl. Phys. A538, 53c-64c (1992)
\bibitem{CHIPS} P.V. Degtyarenko, M.V. Kossov, H.P. Wellisch, Eur. Phys J. A 8, 217-222
(2000)
\bibitem{VNI} VNI 3.1, Klaus Geiger (Brookhaven), BNL-63762, 
Comput. Phys. Commun. 104, 70-160 (1997)
\bibitem{PYTHIA7} M. Bertini, L. L\"onnblad, T. Sj\"orstrand, Pythia version 7-0.0 -- a
proof-of-concept version, LU-TP 00-23, hep-ph/0006152, May 2000

\end{thebibliography}