1
*====================================================================*
* *
* *
* *
* *
* FFFFF L U U K K AAA 222 000 000 666 *
* F L U U K K A A 2 2 0 0 0 0 6 6 *
* F L U U K K A A 2 0 0 0 0 6 *
* FFFF L U U KK AAAAA === 2 0 0 0 0 6666 *
* F L U U K K A A 2 0 0 0 0 6 6 *
* F L U U K K A A 2 0 0 0 0 6 6 *
* F LLLLL UUU K K A A 22222 000 000 666 *
* *
* http://www.fluka.org *
* *
* Copyright (c) 1989-2006 by INFN and CERN *
* *
* All rights reserved *
* Main authors: A.Fasso`, A.Ferrari, J.Ranft, P.R.Sala *
* Contributing authors: G.Battistoni, F.Cerutti, T.Empl, *
* M.V.Garzelli, V.Patera, S.Roesler, *
* V.Vlachoudis *
* *
* 2006 version of the FLUKA code by : *
* *
* Alberto Fasso` - SLAC *
* fasso@slac.stanford.edu *
* *
* Alfredo Ferrari & Paola Sala - CERN/INFN Milan *
* Alfredo.Ferrari@cern.ch, Paola.Sala@mi.infn.it *
* Alfredo.Ferrari@mi.infn.it, Paola.Sala@cern.ch *
* *
* Johannes Ranft - Siegen University *
* Johannes.Ranft@cern.ch *
* *
*====================================================================*
1
09 September 2006
Present (active) authors (since FLUKA89):
A. Fasso`, Stanford Linear Accelerator Center, 2575 Sand Hill Road,
Menlo Park, CA 94025, USA
A. Ferrari, CERN, 1211 Geneva 23, Switzerland, (presently on
leave from Istituto Nazionale di Fisica Nucleare,
via Celoria 16, 20133 MILANO, Italy)
J. Ranft, Universitaet Gesamthochschule Siegen, Fachbereich Physik,
D-57068 Siegen, Germany
P. R. Sala, Istituto Nazionale di Fisica Nucleare, via Celoria 16,
20133 MILANO, Italy
Other authors who contributed to previous FLUKA versions (from FLUKA82
up to FLUKA92):
P. Aarnio, Helsinki University of Technology, Dept. of Technical
Physics Otakaari 1, SF-02150 ESPOO, Finland
(up to FLUKA87)
J.-H. Moehring, Leipzig University, Germany, Fachbereich Physik,
LEIPZIG, Germany
(up to FLUKA92)
G. R. Stevenson, TIS/RP, CERN, CH-1211 GENEVE 23, Switzerland
(up to FLUKA90)
J. M. Zazula, Institute of Nuclear Physics, CRACOW, Poland
(up to FLUKA90)
1
FLUKA User license, as established by the FLUKA Coordination Committee
Copyright statement and license conditions
Copyright Italian National Institute for Nuclear Physics
(INFN) and European Organization for Nuclear Research (CERN)
("the FLUKA copyright holders"), 1989-2006.
All rights not expressly granted under this license are
reserved.
This software results from work performed by Alberto Fasso`,
Alfredo Ferrari, Johannes Ranft and Paola Sala.
INFN and CERN are the exclusive source of distribution of
the code, bug fixes and documentation of the FLUKA
software. Each official version of FLUKA is identified by a
numbering scheme specifying major and minor releases.
The FLUKA Coordination Committee or its delegates are able
to grant any of the permissions noted in this License
Agreement as requiring a specific consent. Any such consent
may only be granted in writing.
Installation, use, reproduction, display of the FLUKA
software ("FLUKA"), in source and binary forms, are
permitted free of charge on a non-exclusive basis for
internal scientific, non-commercial and non-weapon-related
use by non-profit organizations only. Any exercise of these
rights is subject to the following conditions:
1 Insertion of the FLUKA code, in whole or in part, into
other codes, or its translation into any other computer
language are possible only after obtaining prior written
permission. Modifications of the FLUKA code are permitted
for use by the licensee only, unless authorized in
written.
2 FLUKA is non-transferable, non-sub-licensable and may not
be distributed in any way, without express written
consent, whether in original or modified form. Site-wise
or collaboration-wise conditions can be agreed with the
FLUKA Coordination Committee.
3 Notwithstanding the above, the licensee may modify and
sub-license FLUKA User Routines to third parties in so far
as their purpose is limited to the adaptation of input and
output interfaces of FLUKA and their modification does not
circumvent, replace, add to or modify any of the functions
of FLUKA, or extract specific isolated results from any of
the individual internal physics models embedded within
FLUKA.
4 The licensee shall forthwith license all its modifications
of FLUKA to the FLUKA copyright holders, at no cost and
with no limitation of use. The licensee acknowledges that
the FLUKA copyright holders may insert such modifications
into future releases of FLUKA, subject to appropriate
acknowledgment of the licensee's contribution.
5 Any publication by the licensee with respect to FLUKA or
results obtained from it shall explicitly acknowledge
FLUKA by quoting its set of references and the FLUKA
copyright holders. The licensee shall not without prior
written permission publish documents or results based on a
modified form of FLUKA, unless the modification
exclusively concerns User Routines for the adaptation of
its input and output interfaces which comply with the same
restrictions, as defined in section 3) as those which
apply to sub-licensing. Any publication of documents or
results shall be based only on official FLUKA versions as
obtained from the FLUKA website (http://www.fluka.org) or
from any authorized mirror. Publication here implies any
legal publication to any third party, whether verbal,
electronic, visual, in writing or otherwise.
6 The licensee shall ensure that the FLUKA references,
copyright statement and license conditions are not altered
or removed from FLUKA. Any integration of any portion of
FLUKA, in modified or in unmodified form, into any other
software package must preserve the internal copyright
notices in those portions of FLUKA that have been
employed, and must reproduce such notices within any
additional global notices included along or embedded
within the software into which FLUKA has been
integrated. Any portion of FLUKA so integrated, whether
modified or unmodified shall continue to be subject to
these license conditions.
7 Nothing in this license shall be construed as to grant any
rights in any of the FLUKA versions since 1989. In
addition, users are not permitted to circumvent any
protection in prior distributions of FLUKA that provided
for a preset expiration date of the code
8 Versions or parts of the FLUKA source code, entrusted to
individuals or groups prior to the enactment of the
CERN-INFN Collaboration Agreement, which are listed in
Chapter 5 of Annex 1 of the EP-AB-INFN Scientific
Agreement (19-02-2003), together with the agreed
conditions of use, are subject to this License Agreement
in addition to any other restrictions on the scope of use
that may have been part of the initial use grant.
9 Commercial use of FLUKA, outside the scope of this
license, must be negotiated with the copyright holders
10 DISCLAIMER
THIS SOFTWARE IS PROVIDED BY THE FLUKA COPYRIGHT HOLDERS "AS
IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT
NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY, OF
SATISFACTORY QUALITY, AND FITNESS FOR A PARTICULAR PURPOSE
OR USE ARE DISCLAIMED. THE FLUKA COPYRIGHT HOLDERS AND THE
AUTHORS MAKE NO REPRESENTATION THAT THE SOFTWARE AND
MODIFICATIONS THEREOF, WILL NOT INFRINGE ANY PATENT,
COPYRIGHT, TRADE SECRET OR OTHER PROPRIETARY RIGHT.
11 LIMITATION OF LIABILITY
THE FLUKA COPYRIGHT HOLDERS AND THE AUTHORS SHALL HAVE NO
LIABILITY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL,
CONSEQUENTIAL, EXEMPLARY, OR PUNITIVE DAMAGES OF ANY
CHARACTER INCLUDING, WITHOUT LIMITATION, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES, LOSS OF USE, DATA OR PROFITS,
OR BUSINESS INTERRUPTION, HOWEVER CAUSED AND ON ANY THEORY
OF CONTRACT, WARRANTY, TORT (INCLUDING NEGLIGENCE), PRODUCT
LIABILITY OR OTHERWISE, ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.
REQUESTS MADE BY THE FLUKA AUTHORS TO ALL USERS
All licensees are requested to report as soon as practical
to the Authors any errors or bugs found in any portion of
FLUKA and its accompanying documentation.
All licensees are requested to forward copies of all
comparisons that they may make between FLUKA results and
data or other codes as soon as practical. The Authors agree
to keep any such communications confidential unless
otherwise notified by the contributing user.
The Authors reserve the right of publishing any benchmarking
and/or comparisons of the distinct separate performance of
the individual internal models that are embedded into FLUKA,
whether the comparisons are with data or with other
codes. The Authors would also like to convey a general
willingness to conduct any such benchmarking efforts either
upon request or in collaboration with interested parties. In
case of doubt please contact the Authors.
Users should exclusively download FLUKA from the official
FLUKA website (http://www.fluka.org) or one of the
authorized mirror sites. Users are invited to regularly
update their FLUKA version to profit for improvements and
bug fixes.
Users are invited to use reasonably updated versions of the
code for publications. Publications of results based on
those FLUKA versions that are declared unsupported and
obsolete on the official FLUKA website shall be avoided.
Users should address any request of consent to one member of
the FLUKA Coordinating Committee, which at present is
composed as follows:
Giuseppe Battistoni Giuseppe.Battistoni@mi.infn.it
(chairman)
John Ferguson John.Ferguson@cern.ch
John Harvey John.Harvey@cern.ch
Johannes Ranft Johannes.Ranft@cern.ch
Paola Sala Paola.Sala@mi.infn.it
In accordance with the User License, the use of the FLUKA code must be
acknowledged explicitly by quoting the following set of references:
- A. Fasso`, A. Ferrari, J. Ranft, and P.R. Sala,
"FLUKA: a multi-particle transport code",
CERN-2005-10 (2005), INFN/TC_05/11, SLAC-R-773
- A. Fasso`, A. Ferrari, S. Roesler, P.R. Sala,
G. Battistoni, F. Cerutti, E. Gadioli, M.V. Garzelli,
F. Ballarini, A. Ottolenghi, A. Empl and J. Ranft,
"The physics models of FLUKA: status and recent developments",
Computing in High Energy and Nuclear Physics 2003 Conference (CHEP2003),
La Jolla, CA, USA, March 24-28, 2003, (paper MOMT005),
eConf C0303241 (2003), arXiv:hep-ph/0306267
Additional FLUKA references can be added, provided they are relevant
for the FLUKA version under consideration
This set of references is subject to change in time. New ones will be
communicated, when necessary, in the Release Notes of new FLUKA versions.
For questions/clarifications/problems about the license or in general the
use of FLUKA please contact the chairman of the joint INFN/CERN FLUKA
Coordination Committee:
Prof. Giuseppe Battistoni
INFN - Via Celoria 16 I-20133 Milano (Italy)
Giuseppe.Battistoni@mi.infn.it
or one of the Authors.
1
FLUKA2006 MANUAL
IMPORTANT WARNING FOR THE USERS
This manual is a reference tool for preparing input for the FLUKA
particle transport code. It is not complete and it is not guaranteed to
be free from errors. It is continually evolving just as the code does.
It should not be cited: the proper references to be cited in any recent
work related to FLUKA are listed above (see also the list of References
in 17}). In using the code, the user agrees on the authorship
and copyright and hence is bound to quote the above references.
Please note also that early versions of the FLUKA hadronic event generator
as implemented in other codes (in particular GEANT) should be referenced
as such (e.g. GEANT-FLUKA) and not as FLUKA. They have little in common
with the present version and should be considered virtually obsolete.
The proper reference to GEANT-FLUKA is Fas93a.
Some parts of the manual must be "enriched": output etc.; the part on
auxiliary programs must be updated.
Please refer to fasso@slac.stanford.edu / Alfredo.Ferrari@cern.ch for any
comment or criticism on this manual and/or the code.
Alberto Fasso`, Alfredo Ferrari
1******************************************************************************
Index of the FLUKA manual on-line
(search for string " 1}", " 2}" etc. for quick location)
******************************************************************************
0} What is FLUKA?
1} A quick look at FLUKA's physics, structure and capabilities
2} A FLUKA beginner's guide
3} Installation
4} FLUKA modules (Fortran files)
5} Particle and material codes
6} General features of FLUKA input
7} Description of FLUKA input options
8} Combinatorial Geometry
9} Output
10} Low-energy neutrons in FLUKA
11} Collision tape
12} Generating and propagating optical photons
13} User routines
14} Use of RAY pseudoparticles
15} Examples on the material/compound definitions
16} History of FLUKA
17} References
1******************************************************************************
0} What is FLUKA?
******************************************************************************
FLUKA is a general purpose tool for calculations of particle transport
and interactions with matter, covering an extended range of
applications spanning from proton and electron accelerator shielding to
target design, calorimetry, activation, dosimetry, detector design,
Accelerator Driven Systems, cosmic rays, neutrino physics, radiotherapy
etc.
The highest priority in the design and development of FLUKA has always been
the implementation and improvement of sound and modern physical models.
Microscopic models are adopted whenever possible, consistency among all the
reaction steps and/or reaction types is ensured, conservation laws are enforced
at each step, results are checked against experimental data at single
interaction level. As a result, final predictions are obtained with a minimal
set of free parameters fixed for all energy/target/projectile combinations.
Therefore results in complex cases, as well as properties and scaling laws,
arise naturally from the underlying physical models, predictivity is provided
where no experimental data are directly available, and correlations within
interactions and among shower components are preserved.
FLUKA can simulate with high accuracy the interaction and propagation
in matter of about 60 different particles, including photons and electrons
from 1 keV to thousands of TeV, neutrinos, muons of any energy, hadrons
of energies up to 20 TeV (up to 10 PeV by linking FLUKA
with the DPMJET code) and all the corresponding antiparticles, neutrons down
to thermal energies and heavy ions. The program can also transport polarised
photons (e.g., synchrotron radiation) and optical photons. Time evolution and
tracking of emitted radiation from unstable residual nuclei can be performed
online.
FLUKA can handle even very complex geometries, using an improved version of the
well-known Combinatorial Geometry (CG) package. The FLUKA CG has been designed
to track correctly also charged particles (even in the presence of magnetic or
electric fields). Various visualisation and debugging tools are also available.
For most applications, no programming is required from the user.
However, a number of user interface routines (in Fortran 77) are
available for users with special requirements.
The FLUKA physical models are described in several journal and conference
papers; on the technical
side the stress has been put on four apparently conflicting
requirements, namely efficiency, accuracy, consistency and flexibility.
Efficiency has been achieved by having a frequent recourse to table look-up
sampling and a systematic use of double precision has had a great impact on
overall accuracy: both qualities have benefited from a careful choice of the
algorithms adopted. To attain a reasonable flexibility while minimising
the need for user-written code, the program has been provided with a
large number of options available to the user, and has been completely
restructured introducing dynamical dimensioning.
Another feature of FLUKA, probably not found in any other Monte Carlo
program, is its double capability to be used in a biased mode as well as a
fully analogue code. That means that while it can be used to predict
fluctuations, signal coincidences and other correlated events, a wide choice of
statistical techniques are also available to investigate punchthrough or other
rare events in connection with attenuations by many orders of magnitude.
1******************************************************************************
1} A quick look at FLUKA's physics, structure and capabilities
******************************************************************************
Only a very short summary will be given here of the capabilities and
the limitations of FLUKA, since this is meant to be mainly a practical
guide. More detailed descriptions of the physical models, algorithms
and techniques will be found in cited references and hopefully in a
future more comprehensive Reference Manual.
1) PHYSICS
Hadron inelastic nuclear interactions:
The FLUKA hadron-nucleon interaction models are based on resonance
production and decay below a few GeV, and on the Dual Parton model above.
Two models are used also in hadron-nucleus interactions. At momenta
below 3--5 GeV/c the PEANUT package includes a very detailed Generalised
Intra-Nuclear Cascade (GINC) and a preequilibrium stage, while at high
energies the Gribov-Glauber multiple collision mechanism is included in
a less refined GINC. Both modules are followed by equilibrium processes:
evaporation, fission, Fermi break-up, gamma deexcitation. FLUKA can also
simulate photonuclear interactions (described by Vector Meson Dominance,
Delta Resonance, Quasi-Deuteron and Giant Dipole Resonance). A schematic
outline is presented below:
* Inelastic cross sections for hadron-hadron interactions are represented by
parameterised fits based on available experimental data [PDG].
* For hadron-nucleus interactions, a mixture of tabulated data and
parameterised fits is used [Bar72,Moh83,She91,Pra98,Pra98a].
* Elastic and charge exchange reactions are described by phase-shift analyses
and eikonal approximation.
* Inelastic hadron-hadron interactions are simulated by different event
generators, depending on energy:
- Momentum < 20 TeV and > 5 GeV/c:
Dual Parton Model (DPM) [Cap94]. The version used in FLUKA has been
derived by A. Ferrari and P.R. Sala [Fer94, Fas95, Fer95, Fer96b] from
the original version by J. Ranft and collaborators [Ran83, Ran83a]. A
description of modifications and improvements can be found in
[Fer96b, Col00]
- Momentum from threshold to 5~GeV/c:
Resonance production and decay model [Fer96b] (Improved version of the
H"anssgen et al. model [Han79, Han80, Han84, Han84a, Han84b, Han86, Han86a])
* Inelastic hadron-nucleus interactions are simulated by different event
generators depending on energy and projectile:
- Momentum < 20 TeV and > 5 GeV/c: Glauber-Gribov multiple scattering
followed by Generalized Intranuclear Cascade (GINC)
- Below 5 GeV/c for nucleons, anti-nucleons and pions; below 1.5 GeV kinetic
for kaons:
Preequilibrium-cascade model PEANUT (Ferrari-Sala) [Fer94, Fas95]
- In between PEANUT and DPM for kaons: H"anssgen K. et al. GINC modified to
take into account correlations among cascade particles and more refined
nuclear effects (Ferrari-Sala).
* All three models include evaporation and gamma deexcitation of the residual
nucleus [Fer96, Fer96a]. Light residual nuclei are not evaporated but
fragmented into a maximum of 6 bodies, according to a Fermi break-up model.
* Treatment of antiparticle capture: antinucleons according to resonance model,
pi-minus, K-minus and mu-minus by the preequilibrium-cascade model.
Elastic Scattering:
* Parameterised nucleon-nucleon cross sections.
* Tabulated nucleon-nucleus cross sections [Pra98, Pra98a].
* Tabulated phase shift data for pion-proton and phase-shift analysis for
kaon-proton scattering.
* Detailed kinematics of elastic scattering on hydrogen nuclei and transport
of proton recoils (Ferrari-Sala)
Nucleus-Nucleus interactions:
Nuclear interactions generated by ions are treated through interfaces to
external event generators.
* Above 5 GeV per nucleon: DPMJET-II or DPMJET-III, with special
initialisation procedure.
* Between 0.1 and 5 GeV per nucleon: modified RQMD
Transport of charged hadrons and muons:
An original treatment of multiple Coulomb scattering and of ionisation
fluctuations allows the code to handle accurately some challenging problems
such as electron backscattering and energy deposition in thin layers even in
the few keV energy range.
Energy loss:
* Bethe-Bloch theory [Bet30, Bet32, Bet34, Blo33, Blo33a]
* Optional delta-ray production and transport with account for spin
effects and ionisation fluctuations.
The present version includes a special treatment [Fas97a] which
combines delta-ray production with properly restricted ionisation
fluctuations and includes corrections for particle spin and
electrons/positrons and "distant collision" straggling corrections
(similar to Blunck-Leisegang ones).
* Shell and other low-energy corrections derived from Ziegler [Zie77]
* Density effect according to Sternheimer [Ste84].
* Special transport algorithm, based on Moli\`ere's theory of multiple Coulomb
scattering improved by Bethe [Mol48, Mol55, Bet53], with account of several
correlations:
- between lateral and longitudinal displacement and the deflection angle
- between projected angles
- between projected step length and total deflection
* Accurate treatment of boundaries and curved trajectories in magnetic and
electric fields
* Automatic control of the step
* Path length correction
* Spin-relativistic effects at the level of the second Born approximation
[Fer91a]
* Nuclear size effects (scattering suppression) on option (simple nuclear
charge form factors are implemented, more sophisticated ones can be supplied
by the user)
* Correction for cross-section variation with energy over the step.
* Bremsstrahlung and electron pair production at high energy by heavy charged
particles, treated as a continuous energy loss and deposition or as discrete
processes depending on user choice
* Muon photonuclear interactions, with or without transport of the produced
secondaries.
Low-energy neutrons:
For neutrons with energy lower than 20 MeV, FLUKA uses its own neutron cross
section library (P5 Legendre angular expansion, 72 neutron energy groups),
containing more than 140 different materials, selected for their interest in
physics, dosimetry and accelerator engineering and derived from the most
recently evaluated data.
* ENEA multigroup P5 cross-sections [Cuc91]
* Gamma-ray generation and different temperatures available.
* Doppler broadening for temperatures above 0 K.
Transport:
* Standard multigroup transport with photon and fission neutron
generation.
* Detailed kinematics of elastic scattering on hydrogen nuclei.
* Transport of proton recoils and protons from 14-N(n,p)14-C reaction.
* Capture photons are generated according to the multigroup treatment,
but transported with the more accurate EMF package which performs
continuous transport in energy and allows for secondary electron
generation.
For nuclei other than hydrogen, kerma factors are used to
calculate energy deposition (including from low-energy fission).
For details about the available materials, group structure
etc., see 10}
Electrons:
* FLUKA uses an original transport algorithm for charged particles
[Fer91a], including complete multiple Coulomb scattering treatment
giving the correct lateral displacement even near a boundary (see
hadron and muon transport above).
* The variations with energy of the discrete event cross-sections and of the
continuous energy loss in each transport step are taken into account exactly.
* Differences between positrons and electrons are taken into account
concerning both stopping power and bremsstrahlung [Kim86].
* The bremsstrahlung differential cross-sections of Seltzer and
Berger [Sel85, Sel86] have been extended to include the finite value at
"tip" energy, and the angular distribution of bremsstrahlung photons
is sampled accurately.
* The Landau-Pomeranchuk-Migdal suppression effect [Lan53,Lan53a,
Mig56,Mig57] and the Ter-Mikaelyan polarisation effect in the soft part
of the bremsstrahlung spectrum [Ter54] are also implemented.
* Electrohadron production (only above rho mass energy 770 MeV)
via virtual photon spectrum and Vector Meson Dominance Model
[Moh89]. (The treatment of the latter effect has not been
checked with the latest versions, however).
* Positron annihilation in flight and at rest
* Delta-ray production via Bhabha and M\oller scattering.
Note: the present lowest transport limit for electrons is
1 keV. Although in high-Z materials the Moli\`ere multiple scattering
model becomes unreliable below 20-30 keV, a single-scattering option
is available which allows to obtain satisfactory results in any
material also in this low energy range.
The minimum recommended energy for PRIMARY electrons is about
50 to 100 keV for low-Z materials and 100-200 keV for heavy
materials, unless the single scattering algorithm is used.
Single scattering transport allows to overcome most of the
limitations at low energy for the heaviest materials at the price of
some increase in CPU time.
Photons:
* Pair production with actual angular distribution of
electrons and positrons.
* Compton effect with account for atomic bonds through use of
inelastic Hartree-Fock form factors.
* Photoelectric effect with actual photoelectron angular
distribution [Sau31], detailed interaction on six K and L
single sub-shells, optional emission of fluorescence photons
and approximate treatment of Auger electrons.
* Rayleigh effect.
* Photon polarisation taken into account for Compton, Rayleigh
and Photoelectric effects.
* Photohadron production:
- Vector Meson Dominance Model (Ranft [Ran87b]), modified and improved
(Ferrari-Sala) using PEANUT below 770 MeV [Fas95].
- Quasideuteron interactions
- Giant Dipole Resonance
Note: the present lowest transport limit for photons is 1 keV.
However, fluorescence emission may be underestimated at
energies lower than the K-edge in high-Z materials, because of
lack of Coster-Kronig effect.
The mimimum recommended energy for PRIMARY photons is about
5 to 10 keV.
Optical photons:
* Generation and transport (on user's request) of Cherenkov,
Scintillation and Transition Radiation.
* Transport of light of given wavelength in materials with user-defined optical
properties.
Neutrinos:
* Electron and muon (anti)neutrinos are produced and tracked on option, without
interactions
* Neutrino interactions however are implemented, but independently from
tracking.
2) GEOMETRY
A part of the code where efficiency, accuracy, consistency and
flexibility have combined giving very effective results is the new FLUKA
geometry. Derived from the Combinatorial Geometry package, it has been
entirely rewritten. A completely new, fast tracking strategy has been
developed, with special attention to charged particle transport,
especially in magnetic fields. New bodies have been introduced, resulting
in increased rounding accuracy, speed and even easier input preparation.
* Combinatorial Geometry (CG) from MORSE [Emm75], with additional bodies
(infinite circular and elliptical cylinder parallel to X,Y,Z axis, generic
plane, planes perpendicular to the axes).
* Possibility to use body and region names instead of numbers.
* Distance to nearest boundary taken into account for improved performance.
* Accurate treatment of boundary crossing with multiple scattering and magnetic
or electric fields.
* The maximum number of regions (without recompiling the code) is 10000.
* The tracking strategy has been substantially changed with respect to
the original CG package. Speed has been improved and interplay with
charged particle transport (multiple scattering, magnetic and electric
field transport) has been properly set.
* A limited repetition capability (lattice capability) is available. This
allows to avoid describing repetitive structures in all details.
Only one single module has to be described and then can be repeated as
many times as needed. This repetition does not occur at input stage but
is hard-wired into the geometry package, namely repeated regions are not
set up in memory, but the given symmetry is exploited at tracking time
using the minimum amount of bodies/regions required. This allows in
principle to describe geometries with even tens of thousands regions (e.g.
spaghetti calorimeters) with a reasonable number of region and body
definitions.
* Voxel geometry is available on option, completely integrated into CG.
Special options:
* Geometry debugger
* Plotting of selected sections of the geometry, based on the Ispra PLOTGEOM
program
* Pseudoparticle RAY to scan the geometry in a given direction.
3) TRANSPORT
* Condensed history tracking for charged particles, with single scattering
option.
* Time cut-off.
* Legendre angular expansion for low-energy neutron scattering.
* Transport of charged particles in magnetic and electric fields.
Transport limits:
Secondary particles Primary particles
charged hadrons 1 keV-20 TeV (*) 100 keV-20 TeV (*)
neutrons thermal-20 TeV (*) thermal-20 TeV (*)
antineutrons 1 keV-20 TeV (*) 10 MeV-20 TeV (*)
muons 1 keV-1000 TeV 100 keV-1000 TeV
electrons 1 keV-1000 TeV 70 keV-1000 TeV (low-Z materials)
150 keV-1000 TeV (high-Z materials)
photons 1 keV-1000 TeV 7 keV-1000 TeV
heavy ions 10 MeV/n-10000 TeV/n 100 MeV/n-10000 TeV/n
(*) 10 PeV with the DPMJET interface
4) BIASING
* Leading particle biasing for electrons and photons: region dependent,
below user-defined energy threshold and for selected physical effects.
* Russian Roulette and splitting at boundary crossing based on region
relative importance.
* Region-dependent multiplicity tuning in high energy nuclear interactions.
* Region-dependent biased downscattering and non-analogue absorption of
low-energy neutrons.
* Biased decay length for increased daughter production
* Biased inelastic nuclear interaction length
* Biased interaction lengths for electron and photon electromagnetic
interactions
* Biased angular distribution of decay secondary particles.
* Region-dependent weight window in three energy ranges (and energy group
dependent for low energy neutrons).
5) OPTIMISATION
* Optimisation of the step length, user-defined or automatic, by material
and/or by region.
6) SCORING
* Star density by producing particle and region.
* Energy density by region, total or from electrons/photons only.
* Star, energy and momentum transfer density in a geometry-independent binning
structure (Cartesian or cylindrical), averaged over the run or event by event.
* Energy deposition weighted by a quenching factor (Birks law).
* Step size independent of bin size.
* Time window.
* Coincidences and anti-coincidences.
* Fluence and current scoring as a function of energy and angle, via
boundary-crossing, collision and track-length estimators coincident
with regions or region boundaries.
* Track-length fluence in a binning structure (Cartesian or cylindrical)
independent of geometry.
* Particle yield from a target or differential cross section with respect to
several different kinematic variables.
* Residual nuclei.
* Fission density.
* Momentum transfer density.
* Neutron balance.
* No limit to the number of estimators and binnings within the total memory
available (but a maximum number must be fixed at compilation time).
* Energy deposition can be scored on option disregarding the particle weights
(useful for studying computer performance, etc.)
* All quantities from radioactive decay of residual nuclei can be scored
according to user-defined irradiation and cooling time profiles.
Code structure, technical aspects
* The whole program, including the numerical constants, is coded in double
precision (at least the versions for 32-bit word machines). The only
exceptions are the low-energy neutron cross-sections, which are stored in
single precision to save space.
* Consistent use of the latest recommended set of the physical constant
values [PDG].
* Dynamic memory allocation is implemented as far as possible.
* Extensive use of INCLUDE statements and of constant parameterisation
* 64-bit random number generator [Mar04]
7) MAIN DIFFERENCES BETWEEN FLUKA AND EARLIER CODES WITH SAME NAME
The history of FLUKA, spanning more than 40 years, is narrated in detail in 16}.
It is possible to distinguish three different generation of "FLUKA" codes along
the years, which can be roughly identified as the FLUKA of the '70s (main authors
J. Ranft and J. Routti), the FLUKA of the '80s (P. Aarnio, A. Fasso`,
H.-J. M"ohring, J. Ranft, G.R. Stevenson), and the FLUKA of today (A. Fasso`,
A. Ferrari, J. Ranft and P.R. Sala).
These codes stem from the same root and of course every new ``generation''
originated from the previous one. However, each new ``generation'' represented
not only an improvement of the existing program, but rather a quantum
jump in the code physics, design and goals. The same name ``FLUKA'' has been
preserved as a reminder of this historical development - mainly as a
homage to J. Ranft who has been involved in it as an author and mentor from the
beginning until the present days - but the present code is completely different
from the versions which were released before 1990, and in particular from the last
one of the second generation, FLUKA87 [Aar86, Aar87].
Major changes and additions have affected the physical models used, the code
structure, the tracking strategy and scoring. Important additions, such as a
wider range of biasing possibilities and some specialised tools for calorimeter
simulation, have extended the field of its possible applications.
An exhaustive description of all these changes and new features along the years
is reported in Chap. 16}. However, the best gauge of the program evolution is
probably the widening of the application fields, and the boost of its recognition
and diffusion all over the world.
Applications:
While FLUKA86-87 was essentially a specialised program to calculate
shielding of high energy proton accelerators, the present version can be
regarded as a general purpose tool for an extended range of applications.
In addition to traditional target design and shielding, applications are
now spanning from calorimetry to prediction of activation, radiation
damage, isotope transmutation, dosimetry and detector studies.
Prediction of radiation damage has always been a traditional field of
application of FLUKA, restricted however in earlier versions to
hadron damage to accelerator components. The new capability to deal with
the low-energy neutron component of the cascade has extended the field of
interest to include electronics and other sensitive detector parts. In
addition, radiation damage calculations and shielding design are not
limited to proton accelerators any longer, but include electron accelerators
of any energy, photon factories, and any kind of radiation source, be it
artificial or natural.
The present version of FLUKA has been used successfully in such diverse
domains as background studies for underground detectors, cosmic ray
physics, shielding of synchrotron radiation hutches, calculation of dose
received by aircraft crews, evaluation of organ dose in a phantom due to
external radiation, detector design for radiation protection as well as
for high energy physics, electron and proton radiotherapy, nuclear
transmutation, neutrino physics, shielding of free-electron lasers,
calculation of tritium production at electron accelerators, energy
amplifiers, maze design for medical accelerators, etc.
The recent addition of the simulation of heavvy ion interactions allows also
for applications to hadrotherapy.
1******************************************************************************
2} A FLUKA beginner's guide
******************************************************************************
This Chapter is intended to provide a minimal set of instructions to install
and run FLUKA for a beginner user, going through the different steps required
to run a simple example. References to the relevant chapters of the manual are
given to help the user in finding more detailed information on the different
topics. After describing the installation procedure, instructions are given on
how to build the input file for a simple case. Instructions for running and
accessing the results are also reported. As a further step, the user is
addressed to Chapter 13} to learn how to tailor FLUKA to specific needs by
means of user routines.
Installing FLUKA
----------------
A full description of the installation procedure is given in Chapter 3}.
The FLUKA package for LINUX and UNIX platforms is distributed as a tar file
which can be downloaded from the FLUKA Website http://www.fluka.org or other
authorised mirror site.
The user must prepare a directory where the tar file has to be expanded.
Let us suppose that the gzipped tar file, called fluka2006.1-linuxAA.tar.gz,
has been downloaded in a given directory and that it must be expanded in a new
subdirectory called fluka (but any other name is valid). A possible way to
proceed is the following:
mkdir fluka
cd fluka
tar zxvf ../fluka2006.1-linuxAA.tar.gz
An alterantive way to expand the tar file is:
gunzip -dc ../fluka2006.1-linuxAA.tar.gz | tar xvf
At this stage, the user must define an environmental variable FLUPRO pointing
to the directory where the distribution tar file has been opened.
This directory is made available as follows:
Bash shell: use the export command C or tc shell: use the setenv command
... ...
cd fluka cd fluka
export FLUPRO=$PWD setenv FLUPRO $PWD
Of course the definition of FLUPRO can be placed once for ever in the login
script.
The FLUKA libraries and most data files will be located in $FLUPRO, the INCLUDE
files in $FLUPRO/flukapro/, the default user routines in $FLUPRO/usermvax/,
compilation and linking scripts (as well as several postprocessing programs to
analyse user scores) in $FLUPRO/flutil/. See details in Chapter 3}.
The user must produce the default FLUKA executable, to be located in the $FLUPRO
directory, by means of the $FLUPRO/flutil/lfluka script:
...
cd $FLUPRO
$FLUPRO/flutil/lfluka -m fluka
The default executable is called flukahp.
Building a FLUKA input
----------------------
Generalities about FLUKA input
------------------------------
FLUKA reads user input from an ASCII "standard input" file with extension .inp.
The general characteristics and rules of FLUKA input are described in
Chapter 6}.
The input consists of a variable number of "commands" (called also "options"),
each consisting of one or more "lines" (called also "cards" for historical
reasons).
Apart from FLUKA commands, the input file may contain also the description of
the geometry of the simulated set-up. Also this description is provided by
means of specific geometry "command cards" in a special format described in
Chapter 6}.
The geometry description can, on request, be kept in a separate ASCII file:
this feature is especially useful when the same geometry is used in several
different inputs, not only to save space but because modifications can be made
in one single place.
The typical structure of a FLUKA input file is the following:
- Titles and comments for documentation purposes (optional, but recommended)
- Description of the problem geometry (solid bodies and surfaces, combined to
partition space into regions) (mandatory)
- Definition of the materials (mandatory unless pre-defined materials are used)
- Material assignments (correspondence material-region, mandatory)
- Definition of the particle source (mandatory)
- Definition of the requested "detectors". Each of these is a phase space
domain (region of space, particle direction and energy) where the user wants
to calculate the expectation value of a physical quantity such as dose,
fluence, etc. Various kinds of detectors are available, corresponding to
different quantities and to different algorithms used to estimate them
("estimators"). Detectors are optional, but one at least is expected, at
least in the production phase
- Definition of biasing schemes (optional)
- Definition of problem settings such as energy cut-offs, step size, physical
effects not simulated by default, particles not to be transported, etc.
(optional)
- Initialisation of the random number sequence (mandatory if an estimation of
the statistical error is desired)
- Starting signal and number of requested histories (mandatory)
In addition, special commands are available in FLUKA for more advanced problems
involving magnetic fields, time-dependent calculations, writing of history
files (so-called "collision tapes"), transport of optical photons,
event-by-event scoring, calling user-written routines, etc. These options are
expected to be requested only by users having some previous experience with the
more common commands: therefore they will be mostly ignored in this beginner's
guide.
Let's first recall the general structure of the FLUKA command lines (cards).
The geometry commands will be reviewed later. Each card contains:
- one keyword,
- six floating point values (called WHATs),
- one character string (called SDUM)
Not necessarily all WHATs and SDUMs are used. In some cases, a command
line can be followed by a line of text (for instance a filename path or a
title). Any line having an asterisk (*) in the first position is treated as a
comment. All lines (commands, text strings and comments) are echoed on
the standard output (the file with extension .out). In case of problems, it is
a good idea to check how every line has been printed in the standard output.
Often, output reveals typing or format errors by showing how the program has
misinterpreted them.
In addition to the simple echo, an "interpreted" feedback to all commands is
provided in the next section of the standard output. Checking this part of the
output is also very useful, because it helps making sure that the user's
intentions have been expressed correctly and understood by the code. See
Chapter 9} on FLUKA output for a detailed description.
If a line contains an exclamation mark (!) all following characters are
replaced by blanks. This feature can be used for short in-line comments which
will not be echoed in output.
The order of input commands is generally free, with only a few exceptions
reported in Chapter 7}. Therefore, the order suggested in the following should
not be considered as mandatory, but only one of the possible ways to write
FLUKA input.
Input alignment
---------------
Be careful to properly align keywords and numbers. Format is not free, unless a
command is issued at the beginning of input: see option GLOBAL or FREE.
Even in the free format for the input file, the part of the input describing the
geometry can still be written in fixed format (which is different from the
general FLUKA input format, see Chap. 6}). There is the possibility of having
free format also for the geometry part: this can also be activated using the
GLOBAL command.
In fixed format, in order to ensure proper alignment, a comment line showing a
scale can be used anywhere in the input file, for instance:
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
In numerical fields, blanks are treated as zero. Therefore, numbers written
with a decimal period and without an exponent (e.g. 1.2345) can be placed
anywhere inside their respective format fields, For instance, the following two
input lines are equally acceptable:
BEAM 200. 0.2 1.5 1.2 0.7 1.0 PROTON
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
BEAM 200. 0.2 1.5 1.2 0.7 1.0PROTON
If a number is written in exponential notation (e.g. 2.3E5) or in integer form
(without decimal point), it must be aligned to the right of the field.
Depending on the platform and the compiler, sometimes the number is correctly
interpreted even if the alignment rule is not respected. However THIS IS NOT
GUARANTEED AND THE RIGHT ALIGNMENT RULE SHOULD ALWAYS BE FOLLOWED.
For instance in:
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
BEAM 2.E2 0.2 1.5 1.2 0.7 1. PROTON
the first value might be interpreted as 2.E200. Another case is the following:
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
BEAM 200. 0.2 1.5 1.2 0.7 1 PROTON
here the last numerical field would be interpreted as 1000000000. To avoid
mistakes due to this kind of input errors, the present FLUKA versions now
recognise such potential problems and the program is forced to stop. At the
same time a message is printed on the standard output file, as shown here for
the above example:
*** The 6th field 1 of the following input card ***
BEAM 200. 0.2 1.5 1.2 0.7 1 PROTON
*** does not contain a valid formatted fortran real number!!! ***
*** It is ambiguous and it could be read differently on different compilers ***
*** depending how strictly the blank=0 formatted input rule is implemented ***
Keywords (character strings such as BEAM and PROTON) must be aligned to the
left of their field and must be in upper case. An exception is the continuation
character & used in some commands, which can be placed anywhere within its
10-characters field.
A simple example
----------------
Let us now consider a simple starting application. We want to calculate the
charged pion fluence produced by a monochromatic proton beam of momentum
50 GeV/c impinging on a 5 cm thick beryllium target of simple shape: a small
parallelepiped (20 cm x 20 cm x 5 cm). A further simplification will be made
for the purpose of this example, neglecting all the surrounding environment and
substituting it with ideal vacuum.
We will guide the reader through the different parts of a possible input file
suited for this application. The information which follows is meant to serve as
a guide, but does not cover all the important points. It is recommended that
for each option card selected, the user read carefully the relevant manual
entry, and especially the explanatory notes.
The title
---------
Typically, an input file begins with a TITLE card followed by one line of text
describing the problem, or identifying that particular run, or providing some
kind of generic information. In our case, for example:
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
TITLE
Charged pion fluence inside and around a proton-irradiated Be target
Further information can be provided by comment cards, but the title, because it
is printed at the top of the standard output and of each estimator output, is a
useful reminder of what the corresponding file is about. In addition, the title
is printed in all separate output files (error file, estimator files etc.)
together with the date and time of the FLUKA run, allowing to keep track of
their origin.
Commands such as GLOBAL and DEFAULTS, if needed, must immediately follow. Since
this is intended as a beginner's guide, these can be ignored here (for most
common problems the defaults provided are sufficient). Let us recall that
without specifying a DEFAULT value, the NEW-DEFAults set of FLUKA parameters is
loaded.
Definition of the primary particles
-----------------------------------
All "events" or "histories" are initiated by primary particles, which in the
simplest case are monoenergetic, monodirectional and start from a single point
in space (pencil beam). The particle energy (or momentum) is defined by option
BEAM, and their starting position and direction by option BEAMPOSit. These two
commands can be used also to define particle beams having a simple angular or
momentum distribution (Gaussian or rectangular), or a simple transverse profile
(Gaussian, rectangular or annular). Isotropic or semi-isotropic angular
emission can be described as a special case of an angular rectangular
distribution.
For particle sources with more complex distributions in energy, space and
direction, the user must write, compile and link a special routine (SOURCE),
following the instructions given in Chap. 13}, and input a card SOURCE.
A summary of the input data concerning primary particles is printed in the
standard output under the title "Beam properties".
The beam definition for our example can be the following (monochromatic,
monodirectional proton beam of momentum 50 GeV/c):
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
BEAM 50.E+00 PROTON
In our example, the beam starting point is given by:
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
BEAMPOS 0.0 0.0 -50.0
In the cartesian geometry used by FLUKA, the previous card means that the beam
is injected at x, y, z cordinates: 0, 0, -50 cm and is directed along the
positive z axis. Of course, the choice of the point of injection, the
direction, etc., must be coherent with the geometrical description of the
set-up, as discussed in the following section.
The geometry
------------
The input for the Combinatorial Geometry (bodies, regions and optional region
volumes) must be immediately preceded by a GEOBEGIN card and immediately
followed by a GEOEND card. These two cards follow the normal FLUKA format. It
is recalled that the format for the geometry has its own special rules,
described in Chap. 8}.
Comment lines in the geometry input have an asterisk in first position as in
the rest of FLUKA input (but on-line comments are not allowed). Body numerical
data can be written in two different formats, a "short" one (field length 10)
and a "long" one (field length 22). The latter one is to be preferred when
higher precision is needed, for instance when using bodies such as truncated
cones, cylinders or planes not aligned with axes. It must be realised that
using too few decimals can cause geometry errors when bodies are combined into
regions (portions of space not defined or doubly defined).
The whole geometry must be surrounded by a region of "blackhole" limited by a
closed body (generally an RPP parallelepiped). It is often a good idea to make
this body much larger than the minimum required size: this makes easier to
introduce possible future extensions. In some cases, as in our basic example,
it is also useful to surround the actual geometry by a region of ideal vacuum,
and to have the blackhole region surrounding the vacuum. This can be useful,
for instance, in order to start the trajectory of the primary particles
outside the physical geometry (a particle may not be started on a boundary).
Both the body input section and the region input section must be ended with an
END card. Optionally, region volumes can be input between the region END card
and the GEOEND card (this option can be requested by setting a special flag in
the Geometry title card, see Chap. 8}). The only effect of specifying region
volumes is to normalise per cm3 the quantities calculated via the SCORE option
(see below): for other estimators requiring volume normalisation the volume is
input as part of the detector definition (USRTRACK, USRCOLL, USRYIELD), or is
calculated directly by the program (USRBIN).
The GEOEND card indicates the end of the geometry description, but can also be
used to invoke the geometry debugger.
The geometry output is an expanded echo of the corresponding input, containing
information also on memory allocation and on the structure of composite regions
made of several sub-regions by means of the OR operator.
A possible realisation of the geometry set up for our basic example can be seen
in the Figure below:
z ^ -----------------------------------
| / ______________________ /|
| / / / / |
| ----------------------------------- |
| | / vacuum (region 2) / | | |
| | ------------------------ | | |
| | | ___________ | | | |
| | | / Be /| | | | |
| | | ------------ | | | | |
| | | | (reg. 4) |/| | | | |
| | | ----------- | | | | |
| | | | (reg. 3) |/ | | | |
+-- | | ------------ | | | |-------->
/ | | ^ | / | | y
/ | | | Beam |/ | |
/ | ------------------------ | /
/ | Blackhole (region 1) |/
/ -----------------------------------
x
Only four bodies are used here: an RPP body (Rectangular Parallelepiped, body
no. 3) to define a volume which will be the Be target region, inside another
larger RPP body (no. 2), which will be filled with ideal vacuum and in turn is
contained inside another larger RPP body (no. 1), to define the blackhole
region. The fourth body, an XYP half-space (defined by a plane perpendicular to
the z axis), will be used to divide the target into 2 different regions: the
upstream half will be defined as the portion of body 3 contained inside the
half-space, and the downstream half as the portion outside it. Therefore,
region "3" (the upstream half of the target) is the part of body no. 3 which is
also inside body 4, while region "4" (downstream half of the target) is the
part of body no. 3 which is not inside body 4. Region "2" (the vacuum around
the target) is defined as the inside of body no. 2 from which body no. 3 is
subtracted. Region "1" is simply the interior of body no. 1 from which body
no. 2 is subtracted.
The beam starting point has been chosen so that it is in the vacuum, outside
the target region.
The geometry part of the input file can then be written as:
GEOBEGIN COMBINAT
A simple Be target inside vacuum
RPP 1-5000000.0+5000000.0-5000000.0+5000000.0-5000000.0+5000000.0
RPP 2-1000000.0+1000000.0-1000000.0+1000000.0 -100.0+1000000.0
RPP 3 -10.0 +10.0 -10.0 +10.0 0.0 +5.0
* plane to separate the upstream and downstream part of the target
XYP 4 2.5
END
* black hole
BH1 5 +1 -2
* vacuum around
VA2 5 +2 -3
* Be target 1st half
BE3 5 +3 +4
* Be target 2nd half
BE4 5 +3 -4
END
GEOEND
Materials
---------
Each geometry region is supposed to be filled with a homogeneous material, or
with vacuum, or with "blackhole". The latter is a fictitious material used to
terminate particle trajectories: any particle is discarded when reaching a
blackhole boundary. Materials can be simple elements or compounds, where an
element can have either natural composition or consist of a single nuclide,
and compound indicates a chemical compound or a mixture or an alloy (or an
isotopic mixture) of known composition.
An element can be either predefined (see list in 5}) or defined by a MATERIAL
card giving its atomic number, atomic mass, density, name and a material
identification number > 2. The material number can be chosen by the user, with
the restriction that all lower numbers must also be defined (but not
necessarily used).
Number 1 is reserved for blackhole and 2 for ideal vacuum. There are 25
predefined materials; but each of the numbers from 3 to 25 can be redefined
freely, overriding the default definition.
Materials can also be defined with higher numbers, provided no gaps are left in
the numbering sequence. For instance a material cannot be defined to have
number 28 unless also 26 and 27 have been defined.
A compound is defined by a MATERIAL card plus as many COMPOUND cards as needed
to describe its composition. The MATERIAL card used to define a compound
carries only the compound name, density and material number (atomic number and
atomic mass having no meaning in this case).
Materials predefined or defined in the standard input are referred to as "FLUKA
materials", to distinguish them from materials available in the low-energy
neutron cross section library (called "low-energy cross-section materials).
When transport of low-energy neutrons (E < 19.6 MeV) is requested (explicitly
or by the chosen defaults), a correspondence is needed between each elemental
(i.e. not compound) "FLUKA material" and one of the "low-energy cross-section
materials" available in the FLUKA low-energy neutron library. The default
correspondence is set by the name: and if more than one material with that name
exist in the neutron library, the first in the list with that name (see
Chap. 10}) is assumed by default. The default can be changed using option
LOW-MAT.
In the case of our example, only Beryllium is necessary, apart from blackhole
and vacuum. In principle, since Beryllium is one of the pre-defined FLUKA
materials, this part could even be omitted. However, for pedagogical reasons
the following card is proposed, where index 5 is assigned to the target
material:
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
MATERIAL 4.0 9.0122 1.848 5.0 BERYLLIU
Notice that the chosen name is BERYLLIU and not BERYLLIUM, in order to match
the name in the list of "low-energy cross-section materials" for low
energy neutrons (see Chap. 10}), where material names have a maximum length of
8 characters.
The standard output concerning materials is very extended. First a list of
multiple scattering parameters (printed by subroutine MULMIX) is reported for
each material requested. This is mostly of scarce interest for the normal user,
except for a table giving for each requested material the proportion of
components, both by number of atoms (normalised to 1) and by weight (normalised
to material density). The same information is repeated later on in another
table entitled "Material compositions".
If low-energy neutron transport has been requested (explicitly or by a chosen
default), the following section reports the relevant material information: in
particular, a table entitled "Fluka to low en. xsec material correspondence"
specifying which material in the neutron cross section library has been mapped
to each input material. Note that a much more detailed cross section
information can be obtained by setting a printing flag (WHAT(4)) in the
LOW-NEUT command.
The Table "Material compositions" contains information about the requested
materials, those pre-defined by default and the elements used to define
compounds. In addition to effective atomic and mass number, density and
composition, the table shows the value of some typical quantities: inelastic
and elastic scattering length for the beam particles (not valid for electron
and photon beams), radiation length and inelastic scattering length for 19.6
MeV neutrons.
The next table contains material data related to stopping power (average
excitation energy, density effect parameters, and pressure in the case of
gases) plus information about the implementation of various physical effetcs
and the corresponding thresholds and tabulations.
The last material table is printed just before the beginning of the history
calculations, and concerns the "Correspondence of regions and EMF-FLUKA
material numbers and names".
Assigning materials to regions
------------------------------
A material must be associated to each of the geometry regions, except to those
defined as blackhole. This is done in a very straightforward way by command
ASSIGNMAt. Assigning explicitly blackhole to a region is allowed, but is not
necessary (except for region 2) because a region is blackhole by default unless
another material has been associated to it. (Region 2, if not assigned a
material, is COPPER by default).
The table entitled "Regions: materials and fields", in the standard output, can
be consulted to check that material assignment has been done as desired.
For the present example the assignment could be:
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
* Be target, 1st and 2nd half
ASSIGNMAT 5.0 3.0 4.0
* External Black Hole
ASSIGNMAT 1.0 1.0
* Vacuum
ASSIGNMAT 2.0 2.0
Production thresholds
---------------------
The implicit NEW-DEFA default setting adopted in the example, sets, among other
things, the production and transport threshold of heavy particles to 10 MeV.
Production thresholds for e+e- and photons must be explicitly set using the
EMFCUT command for all materials in the problem. Let us choose also in this
case a 10 MeV threshold for the single material of the example (previously
marked with material index 5). Following the instructions about the EMFCUT
option, the card can be written as:
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
* e+e- and gamma production threshold set at 10 MeV
EMFCUT -0.010 0.010 1.0 5.0 PROD-CUT
where the first numerical field is the threshold for e+e- (the minus sign
meaning kinetic energy) and the second is for photons. The material number is
given in the fourth numerical field. For details on all other parameters, and
for other possibilities (for example how to introduce a transport cut-off
different from production threshold) the user should accurately consult the
Notes to EMFCUT.
Production and transport threshold for all other particles can be overwritten
using the PART-THR command.
Estimators and Detectors
------------------------
Even though, for setting-up purposes, it is conceivable that no estimator be
requested in a preliminary run, in most cases FLUKA is used to predict the
expectation value of one or more quantities, as determined by the radiation
field and by the material geometry described by the user: for such a task
several different estimators are available. The quantities which are most
commonly scored are dose and fluence, but others are available. Dose equivalent
is generally calculated from differential fluence using conversion
coefficients.
The simplest estimator available to the user is a historical vestige, survived
from the "ancient" FLUKA (pre-1988) where the only possible output quantities
were energy deposition and star density in regions. It is invoked by option
SCORE, requesting evaluation of one to four different quantities. These can be
different forms of energy density (proportional to dose), or of star density
(approximately proportional to fluence of selected high-energy hadrons).
For this estimator, the detectors are pre-determined: the selected quantities
are reported for each region of the geometry. The corresponding results,
printed in the main output immediately after the last history has been
completed, are presented in 6 columns as follows:
region region first second third fourth
number volume quantity quantity quantity quantity
1 ...... ........ ........ ........ ........
2 ...... ........ ........ ........ ........
etc.
on a line for each geometry region. The region volumes (in cm3) have the value
1.0, or values optionally supplied by the user at the end of the geometry
description. All other columns are normalised per region volume and per primary
particle.
The input could be as follows:
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
* score in each region energy deposition and stars produced by primaries
SCORE 208.0 210.0
Other estimators are more flexible: the corresponding detectors can be
requested practically in any number, can be written as unformatted or text
files, and in most cases can provide differential distributions with respect to
one or more variables. On the other hand, their output is presented in a very
compact array form and must generally be post-processed by the user. For this
purpose several utility programs are available: but output in text format can
even be exported to a spreadsheet for post-processing.
USRBDX is the command required to define a detector for the boundary-crossing
estimator. It calculates fluence or current, mono- or bi-directional,
differential in energy and angle on any boundary between two selected regions.
The area normalisation needed to obtain a current in particles per cm2 is
performed using an area value input by the user: if none is given, the area is
assumed to be = 1 cm2 and the option amounts simply to counting the total number
of particles crossing the boundary. Similarly if fluence is scored, but in this
case each particle is weighted with the secant of the angle between the
particle trajectory and the normal to the boundary surface at the crossing
point.
This is one of the estimators proposed for our example. We will request two
boundary crossing detectors, one to estimate fluence and one for current, of
particles crossing the boundary which separates the upstream and the downstream
half of the target.
The following group of cards can be inserted:
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
* Boundary crossing fluence in the middle of the target (log intervals, one-way)
USRBDX 99.0 209.0 -47.0 3.0 4.0 400. piFluenUD
USRBDX +50.0 +50.0 0.0 10.0 &
*
* Boundary crossing current in the middle of the target (log intervals, one-way)
USRBDX -1.0 209.0 -47.0 3.0 4.0 400. piCurrUD
USRBDX +50.00 +50.0 0.0 10.0 &
According to the instructions reported in the description of the USRBDX
command, it can be seen that the combined fluence of pi+ and pi- is requested
only when particles exit region "3" (the upstream half of the target) to enter
into region "4" (the downstream half). There is no interest in the reverse,
therefore "one-way scoring" is selected. The scoring of the first detector
will be inverse cosine-weighted, in order to define correctly the fluence.
Results will be written unformatted on unit 47 for both quantities (so there
will be two "Detectors" on the same output unit, but this is not mandatory).
The energy distribution is going to be binned in 50 logarithmic intervals, from
0.001 GeV (the default minimum) up to 50 GeV. The angular distribution will be
binned into 10 linear solid angle intervals from 0. to 2pi (having chosen the
one-way estimator). The results will be normalised dividing by the area of the
boundary (separation surface between the two regions, in this case the
transverse section of the target), and will provide a double-differential
fluence or current averaged over that surface in cm-2 GeV-1 sr-1.
Other fluence scoring options, based respectively on a track-length and on a
collision estimator, are USRTRACK and USRCOLL which request the estimation of
volume-averaged fluence (differential in energy) for any type of particle or
family of particles in any selected region. The volume normalisation needed to
obtain the fluence as track-length density or collision density is performed
using a volume value input by the user: if none is given, the volume is assumed
to be = 1 cm3 and the result will be respectively the total track-length in
that region, or the total number of collisions (weighted with the mean free
path at each collision point).
Note that if additional normalisation factors are desired (e.g. beam power)
this can be achieved by giving in input the "volume" or "area" value
multiplied or divided by those factors. Options USRTRACK, USRCOLL and
USRBDX can also calculate energy fluence, if the "particle" type is set
= 208 (energy) or 211 (electron and photon energy).
In our example, we are requesting two track-length detectors, to get the
average fluence in the upstream half and in the downstream half of the target,
respectively.
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
* Tracklength fluence inside the target, Upstream part and Downstream part
* Logarithmic energy intervals
USRTRACK -1.0 209.0 -48.0 3.0 1000.0 20. piFluenU
USRTRACK 50.0 0.001 &
USRTRACK -1.0 209.0 -49.0 4.0 1000.0 20. piFluenD
USRTRACK 50.0 0.001 &
The volume input is 20 x 20 x 2.5 = 1000 cm3. We are requesting an energy
spectrum in 20 logarithmic intervals between 0.001 and 50 GeV. In this case, we
ask that the corresponding output be printed, unformatted, on two different
files.
Option USRBIN provides detailed space distributions of energy deposition, star
density or integrated fluence (not energy fluence, unless by writing a special
user routine). Using some suitable graphics package, USRBIN output can be
presented in the form of colour maps. Programs for this purpose are available
in the $FLUPRO/flutil directory (pawlevbin.f and various kumac files), and
on the FLUKA website www.fluka.org.
USRBIN results are normalised to bin volumes calculated automatically by the
program (except in the case of region binning and special 3-variable binning
which are only seldom used).
The binning structure does not need to coincide with any geometry region. In
our example we propose to ask for two Cartesian space distributions, one of
charged pion fluence and one of total energy deposited. The first will extend
over a volume larger than the target, because fluence can be calculated even in
vacuum. Energy deposition, on the other hand, will be limited to the target
volume.
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
* Cartesian binning of the pion fluence inside and around the target
USRBIN 10.0 209.0 -50.0 50.0 50.0 50. piFluBin
USRBIN -50.0 -50.0 -10.0 100.0 100.0 60.0 &
* Cartesian binning of the deposited energy inside the target
USRBIN 10.0 208.0 -51.0 10.0 10.0 5. Edeposit
USRBIN -10.0 -10.0 0.0 20.0 20.0 5.0 &
Also in this case, the request is for output on two separate files.
Angular yields around a fixed direction of particles exiting a given surface
can be calculated using option USRYIELD. The results are double-differential
distributions with respect to a pair of variables, one of which is generally
energy-like (kinetic energy, momentum, etc.) and the other one angle-like (polar
angle, rapidity, Feynman-x, etc.) Distributions in LET (Linear Energy Transfer)
can also be requested by this option. An arbitrary normalisation factor can be
input.
Another commonly used scoring option is RESNUCLEi, which calculates residual
nuclei production in a given region. A normalisation factor (usually the region
volume) can be input.
A detailed summary of the requested estimators is printed on standard output.
The same information is printed in the same format in estimator ASCII output
files, and is available in coded form in unformatted estimator files.
Initialisation of the random number sequence
--------------------------------------------
The random number sequence used in a run is initialised by default by the seeds
contained in file random.dat provided with the code. To calculate the statistical
error of the results, it is necessary to perform other independent runs (at
least 4 or 5), each with a different independent initialisation, using the seeds
written by the program at the end of each run. The rfluka script provided with
the code on UNIX and LINUX platforms takes care of this task, provided the
following card is issued in the input file:
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
RANDOMIZE 1.0 0.0
The seeds of the random number generator are printed on a special file in
hexadecimal form at the end of each group of histories (the size of
a group depends on the number of histories requested in the START card).
Instead of getting the seeds from the last run, it is also possible to
initialise directly another independent random number sequence by setting the
second RANDOMIZe parameter equal to a different number, for instance:
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
RANDOMIZE 1.0 1198.
Starting signal and number of requested histories
-------------------------------------------------
At the end of the input file, a START card is mandatory in order to actually
start the calculation. That card must indicate also the number of particle
histories requested. The run, however, may be completed before all the histories
have been handled in two cases: if a time limit has been met (on some systems)
or if a "stop file" is created by the user (see instructions in a Note to option
START). The START card is optionally followed by a STOP card. For example, if
the user wants to generate 100000 histories, the input file can be closed with
the following two cards:
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
START 100000.0
STOP
The sample input file
---------------------
In summary, the input file for our basic example (example.inp), written in
fixed format, is the following:
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
TITLE
Charged pion fluence inside and around a proton-irradiated Be target
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
BEAM 50.E+00 PROTON
BEAMPOS 0.0 0.0 -50.0
*
GEOBEGIN COMBINAT
A simple Be target inside vacuum
RPP 1-5000000.0+5000000.0-5000000.0+5000000.0-5000000.0+5000000.0
RPP 2-1000000.0+1000000.0-1000000.0+1000000.0 -100.0+1000000.0
RPP 3 -10.0 +10.0 -10.0 +10.0 0.0 +5.0
* plane to separate the upstream and downstream part of the target
XYP 4 2.5
END
* black hole
BH1 5 +1 -2
* vacuum around
VA2 5 +2 -3
* Be target 1st half
BE3 5 +3 +4
* Be target 2nd half
BE4 5 +3 -4
END
GEOEND
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
MATERIAL 4.0 9.0122 1.848 5.0 BERYLLIU
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
* Be target, 1st and 2nd half
ASSIGNMAT 5.0 3.0 4.0
* External Black Hole
ASSIGNMAT 1.0 1.0
* Vacuum
ASSIGNMAT 2.0 2.0
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
* e+e- and gamma production threshold set at 10 MeV
EMFCUT -0.010 0.010 1.0 5.0 PROD-CUT
* score in each region energy deposition and stars produced by primaries
SCORE 208.0 210.0
* Boundary crossing fluence in the middle of the target (log intervals, one-way)
USRBDX 99.0 209.0 -47.0 3.0 4.0 400. piFluenUD
USRBDX +50.0 +50.0 0.0 10.0 &
* Boundary crossing current in the middle of the target (log intervals, one-way)
USRBDX -1.0 209.0 -47.0 3.0 4.0 400. piCurrUD
USRBDX +50.0 +50.0 0.0 10.0 &
* Tracklength fluence inside the target, Upstream part and Downstream part
* Logarithmic energy intervals
USRTRACK -1.0 209.0 -48.0 3.0 1000.0 20. piFluenU
USRTRACK 50.0 0.001 &
USRTRACK -1.0 209.0 -49.0 4.0 1000.0 20. piFluenD
USRTRACK 50.0 0.001 &
* Cartesian binning of the pion fluence inside and around the target
USRBIN 10.0 209.0 -50.0 50.0 50.0 50. piFluBin
USRBIN -50.0 -50.0 -10.0 100.0 100.0 60.0 &
* Cartesian binning of the deposited energy inside the target
USRBIN 10.0 208.0 -51.0 10.0 10.0 5. Edeposit
USRBIN -10.0 -10.0 0.0 20.0 20.0 5.0 &
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
RANDOMIZE 1.0
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
START 100000.0
STOP
The same input file, using the free format option for the FLUKA commands, but
not for the geometry, can instead be written as follows:
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
TITLE
Charged pion fluence inside and around a proton-irradiated Be target
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
GLOBAL 2.0
BEAM 50.E+00 0. 0. 0. 0. 0. PROTON
BEAMPOS 0. 0. -50.0 0. 0. 0. ' '
*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
GEOBEGIN COMBINAT
A simple Be target inside vacuum
RPP 1-5000000.0+5000000.0-5000000.0+5000000.0-5000000.0+5000000.0
RPP 2-1000000.0+1000000.0-1000000.0+1000000.0 -100.0+1000000.0
RPP 3 -10.0 +10.0 -10.0 +10.0 0.0 +5.0
XYP 4 2.5
END
* black hole
BH1 5 +1 -2
* vacuum around
VA2 5 +2 -3
* Be target 1st half
BE3 5 +3 +4
* Be target 2nd half
BE4 5 +3 -4
END
GEOEND
MATERIAL 4.0 9.0122 1.848 5.0 0. 0. BERYLLIU
* Be target, 1st and 2nd half
ASSIGNMAT 5.0 3.0 4.0 0. 0. 0.
* External Black Hole
ASSIGNMAT 1.0 1.0 0. 0. 0. 0.
* Vacuum
ASSIGNMAT 2.0 2.0 0. 0. 0. 0.
* e+e- and gamma production threshold set at 10 MeV
EMFCUT -0.010 0.010 1.0 5.0, , , PROD-CUT
* score in each region energy deposition and stars produced by primaries
SCORE 208.0 210. 0. 0. 0. 0.
* Boundary crossing fluence in the middle of the target (log intervals, one-way)
USRBDX 99.0 +209.0 -47.0 3.0 4.0 +400.0 piFluenUD
USRBDX +50.00 0. +50.0 0. 0. 10.0 &
* Boundary crossing current in the middle of the target (log intervals, one-way)
USRBDX -1.0 +209.0 -47.0 3.0 4.0 +400.0 piCurrUD
USRBDX +50.00 0. +50.0 0. 0. 10.0 &
* Tracklength fluence inside the target, Upstream part and Downstream part
* Logarithmic energy intervals
USRTRACK -1.0 209.0 -48.0 3.0 1000.0 20. piFluenU
USRTRACK 50.0 0.001 0. 0. 0. 0. &
USRTRACK -1.0 209.0 -49.0 4.0 1000.0 20. piFluenD
USRTRACK 50.0 0.001 0. 0. 0. 0. &
* Cartesian binning of the pion fluence inside and around the target
USRBIN 10.0 209.0 -50.0 50.0 50.0 50. piFluBin
USRBIN -50.0 -50.0 -10.0 100.0 100.0 60.0 &
* Cartesian binning of the deposited energy inside the target
USRBIN 10.0 208.0 -51.0 10.0 10.0 5. Edeposit
USRBIN -10.0 -10.0 0.0 20.0 20.0 5.0 &
RANDOMIZE 1.0 0. 0. 0. 0. 0.
START 100000.0 0. 0. 0. 0. 0.
STOP
Running FLUKA
-------------
It is advisable, but not mandatory, to keep separate the $FLUPRO directory
from that or those where calculations are run and input files are kept.
For instance, flukawork:
cd /home/user/flukawork
As mentioned above, the rfluka script in $FLUPRO/flutil should be used to drive
the FLUKA run. In the following it is supposed that the user is going to ask
for five statistically independent runs, each one made of 100000 histories, of
the proposed basic example. The command is:
$FLUPRO/flutil/rfluka -N0 -M5 example &
(on LINUX/UNIX, the \& character allows to run the program in the background
without "freezing" the terminal window).
The script creates a temporary subdirectory called fluka_nnnn where
nnnn is tbe number of the subprocess. For instance, when the first
run (or "cycle") starts, the user will see on the terminal lines similar
to the following ones:
$TARGET_MACHINE = Linux
$FLUPRO = /home/user/flupro
2789: old priority 0, new priority 10
Initial seed already existing
Running fluka in /home/user/flukawork/fluka_2789
================================ Running FLUKA for cycle # 1 ===================
At the end of each cycle the output files will be copied onto the running
directory, the temporary directory will be erased and a new one will be created
where the next run will take place. The names of the output files from each run
are built by appending to the input file name the run number and an extension
depending on their content: .out for the standard output, .err for the error
file, .log for the log file and _fort.nn for the estimator files (with
nn = absolute value of the selected output unit). The file containing the
random number seeds will be called "ran".
The error file may contain error messages related to the event generators (for
instance when the program does not manage to conserve exactly energy or another
quantity) or to the geometry tracking. Most of those are generally only warning
messages which can be ignored unless there is a large number of them.
The log file generally contains messages related to fatal errors (input errors,
overflow, etc.)
During a multiple run, lines like the following will appear on the user's
screen:
================================ Running FLUKA for cycle # 1 ====================
Removing links
Removing temporary files
Saving output and random number seed
Saving additional files generated
Moving fort.47 to /home/fasso/Fluka/test/example01_fort.47
Moving fort.48 to /home/fasso/Fluka/test/example01_fort.48
Moving fort.49 to /home/fasso/Fluka/test/example01_fort.49
Moving fort.50 to /home/fasso/Fluka/test/example01_fort.50
Moving fort.51 to /home/fasso/Fluka/test/example01_fort.51
================================ Running FLUKA for cyle # 2 ====================
Removing links
Removing temporary files
Saving output and random number seed
Saving additional files generated
Moving fort.47 to /home/fasso/Fluka/test/example002_fort.47
Moving fort.48 to /home/fasso/Fluka/test/example002_fort.48
Moving fort.49 to /home/fasso/Fluka/test/example002_fort.49
Moving fort.50 to /home/fasso/Fluka/test/example002_fort.50
Moving fort.51 to /home/fasso/Fluka/test/example002_fort.51
================================ Running FLUKA for cycle # 3 ===================
.....
================================ Running FLUKA for cycle # 4 ===================
.....
================================ Running FLUKA for cycle # 5 ===================
Removing links
Removing temporary files
Saving output and random number seed
Saving additional files generated
Moving fort.47 to /home/fasso/Fluka/test/example005_fort.47
Moving fort.48 to /home/fasso/Fluka/test/example005_fort.48
Moving fort.49 to /home/fasso/Fluka/test/example005_fort.49
Moving fort.50 to /home/fasso/Fluka/test/example005_fort.50
Moving fort.51 to /home/fasso/Fluka/test/example005_fort.51
End of FLUKA run
At this time, in the working directory, the following new files exist:
example001_fort.47 example002_fort.47 .... example005_fort.47
example001_fort.48 example002_fort.48 .... example005_fort.48
example001_fort.49 example002_fort.49 .... example005_fort.49
example001_fort.50 example002_fort.50 .... example005_fort.50
example001_fort.51 example002_fort.51 .... example005_fort.51
example001.out example002.out .... example005.out
example001.err example002.err .... example005.err
In Chapter 9} the user can find a comprehensive description of the content of
the FLUKA standard output. For the purpose of this beginner's guide, it can
just be pointed out that, according to the content of the USRBDX command, the
files with extension fort.47 contain, in binary form, the boundary crossing
estimator output for the required pion fluence and current detectors (for more
details see Chap. 9}). These files must be combined together to produce a
table of values with their statistical errors which can be easily interfaced by
the user to some analysis codes and/or graphic visualisation tools. Similarly,
the files with extension fort.48 and fort.49 will contain the tracklength
estimator output, and those with extension fort.50 and fort.51 the output from
USRBIN.
Accessing results
-----------------
Boundary crossing estimator
Binary files from the USRBDX estimator can be accessed by means of the usxsuw.f
readout code, which is located in the $FLUPRO/flutil directory.
That readout code can be easily compiled. For example, the same compiling and
linking FLUKA tools can be used for this purpose:
cd $FLUPRO/flutil
./lfluka usxsuw.f -o usxsuw
In order to process the 5 output files produced by the proposed example, the
following interactive procedure can be used:
cd /home/user/flukawork
$FLUPRO/flutil/usxsuw
The readout code will ask for the first FLUKA estimator file name:
Type the input file:
For each estimator file the program will show the content of the TITLE card of
the FLUKA input file, the date and time of the FLUKA run and the number of
histories for the given run.
The request will be iterated until a blank line is given. This will be
interpreted as the end of the list of files, and then a name for the
output file prefix will be requested. Let's use, for example, the
name "pionbdx":
Type the input file: example001_fort.47
Charged pion fluence inside and around a proton-irradiated Be target
DATE: 7/15/ 5, TIME: 16:22:11
100000.
100000
Type the input file: example002_fort.47
Charged pion fluence inside and around a proton-irradiated Be target
DATE: 7/15/ 5, TIME: 16:23: 3
100000.
100000
Type the input file: example003_fort.47
Charged pion fluence inside and around a proton-irradiated Be target
DATE: 7/15/ 5, TIME: 16:23:54
100000.
100000
Type the input file: example004_fort.47
Charged pion fluence inside and around a proton-irradiated Be target
DATE: 7/15/ 5, TIME: 16:24:51
100000.
100000
Type the input file: example005_fort.47
Charged pion fluence inside and around a proton-irradiated Be target
DATE: 7/15/ 5, TIME: 16:25:45
100000.
100000
Type the input file:
Type the output file name: pionbdx
At this point the following 3 new files are produced:
pionbdx
pionbdx_sum.lis
pionbdx_tab.lis
The first one (pionbdx) is again a binary file that can be read out at any time
by usxsuw. The content of this file is statistically equivalent to that of the
sum of the files used to obtain it, and it can replace them to be combined with
further output files if desired (the usxsuw program takes care of giving it the
appropriate weight).
The other two files are ASCII text files.
Let us first examine pionbdx_sum.lis. This contains many comments which can
help the user to understand the results. Since by means of the USRBDX command
separate detectors for pion fluence and current have been requested, with their
output on the same logical unit, there will be two different sections in the
file, identified by the word "Detector": Detector no. 1 is for fluence and
Detector no. 2 is for current, because this is the order in which the
USRBDX commands have been given.
Let us inspect the output from Detector no. 1:
Charged pion fluence inside and around a proton-irradiated Be target
Total primaries run: 500000
Total weight of the primaries run: 500000.
Detector n: 1( 1) piFluenUD
(Area: 400. cmq,
distr. scored: 209 ,
from reg. 3 to 4,
one way scoring,
fluence scoring)
Tot. resp. (Part/cmq/pr) 8.6904905E-04 +/- 0.6976866 %
( --> (Part/pr) 0.3476196 +/- 0.6976866 % )
The total (summed) number of primaries (histories) is reported at first, then
the main features of USRBDX request are summarised. The following numbers
represent the energy and angle integrated fluence ("total response").
Here and later, the statistical error is always expressed in percentage.
After this heading, the differential fluence tabulation as a function of (pion)
energy, and integrated over solid angle, is reported, starting with the
boundaries of the energy bins. As a general convention, these values are given
from the highest to the lowest value:
**** Different. Fluxes as a function of energy ****
**** (integrated over solid angle) ****
Energy boundaries (GeV):
49.99992 40.27077 32.43475 26.12349 21.04029
16.94620 13.64875 10.99293 8.853892 7.131072
5.743484 4.625898 3.725775 3.000802 2.416896
1.946608 1.567831 1.262757 1.017045 0.8191454
0.6597533 0.5313764 0.4279793 0.3447017 0.2776285
0.2236066 0.1800965 0.1450527 0.1168279 9.4095118E-02
7.5785778E-02 6.1039131E-02 4.9161937E-02 3.9595842E-02 3.1891152E-02
2.5685664E-02 2.0687662E-02 1.6662188E-02 1.3420003E-02 1.0808695E-02
8.7055033E-03 7.0115575E-03 5.6472253E-03 4.5483690E-03 3.6633324E-03
2.9505091E-03 2.3763892E-03 1.9139835E-03 1.5415541E-03 1.2415934E-03
Lowest boundary (GeV): 1.0000000E-03
Flux (Part/GeV/cmq/pr):
1.5418744E-09 +/- 99.00000 % 4.8503271E-08 +/- 6.709127 %
2.3456116E-07 +/- 6.506497 % 5.9040013E-07 +/- 3.466331 %
1.2585346E-06 +/- 4.051404 % 2.5295039E-06 +/- 2.039807 %
4.6113087E-06 +/- 2.195296 % 7.6260553E-06 +/- 1.939942 %
1.2214471E-05 +/- 0.8310503 % 1.8394410E-05 +/- 0.6178440 %
2.6636921E-05 +/- 1.128397 % 3.6855919E-05 +/- 1.204921 %
5.1703457E-05 +/- 1.100655 % 6.9101960E-05 +/- 0.7564522 %
9.0419722E-05 +/- 1.799108 % 1.1945122E-04 +/- 1.256268 %
1.5757892E-04 +/- 0.8898824 % 1.9452766E-04 +/- 1.332425 %
2.4165030E-04 +/- 1.521364 % 3.0573772E-04 +/- 2.473622 %
3.6900895E-04 +/- 1.399170 % 4.4734811E-04 +/- 0.9543594 %
5.2953843E-04 +/- 1.964312 % 6.1596523E-04 +/- 1.349476 %
6.4003764E-04 +/- 3.323846 % 6.8828161E-04 +/- 0.9288639 %
6.8151421E-04 +/- 2.018673 % 7.0822553E-04 +/- 4.401796 %
7.4972271E-04 +/- 2.600316 % 6.9859857E-04 +/- 3.693749 %
6.8915845E-04 +/- 4.332464 % 6.6514849E-04 +/- 8.753220 %
6.4636284E-04 +/- 11.30834 % 5.5008888E-04 +/- 7.691558 %
4.3721433E-04 +/- 11.36630 % 3.2056248E-04 +/- 8.380781 %
4.2511927E-04 +/- 12.24571 % 2.2697043E-04 +/- 12.99932 %
2.0069227E-04 +/- 13.10813 % 1.7180138E-04 +/- 16.90801 %
9.9383309E-05 +/- 21.15753 % 2.9268101E-04 +/- 39.29378 %
1.5672133E-04 +/- 44.01294 % 2.1093644E-04 +/- 34.72458 %
7.4201569E-05 +/- 33.68359 % 7.2452240E-05 +/- 33.54827 %
8.6934262E-05 +/- 62.03180 % 1.0245090E-04 +/- 99.00000 %
1.6312006E-04 +/- 82.06016 % 1.3002084E-04 +/- 52.15991 %
Soon after, the cumulative fluence distribution as a function of energy is also
given:
**** Cumulative Fluxes as a function of energy ****
**** (integrated over solid angle) ****
Energy boundaries (GeV):
49.99992 40.27077 32.43475 26.12349 21.04029
16.94620 13.64875 10.99293 8.853892 7.131072
5.743484 4.625898 3.725775 3.000802 2.416896
1.946608 1.567831 1.262757 1.017045 0.8191454
0.6597533 0.5313764 0.4279793 0.3447017 0.2776285
0.2236066 0.1800965 0.1450527 0.1168279 9.4095118E-02
7.5785778E-02 6.1039131E-02 4.9161937E-02 3.9595842E-02 3.1891152E-02
2.5685664E-02 2.0687662E-02 1.6662188E-02 1.3420003E-02 1.0808695E-02
8.7055033E-03 7.0115575E-03 5.6472253E-03 4.5483690E-03 3.6633324E-03
2.9505091E-03 2.3763892E-03 1.9139835E-03 1.5415541E-03 1.2415934E-03
Lowest boundary (GeV): 1.0000000E-03
Cumul. Flux (Part/cmq/pr):
1.5001119E-08 +/- 99.00000 % 3.9507350E-07 +/- 7.326498 %
1.8754495E-06 +/- 5.464718 % 4.8765669E-06 +/- 1.819896 %
1.0029117E-05 +/- 1.898280 % 1.8370021E-05 +/- 1.277005 %
3.0616819E-05 +/- 0.6900454 % 4.6929261E-05 +/- 0.9553517 %
6.7972585E-05 +/- 0.7029299 % 9.3496434E-05 +/- 0.6531623 %
1.2326548E-04 +/- 0.5382378 % 1.5644032E-04 +/- 0.6154544 %
1.9392396E-04 +/- 0.6043725 % 2.3427299E-04 +/- 0.5368618 %
2.7679623E-04 +/- 0.5548110 % 3.2204165E-04 +/- 0.6000980 %
3.7011484E-04 +/- 0.6263003 % 4.1791250E-04 +/- 0.6480659 %
4.6573509E-04 +/- 0.7125404 % 5.1446725E-04 +/- 0.7778813 %
5.6183949E-04 +/- 0.8066853 % 6.0809392E-04 +/- 0.7142704 %
6.5219263E-04 +/- 0.7654761 % 6.9350738E-04 +/- 0.7260005 %
7.2808337E-04 +/- 0.8159186 % 7.5803063E-04 +/- 0.7573094 %
7.8191340E-04 +/- 0.7549785 % 8.0190296E-04 +/- 0.7531289 %
8.1894622E-04 +/- 0.7366922 % 8.3173712E-04 +/- 0.6872664 %
8.4189989E-04 +/- 0.6799491 % 8.4980001E-04 +/- 0.6579692 %
8.5598318E-04 +/- 0.6862395 % 8.6022145E-04 +/- 0.6667165 %
8.6293457E-04 +/- 0.6859071 % 8.6453673E-04 +/- 0.6995495 %
8.6624804E-04 +/- 0.6864265 % 8.6698390E-04 +/- 0.6886846 %
8.6750800E-04 +/- 0.6864119 % 8.6786930E-04 +/- 0.6882262 %
8.6803763E-04 +/- 0.6885374 % 8.6843700E-04 +/- 0.6933275 %
8.6860918E-04 +/- 0.6915213 % 8.6879585E-04 +/- 0.6911866 %
8.6884876E-04 +/- 0.6931223 % 8.6889038E-04 +/- 0.6942393 %
8.6893054E-04 +/- 0.6953420 % 8.6896872E-04 +/- 0.6967193 %
8.6901762E-04 +/- 0.6981055 % 8.6904905E-04 +/- 0.6976866 %
The numbers for the cumulative distribution have been obtained by multiplying
each value of the differential distribution by the corresponding energy bin
width (variable if the distribution is logarithmic as in our example). The
integral fluence in any given energy interval can be obtained as the difference
between the values of the cumulative distribution at the two bounds of that
interval.
Since more than one angular interval was requested, at this point the angular
distribution WITH RESPECT TO THE NORMAL AT THE BOUNDARY CROSSING POINT is
reported, both in steradians and in degrees:
**** Double diff. Fluxes as a function of energy ****
Solid angle minimum value (sr): 0.000000
Solid angle upper boundaries (sr):
0.6283185 1.256637 1.884956 2.513274 3.141593
3.769911 4.398230 5.026548 5.654867 6.283185
Angular minimum value (deg.): 0.000000
Angular upper boundaries (deg.):
25.84193 36.86990 45.57299 53.13010 60.00000
66.42182 72.54239 78.46304 84.26083 90.00000
Let us take for instance the energy bin between 0.345 GeV and 0.278 GeV:
Energy interval (GeV): 0.3447016 0.2776284
Flux (Part/sr/GeV/cmq/pr):
2.2090337E-04 +/- 2.271138 % 1.6099877E-04 +/- 2.023665 %
1.2373505E-04 +/- 3.802638 % 9.4749055E-05 +/- 2.419357 %
7.0389280E-05 +/- 5.640523 % 6.6853667E-05 +/- 9.292711 %
6.8042267E-05 +/- 5.421218 % 6.8482914E-05 +/- 11.91976 %
5.8157104E-05 +/- 2.943847 % 4.8027632E-05 +/- 39.71496 %
Flux (Part/deg/GeV/cmq/pr):
5.3710260E-06 +/- 2.271138 % 9.1729089E-06 +/- 2.023665 %
8.9330297E-06 +/- 3.802638 % 7.8776966E-06 +/- 2.419357 %
6.4377805E-06 +/- 5.640523 % 6.5410413E-06 +/- 9.292711 %
6.9850003E-06 +/- 5.421218 % 7.2676362E-06 +/- 11.91976 %
6.3026077E-06 +/- 2.943847 % 5.2580162E-06 +/- 39.71496 %
The same structure is then replicated for Detector no. 2:
Detector n: 2( 2) piCurrUD
(Area: 400. cmq,
distr. scored: 209 ,
from reg. 3 to 4,
one way scoring,
current scoring)
Tot. resp. (Part/cmq/pr) 7.1694393E-04 +/- 0.7243900 %
( --> (Part/pr) 0.2867776 +/- 0.7243900 % )
and so on.
Note that in this case the ratio between the calculated fluence (8.690E-04) and
the corresponding current (7.169E-04) is about 1.2. The ratio between the
numerical values of the two quantities would be 1 if the pions were all
crossing the boundary at a right angle, 2 in the case of an isotropic
distribution, and could even tend to infinity if the particle direction were
mainly parallel to the boundary:
FLUENCE AND CURRENT ARE VERY DIFFERENT QUANTITIES AND SHOULD NOT BE CONFUSED!
Note also that the above output reports also the current value not normalised
per unit area. This is equivalent to a simple count of crossing particles, so
we see that in our example about 0.287 charged pions per primary proton cross
the middle plane of the target.
The previous file has a structure which is not easily interfaceable to other
readout codes. This can be easily achieved by means of the other output file,
pionbdx_tab.lis: there the user can find, for each Detector, a simple 4-column
structure for the differential fluence integrated over solid angle. The table
starts from the lowest energy and the four columns represent respectively
E_min, E_max, the differential fluence and the statistical error in percentage:
# Detector n: 1 piFluenUD (integrated over solid angle)
# N. of energy intervals 50
1.000E-03 1.242E-03 1.300E-04 5.216E+01
1.242E-03 1.542E-03 1.631E-04 8.206E+01
1.542E-03 1.914E-03 1.025E-04 9.900E+01
1.914E-03 2.376E-03 8.693E-05 6.203E+01
2.376E-03 2.951E-03 7.245E-05 3.355E+01
2.951E-03 3.663E-03 7.420E-05 3.368E+01
3.663E-03 4.548E-03 2.109E-04 3.472E+01
4.548E-03 5.647E-03 1.567E-04 4.401E+01
5.647E-03 7.012E-03 2.927E-04 3.929E+01
.....
By convention, when in a given bin the statistics is not sufficient to
calculate a standard deviation, the statistical error is printed as 99%. For a
null fluence the statistical error is also null.
After this table, the double differential fluence is reported.
First, one or more lines marked by a # sign in column 1 give, from minimum to
maximum, the extremes of the solid angle intervals. Then, for each energy
interval, the minimum and maximum of the interval followed by as many pairs of
values as the number of angular bins: the first value is the calculated
double-differential quantity (fluence or current) in cm-2 sr-1 and the second
is the corresponding statistical error in percent.
For instance, for our example we obtain the following printout (for the sake of
space only 3 bins in energy are shown):
# double differential distributions
# number of solid angle intervals 10
# 0.000E+00 6.283E-01 6.283E-01 1.257E+00 1.257E+00 1.885E+00 ...
#
....
2.069E-02 2.569E-02 4.013E-05 2.472E+01 4.509E-05 2.068E+01 ...
2.569E-02 3.189E-02 5.408E-05 1.907E+01 4.657E-05 2.200E+01 ...
3.189E-02 3.960E-02 5.150E-05 7.137E+00 5.355E-05 1.587E+01 ...
....
Track length estimator
The program to analyse USRTRACK binary output is called ustsuw.f and can also
be found in $FLUPRO/flutil. Its use is very similar to that of usxsuw.f
described above. Applying it to the example00*_fort.48 files (output of the
first USRTRACK detector in our example), we obtain for the average fluence of
charged pions in the upstream half of the beryllium target:
Tot. response (p/cmq/pr) 5.4765277E-04 +/- 0.6965669 %
and from the example00*_fort.49 files (pion fluence in the downstream half):
Tot. response (p/cmq/pr) 1.3474772E-03 +/- 0.5352812 %
As it was to be expected, the average fluence obtained above by the boundary
crossing estimator on the middle surface (8.69E-04 cm-2) has a value which is
intermediate between these two.
Binning estimator
To analyse the binary output from USRBIN, two programs are needed, both
available in $FLUPRO/flutil. The first, usbsuw.f, performs a statistical
analysis of the results and produces a new unformatted file, with a name chosen
by the user. The second program, usbrea.f, reads the latter file and writes on
a formatted file two arrays, namely the content of each bin, averaged over the
given number of runs, followed by the corresponding errors in percent. The
second USRBIN detector defined in example.inp gives the following values
of energy deposition (in GeV/cm3):
1
Cartesian binning n. 1 "Edeposit " , generalized particle n. 208
X coordinate: from -1.0000E+01 to 1.0000E+01 cm, 20 bins ( 1.0000E+00 cm wide)
Y coordinate: from -1.0000E+01 to 1.0000E+01 cm, 20 bins ( 1.0000E+00 cm wide)
Z coordinate: from 0.0000E+00 to 5.0000E+00 cm, 5 bins ( 1.0000E+00 cm wide)
Data follow in a matrix A(ix,iy,iz), format (1(5x,1p,10(1x,e11.4)))
accurate deposition along the tracks requested
1.7164E-07 3.4587E-07 2.1976E-07 3.0997E-07 1.4963E-07 3.5431E-07 .....
5.6597E-07 7.5792E-07 3.6563E-07 2.7822E-07 2.6084E-07 2.8645E-07 .....
2.6191E-07 1.6716E-07 3.8680E-07 2.4925E-07 4.2334E-07 3.5025E-07 .....
.............................................................................
and the following corresponding percentage errors:
Percentage errors follow in a matrix A(ix,iy,iz), format (1(5x,1p,10(1x,e11.4)))
1.3936E+01 4.3211E+01 3.0601E+01 2.2874E+01 1.7783E+01 2.7942E+01 .....
1.6548E+01 1.2291E+01 1.4539E+01 2.4576E+01 2.7828E+01 1.7247E+01 .....
2.2423E+01 1.7258E+01 2.0349E+01 3.7997E+01 2.6855E+01 2.9230E+01 .....
.............................................................................
Readout of other FLUKA estimators
---------------------------------
The $FLUPRO/flutil directory contains other similar programs to average the
outputs from other FLUKA estimators (not used in the present example):
- usrsuw.f: to read out the RESNUCLEi output
- usysuw.f: to read out the USRYIELD output
Various settings
----------------
Accuracy and computer speed depend on several parameters that can be freely
tuned by the user: but in general an increase of either one results in a
decrease of the other. The proper balance must be based both on physical and on
practical considerations. The present defaults have been designed to give
satisfactory results in the most common cases: but other sets of defaults can
be implemented using option DEFAULTS (to be placed at the beginning of the
input file, just after the title).
Even when one set of defaults is enforced, the user can still override some of
them by modifying single parameters. The most used ones concern energy cut-offs
(option EMFCUT for electrons and photons, LOW-BIAS for low-energy neutrons,
PART-THR for all other particles), thresholds for delta-ray production (option
DELTARAY), particles to be ignored (option DISCARD), switching on or off some
physical effect (EMFCUT, IONFLUCT, MUPHOTON, PAIRBREM, PHOTONUC, PHYSICS,
POLARIZAti), and (more rarely) the size of the step for transporting charged
particles (FLUKAFIX, MCSTHRES, MULSOPT, STEPSIZE).
Energy cut-offs for each particle are listed in a table on standard output
("Particle transport thresholds").
Biasing
-------
Although FLUKA is able to perform fully analogue particle transport
calculations (i.e. to reproduce faithfully actual particle histories), in many
cases of very non-uniform radiation fields, such as those encountered in
shielding design, only a very small fraction of all the histories contributes
to the desired response (dose, fluence) in the regions of interest, for
instance behind thick shielding. In these cases, the user's concern is not to
simulate exactly what occurs in reality, but to estimate in the most efficient
way the desired response. This can be obtained by replacing the actual physical
problem with a mathematically equivalent one, i.e. having the same solution but
faster statistical convergence.
A rigorous mathematical treatment of such variance-reduction techniques can be
found in several textbooks (see for instance those of Lux and Koblinger [Lux91]
or Carter and Cashwell [Car75]).
In the present practical introduction we will only issue a few important
warnings:
1) In the limit of the number of histories tending to infinity, the value of
all calculated quantities tend EXACTLY to the same average in the analogue
and in the corresponding biased calculation. In other words, biasing is
mathematically correct and implies no approximation. However, an
acceleration of convergence in certain regions of phase space
(space/energy/angle) will generally be paid for by a slower convergence in
other regions.
Because an actual calculation does not use an infinite number of particles,
but is necessarily truncated after a finite number of histories, results
must be considered with some judgment. For instance, if the number of
histories is too small, it can happen that total energy is not conserved
(check the energy budget summary at the very end of main output!)
2) A bad choice of biasing parameters may have consequences opposite to what is
desired, namely a slower convergence. A long experience, and often some
preliminary trial-and-error investigation, are needed in order to fully
master these techniques (but some biasing algorithms are "safer" than others).
3) Because biasing implies replacing some distributions by others having the
same expectation values but different variance (and different higher
moments), biasing techniques in general do not conserve correlations and
cannot describe correctly fluctuations.
The simplest (and safest) biasing option offered by FLUKA is importance
biasing, which can be requested by option BIASING. Each geometry region is
assigned an "importance", namely a number between 1.0E-4 and 1.0E+4,
proportional to the contribution that particles in that region are expected to
give to the desired result. The ratio of importances in any two adjacent
regions is used to drive a classical biasing algorithm ("Splitting" and
"Russian Roulette"). In a simple, monodimensional attenuation problem, the
importance is often set equal to the inverse of the expected fluence
attenuation factor for each region.
In electron accelerator shielding, two other biasing options are commonly
employed: EMF-BIAS and LAM-BIAS. The first one is used to request leading
particle biasing, a technique which reduces considerably the computer time
required to handle high-energy electromagnetic showers. With this option, CPU
time becomes proportional to primary energy rather than increasing
exponentially with it. Option LAM-BIAS is necessary in order to sample with
acceptable statistics photonuclear reactions which have a much lower
probability than competing electromagnetic photon reactions, but are often
more important from the radiological point of view.
Other important options are those which set weight window biasing (WW-FACTOr
WW-THRESh and WW-PROFIle) but their use requires more experience than assumed
here for a beginner.
Particle importances, weight windows and low-energy neutron biasing parameters
are reported for each region in standard output. On user's request (expressed
as SDUM = PRINT in a BIASING card), Russian Roulette and Splitting counters are
printed for each region on standard output before the final summary. Such
counters can be used for a better tuning of the biasing options.
1******************************************************************************
3} Installation
******************************************************************************
The FLUKA package for LINUX and UNIX platforms is distributed as a tar file
which can be downloaded from the FLUKA Website www.fluka.org.
The release of the FLUKA source code will be available under the licence
reported at the beginning of this volume. For most applications we distribute a
package containing a compiled library, user routines in source form, INCLUDE
files, various unformatted and formatted data files and a number of scripts for
compiling, linking and running the program on a given platform.
A list of the contents is provided in a README file, and information on the
current version, possibly overriding parts of the present manual, may be
contained in a file RELEASE-NOTES.
No external library routines are required. The timing and other necessary
service routines are already included.
In principle, FLUKA can be installed on any computer platform where a Fortran
compiler is available. However, at present only the following are supported
(see the FLUKA website http://www.fluka.org for more information).
- Hewlett-Packard 9000 Series 700/800 running HP-UX
- Sun running SunOS
- DEC computers running Digital UNIX > 4.0
- Intel PCs running LINUX:
RedHat 7.3 (compiler gcc-2.96)
RedHat 9.0 (compiler gcc-3.2.2)
Fedora
It is suggested that the user define an environmental variable FLUPRO pointing
to the directory where the distribution tar file has been opened. The FLUKA
libraries and most data files will be located in $FLUPRO, the INCLUDE files in
$FLUPRO/flukapro/, the default user routines in $FLUPRO/usermvax/, compilation
and linking scripts (as well as several postprocessing programs to analyse user
scores) in $FLUPRO/flutil/.
If the source code is included in the distribution, it will be contained in
$FLUPRO files with names of the form ...mvax.for.
The basic FLUKA program on UNIX machines consists of 29 files (*):
bamjmvax.for blockmvax.for comlatmvax.for decaymvax.for dedxmvax.for
dumvax.for elsmvax.for emfmvax.for eventqmvax.for eventvmvax.for
evffrmvax.for fluoxmvax.for geolatmvax.for kaskadmvax.for lowneumvax.for
mainmvax.for mathmvax.for neutrimvax.for noptmvax.for opphmvax.for
outputmvax.for pemfmvax.for pgmvax.for preclmvax.for preeqmvax.for
pripromvax.for rndmvax.for usermvax.for XXXmvax.for (**)
Two more files contain source code related to the DPMJET and RQMD packages,
which can be linked with FLUKA to run problems involving heavy ion nuclear
interactions:
dpmmvax rqmdmvax
(*) The form ...vax.for has historical reasons. Actually, as seen later, the
files are automatically split by a Makefile into single routines (with
extension .f) before compilation.
(**) XXX stands for hp, ibm, linux, osf etc. depending on the platform.
Most UNIX Fortran compilers require that the extension .for be replaced by
.f (but the Makefile provided with FLUKA takes care of this, see below).
See 4} for a short description of the content of these files.
If the source code is present, the INCLUDE files needed to compile the program
may be grouped into three files emfadd.add, flukaadd.add and lowneuadd.add.
A Makefile and a number of auxiliary programs split these files into individual
routines and INCLUDE files, which are placed in 29+1 separate directories and
compiled. The object files are inserted in a FLUKA library libflukahp.a.
A shell script lfluka links all routines into an executable flukahp (the name
is the same for all UNIX platforms, the "hp" being due to historical reasons).
The DPMJET and RQMD object files are collected in two separate libraries.
The FLUKA distribution tar file normally does not contain an executable file.
To create the default FLUKA executable, type:
$FLUPRO/flutil/lfluka -m fluka
(the name of the resulting executable will be flukahp)
or, if heavy ion nuclear interactions are needed:
$FLUPRO/flutil/ldpmqmd
(the name of the resulting executable will be flukadpm)
User-written routines (in particular a SOURCE subroutine, see list of user
interface routines in 13}) can be compiled separately and linked overriding
the default routines of the library. The $FLUPRO/flutil/lfluka script can
take care of them in three different ways:
a) appending the Fortran files (xxx.f) as last arguments to the
lfluka procedure (Linux only);
b) appending the object files (precompiled using the $FLUPRO/flutil/fff
procedure supplied with the code) as last arguments to the lfluka
procedure;
c) inserting the object files into a library and giving the library
name to the script with the -O or -l options.
An on-line help is available issuing lfluka -h .
The program may need up to 12 auxiliary data files, containing cross-sections,
nuclear and atomic data and so on. Nine of these files are unformatted
and have an extension .bin (or .dat).
The nine unformatted files and three of the remaining auxiliary files require
no modification by the user.
They are generally kept in the main FLUKA directory.
Here is the list:
cohff.bin
Coherent atomic form factors
fluodt.dat
Fluorescence emission data, needed for problems involving
low-energy electron-photon transport
gxsect.bin
Photon cross-sections
neuxsc_72.bin
Low-energy neutron cross-sections: needed for all problems with
neutron transport below 20 MeV.
nuclear.bin
Nuclide masses, abundances and other data: needed for all
hadronic problems
elasct.bin
Elastic cross sections for hadronic problems
sigmapi.bin
Pion cross sections
brems_fin.bin
Bremsstrahlung cross sections
e6r1nds3.fyi, jef2.fyi, jendl3.fyi, xnloan.dat
Fission nuclide yields and neutron multiplicities
1******************************************************************************
4} FLUKA modules (Fortran files)
******************************************************************************
Since several years, the FLUKA source code has been organised in "modules".
This word must not be intended to have the technical meaning which it has
been assigned later in Fortran 90. A FLUKA module is simply a collection of
routines covering the same physics field or belonging to the same class
of functionality.
In the FLUKA2006 version, there are 31 modules:
BAMJM : new hadronisation package (strongly improved version of the
original BAMJET [Rit84])
BLOCKM : block data routines
COMLATM : all geometry routines specific for combinatorial geometry
(CG) and repetition (lattice capability) in the geometry
description
DECAYM : all routines connected with particle decays during transport,
including those managing polarisation or non phase-space-like
decays for pions, kaons, muons and taus
DEDXM : all routines connected with dE/dx and radiative losses of
hadrons and muons, including delta-ray production and cross-
sections for muon photonuclear interactions
DPMM : interface routines for the DPMJET generator
DUM : dummy routines
ELSM : all hadron and photon (photonuclear) cross section routines
EMFM : all routines dealing with electron, positron and photon transport
and interactions (except for photon photonuclear interactions,
fluorescent X-ray and Auger production)
EVENTQM : auxiliary routines for the high energy hadronic interaction
generators
EVENTVM : all routines (besides those in EVENTQM) connected with the high
energy hadronic inelastic interaction package
EVFFRM : separate module with all evaporation, fission and Fermi break-up
routines
FLUOXM : all routines dealing with fluorescence X-ray and Auger production
GEOLATM : geometry navigation and debugging routines
KASKADM : general event steering, most of the relevant transport routines
for hadron and muon transport, including magnetic field tracking,
most of material and region dependent initialisation and source
routines
LOWNEUM : all routines concerning the multigroup treatment of "low" energy
(E < 19.6 MeV) neutrons
MAINM : main, input parsing and auxiliary routines
MATHM : mathematical auxiliary routines (interpolation, integration, etc.)
Many of them adapted from SLATEC (http://www.netlib.org/slatec).
NEUTRIM : nuclear interactions of neutrinos
NOPTM : all routines connected with new scoring options implemented after
FLUKA86, and blank COMMON setting for scoring options.
OPPHM : optical photon production and transport
OUTPUTM : printing routines (apart from output of new options which is
performed in NOPTM)
PEMFM : electromagnetic initialisation
PGM : PLOTGEOM geometry drawing package
PRECLM : full PEANUT second part
PREEQM : full PEANUT first part
PRIPROM : initialisation and drivers for PEANUT
RNDM : random number generation, including gaussian-distributed random
numbers
RQMDM : interface routines for the RQMD generator
USERM : user oriented routines (see list below)
IBMM/HPM/LINUXM/OSFM/VAXM : timing and "environment" routines. These are
machine specific.
User oriented routines (see description in 13}):
The "FLUKA User Routines" mentioned at point 3) in the FLUKA User License are
those (and only those) contained in the directory usermvax, both in the source
and binary versions of the code.
ABSCFF : absorption coefficient (for optical photons)
COMSCW : response functions, user dependent selection for density-like
quantities
DFFCFF : diffusion coefficient (for optical photons)
ENDSCP : energy density distributed - change of positions
FLDSCP : fluence distributed - change of positions
FLUSCW : response functions, user dependent selection for flux-like
quantities
FORMFU : nuclear charge form factors
FRGHNS : material roughness (for optical photons)
FUSRBV : defines a continuous variable for 3-D binnings
LATTIC : symmetry transformation for lattice geometry
LUSRBL : defines a discrete variable for 3-D binnings
MAGFLD : to use a magnetic field map
MDSTCK : management of secondary stack
MGDRAW : to dump trajectories, etc.
MUSRBR : defines a discrete variable for 3-D binnings
OPHBDX : boundary crossing properties (for optical photons)
QUEFFC : quantum efficiency (for optical photons)
RFLCTV : reflectivity (for optical photons)
RFRNDX : refraction index (for optical photons)
SOEVSV : saving source events
SOURCE : to generate any distribution for source particles
STUPRE : set user variables (electrons and photons)
STUPRF : set user variables (hadrons, muons and neutrinos)
UBSSET : to override input biasing parameters
UDCDRL : decay direction biasing
USIMBS : user-defined importance biasing
USREIN : event initialisation
USREOU : post-event output
USRINI : user initialisation
USRMED : to perform user driven biasing and/or particle selections
on a material basis
USROUT : user output
USRRNC : user customisation of residual nuclei scoring
1******************************************************************************
5} Particle and material codes
******************************************************************************
Each particle which can be transported by FLUKA is identified by an integer
number. Negative values of such identifiers are reserved to light and heavy
ions, and to optical photons. The value 0 indicates a pseudoparticle RAY, which
can be used to scan the geometry. Numbers > 200 designate "families" of
particles, grouped according to some common characteristics (all hadrons, or
all charged particles, etc.). In FLUKA, they are called Generalised Particles
and can be used only for scoring. Various forms of scored energy are also
treated as Generalised Particles.
The identifier values are reported in the following Table, together with the
corresponding particle numbering scheme of the Particle Data Group [PDG].
Fluka name Fluka number Common name Standard PDG number
(Particle Data Group)
4-HELIUM (*) -6 Alpha ---
3-HELIUM (*) -5 Helium-3
TRITON (*) -4 Triton ---
DEUTERON (*) -3 Deuteron ---
HEAVYION (*) -2 Generic heavy ion (see command HI-PROPE)
OPTIPHOT -1 Optical Photon ---
RAY (**) 0 Pseudoparticle ---
PROTON 1 Proton 2212
APROTON 2 Antiproton -2212
ELECTRON 3 Electron 11
POSITRON 4 Positron -11
NEUTRIE 5 Electron Neutrino 12
ANEUTRIE 6 Electron Antineutrino -12
PHOTON 7 Photon 22
NEUTRON 8 Neutron 2112
ANEUTRON 9 Antineutron -2112
MUON+ 10 Positive Muon -13
MUON- 11 Negative Muon 13
KAONLONG 12 Kaon-zero long 130
PION+ 13 Positive Pion 211
PION- 14 Negative Pion -211
KAON+ 15 Positive Kaon 321
KAON- 16 Negative Kaon -321
LAMBDA 17 Lambda 3122
ALAMBDA 18 Antilambda -3122
KAONSHRT 19 Kaon zero short 310
SIGMA- 20 Negative Sigma 3112
SIGMA+ 21 Positive Sigma 3222
SIGMAZER 22 Sigma-zero 3212
PIZERO 23 Pion-zero 111
KAONZERO 24 Kaon-zero 311
AKAONZER 25 Antikaon-zero -311
Reserved 26 --- ---
NEUTRIM 27 Muon neutrino 14
ANEUTRIM 28 Muon antineutrino -14
Blank 29 --- ---
Reserved 30 --- ---
ASIGMA- 31 Antisigma-minus -3222
ASIGMAZE 32 Antisigma-zero -3212
ASIGMA+ 33 Antisigma-plus -3112
XSIZERO 34 Xi-zero 3322
AXSIZERO 35 Antixi-zero -3322
XSI- 36 Negative Xi 3312
AXSI+ 37 Positive Xi -3312
OMEGA- 38 Omega-minus 3334
AOMEGA+ 39 Antiomega -3334
Reserved 40 --- ---
TAU+ 41 Positive Tau (***) -15
TAU- 42 Negative Tau (***) 15
NEUTRIT 43 Tau neutrino 16
ANEUTRIT 44 Tau antineutrino -16
D+ 45 D-plus 411
D- 46 D-minus -411
D0 47 D-zero 421
D0BAR 48 AntiD-zero -421
DS+ 49 D_s-plus 431
DS- 50 D_s-minus -431
LAMBDAC+ 51 Lambda_c-plus 4122
XSIC+ 52 Xi_c-plus 4232
XSIC0 53 Xi_c-zero 4112
XSIPC+ 54 Xi'_c-plus 4322
XSIPC0 55 Xi'_c-zero 4312
OMEGAC0 56 Omega_c-zero 4332
ALAMBDC- 57 Antilambda_c-minus -4122
AXSIC- 58 AntiXi_c-minus -4232
AXSIC0 59 AntiXi_c-zero -