General features of FLUKA input

The input of FLUKA consists of a text file​ containing a sequence of option lines (often called “cards”)​ which are followed sometimes by data cards​ specific of the option (or command)​ requested. Option cards​ have all the same structure, and can be read in fixed format​ or in free format​. A description of free format is given in Description of FLUKA input options, options GLOBAL.​ and FREE.​.

CODEWD, (WHAT(I), I = 1, 6), SDUM

(the fixed format is A8, 2X, 6E10.0, A8)

where:

  • CODEWD is the option keyword​

  • The WHAT-parameters are numerical data (or logical data in numerical form)​

  • SDUM, if present, contains character data (only in two exceptional cases, the STERNHEIme ​ and WW–FACTOr​ options, SDUM contains numerical information)​

Since 2006, a very practical and appealing feature has been introduced: input by names​. This means that the numeric WHAT fields can be filled with pre-defined or user-defined names, such as:

  • material names

  • particle or generalised particle names

  • region names, if the geometry too is written in name format

  • estimator names

  • detector/binning names

Names must be at most 8 character long with the exception of detector names (estimator options USRBDX, USRTRACK, USRCOLL, USRBIN, USRYIELD, RESNUCLEi) which can be 10 character long. Leading and trailing blanks are automatically stripped, and the input parser is case sensitive.

A special name (@LASTMAT, @LASTPAR, @LASTREG) can be used corresponding to the largest material number, particle id, and region number respectively. ​​ ​

Name values and numeric values can both be used in the same input file, since the program is able to distinguish a numeric field from a character field. For this reason, names that can be interpreted as numbers must be avoided. This means that old numeric inputs need no modification. Fully-numeric interpretation, however, can be forced by means of the GLOBAL card.​

Due to the introduction of input by names, input data cards are no longer interpreted in the same order as in the input file, therefore the echo on standard output will look different from the original input.

When using numeric fields, note that even if the values to be assigned to WHAT-parameters were logically integers, because of the format used they must be given with a decimal point.

The order​ of the input cards is almost free, with the following exceptions:

  • GLOBAL declarations​, if present, must precede any executable option.

  • Option DEFAULTS​ must be issued at the very beginning of input. It can be preceded only by a GLOBAL card and by command TITLE.

  • The START​ command initiates execution. While old versions of FLUKA were allowing multiple re-starts, only the first START command is executed now. Thus any input given after START is ignored, with the exception of USROCALL​ and STOP.

  • The STOP​ command stops the execution of the program. Thus any input present after STOP is ignored.

  • Some option cards must or can be immediately followed by a variable amount of information, not always in the standard format indicated above. These are:

    OPEN​ is generally followed by the name of the file to be opened (scratch files are an exception). See.
    DETECT, USRBIN, USRBDX, USRCOLL, USRTRACK, USRYIELD, EVENTBIN, EVENTDAT:  data concerning user-defined detectors and binnings extend in general over two cards​. The second card (“continuation card”) must ​ come after the first, but doesn’t need to follow it immediately. A continuation card may be needed also for option GEOEND​, when used to invoke the geometry debugger.  Input included between GEOBEGIN and GEOEND​:  geometry data must be given in a well-defined order and in a special format between a GEOBEGIN and a GEOEND definition (but the LATTICE​ and VOXELS​ geometry option, and the GEOBEGIN​ and GEOEND​ cards themselves follow the normal FLUKA format convention).  PLOTGEOM:
    Unless a different logical input unit is specified, the call to the Plotgeom​ program must be followed immediately by the Plotgeom input, in special format.  TITLE​:  the card following the TITLE command is considered as the title of the run and is reproduced in the output.

  • for old, fully numeric input format only:

    • In some cases, the MAT–PROP​ option must be requested after the corresponding MATERIAL card.

    • The PLOTGEOM​ command must be issued after the geometry input, and, in case the user chooses to plot only boundaries between different materials, it must come also after all the ASSIGNMAt cards.  It is also recommended that PLOTGEOM be issued before any biasing and any other option which makes use of permanent and/or temporary storage.

Most definitions have some default values​. If these are acceptable, it is not compulsory that the corresponding option card appear explicitly in the input sequence. Furthermore for most WHAT and/or SDUM parameters a default value (that may be different from the default value when the definition has not been input) is applied if the corresponding field is left blank (or set = 0.0) in the input card.

