Menu ▾ ▴

Manual

Benoit CLEMENT

User manual

This page contains the basic user guide.

Scripting language

STARucn relies on specific ascii files to configure the various parts of the software. These scripts use a specific language. A script consists in a series of single line instructions. Empty lines and line beginning with # are ignored.

A script line can either:

  • include another script: include <script>
  • define a constant: define <name> <value>. The value can be any chain of characters, not
    including spaces. Afterwards, the constant can be referred to in the script with @{<name>}. Constants
    can also be nested. In addition two constants are automatically defined : @{this} and
    @{thispath} which refers to the absolute filname and path of the script itself.
  • define a value: <type> <name> <value>. Each value is caracterized by a type, name and
    associated value. Default types are either string, double, int or bool. More complex types can
    be defined by the user in the script/parameters.typ file.
    <usertype>:
    - <type 1> <key 1>
    - <type 2> <key 2>
    ...

A user type consists of several keys of basic types. It is used in the script with the syntax :
<user type> <name> <value key 1> <value key 2> ...

Standard and user defined variables will be accessible from the code.

When entering an integer of double value, one can also include simple arithmetic (+, -, *, /) as well as standard functions with a specific syntax. Available functions are :

Function Syntax Function Syntax Function Syntax
sin(x) S(x) cos(x) C(x) tan(x) T(x)
arcsin(x) AS(x) arccos(x) AC(x) arctan(x) AT(x)
sinh(x) HS(x) cosh(x) HC(x) tanh(x) HT(x)
exp(x) E(x) ln(x) L(x) √x or xy R(x) or P(x,y)

Main script

To run the code, call:
starucn <script>
By default, <script> is scripts/STARucn.par. This script controls the main function of the simulation.
One simple, minimal exemple is given here:

string RunMode Generate
string Geometry @{thispath}/geo/TestBox.geo
string GeoMode Star

int Verbose 0
int NbParticles 1000
int MaxBounce 10000
int GenerationSeed 21235521
int InteractionSeed 76756243
mcsetup Generator VolumeGenerator @{thispath}/generator.par
mcsetup Propagator StepPropagator @{thispath}/propagator.par
mcsetup Interaction NeutronInteraction @{thispath}/interaction.par
mcsetup Output TextOutputInterface @{thispath}/output.par

string DisplayGraphics ogl
string DisplayGeometry Root
int StarGeometryStat   100000

The first mandatory element is the run mode of the simulation:

string RunMode <runmode>

Three basics modes are available:

  • Display: display the geometry. In this mode the only mandatory information is the geometry
    setup.
  • Generate: run the actual full simulation.
  • Test: instantiate geometries and plug-ins but do not run the particle loop.
    A few other modes allows more advanced display and are discussed in section advanced display.

The second mandatory line defines the input files describing the geometry:

string Geometry <geometry file>

The third mandatory line defines the type of geometry to be used in the simulation. STARucn uses to different internal geometry description. The ROOT base geometry (Root) uses the ROOT TGeoVolume classes to define the geometry and benefits of the ROOT display features. Nevertheless it might get wrong when used with complex copmposite volumes. It can only be used with step-by-step propagator. STARucn implements also its own geometry package (Star) that is recommended for simulation with both step-by-step and analytical propagator. The STARucn geometry has only poorer and slower display (see below)

string Geometry <geometry file>

The next nine parameters are only mandatory when running a simulation. They consists in several numeric constants:

  • int Verbose <value> : level of verbosity, from 0 (nothing) to 2.
  • int NbParticles <value> : number of neutrons to generate.
  • int MaxBounce <value> : maximal number of bounces for each neutron. This is numerical
    safety to avoid infinite looping neutrons. One must ensure that number of neutrons reaching this
    limit stays marginal.
  • int GenerationSeed <value> and int InteractionSeed <value> : the seeds of the random
    number generators used for generation and interaction respectively.

as well as the setup of the four plug-ins : Generator, Propagator, Interaction and Output:

mcsetup <plugin type> <class name> <config>

<config> is the name of the script file configuring the plug-in. One can choose to include all the plug-ins configurations in the main script and use the keyword @{this} to design the current script as the plug-in configuration.

Finally the last three parameters specify display options for the Display runmode:

  • string DisplayGraphics <value> : display with native 3D ROOT viewer (Root) or openGL (ogl).
  • string DisplayGeometry <value> : geometry mode used for display (Root or Star).
  • int StarGeometryStat <value> : total number of points in the display. The STARucn geometry display is done by randomly drawing points on the surface of each volume in the geometry.

