10.8  The Monitor_nD McStas Component

Release: McStas 1.6 Version: $Revision$

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

Identification

• Author: <a href="mailto:farhi@ill.fr">Emmanuel Farhi</a>

• Origin: <a href="http://www.ill.fr">ILL</a>

• Date: 14th Feb 2000.

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 integrated capture flux. In normal configuration, the Monitor_nD measures the current parameters of the neutron that is beeing detected. USERVARS may 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 the point of initialisation of the USERVARS). 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 bins=10 limits=[-5 5]) When placed after all variables, these two latter modifiers apply to the signal (e.g. intensity). Unknown keywords are ignored. If no limits are specified for a given observable, reasonable defaults will be applied. Note that these implicit limits are even applied in list mode.

Implicit limits for typical variables: (consult monitor_nd-lib.c if you don’t find your variable here) x, y, z: Derived from detection-object geometry

k: [0 10] Angs-1
v: [0 1e6] m/s
t: [0 1] s

p: [0 FLT_MAX] in intensity-units

vx, vy: [-1000 1000] m/s
vz: [0 10000] m/s
kx, ky: [-1 1] Angs-1
kz: [-10 10] Angs-1

energy, omega: [0 100] meV lambda,wavelength: [0 100] Å sx, sy, sz: [-1 1] in polarisation-units angle: [-50 50] deg divergence, vdiv, hdiv, xdiv, ydiv: [-5 5] deg longitude, lattitude: [-180 180] deg neutron: [0 simulaton_ncount] id, pixel id: [0 FLT_MAX]

uservars u0,u1,u2,u3,u4,u5,u6,u7,u8,u9: [-1e10 1e10]

In the case of multiple components at the same position, the ’parallel’ keyword must be used in each instance instead of defining a GROUP.

Possible options are Variables to record: kx ky kz k wavevector [Å-1] Wavevector on x,y,z and norm

vx vy vz v            [m/s]    Velocity on x,y,z and norm
x y z radius          [m]      Distance, Position and norm
xy, yz, xz            [m]      Radial position in xy, yz and xz plane
kxy kyz kxz           [Angs-1] Radial wavevector in xy, yz and xz plane
vxy vyz vxz           [m/s]    Radial velocity in xy, yz and xz plane
t time                [s]      Time of Flight
energy omega          [meV]    energy of neutron
lambda wavelength     [Angs]   wavelength of neutron
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

user0 user1           will monitor the [Mon_Name]_Vars.UserVariable{0|1|2|3|4|5}
user2 user3           to be assigned in an other component (see below)

user4 user5 user6 user7 user8 user9

Premonitoring:            Please use uservars in place of the former PreMonitor_nD.

p intensity flux      [n/s  or  n/cm^2/s]
ncounts n neutron     [1]      neutron ID, i.e current event index
pixel id              [1]      pixelID in histogram made of preceeding vars, e.g. ’theta y’. To set an offset PixelID use the ’min=value’ keyword. Sets event mode.

Other options keywords 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/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 det
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 log of the following variable or of the signal (if used after all variables)
min=[min_value]           Same as limits, but only sets the min or max

max=[max_value]

multiple                  Create multiple independant 1D monitors files
no or not                 Revert next option
outgoing                  Monitor outgoing beam (default)
parallel                  Use this option when the next component is at the same position (parallel components)
per cm2                   Intensity will be per cm^2 (detector area). Displays beam section.
per steradian             Displays beam solid angle in steradian
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
inactivate                To inactivate detector (0D detector)
verbose                   To display additional informations

3He_pressure=[3 in bars] The 3He gas pressure in detector. 3He_pressure=0 is perfect detector (default)

Detector shape options (specified as xwidth,yheight,zdepth or x/y/z/min/max)

box                       Box of size xwidth, yheight, zdepth.
cylinder                  To get a cylindrical monitor (diameter is xwidth or set radius, height is yheight).
banana                    Same as cylinder, without top/bottom, on restricted angular area; use theta variable with limits to define arc. (diameter is xwidth or set radius, height is yheight).
disk                      Disk flat xy monitor. diameter is xwidth.
sphere                    To get a spherical monitor (e.g. a 4PI) (diameter is xwidth or set radius).
square                    Square flat xy monitor (xwidth, yheight).
previous                  The monitor uses PREVIOUS component as detector surface. Or use ’geometry’ parameter to specify any PLY/OFF geometry file.

