About McStas
Conditions of use
Authors/Contacts
Project funding
Download
Components
Other Downloads (share)
Documentation
Wiki (GitHub)
McStas manual
Publications
4.2 Syntactical conventions
Comments follow the C and C++ syntax
1/* C style comment */ 2// C++ style comment 3
Keywords are not case-sensitive, for example “DEFINE”, “define”, and “dEfInE” are all equivalent. However, by convention we always write keywords in uppercase to distinguish them from identifiers and C language keywords. In contrast, McStas identifiers (names), like C identifiers and keywords, are case sensitive, another good reason to use a consistent case convention for keywords. All McStas keywords are reserved, and thus should not be used as C variable names. The list of these reserved keywords is shown in table 4.1.
| Keyword | Scope | Meaning |
| ABSOLUTE | I | Indicates that the AT and ROTATED keywords are in the absolute coordinate system. |
| AT | I | Indicates the position of a component in an instrument definition. |
| COPY | I | Duplicate a previous component instance in the TRACE section (see section 4.4.3). |
| CPU | I | Forces a specific component instance to run on CPU only, even in an otherwise GPU/OpenACC-enabled instrument (implies DEPENDENCY "-DFUNNEL"). |
| DECLARE | I,C | Declares C internal variables. |
| DEFINE | I,C | Starts an INSTRUMENT or COMPONENT definition. |
| DEFINITION | C | Defines component parameters that are constants (#define). |
| DEPENDENCY | C,I | Indicates any library dependency required to create the instrument. |
| DISPLAY | C | Alias for MCDISPLAY. |
| END | I,C | Ends the instrument or component definition. |
| SPLIT | I | Enhance incoming statistics by event repetition. |
| EXTEND | I,C | Extends a component TRACE section (plug-in), or extends an inherited section (see INHERIT). |
| FINALLY | I,C | Embeds C code to execute when simulation ends. |
| GROUP | I | Defines an exclusive group of components. |
| %include | I,C | Imports an instrument part, a component or a piece of C code (when within embedded C). |
| INHERIT | C | Derives a component (definition, or a single section) from an existing component (see section 4.6). |
| INITIALIZE | I,C | Embeds C code to be executed when starting. Alias: INITIALISE. |
| ITERATE | I | Defines iteration counter for JUMP. |
| JUMP | I | Iterative (loops) and conditional jumps. |
| MCDISPLAY | C | Embeds C code to display component geometry. Alias: DISPLAY. |
| METADATA | I,C | Attaches an arbitrary, typed, named block of text (e.g. an IDF/CIF/JSON fragment) to a component definition or instance, retrievable via mcrun –meta-* (see section 4.4.7). |
| MYSELF | I | Refers to the current component instance (COPY, JUMP). |
| NOACC | C | Marks a component class as CPU-only (never compiled for GPU/OpenACC). |
| NEXT | I | Refers to a following component instance (JUMP). |
| OUTPUT | C | Defines internal variables to be public and protected symbols (usually all global variables and functions of DECLARE). Alias: PRIVATE. |
| PARAMETERS | C | Defines a class of component parameter (DEFINITION, SETTING). |
| PREVIOUS | I,C | Refers to a previous component position/orientation/instance. |
| RELATIVE | I | Indicates that the AT and ROTATED keywords are relative to an other component. |
| REMOVABLE | I | Indicates that this component will be removed when the instrument is inserted into an other one using the %include keyword. |
| ROTATED | I | Indicates the orientation of a component in an instrument definition. |
| SAVE | I,C | Embedded C code to execute when saving data. |
| SEARCH | I,C | Appends an additional instrument/component search directory (optionally computed by an external SHELL command), see section 4.3.3. |
| SETTING | C | Defines component parameters that are variables. |
| SHARE | C | Declares global functions and variables to be shared. |
| SHELL | I,C | Executes a shell command before code generation, see section 4.3.4. |
| TRACE | I,C | Defines the instrument as a the component sequence. |
| USERVARS | I,C | Declares per-neutron user state variables, an alternative to global DECLARE variables that is safe for GPU/OpenACC use (see section 4.3.6). |
| WHEN | I | Condition for component activation and JUMP. |
| Table 4.1.: | Reserved McStas keywords. Scope is ’I’ for instrument and ’C’ for component definitions. |
It is possible, and usual, to split the input instrument definition across several different files. For example, if a component is not explicitly defined in the instrument, mcstas will search for a file containing the component definition in the standard component library (as well as in the current directory and any user-specified search directories, see section 3.3.2). It is also possible to explicitly include another file using a line of the form
1 %include "file"
Beware of possible confusion with the C language “#include” statement, especially when it is used in C code embedded within the McStas meta-language. Files referenced with “%include” are read when the instrument is translated into C by mcstas, and must contain valid McStas meta-language input (and possibly C code). Files referenced with “#include” are read when the C compiler generates an executable from the generated C code, and must contain valid C.
Embedded C code is used in several instances in the McStas meta-language. Such code is copied by mcstas into the generated simulation C program. Embedded C code is written by putting it between the special symbols % and %, as follows:
1%{ 2// Embedded C code... 3%}
The %{ and %} must appear on a line by themselves (do not add comments after). Additionally, if a “%include” statement is found within an embedded C code block, the specified file will be included from the ’share’ directory of the standard component library (or from the current directory and any user-specified search directories) as a C library, just like the usual “#include” but only once. For instance, if many components require to read data from a file, they may all ask for “%include "read_table-lib"” without duplicating the code of this library. If the file has no extension, both .h and .c files will be searched and included, otherwise, only the specified file will be imported. The McStas’run-time’ shared library is included by default (equivalent to “%include "mcstas-r"” in the DECLARE section). For an example of %include, see the monitors/Monitor_nD component. See also section 4.4 for insertion of full instruments in instruments (instrument concatenation).
If the instrument description compilation fails, check that the keywords syntax is correct, that no semi-colon (;) sign is missing (e.g. in C blocks and after an ABSORB macro), and there are no name conflicts between instrument and component instances variables.
