The standard layout

An instrument project is a directory containing:

  • A conda.yml file describing the conda environment (see The conda.yml file).

  • Exactly one of the following two directories:

    • instr/: classic McStas .instr files:

      • Exactly one PROJECT_main.instr.

      • Zero or more PROJECT_modeMODENAME.instr.

      • Optionally an includes/ subdirectory with *.h and *.c files, and a snippets/ subdirectory with *.instr files (for use via %include in the main and mode files).

      • Optionally localcomps/ and localdata/ subdirectories with project-specific components and data files (see Local components and data files).

      • No other files or subdirectories are allowed.

      • The instrument in each main and mode file must be named after the file, e.g. DEFINE INSTRUMENT ExInstrBasic_main(...) in ExInstrBasic_main.instr.

    • instrpy/: McStasScript python files:

      • An instrpy/pyproject.toml with a PEP 621 [project] table whose name matches PROJECT.

      • Nothing else is allowed directly in instrpy/, except for __pycache__/ and *.egg-info/ directories created by python tools.

      • An instrpy/PROJECT_instr/ python package with an empty __init__.py, exactly one PROJECT_main.py, and zero or more PROJECT_modeMODENAME.py. Each of these must provide a make() function returning a McStasScript instrument named after the file (e.g. ExPyGenerated_main).

      • Optionally helper modules MODULE.py in the same directory, for code shared between the main and mode files (imported with relative imports like from .common import build). MODULE must be a valid python identifier, and must not start with PROJECT_ (so misnamed mode files are not silently accepted as helper modules).

      • Optionally an includes/ subdirectory (inside the python package) with *.h and *.c files. No other files or subdirectories are allowed. The instruments must themselves make the C compiler find these files, since McStasScript writes and compiles the .instr file elsewhere (in its input_path directory). This can be done by adding the package directory to the include search path, as done in the code generated by generatepy:

        instr.add_include_dir(pathlib.Path(__file__).resolve().parent)
        

        The path must not contain whitespace.

      • Optionally localcomps/ and localdata/ subdirectories (inside the python package) with project-specific components and data files (see Local components and data files).

  • Optionally an extra/ directory with any other content of the project (e.g. notebooks, analysis code, scripts, unused components). There are no rules for its content.

  • Optionally an extra_pytests/ directory with tests, which are run with pytest by runci (see Tests in extra_pytests/). pytest must then be listed in conda.yml.

  • Optionally files named README*, LICENSE*, CHANGELOG* and CONTRIBUTING* (e.g. the contacts and contribution guidelines of the project), a TODO file (see The TODO file), and a citool.toml file with settings (see The citool.toml file).

  • Nothing else, apart from hidden files and directories (names starting with ., e.g. .gitignore and .gitlab-ci.yml).

Tests in extra_pytests/

runci copies extra_pytests/ to its output directory and runs pytest from within the copy (so relative paths in the tests work, and files written by the tests do not end up in the project). The python packages of the project are made available with PYTHONPATH, without installing anything: instrpy/ (for the instrpy layout), and extra/ and extra/src/ (if present), so e.g. an analysis package in extra/ can be used by the tests.

Local components and data files

Warning

Local components and data files exist to allow short-term workarounds and special needs. In general, components (and sometimes also data files) should instead be submitted upstream to McStas, at github.com/mccode-dev/McCode, so they are maintained, tested and available to everyone, and the local copies can be removed again.

Project-specific components and data files are placed in two subdirectories (of instr/, or of the python package instrpy/PROJECT_instr/):

  • localcomps/: components (*.comp), and C libraries used by them (*.c, *.h, e.g. included with %include "mylib" in a SHARE section). Local components must not have the same names as components in the McStas library, since they would shadow those (this is checked by runci).

  • localdata/: data files of the following types only: *.ncmat (NCrystal materials, preferred for samples), *.laz, *.lau, *.hkl, *.cif, *.rfl, *.trm, *.ref, *.sqw, *.dat, *.txt, *.off, *.ply, *.mcpl and *.mcpl.gz.