EXAMPLES: <ul> <li>MyMon = Monitor_nD(xwidth = 0.1, yheight = 0.1, zdepth = 0, &emsp;&emsp;options = "intensity per cm2 angle,limits=[-5 5] bins=10,with &emsp;&emsp;borders, file = mon1"); will monitor neutron angle from [z] axis, between -5 and 5 degrees, in 10 bins, into "mon1.A" output 1D file

<li> options = "sphere theta phi outgoing" for a sphere PSD detector (out beam) and saves into file "MyMon_[Date_ID].th_ph"

<li> options = "banana, theta limits=[10,130], bins=120, y" a theta/height banana detector

<li> options = "angle radius all auto" is a 2D monitor with automatic limits

<li> options = "list=1000 kx ky kz energy" records 1000 neutron event in a file

<li> 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)

<li> options = "theta y, sphere, pixel min=100" a 4pi detector which outputs an event list with pixelID from the actual detector surface, starting from index 100.

</ul> To dynamically define a number of bins, or limits:

Use in DECLARE:    char op[256];

Use in INITIALIZE: sprintf(op, "lambda limits=[%g %g], bins=%i", lmin, lmax, lbin);

Use in TRACE:      Monitor_nD(... options=op ...)

How to monitor any instrument/component variable into a Monitor_nD Suppose you want to monitor a variable ’age’ which you assign somwhere in the instrument: COMPONENT MyMonitor = Monitor_nD( xwidth = 0.1, yheight = 0.1, user1="age", username1="Age of the Captain [years]", options="user1, auto")

AT ...

%BUGS The ’auto’ option for guessing optimal variable bounds should NOT be used with MPI as each process may use different limits.

Input parameters

Parameters in boldface are required; the others are optional.

Links

• Component source code found in file Monitor_nD.comp.

A general Monitor for 0D/1D/2D records

The component Monitor_nD is a general Monitor that may output any set of physical parameters regarding the passing neutrons. The generated files are either a set of 1D signals ([Intensity] vs. [Variable]), or a single 2D signal ([Intensity] vs. [Variable 1] vs. [Variable 1]), and possibly a simple long list of selected physical parameters for each neutron.

The input parameters for Monitor_nD are its dimensions \(x_\textrm { min}, x_\textrm {max}, y_\textrm {min}\), \(y_\textrm {max}\) (in meters) and an options string describing what to detect, and what to do with the signals, in clear language. The \(x_{width}, y_{height}, z_{depth}\) may also be used to enter dimensions.

Eventhough the possibilities of Monitor_nD are numerous, its usage remains as simple as possible, specially in the options parameter, which ’understands’ normal language. The formatting of the options parameter is free, as long as it contains some specific keywords, that can be sometimes followed by values. The no or not option modifier will revert next option. The all option can also affect a set of monitor configuration parameters (see below).

As the usage of this component enables to monitor virtually anything, and thus the combinations of options and parameters is infinite, we shall only present the most basic configuration. The reader should refer to the on-line component help, using e.g. mcdoc Monitor_nD.comp.

The Monitor_nD geometry

The monitor shape can be selected among seven geometries:

1. (square) The default geometry is flat rectangular in (\(xy\)) plane with dimensions \(x_\textrm {min}, x_\textrm {max}, y_\textrm {min}\), \(y_\textrm {max}\), or \(x_{width}, y_{height}\).

2. (box) A rectangular box with dimensions \(x_{width}, y_{height}, z_{depth}\).

3. (disk) When choosing this geometry, the detector is a flat disk in (\(xy\)) plane. The radius is then \begin {equation} \mbox {radius} = \max ( \mbox {abs } [ x_\textrm {min}, x_\textrm {max}, y_\textrm { min}, y_\textrm {max}, x_{width}/2, y_{height}/2 ] ). \end {equation}

4. (sphere) The detector is a sphere with the same radius as for the disk geometry.

