Introduction to GEANT4

== <span style="color:#000080"> Introduction </span> ==


GEANT4 is a software toolkit based on C++. In your code you have to define: 

* Your experimental setup - geometry, materials and primary particles.
* Which physics process you are interested in. 
* You may take actions during the simulation - inspect and store results. 

The interaction with GEANT4 is done via base classes.    

; Mandatory classes:   

* <span style="color:#ff0000"> G4VUserDetectorConstruction </span>: Describe the experimental setup, geometry and materials;
* <span style="color:#ff0000"> G4VUserPhysicsList </span>: Define particles, physics processes and range cuts;
* <span style="color:#ff0000"> G4VUserPrimaryGeneratorAction </span>: Describe particle source, source dimensions, initial position, energy spectrum, angular distributions;

; Optional classes: 

* <span style="color:#ff0000"> G4UserRunAction </span>: Define and store histograms; 
* <span style="color:#ff0000"> G4UserEventAction </span>: Event selection and analysis of simulation data;
* <span style="color:#ff0000"> G4UserStackingAction </span>: Customize priority of tracks;
* <span style="color:#ff0000"> G4UserTrackingAction </span>: Decide whether a trajectory should be stored or not;
* <span style="color:#ff0000"> G4UserSteppingAction </span>: Kill, suspend, postpone a track;

; Manager class 

* <span style="color:#ff0000"> G4RunManager </span>: Manages the simulation process;

  
== <span style="color:#000080"> The function main() </span> ==


The function <span style="color:#ff0000"> main() </span> defines the skeleton of your simulation code. Inside the function you instantiate <span style="color:#ff0000"> G4RunManager </span> and notify it of your mandatory and optional classes. This is example <span style="color:#ff0000"> main() </span> function, where <span style="color:#ff0000"> MyDetectorConstruction </span>, <span style="color:#ff0000"> MyPhysicsList </span>, <span style="color:#ff0000"> MyPrimaryGeneratorAction </span>, <span style="color:#ff0000"> MyEventAction </span> and <span style="color:#ff0000"> MyRunAction </span> are derived classes from the GEANT4 base classes:


<span style="color:#800000"> int main() { </span>
  
<span style="color:#800000"> // Run manager construction </span> 

<span style="color:#800000"> G4RunManager* runManager = new G4RunManager; </span> 


<span style="color:#800000"> // mandatory user initialization classes </span> 

<span style="color:#800000"> runManager->SetUserInitialization(new MyDetectorConstruction); </span> 

<span style="color:#800000"> runManager->SetUserInitialization(new MyPhysicsList); </span> 


<span style="color:#800000"> // mandatory user action classes  </span> 

<span style="color:#800000"> runManager->SetUserAction(new MyPrimaryGeneratorAction); </span> 


<span style="color:#800000"> // optional user action classes </span>  

<span style="color:#800000"> runManager->SetUserAction(new MyEventAction); </span> 

<span style="color:#800000"> runManager->SetUserAction(new MyRunAction); ... } </span> 

 
== <span style="color:#000080"> Experimental setup </span> ==


You derive your own class from <span style="color:#ff0000"> G4VUserDetectorConstruction </span> base class. In the derived class you will: 

* Describe the shape and the size of your detector using <span style="color:#ff0000"> G4VSolid </span> 
* Construct materials and electromagnetic fields using <span style="color:#ff0000"> G4Logical Volume </span> 
* Place volumes of your detector geometry using <span style="color:#ff0000"> G4VPhysical Volume </span> 


<u> Simple example of <span style="color:#ff0000"> MyDetectorConstruction </span> </u>: 


<span style="color:#800000"> class MyDetectorConstruction:public G4VUserDetectorConstruction { </span>

<span style="color:#800000"> public: </span> 
    
<span style="color:#800000"> MyDetectorConstruction(); </span>

<span style="color:#800000"> ~MyDetectorConstruction(); </span>
    
<span style="color:#800000"> virtual G4VPhysicalVolume* Construct(); </span>

     
<span style="color:#800000"> private: </span>
   
<span style="color:#800000"> void  DefineMaterials(); }; </span>   