Neither may contain subdirectories. Files in localdata/ must not have the same names as data files of McStas (e.g. Al.laz) or materials of the NCrystal standard library (e.g. Al_sg225.ncmat), compared case-insensitively, since it would be easy to confuse them (this is checked by runci). The instruments refer to these files as follows:

  • For the instr layout, a SEARCH "localcomps" statement in the TRACE section lets McStas find the local components (and the C libraries they include), and data files are referred to as "localdata/<file>". Both are relative to the directory in which McStas is run, so the instruments must be compiled and run from within instr/ (as done by mctest and this tool). McStas components reading data with read_table-lib, and (since McStas 3.9.0) the NCrystal components, PowderN and Single_crystal also look relative to the .instr file.

  • For the instrpy layout, make() must make the files available, since McStasScript writes and runs the .instr file in its input_path directory. The local components are made available with instr.add_search(<absolute path of localcomps/>), and localdata/ is copied to the input_path directory, so data files can be referred to as "localdata/<file>" like for the instr layout. The code generated by generatepy does exactly this (it replaces the instr.add_search() calls for the SEARCH statements, which mcstas-pygen writes with absolute paths of the source project).

PROJECT must match [A-Za-z][A-Za-z0-9]* and MODENAME must match [A-Za-z][A-Za-z0-9]*. The mode names main and test are reserved, and mode names differing only in case are not allowed. Hidden files (names starting with .) and backup files (names ending with ~) are ignored.

Model checks

The modelcheck action (which is also part of runci) checks the instruments of all modes against the following rules, without compiling or running them:

  • parameter-defaults: all instrument parameters must have default values (so the instruments can run without specifying any parameters, e.g. in tests and when combined with other tools).

  • relative-references: AT and ROTATED of each component must be RELATIVE to a component defined earlier in the instrument (or ABSOLUTE or PREVIOUS).

For the instrpy layout, the rules are checked on the instrument object made by the make() function of each mode. For the instr layout, each .instr file is first processed by the McStas code generator, which reports errors in the instrument (e.g. a reference to an unknown component) and parameters without default values. The files are then translated with mcstas-pygen (as for generatepy), and the rules are checked on the resulting instrument objects. A string parameter without a default value is only reported as such from McStas 3.9.2. With older versions, the check reports that one of the string parameters with no default value or the default value "" is the problem.

The TODO file

The optional TODO file lists the open issues of the project, in a simple format which the tool checks, so the items can be counted (e.g. for the overview of the instrument repositories at DMSC):

  • First, optionally, a title and other text, in lines starting at the left margin (e.g. a title, a line of = below it, and an introduction).

  • Then the items, each starting with * at the left margin. The following lines of an item are indented with spaces, and may contain anything (e.g. lists). Blank lines are ignored.

  • After the first item, every line starting at the left margin must start a new item.

Example:

TODO items for the EXAMPLE model
================================

* The parameter documentation in the header of instr/EXAMPLE_main.instr is
  empty. Fill in the %parameters section, so that mcdoc shows them.

* Tests: only the monitors before the sample are tested. Consider:
  - a mode with a single crystal sample;
  - tests of the detectors.

The citool.toml file

The optional citool.toml file holds settings of the tool for the project, in TOML. The only setting is ncount, the number of neutrons of each %Example test in the full tests (runci), instead of the default of mctest (1e6). It is meant for models whose tests would otherwise take too long, and the expected values in the %Example lines must then be valid for that number of neutrons (within the 20% tolerance of mctest):

# Settings of mcstas-ess-instr-citool:
ncount = 1e4

The conda.yml file

The conda.yml file is parsed by a strict parser supporting only a small subset of YAML (top-level keys name, channels and dependencies, with an optional pip: subsection in the dependencies). Additionally:

  • The channels must be exactly conda-forge and nodefaults.

  • mcstas, python and pip must be listed as conda dependencies.

  • mcstas must have an explicit lower bound of at least 3.9.0 (e.g. mcstas >= 3.9.0).

  • Only lower bounds (>= or >) are allowed as version constraints. Exact versions, upper bounds etc. (including conda’s bare version syntax like numpy 1.26.*) are only allowed for packages on a hardwired allowlist (currently empty).

  • conda, conda-build, mamba and pip-tools are forbidden.

  • Packages in the pip: subsection must be on a hardwired allowlist (currently empty). Pip package names are compared after PEP 503 normalisation.

Example:

name: mcstas-environment

channels:
  - conda-forge
  - nodefaults

dependencies:
  - mcstas >= 3.9.0
  - python >= 3.12
  - pip
  - numpy >= 1.26