Primary and Physics sections

topasmc · Aug 8, 2016 · eba44e1 · eba44e1
1 parent a133f42
commit eba44e1
Show file tree

Hide file tree

Showing 21 changed files with 683 additions and 3 deletions.
diff --git a/examples-docs/Basic/Emittance_Gaussian.rst b/examples-docs/Basic/Emittance_Gaussian.rst
@@ -1,3 +1,5 @@
+.. _example_basic_emittance_gaussian:
+
 Emittance_Gaussian.txt
 ----------------------
 

diff --git a/examples-docs/Basic/Emittance_Twiss.rst b/examples-docs/Basic/Emittance_Twiss.rst
@@ -1,3 +1,5 @@
+.. _example_basic_emittance_twiss:
+
 Emittance_Twiss.txt
 -------------------
 

diff --git a/examples-docs/Basic/Spectrum.rst b/examples-docs/Basic/Spectrum.rst
@@ -1,3 +1,5 @@
+.. _example_basic_spectrum:
+
 Spectrum.txt
 ------------
 

diff --git a/examples-docs/PhaseSpace/WriteASCII.rst b/examples-docs/PhaseSpace/WriteASCII.rst
@@ -1,3 +1,5 @@
+.. _example_phsp_ascii_write:
+
 WriteASCII.txt
 --------------
 

diff --git a/examples-docs/PhaseSpace/WriteBinary.rst b/examples-docs/PhaseSpace/WriteBinary.rst
@@ -1,3 +1,5 @@
+.. _example_phsp_binary_write:
+
 WriteBinary.txt
 ---------------
 

diff --git a/examples-docs/PhaseSpace/WriteLimited.rst b/examples-docs/PhaseSpace/WriteLimited.rst
@@ -1,3 +1,5 @@
+.. _example_phsp_limited_write:
+
 WriteLimited.txt
 ----------------
 

diff --git a/parameters/physics/index.rst b/parameters/physics/index.rst
@@ -6,6 +6,7 @@ Physics
 .. toctree::
     :maxdepth: 2
 
+    intro
     modular
     reference
     optical

diff --git a/parameters/physics/intro.rst b/parameters/physics/intro.rst
@@ -0,0 +1,22 @@
+Introduction
+------------
+
+In Geant4, physics options are set in pieces of code called "Physics Lists". A physics list specifies what particles and physics processes are defined, plus various cuts and options.
+By default, we set TOPAS physics to a list that has been shown to work well for proton therapy research at the Massachusetts General Hospital. This list includes models that handle not only protons but also all secondary particles (neutrons, helium ions, deuterons, tritons, photons, electrons, etc.). The default gives results that closely match a previous custom list that was described in:
+
+* C. Zacharatou Jarlskog and H. Paganetti, "Physics settings for using the Geant4 toolkit in proton therapy," IEEE Trans. Nucl. Sci. 55, 1018-1025 (2008)
+
+but which can no longer be used since that list corresponded to a much earlier Geant4 release.
+
+Advanced users can set their own parameters to override some of these default settings, or can specify entirely different physics lists.
+
+You can choose from two general types of physics lists:
+
+* "Reference" physics lists are pre-made, complete lists provided by Geant4.
+* "Modular" physics lists are lists where you mix and match a set of modules to create a customized complete list.
+
+You can also provide your own physics list (not recommended unless you have significant Geant4 expertise).
+
+You can get a list of what processes are in your currently selected physics list by::
+
+    b:Ph/ListProcesses = "True"
diff --git a/parameters/physics/misc.rst b/parameters/physics/misc.rst
@@ -4,11 +4,46 @@ Miscellaneous
 User-Supplied Physics Lists
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+See Extending TOPAS at the end of this user guide for details on how to provide your own physics list. This option is not recommended unless you have significant Geant4 expertise.
+
+
+
 Multiple Physics Lists
 ~~~~~~~~~~~~~~~~~~~~~~
 
