Before continuing, we should wonder what parameters will be required by the instrument.

In the example that I provide,, I choosed to enter parameters

K_i  incident neutron wavevector (Angs^-1),
Q exchange wavevector modulus (Angs^-1) and
E exchange energy (meV)

These will be asked by the instrument simulation at computation start. You can use as many numerical parameters as you need (max is 1000 !). Character string parameters are also permitted (if you set their type to 'string' or 'char *'). The parameter values usually define the instrumental geometry and physical parameters. They may be used and modified during the simulation.

Globally, an instrument is described following the general template below. We are now going to study the IN14 instrument described in the overview.
The in14_tut.instr file begins with the DEFINE section (you can save this file as a Source/txt file from your Browser). Thus the first line of the instrument description file will be

DEFINE INSTRUMENT IN14(Ki,Q,E)

followed by comments between '/*' and '*/' to identify author, date, instrument, parameters, usage, and a typical example.
You may additionally define default parameters for the instrument with:

DEFINE INSTRUMENT IN14(Ki=2.662,Q=2,E=0)

Each part of the instrument is indicated as a component, positioned and rotated with specified values. So, you first need to look at the component library to search if a given component already exists. If you can't find it, then you may need to write one corresponding to your needs (as we shall see further in this tutorial). In order to build the instrument simulation, McStas first looks for components in the current instrument location, and then refers to the common component library (e.g. /usr/local/lib/mcstas on Unix machines)

The description of the instrument is a sequential listing into the TRACE section. This means that you should not put two 'active' components exactly at the same place, overlap or include one into an other. Usually, you can separate them by say 1 mm if you really want to put them at 'nearly' the same place. Monitors can be positioned at the same place, as they usually do not affect the neutron beam. Anyway, you may build component groups. Look into the McStas manual for more.

Thus, we can write the skeleton of the instrument (following the informations given in the overview). The components have a generic name (from the McStas library, for instance Source_flux) and a specific name identifier, only valid for your simulation (for instance source).

TRACE
COMPONENT source = Source_flux() /* a flat constant source */
AT (0,0,0) ABSOLUTE

COMPONENT cold_guide = Guide()   /* guide between source and mono */
AT (0,0,2.15) RELATIVE source

COMPONENT mono_craddle = Arm() /* this is the monochromator craddle */
AT (0, 0, L1) RELATIVE source ROTATED (0, A1, 0) RELATIVE source

COMPONENT mono = Monochromator() /* Monochromator */
AT (0,0,0) RELATIVE mono_craddle

COMPONENT out_mono = Arm()  /* this is the mono-sample axis */
AT (0,0,0) RELATIVE mono_craddle ROTATED (0, A2, 0) RELATIVE source

COMPONENT mono_soller = Soller() /* a Soller collimator */
AT (0, 0, .9) RELATIVE out_mono

COMPONENT focus_sample = Arm()   /* this is the sample craddle */
AT (0, 0, L2) RELATIVE out_mono ROTATED (0, A3, 0) RELATIVE out_mono

COMPONENT sample = V_sample()    /* Sample */
AT (0,0,0) RELATIVE focus_sample

COMPONENT out_sample = Arm()     /* this is the sample-ana axis */
AT (0,0,0) RELATIVE focus_sample ROTATED (0, A4, 0) RELATIVE out_mono

COMPONENT focus_ana = Arm()      /* this is the analyzer craddle */
AT (0,0, L3) RELATIVE out_sample ROTATED (0, A5, 0) RELATIVE out_sample

COMPONENT ana = Monochromator()  /* Analyzer */
AT (0,0,0) RELATIVE focus_ana

COMPONENT out_ana = Arm()        /* this is the ana-det axis */
AT (0,0,0) RELATIVE focus_ana ROTATED (0, A6, 0) RELATIVE out_sample

COMPONENT focus_det = Arm()      /* this is the detector craddle */
AT (0, 0, L4) RELATIVE out_ana

COMPONENT Detector = Monitor()   /* detector */
AT(0,0,0) RELATIVE focus_det
 

Positioning components

Each component is placed (with AT) and tilted (ROTATED) with given values (in meters and degrees) or variables. The axis system is defined as

the Z-axis beeing the propagation axis (main geometrical direction)
the Y-axis is vertical
the X-axis makes the coordinate system direct

Rotations are around those axis, after the AT translation is performed. These operations are usually made in a given reference coordinate system (precised with the RELATIVE keyword, followed by one of your instrument component-identifier, such as ana or focus_det). As you can see in this skeleton, we introduced the angles A1 to A6 and the distances L1 to L4 in order to position the various components. These values must be defined somewhere. This will be explained in the computations and internal variables section below.
 

Component parameters

The components usually need some parameters to specify their behaviour (for instance the source shape and flux, the guide length, etc...). The component parameters will have to be given between the two parenthesis () following the component type, for instance

Monochromator(<my monochromator parameters=my values> , ...)

Thus when you need to use a specific component, you should first look at it's documentation or source code header, in order to look at the required parameters (in future versions, components will also have some default value parameters if not provided by user).

Here is a component parameters example for the source :

