Start geometry chapter

examples-docs/Basic/Isotope.rst

@@ -1,3 +1,5 @@
+.. _example_basic_isotope:
+
 Isotope.txt
 -----------
 

examples-docs/Basic/LayeredMassGeometry.rst

@@ -1,3 +1,5 @@
+.. _example_basic_layeredmassgeometry:
+
 LayeredMassGeometry.txt
 -----------------------
 

examples-docs/Basic/ShapeTestWithAllParameters.rst

@@ -1,3 +1,5 @@
+.. _example_basic_shapesall:
+
 ShapeTestWithAllParameters.txt
 ------------------------------
 

examples-docs/Scoring/DoseInVoxelMaterials.rst

@@ -1,3 +1,5 @@
+.. _example_scoring_voxelmaterials:
+
 DoseInVoxelMaterials.txt
 ------------------------
 

examples-docs/SpecialComponents/DipoleMagnet.rst

@@ -1,3 +1,5 @@
+.. _example_special_dipole:
+
 DipoleMagnet.txt
 ----------------
 

examples-docs/SpecialComponents/PurgingMagnet_move.rst

@@ -1,3 +1,5 @@
+.. _example_special_purgingmagnet:
+
 PurgingMagnet_move.txt
 ----------------------
 

examples-docs/SpecialComponents/QuadAndDipoleMagnets.rst

@@ -1,3 +1,5 @@
+.. _example_special_quadanddipole:
+
 QuadAndDipoleMagnets.txt
 ------------------------
 

examples-docs/SpecialComponents/QuadrupoleMagnet.rst

@@ -1,3 +1,5 @@
+.. _example_special_quadrupole:
+
 QuadrupoleMagnet.txt
 --------------------
 

examples-docs/SpecialComponents/RangeModulator.rst

@@ -1,3 +1,5 @@
+.. _example_special_rmw:
+
 RangeModulator.txt
 ------------------
 

examples-docs/SpecialComponents/RangeModulator_ConstantBeam.rst

@@ -1,3 +1,5 @@
+.. _example_special_rmw_constant:
+
 RangeModulator_ConstantBeam.txt
 -------------------------------
 

examples-docs/SpecialComponents/RangeModulator_CurrentModulatedBeam.rst

@@ -1,3 +1,5 @@
+.. _example_special_rmw_modulated:
+
 RangeModulator_CurrentModulatedBeam.txt
 ---------------------------------------
 

examples-docs/SpecialComponents/UniformElectroMagneticField.rst

@@ -0,0 +1,6 @@
+.. _example_special_electromagnet:
+
+UniformElectroMagneticField.txt
+-------------------------------
+
+.. literalinclude:: /examples/SpecialComponents/UniformElectroMagneticField.txt

examples-docs/SpecialComponents/index.rst

@@ -21,3 +21,4 @@ SpecialComponents
 	RangeModulator_CurrentModulatedBeam
 	RidgeFilter
 	RotatingMagnet
+	UniformElectroMagneticField

examples/SpecialComponents/UniformElectroMagneticField.txt