5. (cylinder) The detector is a cylinder with revolution axis along \(y\) (vertical). The radius in (\(xz\)) plane is \begin {equation} \mbox {radius} = \max ( \mbox {abs } [ x_\textrm {min}, x_\textrm {max}, x_{width}/2 ] ), \end {equation} and the height along \(y\) is \begin {equation} \mbox {height} = | y_\textrm {max} - y_\textrm {max} | \textrm {or} y_{height}. \end {equation}

6. (banana) The same as the cylinder, but without the top/bottom caps, and on a restricted angular range. The angular range is specified using a theta variable limit specification in the options.

7. (previous) The detector has the shape of the previous component. This may be a surface or a volume. In this case, the neutron is detected on previous component, and there is not neutron propagation.

By default, the monitor is flat, rectangular. Of course, you can choose the orientation of the Monitor_nD in the instrument description file with the usual ROTATED modifier.

For the box, sphere and cylinder, the outgoing neutrons are monitored by default, but you can choose to monitor incoming neutron with the incoming option.

At last, the slit or absorb option will ask the component to absorb the neutrons that do not intersect the monitor. The exclusive option word removes neutrons which are similarly outside the monitor limits (that may be other than geometrical).

The parallel option keyword is of common use in the case where the Monitor_nD is superposed with other components. It ensures that neutrons are detected independently of other geometrical constrains. This is generally the case when you need e.g. to place more than one monitor at the same place.

The neutron parameters that can be monitored

There are many different variables that can be monitored at the same time and position. Some can have more than one name (e.g. energy or omega).

1kx ky kz k wavevector [Angs-1] (    usually axis are 
2vx vy vz v           [m/s]         x=horz., y=vert., z=on axis) 
3x y z                [m]      Distance, Position 
4kxy vxy xy radius     [m]      Radial wavevector, velocity and position 
5t time               [s]      Time of Flight 
6energy omega         [meV] 
7lambda wavelength     [Angs] 
8p intensity flux      [n/s] or [n/cm^2/s] 
9ncounts              [1] 
10sx sy sz             [1]      Spin 
11vdiv ydiv dy         [deg]    vertical divergence (y) 
12hdiv divergence xdiv  [deg]    horizontal divergence (x) 
13angle                [deg]    divergence from  direction 
14theta longitude       [deg]    longitude (x/z) [for sphere and cylinder] 
15phi   lattitude       [deg]    lattitude (y/z) [for sphere and cylinder]

as well as two other special variables

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

To tell the component what you want to monitor, just add the variable names in the options parameter. The data will be sorted into bins cells (default is 20), between some default limits, that can also be set by user. The auto option will automatically determine what limits should be used to have a good sampling of signals.

Important options

Each monitoring records the flux (sum of weights \(p\)) versus the given variables, except if the signal=<variable> word is used in the options. The cm2 option will ask to normalize the flux to the monitor section surface, and the capture option uses the gold foil integrated ’capture’ flux weightening (up to the cadmium cut-off): \begin {equation} \Phi _c = \int _0^{0.5 eV}{\frac {d\Phi }{d\lambda } \frac {\lambda }{\lambda _{2200 m/s}} d\lambda } \end {equation}

The auto option is probably the most useful one: it asks the monitor to automatically determine the best limits for each variable, in order to obtain the most significant monitored histogram. This option should preceed each variable, or be located after all variables in which case they are all affected. On the other hand, one may manually set the limits with the limits=[min max] option. If no limits are set monitor_nd uses predefined limits that usually make sense for most neutron scattering simulations. Example: the default upper energy limit is \(100\) meV, but may be changed with an options string like options="energy limits 0 200". Note that the limits also apply in list mode (see below).

The log and abs options should be positioned before each variable to specify logarithmic binning and absolute value respectively.

The borders option will monitor variables that are outside the limits. These values are then accumulated on the ’borders’ of the signal.

The output files

By default, the file names will be the component name, followed by a time stamp and automatic extensions showing what was monitored (such as MyMonitor.x). You can also set the filename in options with the file keyword followed by the file name that you want. The extension will then be added if the name does not contain a dot (.). Finally, the \(filename\) parameter may also be used.