Geometry

A geometry is a set of volumes, included in larger world box. Each volume is defined from a shape, a
material and a placement matrix. Here is a simple example of an empty cubic box:

int Transparency 70
geometry Geo 200 200 200 Inside|Top|Bottom|Front|Back|Right|Left
material Vacuum 0 0 0 880 2
material BeO 250 0.5 0.001 0 4
matrix M2 0 0 105 0 0 0
matrix M3 0 0 -105 0 0 0
matrix M4 0 105 0 0 0 0
matrix M5 0 -105 0 0 0 0
matrix M6 105 0 0 0 0 0
matrix M7 -105 0 0 0 0 0
matrix Id 0 0 0 0 0 0
volume Top BeO Box 100|100|5 M2 0
volume Bottom BeO Box 100|100|5 M3 0
volume Front BeO Box 100|5|110 M4 0
volume Back BeO Box 100|5|110 M5 0
volume Right BeO Box 5|120|110 M6 0
volume Left BeO Box 5|120|110 M7 0
volume Inside Vacuum Box 100|100|100 Id 0

The overall geometry is defined by:

geometry Geometry <WorldX> <WorldY> <WorldZ> <volumes>

with :

  • <WorldX> <WorldY> <WorldZ> are half length in x, y, and z direction of the world box
  • <volumes> is the list of the volumes constituting the geometry. It consists of the name of the
    volumes separated by a vertical bar,|.

For display purposes one can also specify a fraction of transparency of the volumes for OpenGL, with

int Transparency <value>

Materials

Materials are defined with the command:

material <name> <Vf> <d> <eta> <tau> <color>

where:

  • <name> is the name under which the material will be referred to afterwards,
  • <Vf> is the Fermi potential, in neV,
  • <d> is the fraction of diffuse reflection,
  • <eta> is the absorption coefficient upon reflection, defined as the ration of the imaginary and real
    parts of the Fermi potential, η=W/V,
  • <tau> is the effective lifetime, in seconds, of the neutron in the medium. If this value is zero or
    negative, neutrons will be killed upon entering the material.
  • <color> is the color used for displaying any volume build from this material. The color scheme
    uses the default ROOT color code.

Extra properties can be added, for use in user-defined plugins. For any material one can add a property
as :

materialpropery <materialname>.<propertyname> <value>

Volume and placement

Volumes are build following the volume definition from the ROOT geometry package (see chapter 18 of
the ROOT user’s guide). Distances are given in millimetres and angles in degrees. Shapes are always
centred around the (0,0,0) point and along the vertical z-axis and therefore need a transformation matrix
to place them within the geometry:

volume <name> <material> <type> <def> <matrix> <flag>

where :

  • <name> is the name under which the volume will be referred to afterwards,
  • <material> is the material constituting the volume (if is used in the final geometry),
  • <type> is the type of shape. The available shapes, corresponding to the ROOT shapes classes
    TGeo<type> are : Arb8, Box, Cone, Cons, Ctub, Eltu, Gtra, Hype, Para, Pcon, Pgon, Sphere, Toru, Trap, Trd1, Trd2, Tube and Tubs.
  • <def> is the list of parameters defining the shape. They are given in the same order as in the ROOT
    volume definition, separated by vertical bars |.
  • <matrix> is the placement matrix.
  • <flag> is an additional integer flag that can be used for various purposes.

Alternatively, one can also define composite volumes:

composite <name> <material> <def> <matrix> <flag>

where <def> follow the syntax of composite volumes in the ROOT geometry package. As an example
the external part of the empty box shown previously could have been defined as a single composite
volume instead of six parts :

volume ExternalBox vacuum Box 120|120|120 Id 0
composite Outside BeO ExternalBox:Id-Inside:Id Id 0

Volume placement is done through a combination of a rotation around the (0,0,0) center followed by a
translation of the center:

matrix <name> <Tx> <Ty> <Tz> <A1> <A2> <A3>

with:

  • <name> is the name under which the matrix will be referred to,
  • <Tx> <Ty> <Tz> are the translation along the three axes,
  • <A1> <A2> <A3> are the Euler angles of the rotation. The three angles correspond to:
    • a rotation of <A1> around the Z axis
    • a rotation of <A2> around the X' axis
    • a rotation of <A3> around the Z'' axis

One must be very careful that there is no overlap nor gap between volumes constituting the geometry.
When instantiating the geometry, STARucn checks for volume overlaps (but not gaps) and will print a
warning.

