[ <--- prev -- ]  [ HOME ]  [ -- next ---> ]

[ full index ]

7 Description of FLUKA input options

There are more than 80 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
  AUXSCORE   allows to filter scoring detectors of given estimator type with
             auxiliary (generalized) particle distributions and dose equivalent
             conversion factors, and with isotope ranges

  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

  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

  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 cutoffs 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)
  GCR-SPE    initialises Galactic Cosmic Ray calculations
  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 cutoff 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 cutoffs 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
  SPECSOUR   calls special pre-defined source routines (particles created by
             colliding beams, or cosmic ray sources)
  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
  USRGCALL   calls user-dependent global initialisation
  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

7.1 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.

7.2 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.

7.3 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.

7.4 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, atomic number and atomic weight. 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 set a threshold energy for DPA calculations and to request a call to a special user routine when particles are transported in a given material.

7.5 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.

7.6 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.

7.7 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.

7.8 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.

7.9 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.

7.10 Energy cutoffs

Setting energy cutoffs, 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 cutoffs in order to improve performance. The exception concerns the default particle production cutoffs for electrons, positrons and photons, which are dependent on other settings (see EMFCUT below).

Transport cutoffs, 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 cutoffs 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 cutoffs, 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 cutoffs 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 cutoffs explicitly for each material. Note also that the same EMFCUT command is used to set both transport and production cutoffs: 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 cutoff 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.

7.11 Time cutoffs

For time-dependent calculations, two time cutoff 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.

7.12 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 cutoffs: 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.

7.13 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.

7.13.1 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 cutoff 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 IONTRANS. 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).

7.13.2 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 and Doppler broadening 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.

7.14 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.

7.15 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.

7.16 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 cutoff, 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.

7.17 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.

7.18 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.

7.18.1 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.

7.18.2 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.

7.18.3 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 cutoffs, 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.

7.19 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.

Three more input options activating calls to user routines are USRICALL, USROCALL and USRGCALL. The first two allow the user to issue a call respectively to an initialisation routine USRINI and to an output routine USROUT. The third one activates a call to a routine USRGLO, which performs a global initialisation before any other made by FLUKA.

7.20 Miscellaneous

Command RANDOMIZe 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.