McXtrace - An X-ray ray-trace simulation package

8.9  The Monitor_nD McXtrace Component

Release: McXtrace 1.2

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 photon 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. In normal configuration, the Monitor_nD measures the current parameters of the photon that is being 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 photon: [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          [keV]    energy of photon
lambda wavelength     [Angs]   wavelength of photon
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      [phts/s  or  phts/cm^2/s]
ncounts n photon      [1]      photon 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 photons (X < min or X > max)
capture                   weight by capture flux (not validated)
exclusive                 absorb photon out of monitor limits
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 photon 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             Intensity will be per steradian (requires auto)
signal=[var]              Will monitor [var] instead of usual intensity
slit or absorb            Absorb photons that are out detector
source                    The monitor will save photon states
inactivate                To inactivate detector (0D detector)
verbose                   To display additional informations

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.

EXAMPLES: MyMon = Monitor_nD( xwidth = 0.1, yheight = 0.1, zdepth = 0, options = ”intensity per cm2 angle,limits=[-5 5] bins=10,with borders, file = mon1”); will monitor photon 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 = ”banana, theta limits=[10,130], bins=120, y” a theta/height banana detector

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

options = ”list=1000 kx ky kz energy” records 1000 photon event in a file options = ”multiple kx ky kz, auto abs log t, and list all photons” makes 4 output 1D files and produces a complete list for all photons and monitor log(abs(tof)) within automatic limits (for t) 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.

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 photons. The generated files are either a set of 1D signals ([Intensity] vs. [Variable]), or a single 2D signal ([Intensity] vs. [Variable 1] vs. [Variable 2]), and possibly a simple long list of selected physical parameters for each photon ray.

The input parameters for Monitor_nD are its dimensions xmin, xmax, ymin, ymax (in metres) and an options string describing what to detect, and what to do with the signals, in clear language. The xwidth, yheight, zdepth 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.

8.9.1  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_\mathrm {min}, x_\mathrm {max}, y_\mathrm {min}\), \(y_\mathrm {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_\mathrm {min}, x_\mathrm {max}, y_\mathrm { min}, y_\mathrm {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_\mathrm {min}, x_\mathrm {max}, x_{width}/2 ] ), \end {equation} and the height along \(y\) is \begin {equation} \mbox {height} = | y_\mathrm {max} - y_\mathrm {max} | \mathrm {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 photon is detected on the previous component, and there is no photon 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 photons are monitored by default, but you can choose to monitor incoming photons with the incoming option.

At last, the slit or absorb option will ask the component to absorb the photons that do not intersect the monitor. The exclusive option word removes photons 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 photons 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.

8.9.2  The photon 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).

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

as well as four other special variables

1    user user1           will monitor the [Mon_Name]_Vars.UserVariable{1|2} 
2    user2 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.

8.9.3  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 auto option is probably the most useful one: it asks the monitor to determine automatically 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 x-ray 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.

8.9.4  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 McXtrace 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 photons 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 photons” or ”list all photons”. 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 k" will only record those photons which have a below \(2000\) AA\(^{-1}\), whereas an instance with the option string "list all kx ky kz 0 2000" will record all photons with \(|k_x,k_y|<2000\) AA\(^{-1}\) and \(0<v_z<2000\) AA\(^{-1}\). Thus, in this latter case, any neutron travelling in the negative z-direction will be disregarded.

8.9.5  Monitor equivalences

In the following table 8.10, we show how the Monitor_nD may substitute any other McXtrace monitor.

8.9.6  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 photon 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 photon \(x\) and \(y\) in two 1D files.

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

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

• options="multiple x y z kx ky kz, and list 2000, all auto"
  will monitor all the photons’ 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\).

8.9.7  Monitoring user variables

There are two ways to monitor any quantity with Monitor_nD. This may be e.g. the number of reflections in a mirror system, 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 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 variable 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.

Setting indirectly 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-step 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 complex 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 photon parameters (x,y,z, vx,vy,vz, phi, t, Ex,Ey,Ez, 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), or simply use a global instrument variable. Instrument parameters can not be used directly.