@@ -0,0 +1,62 @@
+# Uniform electric field
+
+d:Ge/World/HLX       = 2.0 m
+d:Ge/World/HLY       = 2.0 m
+d:Ge/World/HLZ       = 2.0 m
+b:Ge/World/Invisible = "True"
+s:Ge/World/Material = "Vacuum"
+
+s:Ge/DriftBox/Type          = "TsBox"
+s:Ge/DriftBox/Parent        = "World"
+s:Ge/DriftBox/Material      = "Vacuum"
+d:Ge/DriftBox/HLX           = 80 cm
+d:Ge/DriftBox/HLY           = 80 cm
+d:Ge/DriftBox/HLZ           = 100 cm
+s:Ge/DriftBox/Field = "UniformElectroMagnetic"
+u:Ge/DriftBox/ElectricFieldDirectionX    = 1.0
+u:Ge/DriftBox/ElectricFieldDirectionY    = 1.0
+u:Ge/DriftBox/ElectricFieldDirectionZ    = 0.0
+d:Ge/DriftBox/ElectricFieldStrength      = 5000 kV/cm
+u:Ge/DriftBox/MagneticFieldDirectionX    = 0.0
+u:Ge/DriftBox/MagneticFieldDirectionY    = 1.0
+u:Ge/DriftBox/MagneticFieldDirectionZ    = 0.0
+d:Ge/DriftBox/MagneticFieldStrength      = 5.0 tesla
+d:Ge/DriftBox/RotZ     = Tf/RotationStep/Value deg
+
+d:Ge/BeamPosition/TransZ = Ge/World/HLZ cm
+d:Ge/BeamPosition/RotX   = 180. deg
+
+i:Tf/Verbosity               = 1
+d:Tf/TimelineEnd             = 30.0 ms
+i:Tf/NumberOfSequentialTimes = 40
+
+s:Tf/RotationStep/Function            = "Linear deg"
+d:Tf/RotationStep/Rate                = 5. deg/ms
+d:Tf/RotationStep/StartValue          = -28.0 deg
+d:Tf/RotationStep/RepetitionInterval  = 360. ms
+
+s:So/Example/Type                     = "Beam"
+s:So/Example/Component                = "BeamPosition"
+s:So/Example/BeamParticle             = "chargedgeantino"
+d:So/Example/BeamEnergy               = 169.23 MeV
+u:So/Example/BeamEnergySpread         = 0.0
+s:So/Example/BeamPositionDistribution = "Gaussian"
+s:So/Example/BeamPositionCutoffShape  = "Ellipse"
+d:So/Example/BeamPositionCutoffX      = 5.0 cm
+d:So/Example/BeamPositionCutoffY      = 5.0 cm
+d:So/Example/BeamPositionSpreadX      = 0.65 cm
+d:So/Example/BeamPositionSpreadY      = 0.65 cm
+s:So/Example/BeamAngularDistribution  = "None"
+i:So/Example/NumberOfHistoriesInRun   = 10
+
+s:Gr/ViewA/Type              = "OpenGL"
+i:Gr/ViewA/WindowSizeX       = 1024
+i:Gr/ViewA/WindowSizeY       = 768
+d:Gr/ViewA/Theta             = 55 deg
+d:Gr/ViewA/Phi               = 20 deg
+s:Gr/ViewA/Projection        = "Perspective"
+d:Gr/ViewA/PerspectiveAngle  = 30 deg
+u:Gr/ViewA/Zoom              = 1.
+b:Gr/ViewA/IncludeStepPoints = "True"
+
+b:Ts/PauseBeforeQuit = "True"

parameters/geometry/dividable.rst

@@ -1,2 +1,23 @@
+.. _geometry_dividable:
+
 Dividable Components
 --------------------
+
+==========  ====================================================================
+TsBox       Box that can optionally have divisions, XBins, YBins, ZBins
+TsCylinder  Cylinder that can optionally have divisions, RBins, PhiBins, ZBins
+TsSphere    Sphere that can optionally have divisions, RBins, PhiBins, ThetaBins
+==========  ====================================================================
+
+.. 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 scoring for details.
+
+You can not 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 the XBins, YBins and ZBins options in scoring). 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::
+
+    sv:Ge/Phantom/VoxelMaterials = 100 "G4_WATER" "G4_WATER" "Air" "Air" "G4_WATER" ...
+
+This means you can create complex phantoms directly from the parameter system.
+VoxelMaterials works for all three kinds of divided components: TsBox, TsCylinder and TsSphere. See the :ref:`example_scoring_voxelmaterials` example.

parameters/geometry/field.rst

