CERN homepage INFN homepage
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 * 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: -
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 +/- 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: -
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 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

Previous Index Next