Plugin Interface

Plugin API

  • Plugin initialisation

    extern "C" int UserHook_init(const char *vers)

    Initialises the plugin.

    Parameters:

    • vers (const char*) – current version of calling FRED executable

    Returns:

    error code (0=OK)

    Return type:

    int

  • Plugin final call

    extern "C" int UserHook_close()

    The plugin can do postprocessing, bookkeeping, writing a summary report, etc. before the simulation is ended.

    Returns:

    error code (0=OK)

    Return type:

    int

  • Step-by-step control of particle tracking

    These functions allow the user to monitor and/or alter the propagation of a given particle at the level of a single step. They are called just before and just after the internal routines that advance the particle by a step.

    extern "C" int  UserHook_step_bfr(Step *stp)

    Control is given to the plugin before taking the step.

    Parameters:

    • stp (Step*) – current step structure

    Returns:

    APPLY/SKIP

    Return type:

    int

    If APPLY is returned, FRED internal step routines will executed, hence the plugin acts as a diagnostic tool, not changing the particle evolution.

    If instead SKIP is returned, then internal step routines are bypassed, and the plugin is taking complete control of the stepping procedure.

    extern "C" void  UserHook_step_aft(Step *stp)

    Control is given to the plugin after taking the step. The plugin can monitor the stepping procedure and score quantities at the step level.

    Parameters:

    • stp (Step*) – current step structure

    Returns:

    none

  • Plugin runtime and execution options

    extern "C" bool isPluginThreadSafe()

    Tell FRED that the plugin can be executed in parallel on many threads. It is reponsability of the developer to check that data race conditions are not occurring during multi-thread execution. By default, FRED assumes that plugin code is not thread-safe and switches to serial, i.e. single-thread, execution.

    Semaphore control functions are provided for enforcing atomic operations on shared data.

    Returns:

    true if plugin is thread-safe

    Return type:

    bool

  • Boundary crossing

    extern "C" void UserHook_domain_boundary_crossing(Step * stp,bool entering)

    …

    Parameters:

    • stp (Step*) – current step structure

    • entering (bool) –

    Returns:

    none

Getting input parameters for the plugin

Input parameters for the plugin can be written in the main input file (e.g. fred.inp) and queried using plugin parsing routines.

Important

User-defined parameters must be enclosed in a multiline plugin<…plugin> directive as in the following example:

plugin<
    myInt = 374
    myBool = false
    myString = 'profile.dat'
    myFloat = -1.234e-12
    myVec = [1,4,3]
plugin>
bool getBoolParam(const char *pname, bool defVal)
Parameters:

  • pname (const char*) – parameter name

  • defVal (bool) – default value returned if parameter not found in the input file

Returns:

the value of the specified parameter

Return type:

bool

bool verbose = getBoolParam("lPluginVerbose",false);
if (verbose) cout<<"Plugin verbose mode is switched on."<<endl;
int getIntParam(const char *pname, int defVal)
Parameters:

  • pname (const char*) – parameter name

  • defVal (int) – default value returned if parameter not found in the input file

Returns:

the value of the specified parameter

Return type:

int

int nfrac = getIntParam("numFractions",1);
cout<<"Number of planned fractions: "<<nfrac<<endl;
float64 getFloatParam(const char *pname, float64 defVal)
Parameters:

  • pname (const char*) – parameter name

  • defVal (float64) – default value returned if parameter not found in the input file

Returns:

the value of the specified parameter

Return type:

float64

float64 fac = getFloatParam("energyRescaleFactor",1);
cout<<"Energy rescaling factor: "<<fac<<endl;
char *getStringParam(const char *pname, const char *defStr)
Parameters:

  • pname (const char*) – parameter name

  • defStr – default string returned if parameter not found in the input file

Returns:

the string for the specified parameter

Return type:

char *

char * fname = getStringParam("tableFile","");
if(strlen(fname)) cout<<"Path to table file: "<<fname<<endl;
void getVec3dRT(const char *pname,vec3dRT &vec, vec3dRT defVec)
Parameters:

  • pname (const char*) – parameter name

  • vec (vec3dRT &) – vector that will be filled with parsed x,y,z components

  • defVec (vec3dRT) – default vector if parameter not found in the input file

Returns:

none

vec3dRT psource_position;
getVec3dRT("sourcePos", &psource_position, vec3dRT(0,0,5));

