GateActor

From Wiki OpenGATE
Jump to: navigation, search

How to add a new GateActor ?

Basically you only need to provide a single new class that inherit from GateVActor and the corresponding messengers providing the user's macros to use it.

As an example, suppose that you want to create an Actor that store an histogram of the lengths of every track that end within a given volume. Let call it the GateTrackLengthActor.

Step 1

  • Inherit from GateVActor. Some mandatory methods will need to be overwritten (see next steps).
  • Add the following command inside the class:

FCT_FOR_AUTO_CREATOR_ACTOR(GateTrackLengthActor)

It allows Gate to automagically add this actor to the list of user's available actors. When the two files will be put in the source folders (digits_hits/include and digits_hits/src, see here), the actor will be available without any other code modification, just like a plugin but at compile time.

Step 2

  • Implement the Construct() method. You need to decide in which situation your Actor will be activated. It can be at the beginning or the end of each run, or each event, or each track or each step. In this example, this is done with the function EnablePostUserTrackingAction(true) because we only need to store something at the end of each track. Then, initialize your data structure, in this example it is an histogram.
  • Implement the PostUserTrackingAction method to get the current track and store what you want to store.
  • In the BeginOfRunAction, it is generally a good idea to initialize your data structure.
  • Implement ResetData() to empty your data structure.
  • Implement SaveData() to write your data to the disk. In this example, this is a Root file.

Step 3

  • Inspire yourself from the example to see how to add a new macro options and retrieve the user's values. You will need to instanciate your messager in the constructor of the previous GateTrackLengthActor class. When inheriting from the GateActorMessenger class, you automatically get the following macro ('YourActorTypeName' is the name given to FCT_FOR_AUTO_CREATOR_ACTOR):
/gate/actor/addActor               YourActorTypeName xx
/gate/actor/xx/save                <filename>
/gate/actor/xx/attachTo            <volume_name> # <-- this GateVolume must be created before
/gate/actor/xx/saveEveryNSeconds   <n>
/gate/actor/xx/saveEveryNEvents    <n>
  • The 'attachTo' macro is very important: your Actor will only be activated when something appends inside this volume. The callback functions (for example PostUserTrackingAction) gives you a pointer to the object describing this volume.
  • The 'save' macro is used to ask the user the filename for the output results. Writing on disk will be performed at the end of the simulation, or, every N seconds/events if the corresponding macros has been specified by the users. As an Actor developer you do only need to provide the SaveData method described previously.

Step 4

  • Remember that you can use the different available filters(link) to enhance the capabilities of your Actor.
  • Actors are very easy to share with your colleagues: only provide the four files describing your actor (GateMyActor.hh/.cc and GateMyActorMessenger.hh/.cc), put them in the digits_hits folder and compile Gate.

Other information

In the same principle, you can also contribute to Gate by adding a new GateFilter, a new GateSource. TODO

Here is a list of current available Actors. You can add your own on the list, if it is not yet included in the official Gate release, please provide a zip file to download your Actor source code.

Name Description Contacts Date (first version) Already in Gate ? Information
GateDoseActor Store dose and energy in 3D matrix todo 23/2/2010 Yes V6.0 DoseActor
GatePhaseSpaceActor Store all particles going through a volume todo 23/2/2010 Yes V6.0 PhaseSpaceActor
GateSimulationStatisticActor Count the number of run, event, track, step todo 23/2/2010 Yes V6.0

SimulationStatisticActor

GateKillActor Kill particle that pass through the attached volume todo 23/2/2010 Yes V6.0

KillActor

GateProductionAndStoppingActor todo todo 23/2/2010 Yes V6.0

ProductionAndStoppingActor

GateDeltaEnergyActor todo todo 23/2/2010 Yes V6.0

DeltaEnergyActor

GateEnergySpectrumActor todo todo 23/2/2010 Yes V6.0

EnergySpectrumActor

GateSecondaryProductionActor todo todo 23/2/2010 Yes V6.0

SecondaryProductionActor

GateTrackLengthActor todo todo 23/2/2010 Yes V6.0

TrackLengthActor

GateEmCalculatorActor Calculate physical electromagnetic parameters for all materials defined in the simulation todo 23/2/2010 Yes V6.0

EmCalculatorActor class

GateParticleInVolumeActor todo todo 23/2/2010 Yes V6.0

ParticleInVolumeActor

GateQvalueActor todo todo 23/2/2010 Yes V6.0

QvalueActor

GateStopOnScriptActor todo todo 23/2/2010 Yes V6.0

StopOnScriptActor