Several option cards may appear more than once in the input sequence​. In most cases, each of such additional cards obviously adds more definitions to those already given, provided they are different and not contradictory. In case of conflict, the last given generally overrides the previous one(s). This feature may be successfully exploited in the numerous cases where whole arrays are assigned according to the scheme

“From …to …in step of …” (corresponding to a Fortran DO-loop)

making the input more compact​. An example can be found in the description of option ASSIGNMAt, Note 2), which is used to set a one-to-many correspondence between material numbers and region numbers.

In most cases of such “DO-loop” assignments, especially when the same option card can be used to assign a value to more than one quantity, a blank or zero field does not assign the default value but leaves the previously given value unchanged. To remove any possible ambiguity, resetting the default value​ needs then to be done explicitly (generally -1. has to be input in such cases).

“DO-loop” assignments can be used also when the input is name-based, since the program replaces each name by the corresponding numerical index. The correspondence can be found by examining the output from a short test run: however, it must be remembered that adding a new material, or a new region, will change the numerical sequence unless the new item is issued as the last of material or region definitions. In this case, if the “DO-loop” indicates all materials, or all regions, using the generic names @LASTMAT​ and @LASTREG​ makes a modification of the assignment definition unnecessary.

All defaults and exceptions are listed under the description of each FLUKA input option. Different defaults, tuned to the type of application of interest, can be specified using the option DEFAULTS ​.

The input preprocessor

FLUKA, since version 2005, comes bundled with an internal preprocessor, a simplified version of a C-like preprocessor. The preprocessor can modify the input file before it is executed with the use of conditions and can allow for parametric expressions to be used in the input cards. Presently the functionality is limited to 3 types of directives, definition​, conditional​ and include​. The preprocessor is a particularly useful way to include or remove blocks of input cards, allowing a more flexible and easy organisation of an input file, and to parameterize input parameters allowing for an easy an safe way of varying them just modifying a #define statement. One can write the input file around a few directives to allow easier debugging, changing thresholds, biasing and scoring cards for the final production.

Syntax

​ All preprocessor directives​ are single lines starting with the # character in the first column and can appear anywhere in the input file, either between normal input cards or inside the geometry definition (inline or externally defined). Each identifier can be up to 40 characters in length.

Definition of Constants

With the definition directives one can define identifiers​ to be used later for inclusion or removal parts of the input file, or for defining a numeric or character value to be used later in one or more of the input cards:

#define [identifier_name]

defines [identifier_name] without giving it a value. This can be used in conjunction with another set of directives that allow conditional execution.

#define [identifier_name] [value]

defines [identifier_name] giving it a value [value]. [value] can be a numeric or character value and its definition can be up to 40 characters in length. This can be used in conjunction with another set of directives that allow conditional execution, or to assign the value [value] anywhere in the input cards, geometry included, by referencing to it as $[identifier_name].

Examples:

#define Ekbeam   100.0
#define Beampart PROTON
...
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
BEAM        -$Ekbeam                                                  $BeamPart
...
#define Zbeam -100.0
...
BEAMPOS          0.0       0.0    $Zbeam
...
#define Xbox   +10.0
#define Ybox   +20.0
#define Zbox   +50.0
...
RPP  TargBox  -$Xbox $Xbox -$Ybox $Ybox -$Zbox $Zbox
...
#define Targmat IRON
...
ASSIGNMAt   $Targmat       1.0  @LASTREG
...

The following names [identifier_name] are predefined (be careful they are case sensitive):

  • Pipipi: \(\pi\) (3.1415…)

  • Minute: minute (60 s)

  • Hour: hour (3600 s)

  • Day: day (86400 s)

  • Week: week (604800 s)

  • Month: month, 1/12 of a mean tropical year (365.242374/12 \(\times\) Day s)

  • Year: mean tropical year (365.242374 \(\times\) Day s)

#undef [identifier_name]

deletes any previously defined [identifier_name].

Conditional directives

​ With the conditional directives one can include or remove parts of the input file before execution. The #if, #elif, #else blocks must be terminated with a closing #endif. There is a maximum of 10 nesting levels that can be used.