Now construct the detector. Your detector is always placed in a mother volume called the world volume.  


<span style="color:#800000"> G4PhysicalVolume* MyDetectorConstruction::Construct() { </span> 

<span style="color:#800000"> ... </span> 

<span style="color:#800000"> // World volume </span>

<span style="color:#800000"> G4VSolid* pWorld = new G4Box("World",5*m,5*m,5*m); </span>
                                         
<span style="color:#800000"> G4LogicalVolume* pWorldLog = new G4LogicalVolume(pWorld,vacuum, "World"); </span>   
                                                                           
<span style="color:#800000"> G4VPhysicalVolume* pWorldPhys = new G4PVPlacement(0,G4ThreeVector(),pWorldLog,"World",0,false,0); </span> 


<span style="color:#800000"> // Water box </span>

<span style="color:#800000"> G4VSolid* pBoxSolid = new G4Box(“WaterBox”, 1.*m, 2.*m, 3.*m); </span> 

<span style="color:#800000"> G4LogicalVolume* pBoxLog = new G4LogicalVolume( pBoxSolid, water, “WaterBox”); </span> 

<span style="color:#800000"> G4VPhysicalVolume* aBoxPhys = new G4PVPlacement( pRotation, G4ThreeVector(posX, posY, posZ), pBoxLog, “WaterBox”, pWorldLog, false, copyNo); ... } </span> 


The elements and materials are defined using classes <span style="color:#ff0000"> G4Element </span> and <span style="color:#ff0000"> G4Material </span>. For example water, hydrogen and oxygen are defined as:


<span style="color:#800000"> void MyDetectorConstruction::DefineMaterials() { </span>

<span style="color:#800000"> ... </span>

<span style="color:#800000"> G4Element* H = new G4Element("Hydrogen","H",z=1.,a= 1.01*g/mole); </span>
 
<span style="color:#800000"> G4Element* O = new G4Element("Oxygen","O",z=8.,a=16.00*g/mole); </span> 


<span style="color:#800000"> density = 1.000*g/cm3; </span> 

<span style="color:#800000"> G4Material* water = new G4Material("Water",density,ncomp=2); </span> 

<span style="color:#800000"> water->AddElement(H, natoms=2); </span> 

<span style="color:#800000"> water->AddElement(O, natoms=1); ...} </span> 


