mcRUN(1)

📦
version 3.5+3.5.19 · 2 versions
, in debian trixie, ubuntu questing, ubuntu resolute

🦋 mcRUN, the manual page (but make it cute) ✨

okay bestie, welcome to mcRUN(1) — that's the manual name right there, we're just folding it in at the top like a little name tag 🎀. This is the whole page, every last flag, no skips, no cap.

NAME 💖

mcrun — running mcstas simulations from the command-line 🌈

SYNOPSIS 🧚

mcrun [-cpnN] INSTR [-sndftgahi] params={val|min,max|min,guess,max}...
[-hB][-c CMD][-f FROM][-n NAME][-o DIR][-s SCRIPT]

like, look at her. the way she has so many letters. iconic. 👑

DESCRIPTION 🌸

So the mcrun front-end is your little bestie that gives you a convenient command-line interface for running simulations with the same automatic compilation features. She doesn't just run stuff either — she also hands you a facility for running a series of simulations while varying an input parameter, plus a multiparameter non-linear optimisation. obsessed. 😌

The command mcrun sim args ... will compile the instrument definition INSTR — like sim.instr for example — (if necessary, bestie, only if necessary) into an executable simulation sim.out. Then she runs sim.out, passing along the argument list args, which is usually a whole lil series of param=value pairs. 💅

And if you ever forget all this? The -h option will list valid options. she's got you fr fr.

OPTIONS ✨

  • --version — show the program's version number and then dip out. bye! 👋
  • -h, --help — show this help message and exit 🫶
  • -c, --force-compile — force a rebuild of the instrument. You might need this if any component definitions changed (because in that case mcrun does not automatically recompile, and she will simply not know), or if a new version of mcstas has been installed. rude but valid.
  • -I I — append path I to the McCode search path. this one implies -c btw 💅
  • --D1=D1 — set extra -D args. implies -c ✨
  • --D2=D2 — set extra -D args. implies -c ✨
  • --D3=D3 — set extra -D args. implies -c ✨
  • -p FILE, --param=FILE — read parameters from file FILE. That file should consist of specifications of the form name =value, separated by spaces or line breaks. You can give multiple -p options together with direct parameter specifications on the command line, no gatekeeping. And if a parameter gets assigned multiple times, later assignments override previous ones — last one in wins, periodt.
  • -N NP, --numpoints=NP — set the number of scan points, varying one or more parameters within specified intervals. A series of simulations like this is called a scan. To specify an interval for a parameter X, you assign it two values separated by a comma. For example, the command mcrun sim.instr -N4 X=2,8 Y=1 would run the simulation defined in sim.instr four times, with X having the values 2, 4, 6, and 8, respectively. After running, results get written to the file mccode.dat by default. That file has one line for each simulation run, giving the values of the scanned input variables along with the integrated intensity and estimated error in all monitors. so much data. so pretty. 📊
  • -L, --list — use a fixed list of points for linear scanning 📋
  • -M, --multi — run a multi-dimensional scan 🌀
  • --autoplot — open plotter on the generated dataset 🎨
  • --autoplotter=AUTOPLOTTER — specify the plotter used with --autoplot 💅
  • --embed — store a copy of the instrument file in the output directory 📦
  • --mpi=NB_CPU — spread the simulation over NB_CPU machines using MPI 🌐
  • --openacc — parallelize using openacc ⚡
  • --funnel — funneling simulation flow, e.g. for mixed CPU/GPU 🕳️
  • --machines=machines — defines path of MPI machinefile to use in parallel mode 🖥️
  • --optimise-file=FILE — store scan results in FILE (defaults to: mccode.dat) 💾
  • --no-cflags — disable optimising compiler flags for faster compilation 🏃
  • --no-main — do not generate a main(), e.g. for use with mcstas2vitess.pl. Implies -c 🚫
  • --verbose — enable verbose output 🗣️
  • --write-user-config — generate a user config file 📝
  • --override-config=PATH — load config file from a specific dir 🔀
  • --optimize — optimize instrument variable parameters to maximize monitors 📈
  • --optimize-maxiter=optimize_maxiter — maximum number of optimization iterations to perform 🔁
  • --optimize-tol=optimize_tol — tolerance for optimization termination. When optimize_tol is specified, the selected optimization algorithm sets some relevant solver-specific tolerance(s) equal to optimize-tol. the algorithm is doing its best okay 😭
  • --optimize-method=optimize_method — optimization solver in ['powell', 'nelder-mead', 'cg', 'bfgs', 'newton-cg', 'l-bfgs-b', 'tnc', 'cobyla', 'slsqp', 'trust-constr', 'dogleg', 'trust-ncg', 'trust-exact', 'trust-krylov'] (default: powell). You can use your custom method method(fun, x0, args, **kwargs, **options). Please refer to scipy documentation for proper use of it: https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html?highlight=minimize 📚
  • --optimize-minimize — choose to minimize the monitors instead of maximize 🔽
  • --optimize-monitor=optimize_monitor — name of a single monitor to optimize (default is to use all) 👀
  • --showcfg=ITEM — print selected cfg item and exit (paths are resolved and absolute). Allowed values are "bindir", "libdir", "resourcedir", and "tooldir" 🗂️

