source: trunk/documents/UserDoc/DocBookUsersGuides/ForToolkitDeveloper/xml/GuideToExtendFunctionality/Particles/particles.xml @ 904

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

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

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.ExtdFuncParticles.Properties">
<title>
Properties of particles
</title>

<para>
The <emphasis>G4ParticleDefinition</emphasis> class has 
properties to characterize individual particles, 
such as name, mass, charge, spin, and so on. 
Properties of particles are set during initialization of each particle. 
Default values of particle properties are described in each particles class.
In addition, properties of heavy nuclei can be given by external files.
Basicaly, these properties can not be changed after initialization phase except for 
ones related its decay; life time, branching ratio of each decay mode and
 the ``stable'' flag. However, Geant4 proivides a method to override these properties 
by using external files.
</para>


<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Properties of nuclei
</bridgehead>

<para>
Individual classes are provided for light nuclei (i.e. deuteron, triton, He3, and He4) 
with default values of their properties. 
Other nuclei are dynamically created by requests from processes (and users). 
<emphasis>G4IonTable</emphasis> class handles creation of such ions. 
Default properties of nuclei are determined with help of <emphasis>G4NuclearProperties</emphasis>. 
</para>
<para>
Users can register a <emphasis>G4IsotopeTable</emphasis> to the
<emphasis>G4IonTable</emphasis>. <emphasis>G4IsotopeTable</emphasis>
describes properties of ions which are used to create ions.
You can get exited energy, decay modes, and life time for relatively long life nuclei 
by using <emphasis>G4RIsotopeTable</emphasis> and data files
(G4RADIOACTIVEDATA should be set to the directory where data files exist).
<emphasis>G4IsotopeMagneticMomentTable</emphasis> provides a table of 
magnetic moment of nuclei with the data file of 
<emphasis>G4IsotopeMagneticMoment.table</emphasis> (The file name should be set to G4IONMAGNETICMOMENT )
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Changing particle properties
</bridgehead>

<para>
Only in ``PreInit'' phase, properties can be modified with help of
 <emphasis> G4ParticlePropertyTable</emphasis> class. 
Particle properties can be overridden with the method
<informalexample><programlisting>
G4bool SetParticleProperty(const G4ParticlePropertyData& newProperty)
</programlisting></informalexample>
by setting new values in <emphasis> G4ParticlePropertyData </emphasis>.
In addition, the current values of particles properties can be extracted 
into text files by using  <emphasis> G4TextPPReporter </emphasis>. 
On the other hand, <emphasis> G4TextPPRetriever </emphasis> can change particle 
properties according to text files.
</para>

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.ExtdFuncParticles.AddNewPar">
<title>
Adding New Particles
</title>

<para>
You can add a new particle by creating a new class for it. 
The new class should be derived from <emphasis>G4ParticleDefinition</emphasis>.
You can find an example under examples/extended/exoticphysics/monopole.
A new class for the monople is defined as follows;
<informalexample><programlisting>
class G4Monopole : public G4ParticleDefinition
{
private:
  static G4Monopole*  theMonopole;

  G4Monopole(
       const G4String&     aName,        G4double            mass,
       G4double            width,        G4double            charge,   
       G4int               iSpin,        G4int               iParity,    
       G4int               iConjugation, G4int               iIsospin,   
       G4int               iIsospin3,    G4int               gParity,
       const G4String&     pType,        G4int               lepton,      
       G4int               baryon,       G4int               encoding,
       G4bool              stable,       G4double            lifetime,
       G4DecayTable        *decaytable );

public: 
   virtual ~G4Monopole();
   static G4Monopole* MonopoleDefinition();
   static G4Monopole* Monopole();
}
</programlisting></informalexample>
Static methods above need to be defined and implemented so that 
this new particle instance will be created 
in ConstructParticls method of your physics list.
You can add new properties if necessary (G4Monopole has a property for magnetic charge)
Values of properties need to be given in the static method as other particle classes.
<informalexample><programlisting>
G4Monopole* G4Monopole::MonopoleDefinition(G4double mass, G4int mCharge, G4int eCharge)
{    
  if(!theMonopole) {
    theMonopole = new G4Monopole(
              "monopole",         mass,       0.0*MeV,           0, 
                    0,               0,             0,          
                    0,               0,             0,             
              "boson",               0,             0,           0,
                 true,            -1.0,             0);
  }
  return theMonopole;
}
</programlisting></informalexample>
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead role="revisionHistory" renderas="sect4">
[Status of this chapter]
</bridgehead>
<para>
<simplelist type="var">
  <member>
    Nov. 2008 cretad by H. Kurashige
  </member>
</simplelist>
</para>

</sect2>
</sect1>