+You can have more than one list defined at the same time, but only the one specified in Ph/ListName will actually be in effect::
+
+    s:Ph/ListName = "MyList1"
+    s:Ph/MyList1/Type= "QGSP_BERT_HP" # This list is in effect now
+    d:Ph/MyList1/CutForAllParticles = 0.05 mm
+    ...
+    s:Ph/MyList2/Type= "Geant4_Modular" # This list goes into effect if Ph/ListName set to MyList2
+    sv:Ph/MyList2/Modules = 1 "g4em-standard_opt3"
+    d:Ph/MyList2/CutForGamma = 0.04 mm
+
+
+
 Production Thresholds
 ~~~~~~~~~~~~~~~~~~~~~
 
+Production Thresholds and range cuts are discussed in detail in the Geant4 Application Developers Guide. By default, appropriate limits are set by the physics list. You can override these defaults with::
+
+    d:Ph/MyPhysics/SetProductionCutLowerEdge = 200 eV
+    d:Ph/MyPhysics/SetProductionCutHighEdge = 30 MeV
+
+For further discussion, see the Geant4 Application Developers Guide.
+
+
+
 Step Size
 ~~~~~~~~~
+
+The selection of step size is a complex issue in Monte Carlo tracking. Geant4 has its own complex logic for automatically selecting what it thinks will be an appropriate step size, based on local geometry and physics, and the user will not generally need to override this automatic behavior. However, your applications may be sensitive to this behavior, and you may therefore want to set a maximum step size in certain components. In general, larger step sizes give faster performance, but smaller step sizes may give better accuracy.
+
+To limit Geant4's maximum step size in a given component::
+
+    d:Ge/MyComponent/MaxStepSize = 1. mm # sets maximum step size used in this component
+
+Step size settings do not affect other Components placed within this Component. You must explicitly set the step size for any subcomponents that you want to affect.
+
+The choice of maximum step size is highly dependent on your exact simulation problem. If you think you need to set a maximum step size, try running with several values, and pick one for which a small variation up or down does not cause a significant change in results.
diff --git a/parameters/physics/modular.rst b/parameters/physics/modular.rst
@@ -1,2 +1,112 @@
+.. _physics_modular:
+
 Modular Physics Lists
 ---------------------
