############################################################################### # Mesh-based Monte Carlo (MMC) - OpenCL # # Copyright (c) 2010-2020 Qianqian Fang <q.fang at neu.edu> # # http://mcx.space/#mmc # # # #Computational Optics & Translational Imaging (COTI) Lab [http://fanglab.org]# # Department of Bioengineering, Northeastern University, Boston, MA, USA # # # # Research funded by NIH/NIGMS grant R01-GM114365 # ############################################################################### $Rev::c49ec0$ v2020 $Date::2020-08-30 04:36:17 +01$ 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 .inp or .json format == 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 -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 format (--outputformat)'ascii', 'bin' (in 'double'), 'mc2' (double) 'hdr' (Analyze) or 'nii' (nifti, double) 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 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 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 [''|MCBWDIOXATRPE] 1 M 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 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 == Example == mmc -n 1000000 -f input.json -s test -b 0 -D TP -G -1