The output files format are standard 1D or 2D McStas detector files. The no file option will inactivate monitor, and make it a single 0D monitor detecting integrated flux and counts. The verbose option will display the nature of the monitor, and the names of the generated files.

The 2D output

When you ask the Monitor_nD to monitor only two variables (e.g. options = "x y"), a single 2D file of intensity versus these two correlated variables will be created.

The 1D output

The Monitor_nD can produce a set of 1D files, one for each monitored variable, when using 1 or more than 2 variables, or when specifying the multiple keyword option.

The List output

The Monitor_nD can additionally produce a list of variable values for neutrons that pass into the monitor. This feature is additive to the 1D or 2D output. By default only 1000 events will be recorded in the file, but you can specify for instance "list 3000 neutrons" or "list all neutrons". This last option may require a lot of memory and generate huge files. Note that the limits to the measured parameters also apply in this mode. To exemplify, a monitor_nd instance with the option string "list all v" will only record those neutrons which have a velocity below \(100000\) m/s, whereas an instance with the option string "list all vx vy vz 0 2000" will record all neutrons with \(|v_x,v_y|<100\) m/s and \(0<v_z<2000\) m/s. Thus, in this latter case, any neutron travelling in the negative z-direction will be disregarded.

Monitor equivalences

In the following table 10.9, we show how the Monitor_nD may substitute any other McStas monitor.

---

---

Usage examples

• 1COMPONENT MyMonitor = Monitor_nD( 
  2    xmin = -0.1, xmax = 0.1, 
  3    ymin = -0.1, ymax = 0.1, 
  4    options = "energy auto limits")

  will monitor the neutron energy in a single 1D file (a kind of E_monitor)

• options = "banana, theta limits=[10,130], bins=120, y bins=30"
  is a theta/height banana detector.

• options = "banana, theta limits=[10,130], auto time"
  is a theta/time-of-flight banana detector.

• options="x bins=30 limits=[-0.05 0.05] ; y"
  will set the monitor to look at \(x\) and \(y\). For \(y\), default bins (20) and limits values (monitor dimensions) are used.

• options="x y, auto, all bins=30"
  will determine itself the required limits for \(x\) and \(y\).

• options="multiple x bins=30, y limits=[-0.05 0.05], all auto"
  will monitor the neutron \(x\) and \(y\) in two 1D files.

• options="x y z kx ky kz, all auto"
  will monitor each of theses variables in six 1D files.

• options="x y z kx ky kz, list all, all auto"
  will monitor all theses neutron variables in one long list, one row per neutron event.

• options="multiple x y z kx ky kz, and list 2000, all auto"
  will monitor all theses neutron variables in one list of 2000 events and in six 1D files.

• options="signal=energy, x y"
  is a PSD monitor recording the mean energy of the beam as a function of \(x\) and \(y\).

Monitoring user variables

There are two ways to monitor any quantity with Monitor_nD. This may be e.g. the number of neutron bounces in a guide, or the wavevector and energy transfer at a sample. The only requirement is to define the user1 (and optionally user2,user3) variables of a given Monitor_nD instance.

Directly setting the user variables (simple)

The first method uses directly the user1 and username1 component parameters to directly transfer the value and label, such as in the following example:

1TRACE 
2(...) 
3COMPONENT UserMonitor = Monitor_nD( 
4  user1    = log(t), username1="Log(time)", 
5  options  ="auto user1")

The values to assign to user2 and user3 must be global instrument variables, or a component output variables as in user1=MC_GETPAR(some_comp, outpar). Similarly, the user2,user3 and username2,username3 parameters may be used to control the second and third user variable, to produce eventually 2D/3D user variable correlation data and custom event lists.

Indirectly setting the user variables (only for professionals)

It is possible to control the user variables of a given Monitor_nD instance anywhere in the instrument description. This method requires more coding, but has the advantage that a variable may be defined to store the result of a computation locally, and then transfer it into the UserMonitor, all fitting in an EXTEND block.

This is performed in a 4 steps process:

1. Declare that you intend to monitor user variables in a Monitor_nD instance (defined in TRACE):

   1DECLARE 
   2%{ (...) 
   3  %include "monitor_nd-lib" 
   4  MONND_DECLARE(UserMonitor); // will monitor custom things in UserMonitor 
   5%}