@@ -0,0 +1,55 @@
+Electromagnetic Fields
+----------------------
+
+You can assign an electric, magnetic or combined electromagnetic field to any geometry component (with exception of Group components). The field will extend into any child components unless they themselves have their own field.
+
+To assign a field, add the parameter "Field", as in::
+
+    s:Ge/MyComponent/Field = "DipoleMagnet" # "DipoleMagnet", "QuadrupoleMagnet", "MappedMagnet", "UniformElectroMagnetic" or your own definition
+
+For "DipoleMagnet", specify dipole field and strength, as in (see :ref:`example_special_dipole`)::
+
+    u:Ge/MyComponent/MagneticFieldDirectionX = 0.0
+    u:Ge/MyComponent/MagneticFieldDirectionY = 1.0
+    u:Ge/MyComponent/MagneticFieldDirectionZ = 0.0
+    d:Ge/MyComponent/MagneticFieldStrength = 3.0 tesla
+
+For "QuadrupoleMagnet", specify the two components of the gradient, as in (see :ref:`example_special_quadrupole`)::
+
+    d:Ge/MyComponent/MagneticFieldGradientX = 1.0 tesla
+    d:Ge/MyComponent/MagneticFieldGradientY = 1.0 tesla
+
+For "MappedMagnet", specify a field map in the Opera 3D format, as in (see :ref:`example_special_purgingmagnet`)::
+
+    s:Ge/MyComponent/MagneticField3DTable = "PurgMag3D.TABLE"
+
+For "UniformElectroMagnetic", specify electric field and dipole magnetic field, as in (see :ref:`example_special_electromagnet`)::
+
+    u:Ge/MyComponent/ElectricFieldDirectionX = 1.0
+    u:Ge/MyComponent/ElectricFieldDirectionY = 1.0
+    u:Ge/MyComponent/ElectricFieldDirectionZ = 0.0
+    d:Ge/MyComponent/ElectricFieldStrength   = 5000 kV/cm
+    u:Ge/MyComponent/MagneticFieldDirectionX = 0.0
+    u:Ge/MyComponent/MagneticFieldDirectionY = 1.0
+    u:Ge/MyComponent/MagneticFieldDirectionZ = 0.0
+    d:Ge/MyComponent/MagneticFieldStrength   = 5.0 tesla
+
+If you have any other value in Field, TOPAS will look in your extensions to find your own class that defines this field. See the Extensions section at the end of this User Guide for more details.
+
+Field orientation is set by rotating the component.
+
+As with almost any TOPAS parameter, the Electric Field Strength, Dipole Magnet Strength, Quadrupole Magnet Gradient or Mapped Magnetic Field file can be set to change over time by using Time Features such as (see :ref:`example_special_quadanddipole`)::
+
+    d:Ge/MyComponent/MagneticFieldStrength = Tf/BField1st/Value tesla
+
+Fine control of the stepping algorithm can be done by changing the following parameters from their default values::
+
+    s:Ge/MyComponent/FieldStepper = "ClassicalRK4"
+    d:Ge/MyComponent/FieldStepMinimum = 1.0 mm
+    d:Ge/MyComponent/FieldDeltaChord = 1.0e-1 mm
+
+See the `Geant4 Application Developers Guide <https://geant4.web.cern.ch/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/ch04s03.html>`_ for detailed discussion of these options.
+
+Stepper choices for purely magnetic fields are: "ExplicitEuler", "ImplicitEuler", "SimpleRunge", "SimpleHeum", "HelixExplicitEuler", "HelixImplicitEuler", "HelixSimpleRunge", "CashKarpRKF45", "RKG3" and "ClassicalRK4".
+
+Stepper choices for electroMagnetic fields are: "ExplicitEuler", "ImplicitEuler", "SimpleRunge", "SimpleHeum" and "ClassicalRK4".

parameters/geometry/generic.rst

@@ -1,2 +1,68 @@
 Generic Components
 ------------------
