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.
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.
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 typename
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 neededAlternatively, 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 reachedstd::string ParameterReader::itrName(std::string type)
: return the name of the current variableA 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 stringParticle
classsee header file
Geometry
classsee header file
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* CoreProcess::fGeo
BaseGenerator* CoreProcess::fGenerator
BasePropagator* CoreProcess::fPropagator
BaseInteraction* CoreProcess::fInteraction
BaseOutputInterface* CoreProcess::fOutputInterface
All four plug-ins base classes contain directly a pointer to the CoreProcess
called fCore
.
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.
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).
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.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.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).
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