Advanced

Advanced user manual

This part of the manual describe how advanced users can implement their own plug-ins.
In addition to the information here, we strongly suggest anyone who wants to write a STARucn plug-in to look directly at the source code of the existing ones.

If you have a plug-in that you would like to see integrated in the standard STARucn release, please contact the authors.

• Adding a new class
• Script interface
• Useful classes
  • Particle class
  • Geometry class
• Plug-ins
  • Common methods and members
  • Generator
  • Propagator
  • Interaction
  • Output

Adding a new class

To add a new class into STARucn, you just need to copy the header (.h) file into inc/plugins and the source code (.cpp) in src/plugins.
Plug-ins are classes inheriting from one of the four base classes: BaseGenerator, BasePropagator, BaseInteraction, BaseOutputInterface.

To finalize the integration of your new class, you just need to clean and recompile the code calling make clean all. Your new plug-in can now be used from the main STARucn script.

Script interface

The interface between the code and the parameters file is done through the ParameterReader class.

This class needs as input a file describing the user defined types, void ParameterReader::AddTypeFile(const char*)
and one or several parameter files, using void ParameterReader::AddParameterFile(const char*) or void ParameterReader::AddParameterFile(std::istream&).

Any key of any parameter (int, double, string, bool) can be accessed through the method:

template <class T> T ParameterReader::GetParameter( std::string type, std::string name="", std::string key="")

where:

• type is the parameter type
• name is the parameter name. If not specified, the current parameter will be accessed (see iterators)
• key is the name of the key one want to access. For basic types (int, double, string, bool), this parameter isn't needed

Alternatively, basic types can be accessed by shortcut methods:

int ParameterReader::GetInt(std::string name="")
std::string ParameterReader::GetString(std::string name="")
double ParameterReader::GetDouble(std::string name="")
bool ParameterReader::GetBool(std::string name="")

For advanced options allow to loop over all variables of a given type, using iterators:

• void ParameterReader::itrInit(std::string type): initialize the iterator on a type.
• void ParameterReader::itrNext(std::string type): move to the next variable in this type. It is the variable which will be accessed if no name is pecified in GetParameter.
• bool ParameterReader::itrEnd(std::string type): true only if the end of the list has been reached
• std::string ParameterReader::itrName(std::string type): return the name of the current variable

A typical loop one the type mytype will look like:

ParameterReader pr
...
for(pr.itrInit("mytype"); !pr.itrEnd("mytype"); pr.itrNext("mytype"))
  {
  std::string name = pr.itrName("mytype");
  ...
  }

Finally, two static methods provide additionary tools:

• static void ParameterReader::ReadString(std::vector<std::string>&, std::string, char = '|'): decompose a string into a vector of substrings, eg. "a|b|c" -> {"a","b","c"}. The third parameter defines the substring separator within the initial string.
• static std::string ParameterReader::Substitute(std::string, char, char) : substitute a char by another in a string

Useful classes

Particle class

see header file

Geometry class

see header file

Plug-ins

All STARucn plug-ins inherits from ParameterReader through the Configurable class.
The user type script, '/script/parameters.typ' is common to all the plug-ins and does not need to to be specified.
Each kind of plug-in has a specific set of mandatory method to define.

A STARucn run always defines four plug-ins: a generator, a propagator, an interaction and an output plug-in.
The singleton class CoreProcess is designed to hold pointers to all four plug-ins as well as the defined geometry.
It can be retrieved at any point of the code through the static method CoreProcess* CoreProcess::GetInstance() and pointers can be publicly accessed:

• Geometry: Geometry* CoreProcess::fGeo
• Generator: BaseGenerator* CoreProcess::fGenerator
• Propagator: BasePropagator* CoreProcess::fPropagator
• Interaction: BaseInteraction* CoreProcess::fInteraction
• Output: BaseOutputInterface* CoreProcess::fOutputInterface

All four plug-ins base classes contain directly a pointer to the CoreProcess called fCore.

Common methods and members

All plug-ins must have a constructor that does not take any parameter and will be used to set default values to the class member.

