User and Programmers Guide to the Neutron Ray-Tracing Package McStas, version 3.8.6

4  The McStas kernel and meta-language

Instrument definitions are written in a special McStas meta-language which is translated automatically by the compiler mcstas into a C program which is in turn compiled to an executable that performs the simulation. The meta-language is custom-designed for neutron scattering and serves two main purposes: (i) to specify the interaction of a single neutron ray with a single optical component, and (ii) to build a simulation by constructing a complete instrument from individual components.

For maximum flexibility and efficiency, the meta-language is based on C. Instrument geometry, propagation of neutrons between the different components, parameters, data input/output etc. is handled in the meta-language and by the compiler mcstas. Complex calculations are written in C embedded in the meta-language description of the components. However, it is possible to set up an instrument from existing components and run a simulation without writing a single line of C code, working entirely in the meta-language.

Apart from the meta-language, McStas also includes a number of C library functions and definitions that are useful for neutron ray-tracing simulations. The definitions available for component developers are listed in appendix A.2. The list includes functions for

The McStas meta-language was designed to be readable, with a verbose syntax and explicit mentioning of otherwise implicit information. The recommended way to get started with the meta-language is to start by looking at the examples supplied with McStas, modifying them as necessary for the application at hand.

4.1 Notational conventions
4.2 Syntactical conventions
4.3 Writing instrument definitions
4.3.1 The instrument definition head
4.3.2 The DEPENDENCY line
4.3.3 The SEARCH line
4.3.4 The SHELL line
4.3.5 The DECLARE section
4.3.6 The USERVARS section
4.3.7 The INITIALIZE section
4.3.8 The NEXUS extension
4.3.9 The TRACE section
4.3.10 The SAVE section
4.3.11 The FINALLY section
4.3.12 The end of the instrument definition
4.3.13 Code for the instrument vanadium_example.instr
4.4 Writing instrument definitions - complex arrangements and syntax
4.4.1 Embedding instruments in instruments TRACE
4.4.2 Groups and component extensions - GROUP - EXTEND
4.4.3 Duplication of component instances - COPY
4.4.4 Conditional components - WHEN
4.4.5 Component loops and non sequential propagation - JUMP
4.4.6 Enhancing statistics reaching components - SPLIT
4.4.7 Attaching metadata to components and instruments - METADATA
4.5 Writing component definitions
4.5.1 The component definition header
4.5.2 The NOACC flag
4.5.3 The DEPENDENCY line
4.5.4 The DECLARE section
4.5.5 The SHARE section
4.5.6 The INITIALIZE section
4.5.7 The TRACE section
4.5.8 The SAVE section
4.5.9 The FINALLY section
4.5.10 The MCDISPLAY section
4.5.11 The end of the component definition
4.5.12 A component example: Slit
4.6 Extending component definitions
4.6.1 Extending from the instrument definition
4.6.2 Component heritage and duplication
4.7 McDoc, the McStas library documentation tool
4.7.1 Documentation generators mcdoc and mcgui
4.7.2 The format of the comments in the library source code