MMC v2025.10 command line help
###############################################################################
# Mesh-based Monte Carlo (MMC) - OpenCL #
# Copyright (c) 2010-2025 Qianqian Fang <q.fang at neu.edu> #
# https://mcx.space/#mmc & https://neurojson.io #
# #
#Computational Optics & Translational Imaging (COTI) Lab [http://fanglab.org]#
# Department of Bioengineering, Northeastern University, Boston, MA, USA #
###############################################################################
# The MCX Project is funded by the NIH/NIGMS under grant R01-GM114365 #
###############################################################################
# Open-source codes and reusable scientific data are essential for research, #
# MCX proudly developed human-readable JSON-based data formats for easy reuse.#
# #
#Please visit our free scientific data sharing portal at https://neurojson.io #
# and consider sharing your public datasets in standardized JSON/JData format #
###############################################################################
$Rev::c11362$v2025.10$Date::2025-10-12 00:12:27 -04$ by $Author::Qianqian Fang$
###############################################################################
usage: mmc <param1> <param2> ...
where possible parameters include (the first item in [] is the default value)
== Required option ==
-f config (--input) read an input file in the .json format,if config
string starts with '{',it is parsed as an inline
JSON input file; if -f is followed by nothing or
a single '-', it reads input from stdin via pipe
-Q benchmark (--bench) run a built-in benchmark, -Q only to list
-N benchmark (--net) get benchmark from NeuroJSON.io, -N only to list
benchmark can be dataset URL,or dbname/benchname
requires 'curl', install from https://curl.se/
== MC options ==
-n [0.|float] (--photon) total photon number, max allowed value is 2^32-1
-b [0|1] (--reflect) 1 do reflection at int&ext boundaries, 0 no ref.
-U [1|0] (--normalize) 1 to normalize the fluence to unitary,0 save raw
-m [0|1] (--mc) 0 use MCX-styled MC method, 1 use MCML style MC
-C [1|0] (--basisorder) 1 piece-wise-linear basis for fluence,0 constant
-u [1.|float] (--unitinmm) define the mesh data length unit in mm
-E [1648335518|int|mch](--seed) set random-number-generator seed;
if an mch file is followed, MMC "replays"
the detected photons; the replay mode can be used
to calculate the mua/mus Jacobian matrices
-P [0|int] (--replaydet) replay only the detected photons from a given
detector (det ID starts from 1), use with -E
-M [G|SG] (--method) choose ray-tracing algorithm (only use 1 letter)
P - Plucker-coordinate ray-tracing algorithm
H - Havel's SSE4 ray-tracing algorithm
B - partial Badouel's method (used by TIM-OS)
S - branch-less Badouel's method with SSE
G - dual-grid MMC (DMMC) with voxel data output
-e [1e-6|float](--minenergy) minimum energy level to trigger Russian roulette
-V [0|1] (--specular) 1 source located in the background,0 inside mesh
-k [1|0] (--voidtime) when src is outside, 1 enables timer inside void
== GPU options ==
-A [0|int] (--autopilot) auto thread config:1 enable;0 disable
-c [opencl,sse,cuda](--compute) select compute backend (default to opencl)
can also use 0: sse, 1: opencl, 2: cuda
-G [0|int] (--gpu) specify which GPU to use, list GPU by -L; 0 auto
or if set to -1, CPU-based SSE mmc will be used
-G '1101' (--gpu) using multiple devices (1 enable, 0 disable)
-W '50,30,20' (--workload) workload for active devices; normalized by sum
--atomic [1|0] 1 use atomic operations, 0 use non-atomic ones
== Output options ==
-s sessionid (--session) a string used to tag all output file names
-O [X|XFEJLP] (--outputtype) X - output flux, F - fluence, E - energy density
J - Jacobian, L - weighted path length, P -
weighted scattering count (J,L,P: replay mode)
-d [0|1] (--savedet) 1 to save photon info at detectors,0 not to save
-H [1000000] (--maxdetphoton) max number of detected photons
-S [1|0] (--save2pt) 1 to save the fluence field, 0 do not save
-x [0|1] (--saveexit) 1 to save photon exit positions and directions
setting -x to 1 also implies setting '-d' to 1
-X [0|1] (--saveref) save diffuse reflectance/transmittance on the
exterior surface. The output is stored in a
file named *_dref.dat, and the 2nd column of
the data is resized to [#Nf, #time_gate] where
#Nf is the number of triangles on the surface;
#time_gate is the number of total time gates.
To plot the surface diffuse reflectance, the
output triangle surface mesh can be extracted
by faces=faceneighbors(cfg.elem,'rowmajor');
where 'faceneighbors' is part of Iso2Mesh.
-q [0|1] (--saveseed) 1 save RNG seeds of detected photons for replay
-F [bin|...] (--outputformat) 'ascii', 'bin' (in 'double'), 'mc2' (double)
'hdr' (Analyze) or 'nii' (nifti, double)
mc2 - MCX mc2 format (binary 64bit float)
jnii - JNIfTI format (https://neurojson.org)
bnii - Binary JNIfTI (https://neurojson.org)
nii - NIfTI format
hdr - Analyze 7.5 hdr/img format
the bnii/jnii formats support compression (-Z) and generate small files
load jnii (JSON) and bnii (UBJSON) files using below lightweight libs:
MATLAB/Octave: JNIfTI toolbox https://github.com/NeuroJSON/jnifti,
MATLAB/Octave: JSONLab toolbox https://github.com/fangq/jsonlab,
Python: PyJData: https://pypi.org/project/jdata
JavaScript: JSData: https://github.com/NeuroJSON/jsdata
-Z [zlib|...] (--zip) set compression method if -F jnii or --dumpjson
is used (when saving data to JSON/JNIfTI format)
0 zlib: zip format (moderate compression,fast)
1 gzip: gzip format (compatible with *.gz)
2 base64: base64 encoding with no compression
3 lzip: lzip format (high compression,very slow)
4 lzma: lzma format (high compression,very slow)
5 lz4: LZ4 format (low compression,extrem. fast)
6 lz4hc: LZ4HC format (moderate compression,fast)
--dumpjson [-,2,'file.json'] export all settings, including volume data using
JSON/JData (https://neurojson.org) format for
easy sharing; can be reused using -f
if followed by nothing or '-', mmc will print
the JSON to the console; write to a file if file
name is specified; by default, prints settings
after pre-processing; '--dumpjson 2' prints
raw inputs before pre-processing
== User IO options ==
-h (--help) print this message
-v (--version) print MMC version information
-l (--log) print messages to a log file instead
-i (--interactive) interactive mode
== Debug options ==
-D [0|int] (--debug) print debug information (you can use an integer
or or a string by combining the following flags)
-D [''|SCBWDIOXATRPEM] 1 S photon movement info
2 C print ray-polygon testing details
4 B print Bary-centric coordinates
8 W print photon weight changes
16 D print distances
32 I entering a triangle
64 O exiting a triangle
128 X hitting an edge
256 A accumulating weights to the mesh
512 T timing information
1024 R debugging reflection
2048 P show progress bar
4096 E exit photon info
8192 M return photon trajectories
combine multiple items by using a string, or add selected numbers together
--debugphoton [-1|int] to print the debug info specified by -D only for
a single photon, followed by its index (start 0)
== Additional options ==
--momentum [0|1] 1 to save photon momentum transfer,0 not to save
--gridsize [1|float] if -M G is used, this sets the grid size in mm
--maxjumpdebug [10000000|int] when trajectory is requested (i.e. -D S),
use this parameter to set the maximum positions
stored (default: 1e7)
== Example ==
example: (list built-in benchmarks: -Q/--bench)
mmc -Q
or (use multiple devices - 1st,2nd and 4th GPUs - together with equal load)
mmc -Q dmmc-cube60 -n 1e7 -G 1101 -W 10,10,10
or (use inline json setting modifier)
mmc -f input.json -j '{"Optode":{"Source":{"Type":"isotropic"}}}'
or (dump simulation in a single json file)
mmc -Q dmmc-cube60 --dumpjson
or (use -N/--net to browse community-contributed mmc simulations at https://neurojson.io)
mmc -N
or (run user-shared mmc simulations, see full list at https://neurojson.org/db/mmc)
mmc -N dmmc-cube60
or (use -f - to read piped input file modified by shell text processing utilities)
mmc -Q dmmc-cube60 --dumpjson | sed -e 's/pencil/isotropic/g' | mmc -f -
or (download/modify simulations from NeuroJSON.io and run with mmc -f)
curl -s -X GET https://neurojson.io:7777/mmc/dmmc-cube60 | jq '.Forward.Dt = 1e-9' | mmc -f
![[Home]](/img/mcx_wiki_banner.png)