Description of FLUKA input options¶

There are more than 80 option keywords available for input in FLUKA. A summary is given in Introduction to the FLUKA input options, 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 Sections ASSIGNMAt to WW–THRESh, 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
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
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
INVCOMPT: activates inverse Compton scattering in vacuum for a black-body photon bath or spherical photon source
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)
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 and electron interactions with nuclei , and photomuon production
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)
SCORE: defines the energy deposited or the stars to be scored by region
SOURCE: tells FLUKA to call a user-written source routine
SPECSOUR: calls special pre-defined source routines (synchrotron radiation photons, particles created by colliding beams or by cosmic ray sources, USRBIN as source, multiple beam spots)
SPOTBEAM: defines multiple beam spots in the corresponding special source case
SPOTDIR: defines multiple beam spots in the corresponding special source case
SPOTPOS: defines multiple beam spots in the corresponding special source case
SPOTTRAN: defines transformations for multiple beam spots
SPOTTIME: defines timre intervals for multiple beam spots
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
SYNCRAD: controls synchrotron radiation emission and sets the maximum magnetic field by region
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
USERWEIGht: 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

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:

the radiation source
the geometrical layout
the materials
the requested results
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 (see 9.1).

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 on, 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 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.

BEAMPOS can be used also to define sources extended in space (spherical, cylindrical, etc.) Both BEAM and BEAMPOS commands can be placed anywhere in the input file, before the START command.

Some special particle sources can be defined with command SPECSOUR: synchrotron radiation photons, cosmic rays, particles produced by colliding beams.

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 (see SOURCE: user-written 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 Combinatorial Geometry, 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 at.

The FLUKA reference frame¶

The FLUKA geometry, described in Combinatorial Geometry, and all particle space coordinates (position x, y, z, and corresponding direction cosines) are based on a right-handed Cartesian reference frame. The origin of the frame (0, 0, 0) and the direction of the three perpendicular axes can be chosen arbitrarily by the user, but by default a particle beam and its space characteristics (angular divergence, transversal profile, polarisation) are referred to a beam direction coincident with the z-axis of the geometry frame of reference. A different beam direction can be specified by means of command BEAMAXES: see a description of the command and especially the corresponding Notes.

Also some scoring structures (binnings, see command USRBIN) are defined as meshes parallel to the reference axes, and in the case of cylindrical binnings the basic axis is again the z-axis. In a similar way, some geometrical bodies (planes, parallelepipeds, infinite cylinders) are described by their orientation with respect to the axes. But rototranslation transformations, defined by commands ROT-DEFIni and ROTPRBIN, allow the user to input binnings and geometrical bodies with arbitrary orientation with respect to axes.

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. Table 5.3 on lists the 25 available pre-defined materials with their default name, index number, density and atomic number and 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 10.3 on).

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 :math:`rightarrow` 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 in Calls to user routines. 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 is 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.

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 [Fas01]), 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 (gas bremsstrahlung): 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: MCSTHRESh 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 region 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 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øller/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.

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.

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 (Energy 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 (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 and 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 (ElectroMagnetic Fluka 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). See respectively and.

Physics effects¶

Some physical effects are automatically activated, but only when certain default sets are in force (see option DEFAULTS on and Table 7.1 on), 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 in Multiple Coulomb scattering. 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 POLARIZAti), 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 to the boundary 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 (see Table 10.3 in The FLUKA neutron cross section library).

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 anti-coincidences. 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 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.

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 on. 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 (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, e.g. 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 on. 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 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.

Calls to user routines¶

The purpose of several FLUKA input options is to trigger calls to user routines (user routines are described in User routines). 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 USERWEIGht 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 (FLUSCW: weighting fluence, current and yield). A typical application is to convert a fluence to dose equivalent.
COMSCW is a function returning a multiplication factor for star densities and doses (COMSCW: weighting deposited energy or stars). Common application: converting energy deposition to dose.
USRRNC is a subroutine providing a hook for user controlled scoring of residual nuclei (USRRNC: USeR 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 (ENDSCP: ENergy density DiStributed — Change of Positions).
FLDSCP is a subroutine performing a displacement (drift) of the track corresponding to a particle step (FLDSCP: FLuence DiStributed — Change of Positions).

Complex magnetic fields can be defined or read from a map by a user routine MAGFLD (MAGFLD: definition of a magnetic field. 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 (MGDRAW: general event interface, 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 (USRINI: USeR INItialisation) and to an output routine USROUT (USROUT: USeR OUTput). The third one activates a call to routine USRGLO (USRGLO: USeR GLObal settings), which performs a global initialisation before any other made by FLUKA.

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. This command can also be used to start different, independent random number sequences, allowing to run several identical jobs in parallel.

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.

Input commands