The plug-in configuration is done through the mandatory void Configure(std::string script) method.
The script contains all the information necessary to configure the plug-in. The standard way to do that is to feed the script to the ParameterReader part of the plug-in (using ParameterReader::AddParameterFile(std::string)) but one can use any other mean to extract information the argument string.

Generator

The generator plug-in inherits from the BaseGenerator class.
The only mandatory methods besides the void Configure(std::string script) method is, virtual void Generate(Particle&). It fills the particle initial caracteristics : position, speed, and time. The particle class

In addition a third method can be overriden, virtual bool Good(), that test the status of the generator. The simulation will stop at the generation step if it return false. By default, this method always return true.

A random number generator can be accessed from within the class via the static TRandom3 Gen private member. It is initialized with the int GenerationSeed parameter from the main simulation script (see user manual).

Propagator

The propagator plug-in inherits from the BasePropagator class.
The mandatory virtual methods are:

• virtual bool Propagate(double dt, Particle&): moves the particles over a time dt (in seconds)
• virtual double PropagateToSurface(Particle&, double& Dt, double* Norm, TGeoVolume* &next, TPolyLine3D* u = 0): moves the particle to the next interface of the geometry. At the end of the propagation, the particle must remains inside the initila volume, close to the surface. The return value shoud be the time, in seconds, spent during the step. The other arguments of the method are used as return values:
  • double& Dt: time step (in seconds) needed for the neutron to move to the next volume.
  • double* Norm: array of 3 elements, direction of the normal to surface, going outwards.
  • TGeoVolume* &next: volume on the other side of the surface.
  • TPolyLine3D* u: if provided, the computed step will be added to the neutron trajectory, that may be recoded afterwards.

In addition, subparts of the geometry can be accesses though protected members:

• TObjArray * fNodes: list of geometry nodes,
• int kNodes: number of nodes,
• TGeoVolume* fCurrentVolume: current volume containing the neutron,
• TGeoShape * fCurrentShape: shape associated the the current volume,
• TGeoNode * fCurrentNode: node associated to the current volume.

Interaction

The interaction plug-in inherits from the BaseInteraction class.
The mandatory virtual methods are:

• virtual int VolumeInteraction (Particle&, TGeoVolume* vin, double Dt): decide if and how the particle interated in the volume during its propagatino to the surface. The arguments are the particle, the current volume and the time sptent to reach the surface. The returned integer is a code to forward to the output, if the neutron did not reach the surface, it must be 0, so the SurfaceInteraction method is not called.
• virtual int SurfaceInteraction(Particle&, TGeoVolume* vin, TGeoVolume* vnext, double dt, double* norm, TGeoVolume*& newvol): decide the interaction of the particle at the surface. Arguments are the particle, the current volume, the neighbouring volume, the time step needed to rach the volume, the normal to the surface. The last argument is used as a return value and should contain the new volume containing the neutron after interaction. In the neutron is transmitted to the neighbouring volume, it should be propagated within the new volume using the input time step using BasePropagator::Propagate method.
  The returned integer is a flag describing the neutron status to be forwarded to the output plug-in.

A second random number generator can be accessed from within the class via the static TRandom3 Gen private member. It is initialized with the int InteractionSeed parameter from the main simulation script (see user manual).

Output

The output plug-in inherits from the BaseOutputInterface class.
The mandatory virtual methods are:

• virtual void BeginParticle(Particle&): called after generation and is typically used to save information on the initial state.
• virtual void SaveStep (Particle&, int vol, int sur, TGeoVolume* vin, TGeoVolume* vnext): called after each propagation step. The two integer vol and sur are the return values of the BaseInteraction::VolumeInteraction and BaseInteraction::SurfaceInteraction methods. vin and vnext are pointers to the pre-step current volume and the neighbouring one.
• virtual void EndParticle(Particle&, int vol, int sur, TGeoVolume* previous, TGeoVolume* interface): called at the end of the steps, with the status of the last step.
• virtual void Finalize(): called at the end of the simulation.

---

Previous: User manual -- Next: Benchmarks