+
+The default list we provide is a Modular physics list. It is specified by the following parameters that are set for you by default::
+
+    s:Ph/ListName = "Default"
+    s:Ph/Default/Type= "Geant4_Modular"
+    sv:Ph/Default/Modules = 6 "g4em-standard_opt4" "g4h-phy_QGSP_BIC_HP" "g4decay" "g4ion-binarycascade" "g4h-elastic_HP" "g4stopping"
+    d:Ph/Default/EMRangeMin = 100. eV # See note below on recommended values
+    d:Ph/Default/EMRangeMax = 500. MeV
+    i:Ph/Default/dEdXBins = 220
+    i:Ph/Default/LambdaBins = 220
+
+The Geant4 EM physics group recommends against setting EMRangeMin too low:
+
+* Set to 100. eV or greater when using standard Geant4 EM physics
+* Set to 10. eV or greater when using Geant4-DNA physics
+
+If you want to run with no physics, but only the transportation process (useful for some demos and tests), specify the modules in the following special way::
+
+    sv:Ph/Default/Modules = 1 "Transportation_Only"
+
+The full list of module names and the corresponding Geant4 class names are shown in the table at the end of this section.
+
+The remaining options for Geant4_Modular are::
+
+    d:Ph/Default/CutForAllParticles = 0.05 mm # single range cut to use for all particles
+    d:Ph/Default/CutForGamma = 0.05 mm # overrides CutForAllParticles for Gamma
+    d:Ph/Default/CutForElectron = 0.05 mm # overrides CutForAllParticles for Electron
+    d:Ph/Default/CutForPositron = 0.05 mm # overrides CutForAllParticles for Positron
+    d:Ph/Default/CutForProton = 0.05 mm # overrides CutForAllParticles for Proton
+    d:Ph/Default/CutForAlpha = 0.05 mm # overrides CutForAllParticles for Alpha
+    d:Ph/Default/CutForDeuteron = 0.05 mm # overrides CutForAllParticles for Deuteron
+    d:Ph/Default/CutForTriton = 0.05 mm # overrides CutForAllParticles for Triton
+    d:Ph/Default/EMRangeMin = 100. eV # minimum for EM tables
+    d:Ph/Default/EMRangeMax = 300. MeV # maximum for EM tables
+    i:Ph/Default/dEdXBins = 220 # number of bins for dEdX tables
+    i:Ph/Default/LambdaBins = 220 # number of Lambda bins
+    b:Ph/Default/Fluorescence = "False" # Set to true to turn on Fluorescence
+    b:Ph/Default/Auger = "False" # Set to true to turn on Auger
+    b:Ph/Default/PIXE = "False" # Set to true to turn on PIXE
+
+By default, cuts affect the entire world, but you can optionally divide the world into several regions and can specify different cuts in each region. First, specify which components belong to a given region::
+
+    s:Ge/MyComponent/AssignToRegionNamed = “MyRegion”
+
+* All children of this component will also be assigned to that region, unless the child has its own "AssignToRegionNamed" parameter.
+* There is no requirement that all of the components in a given region be contiguous.
+
+Then assign cuts per region by including the region name in the parameter name as in::
+
+    d:Ph/Default/ForRegion/MyRegion/CutForGamma = 0.05 mm
+    d:Ph/Default/ForRegion/MyRegion/CutForElectron = 0.05 mm
+    d:Ph/Default/ForRegion/MyRegion/CutForPositron = 0.05 mm
+    d:Ph/Default/ForRegion/MyRegion/CutForProton = 0.05 mm
+
+Cuts do not affect all processes, but only those listed below:
+
+* Energy thresholds for gamma are used in Bremsstrahlung
+* Energy thresholds for electrons are used in ionization and e+e- pair production processes Energy thresholds for positrons are used in e+e- pair production process
+* Energy thresholds for gamma and electrons are used optionally in all discrete processes
+    * Photoelectriceffect
+    * Compton
+    * gamma conversion
+* Energy thresholds for protons are used in processes of elastic scattering for hadrons and ions defining the threshold for kinetic energy of nuclear recoil
+
+==========================  ===========================
+TOPAS Module Name           Geant4 Class Name
+==========================  ===========================
+g4h-chargeexchange          G4ChargeExchangePhysics
+g4decay                     G4DecayPhysics
+g4em-dna                    G4EmDNAPhysics
+g4em-extra                  G4EmExtraPhysics
+g4em-livermore              G4EmLivermorePhysics
+g4em-polarized              G4EmLivermorePolarizedPhysics
+g4em-lowep                  G4EmLowEPPhysics
+g4em-penelope               G4EmPenelopePhysics
+g4em-standard_opt0          G4EmStandardPhysics
+g4em-standard_opt1          G4EMStandardPhysics_option1
+g4em-standard_opt2          G4EMStandardPhysics_option2
+g4em-standard_opt3          G4EMStandardPhysics_option3
+g4em-standard_opt4          G4EMStandardPhysics_option4
+g4em-standard_WVI           G4EmStandardPhysicsWVI
+g4h-elastic_D               G4HadronDElasticPhysics
+g4h-elastic                 G4HadronElasticPhysics
+g4h-elastic_HP              G4HadronElasticPhysicsHP
+g4h-elastic_LEND            G4HadronElasticPhysicsLEND
+g4h-elastic_XS              G4HadronElasticPhysicsXS
+g4h-elastic_H               G4HadronHElasticPhysics
+g4h-inelastic_QBBC          G4HadronInelasticQBBC
+g4h-phy_FTFP_BERT           HadronPhysicsFTFP_BERT
+g4h-phy_FTFP_BERT_HP        HadronPhysicsFTFP_BERT_HP
+g4h-phy_FTFP_BERT_TRV       HadronPhysicsFTFP_BERT_TRV
+g4h-phy_FTF_BIC             HadronPhysicsFTF_BIC
+g4h-phy_QGSP_BERT           HadronPhysicsQGSP_BERT
+g4h-phy_QGSP_BERT_HP        HadronPhysicsQGSP_BERT_HP
+g4h-phy_QGSP_BIC            HadronPhysicsQGSP_BIC
+g4h-phy_QGSP_BIC_HP         HadronPhysicsQGSP_BIC_HP
+g4h-phy_QGSP_FTFP_BERT      HadronPhysicsQGSP_FTFP_BERT
+g4h-phy_QGS_BIC             HadronPhysicsQGS_BIC
+g4h-phy_Shielding           HadronPhysicsShielding
+g4ion-binarycascade         G4IonBinaryCascadePhysics
+g4ion-inclxx                G4IonINCLXXPhysics
+g4ion                       G4IonPhysics
+g4ion-QMD                   G4IonQMDPhysics
+g4n-trackingcut             G4NeutronTrackingCut
+g4optical                   G4OpticalPhysics
+g4radioactivedecay          G4RadioactiveDecayPhysics
+g4stopping                  G4StoppingPhysics
+==========================  ===========================
diff --git a/parameters/physics/optical.rst b/parameters/physics/optical.rst
@@ -4,5 +4,100 @@ Optical Physics
 Optical Photons
 ~~~~~~~~~~~~~~~
 
