Basic McStas

In short, the core of the McStas system is a precompiler. From a user-provided instrument description, components are assembled into a single piece of ansi-c code. Using a compiler, e.g. gcc, the c code is compiled into an executable program which can be run on your computer. Optionally, the program takes input arguments to tune the setup of your instrument/simulation. This section will take you through a (very) simple example instrument to learn you the basic instrument language of McStas. (Instrument filename is vanadium_example.instr, can be loaded using the Neutron Site/Tutorial menu item of the mcgui, see below) Please study carefully the instructive comments, marked by /* ... */ characters

/* The line below defines the 'name' of our instrument */
/* Here, we have a single input parameter, ROT         */
DEFINE INSTRUMENT vanadium_example(ROT=0)

/* The DECLARE section allows us to declare variables  */
/* in c syntax. Here, coll_div (collimator divergence) */
/* is set to 60 degrees...                             */
DECLARE
%{
  double coll_div = 60;
%}

/* Here comes the TRACE section, where the actual      */
/* instrument is defined....                           */
TRACE

/* The Arm() class component defines reference points  */
/* in 3D space. Every component instance must have a   */
/* unique name. Here, arm is used. This Arm() component*/
/* is set to define the origin of our global coordinate*/
/* system (AT (0,0,0) ABSOLUTE)                        */
COMPONENT arm = Arm() AT (0,0,0) ABSOLUTE

/* Next, we need some neutrons. Let's place a neutron  */
/* source. Refer to documentation of Source_flat to    */
/* understand the different input parameters.          */
/* The source component is placed RELATIVE to the arm  */
/* component, meaning that modifying the position or   */
/* orientation of the arm will also affect the source  */
/* component (and other components after that one...   */
COMPONENT source = Source_flat(radius = 0.015, dist = 1,
  xw=0.024, yh=0.015, E0=5, dE=0.2)
 AT (0,0,0) RELATIVE arm

/* Here we have a collimator - or Soller - placed to   */
/* improve beam divergence.                            */
/* The component is placed at a distance RELATIVE to   */
/* a previous component...                             */
COMPONENT collimator = Collimator_linear(len = 0.2, 
  divergence = coll_div, xmin = -0.02, xmax = 0.02, 
  ymin = -0.03, ymax = 0.03)
  AT (0, 0, 0.4) RELATIVE arm

/* We also need something to 'shoot at' - here a sample*/
/* made from vanadium - an isotrope scatterer. Options */
/* are available to restrict the solid angle in which  */
/* neutrons are emitted (no need to simulate anything  */
/* that we know for sure will not gain us more insight)*/
/* Other options for smart targeting are available -   */
/* refer to component documentation for info.          */
COMPONENT target = V_sample(radius_i = 0.008, radius_o = 0.012, 
  h = 0.015, focus_r = 0, pack = 1,
  target_x = 0, target_y = 0, target_z = 1)
  AT (0,0,1) RELATIVE arm

/* Here, a secondary arm - or reference point, placed  */
/* on the sample position. The ROT parameter above     */
/* defines rotation of this arm (and components        */
/* relative to the arm)                                */
COMPONENT arm2 = Arm() 
  AT (0,0,0) RELATIVE target
  ROTATED (0,ROT,0) relative arm

/* For data output, let us place a detector. This      */
/* detector is not very realistic, since it is sphere  */
/* shaped and has a 10 m radius, but has the advantage */
/* that EVERYTHING emitted from the sample will be     */
/* picked up. Notice that this component changes       */
/* orientation with the ROT input parameter of the     */
/* instrument.                                         */
COMPONENT PSD_4pi = PSD_monitor_4PI(radius=10, nx=101, ny=51,
  filename="vanadium.psd")
  AT (0,0,0) RELATIVE target ROTATED (ROT,0,0) RELATIVE arm2
END

Enlightened by the above example, you are probably now ready to learn a few more important details and tips about McStas.

Neutron histories/Intensities: McStas simulates neutron histories rather than direct neutron counts, i.e. when a Monte Carlo choice is made in a given component (e.g. a random number is generated to decide a new direction of the neutron ray), the neutron weight factor is adjusted accordingly. As you may have guessed already, the weight factor is actually a probability of observing a neutron of the given behaviour. The transition to direct neutron intensites is made by adjusting the initial neutron weight of the source component, giving the absolute flux of neutrons emitted in one second. This means that the intensity of the neutron beam at a given position is the initial neutron weight multiplied by the product of all the Monte Carlo weight factors occuring from the source to the given position. When observing McStas output, is the intensity, not .
3D space: The 3D space in which the instrument is defined, usually has a single component which is placed ABSOLUTEly in space, e.g. at (0,0,0). All other components can be placed relative to this component.
Changing coordinate system: Each component has its own local coordinate system. As the neutron travels from one component to the other, the local component coordinate system changes. The definition is that is the direction toward the next component, and that the direction is vertical.
Component order matters! It is important to understand that McStas is component order dependent. The basic idea is to follow the neutron as it travels from one component to the next in the instument description. This means that if you place one component geometrically before another component, but orderly after the other component, neutrons may never reach your 'first' component. This means that some designs can be difficult to achieve, though generally a solution can be found.
Use Arm()'s! The Arm() component is very good for defining changed orientation of the instrument, e.g. for axis turning points etc. Placing many Arm()'s will improve future flexibility of your instrument.
Use PSD_monitor()'s! The PSD_monitor() component is a position sensitive detector. This component can be used to image the shape of your beam as it travels through the instrument. This is very useful for debugging purposes. Other monitors, for instance wavelength monitors can also be useful.

In the McStas manual, available by clicking here if you are using an internet browser to view this document, description of usage of the different McStas tools is printed. The main McStas programs are

mcstas - Core application
mcgui - Main graphical user interface
mcdisplay - Ray trace / debugging application
mcplot - Data / display application
mcdoc - Documentation application

Here are a few hints on using the tools:

To start mcgui, execute mcgui in a terminal window (mcgui.pl on Windows)
To handle instrument files (opening, editing, compiling), use File menu of mcgui
To simulate and plot data, use the Simulation menu of mcgui
To use the distributed example McStas instruments, use the Neutron Site menu of mcgui
For further help on usage, use the items of the mcgui menu of Help menu or read the chapter Running McStas of the McStas manual [2].

Next: Exercises Up: McStas neutron ray-trace tutorial Previous: Basic understanding of instrument

Peter Willendrup 2004-03-05

Printable version

Last Modified: Tuesday, 22-Jun-2004 14:04:14 CEST