cout<<"Point source position: "<<psource_position<<endl;

Step functions

This class of functions can be used to access particle and medium properties via the opaque structure Step passed by FRED to the plugin.

  • Particle properties

    void    getPosition_A(Step *stp, vec3dRT &pos)

    returns in pos the particle position at the beginning of the step

    Parameters:

    • stp (Step*) – current step structure

    • pos (vec3dRT &) –

    Returns:

    none

    void    getPosition_B(Step *stp, vec3dRT &pos)

    returns in pos the particle position at the end of the step

    Parameters:

    • stp (Step*) – current step structure

    • pos (vec3dRT &) –

    Returns:

    none

    void    getDirection_A(Step *stp, vec3dRT &vel)

    returns in vel the particle direction at the beginning of the step

    Parameters:

    • stp (Step*) – current step structure

    • vel (vec3dRT &) –

    Returns:

    none

    void    getDirection_B(Step *stp, vec3dRT &vel)

    returns in vel the particle direction at the end of the step

    Parameters:

    • stp (Step*) – current step structure

    • vel (vec3dRT &) –

    Returns:

    none

    void setDirection_B(Step *stp, vec3dRT vel)

    sets the particle direction to vel at the end point B

    Parameters:

    • stp (Step*) – current step structure

    • vel (vec3dRT) –

    Returns:

    none

    float64 getKineticEnergy_A(Step *stp)
    Parameters:

    • stp (Step*) – current step structure

    Returns:

    particle kinetic energy in MeV at the initial point A

    Return type:

    float64

    float64 getKineticEnergy_B(Step *stp)
    Parameters:

    • stp (Step*) – current step structure

    Returns:

    particle kinetic energy in MeV at the end point B

    Return type:

    float64

    void setKineticEnergy_B(Step *stp, float64 T)
    Parameters:

    • stp (Step*) – current step structure

    • T (float64) – particle kinetic energy in MeV at point B

    Returns:

    none

    float64 getMomentum_A(Step *stp)
    Parameters:

    • stp (Step*) – current step structure

    Returns:

    particle linear momentum in MeV/c at point A

    Return type:

    float64

    float64 getMomentum_B(Step *stp)
    Parameters:

    • stp (Step*) – current step structure

    Returns:

    particle linear momentum in MeV/c at point B

    Return type:

    float64

    void setMomentum_B(Step *stp, float64 p)
    Parameters:

    • stp (Step*) – current step structure

    • p (float64) – particle linear momentum in MeV/c at point B

    Returns:

    none

    int32 getType(Step *stp)
    Parameters:

    • stp (Step*) – current step structure

    Returns:

    particle numerical ID based on PDG 2006 particle codes, e.g. PROTON = 2212

    float32 getParticle_m(Step *stp)
    Parameters:

    • stp (Step*) – current step structure

    Returns:

    particle rest mass (MeV/c^2)

    float32 getParticle_Z(Step *stp)
    Parameters:

    • stp (Step*) – current step structure

    Returns:

    electric charge number or atomic number, i.e. number of protons (P)

    float32 getParticle_A(Step *stp)
    Parameters:

    • stp (Step*) – current step structure

    Returns:

    mass number, i.e. number of nucleons (P+N)

  • Particle family tree

    int32 getUID(Step *stp)
    Parameters:

    • stp (Step*) – current step structure

    Returns:

    particle UID (unique identifier): this number labels each and every particle produced and tracked

    int32 getParentUID(Step *stp)
    Parameters:

    • stp (Step*) – current step structure

    Returns:

    parent UID, i.e. previous generation

    int32 getAncestorUID(Step *stp)
    Parameters:

    • stp (Step*) – current step structure

    Returns:

    ancestor UID, i.e. first generation in the particle family tree

    int32 getGeneration(Step *stp)
    Parameters:

    • stp (Step*) – current step structure

    Returns:

    get particle generation: 1 = primary, 2 = secondary ,…

  • Step properties

    float32 getStepLength(Step *stp)
    Parameters:

    • stp (Step*) – current step structure

    Returns:

    length of trajectory connecting point A and B of the step

    float32 getRangeStep(Step *stp)
    Parameters:

    • stp (Step*) – current step structure

    Returns:

    column density (g/cm^2) corresponding to current step

    float32 getMassDensity(Step *stp)
    Parameters:

    • stp (Step*) – current step structure

    Returns:

    local mass density of the material in which current step is taken

  • Random generators attached to current particle

    to be used if you want a simulation to be reproducible by setting randSeedRoot in the input file

    float32 getRandUnif(Step *stp)
    Parameters:

    • stp (Step*) – current step structure

    Returns:

    random floating point number uniformly distributed in [0,1)

    float32 getRandGauss(Step *stp)
    Parameters:

    • stp (Step*) – current step structure

    Returns:

    random floating point number sampled from a normal distribution (i.e. average=0, stdev=1)

  • Energy loss properties of current step

    float32 get_dEds(Step *stp, float32 T)
    Parameters:

    • stp (Step*) – current step structure

    • T (float32) – particle kinetic energy in MeV

    Returns:

    mass stopping power for the particle with kinetic energy T in the current material

    float32 get_TrackingCutoffEnergy(Step *stp)

    New in version 3.0.25.

    Parameters:

    • stp (Step*) – current step structure

    Returns:

    kinetic cut-off energy for particle transport in the current material