+A full description of the tracking of optical photons is available in the Geant4 Guide for Applications Developers.
+
+Topas allows to include optical physics by means of the g4optical module in the physics list. The available optical processes included in the g4optical module are: scintillation, Cerenkov radiation, wavelength shifting, optical absorption, Rayleigh scattering and boundary processes. However, this module is not sufficient to set up the generation and tracking of optical photons. The optical properties of the material of the volumes must to be defined too (at the least the refractive index must to be defined). There exist two types of variables to define the optical properties: a vector based and constant based. The vector-based parameter allows to define a property (refractive index for example) in function of the photon’s energy. While the constant-based parameters allows to define an scalar (scintillation yield for example)
+
+To activate the optical properties in a material one must to set::
+
+    b:Ma/MyMaterial/EnableOpticalProperties = "True"
+
+To set a property based on a vector, one must to define the energy of reference. For example to include the refractive index one must to define two parameters::
+
+    dv:Ma/MyMaterial/RefractiveIndex/Energies = 3 2.0 2.5 3.0 eV
+    uv:Ma/MyMaterial/RefractiveIndex/Values = 3 1.58 1.58 1.58
+
+To set a property based on a scalar only one parameter is needed, for example::
+
+    u:Ma/MyMaterial/ScintillationYield = 1120 # in ph/MeV
+    d:Ma/MyMaterial/FastTimeConstant = 2.1 ns
+
+The full list of parameters available is listed in the next table.
+
+==============  ===================
+Type            Parameter name
+==============  ===================
+uv              RefractiveIndex
+uv              ImaginaryRefractiveIndex
+uv              RealRefractiveIndex
+dv              AbsLength
+uv              FastComponent
+uv              SlowComponent
+uv              Miehg
+uv              SpecularLobeConstant
+uv              SpecularSpikeConstant
+uv              BackScatterConstant
+uv              WLSAbsLength
+uv              WLSComponent
+uv              Reflectivity
+uv              Efficiency
+uv              Transmittance
+u               ScintillationYield ( in photons/MeV)
+u               ResolutionScale
+d               FastTimeConstant
+d               SlowTimeConstant
+u               YieldRatio
+u               MiehgForward
+u               MiehgBackward
+u               MiehgForwardRatio
+u               WLSTimeConstant
+u               BirksConstant (in mm/MeV)
+==============  ===================
+
+
+
 Optical Surfaces
 ~~~~~~~~~~~~~~~~
