CLI Reference¶

mccode-antlr installs eight command-line programs.

Instrument translation¶

Translate a McCode .instr file to C source code.

mcstas-antlr [OPTIONS] INSTR_FILE

mcxtrace-antlr [OPTIONS] INSTR_FILE

Run commands¶

Compile and run an instrument simulation.

mcrun-antlr [OPTIONS] INSTR_FILE [PARAM=VALUE(S) ...]

mxrun-antlr [OPTIONS] INSTR_FILE [PARAM=VALUE(S) ...]

Seeing the simulation's output¶

A running simulation writes its progress, detector summaries and any component warnings to its own stdout. --capture decides where that goes:

tee writes one log per scan point, beside that point's mccode.sim. It is the one to reach for under MPI, where the ranks' output interleaves on screen and is easier to read afterwards than live.

--capture=no also keeps memory flat: yes and the old behaviour hold the whole run's output in RAM until it finishes.

--capture=tui¶

tui pins a small live summary to the terminal — how many scan points are done, how far the current one has got, its parameter values, the most recent detector result, and any errors — and erases it when the scan ends, leaving you looking at your own last command instead of at thousands of lines of output. The output itself is not discarded; it is written per point exactly as tee writes it.

The per-point percentage comes from the Progress_bar component, which prints it only when the instrument has one, and only every percent of the way (10 by default, and coarser still for small -n). Without it the point bar stays indeterminate rather than inventing progress; add Progress_bar(percent=1) to the instrument for a smoother one.

tui falls back to tee wherever a live display would be useless or in the way: a pipe, a CI log, a terminal that cannot handle it, or --dryrun. Since the log is written either way, nothing is lost in the fallback.

Tracing¶

-t/--trace is off by default. It is a debugging aid: the binary reports every particle's state at every component, which for a real instrument is kilobytes of output per particle. Under MPI every rank's share of that is funnelled through the launcher and captured by mcrun-antlr, which on a chopper instrument at -n 3e5 costs around 90x the untraced runtime.

Because the flag also controls whether trace support is compiled in, switching it on for an instrument that was already built without it recompiles the binary.

Choosing a parallelism target¶

When mcrun-antlr is given an already-compiled binary, --parallel and --gpu are three-valued. Left out, the binary's own build information decides — so running an MPI binary launches it under mpirun without being told to. Given explicitly, they are never silently overridden:

• --parallel on a binary built without MPI is an error, rather than an mpirun invocation that would start N independent full-ncount runs racing on one output directory.
• --no-parallel on an MPI binary warns and runs it as a single process.

When the binary carries no build information and none can be inferred, the flag as given is used.

--mpi decides how many processes to ask for. The default, auto, names no number at all: mpirun — or the batch scheduler that started it — chooses, which is what you want inside a job allocation. On Windows, where mpiexec has no sensible default, auto resolves to the CPU count. Give an integer to pin it.

Parameter syntax¶

Each instrument parameter is given as PARAM=VALUE(S) after the filename. The value determines whether this parameter is held constant or scanned:

1-D scan (default): all ranged parameters must have the same number of points and are stepped together in lock-step. Scalar parameters keep their fixed value at every step.

mcrun-antlr my.instr -n 1e6 a=1.0 b=10:20 c=100:10:200
#                              ^fixed  ^11pts   ^11pts — stepped together

N-D mesh scan (-m / --mesh): all ranged parameters are combined as a full Cartesian product. A scan with lengths [P, Q, R] runs P × Q × R simulations.

mcrun-antlr my.instr -n 1e6 -m E_i=1:2:5 angle=0:5:90
#                                 ^3pts      ^19pts → 57 simulations total

Compile-only commands¶

Compile a McCode instrument to a binary without running it.

mcc-antlr [OPTIONS] FILENAME

mxc-antlr [OPTIONS] FILENAME

Accepts .instr, .json, or pre-generated .c files.

Format command¶

mcfmt¶

Format .instr and .comp McCode DSL source files in canonical style.

mcfmt [OPTIONS] FILE [FILE ...]

The output mode flags (-i, --check, --diff) are mutually exclusive; the default (none given) prints formatted output to stdout.

Management command¶

mccode-antlr¶

Top-level management utility for caches, configuration, and data files.

mccode-antlr SUBCOMMAND [OPTIONS]

mccode-antlr cache¶

cache populate options:

cache register options:

cache build options:

cache build parses only files already on disk; run cache populate first. It always warms the C typedef cache. It writes component IR sidecars (*.comp.<build>.json) only when the cache.component_ir configuration value is true, e.g. MCCODEANTLR_CACHE__COMPONENT_IR=true. They are off by default; turn them on for a prebuilt, shared or read-only cache.

mccode-antlr config¶

mccode-antlr datafile¶

Run mccode-antlr SUBCOMMAND ACTION -h for the full option list of any individual action.

mccode-antlr convert¶

Convert between serialized instrument formats and generated Python assembler scripts.

mccode-antlr convert INPUT [-o OUTPUT] [--to {python,json,instr}] [--flavor {mcstas,mcxtrace}] [-I DIR ...]

mccode-antlr extract¶

Reconstitute a portable instrument into a directory: the .instr file (and any %include-d instruments, per the include hierarchy), every stashed/embedded local file, and the component (.comp) definitions it needs. Everything is written flat into one directory — no subfolders — so the result can be translated or compiled from inside that directory with no -I/--search-dir needed.

By default, only component definitions and dependency files not otherwise available from a remote registry are written (a component shipped with mcstas/mcxtrace, for example, is skipped since it's already fetchable by name elsewhere). Pass --include-remote for a fully self-contained bundle that also reconstructs those.

unzip-like selection is also available: pass one or more MEMBER glob patterns to extract only matching files (naming a remote-sourced file this way extracts it even without --include-remote, since asking for it by name is unambiguous), -x/--exclude to omit matches from whatever set would otherwise be written, and -l/--list to preview — without writing anything — exactly what a given invocation (same MEMBER/-x/--include-remote) would produce.

mccode-antlr extract INPUT [MEMBER ...] [-o OUTPUT_DIR] [--flavor {mcstas,mcxtrace}] [-I DIR ...] [--include-remote] [-x PATTERN ...] [-l]

Examples:

# See what a plain extract would produce, without writing anything
mccode-antlr extract my.instr --list

# Pull just one component definition out of a bundle
mccode-antlr extract my.instr Progress_bar.comp -o ./just-progress-bar

# Fully self-contained bundle, but skip the C source files
mccode-antlr extract my.instr --include-remote -x '*.c'