7.19} Calls to user routines

 ----------------------------
 The purpose of several FLUKA input options is to trigger calls to user routines
 (user routines are described in Chap. 13}). One of the most important ones is
 SOURCE, which makes FLUKA get the characteristics of its primary particles from
 subroutine SOURCE instead of from options BEAM and BEAMPOS. This option allows
 to pass to the subroutine several parameters, thus allowing to drive it from
 input without the need to re-compile it. Note that even when using a
 user-written source, it is still necessary to have in input a BEAM card
 indicating the maximum expected energy of a primary particle, so that the
 program can prepare appropriate cross section tables. If command SOURCE is
 present, but no SOURCE routine has been linked, the default one in the FLUKA
 library will be called, which leaves unchanged the particle type, energy,
 position etc. as defined by BEAM and BEAMPOS.

 Command USERWEIG can call 5 different user routines used to modify a scored
 quantity (at the time of scoring). The routines are:

    * FLUSCW is a function returning a multiplication factor for fluences.
      A typical application is to convert a fluence to dose equivalent.
    * COMSCW is a function returning a multiplication factor for star densities
      and doses. Common application: converting energy deposition to dose.
    * USRRNC is a subroutine providing a convenient user hook for scoring
      residual nuclei.
    * ENDSCP is a subroutine performing a displacement of the energy deposited
      in a particle step, for instance to account for an instrument drift.
    * FLDSCP is a subroutine performing a displacement (drift) of the track
      corresponding to a particle step.

 Complex magnetic fields can be defined or read from a map by a user routine
 MAGFLD. Calls to the routine are activated by command MGNFIELD.

 A collision file (also called a collision tape, or a phase space file) is a
 file on which FLUKA writes on request details of user-selected events:
 particle trajectories, energy deposition events, source particles, boundary
 crossings, physical interactions, etc. This task is performed by subroutine
 MGDRAW, which is called if option USERDUMP is requested in input. The default
 routine present in the FLUKA library can be driven as it is, without
 re-compilation, by setting some of the USERDUMP parameters, but can also be
 modified and re-compiled to adjust to specific needs of the user. A typical
 simple task is to draw particles trajectories. Another frequent application of
 USERDUMP is to perform a calculation in two steps, where the second step uses
 the collision file as a source. In principle it is also possible to use
 subroutine MGDRAW for scoring, for instance by interfacing it to some
 histogramming package, as it is customary in some other Monte Carlo programs.
 However, in general this is discouraged in FLUKA, unless the desired quantity
 cannot be scored via the standard FLUKA input commands, which is very rare. The
 FLUKA scoring options are indeed highly optimised and well checked against
 possible errors and artefacts. It is very unlikely that a user might be able to
 achieve in a short time the same level of reliability. In any case,
 user-written scoring via MGDRAW MUST be avoided in all runs where biasing is
 present, because to handle correctly the particle weights requires other FLUKA
 tools which are not available to the normal user.

 Three more input options activating calls to user routines are USRICALL,
 USROCALL and USRGCALL. The first two allow the user to issue a call respectively
 to an initialisation routine USRINI and to an output routine USROUT. The third
 one activates a call to a routine USRGLO, which performs a global initialisation
 before any other made by FLUKA.

Previous Index Next