+
+If perfect smooth interface is between two dielectric materials, the users only needs to provide the refractive index. In all other cases, a surface or optical boundary needs to be defined. There exist two kinds of surfaces: the border surface that delimits the boundary between two components; and the skin surface which surrounds one single component.
+Border surface is ordered in the sense that the order of the components matters, two border surfaces can exists between a pair of components. Thus, the follow parameters define two surfaces for a pair of components::
+
+    s:Ge/MyComponent1/OpticalBehaviorTo/MyComponent2 = "MySurface1"
+    s:Ge/MyComponent2/OpticalBehaviorTo/MyComponent1 = "MySurface2"
+
+For skin surface only one surface can be defined per component::
+
+    s:Ge/MyComponent1/OpticalBehavior = "MySurface1"
+
+Surfaces can be defined as follows (see next table for description)::
+
+    s:Su/MySurfaceName/Type = "dielectric_dielectric" # or dielectric_metal
+
+Next, choose the model for optical surfaces::
+
+    s:Su/MySurfaceName/Model = "Glisur " # Or Unified
+
+Finally the finish::
+
+    s:Su/MySurfaceName/Finish = "Polished"
+
+In addition, more detailed properties can be added by parameters described in the table 1. In such a case, the way to define would be for example (with prefix Su instead of Ma)::
+
+    dv:Su/MySurfaceName/Energies = 2 1.0 4.0 eV
+    uv:Su/MySurfaceName/Reflectivity = 2 0.8 0.8
+
+========  ==============  ===============================================================
+Type      Parameter name  Possible values
+========  ==============  ===============================================================
+string    Type            | dielectric_dielectric
+                          | dielectric_metal
+string    Finish          | polished: *smooth perfectly polished surface*
+                          | polishedfrontpainted: *smooth top-layer (front) paint*
+                          | polishedbackpainted: *same as polished but with a back-paint*
+                          | ground: *rough surface*
+                          | groundfrontpainted: *rough top-layer (front) paint*
+                          | groundbackpainted: *same as ground but with a back-paint*
+string    Model           | Unified: A. Levin and C. Moisan, A More Physical Approach to Model the Surface Treatment of Scintillation Counters and its Implementation into DETECT, TRIUMF Preprint TRI-PP-96-64, Oct. 1996.
+                          | Glisur: original GEANT3.21 model
+unitless  SigmaAlpha      Between 0 and 1. By default 0
+========  ==============  ===============================================================
diff --git a/parameters/physics/reference.rst b/parameters/physics/reference.rst
@@ -1,2 +1,19 @@
+.. _physics_reference:
+
 Reference Physics Lists
 -----------------------
+
+Reference physics lists are pre-made, complete lists provided by Geant4.
+
+One complication with reference lists is that they do not support use of Parallel Worlds. This means that you cannot place components into a parallel world, and, for the dividable components (TsBox, TsCylinder and TsSphere), you cannot score with a different set of divisions than you have set for the component itself (we handle such complex scoring by creating parallel worlds). TOPAS will give an error if you attempt to use a reference list in a situation where parallel worlds are needed. In such situations, use Geant4_Modular as described below.
+
+The names of the reference physics lists, and their detailed descriptions, are `here
+<http://geant4.web.cern.ch/geant4/support/proc_mod_catalog/physics_lists/referencePL.shtml>`_.
+
+To use a reference physics list, specify the list name in the Type parameter, such as::
+
+    s:Ph/Default/Type = "QGSP_BERT_HP"
+
+Reference physics lists allow only one additional option::
+
+    d:Ph/Default/CutForAllParticles = 0.05 mm # single range cut to use for all particles