#if [identifier_name]
...
#elif [identifier_name]
...
#else
...
#endif

The #if and #elif (else-if) directive is followed by an identifier. If the identifier is defined then the statement evaluates to true, otherwise to false.

Example:

#define DEBUG
#define PLOT1
...
#if DEBUG
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
GEOEND         100.0     100.0     100.0    -100.0    -100.0    -100.0          DEBUG
GEOEND          50.0      50.0      50.0                                        &
#else
GEOEND
#endif
...
#if PLOT1
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
PLOTGEOM                1.0               -2000.0
MBWD6L1
    -100.0       0.0  -21620.0     100.0       0.0  -21250.0
       1.0       0.0       0.0       0.0       0.0       1.0
    -100.0       0.0  -21200.0     100.0       0.0  -20800.0
STOP
#endif

Include directive

​ The include directive switches the input stream from the original input file to a different file, and back to the original file after an end-of-file is met. It can be applied also to geometry input. Include directives can be nested at multiple levels.

#include [path/filename]

where “path” can be an absolute path, or a relative path (relative to the “launching” directory).

Example:

#include /home/geometries/target2.geom
#include frontplanes.geom

Parametric expressions

​ The parametric expressions allow to use symbolic algebra in the definition of input parameters. They are an extension of the definition directives Definition of Constants where instead of defining a numeric or character value, the user can define a complex arithmetical expression which can make use of various mathematical operators and functions and/or of previously defined values.

#define [identifier_name] [expression]

defines [identifier_name] giving it the value corresponding to the evaluation of the mathematical expression [expression]. The definition of [expression] can be up to 60 characters in length and cannot contain any blank character. [expression] can make use of previously defined [identifier_name]s, of the mathematical operators “+”, “-”, “*”, “/” and “^” (power), and of the following standard (fortran) mathematical functions (please note that they are case sensitive):

  • Sin([argument])

  • Cos([argument])

  • Tan([argument])

  • Exp([argument])

  • Log([argument])

  • Abs([argument])

  • Sind([argument])

  • Cosd([argument])

  • Tand([argument])

  • Asin([argument])

  • Acos([argument])

  • Atan([argument])

  • Sqrt([argument])

  • Sinh([argument])

  • Cosh([argument])

  • Asind([argument])

  • Acosd([argument])

  • Atand([argument])

  • Asinh([argument])

  • Acosh([argument])

The function argument [argument] must be enclosed in parentheses as shown above, and can be a simple numerical factor, or an [identifier_name], or another mathematical expression. The expression [expression] can contain several levels of nested parentheses, and it is evaluated according to the rules of symbolic algebra.

The value eventually assigned to an [identifier_name] defined by means of an expression [expression] is echoed on the output file, and on a special copy of the input file ([input name]-echo.inp) which is automatically generated in the directory from where FLUKA has been launched and which contains only the active parts of the input. The creation or not of the echo input file can be controlled by means of the environmental variable FLUKAECHO. If FLUKAECHO is set to y/Y/Yes/yes/1 the echo input file is always created and retained, if FLUKAECHO is set to n/N/No/no/0 the echo input file is never created. The default action (FLUKAECHO undefined or with an invalid value) is to create a temporary echo input file and retain it if there is at least one parametric expression in the input, deleting it otherwise.

Examples:

#define Pbeam        7000.0
#define Zbeam        1.0
...
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
BEAM          $Pbeam                                                  PROTON
...
#define Km           100000.0
#define RadCurv      27.0*Km/2.0/Pipipi
...
#define RadInner     RadCurv-100.0
#define RadOuter     RadCurv+100.0
...
ZCC     LHCinner   0.0   0.0  $RadInner
ZCC     LHCouter   0.0   0.0  $RadOuter
...
#define MagnNumb     1000.0
#define MagChord     2.0*RadCurv*Sind(360.0/MagnNumb/2.0)
...
RCC     Magnet     0.0 0.0 0.0 $MagChord 0.0 0.0 50.0
...
#define AvBField     Pbeam/RadCurv/Zbeam/2.99792458E-03
...
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
MGNFIELD        30.0       0.1      0.75       0.0       0.0 $AvBField
...