FLUKA: USRBIN
Previous Index Next
USRBIN
scores distribution of one of several quantities in a regular spatial
structure (binning detector) independent from the geometry.
As an extension of the meaning, "region binnings" and "special
user-defined binnings" are also defined, where the term indicates a detector
structure not necessarily regular or independent from the geometry.
See also SCORE (scoring by region), EVENTBIN (event-by-event scoring) and
USRBDX, USRCOLL, USRTRACK, USRYIELD (fluence estimators)
The full definition of the detector may require two successive cards.
The second card, identified by the character '&' in any column from 71 to 78
(or in the last field in case of free format input), must be given unless
the corresponding defaults are acceptable to the user.
First card:
WHAT(1)
: code indicating the type of binning selected. Each type is
characterised by a number of properties:
* structure of the mesh (spatial: R-Z, R-Phi-Z, Cartesian, or
special - by region, or user-defined)
* quantity scored:
- density of energy deposited (total or electromagnetic only)
- dose (total or electromagnetic only)
- star density
- fission density (total, high energy or low energy)
- neutron balance density
- activity
- specific activity
- displacements per atom
- density of non ionising energy losses (restricted or
unrestricted)
- dose equivalent: convoluting fluence with conversion
coefficients or multiplying dose by a LET-dependent quality
factor
- density of momentum transfer
- density of net charge
- fluence (track-length density)
- silicon 1 MeV-neutron equivalent fluence
- high energy hadron equivalent fluence
- thermal neutron equivalent fluence
- density of residual nuclei
- density of positron annihilation at rest
* method used for scoring (old crude algorithm where the energy
lost in a step by a charged particle is deposited in the
middle of the step, or accurate algorithm where the energy lost
is apportioned among different bins according to the
relevant step fraction - see more in Note 14)
* mesh symmetry (no symmetry, or specular symmetry around one
of the coordinate planes, or around the origin point)
0.0 <= WHAT(1)
<= 8.0: Quantities scored at a point. In the case of
various types of energy deposition, quantities calculated using
the old algorithm where the energy lost in a step by a charged
particle is deposited at the step midpoint (see Note 14)
Quantity scored:
- if WHAT(2)
= 208 (ENERGY), 211 (EM-ENRGY), 228 (DOSE), 229
(UNB-ENER), 230 (UNB-EMEN), 238 (NIEL-DEP), 239 (DPA-SCO),
241 (DOSE-EM), 243 (DOSEQLET) or 244 (RES-NIEL): energy or
non ionising energy density or displacements per atom or dose
equivalent calculated with a Quality Factor
- if WHAT(2)
= 219 (FISSIONS), 220 (HE-FISS) or 221 (LE-FISS):
fission density
- if WHAT(2)
= 222 (NEU-BALA), neutron balance density
- if WHAT(2)
= 231 (X-MOMENT), 232 (Y-MOMENT) or 233
(Z-MOMENT): momentum transfer density
- if WHAT(2)
= 234 (ACTIVITY) or 235 (ACTOMASS): activity or
specific activity
- if WHAT(2)
= 242 (NET-CHRG): net charge density
- otherwise, density of stars produced by particles (or
families of particles) with particle code or name = WHAT(2)
Not Allowed in point-wise algorithm (but valid in track-length
apportioning algorithm below):
- WHAT(2)
= 236 (SI1MEVNE), 237 (HADGT20M), 240 (DOSE-EQ),
249 (HEHAD-EQ), 250 (THNEU-EQ)
Default
: 208 (ENERGY).
0.0 : Mesh: Cartesian, no symmetry
1.0 : Mesh: R-Z or R-Phi-Z, no symmetry. Phi is the azimuthal angle
around the Z axis, measured from -pi to +pi relative to the X
axis.
2.0 : Mesh: by region (1 bin corresponds to n regions, with
n = 1 to 3)
3.0 : Mesh: Cartesian, with symmetry +/- X (i.e. |x| is used for
scoring)
4.0 : Mesh: Cartesian, with symmetry +/- Y (i.e. |y| is used for
scoring).
5.0 : Mesh: Cartesian, with symmetry +/- Z (i.e. |z| is used for
scoring).
6.0 : Mesh: Cartesian, with symmetry around the origin (i.e. |x|, |y|
and |z| are used for scoring)
7.0 : Mesh: R-Z or R-Phi-Z, with symmetry +/- Z (i.e.|z| is used for
scoring)
8.0 : Special user-defined 3D binning. Two variables are
discontinuous (e.g. region number), the third one is
continuous, e.g. a user-defined function of the space
coordinates or of some energy or angular quantity. See 13.2.9}.
Variable # Type Default
Override routine
1st integer region number MUSRBR
2nd integer lattice cell number LUSRBL
3rd continuous 0.0 FUSRBV
10.0 <= WHAT(1)
<= 18.0: Quantities scored along a step, apportioned
among different bins according to the relevant step fraction.
In particular, in the case of various types of energy
deposition, quantities calculated using the accurate
apportioning algorithm (see Note 14)
Quantity scored:
- if WHAT(2)
= 208 (ENERGY), 211 (EM-ENRGY), 228 (DOSE), 229
(UNB-ENER), 230 (UNB-EMEN), 238 (NIEL-DEP), 239 (DPA-SCO),
241 (DOSE-EM), 243 (DOSEQLET) or 244 (RES-NIEL): energy or
non ionising energy density (as such or weighted with a
Quality Factor) or displacements per atom
- if WHAT(2)
= 236 (SI1MEVNE): fluence weighted by a damage
function
- if WHAT(2)
= 240 (DOSE-EQ): Dose equivalent, calculated by
folding fluence with conversion coefficients
- if WHAT(2)
= 249 (HEHAD-EQ) or 250 (THNEU-EQ): high energy
hadron equivalent or thermal neutron equivalent fluence
- otherwise, fluence (track-length density) of particles (or
families of particles) with particle code or name = WHAT(2)
Not Allowed in track-length apportioning algorithm (but valid
in point-wise algorithm above):
- WHAT(2)
= 219 (FISSIONS), 220 (HE-FISS), 221 (LE-FISS),
222 (NEU-BALA), 231 (X-MOMENT), 232 (Y-MOMENT),
233 (Z-MOMENT), 234 (ACTIVITY), 235 (ACTOMASS),
242 (NET-CHRG)
10.0 : Mesh: Cartesian, no symmetry
11.0 : Mesh: R-Z or R-Phi-Z, no symmetry
12.0 : Mesh: by region (1 bin corresponds to n regions,
with n = 1 to 3)
13.0 : Mesh: Cartesian, with symmetry +/- X (|x| used for scoring)
14.0 : Mesh: Cartesian, with symmetry +/- Y (|y| used for scoring)
15.0 : Mesh: Cartesian, with symmetry +/- Z (|z| used for scoring)
16.0 : Mesh: Cartesian, with symmetry around the origin (|x|,|y|,
|z| used for scoring)
17.0 : Mesh: R-Z or R-Phi-Z, with symmetry +/- Z (|z| used for
scoring)
18.0 : Special user-defined 3D binning. Two variables are
discontinuous (e.g. region number), the third one is
continuous, e.g. a user-defined function of the space
coordinates or of some energy, time or angular quantity.
See 13}
Variable # Type Default
Override routine
1st integer region number MUSRBR
2nd integer lattice cell number LUSRBL
3rd continuous default = 0.0 FUSRBV
Default
= 0.0 (Cartesian scoring without symmetry, star density or
energy density deposited at midstep with the old algorithm)
WHAT(2)
: particle (or particle family) type to be scored
If WHAT(2)
= 208 (ENERGY), 211 (EM-ENRGY), 228 (DOSE), 229
(UNB-ENER), 230 (UNB-EMEN), 238 (NIEL-DEP), 239 (DPA-SCO),
241 (DOSE-EM), 243 (DOSEQLET) or 244 (RES-NIEL):
If WHAT(1)
< 10, the binning will score with the old crude
algorithm energy or non ionising energy deposition (as such or
weighted with a damage function or a Quality Factor), or
displacements per atom.
If WHAT(1)
>= 10, the apportioning algorithm will be used
(more accurate, see Note 14).
If WHAT(2)
= 219 (FISSIONS), 220 (HE-FISS) or 221 (LE-FISS), and
WHAT(1)
< 10, the binning will score fission density.
WHAT(1)
>= 10 is not allowed.
If WHAT(2)
= 222 and WHAT(1)
< 10, neutron balance density will
be scored.
WHAT(1)
>= 10 is not allowed.
If WHAT(2)
= 231 (X-MOMENT), 232 (Y-MOMENT) or 233 (Z-MOMENT),
and WHAT(1)
< 10, the binning will score density of momentum
transfer.
WHAT(1)
>= 10 is not allowed.
If WHAT(2)
= 234 (ACTIVITY) or 235 (ACTOMASS), and WHAT(1)
< 10,
the binning will score activity or specific activity.
WHAT(1)
>= 10 is not allowed.
If WHAT(2)
= 240 (DOSE-EQ) and WHAT(1)
>= 10, the binning will
score dose equivalent calculated as convolution of particle
fluences and conversion coefficients (see option AUXSCORE).
WHAT(1)
< 10 is not allowed.
If WHAT(2)
= 242 (NET-CHRG), the binning will score density of
net charge deposition.
WHAT(1)
>= 10 is not allowed.
If WHAT(2)
= 249 (HEHAD-EQ) and WHAT(1)
>= 10, the binning will
score high energy hadron equivalent fluence.
WHAT(1)
< 10 is not allowed.
If WHAT(2)
= 250 (THNEU-EQ) and WHAT(1)
>= 10, the binning will
score thermal neutron equivalent fluence.
WHAT(1)
< 10 is not allowed.
Any other particle (or family of particles) requested will score:
a) if WHAT(1)
< 10, density of stars produced by particles or
family of particles with particle code or name = WHAT(2)
.
Of course, this choice is meaningful only for particles that
can produce stars (hadrons, photons and muons).
b) if WHAT(1)
>= 10, fluence of particles (or family of
particles) with particle code (or name) = WHAT(2)
.
Note that it is not possible to score energy fluence with this
option alone (it is possible, however, by writing a special
version of the user routine FLUSCW - see 13})
Default
: 208.0 (total energy density)
WHAT(3)
= logical output unit:
> 0.0 : formatted data are written on WHAT(3)
unit
< 0.0 : unformatted data are written on |WHAT(3)
| unit
Values of |WHAT(3)
| < 21 should be avoided (with the exception
of +11).
Default
: WHAT(3)
= 11.0 (standard output unit)
WHAT(4)
= For Cartesian binning: Xmax
For R-Z and R-Phi-Z binning: Rmax
For region binning: last region of the first region set
For special binnings, upper limit of the first user-defined
variable (last region if the default version of the MUSRBR
routine is not overridden)
No default (the user has to define a not null interval)
WHAT(5)
= For Cartesian binning: Ymax
For R-Z and R-Phi-Z binning: Y coordinate of the binning axis
For region binning: last region of the second region set
For special binnings, upper limit of the second user-defined
variable (last lattice cell if the default version of the LUSRBL
routine is not overridden)
Default
: 0.0 for R-Z, R-Phi-Z and region binning
No default otherwise (the user has to define a not null interval)
WHAT(6)
= For R-Z, R-Phi-Z and Cartesian binnings: Zmax
For region binnings, last region of the 3rd region set
For special binnings, upper limit of the 3rd user-defined
variable (0.0 if the default version of the FUSRBV routine is
not overridden)
Default
: 0.0 for region binning
No default otherwise (the user has to define a not null interval)
SDUM
= any character string (not containing '&') identifying the
binning detector (max. 10 characters)
Continuation card: (not needed if the defaults are acceptable)
WHAT(1)
= For Cartesian binning: Xmin (if X symmetry is requested, Xmin
cannot be negative)
For R-Z and R-Phi-Z binning: Rmin
For region binnings, first region of the first region set
Default
: equal to last region (= WHAT(4)
in the first USRBIN
card)
For special binnings, lower limit of the first user-defined
variable (first region if the default version of the MUSRBR
routine is not overridden)
Default
: 0.0
WHAT(2)
= For Cartesian binning: Ymin (if Y symmetry is requested, Ymin
cannot be negative)
For R-Z and R-Phi-Z binning: X coordinate of the binning axis
For region binnings, first region of the second region set
Default
: equal to last region (= WHAT(5)
in the first USRBIN
card)
For special binnings, lower limit of the second
user-defined variable (first lattice cell if the default version
of the LUSRBL routine is not overridden)
Default
: 0.0
WHAT(3)
= For Cartesian, R-Z and R-Phi-Z binnings: Zmin (if Z
symmetry is requested, Zmin cannot be negative)
For region binnings, first region of the third region set
Default
: equal to last region (= WHAT(6)
in the first USRBIN
card)
For special binnings, lower limit of the 3rd user-defined
variable (0.0 if the default version of the FUSRBV routine is not
overridden)
Default
: 0.0
WHAT(4)
= For Cartesian binning: number of X bins (default: 30.0)
For R-Z and R-Phi-Z binning: number of R bins (default: 50.0)
For region binnings, step increment for going from the first to
the last region of the first region set
(Default
: 1)
For special binnings, step increment for going from the first to
the last "region" (or similar)
(Default
: 1)
WHAT(5)
= For Cartesian binning: number of Y bins (default: 30.0)
For R-Phi-Z: number of Phi bins (default is R-Z: 1 Phi bin)
For region binnings, step increment for going from the first to
the last region of the second region set
(Default
: 1)
For special binnings, step increment for going from the first to
the last "lattice cell" (or similar)
(Default
: 1)
WHAT(6)
= For Cartesian, R-Z and R-Phi-Z binnings: number of Z bins
Default
: 10.0 for Cartesian, 50.0 for R-Z and R-Phi-Z
For region binnings, step increment for going from the first to
the last region of the third region set
(Default
: 1)
For special binnings, number of intervals for the third variable
(Default
: 1)
SDUM
= & in any position in column 71 to 78
Default
(option USRBIN not given): no binning detector
Notes:
1) A "binning" is a regular spatial mesh completely independent
from the regions defined by the problem's geometry. As an extension
of the meaning, "region binnings" and "special user-defined
binnings" are also defined, where the term indicates a detector
structure not necessarily regular or independent from the geometry.
On user's request, FLUKA can calculate the distribution of several
different quantities over one or more binning structures, separated
or even overlapping.
The following quantities can be "binned":
- energy density, total or deposited by electrons, positrons
and gamma only
- dose (energy per unit mass), total or deposited by electrons,
positrons and gamma only
- star density (density of hadronic inelastic interactions)
- particle track-length density (fluence)
- dose equivalent (fluence convoluted with fluence-to-dose
equivalent conversion coefficients, or dose multiplied by a
LET-dependent Quality Factor)
- activity (per unit volume) or specific activity (per unit mass)
- density of total, high-energy and low-energy fissions
- density of neutron balance (algebraic sum of outgoing neutrons
minus incoming neutrons for all interactions)
- density of unbiased energy (physically meaningless but useful for
setting biasing parameters and debugging)
- density of momentum transfer components on the three axes
- DPA (Displacements Per Atom)
- density of Non Ionising Energy Losses deposited, unrestricted and
restricted (i.e. larger than the DPA threshold)
- silicon 1 MeV neutron-equivalent fluence
- high energy hadron equivalent fluence (see Note (8) of Chap. 5)
- thermal neutron equivalent fluence (see Note (9) of Chap. 5)
- density of net charge deposited
The available binning shapes are Cartesian (3-D rectangular, with
planes perpendicular to the coordinate axes), R-Z (2-D cylindrical,
with the cylinder axis parallel to the z-axis), and R-Phi-Z (3-D
cylindrical).
2) It is possible to define also binnings with an arbitrary orientation
in space, by means of options ROT-DEFIni and ROTPRBIN.
3) A star is a hadronic inelastic interaction at an energy higher than
a threshold defined via the option THRESHOLd (or by default higher
than the transport threshold of the interacting particle). Star
scoring (traditionally used in most high-energy shielding codes) can
therefore be considered as a form of crude collision estimator:
multiplication of star density by the asymptotic value of the
inelastic nuclear interaction length gives the fluence of hadrons
having energy higher than the current threshold. However, this is
meaningful only if the interaction length doesn't vary appreciably
with energy; therefore it is recommended to set a scoring
threshold = 50 MeV (using option THRESHOLd), since interaction
lengths are practically constant above this energy. Besides, star
densities calculated with a 50 MeV threshold are the basis of some
old techniques to estimate induced activity such as the
omega-factors [Tho88, p.106], and the prediction of single isotope
yields from the ratio of partial to inelastic cross section). These
techniques have now been made obsolete by the capability of FLUKA to
calculate directly induced activity and residual nuclei.
4) Selecting star scoring is meaningful for hadrons, photons and
muons (if their energy is sufficiently high). Any other particle
will not produce any star. And in FLUKA, stars do not include
spallations due to annihilating particles.
The results will be expressed in stars per cm3 per unit primary
weight.
5) Energy deposition will be expressed in GeV per cm3 per unit primary
weight. Doses will be expressed in GeV/g per unit primary weight. To
obtain dose in Gy, multiply GeV/g by 1.602176462E-7
6) Non Ionising Energy Losses deposited (NIEL-DEP), restricted and
unrestricted, will be expressed in GeV per cm3 per unit primary
weight.
7) Displacements Per Atom (DPA) will be expressed as average DPAs in
each bin per unit primary weight.
8) Fluence will be expressed in particles/cm2 per unit primary weight.
9) Dose equivalent will be expressed in pSv per unit primary weight.
10) Activity will be expressed in Bq/cm3 per unit primary weight.
Specific activity will be expressed in Bq/g per unit primary weight.
Scoring activity requires additional commands RADDECAY, IRRPROFI,
DCYTIMES and DCYSCORE.
11) Total, High-energy and Low-energy fissions will be expressed as
fissions/cm3 per unit primary weight.
12) Neutron balance density will be expressed as net number of produced
neutrons per cm3 per unit primary weight.
13) The results from USRBIN are normalised per unit volume and per unit
primary weight, except region binnings and special user-defined
binnings, which are normalised per unit primary weight only, for
DPA, which are given as number of displacements per atom per unit
primary weight, averaged over the bin volume, and for dose
equivalent, expressed as pSv per unit primary weight.
In case symmetries are requested, proper rescaled volumes are taken
into account for normalisation (that is, an extra factor 2 is
applied to the volume if symmetry around one plane is required, 8 if
the symmetry is around the origin)
14) When scoring energy deposition or dose, i.e. generalised particles
208 (ENERGY), 211 (EM-ENRGY), 228 (DOSE) or 241 (DOSE-EM), it is
recommended to set in the first USRBIN card WHAT(1)
= 10.0, 11.0,
..., 18 (rather than 0.0, 1.0, ..., 8.0).
The difference between the two settings is the following.
With WHAT(1)
= 0.0, 1.0, ..., 8.0, the energy lost in a charged
particle step is deposited in the bin corresponding to the midpoint
of the step: this is the old FLUKA algorithm, which is rather
inefficient when the step length is larger than the bin size.
The accurate algorithm, selected by setting WHAT(1)
= 10.0, 11.0,
...., 18, deposits in every bin traversed by the step a fraction of
energy proportional to the respective chord (track-length
apportioning). Statistical convergence is much faster.
15) When scoring region binning and more than one set of regions is
defined, each of the sets (2 or 3) must have the same number of
regions. The first bin will contain the sum of what is contained
in the first regions of each set, the second bin the sum of
the scores of the second regions, etc.
16) The maximum number of binnings that the user can define is
400.
17) The logical output unit for the estimator results (WHAT(3)
of
the first USRBIN card) can be any one of the following:
- the standard output unit 11: estimator results (that in this
case need to be formatted) will be written on the same file as
the standard FLUKA output
- a pre-connected unit (via a symbolic link on most UNIX systems,
ASSIGN under VMS, or equivalent commands on other systems)
- a file opened with the FLUKA command OPEN
- a file opened with a Fortran OPEN statement in a user-written
initialisation routine such as USRINI, USRGLO or SOURCE (see 13}).
- a dynamically opened file, with a default name assigned by the
Fortran compiler (typically fort.xx or ftn.xx, with xx equal
to the chosen logical output unit number).
18) The results of several USRBIN detectors in a same FLUKA run can be
written on the same file, but of course only if they are all in the
same mode (all formatted, or all unformatted).
19) It is also possible in principle to write on the same file the
results of different kinds of estimators (USRBDX, USRTRACK, etc.)
but this is not recommended, especially in the case of an
unformatted file, because it would make very difficult any reading
and analysis.
20) In R-Phi-Z binnings, the azimuthal angle Phi extends from -pi to +pi
(-180 to +180 degrees), where Phi = 0 corresponds to the positive
x-axis. Note that it is not possible to further restrict the domain
of Phi.
21) Binning data can be obtained also separately for each "event"
("event" = history of a primary particle and all its descendants).
See option EVENTBIN for details.
22) Two programs, USBSUW and USBREA, are available with the normal FLUKA
code distribution in directory $FLUPRO/flutil. USBSUW allows to
compute standard deviations over several runs, and returns the
standard deviations and the averages in an unformatted file. USBREA
reads an unformatted file and returns the equivalent formatted file,
including the standard deviations if the input file was produced
by USBSUW.
Example:
USRBIN 10.0 ELECTRON -25.0 7.0 7.0 12.1 verythin
USRBIN -7.0 -7.0 12.0 35.0 35.0 1.0 &
Previous Index Next