INSTRUMENT OPTIONS 🎀

  • -s SEED, --seed=SEED — set random seed (must be: SEED != 0). no zero, bestie, she said what she said 🚫
  • -n COUNT, --ncount=COUNT — set number of neutron to simulate 🔬
  • -t trace, --trace=trace — enable trace of neutron through instrument 👣
  • -d DIR, --dir=DIR — put all data files in directory DIR. Additionally, the directory will have subdirectories 1, 2, 3, . . . containing all data files output from the different simulations. nested folders, we love an organised queen 📁
  • --format=FORMAT — output data files using format FORMAT, usually McCode or NeXus (format list obtained from .out -h) 🧾
  • --bufsiz=BUFSIZ — Monitor_nD list/buffer-size (defaults to 1000000) 🧮
  • --vecsize=VECSIZE — vector length in OpenACC parallel scenarios 🧵
  • --numgangs=NUMGANGS — number of gangs in OpenACC parallel scenarios 🚗
  • --gpu_innerloop=INNERLOOP — maximum particles in an OpenACC kernel run. (If INNERLOOP is smaller than ncount we repeat) 🔄
  • --no-output-files — do not write any data files 🚫📄
  • -i, --info — detailed instrument information ℹ️
  • --list-parameters — print the instrument parameters to standard out 🖨️
  • --meta-list — print all metadata defining component names 🏷️
  • --meta-defined=META_DEFINED — print metadata names for component, or indicate if component:name exists 🔍
  • --meta-type=META_TYPE — print metadata type for component:name 🔤
  • --meta-data=META_DATA — print metadata for component:name 📦

FILES 🗃️

  • /usr/share/mcstas/resources
  • /usr/share/mcstas/tools/Python/mccodelib/mccode_config.json
  • ~/.mcstas/mccode_config.json
  • http://www.mcstas.org

the whole file family tree, slay 🌳

EXAMPLES 🌟

Run the Test_SX example (Single crystal diffraction) 💎

  • mcrun Test_SX.instr -d output_dir -n 1e7 TTH=13.4

look at that. one line. ate. 🔥

AUTHORS 🫶

mcstas Team (mcstas.org)

SEE ALSO 🌈

mcstas(1), mcdoc(1), mcplot(1), mcrun(1), mcgui(1), mcdisplay(1)

(she's in her own SEE ALSO list btw. main character energy, honestly 💅)

AUTHORS (yes, again) 👑

MCSTAS neutron Ray Tracing Team.

and that's the whole page, bestie 💖 this one came out of the git source with the mcRUN(1) footer tag on the bottom, so that's the version and the page identity right there — no date on this one, she's timeless like that. go run some simulations, you're gonna do great. periodt ✨🦋🎀

📦 where this page comes from