source: trunk/documents/UserDoc/DocBookUsersGuides/ForApplicationDeveloper/xml/GettingStarted/eventDef.xml

<!-- ******************************************************** -->
<!--                                                          -->
<!--  [History]                                               -->
<!--    Changed by: Katsuya Amako,  4-Aug-1998                -->
<!--    Changed by: Dennis Wright, 29-Nov-2001                -->
<!--    Proof read by: Joe Chuma,  15-Jun-1999                -->
<!--    Converted to DocBook: Katsuya Amako, Aug-2006         -->
<!--    Added GPS description: Katsuya Amako, Dec-2009        -->
<!--                                                          -->
<!-- ******************************************************** -->


<!-- ******************* Section (Level#1) ****************** -->
<sect1 id="sect.HowToGenEvent">
<title>
How to Generate a Primary Event
</title>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.HowToGenEvent.GenPrimary">
<title>
Generating Primary Events
</title>

<para>
<emphasis>G4VuserPrimaryGeneratorAction</emphasis> is one of the mandatory
classes available for deriving your own concrete class. In your
concrete class, you have to specify how a primary event should be
generated. Actual generation of primary particles will be done by
concrete classes of <emphasis>G4VPrimaryGenerator</emphasis>, explained in the
following sub-section. Your <emphasis>G4VUserPrimaryGeneratorAction</emphasis>
concrete class just arranges the way primary particles are generated.

<example id="programlist_HowToGenEvent_1">
<title>
An example of a <emphasis>G4VUserPrimaryGeneratorAction</emphasis> 
concrete class using <emphasis>G4ParticleGun</emphasis>. 
For the usage of <emphasis>G4ParticleGun</emphasis> refer to the
next subsection.
</title>

<programlisting>
#ifndef ExN01PrimaryGeneratorAction_h
#define ExN01PrimaryGeneratorAction_h 1

#include "G4VUserPrimaryGeneratorAction.hh"

class G4ParticleGun;
class G4Event;

class ExN01PrimaryGeneratorAction : public G4VUserPrimaryGeneratorAction
{
  public:
    ExN01PrimaryGeneratorAction();
    ~ExN01PrimaryGeneratorAction();

  public:
    void generatePrimaries(G4Event* anEvent);

  private:
    G4ParticleGun* particleGun;
};

#endif

#include "ExN01PrimaryGeneratorAction.hh"
#include "G4Event.hh"
#include "G4ParticleGun.hh"
#include "G4ThreeVector.hh"
#include "G4Geantino.hh"
#include "globals.hh"

ExN01PrimaryGeneratorAction::ExN01PrimaryGeneratorAction()
{
  G4int n_particle = 1;
  particleGun = new G4ParticleGun(n_particle);

  particleGun-&gt;SetParticleDefinition(G4Geantino::GeantinoDefinition());
  particleGun-&gt;SetParticleEnergy(1.0*GeV);
  particleGun-&gt;SetParticlePosition(G4ThreeVector(-2.0*m,0.0*m,0.0*m));
}

ExN01PrimaryGeneratorAction::~ExN01PrimaryGeneratorAction()
{
  delete particleGun;
}

void ExN01PrimaryGeneratorAction::generatePrimaries(G4Event* anEvent)
{
  G4int i = anEvent-&gt;get_eventID() % 3;
  switch(i)
  {
    case 0:
      particleGun-&gt;SetParticleMomentumDirection(G4ThreeVector(1.0,0.0,0.0));
      break;
    case 1:
      particleGun-&gt;SetParticleMomentumDirection(G4ThreeVector(1.0,0.1,0.0));
      break;
    case 2:
      particleGun-&gt;SetParticleMomentumDirection(G4ThreeVector(1.0,0.0,0.1));
      break;
  }

  particleGun-&gt;generatePrimaryVertex(anEvent);
}
</programlisting>
</example>

</para>


<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.HowToGenEvent.GenPrimary.SelectGenerator">
<title>
Selection of the generator
</title>

<para>
In the constructor of your <emphasis>G4VUserPrimaryGeneratorAction</emphasis>,
you should instantiate the primary generator(s). If necessary, you
need to set some initial conditions for the generator(s).
</para>

<para>
In <xref linkend="programlist_HowToGenEvent_1" />, 
<emphasis>G4ParticleGun</emphasis> is constructed to
use as the actual primary particle generator. Methods of
<emphasis>G4ParticleGun</emphasis> are described in the following section. Please
note that the primary generator object(s) you construct in your
<emphasis>G4VUserPrimaryGeneratorAction</emphasis> concrete class must be deleted
in your destructor.
</para>

</sect3>

<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.HowToGenEvent.GenPrimary.GenEvent">
<title>
Generation of an event
</title>

<para>
<emphasis>G4VUserPrimaryGeneratorAction</emphasis> has a pure virtual method
named <literal>generatePrimaries()</literal>. This method is invoked at the
beginning of each event. In this method, you have to invoke the
<emphasis>G4VPrimaryGenerator</emphasis> concrete class you instantiated via the
<literal>generatePrimaryVertex()</literal> method.
</para>

<para>
You can invoke more than one generator and/or invoke one
generator more than once. Mixing up several generators can produce
a more complicated primary event.
</para>

</sect3>
</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.HowToGenEvent.G4VPrimGen">
<title>
G4VPrimaryGenerator
</title>

<para>
Geant4 provides three <emphasis>G4VPrimaryGenerator</emphasis> concrete 
classes. Among these <emphasis>G4ParticleGun</emphasis> and 
<emphasis> G4GeneralParticleSource</emphasis> will be discussed here.
The third one is <emphasis>G4HEPEvtInterface</emphasis>, which will be 
discussed in <xref linkend="sect.EventGen" />.
</para>


<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.HowToGenEvent.G4VPrimGen.G4PartGun">
<title>
G4ParticleGun
</title>

<para>
<emphasis>G4ParticleGun</emphasis> is a generator provided by Geant4. This class
generates primary particle(s) with a given momentum and position.
It does not provide any sort of randomizing. The constructor of
<emphasis>G4ParticleGun</emphasis> takes an integer which causes the generation
of one or more primaries of exactly same kinematics. It is a rather
frequent user requirement to generate a primary with randomized
energy, momentum, and/or position. Such randomization can be
achieved by invoking various set methods provided by
<emphasis>G4ParticleGun</emphasis>. The invocation of these methods should be
implemented in the <literal>generatePrimaries()</literal> method of your
concrete <emphasis>G4VUserPrimaryGeneratorAction</emphasis> class before invoking
<literal>generatePrimaryVertex()</literal> of
<emphasis>G4ParticleGun</emphasis>. 
Geant4 provides various random number generation methods with various
distributions (see <xref linkend="sect.GlobClass" />).
</para>

</sect3>

<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.HowToGenEvent.G4VPrimGen.PublicMethG4PartGun">
<title>
Public methods of <emphasis>G4ParticleGun</emphasis>
</title>

<para>
The following methods are provided by <emphasis>G4ParticleGun</emphasis>, and all
of them can be invoked from the <literal>generatePrimaries()</literal> method
in your concrete <emphasis>G4VUserPrimaryGeneratorAction</emphasis> class.

<itemizedlist spacing="compact">
  <listitem><para>
  <literal>void SetParticleDefinition(G4ParticleDefinition*)</literal>
  </para></listitem>
  <listitem><para>
  <literal>void SetParticleMomentum(G4ParticleMomentum)</literal>
  </para></listitem>
  <listitem><para>
  <literal>void SetParticleMomentumDirection(G4ThreeVector)</literal>
  </para></listitem>
  <listitem><para>
  <literal>void SetParticleEnergy(G4double)</literal>
  </para></listitem>
  <listitem><para>
  <literal>void SetParticleTime(G4double)</literal>
  </para></listitem>
  <listitem><para>
  <literal>void SetParticlePosition(G4ThreeVector)</literal>
  </para></listitem>
  <listitem><para>
  <literal>void SetParticlePolarization(G4ThreeVector)</literal>
  </para></listitem>
  <listitem><para>
  <literal>void SetNumberOfParticles(G4int)</literal>
  </para></listitem>
</itemizedlist>
</para>
</sect3>

<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.HowToGenEvent.G4VPrimGen.G4GPS">
<title>
G4GeneralParticleSource
</title>

<para>
For many applications <literal>G4ParticleGun</literal> is a suitable
particle generator. Howevr if you want to generate primary particles
in more sophisticated manner, you can utilize 
<literal>G4GeneralParticleSource</literal> - Geant4 General Particle 
Source module (GPS).
</para>

<para>
Using this tool, you can control the following characteristics of 
primary particles:


<itemizedlist spacing="compact">
   <listitem><para>
     Spectrum: linear, exponential, power-law, Gaussian, blackbody, or 
     piece-wise fits to data.
   </para></listitem>
   <listitem><para>
     Angular distribution: unidirectional, isotropic, cosine-law, 
     beam or arbitrary (user defined).
   </para></listitem>
   <listitem><para>
     Spatial sampling: on simple 2D or 3D surfaces such as discs, spheres, 
     and boxes.
   </para></listitem>
   <listitem><para>
     Multiple sources: multiple independent sources can be used in the same run.
   </para></listitem>
</itemizedlist>
</para>

<para>
Details of information on the General Source Particle Module can be 
found in the documents 
<ulink url="http://reat.space.qinetiq.com/gps/">
Geant4 General Particle Source</ulink>.
</para>

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