[http://geant4.web.cern.ch/geant4/UserDocumentation/Doxygen/examples_doc/html/group__extended__common__detectorConstruction.html Here] you can find more examples of DetectorConstruction classes.


== <span style="color:#000080"> Physics processes </span> == 


You can build your own physics list or chose from already built physics lists. To build your own physics lists, you can use two base physics list classes: <span style="color:#ff0000"> G4VUserPhysicsList </span> and <span style="color:#ff0000"> G4ModularPhysicsList </span>. The class <span style="color:#ff0000"> G4VUserPhysicsList </span> is used for simple physics lists while <span style="color:#ff0000"> G4ModularPhysicsList </span> is used to build more complex physics lists. There exist also already built pre-packaged physics lists.


=== <span style="color:#000080"> Simple physics lists </span> ===  


If the particles in your simulation undergo a descrete number of physics processes you can use the class <span style="color:#ff0000"> G4VUserPhysicsList </span> to define them. This class has three methods:

* ConstructParticles() : Define all necessary particles;  
* ConstructProcesses() : Define all necessary processes and assign them to proper particles;
* SetCuts() : Define production thresholds in terms of range; 


<u> Simple example of <span style="color:#ff0000"> MyPhysicsList </span> </u>: 


<span style="color:#800000"> class MyPhysicsList:public G4VUserPhysicsList() { </span>

<span style="color:#800000"> public: </span>

<span style="color:#800000"> MyPhysicsList(); </span>

<span style="color:#800000"> ~MyPhysicsList(); </span>

<span style="color:#800000"> void ConstructParticle(); </span>

<span style="color:#800000"> void ConstructProcess(); </span>

<span style="color:#800000"> void SetCuts(); } </span>
 

Now implement the methods ConstructParticle(), ConstructProcess() and SetCuts():

 
<span style="color:#800000"> void MyPhysicsList::ConstructParticle() { </span>

<span style="color:#800000"> // Define the particles </span>

<span style="color:#800000"> G4Electron::ElectronDefinition(); </span>

<span style="color:#800000"> G4Positron::PositronDefinition(); </span>

<span style="color:#800000"> G4Proton::ProtonDefinition(); </span>

<span style="color:#800000"> G4Neutron::NeutronDefinition(); </span>

<span style="color:#800000"> G4Gamma::GammaDefinition(); ... } </span>


GEANT4 provides a variety of physics processes. These processes are decoupled from one another and you can select those which are relevant to your simulation. The processes are grouped in seven categories and their list is available [http://geant4.cern.ch/support/proc_mod_catalog/processes/ here]:

<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* electromagnetic 
* hadronic
* decay
* photolepton-hadron
* optical
* parameterization
* transportation 
</div>


For each particle defined in ConstructParticle() assign all the physics processes that you want to
consider in your simulation: 
  

<span style="color:#800000"> void MyPhysicsList::ConstructProcess() { </span>

<span style="color:#800000"> AddTransportation(); // Assign transportation process to all particles </span>

<span style="color:#800000"> ConstructEM(); // Electromagnetic processes </span>

<span style="color:#800000"> ConstructGeneral(); // Other processes } </span>


In methods ConstructEM() and ConstructGeneral() assign the physics processes to the corresponding particles: 


<span style="color:#800000"> void MyPhysicsList::ConstructEM() { </span>

<span style="color:#800000"> aParticleIterator->reset(); </span>

<span style="color:#800000"> while((*aParticleIterator)()){ </span>

<span style="color:#800000"> G4ParticleDefinition* particle = aParticleIterator->value(); </span>
 
<span style="color:#800000"> G4ProcessManager* pmanager = particle->GetProcessManager(); </span>

<span style="color:#800000"> G4String particleName = particle->GetParticleName(); </span>
     
<span style="color:#800000"> if (particleName == "gamma") { </span>
     
<span style="color:#800000"> pmanager->AddDiscreteProcess(new G4GammaConversion); ...} </span> 
    

<span style="color:#800000"> void MyPhysicsList::ConstructGeneral() { </span>

<span style="color:#800000"> G4Decay* theDecayProcess = new G4Decay() </span>

<span style="color:#800000"> aParticleIterator->reset(); </span>

<span style="color:#800000"> while((*aParticleIterator)()) { </span>

<span style="color:#800000"> G4ParticleDefinition* particle = aParticleIterator->value(); </span>
 
<span style="color:#800000"> G4ProcessManager* pmanager = particle->GetProcessManager(); </span>

<span style="color:#800000"> if theDecayProcess->IsApplicable(*particle)) { </span>
     
<span style="color:#800000"> pmanager->AddProcess(theDecayProcess); </span>
     
<span style="color:#800000"> pmanager->SetProcessOrdering(theDecayProcess,idxPostStep); </span> 
    
<span style="color:#800000"> pmanager->SetProcessOrdering(theDecayProcess,idxAtRest); }}} </span>


This is the full [http://geant4.cern.ch/support/proc_mod_catalog/particles/ list] of physics processes every  particle can participate in. Finally, method SetCuts() is defined as:


<span style="color:#800000"> void MyPhysicsList::SetCuts() { </span>

<span style="color:#800000"> defaultCutValue = 1.0*mm; </span>

<span style="color:#800000"> SetCutValue(defaultCutValue, "gamma"); </span>

<span style="color:#800000"> SetCutValue(defaultCutValue, "e+"); </span>

<span style="color:#800000"> SetCutValue(defaultCutValue, "e-"); </span>


=== <span style="color:#000080"> Detailed physics lists </span> === 


If you want to build more realistic physics list you have to use the class <span style="color:#ff0000"> G4VModularPhysicsList </span>. For example, the photon from the example above can undergo compton scattering apart from conversion. In <span style="color:#ff0000"> G4VModularPhysicsList </span> you can group the physics processes into separate modules: EM physics, hadronic physics, decay physics etc. 


<u> Simple example of <span style="color:#ff0000"> MyPhysicsList </span> </u>:


<span style="color:#800000"> class MyPhysicsList:public G4VModularPhysicsList { </span>

<span style="color:#800000"> public: </span>

<span style="color:#800000"> MyPhysicsList(); </span>

<span style="color:#800000"> ~MyPhysicsList(); </span>

<span style="color:#800000"> virtual void ConstructParticle(); </span>
    
<span style="color:#800000"> virtual void SetCuts(); </span>
        
<span style="color:#800000"> void AddPhysicsList(const G4String& name); </span>

<span style="color:#800000"> virtual void ConstructProcess(); </span>

      
<span style="color:#800000"> private: </span>
    
<span style="color:#800000"> G4String                             fEmName; </span>

<span style="color:#800000"> G4VPhysicsConstructor*               fEmPhysicsList; </span>

<span style="color:#800000"> G4VPhysicsConstructor*               fDecPhysicsList; </span>

<span style="color:#800000"> std::vector<G4VPhysicsConstructor*>  fHadronPhysicsList; }; </span>


Now we can build the physics lists:


<span style="color:#800000"> void MyPhysicsList::AddPhysicsList(const G4String& name) { </span>

<span style="color:#800000"> ... </span>

<span style="color:#800000"> if (name == "emstandard_opt3") { </span>
    
<span style="color:#800000"> fEmName = name; </span>  
    
<span style="color:#800000"> delete fEmPhysicsList; </span>
    
<span style="color:#800000"> fEmPhysicsList = new G4EmStandardPhysics_option3(); </span>  


<span style="color:#800000"> } else if (name == "emlivermore") { </span>
   
<span style="color:#800000"> fEmName = name; </span>
    
<span style="color:#800000"> delete fEmPhysicsList; </span>
    
<span style="color:#800000"> fEmPhysicsList = new G4EmLivermorePhysics(); </span>


<span style="color:#800000"> } else if (name == "empenelope") { </span>
    
<span style="color:#800000"> fEmName = name; </span>
    
<span style="color:#800000"> delete fEmPhysicsList; </span>
    
<span style="color:#800000"> fEmPhysicsList = new G4EmPenelopePhysics(); </span>


<span style="color:#800000"> } else if (name == "HElastic") { </span>
    
<span style="color:#800000"> fHadronPhysicsList.push_back( new G4HadronHElasticPhysics()); </span>


<span style="color:#800000"> } else if (name == "HInelastic") { </span>
   
<span style="color:#800000"> fHadronPhysicsList.push_back(new G4HadronInelasticQBBC()); </span>
    
<span style="color:#800000"> } ... } </span>


and 


<span style="color:#800000"> void MyPhysicsList::ConstructProcess() { </span>
 
<span style="color:#800000"> AddTransportation(); // transportation </span>
  
<span style="color:#800000"> fEmPhysicsList->ConstructProcess(); // electromagnetic physics list </span>

<span style="color:#800000"> fDecPhysicsList->ConstructProcess(); // decay physics list </span>
  
<span style="color:#800000"> for(size_t i=0; i<fHadronPhys.size(); i++) { // hadronic physics lists </span>
  
<span style="color:#800000"> fHadronPhys[i]->ConstructProcess(); } } </span>
  

=== <span style="color:#000080"> Pre-packaged physics lists </span> ===


Some built-in pre-packaged physics lists are available [http://geant4.web.cern.ch/geant4/support/proc_mod_catalog/physics_lists/referencePL.shtml here]. You can use them as a starting point of your simulation.    


<u> Simple example of <span style="color:#ff0000"> pre-packaged physics list </span> </u>:


In function <span style="color:#ff0000"> main() </span>: 


<span style="color:#800000"> G4PhysListFactory factory* physListFactory = new G4PhysListFactory(); </span>

<span style="color:#800000"> G4VUserPhysicsList* physicsList = physListFactory->GetReferencePhysList(“FTFP_BERT”); </span>

<span style="color:#800000"> runManager->SetUserInitialization(physicsList); </span>


Most of the pre-packaged physics lists use "standard" electromagnetic physics processes. The "standard" EM processes are defined with classes: G4EmStandardPhysics, G4EmStandardPhysics_option1, G4EmStandardPhysics_option2 and G4EmStandardPhysics_option3. If you want to use "low energy" electromagnetic physics processes (defined with classes G4EmLivermorePhysics, G4EmLivermorePolarizedPhysics, G4EmPenelopePhysics and G4EmDNAPhysics) in the pre-packaged physics list you have to define them in your physics list class (see example ProtonPencilBeam). 


For example, if you want to simulate clinical proton beam of energy 150 MeV you can use pre-packaged physics list e.g. QGSP_BIC, QGSP_BERT and FTFP_BERT. If you are interested in Bragg curve physics, use a physics list ending in "EMV" or "EMX" e.g. QGSP_BERT_EMV. 
 

== <span style="color:#000080"> Generate primary particles </span> == 


You derive your own class from <span style="color:#ff0000"> G4VUserPrimaryGeneratorAction </span> base class.
Actual generation of primary particles is done via classes <span style="color:#ff0000"> G4ParticleGun </span> and <span style="color:#ff0000"> G4GeneralParticleSource </span>. 

* <span style="color:#ff0000"> G4ParticleGun </span> is used to simulate a beam of particles. It shoots a primary particle of a certain energy and direction from a given point at a given time.
* <span style="color:#ff0000"> G4GeneralParticleSource </span> simulates a beam of particles and the primary vertex is randomly chosen on surface of a given volume with pre-defined energy spectra, spatial and angular distribution. 


<u> Simple example of <span style="color:#ff0000"> MyPrimaryGeneratorAction </span> using particle gun </u>:


<span style="color:#800000"> class MyPrimaryGeneratorAction:public G4VUserPrimaryGeneratorAction { </span>

<span style="color:#800000"> public: </span>

<span style="color:#800000"> MyPrimaryGeneratorAction( </span>

<span style="color:#800000"> const G4String& particleName = "proton", </span>
      
<span style="color:#800000"> G4double energy = 1.*CLHEP::MeV, </span>
      
<span style="color:#800000"> G4ThreeVector position= G4ThreeVector(0,0,0), </span>
      
<span style="color:#800000"> G4ThreeVector momentumDirection = G4ThreeVector(0,0,1)); </span>    
    
<span style="color:#800000"> ~MyPrimaryGeneratorAction(); </span>

<span style="color:#800000"> virtual void GeneratePrimaries(G4Event*); </span>


<span style="color:#800000"> private: </span>
    
<span style="color:#800000"> G4ParticleGun*  fParticleGun; }; </span>


<u> Simple example of <span style="color:#ff0000"> MyPrimaryGeneratorAction </span> using general particle source </u>:


<span style="color:#800000"> class MyPrimaryGeneratorAction:public G4VUserPrimaryGeneratorAction { </span>

<span style="color:#800000"> public: </span>

<span style="color:#800000"> MyPrimaryGeneratorAction(); </span>    

<span style="color:#800000"> ~MyPrimaryGeneratorAction(); </span>

<span style="color:#800000"> virtual void GeneratePrimaries(G4Event*); </span>


<span style="color:#800000"> private: </span>

<span style="color:#800000"> static const G4String ParticleName; </span>

<span style="color:#800000"> static const G4double ParticleEnergy; </span>

<span style="color:#800000"> G4GeneralParticleSource*  fGeneralParticleSource; }; </span>


[http://geant4.web.cern.ch/geant4/UserDocumentation/Doxygen/examples_doc/html/group__extended__common__primaryGenerator.html Here] you can find how to implement MyPrimaryGeneratorAction class defined above in your code.
   

== <span style="color:#000080"> Optional user classes </span> ==


[http://geant4.web.cern.ch/geant4/UserDocumentation/Doxygen/examples_doc/html/group__extended__common__userActions.html Here] you can find examples of user defined RunAction and EventAction classes.