+
+You can create a Geometry Component for any of the standard solids defined in the geometry section of the `Geant4 Application Developers Guide <http://geant4.web.cern.ch/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/ch04.html#sect.Geom.Solids>`_.
+
+The :ref:`example_basic_shapesall` example demonstrates how to build each of the solids.
+
+.. image:: generic.png
+
+Below we list the parameters for each Geant4 solid.
+Further details about the parameters, along with helpful diagrams, can be found in the `Geant4 Application Developers Guide <http://geant4.web.cern.ch/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/ch04.html#sect.Geom.Solids>`_.
+All parameters are type ``d:`` unless otherwise noted below.
+Some of these parameters have default values. If so, the default value is shown in parentheses. For most solids, sizes are specified in Half Lengths, denoted with an HL, such as HLX.
+For a few solids, sizes are specified in full Lengths, denoted with just L, such as LX.
+
+
+================  =========================================
+G4Box             use :ref:`TsBox <geometry_dividable>` instead
+G4Tubs            use :ref:`TsCylinder <geometry_dividable>` instead
+G4CutTubs         RMin (0), RMax, HL, SPhi (0), DPhi (360 deg),
+                  LowNorm, HighNorm (these are both ``uv:`` with length of 3)
+G4Cons            RMin1 (0), RMax1, RMin2 (0), RMax2, HL, SPhi (0), DPhi (360 deg)
+G4Para            HLX, HLY, HLZ, Alpha, Theta, Phi
+G4Trd             HLX1, HLX2, HLY1, HLY2, HLZ
+G4RTrap           LZ, LY, LX, LTX
+G4GTrap           HLZ, Theta, Phi, HLY1, HLX1, HLX2, Alp1, HLY2, HLX3, HLX4, Alp2
+G4Sphere          use :ref:`TsSphere <geometry_dividable>` instead
+G4Orb             R
+G4Torus           RMin (0), RMax, RTor, SPhi (0), DPhi (360 deg)
+G4HPolycone       PhiStart, PhiTotal,
+                  Z, RInner, ROuter (these three are ``dv:`` with length of numZPlanes)
+G4SPolycone       PhiStart (0), PhiTotal (360 deg),
+                  R, Z (these two are ``dv:`` with length of numZPlanes)
+G4HPolyhedra      PhiStart (0), PhiTotal (360 deg), NSides (``i:``),
+                  Z, RInner, ROuter (these three are ``dv:`` with length of numZPlanes)
+G4SPolyhedra      PhiStart (0), PhiTotal (360 deg), NSides (``i:``),
+                  R, Z (these two are ``dv:`` with length of numRZ)
+G4EllipticalTube  HLX, HLY, HLZ
+G4Ellipsoid       HLX, HLY, HLZ, ZBottom (-HLZ), ZTop (HLZ)
+G4EllipticalCone  HLX, HLY, ZMax, ZTop (ZMax)
+G4Paraboloid      HLZ, R1, R2
+G4Hype            IR (0), OR, IS (0), OS, HLZ
+G4Tet             Anchor, P2, P3, P4 (these four are ``dv:`` with length of 3)
+G4Extruded        Polygons (``dv:`` with length of 2 x number of polygons),
+                  HLZ, Off1 (``dv:`` with length of 2), Scale1 (``uv:``),
+                  Off2 (``dv:`` with length of 2), Scale2 (``uv:``)
+G4TwistedBox      Twist, HLX, HLY, HLZ
+G4RTwistedTrap    Twist, HLX1, HLX2, HLY, HLZ
+G4GTwistedTrap    Twist, HLZ, Theta, Phi, HLY1, HLX1, HLX2, HLY2, HLX3, HLX4, Alpha
+G4TwistedTrd      HLX1, HLX2, HLY1, HLY2, HLZ, Twist
+G4GenericTrap     HLZ, Vertices (``dv:`` with length of 2 x number of vertices
+G4TwistedTubs     Twist, EndInnerRad, EndOuterRad, HLZ, Phi
+================  =========================================
+
+Some examples of components that can be built just from TsGenericComponents:
+
+* Scatterer
+* Collimator
+* Mirror
+* Water Tank
+* Rando Phantom (as constructive solid geometry rather than DICOM import)
+* Pin Diode Chamber
+* Flat Panel Imaging Device
+* Standard Ion Chamber
+* Segmented Ion Chamber
+* Faraday Cup
+
+We have built some complex things just from combinations of the above Generic Components (such as the STAR radiosurgery beamline at MGH).

parameters/geometry/group.rst

@@ -1,2 +1,33 @@
 Group Component
 ---------------
+
+Creates no actual solid, but still has a placement (Trans and Rot).
+Other components placed within this Group component are affected by this placement just as if the group were an enclosing box component.
+
+The following defines a group component called "MyGroup"::
+
+    s:Ge/MyGroup/Type="Group"
+    s:Ge/MyGroup/Parent = "World"
+    d:Ge/MyGroup/TransX=2. m
+    d:Ge/MyGroup/TransY=2. m
+    d:Ge/MyGroup/TransZ=0. m
+    d:Ge/MyGroup/RotX=0. deg
+    d:Ge/MyGroup/RotY=0. deg
+    d:Ge/MyGroup/RotZ=30. deg
+
+The following example shows how a Group Component, "Jaws", placed in a nozzle, allows one to position two individual movable collimator blocks, "Jaw_Upper" and "Jaw_Lower", without the creation of an extraneous mother volume::
+
+    s:Ge/Jaws/Type = "Group"
+    s:Ge/Jaws/Parent = "Nozzle"
+    d:Ge/Jaws/TransZ = 0. m
+    ...
+    s:Ge/Jaw_Upper/Type = "TsBox"
+    s:Ge/Jaw_Upper/Parent = "Jaws"
+    s:Ge/Jaw_Upper/Material = "Tungsten"
+    d:Ge/Aperture/TransY = 2. cm
+    ...
+    s:Ge/Jaw_Lower/Type = "TsBox"
+    s:Ge/Jaw_Lower/Parent = "Jaws"
+    s:Ge/Jaw_Lower/Material = "Tungsten"
+    d:Ge/Aperture/TransY = -2. cm
+    ...

parameters/geometry/index.rst

@@ -6,9 +6,10 @@ Geometry Components
 .. toctree::
     :maxdepth: 2
 
+    intro
     placement
     parallel_world
-    magnet
+    field
     visualization
     dividable
     generic

parameters/geometry/intro.rst

@@ -0,0 +1,43 @@
+.. _geometry_intro:
+
+Introduction
+------------
+
+All Geometry Components must have at least the following parameters::
+
+    s:Ge/MyComponent/Parent = "World"
+    s:Ge/MyComponent/Type = "TsBox"
+    d:Ge/MyComponent/TransX=0.0 cm # defaults to 0
+    d:Ge/MyComponent/TransY=0.0 cm # defaults to 0
+    d:Ge/MyComponent/TransZ=0.0 cm # defaults to 0
+    d:Ge/MyComponent/RotX=0.0 deg # defaults to 0
+    d:Ge/MyComponent/RotY=0.0 deg # defaults to 0
+    d:Ge/MyComponent/RotZ=0.0 deg # defaults to 0
+
+The Parent, Trans and Rot parameters place a component within its "mother" as described in :ref:`geometry_placement`.
+
+Each Type has its own set of additional required parameters, discussed later when we show the specific component types.
+
+The component name can include the forward slash character ``/``, and this is used in many examples to give some hints about component hierarchy , such as::
+
+    s:Ge/VBox2/Dipole/Parent = "Nozzle"
+
+This bit of hierarchy in the component name, such as ``VBox2/Dipole``, does NOT actually control how the components are assembled. The actual control is from the Parent parameter (discussed below). The forward slash is just another character here. You could just as well use ``VBox2_Dipole`` or ``VBox2Dipole``, as long as you use the same exact string whenever you refer to this component.
+
+Components that are in the real world (as opposed to :ref:`geometry_parallel`) must also have a material::
+
+    s:Ge/MyComponent/Material = "Air"
+
+To deactivate a Component (and all its children), you can either comment out the parameter that sets its Parent, or set its Include parameter to false, as in::
+
+    b:Ge/MyComponent/Include = "False" # defaults to "True"
+
+While it is not forbidden to have unused components (components that are never assigned a parent), this can often be a sign that you have not correctly assigned the parents in your geometry. Accordingly, we check for unused components on startup and given a warning message if any are found. You can disable this warning message by setting::
+
+    Ge/CheckForUnusedComponents = "False"
+
+In some cases you may want to keep unused components around. This can be like keeping extra pieces of unused laboratory equipment handy on a shelf. They will have no effect on your simulation, but remain available to quickly plug in when needed by assigning a parent and setting placement parameters.
+
+Physics control for a specific component is done as part of the ``Ge/`` parameters for that component rather than in the ``Ph/`` parameters, such as::
+
+    d:Ge/MyComponent/MaxStepSize = 1. mm # sets maximum step size used in this component