[ Identification | Description | Input parameters | Output parameters | Links ]

# The `Monitor_nD` Component

This component is a general Monitor that can output 0/1/2D signals (Intensity or signal vs. [something] and vs. [something] ...)

## Identification

- Author: Emmanuel Farhi
- Origin: ILL
- Date: 14th Feb 2000.
- Version: 1.0.0 (includes MONITOR_ND_LIB_H)
- Modification history:
  - EF, 29th Feb 2000 : added more options, monitor shape, theta, phi
  - EF, 10th Mar 2000 : use struct.
  - EF, 25th May 2000 : correct Vars.Mon2D_Buffer alloc bug.
  - EF, 17th Oct 2000 : spin detector ok. (0.13.4)
  - EF, 19th Jan 2001 : 'auto limits' bug corrected (0.13.5)
  - EF, 01st Feb 2001 : PreMonitor for correlation studies (0.13.6)
  - EF, 02nd Feb 2001 : user variable (0.13.7)
  - EF, 2th Feb 2001 : 3He gas absorption handling (0.13.8)
  - EF, 5th Mar 2001 : intermediate savings (0.13.9)
  - EF, 5th Apr 2001 : use global functions (0.14) compile faster
  - EF, 18th Apr 2001 : passes DETECTOR_OUT to mcdetector_out 0.14.1
  - EF, 23th Jul 2001 : log of signal, init arrays to 0, box (0.15)
  - EF, 04th Sep 2001 : log/abs of variables (0.16)
  - EF, 19th Sep 2001 : correct PROP_ZO and disk bug. McStas 1.6.
  - EF, 28th Sep 2001 : intermediate 'source' option. bug for list ok
  - EF, 24th Oct 2001 : capture flux [p*lambda/1.7985] (0.16.3)
  - EF, 15th Feb 2002 : corrected bug in auto regeneration (0.16.4)
  - EF, 27th Aug 2002 : monitor a variable in place of I (0.16.5)
  - EF, 25th Oct 2002 : banana, and auto for each variable (0.16.5)