COMPONENT source = Source_flux( /* a flat constant source */
 radius = 0.20,
 dist = 2.16,
 xw = 0.06, yh = 0.12,<
 E0 = Ei,
 dE = 0.5,
 flux=1e13)
AT (0,0,0) ABSOLUTE

The component name of the parameter (left part of the =, for instace radius) is fixed by the component definition. It can not be changed in your instrument.
The values of these parameters (right part of =) can be given as a numerical (0.9), string ("my_filename", do not forget the quotes !), an instrument parameter (could be Q here) or variable (A1, but has to be defined before), and you can use mathematical expressions using internal variables, except instrument input parameters (e.g. 'A2/2' is permitted, if A2 has already been defined and is not an input component/instrument parameter). If you want to compute a numerical value (for instance A2/2), you may need to create a variable containing this value., as indicated in the computations and internal variables section below. For instance, in the source example up-there, the value of Ei should be known before the component is positioned.
The other components also need some parameters, as indicated in the TRACE section of the in14_tut.instr file. Please have a look at it.

In fact, we shall use a simple model of flat energy flux distribution for the source, flat monochromator and analyzer, and a single detector at the end. The Vanadium sample scattering is 'focussed' towards the analyzer. No need to scatter somewhere else, and loose neutrons !

Note: when using McGUI, the filenames (e.g. for monitors) should be specified between double quotes (").

Defining some component parameters or variables internal to the instrument simulation is done in two steps.

If you need to use such computations (mathematical expressions), you must compute them with embeded C code before calling the component.

Obviously, computing some paranmeters needed to position, rotate and describe components is an essential point of the simulation. This is done in the DECLARE and INITIALIZE sections, before the TRACE keyword.
In this example, we need to calculate the values of

• Ei in source : energy of neutrons produced by the source : should be set by the monochromator Bragg law.
• L1 to L4 for AT keywords : these are fixed, but should be easely modified in the instrument
• A1 to A6 for ROTATED keywords : these are to be computed from the instrument input parameters Ki, Q and E
• mono_q, ana_q : are values to be computed from monochromator and analyzer crystal lattice parameters, DM and DA. These should be easely changeable by user.

The computation of these values is done in two steps.

Declaring instrument internal variables : DECLARE

In the DECLARE section, which is optional if you don't use variables in your instrument (see the in14_tut.instr file), you indicate between symbols '%{' and '}%' what C variables you are going to use.
Possible C types are
 

You can assign a default value in the C declaration section. The variables declared in this section are global. You can use them in the whole instrument (INITIALIZE, TRACE and FINALLY sections) as shown below.

In the case of string arrays (character strings), you may need to dynamically allocate some memory with the malloc C function. Do not forget to free the allocated memory when it is not needed anymore (with the free C funtion). Please refer for this matter to a C language book, such as the Kernigan and Richie, C language, Prentice Hall, London, 1994. An example of dynamical allocation is shown in the Monitor_nD component (which calls the MCSTAS/share/monitor_nd-lib shared library).

Now, you can look at the DECLARE section of the instrument definition file. You will see that we introduce here the variables Ei, L1 to L4, A1 to A6, mono_q and ana_q, but also some other variables (DM, DA) that can be easely changed by the user, as they are all gathered in the same zone of the instrument source file. The variables Kf and Ef are declared also in case you would need them somewhere esle in the instrument.

Computing mathematical expressions and internal variables : INITIALIZE

In the INITIALIZE section, which follows the DECLARE section, you can also declare some C variables, but these will only be valid inside the INITIALIZE section. For instance, in our example, we declare Vi, Vf and others...
The embeded C code, between symbols '%{' and '}%', is executed at the begining of each computation. It can then be used to compute the values of your instrument variables, or to open some output files, display some specific informations on screen, etc...

In a typical TAS instrument, the incident Ki, transfert Q and final Kf neutron wavevector modulus, are related to the geometrical angles A1 to A6 by classical expressions :

Bragg reflexions

2 pi/Ki = 2 DM sin (A1) and 2 pi/Kf = 2 DA sin (A5) Momentum exchange rule Q2 = Ki2 + Kf2 - 2 | Ki.Kf | cos (A4) Energy exchange rule Ef = Ei - E Geometrical relations A2 = 2*A1
A6=2*A5

with the monochromator and analyzer lattice spacings DM and DA respectively (in Angstroms). The value of A3 deends on the sample orientations. We shall use here A3=A4/2.
In our example, we check the validity of instrument parameters, by the if keywords., and display a message if they are not valid (printf). We compute the values of mono_q and ana_q :

mono_q = 2*PI*ORDER/DM;
ana_q = 2*PI*ORDER/DA;

while DM and DA have been declared and initialized in the DECLARE section. ORDER is the order of the Bragg reflexion (usually 1).
The values of PI and DEG2RAD are defined in McStas. We do also a minimal error checking (no division by 0 please).

At the end of the INITIALIZE section, all variables defined in the DECLARE section or used in the TRACE section should have been defined and assigned.

At the end of the simulation file, place the keyword END. That's all.

If you want to do some stuff at the end of the computation (display some parameter values, free some C memory allocation blocks...), you are invited to do that in the FINALLY section (C code between the usual %{ and %} signs). It is executed at the end of the simulation. In our example we do not use that section.