Finish editing

examples-docs/Nozzle/RasterScanningPattern.rst

@@ -1,3 +1,5 @@
+.. _example_nozzle_raster:
+
 RasterScanningPattern.txt
 -------------------------
 

examples-docs/Nozzle/ScanningStationaryTarget.rst

@@ -1,3 +1,5 @@
+.. _example_nozzle_scanning_stationary:
+
 ScanningStationaryTarget.txt
 ----------------------------
 

examples-docs/Nozzle/ScanningTargetMovingHorizontal.rst

@@ -1,3 +1,5 @@
+.. _example_nozzle_scanning_horiz:
+
 ScanningTargetMovingHorizontal.txt
 ----------------------------------
 

examples-docs/Nozzle/ScanningTargetMovingInDepth.rst

@@ -1,3 +1,5 @@
+.. _example_nozzle_scanning_depth:
+
 ScanningTargetMovingInDepth.txt
 -------------------------------
 

examples-docs/Nozzle/ScatteringNozzle_run.rst

@@ -1,3 +1,5 @@
+.. _example_nozzle_scattering_run:
+
 ScatteringNozzle_run.txt
 ------------------------
 

getting-started/authors.rst

@@ -27,6 +27,8 @@ Additional Authors      * Jungwook Shin
                         * Jan Schuemann
                         * Jose Ramos
                         * David Hall
+Editors                 * Joseph Perl
+                        * David Hall
 User Contributions      * Aleksandra Biegun
                         * Fada Guan
 ====================    ============================

parameters/defaults.rst

@@ -119,6 +119,8 @@ Demo Particle Source
 
 
 
+.. _parameters_default_physics:
+
 Physics
 ~~~~~~~
 

parameters/geometry/dividable.rst

@@ -20,9 +20,9 @@ TsSphere    | RBins         | i       | 1
 
 .. image:: dividable.png
 
-Scorers associated with the dividable components may use the same or different divisions (thus one can do things like represent the patient with CT resolution but score with other resolutions). See :ref:`here <scoring_binning>` for details.
+Scorers associated with the dividable components may use the same or different divisions (thus one can do things like represent the patient with CT resolution but score with other resolutions). See :ref:`here <scoring_binning_space>` for details.
 
-You cannot place child components inside a divided component, but if the only reason for dividing this component is to have fine-grained scoring, you can easily work around this limitation. Use an undivided parent component. Place the children into this undivided parent component. Then when you specify that you want to score on this parent component, specify divided scoring (see :ref:`here <scoring_binning>`). TOPAS will automatically create a parallel world version of your component to handle the divided scoring.
+You cannot place child components inside a divided component, but if the only reason for dividing this component is to have fine-grained scoring, you can easily work around this limitation. Use an undivided parent component. Place the children into this undivided parent component. Then when you specify that you want to score on this parent component, specify divided scoring (see :ref:`here <scoring_binning_space>`). TOPAS will automatically create a parallel world version of your component to handle the divided scoring.
 
 You can optionally specify different materials for each voxel, overriding the value set in the regular ``Ge/.../Material`` parameter::
 

parameters/geometry/generic.rst

@@ -1,3 +1,5 @@
+.. _geometry_generic:
+
 Generic Components
 ------------------
 

parameters/geometry/patient.rst

@@ -3,12 +3,12 @@ Patient Components
 
 TOPAS currently supports the following Patient Component types:
 
-=========================== ========================
-Geometry Component          Type
-=========================== ========================
-:ref:`geometry_dicom`       TsDicomPatient
-:ref:`geometry_xio`         TsXioPatient
-=========================== ========================
+==============================  ========================
+Geometry Component              Type
+==============================  ========================
+:ref:`geometry_patient_dicom`   TsDicomPatient
+:ref:`geometry_patient_xio`     TsXioPatient
+==============================  ========================
 
 It is also necessary to define how to convert the imaging data to material data, following a :ref:`imaging_material_conversion` scheme.
 
@@ -81,7 +81,7 @@ By default, OpenGL graphics switches its fast "Stored" mode to its more memory e
 
 
 
-.. _geometry_dicom:
+.. _geometry_patient_dicom:
 
 Patient in DICOM Format
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -132,7 +132,7 @@ To make TOPAS color the voxels by structure::
 
 
 
-.. _geometry_xio:
+.. _geometry_patient_xio:
 
 Patient in XiO Format
 ~~~~~~~~~~~~~~~~~~~~~

parameters/geometry/specialized.rst

