USRBIN¶

Summary

Scores distributions 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
- 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)

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:

WHAT(2) = 236 (SI1MEVNE), 237 (HADGT20M), 240 (DOSE–EQ), 249 (HEHAD–EQ), 250 (THNEU–EQ)

= 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 $\pm$ X (i.e. |x| is used for scoring)

= 4.0:

Mesh: Cartesian, with symmetry $\pm$ Y (i.e. |y| is used for scoring)

= 5.0:

Mesh: Cartesian, with symmetry $\pm$ 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 $\pm$ Z (i.e. |z| is used for scoring)

= 8.0:

Special user-defined 3-D 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 MUSRBR, LUSRBL, FUSRBV: user-defined quantities for special binning.

Variable	Type	Default	Override routine
1$^\text{st}$	integer	region number	`MUSRBR`
2$^\text{nd}$	integer	lattice cell number	`LUSRBL`
3$^\text{rd}$	continuous	0.0	`FUSRBV`

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:

WHAT(2) = 219.0 (FISSIONS), 220.0 (HE–FISS), 221.0 (LE–FISS), 222.0 (NEU–BALA), 231.0 (X–MOMENT), 232.0 (Y–MOMENT), 233.0 (Z–MOMENT), 234.0 (ACTIVITY), 235.0 (ACTOMASS), 242.0 (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 $\pm$ X (|x| used for scoring)

= 14.0:

Mesh: Cartesian, with symmetry $\pm$ Y (|y| used for scoring)

= 15.0:

Mesh: Cartesian, with symmetry $\pm$ 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 $\pm$ Z (|z| used for scoring)

= 18.0:

Special user-defined 3-D binning. Two variables are discrete (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 MUSRBR, LUSRBL, FUSRBV: user-defined quantities for special binning.

Variable	Type	Default	Override routine
1$^{st}$	integer	region number	`MUSRBR`
2$^{nd}$	integer	lattice cell number	`LUSRBL`
3$^{rd}$	continuous	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.0, the binning will score with the old algorithm energy density or non ionising energy density (as such or weighted with a damage function or a Quality Factor), or displacements per atom.
- If WHAT(1) ≥ 10.0, 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.0 (Y–MOMENT) or 233.0 (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.0 (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:
- If WHAT(1) < 10.0, 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).
- If WHAT(1) ≥ 10.0, 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 FLUSCW: weighting fluence, current and yield)

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.0 should be avoided (with the exception of +11).

Default

= 11.0 (standard output unit)

WHAT(4) =

For Cartesian binning: X\(_{max}\)
For R–Z and R–\(\Phi\)–Z binning: R\(_{max}\)
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)​

Default

: No default

WHAT(5) =

For Cartesian binning: Y\(_{max}\)
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 binnings.

No default otherwise (the user has to define a not null interval)

WHAT(6) =

For R–Z, R–\(\Phi\)–Z and Cartesian binnings: Z\(_{max}\)
For region binnings, last region of the third region set
For special binnings, upper limit of the third 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: X$_{min}$ (if X symmetry is requested, X$_{min}$ cannot be negative)

For R–Z and R–$\Phi$–Z binning: R$_{min}$

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: Y$_{min}$ (if Y symmetry is requested, Y$_{min}$ 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: Z$_{min}$ (if Z symmetry is requested, Z$_{min}$ 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 third 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.0)

For special binnings, step increment for going from the first to the last “region” (or similar).    (Default: 1.0)
WHAT(5) =: For Cartesian binning: number of Y bins.    (Default: 30.0).

For R–$\Phi$–Z: number of $\Phi$ bins.    (Default is R–$\Phi$–Z = R–Z, i.e. 1 $\Phi$ bin).

For region binnings, step increment for going from the first to the last region of the second region set.    (Default: 1.0).

For special binnings, step increment for going from the first to the last “lattice cell” (or similar).    (Default: 1.0).
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.0).

For special binnings, number of intervals for the third variable. (Default: 1.0).
SDUM: = “ & ” in any position in column 71 to 78 (or in the last field if free format is used)
Default: (option USRBIN not given): no binning detector

Notes

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 $e^+$$e^-$$\gamma$ only
- dose (energy per unit mass), total or deposited by $e^+$$e^-$$\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 5.1)
- thermal neutron equivalent fluence (see Note 5.1)
- 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).
It is possible to define also binnings with an arbitrary orientation in space, by means of options ROT–DEFIni and ROTPRBIN.
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 (see [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.
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 cm$^3$ per unit primary weight.
Energy deposition will be expressed in GeV per cm$^3$ 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.602176462 \times 10^{-7}$
Non Ionising Energy Losses deposited (NIEL–DEP), restricted and unrestricted, will be expressed in GeV per cm$^3$3 per unit primary weight.
Displacements Per Atom (DPA) will be expressed as average DPAs in each bin per unit primary weight.
Fluence will be expressed in particles/cm$^2$ per unit primary weight.
Dose equivalent will be expressed in pSv per unit primary weight.
Activity will be expressed in Bq/cm$^3$ 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.
Total, High-energy and Low-energy fissions will be expressed as fissions/cm$^3$ per unit primary weight.
Neutron balance density will be expressed as net number of produced neutrons per cm$^3$3 per unit primary weight.
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).
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.0 (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.0, 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.
When scoring region binning and more than one set of regions is defined, each of the sets (2 or 3) must consist of 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.
The maximum number of binnings that the user can define is 400.
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 USRINI: USeR INItialisation, USRGLO: USeR GLObal settings, SOURCE: user-written source)
- 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).
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).
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.
In R–$\Phi$–Z binnings, the azimuthal angle $\Phi$ extends from $-\pi$ to $+\pi$ ($-180^\circ$ to $+180^\circ$), where $\Phi = 0$ corresponds to the positive $x$-axis. Note that it is not possible to further restrict the domain of $\Phi$.
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.
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.

A program USBAPP is also available in directory $FLUPRO/flutil. USBAPP reads several USRBIN unformatted files and concatenates their binnings into one output file: each binning of each input file becomes an additional, sequentially-renumbered entry in the output, with the per-cell content copied verbatim. The statistics record of the output is written only if every contributing input carried one. USBAPP performs no statistical combination: input cells are not summed but juxtaposed.

A program USBWEI is also available in directory $FLUPRO/flutil. USBWEI reads a list of USRBIN unformatted files and a user-supplied weight for each, then produces a weighted mean or weighted sum. For each cell, the merged value is Y(j) = (1 / W) * Sum_i w_i * X_i(j), where W is either the sum of the input weights or 1.0. The per-cell statistical uncertainty is obtained by standard error propagation from inputs carrying per-cell statistics; the relative error is capped at 0.99. Cells without statistics receive a sentinel relative error of 100 percent. The input files must share the same binning definitions.

Example:

*...+....1....+....2....+....3....+....4....+....5....+....6....+....7...+...8
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 &
*  Cartesian binning of electron track-length density, to be written
*  unformatted on unit 25. Mesh is 35 bins between x = -7 and x = 7, 35 bins
*  between y = -7 and y = 7, and 1 bin between z = 12 and z = 12.1