This Chapter is intended to provide a minimal set of instructions to install
and run FLUKA for a beginner user, going through the different steps required
to run a simple example. References to the relevant chapters of the manual are
given to help the user in finding more detailed information on the different
topics. After describing the installation procedure, instructions are given on
how to build the input file for a simple case. Instructions for running and
accessing the results are also reported. As a further step, the user is
addressed to Chapter 13} to learn how to tailor FLUKA to specific needs by
means of user routines.
Installing FLUKA
----------------
A full description of the installation procedure is given in Chapter 3}.
The FLUKA package for LINUX and UNIX platforms is distributed as a tar file
which can be downloaded from the FLUKA Website http://www.fluka.org or other
authorised mirror site.
The user must prepare a directory where the tar file has to be expanded.
Let us suppose that the gzipped tar file, called fluka2006.1-linuxAA.tar.gz,
has been downloaded in a given directory and that it must be expanded in a new
subdirectory called fluka (but any other name is valid). A possible way to
proceed is the following:
mkdir fluka
cd fluka
tar zxvf ../fluka2006.1-linuxAA.tar.gz
An alterantive way to expand the tar file is:
gunzip -dc ../fluka2006.1-linuxAA.tar.gz | tar xvf
At this stage, the user must define an environmental variable FLUPRO pointing
to the directory where the distribution tar file has been opened.
This directory is made available as follows:
Bash shell: use the export command C or tc shell: use the setenv command
... ...
cd fluka cd fluka
export FLUPRO=$PWD setenv FLUPRO $PWD
Of course the definition of FLUPRO can be placed once for ever in the login
script.
The FLUKA libraries and most data files will be located in $FLUPRO, the INCLUDE
files in $FLUPRO/flukapro/, the default user routines in $FLUPRO/usermvax/,
compilation and linking scripts (as well as several postprocessing programs to
analyse user scores) in $FLUPRO/flutil/. See details in Chapter 3}.
The user must produce the default FLUKA executable, to be located in the $FLUPRO
directory, by means of the $FLUPRO/flutil/lfluka script:
...
cd $FLUPRO
$FLUPRO/flutil/lfluka -m fluka
The default executable is called flukahp.
Building a FLUKA input
----------------------
Generalities about FLUKA input
------------------------------
FLUKA reads user input from an ASCII "standard input" file with extension .inp.
The general characteristics and rules of FLUKA input are described in
Chapter 6}.
The input consists of a variable number of "commands" (called also "options"),
each consisting of one or more "lines" (called also "cards" for historical
reasons).
Apart from FLUKA commands, the input file may contain also the description of
the geometry of the simulated set-up. Also this description is provided by
means of specific geometry "command cards" in a special format described in
Chapter 6}.
The geometry description can, on request, be kept in a separate ASCII file:
this feature is especially useful when the same geometry is used in several
different inputs, not only to save space but because modifications can be made
in one single place.
The typical structure of a FLUKA input file is the following:
- Titles and comments for documentation purposes (optional, but recommended)
- Description of the problem geometry (solid bodies and surfaces, combined to
partition space into regions) (mandatory)
- Definition of the materials (mandatory unless pre-defined materials are used)
- Material assignments (correspondence material-region, mandatory)
- Definition of the particle source (mandatory)
- Definition of the requested "detectors". Each of these is a phase space
domain (region of space, particle direction and energy) where the user wants
to calculate the expectation value of a physical quantity such as dose,
fluence, etc. Various kinds of detectors are available, corresponding to
different quantities and to different algorithms used to estimate them
("estimators"). Detectors are optional, but one at least is expected, at
least in the production phase
- Definition of biasing schemes (optional)
- Definition of problem settings such as energy cut-offs, step size, physical
effects not simulated by default, particles not to be transported, etc.
(optional)
- Initialisation of the random number sequence (mandatory if an estimation of
the statistical error is desired)
- Starting signal and number of requested histories (mandatory)
In addition, special commands are available in FLUKA for more advanced problems
involving magnetic fields, time-dependent calculations, writing of history
files (so-called "collision tapes"), transport of optical photons,
event-by-event scoring, calling user-written routines, etc. These options are
expected to be requested only by users having some previous experience with the
more common commands: therefore they will be mostly ignored in this beginner's
guide.
Let's first recall the general structure of the FLUKA command lines (cards).
The geometry commands will be reviewed later. Each card contains:
- one keyword,
- six floating point values (called WHATs),
- one character string (called SDUM)
Not necessarily all WHATs and SDUMs are used. In some cases, a command
line can be followed by a line of text (for instance a filename path or a
title). Any line having an asterisk (*) in the first position is treated as a
comment. All lines (commands, text strings and comments) are echoed on
the standard output (the file with extension .out). In case of problems, it is
a good idea to check how every line has been printed in the standard output.
Often, output reveals typing or format errors by showing how the program has
misinterpreted them.
In addition to the simple echo, an "interpreted" feedback to all commands is
provided in the next section of the standard output. Checking this part of the
output is also very useful, because it helps making sure that the user's
intentions have been expressed correctly and understood by the code. See
Chapter 9} on FLUKA output for a detailed description.
If a line contains an exclamation mark (!) all following characters are
replaced by blanks. This feature can be used for short in-line comments which
will not be echoed in output.
The order of input commands is generally free, with only a few exceptions
reported in Chapter 7}. Therefore, the order suggested in the following should
not be considered as mandatory, but only one of the possible ways to write
FLUKA input.
Input alignment
---------------
Be careful to properly align keywords and numbers. Format is not free, unless a
command is issued at the beginning of input: see option GLOBAL or FREE.
Even in the free format for the input file, the part of the input describing the
geometry can still be written in fixed format (which is different from the
general FLUKA input format, see Chap. 6}). There is the possibility of having
free format also for the geometry part: this can also be activated using the
GLOBAL command.
In fixed format, in order to ensure proper alignment, a comment line showing a
scale can be used anywhere in the input file, for instance:
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
In numerical fields, blanks are treated as zero. Therefore, numbers written
with a decimal period and without an exponent (e.g. 1.2345) can be placed
anywhere inside their respective format fields, For instance, the following two
input lines are equally acceptable:
BEAM 200. 0.2 1.5 1.2 0.7 1.0 PROTON
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
BEAM 200. 0.2 1.5 1.2 0.7 1.0PROTON
If a number is written in exponential notation (e.g. 2.3E5) or in integer form
(without decimal point), it must be aligned to the right of the field.
Depending on the platform and the compiler, sometimes the number is correctly
interpreted even if the alignment rule is not respected. However THIS IS NOT
GUARANTEED AND THE RIGHT ALIGNMENT RULE SHOULD ALWAYS BE FOLLOWED.
For instance in:
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
BEAM 2.E2 0.2 1.5 1.2 0.7 1. PROTON
the first value might be interpreted as 2.E200. Another case is the following:
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
BEAM 200. 0.2 1.5 1.2 0.7 1 PROTON
here the last numerical field would be interpreted as 1000000000. To avoid
mistakes due to this kind of input errors, the present FLUKA versions now
recognise such potential problems and the program is forced to stop. At the
same time a message is printed on the standard output file, as shown here for
the above example:
*** The 6th field 1 of the following input card ***
BEAM 200. 0.2 1.5 1.2 0.7 1 PROTON
*** does not contain a valid formatted fortran real number!!! ***
*** It is ambiguous and it could be read differently on different compilers ***
*** depending how strictly the blank=0 formatted input rule is implemented ***
Keywords (character strings such as BEAM and PROTON) must be aligned to the
left of their field and must be in upper case. An exception is the continuation
character & used in some commands, which can be placed anywhere within its
10-characters field.
A simple example
----------------
Let us now consider a simple starting application. We want to calculate the
charged pion fluence produced by a monochromatic proton beam of momentum
50 GeV/c impinging on a 5 cm thick beryllium target of simple shape: a small
parallelepiped (20 cm x 20 cm x 5 cm). A further simplification will be made
for the purpose of this example, neglecting all the surrounding environment and
substituting it with ideal vacuum.
We will guide the reader through the different parts of a possible input file
suited for this application. The information which follows is meant to serve as
a guide, but does not cover all the important points. It is recommended that
for each option card selected, the user read carefully the relevant manual
entry, and especially the explanatory notes.
The title
---------
Typically, an input file begins with a TITLE card followed by one line of text
describing the problem, or identifying that particular run, or providing some
kind of generic information. In our case, for example:
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
TITLE
Charged pion fluence inside and around a proton-irradiated Be target
Further information can be provided by comment cards, but the title, because it
is printed at the top of the standard output and of each estimator output, is a
useful reminder of what the corresponding file is about. In addition, the title
is printed in all separate output files (error file, estimator files etc.)
together with the date and time of the FLUKA run, allowing to keep track of
their origin.
Commands such as GLOBAL and DEFAULTS, if needed, must immediately follow. Since
this is intended as a beginner's guide, these can be ignored here (for most
common problems the defaults provided are sufficient). Let us recall that
without specifying a DEFAULT value, the NEW-DEFAults set of FLUKA parameters is
loaded.
Definition of the primary particles
-----------------------------------
All "events" or "histories" are initiated by primary particles, which in the
simplest case are monoenergetic, monodirectional and start from a single point
in space (pencil beam). The particle energy (or momentum) is defined by option
BEAM, and their starting position and direction by option BEAMPOSit. These two
commands can be used also to define particle beams having a simple angular or
momentum distribution (Gaussian or rectangular), or a simple transverse profile
(Gaussian, rectangular or annular). Isotropic or semi-isotropic angular
emission can be described as a special case of an angular rectangular
distribution.
For particle sources with more complex distributions in energy, space and
direction, the user must write, compile and link a special routine (SOURCE),
following the instructions given in Chap. 13}, and input a card SOURCE.
A summary of the input data concerning primary particles is printed in the
standard output under the title "Beam properties".
The beam definition for our example can be the following (monochromatic,
monodirectional proton beam of momentum 50 GeV/c):
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
BEAM 50.E+00 PROTON
In our example, the beam starting point is given by:
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
BEAMPOS 0.0 0.0 -50.0
In the cartesian geometry used by FLUKA, the previous card means that the beam
is injected at x, y, z cordinates: 0, 0, -50 cm and is directed along the
positive z axis. Of course, the choice of the point of injection, the
direction, etc., must be coherent with the geometrical description of the
set-up, as discussed in the following section.
The geometry
------------
The input for the Combinatorial Geometry (bodies, regions and optional region
volumes) must be immediately preceded by a GEOBEGIN card and immediately
followed by a GEOEND card. These two cards follow the normal FLUKA format. It
is recalled that the format for the geometry has its own special rules,
described in Chap. 8}.
Comment lines in the geometry input have an asterisk in first position as in
the rest of FLUKA input (but on-line comments are not allowed). Body numerical
data can be written in two different formats, a "short" one (field length 10)
and a "long" one (field length 22). The latter one is to be preferred when
higher precision is needed, for instance when using bodies such as truncated
cones, cylinders or planes not aligned with axes. It must be realised that
using too few decimals can cause geometry errors when bodies are combined into
regions (portions of space not defined or doubly defined).
The whole geometry must be surrounded by a region of "blackhole" limited by a
closed body (generally an RPP parallelepiped). It is often a good idea to make
this body much larger than the minimum required size: this makes easier to
introduce possible future extensions. In some cases, as in our basic example,
it is also useful to surround the actual geometry by a region of ideal vacuum,
and to have the blackhole region surrounding the vacuum. This can be useful,
for instance, in order to start the trajectory of the primary particles
outside the physical geometry (a particle may not be started on a boundary).
Both the body input section and the region input section must be ended with an
END card. Optionally, region volumes can be input between the region END card
and the GEOEND card (this option can be requested by setting a special flag in
the Geometry title card, see Chap. 8}). The only effect of specifying region
volumes is to normalise per cm3 the quantities calculated via the SCORE option
(see below): for other estimators requiring volume normalisation the volume is
input as part of the detector definition (USRTRACK, USRCOLL, USRYIELD), or is
calculated directly by the program (USRBIN).
The GEOEND card indicates the end of the geometry description, but can also be
used to invoke the geometry debugger.
The geometry output is an expanded echo of the corresponding input, containing
information also on memory allocation and on the structure of composite regions
made of several sub-regions by means of the OR operator.
A possible realisation of the geometry set up for our basic example can be seen
in the Figure below:
z ^ -----------------------------------
| / ______________________ /|
| / / / / |
| ----------------------------------- |
| | / vacuum (region 2) / | | |
| | ------------------------ | | |
| | | ___________ | | | |
| | | / Be /| | | | |
| | | ------------ | | | | |
| | | | (reg. 4) |/| | | | |
| | | ----------- | | | | |
| | | | (reg. 3) |/ | | | |
+-- | | ------------ | | | |-------->
/ | | ^ | / | | y
/ | | | Beam |/ | |
/ | ------------------------ | /
/ | Blackhole (region 1) |/
/ -----------------------------------
x
Only four bodies are used here: an RPP body (Rectangular Parallelepiped, body
no. 3) to define a volume which will be the Be target region, inside another
larger RPP body (no. 2), which will be filled with ideal vacuum and in turn is
contained inside another larger RPP body (no. 1), to define the blackhole
region. The fourth body, an XYP half-space (defined by a plane perpendicular to
the z axis), will be used to divide the target into 2 different regions: the
upstream half will be defined as the portion of body 3 contained inside the
half-space, and the downstream half as the portion outside it. Therefore,
region "3" (the upstream half of the target) is the part of body no. 3 which is
also inside body 4, while region "4" (downstream half of the target) is the
part of body no. 3 which is not inside body 4. Region "2" (the vacuum around
the target) is defined as the inside of body no. 2 from which body no. 3 is
subtracted. Region "1" is simply the interior of body no. 1 from which body
no. 2 is subtracted.
The beam starting point has been chosen so that it is in the vacuum, outside
the target region.
The geometry part of the input file can then be written as:
GEOBEGIN COMBINAT
A simple Be target inside vacuum
RPP 1-5000000.0+5000000.0-5000000.0+5000000.0-5000000.0+5000000.0
RPP 2-1000000.0+1000000.0-1000000.0+1000000.0 -100.0+1000000.0
RPP 3 -10.0 +10.0 -10.0 +10.0 0.0 +5.0
* plane to separate the upstream and downstream part of the target
XYP 4 2.5
END
* black hole
BH1 5 +1 -2
* vacuum around
VA2 5 +2 -3
* Be target 1st half
BE3 5 +3 +4
* Be target 2nd half
BE4 5 +3 -4
END
GEOEND
Materials
---------
Each geometry region is supposed to be filled with a homogeneous material, or
with vacuum, or with "blackhole". The latter is a fictitious material used to
terminate particle trajectories: any particle is discarded when reaching a
blackhole boundary. Materials can be simple elements or compounds, where an
element can have either natural composition or consist of a single nuclide,
and compound indicates a chemical compound or a mixture or an alloy (or an
isotopic mixture) of known composition.
An element can be either predefined (see list in 5}) or defined by a MATERIAL
card giving its atomic number, atomic mass, density, name and a material
identification number > 2. The material number can be chosen by the user, with
the restriction that all lower numbers must also be defined (but not
necessarily used).
Number 1 is reserved for blackhole and 2 for ideal vacuum. There are 25
predefined materials; but each of the numbers from 3 to 25 can be redefined
freely, overriding the default definition.
Materials can also be defined with higher numbers, provided no gaps are left in
the numbering sequence. For instance a material cannot be defined to have
number 28 unless also 26 and 27 have been defined.
A compound is defined by a MATERIAL card plus as many COMPOUND cards as needed
to describe its composition. The MATERIAL card used to define a compound
carries only the compound name, density and material number (atomic number and
atomic mass having no meaning in this case).
Materials predefined or defined in the standard input are referred to as "FLUKA
materials", to distinguish them from materials available in the low-energy
neutron cross section library (called "low-energy cross-section materials).
When transport of low-energy neutrons (E < 19.6 MeV) is requested (explicitly
or by the chosen defaults), a correspondence is needed between each elemental
(i.e. not compound) "FLUKA material" and one of the "low-energy cross-section
materials" available in the FLUKA low-energy neutron library. The default
correspondence is set by the name: and if more than one material with that name
exist in the neutron library, the first in the list with that name (see
Chap. 10}) is assumed by default. The default can be changed using option
LOW-MAT.
In the case of our example, only Beryllium is necessary, apart from blackhole
and vacuum. In principle, since Beryllium is one of the pre-defined FLUKA
materials, this part could even be omitted. However, for pedagogical reasons
the following card is proposed, where index 5 is assigned to the target
material:
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
MATERIAL 4.0 9.0122 1.848 5.0 BERYLLIU
Notice that the chosen name is BERYLLIU and not BERYLLIUM, in order to match
the name in the list of "low-energy cross-section materials" for low
energy neutrons (see Chap. 10}), where material names have a maximum length of
8 characters.
The standard output concerning materials is very extended. First a list of
multiple scattering parameters (printed by subroutine MULMIX) is reported for
each material requested. This is mostly of scarce interest for the normal user,
except for a table giving for each requested material the proportion of
components, both by number of atoms (normalised to 1) and by weight (normalised
to material density). The same information is repeated later on in another
table entitled "Material compositions".
If low-energy neutron transport has been requested (explicitly or by a chosen
default), the following section reports the relevant material information: in
particular, a table entitled "Fluka to low en. xsec material correspondence"
specifying which material in the neutron cross section library has been mapped
to each input material. Note that a much more detailed cross section
information can be obtained by setting a printing flag (WHAT(4)) in the
LOW-NEUT command.
The Table "Material compositions" contains information about the requested
materials, those pre-defined by default and the elements used to define
compounds. In addition to effective atomic and mass number, density and
composition, the table shows the value of some typical quantities: inelastic
and elastic scattering length for the beam particles (not valid for electron
and photon beams), radiation length and inelastic scattering length for 19.6
MeV neutrons.
The next table contains material data related to stopping power (average
excitation energy, density effect parameters, and pressure in the case of
gases) plus information about the implementation of various physical effetcs
and the corresponding thresholds and tabulations.
The last material table is printed just before the beginning of the history
calculations, and concerns the "Correspondence of regions and EMF-FLUKA
material numbers and names".
Assigning materials to regions
------------------------------
A material must be associated to each of the geometry regions, except to those
defined as blackhole. This is done in a very straightforward way by command
ASSIGNMAt. Assigning explicitly blackhole to a region is allowed, but is not
necessary (except for region 2) because a region is blackhole by default unless
another material has been associated to it. (Region 2, if not assigned a
material, is COPPER by default).
The table entitled "Regions: materials and fields", in the standard output, can
be consulted to check that material assignment has been done as desired.
For the present example the assignment could be:
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
* Be target, 1st and 2nd half
ASSIGNMAT 5.0 3.0 4.0
* External Black Hole
ASSIGNMAT 1.0 1.0
* Vacuum
ASSIGNMAT 2.0 2.0
Production thresholds
---------------------
The implicit NEW-DEFA default setting adopted in the example, sets, among other
things, the production and transport threshold of heavy particles to 10 MeV.
Production thresholds for e+e- and photons must be explicitly set using the
EMFCUT command for all materials in the problem. Let us choose also in this
case a 10 MeV threshold for the single material of the example (previously
marked with material index 5). Following the instructions about the EMFCUT
option, the card can be written as:
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
* e+e- and gamma production threshold set at 10 MeV
EMFCUT -0.010 0.010 1.0 5.0 PROD-CUT
where the first numerical field is the threshold for e+e- (the minus sign
meaning kinetic energy) and the second is for photons. The material number is
given in the fourth numerical field. For details on all other parameters, and
for other possibilities (for example how to introduce a transport cut-off
different from production threshold) the user should accurately consult the
Notes to EMFCUT.
Production and transport threshold for all other particles can be overwritten
using the PART-THR command.
Estimators and Detectors
------------------------
Even though, for setting-up purposes, it is conceivable that no estimator be
requested in a preliminary run, in most cases FLUKA is used to predict the
expectation value of one or more quantities, as determined by the radiation
field and by the material geometry described by the user: for such a task
several different estimators are available. The quantities which are most
commonly scored are dose and fluence, but others are available. Dose equivalent
is generally calculated from differential fluence using conversion
coefficients.
The simplest estimator available to the user is a historical vestige, survived
from the "ancient" FLUKA (pre-1988) where the only possible output quantities
were energy deposition and star density in regions. It is invoked by option
SCORE, requesting evaluation of one to four different quantities. These can be
different forms of energy density (proportional to dose), or of star density
(approximately proportional to fluence of selected high-energy hadrons).
For this estimator, the detectors are pre-determined: the selected quantities
are reported for each region of the geometry. The corresponding results,
printed in the main output immediately after the last history has been
completed, are presented in 6 columns as follows:
region region first second third fourth
number volume quantity quantity quantity quantity
1 ...... ........ ........ ........ ........
2 ...... ........ ........ ........ ........
etc.
on a line for each geometry region. The region volumes (in cm3) have the value
1.0, or values optionally supplied by the user at the end of the geometry
description. All other columns are normalised per region volume and per primary
particle.
The input could be as follows:
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
* score in each region energy deposition and stars produced by primaries
SCORE 208.0 210.0
Other estimators are more flexible: the corresponding detectors can be
requested practically in any number, can be written as unformatted or text
files, and in most cases can provide differential distributions with respect to
one or more variables. On the other hand, their output is presented in a very
compact array form and must generally be post-processed by the user. For this
purpose several utility programs are available: but output in text format can
even be exported to a spreadsheet for post-processing.
USRBDX is the command required to define a detector for the boundary-crossing
estimator. It calculates fluence or current, mono- or bi-directional,
differential in energy and angle on any boundary between two selected regions.
The area normalisation needed to obtain a current in particles per cm2 is
performed using an area value input by the user: if none is given, the area is
assumed to be = 1 cm2 and the option amounts simply to counting the total number
of particles crossing the boundary. Similarly if fluence is scored, but in this
case each particle is weighted with the secant of the angle between the
particle trajectory and the normal to the boundary surface at the crossing
point.
This is one of the estimators proposed for our example. We will request two
boundary crossing detectors, one to estimate fluence and one for current, of
particles crossing the boundary which separates the upstream and the downstream
half of the target.
The following group of cards can be inserted:
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
* Boundary crossing fluence in the middle of the target (log intervals, one-way)
USRBDX 99.0 209.0 -47.0 3.0 4.0 400. piFluenUD
USRBDX +50.0 +50.0 0.0 10.0 &
*
* Boundary crossing current in the middle of the target (log intervals, one-way)
USRBDX -1.0 209.0 -47.0 3.0 4.0 400. piCurrUD
USRBDX +50.00 +50.0 0.0 10.0 &
According to the instructions reported in the description of the USRBDX
command, it can be seen that the combined fluence of pi+ and pi- is requested
only when particles exit region "3" (the upstream half of the target) to enter
into region "4" (the downstream half). There is no interest in the reverse,
therefore "one-way scoring" is selected. The scoring of the first detector
will be inverse cosine-weighted, in order to define correctly the fluence.
Results will be written unformatted on unit 47 for both quantities (so there
will be two "Detectors" on the same output unit, but this is not mandatory).
The energy distribution is going to be binned in 50 logarithmic intervals, from
0.001 GeV (the default minimum) up to 50 GeV. The angular distribution will be
binned into 10 linear solid angle intervals from 0. to 2pi (having chosen the
one-way estimator). The results will be normalised dividing by the area of the
boundary (separation surface between the two regions, in this case the
transverse section of the target), and will provide a double-differential
fluence or current averaged over that surface in cm-2 GeV-1 sr-1.
Other fluence scoring options, based respectively on a track-length and on a
collision estimator, are USRTRACK and USRCOLL which request the estimation of
volume-averaged fluence (differential in energy) for any type of particle or
family of particles in any selected region. The volume normalisation needed to
obtain the fluence as track-length density or collision density is performed
using a volume value input by the user: if none is given, the volume is assumed
to be = 1 cm3 and the result will be respectively the total track-length in
that region, or the total number of collisions (weighted with the mean free
path at each collision point).
Note that if additional normalisation factors are desired (e.g. beam power)
this can be achieved by giving in input the "volume" or "area" value
multiplied or divided by those factors. Options USRTRACK, USRCOLL and
USRBDX can also calculate energy fluence, if the "particle" type is set
= 208 (energy) or 211 (electron and photon energy).
In our example, we are requesting two track-length detectors, to get the
average fluence in the upstream half and in the downstream half of the target,
respectively.
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
* Tracklength fluence inside the target, Upstream part and Downstream part
* Logarithmic energy intervals
USRTRACK -1.0 209.0 -48.0 3.0 1000.0 20. piFluenU
USRTRACK 50.0 0.001 &
USRTRACK -1.0 209.0 -49.0 4.0 1000.0 20. piFluenD
USRTRACK 50.0 0.001 &
The volume input is 20 x 20 x 2.5 = 1000 cm3. We are requesting an energy
spectrum in 20 logarithmic intervals between 0.001 and 50 GeV. In this case, we
ask that the corresponding output be printed, unformatted, on two different
files.
Option USRBIN provides detailed space distributions of energy deposition, star
density or integrated fluence (not energy fluence, unless by writing a special
user routine). Using some suitable graphics package, USRBIN output can be
presented in the form of colour maps. Programs for this purpose are available
in the $FLUPRO/flutil directory (pawlevbin.f and various kumac files), and
on the FLUKA website www.fluka.org.
USRBIN results are normalised to bin volumes calculated automatically by the
program (except in the case of region binning and special 3-variable binning
which are only seldom used).
The binning structure does not need to coincide with any geometry region. In
our example we propose to ask for two Cartesian space distributions, one of
charged pion fluence and one of total energy deposited. The first will extend
over a volume larger than the target, because fluence can be calculated even in
vacuum. Energy deposition, on the other hand, will be limited to the target
volume.
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
* Cartesian binning of the pion fluence inside and around the target
USRBIN 10.0 209.0 -50.0 50.0 50.0 50. piFluBin
USRBIN -50.0 -50.0 -10.0 100.0 100.0 60.0 &
* Cartesian binning of the deposited energy inside the target
USRBIN 10.0 208.0 -51.0 10.0 10.0 5. Edeposit
USRBIN -10.0 -10.0 0.0 20.0 20.0 5.0 &
Also in this case, the request is for output on two separate files.
Angular yields around a fixed direction of particles exiting a given surface
can be calculated using option USRYIELD. The results are double-differential
distributions with respect to a pair of variables, one of which is generally
energy-like (kinetic energy, momentum, etc.) and the other one angle-like (polar
angle, rapidity, Feynman-x, etc.) Distributions in LET (Linear Energy Transfer)
can also be requested by this option. An arbitrary normalisation factor can be
input.
Another commonly used scoring option is RESNUCLEi, which calculates residual
nuclei production in a given region. A normalisation factor (usually the region
volume) can be input.
A detailed summary of the requested estimators is printed on standard output.
The same information is printed in the same format in estimator ASCII output
files, and is available in coded form in unformatted estimator files.
Initialisation of the random number sequence
--------------------------------------------
The random number sequence used in a run is initialised by default by the seeds
contained in file random.dat provided with the code. To calculate the statistical
error of the results, it is necessary to perform other independent runs (at
least 4 or 5), each with a different independent initialisation, using the seeds
written by the program at the end of each run. The rfluka script provided with
the code on UNIX and LINUX platforms takes care of this task, provided the
following card is issued in the input file:
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
RANDOMIZE 1.0 0.0
The seeds of the random number generator are printed on a special file in
hexadecimal form at the end of each group of histories (the size of
a group depends on the number of histories requested in the START card).
Instead of getting the seeds from the last run, it is also possible to
initialise directly another independent random number sequence by setting the
second RANDOMIZe parameter equal to a different number, for instance:
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
RANDOMIZE 1.0 1198.
Starting signal and number of requested histories
-------------------------------------------------
At the end of the input file, a START card is mandatory in order to actually
start the calculation. That card must indicate also the number of particle
histories requested. The run, however, may be completed before all the histories
have been handled in two cases: if a time limit has been met (on some systems)
or if a "stop file" is created by the user (see instructions in a Note to option
START). The START card is optionally followed by a STOP card. For example, if
the user wants to generate 100000 histories, the input file can be closed with
the following two cards:
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
START 100000.0
STOP
The sample input file
---------------------
In summary, the input file for our basic example (example.inp), written in
fixed format, is the following:
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
TITLE
Charged pion fluence inside and around a proton-irradiated Be target
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
BEAM 50.E+00 PROTON
BEAMPOS 0.0 0.0 -50.0
*
GEOBEGIN COMBINAT
A simple Be target inside vacuum
RPP 1-5000000.0+5000000.0-5000000.0+5000000.0-5000000.0+5000000.0
RPP 2-1000000.0+1000000.0-1000000.0+1000000.0 -100.0+1000000.0
RPP 3 -10.0 +10.0 -10.0 +10.0 0.0 +5.0
* plane to separate the upstream and downstream part of the target
XYP 4 2.5
END
* black hole
BH1 5 +1 -2
* vacuum around
VA2 5 +2 -3
* Be target 1st half
BE3 5 +3 +4
* Be target 2nd half
BE4 5 +3 -4
END
GEOEND
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
MATERIAL 4.0 9.0122 1.848 5.0 BERYLLIU
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
* Be target, 1st and 2nd half
ASSIGNMAT 5.0 3.0 4.0
* External Black Hole
ASSIGNMAT 1.0 1.0
* Vacuum
ASSIGNMAT 2.0 2.0
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
* e+e- and gamma production threshold set at 10 MeV
EMFCUT -0.010 0.010 1.0 5.0 PROD-CUT
* score in each region energy deposition and stars produced by primaries
SCORE 208.0 210.0
* Boundary crossing fluence in the middle of the target (log intervals, one-way)
USRBDX 99.0 209.0 -47.0 3.0 4.0 400. piFluenUD
USRBDX +50.0 +50.0 0.0 10.0 &
* Boundary crossing current in the middle of the target (log intervals, one-way)
USRBDX -1.0 209.0 -47.0 3.0 4.0 400. piCurrUD
USRBDX +50.0 +50.0 0.0 10.0 &
* Tracklength fluence inside the target, Upstream part and Downstream part
* Logarithmic energy intervals
USRTRACK -1.0 209.0 -48.0 3.0 1000.0 20. piFluenU
USRTRACK 50.0 0.001 &
USRTRACK -1.0 209.0 -49.0 4.0 1000.0 20. piFluenD
USRTRACK 50.0 0.001 &
* Cartesian binning of the pion fluence inside and around the target
USRBIN 10.0 209.0 -50.0 50.0 50.0 50. piFluBin
USRBIN -50.0 -50.0 -10.0 100.0 100.0 60.0 &
* Cartesian binning of the deposited energy inside the target
USRBIN 10.0 208.0 -51.0 10.0 10.0 5. Edeposit
USRBIN -10.0 -10.0 0.0 20.0 20.0 5.0 &
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
RANDOMIZE 1.0
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
START 100000.0
STOP
The same input file, using the free format option for the FLUKA commands, but
not for the geometry, can instead be written as follows:
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
TITLE
Charged pion fluence inside and around a proton-irradiated Be target
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
GLOBAL 2.0
BEAM 50.E+00 0. 0. 0. 0. 0. PROTON
BEAMPOS 0. 0. -50.0 0. 0. 0. ' '
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
GEOBEGIN COMBINAT
A simple Be target inside vacuum
RPP 1-5000000.0+5000000.0-5000000.0+5000000.0-5000000.0+5000000.0
RPP 2-1000000.0+1000000.0-1000000.0+1000000.0 -100.0+1000000.0
RPP 3 -10.0 +10.0 -10.0 +10.0 0.0 +5.0
XYP 4 2.5
END
* black hole
BH1 5 +1 -2
* vacuum around
VA2 5 +2 -3
* Be target 1st half
BE3 5 +3 +4
* Be target 2nd half
BE4 5 +3 -4
END
GEOEND
MATERIAL 4.0 9.0122 1.848 5.0 0. 0. BERYLLIU
* Be target, 1st and 2nd half
ASSIGNMAT 5.0 3.0 4.0 0. 0. 0.
* External Black Hole
ASSIGNMAT 1.0 1.0 0. 0. 0. 0.
* Vacuum
ASSIGNMAT 2.0 2.0 0. 0. 0. 0.
* e+e- and gamma production threshold set at 10 MeV
EMFCUT -0.010 0.010 1.0 5.0, , , PROD-CUT
* score in each region energy deposition and stars produced by primaries
SCORE 208.0 210. 0. 0. 0. 0.
* Boundary crossing fluence in the middle of the target (log intervals, one-way)
USRBDX 99.0 +209.0 -47.0 3.0 4.0 +400.0 piFluenUD
USRBDX +50.00 0. +50.0 0. 0. 10.0 &
* Boundary crossing current in the middle of the target (log intervals, one-way)
USRBDX -1.0 +209.0 -47.0 3.0 4.0 +400.0 piCurrUD
USRBDX +50.00 0. +50.0 0. 0. 10.0 &
* Tracklength fluence inside the target, Upstream part and Downstream part
* Logarithmic energy intervals
USRTRACK -1.0 209.0 -48.0 3.0 1000.0 20. piFluenU
USRTRACK 50.0 0.001 0. 0. 0. 0. &
USRTRACK -1.0 209.0 -49.0 4.0 1000.0 20. piFluenD
USRTRACK 50.0 0.001 0. 0. 0. 0. &
* Cartesian binning of the pion fluence inside and around the target
USRBIN 10.0 209.0 -50.0 50.0 50.0 50. piFluBin
USRBIN -50.0 -50.0 -10.0 100.0 100.0 60.0 &
* Cartesian binning of the deposited energy inside the target
USRBIN 10.0 208.0 -51.0 10.0 10.0 5. Edeposit
USRBIN -10.0 -10.0 0.0 20.0 20.0 5.0 &
RANDOMIZE 1.0 0. 0. 0. 0. 0.
START 100000.0 0. 0. 0. 0. 0.
STOP
Running FLUKA
-------------
It is advisable, but not mandatory, to keep separate the $FLUPRO directory
from that or those where calculations are run and input files are kept.
For instance, flukawork:
cd /home/user/flukawork
As mentioned above, the rfluka script in $FLUPRO/flutil should be used to drive
the FLUKA run. In the following it is supposed that the user is going to ask
for five statistically independent runs, each one made of 100000 histories, of
the proposed basic example. The command is:
$FLUPRO/flutil/rfluka -N0 -M5 example &
(on LINUX/UNIX, the \& character allows to run the program in the background
without "freezing" the terminal window).
The script creates a temporary subdirectory called fluka_nnnn where
nnnn is tbe number of the subprocess. For instance, when the first
run (or "cycle") starts, the user will see on the terminal lines similar
to the following ones:
$TARGET_MACHINE = Linux
$FLUPRO = /home/user/flupro
2789: old priority 0, new priority 10
Initial seed already existing
Running fluka in /home/user/flukawork/fluka_2789
================================ Running FLUKA for cycle # 1 ===================
At the end of each cycle the output files will be copied onto the running
directory, the temporary directory will be erased and a new one will be created
where the next run will take place. The names of the output files from each run
are built by appending to the input file name the run number and an extension
depending on their content: .out for the standard output, .err for the error
file, .log for the log file and _fort.nn for the estimator files (with
nn = absolute value of the selected output unit). The file containing the
random number seeds will be called "ran".
The error file may contain error messages related to the event generators (for
instance when the program does not manage to conserve exactly energy or another
quantity) or to the geometry tracking. Most of those are generally only warning
messages which can be ignored unless there is a large number of them.
The log file generally contains messages related to fatal errors (input errors,
overflow, etc.)
During a multiple run, lines like the following will appear on the user's
screen:
================================ Running FLUKA for cycle # 1 ====================
Removing links
Removing temporary files
Saving output and random number seed
Saving additional files generated
Moving fort.47 to /home/fasso/Fluka/test/example01_fort.47
Moving fort.48 to /home/fasso/Fluka/test/example01_fort.48
Moving fort.49 to /home/fasso/Fluka/test/example01_fort.49
Moving fort.50 to /home/fasso/Fluka/test/example01_fort.50
Moving fort.51 to /home/fasso/Fluka/test/example01_fort.51
================================ Running FLUKA for cyle # 2 ====================
Removing links
Removing temporary files
Saving output and random number seed
Saving additional files generated
Moving fort.47 to /home/fasso/Fluka/test/example002_fort.47
Moving fort.48 to /home/fasso/Fluka/test/example002_fort.48
Moving fort.49 to /home/fasso/Fluka/test/example002_fort.49
Moving fort.50 to /home/fasso/Fluka/test/example002_fort.50
Moving fort.51 to /home/fasso/Fluka/test/example002_fort.51
================================ Running FLUKA for cycle # 3 ===================
.....
================================ Running FLUKA for cycle # 4 ===================
.....
================================ Running FLUKA for cycle # 5 ===================
Removing links
Removing temporary files
Saving output and random number seed
Saving additional files generated
Moving fort.47 to /home/fasso/Fluka/test/example005_fort.47
Moving fort.48 to /home/fasso/Fluka/test/example005_fort.48
Moving fort.49 to /home/fasso/Fluka/test/example005_fort.49
Moving fort.50 to /home/fasso/Fluka/test/example005_fort.50
Moving fort.51 to /home/fasso/Fluka/test/example005_fort.51
End of FLUKA run
At this time, in the working directory, the following new files exist:
example001_fort.47 example002_fort.47 .... example005_fort.47
example001_fort.48 example002_fort.48 .... example005_fort.48
example001_fort.49 example002_fort.49 .... example005_fort.49
example001_fort.50 example002_fort.50 .... example005_fort.50
example001_fort.51 example002_fort.51 .... example005_fort.51
example001.out example002.out .... example005.out
example001.err example002.err .... example005.err
In Chapter 9} the user can find a comprehensive description of the content of
the FLUKA standard output. For the purpose of this beginner's guide, it can
just be pointed out that, according to the content of the USRBDX command, the
files with extension fort.47 contain, in binary form, the boundary crossing
estimator output for the required pion fluence and current detectors (for more
details see Chap. 9}). These files must be combined together to produce a
table of values with their statistical errors which can be easily interfaced by
the user to some analysis codes and/or graphic visualisation tools. Similarly,
the files with extension fort.48 and fort.49 will contain the tracklength
estimator output, and those with extension fort.50 and fort.51 the output from
USRBIN.
Accessing results
-----------------
Boundary crossing estimator
Binary files from the USRBDX estimator can be accessed by means of the usxsuw.f
readout code, which is located in the $FLUPRO/flutil directory.
That readout code can be easily compiled. For example, the same compiling and
linking FLUKA tools can be used for this purpose:
cd $FLUPRO/flutil
./lfluka usxsuw.f -o usxsuw
In order to process the 5 output files produced by the proposed example, the
following interactive procedure can be used:
cd /home/user/flukawork
$FLUPRO/flutil/usxsuw
The readout code will ask for the first FLUKA estimator file name:
Type the input file:
For each estimator file the program will show the content of the TITLE card of
the FLUKA input file, the date and time of the FLUKA run and the number of
histories for the given run.
The request will be iterated until a blank line is given. This will be
interpreted as the end of the list of files, and then a name for the
output file prefix will be requested. Let's use, for example, the
name "pionbdx":
Type the input file: example001_fort.47
Charged pion fluence inside and around a proton-irradiated Be target
DATE: 7/15/ 5, TIME: 16:22:11
100000.
100000
Type the input file: example002_fort.47
Charged pion fluence inside and around a proton-irradiated Be target
DATE: 7/15/ 5, TIME: 16:23: 3
100000.
100000
Type the input file: example003_fort.47
Charged pion fluence inside and around a proton-irradiated Be target
DATE: 7/15/ 5, TIME: 16:23:54
100000.
100000
Type the input file: example004_fort.47
Charged pion fluence inside and around a proton-irradiated Be target
DATE: 7/15/ 5, TIME: 16:24:51
100000.
100000
Type the input file: example005_fort.47
Charged pion fluence inside and around a proton-irradiated Be target
DATE: 7/15/ 5, TIME: 16:25:45
100000.
100000
Type the input file:
Type the output file name: pionbdx
At this point the following 3 new files are produced:
pionbdx
pionbdx_sum.lis
pionbdx_tab.lis
The first one (pionbdx) is again a binary file that can be read out at any time
by usxsuw. The content of this file is statistically equivalent to that of the
sum of the files used to obtain it, and it can replace them to be combined with
further output files if desired (the usxsuw program takes care of giving it the
appropriate weight).
The other two files are ASCII text files.
Let us first examine pionbdx_sum.lis. This contains many comments which can
help the user to understand the results. Since by means of the USRBDX command
separate detectors for pion fluence and current have been requested, with their
output on the same logical unit, there will be two different sections in the
file, identified by the word "Detector": Detector no. 1 is for fluence and
Detector no. 2 is for current, because this is the order in which the
USRBDX commands have been given.
Let us inspect the output from Detector no. 1:
Charged pion fluence inside and around a proton-irradiated Be target
Total primaries run: 500000
Total weight of the primaries run: 500000.
Detector n: 1( 1) piFluenUD
(Area: 400. cmq,
distr. scored: 209 ,
from reg. 3 to 4,
one way scoring,
fluence scoring)
Tot. resp. (Part/cmq/pr) 8.6904905E-04 +/- 0.6976866 %
( --> (Part/pr) 0.3476196 +/- 0.6976866 % )
The total (summed) number of primaries (histories) is reported at first, then
the main features of USRBDX request are summarised. The following numbers
represent the energy and angle integrated fluence ("total response").
Here and later, the statistical error is always expressed in percentage.
After this heading, the differential fluence tabulation as a function of (pion)
energy, and integrated over solid angle, is reported, starting with the
boundaries of the energy bins. As a general convention, these values are given
from the highest to the lowest value:
**** Different. Fluxes as a function of energy ****
**** (integrated over solid angle) ****
Energy boundaries (GeV):
49.99992 40.27077 32.43475 26.12349 21.04029
16.94620 13.64875 10.99293 8.853892 7.131072
5.743484 4.625898 3.725775 3.000802 2.416896
1.946608 1.567831 1.262757 1.017045 0.8191454
0.6597533 0.5313764 0.4279793 0.3447017 0.2776285
0.2236066 0.1800965 0.1450527 0.1168279 9.4095118E-02
7.5785778E-02 6.1039131E-02 4.9161937E-02 3.9595842E-02 3.1891152E-02
2.5685664E-02 2.0687662E-02 1.6662188E-02 1.3420003E-02 1.0808695E-02
8.7055033E-03 7.0115575E-03 5.6472253E-03 4.5483690E-03 3.6633324E-03
2.9505091E-03 2.3763892E-03 1.9139835E-03 1.5415541E-03 1.2415934E-03
Lowest boundary (GeV): 1.0000000E-03
Flux (Part/GeV/cmq/pr):
1.5418744E-09 +/- 99.00000 % 4.8503271E-08 +/- 6.709127 %
2.3456116E-07 +/- 6.506497 % 5.9040013E-07 +/- 3.466331 %
1.2585346E-06 +/- 4.051404 % 2.5295039E-06 +/- 2.039807 %
4.6113087E-06 +/- 2.195296 % 7.6260553E-06 +/- 1.939942 %
1.2214471E-05 +/- 0.8310503 % 1.8394410E-05 +/- 0.6178440 %
2.6636921E-05 +/- 1.128397 % 3.6855919E-05 +/- 1.204921 %
5.1703457E-05 +/- 1.100655 % 6.9101960E-05 +/- 0.7564522 %
9.0419722E-05 +/- 1.799108 % 1.1945122E-04 +/- 1.256268 %
1.5757892E-04 +/- 0.8898824 % 1.9452766E-04 +/- 1.332425 %
2.4165030E-04 +/- 1.521364 % 3.0573772E-04 +/- 2.473622 %
3.6900895E-04 +/- 1.399170 % 4.4734811E-04 +/- 0.9543594 %
5.2953843E-04 +/- 1.964312 % 6.1596523E-04 +/- 1.349476 %
6.4003764E-04 +/- 3.323846 % 6.8828161E-04 +/- 0.9288639 %
6.8151421E-04 +/- 2.018673 % 7.0822553E-04 +/- 4.401796 %
7.4972271E-04 +/- 2.600316 % 6.9859857E-04 +/- 3.693749 %
6.8915845E-04 +/- 4.332464 % 6.6514849E-04 +/- 8.753220 %
6.4636284E-04 +/- 11.30834 % 5.5008888E-04 +/- 7.691558 %
4.3721433E-04 +/- 11.36630 % 3.2056248E-04 +/- 8.380781 %
4.2511927E-04 +/- 12.24571 % 2.2697043E-04 +/- 12.99932 %
2.0069227E-04 +/- 13.10813 % 1.7180138E-04 +/- 16.90801 %
9.9383309E-05 +/- 21.15753 % 2.9268101E-04 +/- 39.29378 %
1.5672133E-04 +/- 44.01294 % 2.1093644E-04 +/- 34.72458 %
7.4201569E-05 +/- 33.68359 % 7.2452240E-05 +/- 33.54827 %
8.6934262E-05 +/- 62.03180 % 1.0245090E-04 +/- 99.00000 %
1.6312006E-04 +/- 82.06016 % 1.3002084E-04 +/- 52.15991 %
Soon after, the cumulative fluence distribution as a function of energy is also
given:
**** Cumulative Fluxes as a function of energy ****
**** (integrated over solid angle) ****
Energy boundaries (GeV):
49.99992 40.27077 32.43475 26.12349 21.04029
16.94620 13.64875 10.99293 8.853892 7.131072
5.743484 4.625898 3.725775 3.000802 2.416896
1.946608 1.567831 1.262757 1.017045 0.8191454
0.6597533 0.5313764 0.4279793 0.3447017 0.2776285
0.2236066 0.1800965 0.1450527 0.1168279 9.4095118E-02
7.5785778E-02 6.1039131E-02 4.9161937E-02 3.9595842E-02 3.1891152E-02
2.5685664E-02 2.0687662E-02 1.6662188E-02 1.3420003E-02 1.0808695E-02
8.7055033E-03 7.0115575E-03 5.6472253E-03 4.5483690E-03 3.6633324E-03
2.9505091E-03 2.3763892E-03 1.9139835E-03 1.5415541E-03 1.2415934E-03
Lowest boundary (GeV): 1.0000000E-03
Cumul. Flux (Part/cmq/pr):
1.5001119E-08 +/- 99.00000 % 3.9507350E-07 +/- 7.326498 %
1.8754495E-06 +/- 5.464718 % 4.8765669E-06 +/- 1.819896 %
1.0029117E-05 +/- 1.898280 % 1.8370021E-05 +/- 1.277005 %
3.0616819E-05 +/- 0.6900454 % 4.6929261E-05 +/- 0.9553517 %
6.7972585E-05 +/- 0.7029299 % 9.3496434E-05 +/- 0.6531623 %
1.2326548E-04 +/- 0.5382378 % 1.5644032E-04 +/- 0.6154544 %
1.9392396E-04 +/- 0.6043725 % 2.3427299E-04 +/- 0.5368618 %
2.7679623E-04 +/- 0.5548110 % 3.2204165E-04 +/- 0.6000980 %
3.7011484E-04 +/- 0.6263003 % 4.1791250E-04 +/- 0.6480659 %
4.6573509E-04 +/- 0.7125404 % 5.1446725E-04 +/- 0.7778813 %
5.6183949E-04 +/- 0.8066853 % 6.0809392E-04 +/- 0.7142704 %
6.5219263E-04 +/- 0.7654761 % 6.9350738E-04 +/- 0.7260005 %
7.2808337E-04 +/- 0.8159186 % 7.5803063E-04 +/- 0.7573094 %
7.8191340E-04 +/- 0.7549785 % 8.0190296E-04 +/- 0.7531289 %
8.1894622E-04 +/- 0.7366922 % 8.3173712E-04 +/- 0.6872664 %
8.4189989E-04 +/- 0.6799491 % 8.4980001E-04 +/- 0.6579692 %
8.5598318E-04 +/- 0.6862395 % 8.6022145E-04 +/- 0.6667165 %
8.6293457E-04 +/- 0.6859071 % 8.6453673E-04 +/- 0.6995495 %
8.6624804E-04 +/- 0.6864265 % 8.6698390E-04 +/- 0.6886846 %
8.6750800E-04 +/- 0.6864119 % 8.6786930E-04 +/- 0.6882262 %
8.6803763E-04 +/- 0.6885374 % 8.6843700E-04 +/- 0.6933275 %
8.6860918E-04 +/- 0.6915213 % 8.6879585E-04 +/- 0.6911866 %
8.6884876E-04 +/- 0.6931223 % 8.6889038E-04 +/- 0.6942393 %
8.6893054E-04 +/- 0.6953420 % 8.6896872E-04 +/- 0.6967193 %
8.6901762E-04 +/- 0.6981055 % 8.6904905E-04 +/- 0.6976866 %
The numbers for the cumulative distribution have been obtained by multiplying
each value of the differential distribution by the corresponding energy bin
width (variable if the distribution is logarithmic as in our example). The
integral fluence in any given energy interval can be obtained as the difference
between the values of the cumulative distribution at the two bounds of that
interval.
Since more than one angular interval was requested, at this point the angular
distribution WITH RESPECT TO THE NORMAL AT THE BOUNDARY CROSSING POINT is
reported, both in steradians and in degrees:
**** Double diff. Fluxes as a function of energy ****
Solid angle minimum value (sr): 0.000000
Solid angle upper boundaries (sr):
0.6283185 1.256637 1.884956 2.513274 3.141593
3.769911 4.398230 5.026548 5.654867 6.283185
Angular minimum value (deg.): 0.000000
Angular upper boundaries (deg.):
25.84193 36.86990 45.57299 53.13010 60.00000
66.42182 72.54239 78.46304 84.26083 90.00000
Let us take for instance the energy bin between 0.345 GeV and 0.278 GeV:
Energy interval (GeV): 0.3447016 0.2776284
Flux (Part/sr/GeV/cmq/pr):
2.2090337E-04 +/- 2.271138 % 1.6099877E-04 +/- 2.023665 %
1.2373505E-04 +/- 3.802638 % 9.4749055E-05 +/- 2.419357 %
7.0389280E-05 +/- 5.640523 % 6.6853667E-05 +/- 9.292711 %
6.8042267E-05 +/- 5.421218 % 6.8482914E-05 +/- 11.91976 %
5.8157104E-05 +/- 2.943847 % 4.8027632E-05 +/- 39.71496 %
Flux (Part/deg/GeV/cmq/pr):
5.3710260E-06 +/- 2.271138 % 9.1729089E-06 +/- 2.023665 %
8.9330297E-06 +/- 3.802638 % 7.8776966E-06 +/- 2.419357 %
6.4377805E-06 +/- 5.640523 % 6.5410413E-06 +/- 9.292711 %
6.9850003E-06 +/- 5.421218 % 7.2676362E-06 +/- 11.91976 %
6.3026077E-06 +/- 2.943847 % 5.2580162E-06 +/- 39.71496 %
The same structure is then replicated for Detector no. 2:
Detector n: 2( 2) piCurrUD
(Area: 400. cmq,
distr. scored: 209 ,
from reg. 3 to 4,
one way scoring,
current scoring)
Tot. resp. (Part/cmq/pr) 7.1694393E-04 +/- 0.7243900 %
( --> (Part/pr) 0.2867776 +/- 0.7243900 % )
and so on.
Note that in this case the ratio between the calculated fluence (8.690E-04) and
the corresponding current (7.169E-04) is about 1.2. The ratio between the
numerical values of the two quantities would be 1 if the pions were all
crossing the boundary at a right angle, 2 in the case of an isotropic
distribution, and could even tend to infinity if the particle direction were
mainly parallel to the boundary:
FLUENCE AND CURRENT ARE VERY DIFFERENT QUANTITIES AND SHOULD NOT BE CONFUSED!
Note also that the above output reports also the current value not normalised
per unit area. This is equivalent to a simple count of crossing particles, so
we see that in our example about 0.287 charged pions per primary proton cross
the middle plane of the target.
The previous file has a structure which is not easily interfaceable to other
readout codes. This can be easily achieved by means of the other output file,
pionbdx_tab.lis: there the user can find, for each Detector, a simple 4-column
structure for the differential fluence integrated over solid angle. The table
starts from the lowest energy and the four columns represent respectively
E_min, E_max, the differential fluence and the statistical error in percentage:
# Detector n: 1 piFluenUD (integrated over solid angle)
# N. of energy intervals 50
1.000E-03 1.242E-03 1.300E-04 5.216E+01
1.242E-03 1.542E-03 1.631E-04 8.206E+01
1.542E-03 1.914E-03 1.025E-04 9.900E+01
1.914E-03 2.376E-03 8.693E-05 6.203E+01
2.376E-03 2.951E-03 7.245E-05 3.355E+01
2.951E-03 3.663E-03 7.420E-05 3.368E+01
3.663E-03 4.548E-03 2.109E-04 3.472E+01
4.548E-03 5.647E-03 1.567E-04 4.401E+01
5.647E-03 7.012E-03 2.927E-04 3.929E+01
.....
By convention, when in a given bin the statistics is not sufficient to
calculate a standard deviation, the statistical error is printed as 99%. For a
null fluence the statistical error is also null.
After this table, the double differential fluence is reported.
First, one or more lines marked by a # sign in column 1 give, from minimum to
maximum, the extremes of the solid angle intervals. Then, for each energy
interval, the minimum and maximum of the interval followed by as many pairs of
values as the number of angular bins: the first value is the calculated
double-differential quantity (fluence or current) in cm-2 sr-1 and the second
is the corresponding statistical error in percent.
For instance, for our example we obtain the following printout (for the sake of
space only 3 bins in energy are shown):
# double differential distributions
# number of solid angle intervals 10
# 0.000E+00 6.283E-01 6.283E-01 1.257E+00 1.257E+00 1.885E+00 ...
#
....
2.069E-02 2.569E-02 4.013E-05 2.472E+01 4.509E-05 2.068E+01 ...
2.569E-02 3.189E-02 5.408E-05 1.907E+01 4.657E-05 2.200E+01 ...
3.189E-02 3.960E-02 5.150E-05 7.137E+00 5.355E-05 1.587E+01 ...
....
Track length estimator
The program to analyse USRTRACK binary output is called ustsuw.f and can also
be found in $FLUPRO/flutil. Its use is very similar to that of usxsuw.f
described above. Applying it to the example00*_fort.48 files (output of the
first USRTRACK detector in our example), we obtain for the average fluence of
charged pions in the upstream half of the beryllium target:
Tot. response (p/cmq/pr) 5.4765277E-04 +/- 0.6965669 %
and from the example00*_fort.49 files (pion fluence in the downstream half):
Tot. response (p/cmq/pr) 1.3474772E-03 +/- 0.5352812 %
As it was to be expected, the average fluence obtained above by the boundary
crossing estimator on the middle surface (8.69E-04 cm-2) has a value which is
intermediate between these two.
Binning estimator
To analyse the binary output from USRBIN, two programs are needed, both
available in $FLUPRO/flutil. The first, usbsuw.f, performs a statistical
analysis of the results and produces a new unformatted file, with a name chosen
by the user. The second program, usbrea.f, reads the latter file and writes on
a formatted file two arrays, namely the content of each bin, averaged over the
given number of runs, followed by the corresponding errors in percent. The
second USRBIN detector defined in example.inp gives the following values
of energy deposition (in GeV/cm3):
1
Cartesian binning n. 1 "Edeposit " , generalized particle n. 208
X coordinate: from -1.0000E+01 to 1.0000E+01 cm, 20 bins ( 1.0000E+00 cm wide)
Y coordinate: from -1.0000E+01 to 1.0000E+01 cm, 20 bins ( 1.0000E+00 cm wide)
Z coordinate: from 0.0000E+00 to 5.0000E+00 cm, 5 bins ( 1.0000E+00 cm wide)
Data follow in a matrix A(ix,iy,iz), format (1(5x,1p,10(1x,e11.4)))
accurate deposition along the tracks requested
1.7164E-07 3.4587E-07 2.1976E-07 3.0997E-07 1.4963E-07 3.5431E-07 .....
5.6597E-07 7.5792E-07 3.6563E-07 2.7822E-07 2.6084E-07 2.8645E-07 .....
2.6191E-07 1.6716E-07 3.8680E-07 2.4925E-07 4.2334E-07 3.5025E-07 .....
.............................................................................
and the following corresponding percentage errors:
Percentage errors follow in a matrix A(ix,iy,iz), format (1(5x,1p,10(1x,e11.4)))
1.3936E+01 4.3211E+01 3.0601E+01 2.2874E+01 1.7783E+01 2.7942E+01 .....
1.6548E+01 1.2291E+01 1.4539E+01 2.4576E+01 2.7828E+01 1.7247E+01 .....
2.2423E+01 1.7258E+01 2.0349E+01 3.7997E+01 2.6855E+01 2.9230E+01 .....
.............................................................................
Readout of other FLUKA estimators
---------------------------------
The $FLUPRO/flutil directory contains other similar programs to average the
outputs from other FLUKA estimators (not used in the present example):
- usrsuw.f: to read out the RESNUCLEi output
- usysuw.f: to read out the USRYIELD output
Various settings
----------------
Accuracy and computer speed depend on several parameters that can be freely
tuned by the user: but in general an increase of either one results in a
decrease of the other. The proper balance must be based both on physical and on
practical considerations. The present defaults have been designed to give
satisfactory results in the most common cases: but other sets of defaults can
be implemented using option DEFAULTS (to be placed at the beginning of the
input file, just after the title).
Even when one set of defaults is enforced, the user can still override some of
them by modifying single parameters. The most used ones concern energy cut-offs
(option EMFCUT for electrons and photons, LOW-BIAS for low-energy neutrons,
PART-THR for all other particles), thresholds for delta-ray production (option
DELTARAY), particles to be ignored (option DISCARD), switching on or off some
physical effect (EMFCUT, IONFLUCT, MUPHOTON, PAIRBREM, PHOTONUC, PHYSICS,
POLARIZAti), and (more rarely) the size of the step for transporting charged
particles (FLUKAFIX, MCSTHRES, MULSOPT, STEPSIZE).
Energy cut-offs for each particle are listed in a table on standard output
("Particle transport thresholds").
Biasing
-------
Although FLUKA is able to perform fully analogue particle transport
calculations (i.e. to reproduce faithfully actual particle histories), in many
cases of very non-uniform radiation fields, such as those encountered in
shielding design, only a very small fraction of all the histories contributes
to the desired response (dose, fluence) in the regions of interest, for
instance behind thick shielding. In these cases, the user's concern is not to
simulate exactly what occurs in reality, but to estimate in the most efficient
way the desired response. This can be obtained by replacing the actual physical
problem with a mathematically equivalent one, i.e. having the same solution but
faster statistical convergence.
A rigorous mathematical treatment of such variance-reduction techniques can be
found in several textbooks (see for instance those of Lux and Koblinger [Lux91]
or Carter and Cashwell [Car75]).
In the present practical introduction we will only issue a few important
warnings:
1) In the limit of the number of histories tending to infinity, the value of
all calculated quantities tend EXACTLY to the same average in the analogue
and in the corresponding biased calculation. In other words, biasing is
mathematically correct and implies no approximation. However, an
acceleration of convergence in certain regions of phase space
(space/energy/angle) will generally be paid for by a slower convergence in
other regions.
Because an actual calculation does not use an infinite number of particles,
but is necessarily truncated after a finite number of histories, results
must be considered with some judgment. For instance, if the number of
histories is too small, it can happen that total energy is not conserved
(check the energy budget summary at the very end of main output!)
2) A bad choice of biasing parameters may have consequences opposite to what is
desired, namely a slower convergence. A long experience, and often some
preliminary trial-and-error investigation, are needed in order to fully
master these techniques (but some biasing algorithms are "safer" than others).
3) Because biasing implies replacing some distributions by others having the
same expectation values but different variance (and different higher
moments), biasing techniques in general do not conserve correlations and
cannot describe correctly fluctuations.
The simplest (and safest) biasing option offered by FLUKA is importance
biasing, which can be requested by option BIASING. Each geometry region is
assigned an "importance", namely a number between 1.0E-4 and 1.0E+4,
proportional to the contribution that particles in that region are expected to
give to the desired result. The ratio of importances in any two adjacent
regions is used to drive a classical biasing algorithm ("Splitting" and
"Russian Roulette"). In a simple, monodimensional attenuation problem, the
importance is often set equal to the inverse of the expected fluence
attenuation factor for each region.
In electron accelerator shielding, two other biasing options are commonly
employed: EMF-BIAS and LAM-BIAS. The first one is used to request leading
particle biasing, a technique which reduces considerably the computer time
required to handle high-energy electromagnetic showers. With this option, CPU
time becomes proportional to primary energy rather than increasing
exponentially with it. Option LAM-BIAS is necessary in order to sample with
acceptable statistics photonuclear reactions which have a much lower
probability than competing electromagnetic photon reactions, but are often
more important from the radiological point of view.
Other important options are those which set weight window biasing (WW-FACTOr
WW-THRESh and WW-PROFIle) but their use requires more experience than assumed
here for a beginner.
Particle importances, weight windows and low-energy neutron biasing parameters
are reported for each region in standard output. On user's request (expressed
as SDUM = PRINT in a BIASING card), Russian Roulette and Splitting counters are
printed for each region on standard output before the final summary. Such
counters can be used for a better tuning of the biasing options.