Plugins

Plug-ins are modules that perform specific parts of the simulation. There are four kind of plug-ins:

  • Generator: creates the initial coordinates, direction, velocity and time of the simulated neutron
  • Propagator: handles the propagation of the neutron within the geometry from the current position
    to the next boundary of the active volume.
  • Interaction: handles the interaction of the neutron during its propagation within the volume
    and at the interface.
  • Output: handles the information to be saved at each simulation step and at the end of each
    neutron.

Each plug-in is configured with its own parameter script, with specific keywords.

Generators

Two default generators are available:

  • VolumeGenerator: Neutrons are uniformly distributed within one volume of the geometry with
    a user specified velocity distribution and production rate. Coordinates are provided in mm, time
    in s and velocities in mm/s.
    • string VolumeGenerator.Volume <name>: name of the volume used for generation. The volume must exist in the geometry.
    • double VolumeGenerator.Rate <rate>: production rate, in Hz. If negative, all neutrons
      are produced at time 0.
    • string VolumeGenerator.Mode <mode>: the mode define the way the velocity density
      is provided : XYZ cartesian coordinates (x,y,z), CPV spherical coordinates along the x-axis
      (cosq, j, V), CPVZ spherical coordinates along the z-axis.
    • density VolumeGenerator.Density <X> <fun> <min> <max>: Specify the probability
      density for a given variable <X>=X, Y, Z, C, P, V. The function <fun> is given using ROOT's
      TF1       syntax or by the specific keyword Uniform for uniform density. Than range of the pdf
      is given by <min> and <max>.
  • TextGenerator: Neutrons are read from a simple ascii file where each neutron is described in
    one line of 8 numbers : the position (cartesian vector, in mm), direction (cartesian vector), velocity
    (in mm/s) and time (s). Note that the TextOut put output plug-in can produce such a file.
    • string FileGenerator.InputFile <name>: name of the input file to read.
      +

Propagators

This plug-in computes the time and interaction point where the neutron is going out of its current containing volume. Two techniques are used in STARucn. Both have similar configuration.

  • StepPropagator: The next surface is reached through time steps following is trajectory. When
    the neutron goes out of the volume, the last step is cancelled and the time step is reduced, until the
    distance to surface is smaller than some tolerance.
  • AnalyticPropagator: For the simpler volumes (box, cylinder, tube and torus), the analytic
    solution of the intersection is computed. For more complex volumes, the StepPropagator will be
    automatically used, hence the set-up of this plug-in require also the inputs for the step propagation.

The configuration script must contain the following keywords :
* double StepPropagator.StepSize <length>: initial size (in mm) of the step. If set to -1, an
adaptative step will be used; this is the recommended mode. Fixed step is used if one need to save
the particle trajectory with many points along the trajectory.
+ double StepPropagator.Tolerance <length>: minimal distance from the surface to which we assume the surface has been reached.
+ bool StepPropagator.UseGravity <bool>: switch on (1) or off (0) the gravity.
For the AnalyticPropagator, the keyword are identical, replacing StepPropagator.<X>by AnalyticPropagator.<X>

Interaction

There is only one interaction plugin available, NeutronInteraction, that does not need any external
configuration.

Output

Outputs of the simulation can be produced after each step and at the end of each neutron. Three default
output plug-ins are available:

  • CompleteRootOutputInterface: Information on each neutron are saved into a ROOT tree
    named starucn. This plug-in allow also to save trajectories of some of the generated neutrons.
    • string CompleteRootOutputInterface.OutputFile <file>: name of the output file.
    • int CompleteRootOutputInterface.TrajectoryRecord <nb>: record the trajectory
      every <nb> neutron. If off <nb>=0, this feature is switched off.
    • string CompleteRootOutputInterface.TrajectoryRecordFinalVolume <volumes>:
      extra flag to record only neutrons that end up in one of the listed volumes (volumes name separated
      by vertical bars). If not defined, all recorded trajectories are saved.
  • HistogramOutputInterface: This plug-in fills an histogram recording the number of neutrons
    within a given volume as a function of time.
    • string HistogramOutputInterface.OutputFile <file>: name of the output file.
    • double HistogramOutputInterface.SnapShotTime <time>: duration of each time bin.
    • int HistogramOutputInterface.NbSnapShots <nb>: number of bins.
    • string HistogramOutputInterface.VolumeName <volume>: volume to study. If not
      specified the full geometry is used. It is not possible at the moment to specify several volumes.
  • TextOutputInterface: dump the information for each neutron into a text file for later use.
    Neutron data can be recoreded after a fixed time (Time mode), when they enter a specific volume
    (Volume mode) or after a fixed number of interactions (Interaction mode, mostly used for
    debugging purpose). The generated text file can be used as an input of a second simulation, through
    the TextGenerator plug-in.
    • string TextOutputInterface.OutputFile <file>: name of the output file.
    • bool TextOutputInterface.DoRootTree <bool>: if 1, a ROOT tree will also be created
      mirroring the output file.
    • string TextOutputInterface.StopMode <mode>: saving mode.
    • double TextOutputInterface.StopTime <time>: for Time mode only, specify the time
      in seconds after which data are dumped.
    • string TextOutputInterface.FinalVolumes <volumes>: for Volume mode only, list
      of volumes to reach.
    • int TextOutputInterface.NbInteract <nb>: for Interaction mode only, number of
      allowed interactions.

