![[Home]](/img/mcx_wiki_banner.png)
Appendix A - Command line options
The below section provides full lists to the version 2020 of mcx and mcxcl binaries. One can obtain these outputs via the command mcx --help or mcxcl --help.
mcx command full option list
###############################################################################
# Monte Carlo eXtreme (MCX) -- CUDA #
# Copyright (c) 2009-2020 Qianqian Fang <q.fang at neu.edu> #
# http://mcx.space/ #
# #
# Computational Optics & Translational Imaging (COTI) Lab- http://fanglab.org #
# Department of Bioengineering, Northeastern University #
###############################################################################
# The MCX Project is funded by the NIH/NIGMS under grant R01-GM114365 #
###############################################################################
$Rev::fb2cc8$2020.4 $Date::2020-04-06 13:30:09 -04$ by $Author::Qianqian Fang $
###############################################################################
usage: mcx <param1> <param2> ...
where possible parameters include (the first value in [*|*] is the default)
== Required option ==
-f config (--input) read an input file in .json or .inp format
--bench ['cube60','skinvessel',..] run a buint-in benchmark specified by name
run --bench without parameter to get a list
== MC options ==
-n [0|int] (--photon) total photon number (exponential form accepted)
max accepted value:9.2234e+18 on 64bit systems
-r [1|+/-int] (--repeat) if positive, repeat by r times,total= #photon*r
if negative, divide #photon into r subsets
-b [1|0] (--reflect) 1 to reflect photons at ext. boundary;0 to exit
-B '______' (--bc) per-face boundary condition (BC), 6 letters for
/case insensitive/ bounding box faces at -x,-y,-z,+x,+y,+z axes;
overwrite -b if given.
each letter can be one of the following:
'_': undefined, fallback to -b
'r': like -b 1, Fresnel reflection BC
'a': like -b 0, total absorption BC
'm': mirror or total reflection BC
'c': cyclic BC, enter from opposite face
-u [1.|float] (--unitinmm) defines the length unit for the grid edge
-U [1|0] (--normalize) 1 to normalize flux to unitary; 0 save raw
-E [0|int|mch](--seed) set random-number-generator seed, -1 to generate
if an mch file is followed, MCX "replays"
the detected photon; the replay mode can be used
to calculate the mua/mus Jacobian matrices
-z [0|1] (--srcfrom0) 1 volume origin is [0 0 0]; 0: origin at [1 1 1]
-R [-2|float] (--skipradius) -2: use atomics for the entire domain (default)
0: vanilla MCX, no atomic operations
>0: radius in which use shared-memory atomics
-1: use crop0/crop1 to determine atomic zone
-k [1|0] (--voidtime) when src is outside, 1 enables timer inside void
-Y [0|int] (--replaydet) replay only the detected photons from a given
detector (det ID starts from 1), used with -E
if 0, replay all detectors and sum all Jacobians
if -1, replay all detectors and save separately
-V [0|1] (--specular) 1 source located in the background,0 inside mesh
-e [0.|float] (--minenergy) minimum energy level to terminate a photon
-g [1|int] (--gategroup) number of time gates per run
== GPU options ==
-L (--listgpu) print GPU information only
-t [16384|int](--thread) total thread number
-T [64|int] (--blocksize) thread number per block
-A [1|int] (--autopilot) 1 let mcx decide thread/block size, 0 use -T/-t
-G [0|int] (--gpu) specify which GPU to use, list GPU by -L; 0 auto
or
-G '1101' (--gpu) using multiple devices (1 enable, 0 disable)
-W '50,30,20' (--workload) workload for active devices; normalized by sum
-I (--printgpu) print GPU information and run program
== Input options ==
-P '{...}' (--shapes) a JSON string for additional shapes in the grid
-K [1|int|str](--mediabyte) volume data format, use either a number or a str
1 or byte: 0-128 tissue labels
2 or short: 0-65535 (max to 4000) tissue labels
4 or integer: integer tissue labels
100 or muamus_float: 2x 32bit floats for mua/mus
101 or mua_float: 1 float per voxel for mua
102 or muamus_half: 2x 16bit float for mua/mus
103 or asgn_byte: 4x byte gray-levels for mua/s/g/n
104 or muamus_short: 2x short gray-levels for mua/s
-a [0|1] (--array) 1 for C array (row-major); 0 for Matlab array
== Output options ==
-s sessionid (--session) a string to label all output file names
-O [X|XFEJPM] (--outputtype) X - output flux, F - fluence, E - energy density
/case insensitive/ J - Jacobian (replay mode), P - scattering,
event counts at each voxel (replay mode only)
M - momentum transfer;
-d [1|0] (--savedet) 1 to save photon info at detectors; 0 not save
-w [DP|DSPMXVW](--savedetflag)a string controlling detected photon data fields
/case insensitive/ 1 D output detector ID (1)
2 S output partial scat. even counts (#media)
4 P output partial path-lengths (#media)
8 M output momentum transfer (#media)
16 X output exit position (3)
32 V output exit direction (3)
64 W output initial weight (1)
combine multiple items by using a string, or add selected numbers together
by default, mcx only saves detector ID and partial-path data
-x [0|1] (--saveexit) 1 to save photon exit positions and directions
setting -x to 1 also implies setting '-d' to 1.
same as adding 'XV' to -w.
-X [0|1] (--saveref) 1 to save diffuse reflectance at the air-voxels
right outside of the domain; if non-zero voxels
appear at the boundary, pad 0s before using -X
-m [0|1] (--momentum) 1 to save photon momentum transfer,0 not to save.
same as adding 'M' to the -w flag
-q [0|1] (--saveseed) 1 to save photon RNG seed for replay; 0 not save
-M [0|1] (--dumpmask) 1 to dump detector volume masks; 0 do not save
-H [1000000] (--maxdetphoton) max number of detected photons
-S [1|0] (--save2pt) 1 to save the flux field; 0 do not save
-F [mc2|...] (--outputformat) fluence data output format:
mc2 - MCX mc2 format (binary 32bit float)
jnii - JNIfTI format (http://openjdata.org)
bnii - Binary JNIfTI (http://openjdata.org)
nii - NIfTI format
hdr - Analyze 7.5 hdr/img format
tx3 - GL texture data for rendering (GL_RGBA32F)
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/fangq/jnifti,
MATLAB/Octave: JSONLab toolbox https://github.com/fangq/jsonlab,
Python: PyJData: https://pypi.org/project/jdata
JavaScript: JSData: https://github.com/fangq/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 (http://openjdata.org) format for
easy sharing; can be reused using -f
if followed by nothing or '-', mcx 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 MCX revision number
-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 [''|RMP] 1 R debug RNG
/case insensitive/ 2 M store photon trajectory info
4 P print progress bar
combine multiple items by using a string, or add selected numbers together
== Additional options ==
--root [''|string] full path to the folder storing the input files
--gscatter [1e9|int] after a photon completes the specified number of
scattering events, mcx then ignores anisotropy g
and only performs isotropic scattering for speed
--internalsrc [0|1] set to 1 to skip entry search to speedup launch
--maxvoidstep [1000|int] maximum distance (in voxel unit) of a photon that
can travel before entering the domain, if
launched outside (i.e. a widefield source)
--maxjumpdebug [10000000|int] when trajectory is requested (i.e. -D M),
use this parameter to set the maximum positions
stored (default: 1e7)
--faststep [0|1] 1-use fast 1mm stepping, [0]-precise ray-tracing
== Example ==
example: (autopilot mode)
mcx -A 1 -n 1e7 -f input.inp -G 1 -D P
or (manual mode)
mcx -t 16384 -T 64 -n 1e7 -f input.inp -s test -r 2 -g 10 -d 1 -w dpx -b 1 -G 1
or (use multiple devices - 1st,2nd and 4th GPUs - together with equal load)
mcx -A -n 1e7 -f input.inp -G 1101 -W 10,10,10
or (use inline domain definition)
mcx -f input.json -P '{"Shapes":[{"ZLayers":[[1,10,1],[11,30,2],[31,60,3]]}]}'