Installation and usage
Install the tool with pip (Python 3.11 or newer), e.g. directly from GitHub:
pip install git+https://github.com/mccode-dev/mcstas-ess-instr-citool.git
or with pip install -e . from a clone of the repository.
mcstas-ess-instr-citool --version shows the installed version (see
Versions and releases). The generate,
generatepy, modelcheck and runci actions need McStas 3.9.0 or newer
(with McStasScript 0.0.94 or newer), for example from a conda environment
created with:
conda create -n mcstas -c conda-forge --override-channels "mcstas>=3.9.0" "mcstasscript>=0.0.94"
Usage (see also the Command line reference):
mcstas-ess-instr-citool [-a ACTION] [-o OUTDIR] [--mpi N] [--lenient] [--errtrace] PROJECT_DIR
All actions first validate the project layout and the conda.yml file,
failing with an error message on any violation. Available actions:
list(default): print a human-readable summary of the project.check: only validate the project.json,pprint: print the extracted project information as JSON or as a pretty-printed python dictionary.generate: generateOUTDIR/instr/MODE/for each mode (withMAINfor the main instrument). For theinstrlayout, the.instrfile and anyincludes/,snippets/,localcomps/andlocaldata/files are copied. For theinstrpylayout, eachmake()function is called in a separate process (with a timeout of 600 seconds) and must write exactly one.instrfile (and may createlocaldata/next to it). Theincludes/,localcomps/andlocaldata/files are not copied, sincemake()must make them available itself (see The standard layout).generatepy: generate a completeinstrpyproject inOUTDIR(-ois required), withconda.yml,instrpy/pyproject.tomland the python package. For aninstrpyproject, the files are simply copied. For aninstrproject, each.instrfile is translated withmcstas-pygen(snippets/are thereby included, andincludes/,localcomps/andlocaldata/files are copied into the package, with code making them available to the instrument). The instrument is named after the file,%Examplelines are translated into McStasScript tests (instr.add_test), and dates and local paths are removed from the output, so it is reproducible. The generatedmake()writes the instrument into McStasScript’s defaultinput_path(the working directory), not into the python package.modelcheck: check the instruments against the rules for the models, e.g. that all instrument parameters have default values (see Model checks).repos,repos-json: list the instrument repositories at DMSC (see Instrument repositories at DMSC), as a table or as JSON. These actions take noPROJECT_DIR.runci: check that local components do not shadow McStas components, and that local data files do not have the names of McStas data files or NCrystal standard library materials, then run the model checks (asmodelcheck),generate, andmctest --strict --localon the result. With--strict, each instrument must have at least one%Exampleline, and all examples must pass.--noplotsis also given, somctestdoes not plot the output of the tests, which can take much longer than the tests for instruments with many monitors. The%Exampletests run with the default number of neutrons ofmctest(1e6), unlessncountis set in thecitool.tomlfile of the project. Finally, if the project has anextra_pytests/directory, the tests in it are run withpytest(see Tests in extra_pytests/). With--mpi N(or--mpi autofor the number of available processors), the instruments are compiled and run with MPI, using N processes. This tests that the instruments work with MPI. It does not necessarily make the tests faster, since compilation with MPI takes longer, and the defaultmctestsimulations are short.runcifast: a quicker version ofrunci, for fast feedback while developing: the same checks, but each%Exampletest is run with only 100 neutrons, and only has to compile and run without crashing (its results are not compared with the expected values, which they will not match with fewer neutrons). The instruments are tested one at a time, stopping at the first failure, and the tests inextra_pytests/are not run.--mpican be used as forrunci.checkbuild: likeruncifast, but the instruments are only compiled, not run (with 0 neutrons).
If -o OUTDIR is not given (it must be empty or not exist), a temporary
directory is used and cleaned up afterwards.
With --lenient, unexpected files and directories in the project (which
the layout rules do not allow) are ignored with a warning, instead of
causing an error. They are also left out of the generated instruments (for
the instr layout). This is for testing a working copy locally, which may
contain temporary files, e.g. compiled instruments or simulation output.
The other rules still apply. --lenient is not allowed in CI (it is refused
when the CI environment variable is set, as it is in GitLab CI), since the
committed files must follow the layout.
Errors caused by the project or the environment, e.g. a violation of the
layout rules or a failed check, are reported as a message (starting with
ERROR:), with exit code 1. With --errtrace, the full Python traceback is
shown instead, e.g. for debugging the tool. Other errors are always shown
with a traceback.