2. Initialize the label of the user variable (optional):

   1INITIALIZE 
   2%{ 
   3  (...) 
   4  MONND_USER_TITLE(UserMonitor, 1, "Log(time)"); 
   5%}

   The value ’1’ could be ’2’ or ’3’ for the user2,user3 variable.

3. Set the user variable value in a TRACE component EXTEND block:

   1TRACE 
   2(...) 
   3COMPONENT blah = blah_comp(...) 
   4EXTEND 
   5%{  // attach a value to user1 in UserMonitor, could be much more comlex here. 
   6  MONND_USER_VALUE(UserMonitor, 1, log(t)); 
   7%} 
   8(...)

4. Tell the Monitor_nD instance to record user variables:

   1TRACE 
   2(...) 
   3COMPONENT UserMonitor = Monitor_nD(options="auto user1") 
   4(...)

Setting the user variable values may either make use of the neutron parameters (x,y,z, vx,vy,vz, t, sx,sy,sz, p), access the internal variables of the component that sets the user variables (in this example, those from the blah instance), access any component OUTPUT parameter using the MC_GETPAR C macro(see chapter A.5.4), or simply use a global instrument variable. Instrument parameters can not be used directly.

Example: Number of neutron bounces in a guide

In the following example, we show how the number of bounces in a polygonal guide may be monitored. Let us have a guide made of many Guide_gravity instances. We declare a global simulation variable nbounces, set it to 0 for each neutron entering the guide, and sum-up all bounces from each section, accessing the Gvars OUTPUT variable of component Guide_gravity. Then we ask Monitor_nD to look at that value.

1DECLARE 
2%{ 
3  double nbounces; 
4%} 
5TRACE 
6(...) 
7COMPONENT Guide_in = Arm() AT (...) 
8EXTEND 
9%{ 
10  nbounces = 0; 
11%} 
12 
13COMPONENT Guide1 = Guide_gravity(...) AT (...) RELATIVE PREVIOUS 
14EXTEND 
15%{ 
16  if (SCATTERED) nbounces += GVars.N_reflection[0]; 
17%} 
18(... many guide instances, copy/paste and change names automatically ...) 
19COMPONENT COPY(Guide1) = COPY(Guide1) AT (...) RELATIVE PREVIOUS 
20EXTEND 
21%{ 
22  if (SCATTERED) nbounces += GVars.N_reflection[0]; 
23%} 
24 
25// monitor nbounces 
26COMPONENT UserMonitor = Monitor_nD( 
27  user1=nbounces, username1="Number of bounces", 
28  options="auto user1") AT (...) 
29(...)

Monitoring neutron parameter correlations, PreMonitor_nD

The first imediate usage of the Monitor_nD component is when one requires to identify cross-correlations between some neutron parameters, e.g. position and divergence (aka phase-space diagram). This latter monitor would be merely obtained with:

1options="x dx, auto", bins=30

This example records the correlation between position and divergence of neutrons at a given instrument location.

But it is also possible to search for cross-correlation between two part of the instrument simulation. One example is the acceptance phase-diagram, which shows the neutron caracteristics at the input required to reach the end of the simulation. This spatial correlation may be revealed using the PreMonitor_nD component. This latter stores the neutron parameters at a given instrument location, to be used at an other Monitor_nD location for monitoring.

The only parameter of PreMonitor_nD is the name of the associated Monitor_nD instance, which should use the premonitor option, as in the following example:

1COMPONENT CorrelationLocation = PreMonitor_nD(comp = CorrelationMonitor) 
2AT (...) 
3 
4  (... e.g. a guide system ) 
5 
6COMPONENT CorrelationMonitor  = Monitor_nD( 
7   options="x dx, auto, all bins=30, premonitor") 
8AT (...)

which performs the same monitoring as the previous example, but with a spatial correlation constrain. Indeed, it records the position vs the divergence of neutrons at the correlation location, but only if they reach the monitoring position. All usual Monitor_nD variables may be used, except the user variables. These latter may be defined as described in section 10.8.0.0 in an EXTEND block.