@@ -548,6 +548,7 @@ A typical compensator has the following parameters (see :ref:`example_nozzle_sca
     * ...
     * nN deltaXn Xn Yn
     * D1 D2 ... DnN
+
   NumberOfRows = N defines how many rows of drill holes there are (in Y), the MainCylinderThickness. The DrillHoleDiameter is the diameter of the drill hole, we approximate this by a hexagon. The values ni are the number of drill holes in X for each row of drill holes in Y, deltaXi defines the step size (and direction) and Xi and Yi are the starting position of the drilling for this row.
 
 * ``"MGH"``: all sizes are in inches:

parameters/graphics.rst

@@ -1,12 +1,14 @@
 Graphics
 ========
 
-You may have zero, one or more graphics active at same time::
+You may have zero, one or more graphics windows active at same time::
 
     s:Gr/MyGraphic1/Type = "OpenGL" # OpenGL, HepRep, VRML, DAWN, RayTracer, RayTracerX
 
 Note that the file-based graphics systems, HepRep, VRML and DAWN may not show any image until at least one history is run. We will revisit this issue when we move to the next Geant4 version.
 
+.. todo:: file-based graphics not visible until one history is run
+
 HepRep files are designed to be viewed in a Java application called HepRApp.
 Details can be found `here <http://geant4.slac.stanford.edu/Presentations/vis/G4HepRAppTutorial/G4HepRAppTutorial.html>`_.
 
@@ -22,8 +24,8 @@ File-based graphics systems will also expect a file name::
 
     s:Gr/MyGraphic1/FileName = "MyFileName" # Defaults to name of view (which here is MyGraphic1).
 
-Will use this filename plus an "_n" where n increments with each refresh.
-Due to limitations in Geant4, only affects OpenGL and HepRep. For other cases, the file name is a fixed value, ``g4_`` followed by a file number.
+Will use this filename plus an ``_n`` where n increments with each refresh.
+Due to limitations in Geant4, ``FileName`` only affects OpenGL and HepRep. For other cases, the file name is a fixed value, ``g4_`` followed by a file number.
 
 This can be more than just a file name - it can include a relative or absolute file path, as in::
 
@@ -40,7 +42,12 @@ Colors are defined by specifying their red, green, blue components, each on a sc
 
     iv:Gr/Color/lightblue = 3 175 255 255
 
-By default, trajectories will be drawn as what Geant4 calls "Smooth Trajectories", which means they include additional points to make them curve smoothly in a magnetic field. Geant4 does not actually use these "auxiliary points" in its simulation results, they are just present to make visualization in a field look better. In some cases, Geant4 has trouble handling these auxiliary points, and reports:  ``!!!!!!!! Filter: auxiliary points are being memory leaked !!!!!``
+By default, trajectories will be drawn as what Geant4 calls "Smooth Trajectories", which means they include additional points to make them curve smoothly in a magnetic field. Geant4 does not actually use these "auxiliary points" in its simulation results, they are just present to make visualization in a field look better. In some cases, Geant4 has trouble handling these auxiliary points, and reports:
+
+.. code-block:: plain
+
+    ``!!!!!!!! Filter: auxiliary points are being memory leaked !!!!!``
+
 To work around this, turn off trajectory drawing or tell Geant4 not to making the trajectories smooth::
 
     b:Gr/MyGraphic1/UseSmoothTrajectories = "False" # defaults to "True"
@@ -59,7 +66,7 @@ You can visualize magnetic fields, with field intensity and direction depicted t
 
 Use with caution. When combined with rotation seems to sometimes cause crashes in polycone drawing (involved in drawing the arrowheads).
 
-By default, graphics views will refresh after every run. But you can change this to show each history individually or to accumulate all histories for the entire session (multiple runs) with::
+By default, graphics views will refresh after every run. But you can change this to show each history individually or to accumulate all histories for the entire session (multiple runs). This applies globally to all graphics views::
 
     s:Gr/RefreshEvery = "History" # "History", "Run" or "Session"
 
@@ -92,80 +99,85 @@ You can set Topas so that each time the OpenGL updates, the view is copied to a
     b:Gr/MyGraphic1/CopyOpenGLToPDF = "True" # save to PDF
     b:Gr/MyGraphic1/CopyOpenGLToSVG = "True" # save to Scalable Vector Graphics
     b:Gr/MyGraphic1/CopyOpenGLToEPS = "True" # save to Encapsulated PostScript
-    b:Gr/MyGraphic1/CopyOpenGLToPS = "True" # save to PostScript
+    b:Gr/MyGraphic1/CopyOpenGLToPS  = "True" # save to PostScript
 
 Some views may result in one of the following warning messages from Geant4 Visualization.  These messages are just informational and can be safely ignored.
 
-* "WARNING: Viewpoint direction is very close to the up vector direction.
-  Consider setting the up vector to obtain definable behavior."
-* "G4PhysicalVolumeSearchScene::FindVolume:
-  Required volume "Phantom3_10x10x1", copy no. 0, found more than once.
-  This function is not smart enough to distinguish identical physical volumes which have different parentage. It is tricky to specify in general. This function gives you access to the first occurrence only."
+.. code-block:: plain
+
+    "WARNING: Viewpoint direction is very close to the up vector direction.
+    Consider setting the up vector to obtain definable behavior."
+
+    "G4PhysicalVolumeSearchScene::FindVolume:
+    Required volume "Phantom3_10x10x1", copy no. 0, found more than once.
+    This function is not smart enough to distinguish identical physical volumes which
+    have different parentage. It is tricky to specify in general. This function gives
+    you access to the first occurrence only."
 
-To create movies, Zoom, Theta, Phi, TransX, TransY, Projection and PerspectiveAngle can be controlled by time features.
+To create movies, ``Zoom``, ``Theta``, ``Phi``, ``TransX``, ``TransY``, ``Projection`` and ``PerspectiveAngle`` can be controlled by :ref:`time_feature`.
 
 Trajectory Coloring::
 
     s:Gr/MyGraphic1/ColorBy = "Charge" # "Charge", "ParticleType", "OriginComponent", "Energy", "Momentum", "Generation", "CreatorProcess"
 
-For ColorBy = Charge, trajectories default to red, greed, blue for negative, neutral and positive.  You can override these defaults with::
+For ``ColorBy = "Charge"``, trajectories default to red, greed, blue for negative, neutral and positive.  You can override these defaults with::
 
     sv:Gr/MyGraphic1/ColorByChargeColors = 3 "blue" "green" "red" # colors for neg, neutral, pos
 
-For ColorBy = ParticleType, colors are Geant4 defaults:
+For ``ColorBy = "ParticleType"``, colors are Geant4 defaults:
 
-* gamma = green
-* e- = red
-* e+ = blue
-* pi+- = magenta
-* proton = cyan
-* neutron = yellow
-* other = grey
+================    ==========
+Particle Species    Color
+================    ==========
+gamma               green
+e-                  red
+e+                  blue
+pi+                 magenta
+proton              cyan
+neutron             yellow
+other               gray
+================    ==========
 
 You can override these settings with (particle names are described :ref:`here <particle_names>`)::
 
     sv:Gr/MyGraphic1/ColorByParticleTypeNames = 4 "e-" "gamma" "proton" "neutron" # any number of particle names
     sv:Gr/MyGraphic1/ColorByParticleTypeColors = 4 "red" "green" "blue" "yellow" # for each particle type above. All other particles will be set to grey.
 
-For ColorBy = OriginVolume, trajectories are grey unless they come from a named volume in::
+For ``ColorBy = "OriginVolume"``, trajectories are grey unless they come from a named volume in::
 
     sv:Gr/MyGraphic1/ColorByOriginVolumeNames = 1 "Propeller20/Leaf" # one or more volume
     sv:Gr/MyGraphic1/ColorByOriginVolumeColors = 1 "red" # one color for each name above
 
-For ColorBy = OriginComponent, trajectories are grey unless they come from a named component in::
+For ``ColorBy = "OriginComponent"``, trajectories are grey unless they come from a named component in::
 
     sv:Gr/MyGraphic1/ColorByOriginComponentNames = 1 "jaws" # one or more component names
     sv:Gr/MyGraphic1/ColorByOriginComponentColors = 1 "red" # one color for each name above
 
-For ColorBy = ColorByOriginComponentOrSubComponentOf, trajectories are grey unless they come from a named component or any of its subcomponents in::
+For ``ColorBy = "ColorByOriginComponentOrSubComponentOf"``, trajectories are grey unless they come from a named component or any of its subcomponents in::
 
     sv:Gr/MyGraphic1/ColorByOriginComponentNames = 1 "Nozzle" # one or more components
     sv:Gr/MyGraphic1/ColorByOriginComponentColors = 1 "red" # one color for each name above
 
-For ColorBy = Energy::
+For ``ColorBy = "Energy"``::
 
     dv:Gr/MyGraphic1/ColorByEnergyRanges = 3 1. 4. 8. MeV # limits of energy ranges
     sv:Gr/MyGraphic1/ColorByEnergyColors = 4 "red green blue yellow" # one for every energy interval that is defined by those ranges - one more value than number of ranges since includes less than first range value and greater than first range value
 
-For ColorBy = Momentum::
+For ``ColorBy = "Momentum"``::
 
     dv:Gr/MyGraphic1/ColorByMomentumRanges = 3 1. 4. 8. MeV # limits of momentum ranges
     sv:Gr/MyGraphic1/ColorByMomentumColors = 4 "red" "green" "blue" "yellow" # one for every energy interval that is defined by those ranges - one more value than number of ranges since includes less than first range value and greater than first range value
 
-For ColorBy = Generation::
+For ``ColorBy = "Generation"``::
 
     sv:Gr/MyGraphic1/ColorByGenerationColors = 2 "red" "green" # colors for primary and secondaries
 
-For ColorBy = CreatorProcess::
+For ``ColorBy = "CreatorProcess"``::
 
     sv:Gr/MyGraphic1/ColorByCreatorProcessNames = 5 "eBrem" "annihil" "Decay" "eIoni" "hIoni" # one or more process name
     sv:Gr/MyGraphic1/ColorByCreatorProcessColors = 5 "red" "green" "blue" "yellow" "magenta" # one for every process name
 
-To control how often graphics refresh (applies globally to all graphics views)::
-
-    s:Gr/RefreshEvery = "Run" # "History", "Run" or "Session"
-
-To filter what trajectories will be in the graphics, use similar syntax to that used for filtering of scoring and particle source (apply globally to all graphics views)::
+To filter what trajectories will be in the graphics, use similar syntax to that used for :ref:`scoring_filter` and :ref:`source_filter` (applies globally to all graphics views)::
 
     sv:Gr/OnlyIncludeParticlesNamed = 2 "proton" "neutron" # one or more particle names
     sv:Gr/OnlyIncludeParticlesCharged = 1 "negative" # one or more "positive", "negative" or "neutral"
@@ -186,7 +198,9 @@ Note that the following three filters may cause a crash if the particle origin i
 
 We will study this issue again when we move to the next Geant4 version.
 
-Visualization control for a specific component is done as part of the Ge/ parameters for that component rather than in the ``Gr/`` parameters::
+.. todo:: Some graphics filters crash if particle origin is on World boundary
+
+Visualization control for a specific component is done as part of the ``Ge/`` parameters for that component rather than in the ``Gr/`` parameters::
 
     s:Ge/MyComponent/Color = "red"
     s:Ge/MyComponent/DrawingStyle = "Solid" # "Solid", "Wireframe" or "FullWireFrame".
@@ -203,3 +217,5 @@ We sometimes see error messages from visualization of the following form:
     Required volume "PhantomCentralDose_1x1x40", copy no. 0, found more than once...
 
 Such messages can be ignored. They do not affect the simulation results. We will revisit how to solve these error messages once we move to the next Geant4 version.
+
+.. todo:: Visualization error messages

parameters/overall/mode.rst

@@ -1,10 +1,14 @@
+.. _time_mode:
+
 Time mode
 ---------
 
 If you do nothing special, TOPAS will do a single run with no time variation. We call this "Fixed Time Mode". Other available modes are "Sequential" and "Random".
 
 
 
+.. _time_mode_fixed:
+
 Fixed Time Mode
 ~~~~~~~~~~~~~~~
 
@@ -20,6 +24,8 @@ If you have more than one source, the run will continue until all sources have r
 
 
 
+.. _time_mode_sequential:
+
 Sequential Time Mode
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -67,6 +73,8 @@ By default, scorers will output just once, after the entire session. But if you
 
 
 
+.. _time_mode_random:
+
 Random Time Mode
 ~~~~~~~~~~~~~~~~
 

parameters/physics/intro.rst

@@ -12,10 +12,10 @@ Advanced users can set their own parameters to override some of these default se
 
 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.
+* :ref:`physics_reference` are pre-made, complete lists provided by Geant4.
+* :ref:`physics_modular` 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 also provide your own physics list using :ref:`extension_physics` (not recommended unless you have significant Geant4 expertise).
 
 You can get a list of what processes are in your currently selected physics list by::
 

parameters/physics/misc.rst

@@ -4,14 +4,14 @@ 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.
+See :ref:`extension_physics` 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::
+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
@@ -26,13 +26,11 @@ You can have more than one list defined at the same time, but only the one speci
 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::
+Production Thresholds and range cuts are discussed in detail in the `Geant4 Application Developers Guide <http://geant4.cern.ch/G4UsersDocuments/UsersGuides/ForApplicationDeveloper/html/TrackingAndPhysics/thresholdVScut.html>`_. 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