An additional fourth output plug-in allows to run simultaneously several output plugins: MultiOutputInterface.
The configuration script is as follow :

  • int MultiOutputInterface.NbOutputs <nbmax>: number of output plug-ins to use.
  • mcsetup MultiOutputInterface.Output <n> <class name> <config file>: type and
    configuration file of the <n>-th plug-in (<n>=1 to <nbmax>)

Advanced display

Neutron trajectories

Tracks
This mode allow to display each neutron trajectory within the geometry, if such trajectories have been
previously generated (see CompleteRootOutputInterface for exemple)

To run this mode you need to define the run mode as:
string RunMode Trajectory
add add the following entries in your main script:

  • string Trajectory.InputFile <file>: name of the file containing the trajectories (CompleteRootOutputInterface output)
  • string Trajectory.InputTree <name>: name of the output tree. If you're trajectory are generated with CompleteRootOutputInterface, it should be starucn.

Animations

Anim
STARucn (>v1.2) also allows to generate animated gifs diplaying the time evolution of the neutron within the geometry. Producing an animation is a two step process.

First one must run a simulation producing text snapshot of the system at every time period. This is done by configuring a standard simulation and changing the runmode from Generate to Animate.
The second step consists in creating the image from the output text, using the AnimateGraphics runmode.

Both steps require a few addition to the main script:

  • int Animate.NbFrames <nb>: number of snapshots,
  • double Animate.TimeStep <time>: time between two snapshot,
  • string Animate.BaseName <name>: base name of the produced files, the final gif will be <name>.gif,
  • string Animate.OutputDir <dir>: output directory, as this runmode will produce many output files.

The creation of the final image needs additionnary inputs:

  • string Animate.Display <name>: Display mode to use. You can either use the default ROOT 3D display (<name>=StdROOT) or the naiver OpenLG one (<name>=OpenGL). Note that ROOT implementation of OpenGL is sometimes tricky with composite volumes.
  • double Animate.Timefactor <value>: time dilatation of the animation
  • int Animate.StartFrame <nb>: id of the first snapshot to use
  • `int Animate.StopFrame <nb>
  • double Animate.MarkerSize <value>: size of the markers used to display the neutron. Remove the line to get default values (0.4 for StdROOT and 3 for OpenGL).

Neutrons can be displayed in several colors depending on their position and speed, defining one or several animset:

animset Animate.<name> <condition> <color>: condition is a logical condition on one or more of the seven parameters~: [x], [y], [z] (position), [vx], [vy], [vz] (speed), [v] (norm of the speed) and <color> is the displayed color according to the ROOT color scheme. For exemple, animset Animate.Set1 [v]>3000 2 will display in red neutrons with a speed larger than 3000 mm/s.

Finally serval parameters are used to define the camera orientation. They can be either constant or changing within time. The genereric syntax are:

  • camera Animate.<name> const <value>: specify a constant value.

  • camera Animate.<name> function <string>: specify a time changing value. <string> is the definition of a TF1 ROOT object with x as time variable.
    The keywords <name> for the camera parameters are:

  • PhiAngle: rotation angle in the horizontal plane,

  • ThetaAngle: rotation angle in the vetical plane.

In addition, for the OpenGL display you must specify the field of view angle (OpenGLFov), the dolly position (OpenGLDolly) and the center of the frame (OpenGLCenterX, OpenGLCenterY and OpenGLCenterZ)

Previous: Download and install -- Next: Advanced user/Plugin developper manual

Related

Wiki: Advanced
Wiki: Download
Wiki: Home

Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.