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 7}, option GLOBAL.
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 free format "name" based
- estimator 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, notice 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 commands such as COMMENT or
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 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:
COMMENT:
an optional number of cards following the COMMENT command are considered
as comments and are merely reproduced in the output. In case COMMENT is
issued with SDUM keyword = INPUT or MODEL, one single card must follow.
OPEN is generally followed by the name of the file to be opened (scratch
files are an exception)
DETECT, USRBIN, USRBDX, USRCOLL, USRTRACK, USRYIELD, EVENTBIN, EVENTDAT:
data concerning user-defined estimators and binnings extend in general
over two cards. The second ("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
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.
RANDOMIZe:
depending on user's choice, the RANDOMIZe command may be followed
by a card giving the number of calls to the random number generator.
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 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 below in the description of
option ASSIGNMAt, 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). An
example can be found in the description of option EMF-BIAS.
"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.
Physical units
Physical units consistently used in FLUKA input and output are:
distance cm (and derived units cm2, cm3 for areas and volumes)
energy GeV
Exceptions:
eV is used for average ionisation potential input by option
MAT-PROP
g/(MeV cm2) are used for Birks coefficients input by option
TCQUENCH.
momentum GeV/c
temperature degree Kelvin
solid angle sr (exception: degrees may be used, on user's request, with
option USRYIELD)
magnetic field T
electric field kV/cm
time s (option TCQUENCH) or ns (option TIME-CUT)
The input preprocessor
----------------------
FLUKA, since 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. Presently the functionality
is limited to 2 types of directives, DEFINITION and CONDITIONAL, and probably
will be expanded in the future. The preprocessor is a particularly useful way
to include or remove blocks of input cards, allowing a more flexible and easy
organization of an input file. 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 10 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:
#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.
#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