## Description

    This component is a general Monitor that can output 0/1/2D signals
    It can produce many 1D signals (one for any variable specified in
    option list), or a single 2D output (two variables correlation).
    Also, an additional 'list' of neutron events can be produced.
    By default, monitor is square (in x/y plane). A disk shape is also possible
    The 'cylinder' and 'banana' option will change that for a banana shape
    The 'sphere' option simulates spherical detector. The 'box' is a box.
    The cylinder, sphere and banana should be centered on the scattering point.
    The monitored flux may be per monitor unit area, and weighted by
    a lambda/lambda(2200m/s) factor to obtain standard capture flux.
    In normal configuration, the Monitor_nD measures the current parameters
    of the neutron that is beeing detected. But a PreMonitor_nD component can
    be used in order to study correlations between a neutron being detected in
    a Monitor_nD place, and given parameters that are monitored elsewhere
    (at PreMonitor_nD).
    The monitor can also act as a 3He gas detector, taking into account the
    detection efficiency.

    The 'bins' and 'limits' modifiers are to be used after each variable,
    and 'auto','log' and 'abs' come before it. (eg: auto abs log hdiv
    limits=[-5 5] bins=10) When placed after all variables,  these two latter
    modifiers apply to the signal (e.g. intensity).

    Possible options are
    Variables to record:
        kx ky kz k wavevector (Angs-1) [    usually axis are
        vx vy vz v            (m/s)         x=horz., y=vert., z=on axis]
        x y z radius          (m)      Distance, Position
        t time                (s)      Time of Flight
        energy omega          (meV)
        lambda wavelength     (Angs)
        p intensity flux      (n/s) or (n/cm^2/s)
        ncounts               (1)
        sx sy sz              (1)      Spin
        vdiv ydiv dy          (deg)    vertical divergence (y)
        hdiv divergence xdiv  (deg)    horizontal divergence (x)
        angle                 (deg)    divergence from <z> direction
        theta longitude       (deg)    longitude (x/z) [for sphere and cylinder]
        phi   lattitude       (deg)    lattitude (y/z) [for sphere and cylinder]

        user user1            will monitor the [Mon_Name]_Vars.UserVariable{1|2}
        user2                 to be assigned in an other component (see below)

    Other options are:
        abs                       Will monitor the abs of the following variable
                                  or of the signal (if used after all variables)
        auto                      Automatically set detector limits for one or all
        all  {limits|bins|auto}   To set all limits or bins values or auto mode
        binary {float|double}     with 'source' option, saves in compact files
        bins=[bins=20]            Number of bins in the detector along dimension
        borders                   To also count off-limits neutrons
                                   (X < min or X > max)
        capture                   weight by lambda/lambda(2200m/s) capture flux
        file=string               Detector image file name. default is component
                                   name, plus date and variable extension.
        incoming                  Monitor incoming beam in non flat (box/sph/cyl) det
        intermediate=[5 in %]     Save ALL results every n% steps in simulation
        limits=[min max]          Lower/Upper limits for axes
                                   (see up for the variable unit)
        list=[counts=1000] or all For a long file of neutron characteristics
                                   with [counts] or all events
        log                       Will monitor the log10 of the following variable
                                  or of the signal (if used after all variables)
        multiple                  For 1D monitors into multiple independant files
        no or not                 Revert next option
        outgoing                  Monitor outgoing beam in non flat det (default)
        parallel                  Use this option when the next component is at
                                   the same position (parallel components)
        per cm2                   Intensity will be per cm^2
        premonitor                Will monitor neutron parameters stored
                                   previously with PreMonitor_nD.
        signal=[var]              Will monitor [var] instead of usual intensity
        slit or absorb            Absorb neutrons that are out detector
        source                    The monitor will save neutron states
        unactivate                To unactivate detector (0D detector)
        verbose                   To display additional informations
        3He_pressure=[3 in bars]  The 3He gas pressure in detector.
                                  3He_pressure=0 means perfect detector (default)

    Detector shape options (specified as xwidth, yheight, zthick or x/y/z/min/max)
        box                       Box of size xwidth, yheight, zthick
        cylinder                  To get a cylindrical monitor
                                   (diameter is xwidth, height is yheight).
        banana                    Same as cylinder, without top/bottom,
                                   on restricted angular area
        disk                      Disk flat xy monitor. radius is xwidth.
        sphrere                   To get a spherical monitor (e.g. a 4PI)
                                   (diameter is xwidth).
        square                    Square flat xy monitor (xwidth, yheight)

    EXAMPLES:
    MyMon = Monitor_nD(
      xwidth = 0.1, yheight = 0.1, zthick = 0,
      options = "intensity per cm2 angle,limits=[-5 5] bins=10,with
                 borders, file = mon1");
                              will monitor neutron angle from [z] axis, between -5
                           and 5 degrees, in 10 bins, into "mon1.A" output 1D file
      options = "sphere theta phi outgoing"   for a sphere PSD detector (out beam)
                                       and saves into file "MyMon_[Date_ID].th_ph"
      options = "angle radius all auto"   is a 2D monitor with automatic limits
      options = "list kx ky kz energy" records each neutron contribution in 1 file
      options = "multiple kx ky kz auto abs log t and list all neutrons"
             makes 4 output 1D files and produces a complete list for all neutrons
             and monitor log(abs(tof)) within automatic limits (for t)

    How to monitor anything in my simulation: with the 'user' option
    1) put in your instrument DECLARE: struct MonitornD_Variables *InstrVars;
    2) put in your instrument INITIALIZE (optionally, to set monitor name):
       InstrVars = &(MC_GETPAR(MyMonitor, Vars));
       strcpy(InstrVars->UserName1,"log xy+1");
    3) put just after the component where you want to monitor (to set the value)
     EXTEND
     %{
       InstrVars = &(MC_GETPAR(MyMonitor, Vars));
       InstrVars->UserVariable1 = log(fabs(x*y+1));
     %}
    4) put further in the instrument (to monitor the user1 value defined before)
     COMPONENT MyMonitor = Monitor_nD(
      xwidth = 0.1, yheight = 0.1,
      options="user1, auto")
     AT ...

    See also the example in PreMonitor_nD to
    monitor neutron parameters cross-correlations.

## Input parameters

Parameters in boldface are required; the others are optional.

Name | Unit | Description | Default
--- | --- | --- | ---
options | str | String that specifies the configuration of the monitor The general syntax is "[x] options..." (see Descr.) | 0
filename |  |  | 0
xwidth | m | Width/diameter of detector (x) | .1
yheight | m | Height of detector (y) | .1
zthick | m | Thichness of detector (z) | 0
xmin | m | Lower x bound of opening | 0
xmax | m | Upper x bound of opening | 0
ymin | m | Lower y bound of opening | 0
ymax | m | Upper y bound of opening | 0
zmin | m | Lower z bound of opening | 0
zmax | m | Upper z bound of opening | 0

## Output parameters

Name | Unit | Description | Default
--- | --- | --- | ---
DEFS | struct | structure containing Monitor_nD Defines |
Vars | struct | structure containing Monitor_nD variables |

## Links

- Source code for `Monitor_nD.comp`.
- McStas at ILL PreMonitor_nD

[ Identification | Description | Input parameters | Output parameters | Links ]