The standard layout
An instrument project is a directory containing:
A
conda.ymlfile describing the conda environment (see The conda.yml file).Exactly one of the following two directories:
instr/: classic McStas.instrfiles:Exactly one
PROJECT_main.instr.Zero or more
PROJECT_modeMODENAME.instr.Optionally an
includes/subdirectory with*.hand*.cfiles, and asnippets/subdirectory with*.instrfiles (for use via%includein the main and mode files).Optionally
localcomps/andlocaldata/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(...)inExInstrBasic_main.instr.
instrpy/: McStasScript python files:An
instrpy/pyproject.tomlwith a PEP 621[project]table whosenamematchesPROJECT.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 onePROJECT_main.py, and zero or morePROJECT_modeMODENAME.py. Each of these must provide amake()function returning a McStasScript instrument named after the file (e.g.ExPyGenerated_main).Optionally helper modules
MODULE.pyin the same directory, for code shared between the main and mode files (imported with relative imports likefrom .common import build).MODULEmust be a valid python identifier, and must not start withPROJECT_(so misnamed mode files are not silently accepted as helper modules).Optionally an
includes/subdirectory (inside the python package) with*.hand*.cfiles. No other files or subdirectories are allowed. The instruments must themselves make the C compiler find these files, since McStasScript writes and compiles the.instrfile elsewhere (in itsinput_pathdirectory). This can be done by adding the package directory to the include search path, as done in the code generated bygeneratepy:instr.add_include_dir(pathlib.Path(__file__).resolve().parent)
The path must not contain whitespace.
Optionally
localcomps/andlocaldata/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 withpytestbyrunci(see Tests in extra_pytests/).pytestmust then be listed inconda.yml.Optionally files named
README*,LICENSE*,CHANGELOG*andCONTRIBUTING*(e.g. the contacts and contribution guidelines of the project), aTODOfile (see The TODO file), and acitool.tomlfile with settings (see The citool.toml file).Nothing else, apart from hidden files and directories (names starting with
., e.g..gitignoreand.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 aSHAREsection). Local components must not have the same names as components in the McStas library, since they would shadow those (this is checked byrunci).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,*.mcpland*.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
instrlayout, aSEARCH "localcomps"statement in theTRACEsection 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 withininstr/(as done bymctestand this tool). McStas components reading data withread_table-lib, and (since McStas 3.9.0) the NCrystal components,PowderNandSingle_crystalalso look relative to the.instrfile.For the
instrpylayout,make()must make the files available, since McStasScript writes and runs the.instrfile in itsinput_pathdirectory. The local components are made available withinstr.add_search(<absolute path of localcomps/>), andlocaldata/is copied to theinput_pathdirectory, so data files can be referred to as"localdata/<file>"like for theinstrlayout. The code generated bygeneratepydoes exactly this (it replaces theinstr.add_search()calls for theSEARCHstatements, whichmcstas-pygenwrites 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:ATandROTATEDof each component must beRELATIVEto a component defined earlier in the instrument (orABSOLUTEorPREVIOUS).
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-forgeandnodefaults.mcstas,pythonandpipmust be listed as conda dependencies.mcstasmust 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 likenumpy 1.26.*) are only allowed for packages on a hardwired allowlist (currently empty).conda,conda-build,mambaandpip-toolsare 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