Material properties

The mean properties of a material are queried using:

int getImat_A(Step *stp)
Parameters:

  • stp (Step*) – current step structure

Returns:

get material index at initial point A

Return type:

int32

int getImat_B(Step *stp)
Parameters:

  • stp (Step*) – current step structure

Returns:

get material index at initial point B

Return type:

int32

string getMatID(int imat)

New in version 3.0.24.

Parameters:

  • imat – material index

Returns:

material ID, i.e. a string representing its name

Return type:

string

float32 getMat_Zmean(int imat)
Parameters:

  • imat – material index

Returns:

average atomic number <Z> of the material

Return type:

float32

float32 getMat_Amean(int imat)
Parameters:

  • imat – material index

Returns:

average mass number <A> (g/mol) of the material

Return type:

float32

float32 getMat_RelStopPow(int imat)
Parameters:

  • imat – material index

Returns:

relative stopping power of the material

Return type:

float32

float32 getMat_Lrad(int imat)
Parameters:

  • imat – material index

Returns:

radiation length (g/cm^2) of the material

Return type:

float32

int16 getHU(int imat)
Parameters:

  • imat – material index

  • iel (int32) – index of element in the material

Returns:

HU value of the material (if not defined, returns -10000)

Return type:

int16

Elemental composition

Query functions for elemental composition:

int32 getMatNumElements(int imat)
Parameters:

  • imat – material index

Returns:

number of elements in the material

Return type:

int32

single elements in the material are indexed from 0

float32 getMat_Z(int imat, int32 iel)
Parameters:

  • imat – material index

  • iel (int32) – index of element in the material

Returns:

num of protons in element nucleus (P)

Return type:

float32

float32 getMat_A(int imat, int32 iel)
Parameters:

  • imat – material index

  • iel (int32) – index of element in the material

Returns:

num of nucleons in element nucleus (N+P)

Return type:

float32

float32 getMat_m(int imat, int32 iel)
Parameters:

  • imat – material index

  • iel (int32) – index of element in the material

Returns:

mass of element nucleus (MeV/c^2)

Return type:

float32

float32 getMat_w(int imat, int32 iel)
Parameters:

  • imat – material index

  • iel (int32) – index of element in the material

Returns:

weight fraction of element in the material

Return type:

float32

float32 getMat_x(int imat, int32 iel)
Parameters:

  • imat – material index

  • iel (int32) – index of element in the material

Returns:

number fraction of element in the material

Return type:

float32

Example:

int imat = getImat_A(stp);
int nel = getMatNumElements(imat);
cout<<endl<<"Number of elements in the material:  "<<nel<<endl;
for(int iel=0;iel<nel;iel++)
    cout<<iel<<' '<<getMat_Z(imat,iel)<<' '<<getMat_A(imat,iel)<<' '<<getMat_w(imat,iel)<<' '<<getMat_x(imat,iel)<<endl;
cout<<endl;

Environment subroutines

string getInputDirectory()
Returns:

path to the current input directory

Return type:

string

string getOutputDirectory()
Returns:

path to the current output directory

Return type:

string

string getPluginDirectory()
Returns:

path to the directory containing the plugin

Return type:

string