source: trunk/documents/UserDoc/DocBookUsersGuides/ForApplicationDeveloper/xml/GettingStarted/particleDef.xml @ 1208

<!-- ******************************************************** -->
<!--                                                          -->
<!--  [History]                                               -->
<!--    Changed by: Katsuya Amako,  4-Aug-1998                -->
<!--    Proof read by: Joe Chuma,  15-Jun-1999                -->
<!--    Changed by: Hisaya Kurashige, 28-Oct-2001             -->
<!--    Changed by: Dennis Wright, 29-Nov-2001                -->
<!--    Converted to DocBook: Katsuya Amako, Aug-2006         -->
<!--    Changed by: Hisaya Kurashige, 18-Jan-2007             -->
<!--    Changed by: Hisaya Kurashige, 1-Dec-2007              -->
<!--    modified 2.4.2 by: Hisaya Kurashige, 23-Nov-2009      -->
<!--                                                          -->
<!-- ******************************************************** -->


<!-- ******************* Section (Level#1) ****************** -->
<sect1 id="sect.HowToSpecParti">
<title>
How to Specify Particles
</title>

<para>
<literal>G4VuserPhysicsList</literal> is one of the mandatory user base
classes described in 
<xref linkend="sect.HowToDefMain" />.
Within this class all particles and physics processes to be used in
your simulation must be defined. The range cut-off parameter should
also be defined in this class.
</para>

<para>
The user must create a class derived from
<literal>G4VuserPhysicsList</literal> and implement the following pure
virtual methods:

<informalexample>
<programlisting>
ConstructParticle();      // construction of particles
ConstructProcess();       // construct processes and register them to particles
SetCuts();                // setting a range cut value for all particles
</programlisting>
</informalexample>
</para>

<para>
This section provides some simple examples of the
<literal>ConstructParticle()</literal> and <literal>SetCuts()</literal>
methods. 
For information on <literal>ConstructProcess()</literal> methods, please see
<xref linkend="sect.HowToSpecPhysProc" />.

</para>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.HowToSpecParti.PartiDef">
<title>
Particle Definition
</title>

<para>
Geant4 provides various types of particles for use in simulations:

<itemizedlist spacing="compact">
  <listitem><para>
  ordinary particles, such as electrons, protons, and gammas
  </para></listitem>
  <listitem><para>
  resonant particles with very short lifetimes, such as vector
  mesons and delta baryons
  </para></listitem>
  <listitem><para>
  nuclei, such as deuteron, alpha, and heavy ions (including hyper-nuclei)
  </para></listitem>
  <listitem><para>
  quarks, di-quarks, and gluon
  </para></listitem>
</itemizedlist>
</para>

<para>
Each particle is represented by its own class, which is derived
from <literal>G4ParticleDefinition</literal>. 
(Exception: G4Ions represents all heavy nuclei. Please see
<xref linkend="sect.Parti" />.)
Particles are organized into six major categories:

<itemizedlist spacing="compact">
  <listitem><para>
  lepton,
  </para></listitem>
  <listitem><para>
  meson,
  </para></listitem>
  <listitem><para>
  baryon,
  </para></listitem>
  <listitem><para>
  boson,
  </para></listitem>
  <listitem><para>
  shortlived and
  </para></listitem>
  <listitem><para>
  ion,
  </para></listitem>
</itemizedlist>

each of which is defined in a corresponding sub-directory under
<literal>geant4/source/particles</literal>. There is also a corresponding
granular library for each particle category.
</para>


<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.HowToSpecParti.PartiDef.G4ParticleDefinition">
<title>
The <literal>G4ParticleDefinition</literal> Class
</title>

<para>
<literal>G4ParticleDefinition</literal> has properties which characterize
individual particles, such as, name, mass, charge, spin, and so on.
Most of these properties are "read-only" and can not be changed directly.
<literal>G4ParticlePropertyTable</literal> is used to retrieve (load) 
particle property of <literal>G4ParticleDefinition</literal> 
into (from) <literal>G4ParticlePropertyData</literal>.
</para>

</sect3>

<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.HowToSpecParti.PartiDef.HowToAccessParti">
<title>
How to Access a Particle
</title>

<para>
Each particle class type represents an individual particle type,
and each class has a single object. This object can be accessed by 
using the static method of each class.
There are some exceptions to this rule; please see 
<xref linkend="sect.Parti" /> for details.
</para>

<para>
For example, the class <literal>G4Electron</literal> represents the
electron and the member <literal>G4Electron::theInstance</literal> 
points its only object. 
The pointer to this object is available
through the static methods
<literal>G4Electron::ElectronDefinition()</literal>.
<literal>G4Electron::Definition()</literal>.
</para>

<para>
More than 100 types of particles are provided by default, to be
used in various physics processes. In normal applications, users
will not need to define their own particles.
</para>

<para>
The unique object for each particle class is created when its static 
method to get the pointer is called at the first time.
Because particles are dynamic objects and should be instantiated before 
initialization of physics processes, 
you must explicitly invoke static methods of all particle classes 
required by your program at the initialization step.
(NOTE: The particle object was static and created automatically before 8.0 release)
</para>

</sect3>

<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.HowToSpecParti.PartiDef.DictOfParti">
<title>Dictionary of Particles
</title>

<para>
The <literal>G4ParticleTable</literal> class is provided as a dictionary of
particles. Various utility methods are provided, such as:

<informalexample>
<programlisting>
FindParticle(G4String name);         // find the particle by name
FindParticle(G4int PDGencoding)      // find the particle by PDG encoding .
</programlisting>
</informalexample>
</para>

<para>
<literal>G4ParticleTable</literal> is defined as a singleton object,
and the static method <literal>G4ParticleTable::GetParticleTable()</literal>
provides its pointer.
</para>

<para>
As for heavy ions (including hyper-nuclei), objects are created
dynamically by requests from users and processes.  
The <literal>G4ParticleTable</literal> class provides
methods to create ions, such as:
<informalexample>
<programlisting>
G4ParticleDefinition* GetIon(  G4int    atomicNumber,  
                               G4int    atomicMass, 
                               G4double   excitationEnergy);
</programlisting>
</informalexample>
</para>

<para>
Particles are registered automatically during construction. The
user has no control over particle registration.
</para>


</sect3>

<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.HowToSpecParti.PartiDef.ConstruParti">
<title>
Constructing Particles
</title>

<para>
<literal>ConstructParticle()</literal> is a pure virtual method, in which 
the static member functions for all the particles you require should be called.
This ensures that objects of these particles are created.
</para>

<para>
WARNING: You must define "All PARTICLE TYPES" which are used in your
application, except for heavy ions. 
"All PARTICLE TYPES" means not only primary 
particles, but also all other particles which may appear as secondaries 
generated by physics processes you use. Beginning with Geant4 version 8.0, 
you should keep this rule strictly because all particle definitions are 
revised to "non-static" objects.
</para>

<para>
For example, suppose you need a proton and a geantino, which is
a virtual particle used for simulation and which does not interact
with materials. The <literal>ConstructParticle()</literal> method is
implemented as below:

<example id="programlist_HowToSpecParti_1">
<title>
Construct a proton and a geantino.
</title>
<programlisting>
 void ExN01PhysicsList::ConstructParticle()
 {
   G4Proton::ProtonDefinition();
   G4Geantino::GeantinoDefinition();
 }
</programlisting>
</example>
</para>

<para>
Due to the large number of pre-defined particles in Geant4, it
is cumbersome to list all the particles by this method. If you want
all the particles in a Geant4 particle category, there are six
utility classes, corresponding to each of the particle categories,
which perform this function:

<itemizedlist spacing="compact">
  <listitem><para>
  <literal>G4BosonConstructor</literal>
  </para></listitem>
  <listitem><para>
  <literal>G4LeptonConstructor</literal>
  </para></listitem>
  <listitem><para>
  <literal>G4MesonConstructor</literal>
  </para></listitem>
  <listitem><para>
  <literal>G4BarionConstructor</literal>
  </para></listitem>
  <listitem><para>
  <literal>G4IonConstructor</literal>
  </para></listitem>
  <listitem><para>
  <literal>G4ShortlivedConstructor</literal>.
  </para></listitem>
</itemizedlist>
</para>

<para>
An example of this is shown in <literal>ExN05PhysicsList</literal>, 
listed below.

<example id="programlist_HowToSpecParti_2">
<title>
Construct all leptons.
</title>
<programlisting>
void ExN05PhysicsList::ConstructLeptons()
{
  // Construct all leptons
  G4LeptonConstructor pConstructor;
  pConstructor.ConstructParticle();
}
</programlisting>
</example>
</para>

</sect3>
</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.HowToSpecParti.RangeCuts">
<title>
Range Cuts
</title>

<para>
To avoid infrared divergence, some electromagnetic processes
require a threshold below which no secondary will be generated.
Because of this requirement, gammas, electrons and positrons
require production thresholds which the user should define. This
threshold should be defined as a distance, or range cut-off, which
is internally converted to an energy for individual materials. The
range threshold should be defined in the initialization phase using
the <literal>SetCuts()</literal> method of <literal>G4VUserPhysicsList</literal>.
<xref linkend="sect.CutReg" /> discusses threshold and tracking 
cuts in detail.
</para>



<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.HowToSpecParti.RangeCuts.SetCuts">
<title>
Setting the cuts
</title>

<para>
Production threshold values should be defined in <literal>SetCuts()</literal>
which is a pure virtual method of the <literal>G4VUserPhysicsList</literal>
class. Construction of particles, materials, and processes should
precede the invocation of <literal>SetCuts()</literal>. <literal>G4RunManager</literal>
takes care of this sequence in usual applications.
</para>
<para> 
This range cut value is converted threshold energies 
for each material and for each particle type (i.e. electron,
positron and gamma) 
so that the particle with threshold energy stops (or is absorbed) 
after traveling the range cut distance.   
In addition, from the 9.3 release ,this range cut value is applied 
to the proton as production thresholds of nuclei for  hadron 
elastic processes. In this case, the range cut value does not means 
the distance of traveling. Threshold energies are calculated 
by a simple formula from the cut in range. 
</para>

<para>
Note that the upper limit of the threshold energy is defined as 10
GeV. If you want to set higher threshold energy, you can change 
the limit by using "/cuts/setMaxCutEnergy" command before setting
the range cut.
</para>

<para>
The idea of a "unique cut value in range" is one of the
important features of Geant4 and is used to handle cut values in a
coherent manner. For most applications, users need to determine
only one cut value in range, and apply this value to gammas,
electrons and positrons alike. (and proton too)
</para>

<para>
In such case, the <literal>SetCutsWithDefault()</literal> method may be
used. It is provided by the <literal>G4VuserPhysicsList</literal> base class,
which has a <literal>defaultCutValue</literal> member as the default range
cut-off value. <literal>SetCutsWithDefault()</literal> uses this value.
</para>

<para>
It is possible to set different range cut values for gammas,
electrons and positrons, and also to set different range cut values
for each geometrical region. In such cases however, one must be
careful with physics outputs because Geant4 processes (especially
energy loss) are designed to conform to the "unique cut value in
range" scheme.

<example id="programlist_HowToSpecParti_3">
<title>
Set cut values by using the default cut value.
</title>
<programlisting>
void ExN04PhysicsList::SetCuts()
{
  //   the G4VUserPhysicsList::SetCutsWithDefault() method sets 
  //   the default cut value for all particle types 
  SetCutsWithDefault();   
}
</programlisting>
</example>
</para>

<para>
The <literal>defaultCutValue</literal> is set to 1.0 mm by default. Of
course, you can set the new default cut value in the constructor of
your physics list class as shown below.

<example id="programlist_HowToSpecParti_4">
<title>
Set the default cut value.
</title>
<programlisting>
ExN04PhysicsList::ExN04PhysicsList():  G4VUserPhysicsList()
{
  // default cut value  (1.0mm) 
  defaultCutValue = 1.0*mm;
}
</programlisting>
</example>
</para>

<para>
The <literal>SetDefaultCutValue()</literal> method in
<literal>G4VUserPhysicsList</literal> may also be used, 
and the "/run/setCut" command may be used 
to change the default cut value interactively.
</para>

<para>
You can set different cut values in range for different 
particle types. The "/run/setCutForAGivenParticle"  command 
may be used interactively.
</para>

<para>
WARNING: DO NOT change cut values inside the event loop. Cut
values may however be changed between runs.
</para>

<para>
An example implementation of <literal>SetCuts()</literal> is shown
below:

<example id="programlist_HowToSpecParti_5">
<title>
Example implementation of the <literal>SetCuts()</literal> method.
</title>
<programlisting>
void ExN03PhysicsList::SetCuts()
{
  // set cut values for gamma at first and for e- second and next for e+,
  // because some processes for e+/e- need cut values for gamma 
  SetCutValue(cutForGamma, "gamma");
  SetCutValue(cutForElectron, "e-");
  SetCutValue(cutForElectron, "e+");
  SetCutValue(cutForProton,   "proton");
}
</programlisting>
</example>
</para>

<para>
Beginning with Geant4 version 5.1, it is now possible to set
production thresholds for each geometrical region. This new
functionality is described in <xref linkend="sect.CutReg" />.
</para>


</sect3>
</sect2>
</sect1>