[ <--- prev -- ]  [ HOME ]  [ -- next ---> ]

[ full index ]

USRBIN

scores distribution of one of several quantities in a regular spatial structure (binning detector) 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: 
                 - energy deposited (total or electromagnetic only), dose
                 - stars, fissions (total, high energy or low energy)
                 - neutron balance
                 - activity, specific activity
                 - displacements per atom, non ionising energy losses 
                   (restricted or unrestricted)
                 - dose equivalent: convoluting fluence with conversion
                   coefficients (total or electromagnetic only) or multiplying
                   dose by a LET-dependent quality factor
                 - momentum transfer
                 - net charge
                 - fluence (track-length density), silicon 1 MeV-equivalent
                   neutron flux
               * method used for scoring (old algorithm where the energy
                 lost in a step by a charged particle is deposited in the
                 middle of the step, or new 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 : Mesh: Cartesian, no symmetry
                 Quantity scored:
                 - if WHAT(2) = 208 (ENERGY), 211 (EM-ENRGY), 228 (DOSE), 229
                   (UNB-ENER), 230 (UNB-EMEN), 239 (DPA-SCO), 238 (NIEL-DEP),
                   243 (DOSEQLET) or 244 (RES-NIEL): energy or non ionising
                   energy density or displacements per atom or dose equivalent
                   calculated with a Quality Factor (deposited with the old
                   algorithm at midstep, see Note 14)
                 - 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
                 - WHAT(2)  = 240 (DOSE-EQ), 241 (DOSE-EM): not allowed
                 - otherwise, density of stars produced by particles (or
                   families of particles) with particle code or name = WHAT(2)
           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.
                 Quantity scored: same as for WHAT(1) = 0.0
           2.0 : Mesh: by region (1 bin corresponds to n regions, with n = 1 to 3)
                 Quantity scored: same as for WHAT(1) = 0.0
           3.0 : Mesh: Cartesian, with symmetry +/- X (i.e. |x| is used for
                 scoring)
                 Quantity scored: same as for WHAT(1) = 0.0
           4.0 : Mesh: Cartesian, with symmetry +/- Y (i.e. |y| is used for
                 scoring).
                 Quantity scored: same as for WHAT(1) = 0.0
           5.0 : Mesh: Cartesian, with symmetry +/- Z (i.e. |z| is used for
                 scoring).
                 Quantity scored: same as for WHAT(1) = 0.0
           6.0 : Mesh: Cartesian, with symmetry around the origin (i.e.
                 |x|, |y| and |z| are used for scoring)
                 Quantity scored: same as for WHAT(1) = 0.0
           7.0 : Mesh: R-Z or R-Phi-Z, with symmetry +/- Z (i.e. |z| is used for
                 scoring)
                 Quantity scored: same as for WHAT(1) = 0.0
           8.0 : Special user-defined 3D binning. Two variables are discontinuous
                 (e.g. region number), the third one is continuous, but not
                 necessarily a space coordinate. See (13) for instructions on how
                 to write, compile and link the user routines.
                Variable #     Type        Default            Override routine
                        1st    integer     region number         MUSRBR
                        2nd    integer     lattice cell number   LUSRBL
                        3rd    continuous  pseudo-rapidity       FUSRBV
          10.0 : Mesh: Cartesian, no symmetry
                 Quantity scored: if WHAT(2) = 208 (ENERGY), 211 (EM-ENRGY),
                    228 (DOSE), 229 (UNB-ENER), 230 (UNB-EMEN), 239 (DPA-SCO),
                    238 (NIEL-DEP) or 244 (RES-NIEL): energy or non ionising
                    energy density or displacements per atom (apportioned with
                    the new algorithm along the step, as explained in Note 14).
                    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): not allowed.
                    WHAT(2) = 240 (DOSE-EQ): Dose equivalent.
                    Otherwise, fluence (tracklength density) of particles (or
                    families of particles) with particle code or name = WHAT(2)
          11.0 : Mesh: R-Z or R-Phi-Z, no symmetry
                 Quantity scored: same as for WHAT(1) = 10.0
          12.0 : Mesh: by region (1 bin corresponds to n regions, with n = 1 to 3)
                 Quantity scored: same as for WHAT(1) = 10.0
          13.0 : Mesh: Cartesian, with symmetry +/- X (|x| used for scoring)
                 Quantity scored: same as for WHAT(1) = 10.0
          14.0 : Mesh: Cartesian, with symmetry +/- Y (|y| used for scoring)
                 Quantity scored: same as for WHAT(1) = 10.0
          15.0 : Mesh: Cartesian, with symmetry +/- Z (|z| used for scoring)
                 Quantity scored: same as for WHAT(1) = 10.0
          16.0 : Mesh: Cartesian, with symmetry around the origin (|x|,|y|,
                 |z| used for scoring)
                 Quantity scored: same as for WHAT(1) = 10.0
          17.0 : Mesh: R-Z or R-Phi-Z, with symmetry +/- Z (|z| used for scoring)
                 Quantity scored: same as for WHAT(1) = 10.0

          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) or 230 (UNB-EMEN):
                 If WHAT(1) < 10, the binning will score energy deposition with
                  the old algorithm.
                 If WHAT(1) >= 10,  the new deposition 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) = 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 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.
               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(1)| < 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

     WHAT(5) = For Cartesian binning: Ymax
               For R-Z binning: Y coordinate of the binning axis
               (in R-Phi-Z binnings, the Y coordinate must be zero).
               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)
               No default

     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 (eta_max if the default
               version of the FUSRBV routine is not overridden)
               No default

     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 binning: X coordinate of the binning axis
               (in R-Phi-Z binnings, the X coordinate must be zero).
               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 (eta_min 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 ("eta", or similar)
                                                        (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. 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 (hadronic inelastic interactions)
  
• particle tracklength density (fluence)
  
• dose equivalent (fluence convoluted with fluence-to-dose equivalent conversion coefficients)
  
• activity (per unit volume) or specific activity (per unit mass)
  
• density of total, high-energy and low-energy fissions
• neutron balance density (algebraic sum of outgoing neutrons minus incoming neutrons for all interactions)
  
• unbiased energy density (physically meaningless but useful for setting biasing parameters and debugging)
  
• DPA (Displacements Per Atom)
  
• NIEL (Non Ionising Energy Losses), unrestricted and restricted (i.e. larger than the DPA threshold)

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 (NIEL), 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.

• 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 unit primary weight.

• 13) The results from USRBIN are normalised per unit volume and per unit primary weight, except for 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, i.e. generalised particles 208 (ENERGY) and 211 (EM-ENRGY), it is recommended to set in the first USRBIN card WHAT(1) = 10.0, 11.0, ...., 17 (rather than 0.0, 1.0, ..., 7.0). The difference between the two settings is the following. With WHAT(1) = 0.0, 1.0, ..., 7.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 new algorithm, selected by setting WHAT(1) = 10.0, 11.0, ...., 17, 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. This value can be changed by modifying the parameter MXUSBN in member USRBIN of the flukapro library or directory and then re-compiling and linking FLUKA.

• 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 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 Phi coordinates extend from -pi to +pi (-180 to +180 degrees). Phi = 0 corresponds to the x-axis.

• 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:

 *...+....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 tracklength 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