There are more than 70 option keywords available for input in FLUKA. A summary
is given in the next section, where the commands will be shortly introduced and
grouped by type of functionality. Some of the commands, which can provide
several different services, will be mentioned in the context of more than one
group.
A complete description of each command will follow, in alphabetical order.
Introduction to the FLUKA input options
Summary of the available options.
Here is a list of the options (commands) that are at the disposal of the FLUKA
user to prepare an input file. In the rest of this section, the same commands
will be presented by grouping them according to the different services they can
provide.
ASSIGNMAt defines the correspondence between region and material indices and
defines regions where a magnetic field exists
BEAM defines most of the beam characteristics (energy, profile,
divergence, particle type)
BEAMAXES defines the axes used for a beam reference frame different from the
geometry frame
BEAMPOS defines the starting point of beam particles and the beam direction
BIASING sets importance sampling (Russian Roulette/splitting) at boundary
crossings and at high-energy hadronic collisions on a region by
region basis
BME defines some I/O parameters relevant to the heavy ion event
generator BME (Boltzmann Master Equation)
COMMENT inserts comments in the input or passes to the program information
about the computer used and about the input file
COMPOUND defines a compound or a mixture or a mixture of isotopes
CORRFACT allows to alter material density for dE/dx and nuclear processes on
a region-by-region basis
DCYSCORE associates selected scoring detectors of given estimator type with
user-defined decay times
DCYTIMES defines decay times for radioactive product scoring
DEFAULTS sets FLUKA defaults for specified kinds of problems
DELTARAY activates delta-ray production by heavy charged particles and
controls energy loss and deposition
DETECT scores energy deposition in coincidence or anti-coincidence with a
trigger, on an event by event basis
DISCARD defines the particles which must not be transported
DPMJET defines some I/O parameters relevant to the heavy ion event
generator DPMJET
ELCFIELD sets the tracking conditions for transport in electric fields and
possibly defines an homogeneous electric field (not yet implemented)
EMF requests detailed transport of electrons, positrons and photons
EMF-BIAS defines electron/photon leading particle biasing or biases
electron/photon interaction length
EMFCUT sets energy cut-offs for electrons, positrons and photons, for
transport and production, or for switching off some physical
interactions
EMFFIX sets the size of electron steps corresponding to a fixed fraction
loss of the total energy
EMFFLUO activates production of fluorescence X rays in selected materials
EMFRAY activates Rayleigh (coherent) scattering in selected regions
EVENTBIN scores energy or star densities in a binning structure independent
from the geometry, and prints the binning output after each "event"
(primary history)
EVENTDAT prints event by event the scored star production and/or energy
deposition in each region, and the total energy balance
EVENTYPE defines the hadron particle production model to be used
EXPTRANS requests exponential transformation ("path stretching") (not yet
implemented)
FLUKAFIX sets the size of the step of muons and charged hadrons to a fixed
fraction loss of the kinetic energy
FREE switches to free-format input (geometry excluded)
GEOBEGIN starts the geometry description
GEOEND ends the geometry description; can also be used to activate the
geometry debugger
GLOBAL issues global declarations about the class of the problem (analogue
or weighted) and about the complexity of the geometry. It also
allows to use free format input (geometry included)
HI-PROPE defines the properties of a heavy ion primary
IONFLUCT calculates ionisation energy losses with fluctuations
IRRPROFI defines an irradiation profile for radioactive decay calculations
LAM-BIAS biases decay length and interaction length
LOW-BIAS requests non-analogue absorption and defines the energy cut-off for
low-energy neutron transport on a region by region basis
LOW-DOWN biases the downscattering probability in low energy neutron
transport on a region by region basis
LOW-MAT sets the correspondence between FLUKA materials and low-energy
neutron cross-section data
LOW-NEUT requests low-energy neutron transport
MATERIAL defines a material and its properties
MAT-PROP supplies extra information about gaseous materials and materials
with fictitious or inhomogeneous density and defines other material
properties
MCSTHRES defines energy thresholds for applying the multiple Coulomb
scattering algorithm to the transport of muons and charged hadrons
MGNFIELD sets the tracking conditions for transport in magnetic fields
and possibly defines a homogeneous magnetic field
MULSOPT controls optimisation of multiple Coulomb scattering treatment. It
can also request transport with single scattering
MUPHOTON controls photonuclear interactions of high-energy heavy charged
particles (mediated by virtual photons)
MYRQMD defines some I/O parameters relevant to the new heavy ion event
generator RQMD
OPEN defines input/output files without pre-connecting
OPT-PROP defines optical properties of materials
OPT-PROD controls Cherenkov and Transition Radiation photon production
PAIRBREM controls simulation of pair production and bremsstrahlung by
high-energy heavy charged particles
PART-THR sets different energy cut-offs for selected particles
PHOTONUC activates photon interactions with nuclei
PHYSICS controls some physical processes for selected particles
PLOTGEOM calls the PLOTGEOM package to draw a slice of the geometry
POLARIZA defines polarised beams (only for photons at present)
RADDECAY requests simulation of radioactive decays and sets the corresponding
biasing and transport conditions
RANDOMIZe sets the seeds and selects a sequence for the random number
generator
RESNUCLEi scores residual nuclei after inelastic hadronic interactions
ROT-DEFIni defines rotations/translations to be applied to user-defined
binnings
ROTPRBIN sets the storage precision (single or double) and assigns possible
rotations/translations for a given user-defined binning (USRBIN or
EVENTBIN)
RQMD defines some I/O parameters relevant to the heavy ion event
generator RQMD
SCORE defines the energy deposited or the stars to be scored by region
SOURCE tells FLUKA to call a user-defined source routine
START defines the number of primary particles to follow, gets a primary
particle from a beam or from a source, starts the transport and
repeats until the predetermined number of primaries is reached
STEPSIZE sets the maximum step size in cm (by region) for transport of
charged particles
STERNHEIme allows users to input their own values of the density effect
parameters
STOP stops input reading
TCQUENCH sets scoring time cutoffs and/or Birks quenching parameters
THRESHOLd defines the energy threshold for star density scoring, and sets
thresholds for elastic and inelastic hadron reactions
TIME-CUT sets transport time cutoffs
TITLE gives the title of the run
USERDUMP requests a collision file and defines the events to be written
USERWEIG defines extra weighting to be applied to scored yields, fluences,
doses, residual nuclei or star densities (at scoring time)
USRBDX defines a detector for a boundary crossing fluence or current
estimator
USRBIN scores energy, star density or particle fluence in a binning
structure independent from the geometry
USRCOLL defines a detector for a collision fluence estimator
USRICALL calls user-dependent initialisation
USROCALL calls user-dependent output
USRTRACK defines a detector for a track-length fluence estimator
USRYIELD defines a detector for scoring particle yield around a given
direction
WW-FACTOr defines weight windows in selected regions
WW-PROFIle defines energy group-dependent extra factors ("profiles") to modify
the basic setting of the low-energy neutron weight windows in
selected sets of regions, or the low-energy neutron importances in
each region
WW-THRESh defines the energy limits for a RR/splitting weight window
Basic commands
Most FLUKA commands are optional, and if anyone of them is not used an
appropriate set of defaults is provided. A few commands, however, are nearly
always needed in order to provide a meaningful definition of the problem to be
studied.
In general, for a problem to be fully determined, the following elements need
to be defined:
1) the radiation source
2) the geometrical layout
3) the materials
4) the requested results
5) setting of parameters, accuracy, conditions, and in general technical
directives to the program on how the calculation shall be performed
Defaults are provided in FLUKA for all the above features, but those for
items 1), 2) and 3) are unlikely to be useful: therefore the few commands used
to define source, geometry and materials are practically always present in the
input file.
For what concerns item 4), the user has a choice of several options to request
the estimation of various radiometric quantities. Of course, there is no much
point in running the program without requesting any result, but in a phase of
input preparation it is quite common to have a few runs without any scoring
commands. A typical minimum input containing only specifications for the above
items 1), 2) and 3) will still produce some useful information. Looking at the
standard FLUKA output, the user can do several consistency checks, and can get
some better insight into the problem from the final statistics and energy
balance.
The last part of problem definition, element 5) (setting) is important but is
supported by very robust defaults. In many cases, the only user concern should
consist in choosing the right set of defaults. However, there are some
applications which require explicit setting commands, for instance to request
photonuclear reactions for electron accelerator shielding.
Definition of the radiation source
The simplest particle source is pointlike, monoenergetic and monodirectional,
that is, a "particle beam". Option BEAM, fully described later, is used to
define the particle type and momentum (or energy). If desired, this option can
also define an energy spread, a beam profile shape and an angular divergence.
However, the two latter distributions are restricted to a beam is directed in
the positive z direction: to describe divergence and beam profile for an
arbitrary beam direction it is necessary to define a beam reference frame by
means of option BEAMAXES.
The energy declared with BEAM is used by the program to initialise
cross-section tables and other energy-dependent arrays: therefore that command
must always be present, even when a more complex source is described by means
of a user routine.
The particle starting point and direction are declared by means of option
BEAMPOS. If BEAMPOS is not present, the beam particles are assumed to start
from the origin of the coordinates 0., 0., 0. and to be directed along the z
axis. It is important that the starting point be not on a boundary and not
inside a blackhole region. In many cases, starting in vacuum upstream of the
actual target can be convenient.
Both BEAM and BEAMPOS commands can be placed anywhere in the input file, before
the START command.
Particle sources with more complicated features (with arbitrary distribution in
energy, space, angle, time, and even with more than one type of particle) can
be described by a user-written subroutine SOURCE. To call it, a command SOURCE
must be present in input.
Description of the geometry
The Combinatorial Geometry used by FLUKA is based on two important concepts:
bodies and regions. The first ones are closed solid bodies (spheres,
parallelepipeds, etc.) or semi-infinite portions of space (half-spaces,
infinite cylinders) delimited by surfaces of first or second degree. The user
must combine bodies by boolean operations (addition, intersection and
subtraction) to perform a complete partition of the space of interest into
regions, namely cells of uniform material composition. One important rule to
remember is that inside the space of interest, defined by means of an external
closed body, every point must belong to one and only one region.
Input for the geometry description, which has its own format and rules,
explained in Chap. 9, must be contained between a GEOBEGIN and a GEOEND card.
These two cards follow the normal FLUKA input syntax. An option offered by the
GEOBEGIN command is to read the geometry input from a separate file. Command
GEOEND can be used also to invoke the geometry debugger, a check which is
always strongly recommended.
Geometry input, sandwiched between a GEOBEGIN and a GEOEND card can be placed
anywhere in the input file (before the START command). It is mandatory in all
cases.
An optional command related to geometry is PLOTGEOM. It is used to display
sections of the geometry and needs to read its own input, as explained later.
Materials
Materials in FLUKA are identified by a name (an 8-character string) and by a
number, or material index. Both are used to create correspondences, for
instance between region number and material number, or between material name
and neutron cross section name.
Some materials are already pre-defined. A Table in 5} lists the 25 available
pre-defined materials with their default name, index number, density and atomic
and mass number. The user can either refer to any one of them as it is, or
override it with a new number, name and other properties, or define a new
material. In the latter two cases, the new material definition is done by
option MATERIAL. If the material is not a single element or isotope, but a
compound, mixture or alloy, a command COMPOUND, extended on as many cards as
necessary, is needed to specify its atomic composition. The correspondence
between the material and the composition is set using the same name in the
MATERIAL and in the COMPOUND cards. Note that material names, if low-energy
neutron transport is desired, cannot be assigned arbitrarily but must match one
of the names available in the FLUKA cross-section library (see Table in
Chap. 10}.
Once all the materials to be assigned to the various geometry regions have been
defined (either explicitly with MATERIAL or implicitly in the pre-defined
list), it is necessary to specify of which material each region is made, by
setting a correspondence material index --> region number. This is done by
command ASSIGNMAt.
Command ASSIGNMAt is used also to indicate that a magnetic field exists inside
one or more given regions: in this case a command MGNFIELD is needed to specify
intensity and direction of a constant magnetic field, or a complex one defined
by a user routine as explained below. Note that in practice at least one
ASSIGNMAt command must always be present.
A less common kind of correspondence is set by option LOW-MAT. By default, the
correspondence between a material and a low-energy neutron cross section set
established by name, but in some circumstances this cannot be done, for
instance when two different materials share the same cross section set, or when
two cross section sets have the same name. Option LOW-MAT can be used to set a
different correspondence.
Another FLUKA option concerning the definition of materials is MAT-PROP. It is
used for a variety of purposes: to describe porous, inhomogeneous or gas
materials, to override the default average ionisation potential, to do a rough
temperature re-scaling of thermal neutron cross-sections when no cross-section
set is available at a desired temperature, and to request a call to a special
user routine when particles are transported in a given material.
Setting options
Many FLUKA input options are not used to describe the radiation transport
problem but to issue directives to the program about how to do the
calculations. Other options are used just to select a preferred input format.
We refer to these options as "setting options".
Thanks to a complete and well-tuned set of defaults, setting options are not
always necessary, especially for a beginner or in a preliminary phase of input
preparation. However, an experienced user can often improve considerably the
code performance by a judicious selection of parameters.
Format setting
The default, fixed input format can be replaced by a free format using option
FREE or better GLOBAL. The latter allows to choose free format for both the
normal input and the geometry input separately, and serves also a few other
purposes: it can be used to increase the maximum allowed number of geometry
regions, and to force a calculation to be fully analogue (i.e., simulating
physical reality as directly as possible, without any biasing to accelerate
statistical convergence. A more esoteric capability of GLOBAL, used mainly for
debugging, is to ensure that the random number sequence be exactly reproduced
even in cases where the geometry tracking algorithm has the possibility to
follow different logical paths to achieve the same result.
General setting options
The difficult task of choosing the best settings for a calculation problem is
made much easier by the existence of several "pre-packaged" sets of defaults,
each of which is optimised for a particular type of application. Each set is
chosen by option DEFAULTS, which has to be placed at the beginning of the input
file, possibly preceded only by TITLE or GLOBAL. Several possibilities include
hadrotherapy, calorimetry, pure electromagnetic runs without photonuclear
reactions, low-energy neutron runs without gamma production, and others. One
set of defaults is tuned for maximum precision (but not necessarily great time
efficiency). Reasonable defaults, acceptable for most generic routine
calculations, are provided in case DEFAULTS is missing. In most cases, the user
has the possibility to use some of the other setting options described below,
to override one or more of the defaults provided by the chosen set.
In any case, it is important to check the list of defaults to make sure that
nothing important is missing or has been overlooked. For instance, photonuclear
reactions, which are critical for electron accelerator shielding, are not
provided by any of the available default sets and must be added by the user by
means of the PHOTONUC command.
Another setting option, DISCARD, is used to indicate particles which shall not
be transported. The energy of those particles is not deposited anywhere but is
added up in an accumulator which is printed at the end of the FLUKA standard
output. Of course it is the user's responsibility to see that the discarded
particles and their progeny would not give a significant contribution to the
requested results.
Multiple Coulomb scattering
The concept of multiple scattering is an approximation to physical reality
(condensed history approximation [Ber63], where charged particles undergo a
very large number of single collisions with the atomic electrons, too many to
be simulated in detail except in very special cases. All the theoretical
treatments which have been developed are valid only within certain limits, and
none of them gives rules on how to handle material boundaries and magnetic
fields. FLUKA uses an original approach [Fer91a, based on Molière's theory
[Mol47,Mol48,Bet53,Mol55], which gives very good results for all charged
particles in all circumstances (even in backscattering problems), preserving
various angular and space correlations and freeing the user from the need to
control the particle step length.
Although the default treatment is always more than satisfactory, the user has
the possibility to request various kinds of optimisation, for both
electrons/positrons and heavy charged particles. This can be done by means of
option MULSOPT, which offers also the possibility to switch off completely
multiple scattering in selected materials. The latter is a technique used when
simulating particle interactions in gases of very low density such as are
contained in accelerator vacuum chambers: the simulation is done for a gas of
much larger density and the results are scaled to the actual low density: but
scaling is meaningful only if no scattering takes place.
Another very important feature of option MULSOPT is single scattering, which
can be requested in various degrees at boundary crossing, when the limits of
Molière's theory are not satisfied, and even all the time (but the latter
possibility is to be used only for problems of very low energy, because it is
very demanding in CPU time).
There is also another option connected with multiple scattering, which however
concerns only heavy charged particles such as hadrons and muons: MCSTHRES
allows to set a threshold below which multiple Coulomb scattering is not
performed. However, the CPU time saved is minimal and the option is not
frequently used.
Step length
Another aspect of the condensed history approximation is that charged particle
transport is performed in steps. The finite fraction of the particle energy
which is lost and deposited in matter in each step is an approximation for the
sum of innumerable tiny amounts of energy lost by the particle in elastic and
inelastic collisions.
In early Monte Carlo programs results could depend critically on the size of
the step, mainly due to the inaccurate determination of the path length
correction (ratio between the length of the actual wiggling path of the
particle and that of the straight step connecting the two endpoints). For a
more complete discussion, see [Aar93a,Fas01]. The multiple scattering algorithm
used by FLUKA [Fer91a] provides a robust independence of the results from the
step size, but for problems where a special accuracy is requested, or when
magnetic fields are present, it is possible for the user to override the
default step length. Two options control the maximum fractional energy loss per
step: EMFFIX for electrons and positrons, and FLUKAFIX for muons and charged
hadrons. The second one is seldom used, however, except in problems of very
large dimensions typical of cosmic ray research. Option STEPSIZE is used
instead to limit the absolute length of the step, independent of the energy
lost. Contrary to EMFFIX and FLUKAFIX, it works also in vacuum. While its use
is highly recommended in problems with magnetic fields, to ensure that steps be
smaller than the dimensions of the current regions and of those that border it,
when no magnetic fields are present this option should better be avoided, as it
would imply no obvious advantage and could even downgrade performance.
Energy cut-offs
Setting energy cut-offs, for both transport and production, is an important
responsibility of the user, who is interested in choosing the best compromise
between accuracy and time efficiency. Each of the parameter sets available via
option DEFAULTS, including the basic defaults set which exists when that option
has not been explicitly requested, offers a well-optimised choice for the
corresponding class of applications, with only one exception. But even so, it
is often convenient to override some of the default cut-offs in order to
improve performance. The exception concerns the default particle production
cut-offs for electrons, positrons and photons, which are dependent on other
settings (see EMFCUT below).
Transport cut-offs, or thresholds, are set with command PART-THRes for hadrons
and muons, with EMFCUT for electrons, positrons and photons, and with LOW-BIAS
for low-energy neutrons. Despite the similar functionality of the three
commands, there are important differences in their syntax and in the way the
threshold is implemented for the three families of particles. PART-THRes can
assign different transport thresholds to different particles, but the
thresholds are the same in all materials and regions. When the hadron or muon
energy becomes lower than the relevant threshold, the particle is not stopped
but ranged out in a simplified way. Because the electron and photon cut-offs
are more critical with respect to calculation accuracy, EMFCUT can assign
transport thresholds on a region basis: on the other hand no ranging out is
performed, due to the difficulty to clearly define electron ranges. For
low-energy neutrons, the transport threshold is set by LOW-BIAS also on a
region basis, but as a group number rather than an energy.
Two input commands can set particle production cut-offs, respectively for heavy
particles and for electrons, positrons and photons.
Thresholds for delta ray production by charged hadrons and muons are assigned,
on a material basis, by means of option DELTARAY. Energy transfers to electrons
lower than the threshold are handled in the continuous slowing down
approximation. Production of bremsstrahlung by electrons and of M\oller/Bhabha
secondary electrons is simulated explicitly above thresholds set on a material
basis with option EMFCUT. Defaults for electron and photon production cut-offs
are dependent on other settings in a complex way. Therefore it is recommended
to check the values printed on standard output, or to set EMFCUT production
cut-offs explicitly for each material. Note also that the same EMFCUT command
is used to set both transport and production cut-offs: but the setting is done
by region in the first case and by material in the second.
To complete the list of commands used for cut-off setting, we will mention
THRESHOLd, which is used to set an energy threshold for star scoring. In
principle, a "star" is any high energy inelastic hadron interaction
(spallation) and star density has always been one the quantities which can be
scored by FLUKA. Since a popular technique to estimate induced radioactivity
was based originally on the density of stars produced by hadrons with energies
higher than 50 MeV, the possibility to set a scoring energy limit is provided.
Time cut-offs
For time-dependent calculations, two time cut-off options are available: one
for particle transport, TIME-CUT, and one for scoring, TCQUENCH. While option
TIME--CUT sets a particle-dependent time limit after which the corresponding
particle history is terminated, the limits set by TCQUENCH are assigned to
selected binnings. Scoring contributions to a binning by particles having
exceeded the corresponding time limit are ignored, but particle transport
continues, possibly contributing to other detector scores.
Ionisation energy loss
Transport of charged particles can be done in many ways: without delta ray
production and ionisation fluctuations (continuous slowing down approximation),
with ionisation fluctuations and no delta rays, with delta ray production above
a chosen energy threshold and no ionisation fluctuations below the threshold,
and with both: delta rays above the threshold and ionisation fluctuations below
it. Depending on the application type chosen with option DEFAULTS, different
defaults and thresholds apply, which can be modified by the user by means of
options IONFLUCT, DELTARAY and EMFCUT. Option IONFLUCT is used to request
(restricted) ionisation fluctuations on a material basis. In FLUKA, these
fluctuations are not simulated according to Landau or Vavilov theory but
according to an original statistical approach [Fas97a]. They can be requested
separately for electrons and positrons and for muons and charged hadrons. Delta
ray production thresholds are instead set for the two particle families by two
separate options, which have already been mentioned above in the context of
production cut-offs: EMFCUT and DELTARAY. DELTARAY can be used also to define
(and print) the mesh width of the stopping power tabulations used by the program.
The user has also the possibility to change the default parameters used in the
calculation of stopping power. Command STERNHEIme allows to change the density
effect parameters,and MAT-PROP can set, in addition to several other material
properties, a user-defined average ionisation potential.
Special radiation components or effects
In FLUKA, an effort has been made to implement a full cross-talk between
different radiation components (hadronic, muonic, electromagnetic, low-energy
neutrons, heavy ions, optical photons). However, some components are not
activated by default, and others are only activated in some of the available
default settings. Input options are provided to switch them on and off.
In a similar way, some physical effects may need to be activated, overriding
the chosen defaults. On the other hand, in some cases it can be of interest
(but possibly dangerous!) to ignore some effects. A number of commands are
available for these purposes.
Radiation components
High-energy hadrons and muons are always generated and transported, except with
defaults settings EM-CASCA and NEUTRONS (however, they cannot be requested
overriding these two defaults). To suppress them, one can use command DISCARD.
Option EMF (E_lectroM_agnetic F_luka) can be used to request electron, positron
and photon transport, and also to ask for its suppression (the latter could be
obtained also by discarding electrons, positrons and photons by means of DISCARD).
Low-energy neutron transport (if not already on by default) can be activated
with option LOW-NEUT. Explicit suppression is not possible: but the same effect
can be obtained using option LOW-BIAS to set a cut-off at energy group 1.
Heavy ion transport (only ionisation energy loss, without nuclear interactions)
is implicit with some default settings, while with others it is not available.
Details can be found in the description of command EVENTYPE. The same command
can be used also to request heavy ion interactions using different event
generators: in this case the corresponding libraries must be linked.
A special option, HI-PROPErt, is necessary to define the properties of a heavy
ion primary, since the particle type input via the BEAM command can only be a
generic heavy ion.
Generation and transport of optical photons is available only on explicit user
request. Activation (and deactivation) are requested via OPT-PROD (for
Cherenkov, transition radiation or scintillation photon production) and
OPT-PROP (transport).
Physics effects
Some physical effects are automatically activated, but only when certain
default sets are in force (see option DEFAULTS), and can be switched on or off
with appropriate commands. The command to simulate fluorescence is EMFFLUO,
that for Rayleigh scattering and Compton binding corrections is EMFRAY, while
for multiple scattering there are MULSOPT and MCSTHRESh which we have already
introduced above. High-energy effects such as production of bremsstrahlung and
electron pairs by heavy charged particles (in particular muons) are regulated
by option PAIRBREM.
A few physical effects need to be requested explicitly, whatever the defaults.
These are photon polarisation (command POLARIZA), polarisation of pion, kaon
and muon decays (command PHYSICS), photonuclear reactions (PHOTONUC), and muon
hadronic interactions via virtual photons (MUPHOTON).
In some cases, it is also possible to switch off some important effects to
study the relative importance of different processes. Command THRESHOLd allows
to set a lower energy limit for hadron elastic scattering and inelastic
reactions, and EMFCUT does the same with various kinds of electron and photon
interactions. The user must bear in mind, however, that results obtained
suppressing effects which are critical for the development of the
electromagnetic or hadronic cascade are unlikely to be physically correct.
Scoring options
Any result in a Monte Carlo calculation is obtained by adding up the
contributions to the "score", or "tally" of a detector defined by the user.
A detector is the Monte Carlo equivalent of a measurement instrument. Each
"estimator" (detector type) is designed to estimate one or more radiometric
quantities, and the final score is a statistical estimation of the average
value of the corresponding population. As in experimental measurements, it is
possible to calculate a standard deviation by running several independent
calculations.
No default detector is available: each scoring option must be explicitly
requested. There are different input options corresponding to different types
of detector. The simplest is SCORE which provides energy deposition
(proportional to dose) or star density in every region of the geometry. "Stars"
is an old name for inelastic hadron reactions which derives from early
experiments with nuclear emulsions.
The same quantities can be scored in a uniform spatial mesh independent of
geometry, called a "binning", by means of option USRBIN. There are several
types of binnings: Cartesian, 2D-cylindrical, 3D-cylindrical and even more
complex phase space structures. In addition to dose and star density, it is
possible to use USRBIN to score particle fluence distributions in space. USRBIN
results are often displayed as colour plots where each colour corresponds to a
pre-defined range of values. A post-processing program for this purposes
(PAWLEVBIN) is available in the directory $FLUPRO/flutil, and a GUI interface
can be downloaded from the FLUKA website www.fluka.org.
Fluence, averaged over the volume of a given geometry region, can be calculated
with options USRTRACK and - less often - USRCOLL. The first is a "track-length
estimator" (it estimates fluence as volume density of particle trajectory
lengths), and the second is a "collision estimator" (fluence is estimated as
volume density of collisions weighted with the particle mean free path). Of
course, USRCOLL can be used only in a region of matter, while USRTRACK works
also in vacuum. Both options provide fluence differential energy spectra.
Another common scoring option is USRBDX, which also calculates fluence, but
averaged over the boundary between two geometry regions. It is a "boundary
crossing estimator", which estimates fluence as the surface density of crossing
particles weighted with the secant of the angle between trajectory and normal
to the boundary at the crossing point. Option USRBDX can also calculate
current, i.e. a simple counter of crossings, not weighted by inverse cosine:
but despite a widespread credence, current is only seldom a quantity worth
calculating. The results of USRBDX can account on request for particles
crossing the boundary from either side or from one side only, and are in the
form of double-differential energy and angular spectra. The angle considered
is again that with the normal at the crossing point.
USRYIELD is a multi-purpose estimator option, which can estimate several
different double-differential quantities. The main one is an energy-angle
double-differential yield of particles escaping from a target, the angle in
this case being with respect to a fixed direction. Energy and angle can be
replaced by many other variables which are mostly of the same kind, such as
momentum and rapidity. But it is possible also to score yields as a function of
charge and LET (linear energy transfer).
Production of residual nuclei can be obtained with command RESNUCLEi.
The results, which are closely related to induced activity and dose rate from
activated components, may include nuclei produced in low-energy neutron
interactions, provided the corresponding information is available in
the neutron cross section library for the materials of interest.
Event by event scoring options
Typical particle physics applications, in particular calorimetry, require
separate scoring event by event (that is, results are printed after each
primary particle history). Two commands, EVENTBIN and EVENTDAT, are
respectively the event-equivalent of USRBIN and SCORE which have been
introduced before. A third command, DETECT, allows to score event by event
energy deposition simulating a detector trigger, defining coincidences and
anticoincidences. All these options are incompatible with any biasing. It is
suggested to use command GLOBAL to make sure that the run will be completely
analogue.
Scoring modifying options
There are a few commands which are used to modify some of the scoring options
already described. TCQUENCH, which has already been shown to define a time
cut-off, can be used also to apply a quenching factor (Birks factor) to energy
deposition scored with USRBIN or EVENTBIN. ROT-DEFI and ROTPRBIN allow to
define roto-translation transformations for binnings not aligned with the
coordinate axes. ROTPRBIN can be used also to set the binning storage
precision: a space saving feature, which is useful mainly when scoring event by
event with EVENTBIN.
Options to handle radioactive decay
It is possible to transport and score in the same run also the beta and gamma
radiation emitted in the decay of radioactive nuclei produced in the hadronic
or electromagnetic cascade. Several options are available for this purpose:
RADDECAY is used to request the simulation of radioactive decays, IRRPROFIle
defines a time profile for the intensity of the primary particles, DCYTIMES
requests one or more decay times at which the desired scoring shall occur, and
DCYSCORE associates selected scoring detectors to the decay times so requested.
Biasing options
When run in fully analogue mode, FLUKA allows the user to study fluctuations
and correlations, and to set up a direct simulation of physical reality where
all moments of phase space distributions are faithfully reproduced. On the
other hand, in the many applications where only quantities averaged over many
events are of interest, it is convenient to use calculation techniques
converging to the correct expectation values but reducing the variance (or the
CPU time, or both) by sampling from biased distributions. This is especially
useful in deep penetration calculations, or when the results of interest are
driven by rare physical interactions or cover a small domain of phase space.
FLUKA makes available several biasing options. Some are easy to use, but others
require experience and judgment, and often a few preliminary preparation runs
are needed to optimise the biasing parameters.
Simple biasing options
The easiest biasing command is fittingly called BIASING. It provides two
different kinds of variance reduction: Multiplicity Reduction and Importance
Biasing, which is based on the two complementary techniques Geometry Splitting
and Russian Roulette (RR).
Splitting and Russian Roulette are two classical variance reduction techniques,
which are described in most textbooks on Monte Carlo [Car75, Lux91].
A detailed description of how they are implemented in FLUKA is available in a
Note to option BIASING. Importance biasing consists in assigning an importance
value to each geometry region. The number of particles moving from a region to
another will increase (by splitting) or decrease (via RR) according to the
ratio of importances, and the particle statistical weight will be modified
inversely so that the total weight will remain unchanged. In this way, the user
can strive to keep the particle population constant, making up for attenuation,
or to make it decrease in regions far from the detectors where there is a lower
probability to contribute to the score. In FLUKA, importance biasing can be
done separately for hadrons/muons, electrons/positrons/photons and low-energy
neutrons.
Multiplicity Reduction is a simple technique which was introduced for the first
time in FLUKA (now it has been adopted also by other programs), in order to
decrease the computer time needed to simulate a very high energy hadron
cascade. At energies of several hundred GeV and more, the number of
secondaries produced in a hadron-nucleus interaction is very large and the
total number can increase geometrically in the following interactions,
requiring an unacceptably long computer time. Since many secondaries are
particles of the same kind and with a similar angular and energy distribution,
the user can decide to follow only a region-dependent fraction of them.
A biasing option performing a similar multiplicity reduction on electromagnetic
showers is EMF-BIAS. In this case the technique is known as Leading Particle
Biasing and consists in sampling only one of the two secondary particles which
are present in the final state of most electromagnetic interactions. The
secondary of higher energy is sampled with higher probability. The EMF-BIAS
option can be tuned per region below user-defined energy thresholds and is used
very often in shielding calculations for high-energy electron accelerators. The
same command can be used also to bias the electron and photon mean free path
for various types of interaction, for instance to enhance the probability of
interaction in a thin or low-density target.
In a similar way, option LAM-BIAS can be used to increase the probability of
hadronic interactions, and in particular photohadron reactions. These are the
dominant reactions for high-energy electron accelerator induced activity and
shielding design, but because their cross section is small compared to that of
electromagnetic effects, analogue sampling would be very inefficient. The same
command can help to get a higher probability of hadron interaction in a thin
target. It can also be used to bias a particle decay length (for instance, to
enhance muon or neutrino production) and the emission angle of the decay
secondaries in a direction indicated by the user.
Weight window options
The weight window is a very powerful biasing technique, not based on relative
importances, but on the absolute value of particle weight. The user sets an
upper and a lower limit for the particle weight in each geometry region,
possibly tuned per type of particle and energy. Splitting and RR will be
applied so that the weight of all relevant particles will have a value between
the two limits. In addition to controlling the particle population, this
technique helps also to "damp" excessive weight fluctuations due to other
biasing options.
Its use is not as easy as that of importance biasing, because it is necessary
to have at least a rough idea of what are the average weights in different
regions. Special splitting and RR counters can be printed on request to help
setting the window parameters setting SDUM = PRINT in command BIASING. An
explanation about the meaning of the counters can be found in Chap. 9}. Weight
window setting is done in FLUKA by three input commands: WW-FACTOr, WW-THRESh
and WW-PROFIle. The first two commands must be used together: WW-FACTOr sets
the upper and lower weight limits per region, while WW-THRESh defines energy
limits within which the weight window must be applied, and the particles to
which it is to be applied. The third option is reserved to low-energy neutrons,
whose transport characteristics often require a more detailed biasing pattern:
WW-PROFIle allows indeed to tune the weight window by neutron energy group.
Biasing options for low-energy neutrons
The special multigroup transport structure used by FLUKA for low-energy
neutrons calls for some biasing options specific to these particles. We have
just introduced the weight window command WW-PROFIle. Two more options are
LOW-BIAS, which has already been mentioned before in the context of energy
cut-offs, but which is used also to set a user-defined non-analogue absorption
probability, and LOW-DOWN, by which it is possible to bias neutron
thermalisation (downscattering). The latter, however, is an option recommended
only to users with a good knowledge and experience of neutronics.
Calls to user routines
The purpose of several FLUKA input options is to trigger calls to user routines
(user routines are described in Chap. 13}). One of the most important ones is
SOURCE, which makes FLUKA get the characteristics of its primary particles from
subroutine SOURCE instead of from options BEAM and BEAMPOS. This option allows
to pass to the subroutine several parameters, thus allowing to drive it from
input without the need to re-compile it. Note that even when using a
user-written source, it is still necessary to have in input a BEAM card
indicating the maximum expected energy of a primary particle, so that the
program can prepare appropriate cross section tables. If command SOURCE is
present, but no SOURCE routine has been linked, the default one in the FLUKA
library will be called, which leaves unchanged the particle type, energy,
position etc. as defined by BEAM and BEAMPOS.
Command USERWEIG can call 5 different user routines used to modify a scored
quantity (at the time of scoring). The routines are:
* FLUSCW is a function returning a multiplication factor for fluences.
A typical application is to convert a fluence to dose equivalent.
* COMSCW is a function returning a multiplication factor for star densities
and doses. Common application: converting energy deposition to dose.
* USRRNC is a subroutine providing a convenient user hook for scoring
residual nuclei.
* ENDSCP is a subroutine performing a displacement of the energy deposited
in a particle step, for instance to account for an instrument drift.
* FLDSCP is a subroutine performing a displacement (drift) of the track
corresponding to a particle step.
Complex magnetic fields can be defined or read from a map by a user routine
MAGFLD. Calls to the routine are activated by command MGNFIELD.
A collision file (also called a collision tape, or a phase space file) is a
file on which FLUKA writes on request details of user-selected events:
particle trajectories, energy deposition events, source particles, boundary
crossings, physical interactions, etc. This task is performed by subroutine
MGDRAW, which is called if option USERDUMP is requested in input. The default
routine present in the FLUKA library can be driven as it is, without
re-compilation, by setting some of the USERDUMP parameters, but can also be
modified and re-compiled to adjust to specific needs of the user. A typical
simple task is to draw particles trajectories. Another frequent application of
USERDUMP is to perform a calculation in two steps, where the second step uses
the collision file as a source. In principle it is also possible to use
subroutine MGDRAW for scoring, for instance by interfacing it to some
histogramming package, as it is customary in some other Monte Carlo programs.
However, in general this is discouraged in FLUKA, unless the desired quantity
cannot be scored via the standard FLUKA input commands, which is very rare. The
FLUKA scoring options are indeed highly optimised and well checked against
possible errors and artefacts. It is very unlikely that a user might be able to
achieve in a short time the same level of reliability. In any case,
user-written scoring via MGDRAW MUST be avoided in all runs where biasing is
present, because to handle correctly the particle weights requires other FLUKA
tools which are not available to the normal user.
Two more input options activating calls to user routines are USRICALL and
USROCALL. They allow the user to issue a call respectively to an initialisation
routine USRINI and to an output routine USROUT.
Miscellaneous
Option COMMENT is not often used. Its main function is to insert a certain
number of comment lines in the input file, but these are now most often
replaced by lines with an asterisk in column 1. The same command can be
used to override the default name (fluka.stop) of the "stopping file" which
can terminate a FLUKA run before the requested number of histories is reached
(see Note to option START). In addition, it can communicate to the program
information about the computer platform used, so that it will printed in
output. This command can also be used to start different, independent random
number sequences, allowing to run several identical jobs in parallel.
Much more important is command RANDOMIZe, which starts a new independent
random number sequence. It can be omitted only in a first run, but it is
compulsory if a sequence of independent runs is desired in order to calculate
statistical errors.
Command STOP, inserted at any point in the input file, interrupts the reading.
Any further input card is ignored. It may be made to follow a PLOTGEOM command
and the corresponding input, so that the Plotgeom program is executed, but no
FLUKA simulation is started.
Finally, command START is always needed to give the program the signal to begin
the calculation. The command includes the number of primary histories to be
simulated. A STOP command may follow, but it is not necessary since it is
assumed to be present by default.
