While the repeatability requirements of the TOPAS parameter system require that parameter definitions be well specified, there is still a need to define time-dependent behaviors (such as motion, beam current modulation, starting and stopping of scoring activities). The TOPAS Time Feature system allows such time-dependence to be specified in a manner that is both flexible and repeatable.
A Time Feature is a set of parameters that ultimately describes the change of a time feature
Value. You provide parameters that define the time function, such as a linear change over time.
TOPAS automatically creates a
Value parameter for this function (a parameter you don’t define). TOPAS continually updates this
Value parameter to the appropriate value for a given time.
If you’re doing complex things with parameter file chains, you may want to know where in chain this automatically added
Tf/.../Value parameter goes: the answer is that it goes into the same virtual file as the
In addition to specifying the time features, you need to specify the overall time sequence for Sequential Time Mode.
Here is an example, a Time Feature called
ArmRot that describes a constant rotation:
s:Tf/ArmRot/Function = "Linear deg" d:Tf/ArmRot/Rate = 2. deg/ms d:Tf/ArmRot/StartValue = 0.0 deg d:Tf/ArmRot/RepetitionInterval = 50. ms
TOPAS automatically creates another parameter:
and updates this parameter to the appropriate value for a given time.
You can then use this value to affect a component position through a statement such as:
d:Ge/Arm/RotX = 0. deg + Tf/ArmRot/Value
Linear, Sine, Cosine and Sqrt Functions¶
For Dimensioned Double or Unitless values, the
Function can be any one of:
|Linear||StartValue + Rate * Time|
|Sine||Sine ( StartValue + Rate * Time )|
|Cosine||Cosine ( StartValue + Rate * Time )|
|Sqrt||Sqrt ( StartValue + Rate * Time )|
If the value is Dimensioned Double, you must also provide a unit, such as the
s:Tf/ArmRot/Function = "Linear deg"
You must provide appropriate
Rate parameters, such as:
d:Tf/ArmRot/Rate = 2. deg/ms d:Tf/ArmRot/StartValue = 0.0 deg
RepetitionInterval, is the time interval after which the function will reset to the
StartValue. If you do not provide this parameter, the function will not reset.
With a Step function, you can control any type of parameter value. You define a set of times at which to change value, and a value for each of those times. The first value you provide specifies the starting value (the value at time zero).
Here is an example of a Step time feature that controls a String:
s:Tf/ImageName/Function = "Step" dv:Tf/ImageName/Times = 3 10 20 30 ms sv:Tf/ImageName/Values = 3 "lung-1" "lung-2" "lung-3"
- The first value is used for times
Tf/TimelineStartto 10 ms.
Tf/TimelineStartwas not specified, it defaults to 0, so that first value will be used for times 0 to 10 ms.
- The second value is used for times 10 to 20 ms.
- The third value is used for times 20 to 30 ms.
- After 30 ms, the value cycles back to the first value.
Note that the first member of Values is not the time that the first Value should be used.
It is the time that the first Change of value should be made.
The first Value will be used for the time between
Tf/TimelineStart and that first member of Tf/*/Times.
Note that whereas continuous functions (Linear, Sine, Cosine and Sqrt) include a
RepetitionInterval, Step Functions do not. They just cycle back to the first
Value after the last of the
Times is reached.
Here is an example of a Step time feature that controls a Boolean:
s:Tf/ScoringOnOff/Function="Step" dv:Tf/ScoringOnOff/Times =10 10 20 30 40 50 60 70 80 90 100 ms bv:Tf/ScoringOnOff/Values=10 "true" "false" "true" "false" "false" "true" "true" "true" "false" "true"
Tf/.../Timesis always of type
dv:and has unit of time.
Tf/.../Valuesis a vector of whatever type the function controls.
Any individual member of the
Values parameter vector can itself be a parameter, such as:
bv:Tf/ScoringOnOff/Values=4 "true" "false" Some_Other_Boolean_Parameter_Name "false"
Combining Time Features for Complex Behaviors¶
You can add or multiply time feature
Value parameters just as you can add or multiply any other kind of parameter. For example, here is how the number of histories in a run can be controlled by both a beam current and a beam weight:
s:Tf/BeamCurrent/Function = "Step" dv:Tf/BeamCurrent/Times = 1 10 ms iv:Tf/BeamCurrent/Values = 1 10 s:Tf/BeamWeight/Function = "Step" dv:Tf/BeamWeight/Times = 10 1 2 3 4 5 6 7 8 9 10 ms iv:Tf/BeamWeight/Values = 10 1 1 1 2 2 2 2 4 4 4 i:Tf/BCM/Value = Tf/BeamWeight/Value * Tf/BeamCurrent/Value i:So/MySource/NumberOfHistoriesInRun = Tf/BCM/Value
By combining Step time features with other time features, you can control complex sequences. The following from PurgingMagnet_move.txt moves a box first in one direction and then in the other:
s:Tf/BackForward/Function = "Step" dv:Tf/BackForward/Times = 2 100.0 200.0 ms dv:Tf/BackForward/Values = 2 Tf/BackStep/Value Tf/ForwardStep/Value mm s:Tf/BackStep/Function = "Linear mm" d:Tf/BackStep/Rate = 3 mm/ms d:Tf/BackStep/StartValue = 0.0 mm d:Tf/BackStep/RepetitionInterval = 100.0 ms s:Tf/ForwardStep/Function = "Linear mm" d:Tf/ForwardStep/Rate = -3 mm/ms d:Tf/ForwardStep/StartValue = 300.0 mm d:Tf/ForwardStep/RepetitionInterval = 100.0 ms
Some complex examples of time features are in examples/Nozzle. While we have had examples of double scattering and pencil beam scanning for some time, those examples have included proprietary IBA information, so could not be generally shared. The examples found in examples/Nozzle have no vendor confidential information.
|RasterScanningPattern.txt||Time Features for controlling the dipole magnets are implemented. The time varying magnet will scan rectangle fields in a raster pattern.|
|ScanningStationaryTarget.txt||In addition to RasterScanningPattern.txt, a water phantom including a plane target is added.|
|ScanningTargetMovingHorizontal.txt||The perpendicularly moving target is defined. In order to make protons follow the moving target, compensated Time Features for the dipole magnets are implemented. The execution of this file will show the moving target in horizontal direction and the proton beams tracking the moving target.|
|ScanningTargetMovingInDepth.txt||To trace the target moving along with the depth, the changes of proton’s incident energy should be synchronized with the motion.|
|ScanningNozzle.txt||All geometry for the scanning nozzle is defined. The nozzle consists of magnet systems, for example, two quadrupole magnets and two dipole magnets in helium gas filled beam pipe and various monitoring chambers. Magnet fields are set to zero in this parameter file.|
|ScatteringNozzle.txt||All geometry for the scattering nozzle is defined.|
|ScatteringNozzle_run.txt||Range Modulator Wheel rotates over time and scatterers move in and out of the beam.|
Take care when mixing Phase Space Sources with Time Features. While TOPAS can save the current TOPAS time to a phase space file, this time is not automatically applied when reading particles back in from phase space. Thus, if you want to correct replay source particles that were recorded with time features, it is your responsibility to apply the identical time features during the play back simulation. Some additional notes:
- Do not attempt to change the name of the phase space file over time. Save and replay all particles from a single phase space file.
- Do not use Random Time Mode. The randomly generated times during playback will not necessarily match the randomly generated times that were saved to the phase space. Only use Fixed Time Mode or Sequential Time Mode.
A future version of TOPAS will provide more tools to synchronize and check playback time features.