Time Features

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 Tf/.../Function parameter.

In addition to specifying the time features, you need to specify the overall time sequence for Sequential Time Mode.

First example

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:

Function Value(Time)
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 deg in:

s:Tf/ArmRot/Function = "Linear deg"

You must provide appropriate StartValue and Rate parameters, such as:

d:Tf/ArmRot/Rate = 2. deg/ms
d:Tf/ArmRot/StartValue = 0.0 deg

You must also provide a RepetitionInterval, the time interval after which the function will return to the StartValue.

Step Function

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/TimelineStart to 10 ms.
  • If Tf/TimelineStart was 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:

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"

Note that:

  • Tf/.../Times is always of type dv: and has unit of time.
  • Tf/.../Values is 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.

Example Description
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.