source: trunk/documents/UserDoc/DocBookUsersGuides/ForApplicationDeveloper/xml/UserActions/mandatoryActions.xml

<!-- ******************************************************** -->
<!--                                                          -->
<!--  [History]                                               -->
<!--    Changed by: Katsuya Amako,  9-Jul-1998                -->
<!--    Changed by: Katsuya Amako,  4-Aug-1998                -->
<!--    Changed by: John Allison,   4-Aug-1998                -->
<!--    Changed by: Katsuya Amako, 30-Nov-1998                -->
<!--    Changed by: Dennis Wright, 29-Nov-2001                -->
<!--    Changed by: Makoto Asai,   22-Apr-2003                -->
<!--    Proof read by: Joe Chuma,   2-Jul-1999                -->
<!--    Converted to DocBook: Katsuya Amako, Aug-2006         -->
<!--                                                          -->
<!-- ******************************************************** -->


<!-- ******************* Section (Level#1) ****************** -->
<sect1 id="sect.ManUAct">
<title>
Mandatory User Actions and Initializations
</title>

<para>
Geant4 has three virtual classes whose methods the user must
override in order to implement a simulation. They require the user
to define the detector, specify the physics to be used, and
describe how initial particles are to be generated.
</para>

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

<para>
<example id="programlist_ManUAct_1">
<title>
<literal>G4VUserDetectorConstruction</literal>
</title>

<programlisting>
     class G4VUserDetectorConstruction
     {
       public:
         G4VUserDetectorConstruction();
         virtual ~G4VUserDetectorConstruction();

       public:
         virtual G4VPhysicalVolume* Construct() = 0;
     };
</programlisting>
</example>
</para>


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

<para>
This is an abstract class for constructing particles and
processes. The user must derive a concrete class from it and
implement three virtual methods:

<itemizedlist spacing="compact">
  <listitem><para>
    <literal>ConstructParticle()</literal> to instantiate each requested
    particle type,
  </para></listitem>
  <listitem><para>
    <literal>ConstructPhysics()</literal> to instantiate the desired physics
    processes and register each of them with the process managers of
    the appropriate particles, and
  </para></listitem>
  <listitem><para>
    <literal>SetCuts(G4double aValue)</literal> to set a cut value in range
    for all particles in the particle table, which invokes the
    rebuilding of the physics table.
  </para></listitem>
</itemizedlist>
</para>

<para>
When called, the <literal>Construct()</literal> method of
<emphasis>G4VUserPhysicsList</emphasis> first invokes
<literal>ConstructParticle()</literal> and then <literal>ConstructProcess()</literal>.
The <literal>ConstructProcess()</literal> method must always invoke the
<literal>AddTransportation()</literal> method in order to insure particle
transportation. <literal>AddTransportation()</literal> must never be
overridden.
</para>

<para>
<emphasis>G4VUserPhysicsList</emphasis> provides several utility methods for
the implementation of the above virtual methods. They are presented
with comments in the class declaration in <xref linkend="programlist_ManUAct_2"
/>.

<example id="programlist_ManUAct_2">
<title>
<literal>G4VUserPhysicsList</literal>
</title>

<programlisting>
class G4VUserPhysicsList
{
  public:
    G4VUserPhysicsList();
    virtual ~G4VUserPhysicsList();

  public:  // with description
    // By calling the "Construct" method,
    // particles and processes are created
    void Construct();

  protected: // with description
   // These two methods of  ConstructParticle() and ConstructProcess()
   // will be invoked in the Construct() method.

   // each particle type will be instantiated
   virtual void ConstructParticle() = 0;

   // each physics process will be instantiated and
   // registered to the process manager of each particle type
   virtual void ConstructProcess() = 0;

  protected: // with description
   //  User must invoke this method in his ConstructProcess()
   //  implementation in order to insures particle transportation.
   //  !! Caution: this class must not be overriden !!
   void AddTransportation();

  /////////////////////////////////////////////////////////////////
  public: // with description
   //  "SetCuts" method sets a cut value for all particle types
   //   in the particle table
   virtual void SetCuts() = 0;

  public:  // with description
   //  set/get the default cut value
   //  Calling SetDefaultCutValue causes re-calcuration of cut values
   //  and physics tables just before the next event loop
   void     SetDefaultCutValue(G4double newCutValue);
   G4double GetDefaultCutValue() const;
</programlisting>
</example>
<informalexample>
<programlisting>
  /////////////////////////////////////////////////////////////////////
  public: // with description
    // Invoke BuildPhysicsTable for all processes for all particles
    // In case of "Retrieve" flag is ON, PhysicsTable will be
    // retrieved from files
    void BuildPhysicsTable();

   // do BuildPhysicsTable for specified particle type
    void BuildPhysicsTable(G4ParticleDefinition* );

     // Store PhysicsTable together with both material and cut value
    // information in files under the specified directory.
    //  (return true if files are sucessfully created)
    G4bool  StorePhysicsTable(const G4String&amp; directory = ".");

    // Return true if "Retrieve" flag is ON.
    // (i.e. PhysicsTable will be retrieved from files)
    G4bool  IsPhysicsTableRetrieved() const;
    G4bool  IsStoredInAscii() const;

    // Get directory path for physics table files.
    const G4String&amp; GetPhysicsTableDirectory() const;

    // Set "Retrieve" flag
    // Directory path can be set together.
    // Null string (default) means directory is not changed
    // from the current value
    void    SetPhysicsTableRetrieved(const G4String&amp; directory = "");
    void    SetStoredInAscii();

    // Reset "Retrieve" flag
    void    ResetPhysicsTableRetrieved();
    void    ResetStoredInAscii();

 ///////////////////////////////////////////////////////////////////////
  public: // with description
    // Print out the List of registered particles types
    void DumpList() const;

  public: // with description
    // Request to print out information of cut values
    // Printing will be performed when all tables are made
    void DumpCutValuesTable(G4int nParticles=3);

    // The following method actually trigger the print-out requested
    // by the above method. This method must be invoked by RunManager
    // at the proper moment.
    void DumpCutValuesTableIfRequested();

  public: // with description
    void  SetVerboseLevel(G4int value);
    G4int GetVerboseLevel() const;
    // set/get controle flag for output message
    //  0: Silent
    //  1: Warning message
    //  2: More
</programlisting>
</informalexample>
<informalexample>
<programlisting>
  ///////////////////////////////////////////////////////////////////////////
  public: // with description
   //  "SetCutsWithDefault" method sets the default cut value
   //   for all particles for the default region.
   void SetCutsWithDefault();

   // Following are utility methods for SetCuts

   // SetCutValue sets a cut value for a particle type for the default region
   void SetCutValue(G4double aCut, const G4String&amp; pname);

   // SetCutValue sets a cut value for a particle type for a region
   void SetCutValue(G4double aCut, const G4String&amp; pname, const G4String&amp; rname);

   // Invoke SetCuts for specified particle for a region
   // If the pointer to the region is NULL, the default region is used
   // In case of "Retrieve" flag is ON,
   // Cut values will be retrieved from files
   void SetParticleCuts(G4double cut,G4ParticleDefinition* particle,G4Region* region=0);

   // Invoke SetCuts for all particles in a region
   void SetCutsForRegion(G4double aCut, const G4String&amp; rname);

   // Following are utility methods are obsolete
   void ResetCuts();

///////////////////////////////////////////////////////////////////
  public:
   // Get/SetApplyCuts gets/sets the flag for ApplyCuts
   void SetApplyCuts(G4bool value, const G4String&amp; name);
   G4bool GetApplyCuts(const G4String&amp; name) const;

///////////////////////////////////////////////////////////////////////////////
  protected:
    // do BuildPhysicsTable for make the integral schema
    void BuildIntegralPhysicsTable(G4VProcess* ,G4ParticleDefinition*  );


  protected:
    // Retrieve PhysicsTable from files for proccess belongng the particle.
    // Normal BuildPhysics procedure of processes will be invoked,
    // if it fails (in case of Process's RetrievePhysicsTable returns false)
    virtual void  RetrievePhysicsTable(G4ParticleDefinition* ,
                                       const G4String&amp; directory,
                                       G4bool          ascii = false);

   /////////////////////////////////////////////////////////////////
  protected:
    // adds new ProcessManager to all particles in the Particle Table
    //   this routine is used in Construct()
    void InitializeProcessManager();

  public: // with description
    // remove and delete ProcessManagers for all particles in tha Particle Table
    //    this routine is invoked from RunManager
    void RemoveProcessManager();

  public: // with description
    // add process manager for particles created on-the-fly
    void AddProcessManager(G4ParticleDefinition* newParticle,
                           G4ProcessManager*    newManager = 0 );

};
</programlisting>
</informalexample>
</para>


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

<para>
<example id="programlist_ManUAct_3">
<title>
<literal>G4VUserPrimaryGeneratorAction</literal>
</title>

<programlisting>
     class G4VUserPrimaryGeneratorAction
     {
       public:
         G4VUserPrimaryGeneratorAction();
         virtual ~G4VUserPrimaryGeneratorAction();
     
       public:
         virtual void GeneratePrimaries(G4Event* anEvent) = 0;
     };
</programlisting>
</example>
</para>


</sect1>