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.
- Inherit from GateVActor. Some mandatory methods will need to be overwritten (see next steps).
- Add the following command inside the class:
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.
- 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
PostUserTrackingActionmethod 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.
ResetData()to empty your data structure.
SaveData()to write your data to the disk. In this example, this is a Root file.
- Now almost all is done. You only need to describe the macro that will be available to the user to control your Actor. Create a new GateTrackLengthActorMessenger class with two files, GateTrackLengthActorMessenger.hh and .cc, and inherit from the GateActorMessenger class.
- 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.
- 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 (
GateMyActorMessenger.hh/.cc), put them in the digits_hits folder and compile Gate.
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|
|GateKillActor||Kill particle that pass through the attached volume||todo||23/2/2010||Yes V6.0|
|GateEmCalculatorActor||Calculate physical electromagnetic parameters for all materials defined in the simulation||todo||23/2/2010||Yes V6.0|