{"id":17744072,"url":"https://github.com/fangq/mmc","last_synced_at":"2025-04-07T19:16:58.226Z","repository":{"id":26354469,"uuid":"29803464","full_name":"fangq/mmc","owner":"fangq","description":"Mesh-based Monte Carlo (MMC)","archived":false,"fork":false,"pushed_at":"2025-02-14T03:20:54.000Z","size":20580,"stargazers_count":40,"open_issues_count":7,"forks_count":33,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-02T02:31:27.800Z","etag":null,"topics":["biomedical-image-processing","matlab","monte-carlo","multi-threading","parallel-computing","photonics","transport"],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fangq.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog.txt","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.txt","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-01-25T05:05:52.000Z","updated_at":"2025-02-13T22:56:23.000Z","dependencies_parsed_at":"2024-04-25T17:53:53.275Z","dependency_job_id":"2f58123b-c130-4a52-b5ac-117712a1d548","html_url":"https://github.com/fangq/mmc","commit_stats":{"total_commits":1071,"total_committers":14,"mean_commits":76.5,"dds":"0.31092436974789917","last_synced_commit":"2886ba36e0f898630bf4bb89d07c70cbce86165a"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fangq%2Fmmc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fangq%2Fmmc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fangq%2Fmmc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fangq%2Fmmc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fangq","download_url":"https://codeload.github.com/fangq/mmc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247713258,"owners_count":20983683,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["biomedical-image-processing","matlab","monte-carlo","multi-threading","parallel-computing","photonics","transport"],"created_at":"2024-10-26T06:41:52.750Z","updated_at":"2025-04-07T19:16:58.200Z","avatar_url":"https://github.com/fangq.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"Mesh-based Monte Carlo (MMC) - SSE4 and OpenCL\n==============================================\n\n\n-   Author: Qianqian Fang (q.fang at neu.edu)\n-   License: GNU General Public License version 3 (GPL v3), see License.txt\n-   Version: 2.6.0 (v2025, Popcorn)\n-   URL: \u003chttps://mcx.space/mmc\u003e\n\n![Mex and Binaries](https://github.com/fangq/mcxcl/actions/workflows/build_all.yml/badge.svg)\n\nTable of Content:\n\n  * [What's New](#whats-new)\n  * [Introduction](#introduction)\n  * [Download and Compile MMC](#download-and-compile-mmc)\n  * [Running Simulations](#running-simulations)\n    + [Preparation](#preparation)\n    + [Command line options](#command-line-options)\n    + [Input files](#input-files)\n    + [JSON-formatted input files](#json-formatted-input-files)\n    + [Photon debugging information using -D flag](#photon-debugging-information-using--d-flag)\n    + [Plotting the Results](#plotting-the-results)\n  * [Known issues and TODOs](#known-issues-and-todos)\n  * [Getting Involved](#getting-involved)\n  * [Acknowledgement](#acknowledgement)\n    + [SSE Math library by Julien Pommier](#sse-math-library-by-julien-pommier)\n    + [cJSON library by Dave Gamble](#cjson-library-by-dave-gamble)\n    + [SFMT library by Mutsuo Saito, Makoto Matsumoto and Hiroshima University](#sfmt-library-by-mutsuo-saito--makoto-matsumoto-and-hiroshima-university)\n    + [drand48_r port for libgw32c by Free Software Foundation](#drand48-r-port-for-libgw32c-by-free-software-foundation)\n    + [git-rcs-keywords by Martin Turon (turon) at Github](#git-rcs-keywords-by-martin-turon--turon--at-github)\n  * [Reference](#reference)\n\n\nWhat's New\n-------------\n\nMMC v2025 (2.6.0) is a maintenance release with multiple bug fixes and new features. It is highly\nrecommended to upgrade for all users.\n\nMMC v2025 adds the below key features\n\n* add photon-sharing (multi-pattern simulations) in OpenCL/GPU\n* optimizing thread number on Apple silicon (M1/M2/M3/M4), gain 6x speedup\n* the new `-N/--net` command line flag allows one to browse and run growing number of community-contributed\n  simulations hosted on https://neurojson.io (one can browse the list at https://neurojson.org/db/mmc)\n* mmc can read stdin (standard input) using pipe, allow one to use advanced text processing utilities in the shell,\n  such as `sed, perl, jq` to modify JSON inputs at runtime. For example `mcx -N cube60 | jq '.Forward.Dt=1e-10' | mcx -f`\n* a new shortcut option `-Q` for `--bench` to conveniently browse and run built-in benchmarks\n* automatically compute initial element ID, facenb, element/nodal volume if not provided, greatly simplifying input data\n* speed up facenb computation by a factor of 2x\n* add `--dumpjson` flag to allow exporting simulations to a JSON file\n\nAside from these added new features, we have also fixed a number of bugs.\nWe want to particularly thank Andrea Farina (CNR-IFN) for reporting and fixing \na number of the below issues.\n\n* fix shared memory initialization error (#101, #103)\n* fix stdout not found error when building with `cudamex` target, fix various trinity/cuda compilation errors\n* fix replay error in trinity/cuda target (#98)\n* fix double-precision saving bug in jnii/bnii (#90)\n* disable SSE on arm64 Apple silicon as it is not supported\n* add the missing `-H/--maxdetphoton` flag\n\n\nIntroduction\n---------------\n\nMesh-based Monte Carlo (MMC) is a 3D Monte Carlo (MC) simulation software for \nphoton transport in complex turbid media. MMC combines the strengths of the \nMC-based technique and the finite-element (FE) method: on the one hand, it can \nhandle general media, including low-scattering ones, as in the MC method; on \nthe other hand, it can use an FE-like tetrahedral mesh to represent curved \nboundaries and complex structures, making it even more accurate, flexible, and \nmemory efficient. MMC uses the state-of-the-art ray-tracing techniques to \nsimulate photon propagation in a mesh space. It has been extensively optimized \nfor excellent computational efficiency and portability. MMC currently supports \nmulti-threaded parallel computing via OpenMP, Single Instruction Multiple Data \n(SIMD) parallelism via SSE and, starting from v2019.10, OpenCL to support a wide \nrange of CPUs/GPUs from nearly all vendors.\n\nTo run an MMC simulation, one has to prepare an FE mesh first to discretize the \nproblem domain. Image-based 3D mesh generation has been a very challenging task \nonly until recently. One can now use a powerful yet easy-to-use mesh generator, \niso2mesh [1], to make tetrahedral meshes directly from volumetric medical \nimages. You should download and install the latest iso2mesh toolbox in order to \nrun the build-in examples in MMC.\n\nWe are working on a massively-parallel version of MMC by porting this code to \nCUDA and OpenCL. This is expected to produce a hundred- or even thousand-fold \nacceleration in speed similar to what we have observed in our GPU-accelerated \nMonte Carlo software (Monte Carlo eXtreme, or MCX [2]).\n\nThe most relevant publication describing this work is the GPU-accelerated MMC \npaper:\n\n\u003e Qianqian Fang and Shijie Yan, “GPU-accelerated mesh-based Monte Carlo photon \ntransport simulations,” J. of Biomedical Optics, 24(11), 115002 (2019)\nURL: \u003chttp://dx.doi.org/10.1117/1.JBO.24.11.115002\u003e\n\nPlease keep in mind that MMC is only a partial implementation of the general \nMesh-based Monte Carlo Method (MMCM). The limitations and issues you observed \nin the current software will likely be removed in the future version of the \nsoftware. If you plan to perform comparison studies with other works, please \ncommunicate with the software author to make sure you have correctly understood \nthe details of the implementation.\n\nThe details of MMCM can be found in the following paper:\n\n\u003e Qianqian Fang, “Mesh-based Monte Carlo method using fast ray-tracing in \nPlücker coordinates,” Biomed. Opt. Express 1, 165-175 (2010) URL: \n\u003chttps://www.osapublishing.org/boe/abstract.cfm?uri=boe-1-1-165\u003e\n\nWhile the original MMC paper was based on the Plücker coordinates, a number of \nmore efficient SIMD-based ray-tracers, namely, Havel SSE4 ray-tracer, Badouel \nSSE ray-tracer and branchless-Badouel SSE ray-tracer (fastest) have been added \nsince 2011. These methods can be selected by the `-M` flag. The details of these \nmethods can be found in the below paper\n\n\u003e Qianqian Fang and David R. Kaeli, “Accelerating mesh-based Monte Carlo method \non modern CPU architectures,” Biomed. Opt. Express 3(12), 3223-3230 (2012) \nURL: \u003chttps://www.osapublishing.org/boe/abstract.cfm?uri=boe-3-12-3223\u003e\n\nand their key differences compared to another mesh-based MC simulator, TIM-OS, \nare discussed in\n\n\u003e Qianqian Fang, “Comment on 'A study on tetrahedron-based inhomogeneous \nMonte-Carlo optical simulation',” Biomed. Opt. Express, vol. 2(5) 1258-1264, (2011)\nURL: \u003chttps://www.osapublishing.org/boe/abstract.cfm?uri=boe-2-5-1258\u003e\n\nIn addition, the generalized MMC algorithm for wide-field sources and detectors \nare described in the following paper, and was made possible with the \ncollaboration with Ruoyang Yao and Prof. Xavier Intes from RPI\n\n\u003e Yao R, Intes X, Fang Q, “Generalized mesh-based Monte Carlo for wide-field \nillumination and detection via mesh retessellation,” Biomed. Optics Express, \n7(1), 171-184 (2016) URL: \n\u003chttps://www.osapublishing.org/boe/abstract.cfm?uri=boe-7-1-171\u003e\n\nIn addition, we have been developing a fast approach to build the Jacobian \nmatrix for solving inverse problems. The technique is called “photon \nreplay”, and is described in details in the below paper:\n\n\u003e Yao R, Intes X, Fang Q, “A direct approach to compute Jacobians for diffuse \noptical tomography using perturbation Monte Carlo-based photon 'replay',” \nBiomed. Optics Express, in press, (2018)\n\nIn 2019, we published an improved MMC algorithm, named “dual-grid MMC”, or \nDMMC, in the below JBO Letter. This method allows to use separate mesh for \nray-tracing and fluence storage, and can be 2 to 3 fold faster than the \noriginal MMC without loss of accuracy.\n\n\u003e Shijie Yan, Anh Phong Tran, Qianqian Fang, “A dual-grid mesh-based Monte \nCarlo algorithm for efficient photon1transport simulations in complex 3-D \nmedia,” J. of Biomedical Optics, 24(2), 020503 (2019).\n\nThe authors of the papers are greatly appreciated if you can cite the above \npapers as references if you use MMC and related software in your publication.\n\n\nDownload and Compile MMC\n---------------------------\n\nThe latest release of MMC can be downloaded from the following URL:\n\n\u003chttp://mcx.space/#mmc\u003e\n\nThe development branch (not fully tested) of the code can be accessed using \nGit. However this is not encouraged unless you are a developer. To check out \nthe Git source code, you should use the following command:\n\n      git clone https://github.com/fangq/mmc.git\n\nTo compile the software, you need to install GNU gcc compiler toolchain on your \nsystem. For Debian/Ubuntu based GNU/Linux systems, you can type\n\n      sudo apt-get install build-essential\n\nand for Fedora/Redhat based GNU/Linux systems, you can type\n\n      sudo dnf install make automake gcc gcc-c++\n\nTo compile the binary with multi-threaded computing via OpenMP, \nyour `gcc` version should be at least 4.0. To compile the binary \nsupporting SSE4 instructions, gcc version should be at least \n4.3.4. For windows users, you should install MSYS2 or Cygwin64 [3]. During the \ninstallation, please select `mingw64-x86_64-gcc` and `make` packages.\nFor MacOS users, you need to install the newer gcc from \nHomebrew or MacPorts and use the instructions below to compile the \nMMC source code.\n\n## Building MMC using CMake\n\nOne can choose one of the two methods to build mmc binaries. The first\napproach is to use CMake. CMake is a portable system creating compilation\nand linking commands automatically adapted to your operating system and \ninstalled compiler. It can run on Linux, MacOS and Windows.\n\nTo use CMake, you will have to first run `sudo apt-get install cmake`\nor `sudo dnf install cmake` to install cmake first. To build MMC binaries,\nyou should first navigate to the `mmc/src` folder, and run\n\n      mkdir -p build\n      cd build\n      cmake .. \u0026\u0026 make\n\nif cmake complains that any required library is missing, you will need\nto install those dependencies, removing all files inside the build folder,\nand run the cmake command above again.\n\nThe above command builds the `mmc` executable inside `mmc/bin` folder. If\nyour system has MATLAB installed, the above command also builds mmclab mex\nfile as `mmc/mmclab/mmc.mex*` where the mex suffix depends on your OS.\n\nIf you want to build the \"Trinity\" version of mmc to support CUDA on NVIDIA\nGPUs, you will have to first install CUDA toolkit, and replace the above cmake\ncommand by \n\n      cmake .. -DBUILD_CUDA=on \u0026\u0026 make\n\nthe executable will be build as `mmc/bin/mmciii` and the mex file is `mmc/mmclab/mmciii.mex*`.\n\n\n## Building MMC using GNU Make\n\nA more traditional, and fine-grained, approach to build MMC is to use the provided\n`Makefile` using GNU make. Similarly, you will need to open a terminal, navigate to\nthe `mmc/src` folder, and type\n\n      make\n\nthis should create a fully optimized OpenCL based mmc executable, located under \nthe `mmc/bin/` folder. The binary also supports SSE4 on the CPU.\n\nOther compilation options include\n\n      make ssemath  # this is the same as make, building mmc binary with SSE4+OpenMP+OpenCL\n      make cuda     # this compiles the \"Trinity\" version of mmc, supports SSE4+OpenMP+OpenCL+CUDA\n      make omp      # this compiles a multi-threaded binary using OpenMP\n      make release  # create a single-threaded optimized binary\n      make prof     # this makes a binary to produce profiling info for gprof\n      make sse      # this uses SSE4 for all vector operations (dot, cross), implies omp\n\nif you wish to build the mmc mex file to be used in matlab, you should run\n\n      make mex      # this produces mmc.mex* under mmc/mmclab/ folder\n      make cudamex  # this produces a \"Trinity\" version of mmc.mex* that supports SSE+OpenCL+CUDA\n\nsimilarly, if you wish to build the mex file for GNU Octave, you should run\n\n      make oct      # this produces mmc.mex* under mmc/mmclab/ folder\n      make cudaoct  # this produces a \"Trinity\" version of mmc.mex* that supports SSE+OpenCL+CUDA\n\nIf you append `-f makefile_sfmt` at the end of any of the above make \ncommands, you will get an executable named `mmc_sfmt`, which uses a fast \nMT19937 random-number-generator (RNG) instead of the default GLIBC 48bit RNG. \nIf your CPU supports SSE4, the fastest binary can be obtained by running the \nfollowing command:\n\n      make ssemath -f makefile_sfmt\n\nYou should be able to compile the code with an Intel C++ compiler, an AMD C \ncompiler or LLVM compiler without any difficulty. To use other compilers, you \nsimply append `CC=compiler_exe` to the above make commands. If you see any \nerror messages, please google and fix your compiler settings or install the \nmissing libraries.\n\nA special note for Mac OS users: you can you use both gcc (installed by MacPorts\nor brew) or the default clang gcc provided by the default Xcode compiler to build\nmmc. MMC requires OpenMP for multi-threading based parallel computing. If one uses\nthe clang compiler, one must first install `libomp` package in order to compile mmc.\n\n      brew install libomp\n      brew link --force libomp\n\nOne can switch to other compilers by setting the `CC`, `CXX` and `AR` environment\nvariables, for example\n\n      make CC=gcc-mp-10 CXX=g++-mp-10 AR=g++-mp-10\n\nAfter compilation, you may add the path to the `mmc` binary (typically, \n`mmc/bin`) to your search path. To do so, you should modify your `$PATH` \nenvironment variable. Detailed instructions can be found at [5].\n\nYou can also compile MMC using Intel's C++ compiler - `icc`. To do this, you run\n\n      make CC=icc\n\nyou must enable `icc` related environment variables by source the `compilervars.sh`\nfile. The speed of icc-generated mmc binary is generally faster for CPU/SSE based\nMMC simulation than those compiled by `gcc`.\n\n\nRunning Simulations\n----------------------\n\n### Preparation\n\nBefore you create/run your own MMC simulations, we suggest you first \nunderstanding all the examples under the mmc/example directory, checking out \nthe formats of the input files and the scripts for pre- and post-processing.\n\nBecause MMC uses FE meshes in the simulation, you should create a mesh for your \nproblem domain before launching any simulation. This can be done fairly \nstraightforwardly using a Matlab/Octave mesh generator, iso2mesh [1], \ndeveloped by the MMC author. In the mmc/matlab folder, we also provide \nadditional functions to generate regular grid-shaped tetrahedral meshes.\n\nIt is required to use the `savemmcmesh` function under the mmc/matlab \nfolder to save the mesh output from iso2mesh, because it performs additional \ntests to ensure the consistency of element orientations. If you choose not to \nuse `savemmcmesh`, you MUST call the `meshreorient` function in iso2mesh to \ntest the `elem` array and make sure all elements are oriented in the same \ndirection. Otherwise, MMC will give incorrect results.\n\n### Command line options\n\nThe full command line options of MMC include the following:\n\n```\n###############################################################################\n#                     Mesh-based Monte Carlo (MMC) - OpenCL                   #\n#          Copyright (c) 2010-2025 Qianqian Fang \u003cq.fang at neu.edu\u003e          #\n#              https://mcx.space/#mmc  \u0026  https://neurojson.io/               #\n#                                                                             #\n#Computational Optics \u0026 Translational Imaging (COTI) Lab  [http://fanglab.org]#\n#   Department of Bioengineering, Northeastern University, Boston, MA, USA    #\n###############################################################################\n#    The MCX Project is funded by the NIH/NIGMS under grant R01-GM114365      #\n###############################################################################\n#  Open-source codes and reusable scientific data are essential for research, #\n# MCX proudly developed human-readable JSON-based data formats for easy reuse.#\n#                                                                             #\n#Please visit our free scientific data sharing portal at https://neurojson.io/#\n# and consider sharing your public datasets in standardized JSON/JData format #\n###############################################################################\n$Rev::      $v2024.2 $Date::                       $ by $Author::             $\n###############################################################################\n\nusage: mmc \u003cparam1\u003e \u003cparam2\u003e ...\nwhere possible parameters include (the first item in [] is the default value)\n\n== Required option ==\n -f config     (--input)       read an input file in .json or inp format\n\n== MC options ==\n -n [0.|float] (--photon)      total photon number, max allowed value is 2^32-1\n -b [0|1]      (--reflect)     1 do reflection at int\u0026ext boundaries, 0 no ref.\n -U [1|0]      (--normalize)   1 to normalize the fluence to unitary,0 save raw\n -m [0|1]      (--mc)          0 use MCX-styled MC method, 1 use MCML style MC\n -C [1|0]      (--basisorder)  1 piece-wise-linear basis for fluence,0 constant\n -u [1.|float] (--unitinmm)    define the mesh data length unit in mm\n -E [1648335518|int|mch](--seed) set random-number-generator seed;\n                               if an mch file is followed, MMC \"replays\" \n                               the detected photons; the replay mode can be used\n                               to calculate the mua/mus Jacobian matrices\n -P [0|int]    (--replaydet)   replay only the detected photons from a given \n                               detector (det ID starts from 1), use with -E \n -M [G|SG]    (--method)      choose ray-tracing algorithm (only use 1 letter)\n                               P - Plucker-coordinate ray-tracing algorithm\n                               H - Havel's SSE4 ray-tracing algorithm\n                               B - partial Badouel's method (used by TIM-OS)\n                               S - branch-less Badouel's method with SSE\n                               G - dual-grid MMC (DMMC) with voxel data output\n -e [1e-6|float](--minenergy)  minimum energy level to trigger Russian roulette\n -V [0|1]      (--specular)    1 source located in the background,0 inside mesh\n -k [1|0]      (--voidtime)    when src is outside, 1 enables timer inside void\n\n== GPU options ==\n -A [0|int]    (--autopilot)   auto thread config:1 enable;0 disable\n -c [opencl,sse,cuda](--compute) select compute backend (default to opencl)\n                               can also use 0: sse, 1: opencl, 2: cuda\n -G [0|int]    (--gpu)         specify which GPU to use, list GPU by -L; 0 auto\n      or                       if set to -1, CPU-based SSE mmc will be used\n -G '1101'     (--gpu)         using multiple devices (1 enable, 0 disable)\n -W '50,30,20' (--workload)    workload for active devices; normalized by sum\n --atomic [1|0]                1 use atomic operations, 0 use non-atomic ones\n\n== Output options ==\n -s sessionid  (--session)     a string used to tag all output file names\n -O [X|XFEJLP] (--outputtype)  X - output flux, F - fluence, E - energy density\n                               J - Jacobian, L - weighted path length, P -\n                               weighted scattering count (J,L,P: replay mode)\n -d [0|1]      (--savedet)     1 to save photon info at detectors,0 not to save\n -H [1000000] (--maxdetphoton) max number of detected photons\n -S [1|0]      (--save2pt)     1 to save the fluence field, 0 do not save\n -x [0|1]      (--saveexit)    1 to save photon exit positions and directions\n                               setting -x to 1 also implies setting '-d' to 1\n -X [0|1]      (--saveref)     save diffuse reflectance/transmittance on the \n                               exterior surface. The output is stored in a \n                               file named *_dref.dat, and the 2nd column of \n                               the data is resized to [#Nf, #time_gate] where\n                               #Nf is the number of triangles on the surface; \n                               #time_gate is the number of total time gates. \n                               To plot the surface diffuse reflectance, the \n                               output triangle surface mesh can be extracted\n                               by faces=faceneighbors(cfg.elem,'rowmajor');\n                               where 'faceneighbors' is part of Iso2Mesh.\n -q [0|1]      (--saveseed)    1 save RNG seeds of detected photons for replay\n -F [bin|...] (--outputformat) 'ascii', 'bin' (in 'double'), 'mc2' (double) \n                               'hdr' (Analyze) or 'nii' (nifti, double)\n                               mc2 - MCX mc2 format (binary 64bit float)\n                               jnii - JNIfTI format (https://neurojson.org)\n                               bnii - Binary JNIfTI (https://neurojson.org)\n                               nii - NIfTI format\n                               hdr - Analyze 7.5 hdr/img format\n    the bnii/jnii formats support compression (-Z) and generate small files\n    load jnii (JSON) and bnii (UBJSON) files using below lightweight libs:\n      MATLAB/Octave: JNIfTI toolbox   https://github.com/NeuroJSON/jnifti, \n      MATLAB/Octave: JSONLab toolbox  https://github.com/fangq/jsonlab, \n      Python:        PyJData:         https://pypi.org/project/jdata\n      JavaScript:    JSData:          https://github.com/NeuroJSON/jsdata\n -Z [zlib|...] (--zip)      set compression method if -F jnii or --dumpjson\n                            is used (when saving data to JSON/JNIfTI format)\n                            0 zlib: zip format (moderate compression,fast) \n                            1 gzip: gzip format (compatible with *.gz)\n                            2 base64: base64 encoding with no compression\n                            3 lzip: lzip format (high compression,very slow)\n                            4 lzma: lzma format (high compression,very slow)\n                            5 lz4: LZ4 format (low compression,extrem. fast)\n                            6 lz4hc: LZ4HC format (moderate compression,fast)\n --dumpjson [-,2,'file.json'] export all settings, including volume data using\n                          JSON/JData (https://neurojson.org) format for \n                          easy sharing; can be reused using -f\n                          if followed by nothing or '-', mmc will print\n                          the JSON to the console; write to a file if file\n                          name is specified; by default, prints settings\n                          after pre-processing; '--dumpjson 2' prints \n                          raw inputs before pre-processing\n\n== User IO options ==\n -h            (--help)        print this message\n -v            (--version)     print MMC version information\n -l            (--log)         print messages to a log file instead\n -i            (--interactive) interactive mode\n\n== Debug options ==\n -D [0|int]    (--debug)       print debug information (you can use an integer\n  or                           or a string by combining the following flags)\n -D [''|SCBWDIOXATRPEM]        1 S  photon movement info\n                               2 C  print ray-polygon testing details\n                               4 B  print Bary-centric coordinates\n                               8 W  print photon weight changes\n                              16 D  print distances\n                              32 I  entering a triangle\n                              64 O  exiting a triangle\n                             128 X  hitting an edge\n                             256 A  accumulating weights to the mesh\n                             512 T  timing information\n                            1024 R  debugging reflection\n                            2048 P  show progress bar\n                            4096 E  exit photon info\n                            8192 M  return photon trajectories\n      combine multiple items by using a string, or add selected numbers together\n --debugphoton [-1|int]        to print the debug info specified by -D only for\n                               a single photon, followed by its index (start 0)\n\n== Additional options ==\n --momentum     [0|1]          1 to save photon momentum transfer,0 not to save\n --gridsize     [1|float]      if -M G is used, this sets the grid size in mm\n --maxjumpdebug [10000000|int] when trajectory is requested (i.e. -D S),\n                               use this parameter to set the maximum positions\n                               stored (default: 1e7)\n\n== Example ==\n       mmc -n 1000000 -f input.json -s test -b 0 -D TP -G -1\n```\n\n### Input files\n\nIt is highly recommended to use the JSON-formatted input file described in the following\nsection. The legacy input file format `.inp` is depreciated and may be removed in\nfuture releases.\n\nThe simplest example can be found under the `example/onecube` folder. \nPlease run `createmesh.m` first from Matlab/Octave to create all the mesh \nfiles, which include\n\n    elem_onecube.dat    -- tetrahedral element file\n    facenb_onecube.dat  -- element neighbors of each face\n    node_onecube.dat    -- node coordinates\n    prop_onecube.dat    -- optical properties of each element type\n    velem_onecube.dat   -- volume of each element\n\nThe input file of the example is named `onecube.inp`, where we specify most \nof the simulation parameters. The input file follows a similar format as in \nMCX, which looks like the following\n\n    100                  # total photon number (can be overwriten by -n)\n    17182818             # RNG seed, negative to regenerate\n    2. 8. 0.             # source position (mm)\n    0. 0. 1.             # initial incident vector\n    0.e+00 5.e-09 5e-10  # time-gates(s): start, end, step\n    onecube              # mesh id: name stub to all mesh files\n    3                    # index of element (starting from 1) which encloses the source\n    3       1.0          # detector number and radius (mm)\n    2.0     6.0    0.0   # detector 1 position (mm)\n    2.0     4.0    0.0   # ...\n    2.0     2.0    0.0\n    pencil               # optional: source type\n    0 0 0 0              # optional: source parameter set 1\n    0 0 0 0              # optional: source parameter set 2\n\nThe mesh files are linked through the `mesh id` (a name stub) with a format \nof `{node|elem|facenb|velem}_meshid.dat`. All mesh files must exist for an MMC \nsimulation. If the index to the tetrahedron that encloses the source is not \nknown, please use the `tsearchn` function in matlab/octave to find out and \nsupply it in the 7th line in the input file. Examples are provided in \n`mmc/examples/meshtest/createmesh.m`.\n\nTo run a simulation, you should execute the `run_test.sh` bash script in \nthis folder. If you want to run mmc directly from the command line, you can do \nso by typing\n\n`../../bin/mmc -n 20 -f onecube.inp -s onecube`\n\nwhere `-n` specifies the total photon number to be simulated, `-f` specifies the \ninput file, and `-s` gives the output file name. To see all the supported \noptions, run `mmc` without any parameters.\n\nThe above command only simulates 20 photons and will complete instantly. An \noutput file `onecube.dat` will be saved to record the normalized (unitary) \nflux at each node. If one specifies multiple time-windows from the input file, \nthe output will contain multiple blocks with each block corresponding to the \ntime-domain solution at all nodes computed for each time window.\n\nMore sophisticated examples can be found under the `example/validation` and \n`example/meshtest` folders, where you can find `createmesh` scripts and \npost-processing script to make plots from the simulation results.\n\n### JSON-formatted input files\n\nStarting from version 0.9, MMC accepts a JSON-formatted input file in addition \nto the conventional tMCimg-like input format. JSON (JavaScript Object Notation) \nis a portable, human-readable and “fat-free” text format to represent \ncomplex and hierarchical data. Using the JSON format makes a input file \nself-explanatory, extensible and easy-to-interface with other applications \n(like MATLAB).\n\nA sample JSON input file can be found under the `examples/onecube` folder. The \nsame file, `onecube.json`, is also shown below:\n\n    {\n        \"Domain\": {\n            \"MeshID\": \"onecube\",\n            \"InitElem\": 3\n        },\n        \"Session\": {\n            \"Photons\":  100,\n            \"Seed\":     17182818,\n            \"ID\":       \"onecube\"\n        },\n        \"Forward\": {\n            \"T0\": 0.0e+00,\n            \"T1\": 5.0e-09,\n            \"Dt\": 5.0e-10\n        },\n        \"Optode\": {\n            \"Source\": {\n                \"Type\": \"pencil\",\n                \"Pos\": [2.0, 8.0, 0.0],\n                \"Dir\": [0.0, 0.0, 1.0],\n                \"Param1\": [0.0, 0.0, 0.0, 0.0],\n                \"Param2\": [0.0, 0.0, 0.0, 0.0]\n            },\n            \"Detector\": [\n                {\n                    \"Pos\": [2.0, 6.0, 0.0],\n                    \"R\": 1.0\n                },\n                {\n                    \"Pos\": [2.0, 4.0, 0.0],\n                    \"R\": 1.0\n                },\n                {\n                    \"Pos\": [2.0, 2.0, 0.0],\n                    \"R\": 1.0\n                }\n            ]\n        }\n    }\n\nA JSON input file requires 4 root objects, namely `Domain`, `Session`, \n`Forward` and `Optode`. Each object is a data structure providing \ninformation as indicated by its name. Each object can contain various \nsub-fields. The orders of the fields in the same level are flexible. For each \nfield, you can always find the equivalent fields in the `*.inp` input files. For \nexample, The `MeshID` field under the `Mesh` object is the same as \nLine\\#6 in onecube.inp; the `InitElem` under `Mesh` is the same as \nLine\\#7; the `Forward.T0` is the same as the first number in Line\\#5, etc.\n\nAn MMC JSON input file must be a valid JSON text file. You can validate your \ninput file by running a JSON validator, for example \u003chttp://jsonlint.com/\u003e You \nshould always use `...` to quote a `name` and separate parallel items \nby `,`.\n\nMMC accepts an alternative form of JSON input, but using it is not recommended. \nIn the alternative format, you can use `\"rootobj_name.field_name\": value `\n\nto represent any parameter directly in the root level. For example\n\n    {\n        \"Domain.MeshID\": \"onecube\",\n        \"Session.ID\": \"onecube\",\n        ...\n    }\n\nYou can even mix the alternative format with the standard format. If any input \nparameter has values in both formats in a single input file, the \nstandard-formatted value has higher priority.\n\nTo invoke the JSON-formatted input file in your simulations, you can use the \n`-f` command line option with MMC, just like using an `.inp` file. For \nexample:\n\n      ../../bin/mmc -n 20 -f onecube.json -s onecubejson -D M\n\nThe input file must have a `.json` suffix in order for MMC to recognize. If \nthe input information is set in both command line, and input file, the command \nline value has higher priority (this is the same for `.inp` input files). For \nexample, when using `-n 20`, the value set in `Session`/`Photons` \nis overwritten to 20; when using `-s onecubejson`, the \n`Session`/`ID` value is modified. If your JSON input file is invalid, \nMMC will quit and point out where it expects you to double check.\n\n### Photon debugging information using -D flag\n\nthe output format for `-D M` (photon moving) is below:\n\n    ? px py pz eid id scat\n\n    ? is a single letter representing the state of the current position:\n       B a boundary point\n       P the photon is passing an interface point\n       T the photon terminates at this location due to\n          exceeding end of the time window\n       M a position other than any of the above\n\n    px,py,pz: the current photon position\n\n    eid: the index (starting from 1) of the current enclosing element\n\n    id: the index of the current photon, from 1 to nphoton\n\n    scat: the \"normalized\" length to read the next scattering site, \\\n       it is unitless\n\n    for -D A (flux accumulation debugging), the output is\n\n    A ax ay az ww eid dlen\n\n    ax ay az: the location where the accumulation calculation was done \\\n       (typically, the half-way point of the line segment between the last \\\n       and current positions)\n\n    ww: the photon weight loss for the line segment\n\n    dlen=scat/mus of the current element: the distance left to arrive \\\n       the next scattering site\n\n    for -D E\n\n    E  px py pz vx vy vz w eid\n\n    vx vy vz: the unitary propagation vector when the photon exits\n    w: the current photon weight\n\n\n### Plotting the Results\n\nAs described above, MMC produces a fluence-rate output file as \n`session-id.dat`. By default, this file contains the normalized, i.e. under \nunitary source, fluence at each node of the mesh. The detailed interpretation \nof the output data can be found in [6]. If multiple time-windows are defined, \nthe output file will contain multiple blocks of data, with each block being the \nfluence distribution at each node at the center point of each time-window. The \ntotal number of blocks equals to the total time-gate number.\n\nTo read the mesh files (tetrahedral elements and nodes) into matlab, one can \nuse `readmmcnode` and `readmmcelem` function under the mmc/matlab directory. \nPlotting non-structural meshes in matlab is possible with interpolation \nfunctions such as griddata3. However, it is very time-consuming for large \nmeshes. In iso2mesh, a fast mesh slicing \u0026 plotting function, `qmeshcut`, is very \nefficient in making 3D plots of mesh or cross-sections. More details can be \nfound at this webpage [7], or `help qmeshcut` in matlab. Another useful \nfunction is plotmesh in iso2mesh toolbox. It has very flexible syntax to allow \nusers to plot surfaces, volumetric meshes and cross-section plots. One can use \nsomething like\n\n      plotmesh([node fluence],elem,'x\u003c30 \u0026 y\u003e30');\n\nto plot a sliced mesh, or\n\n      plotmesh([node log10(fluence)],elem,'x=30'); view(3)\n\nto show a cross-sectional plot.\n\nPlease edit or browse the `*.m` files under all example subfolder to find more \noptions to make plot from MMC output.\n\nWhen users specify `-d 1` to record partial path lengths for all detected \nphotons, an output file named `sessionid.mch` will be saved under the same \nfolder. This file can be loaded into Matlab/Octave using the `loadmch.m`\nscript under the mmc/matlab folder. The output of loadmch script has the \nfollowing columns:\n\n      detector-id, scattering-events, partial-length_1, partial-length_2, ...., additional data ...`\n\nThe simulation settings will be returned by a structure. Using the information \nfrom the mch file will allow you to re-scale the detector readings without \nrerunning the simulation (for absorption changes only).\n\n\nKnown issues and TODOs\n-------------------------\n\n-   MMC only supports linear tetrahedral elements at this point. \n Quadratic elements will be added later\n-   Currently, this code only supports element-based optical properties; \n nodal-based optical properties (for continuously varying media) will be\n added in a future release\n\n\nGetting Involved\n-------------------\n\nMMC is an open-source software. It is released under the terms of GNU General \nPublic License version 3 (GPLv3). That means not only everyone can download and \nuse MMC for any purposes, but also you can modify the code and share the \nimproved software with others (as long as the derived work is also licensed \nunder the GPLv3 license).\n\nIf you already made a change to the source code to fix a bug you encountered in \nyour research, we are appreciated if you can share your changes (as `git diff` \noutputs) with the developers. We will patch the code as soon as we \nfully test the changes (we will acknowledge your contribution in the MMC \ndocumentation).\n\nWhen making edits to the source code with an intent of sharing with the \nupstream authors, please set your editor's tab width to 8 so that the \nindentation of the source is correctly displayed. Please keep your patch as \nsmall and local as possible, so that other parts of the code are not influenced.\n\nTo streamline the process process, the best way to contribute your patch is to \nclick the **fork** button from \u003chttp://github.com/fangq/mmc\u003e, and then change \nthe code in your forked repository. Once fully tested and documented, you can \nthen create a **pull request** so that the upstream author can review the \nchanges and accept your change.\n\nIn you are a user, please use our mmc-users mailing list to post questions or \nshare experience regarding MMC. The mailing lists can be found from this link:\n\n\u003chttp://mcx.space/#about\u003e\n\n\nAcknowledgement\n------------------\n\nMMC uses the following open-source libraries:\n\n\n### ZMat data compression unit\n\n- Files: src/zmat/*\n- Copyright: 2019-2020 Qianqian Fang\n- URL: https://github.com/fangq/zmat\n- License: GPL version 3 or later, https://github.com/fangq/zmat/blob/master/LICENSE.txt\n\n### LZ4 data compression library\n\n- Files: src/zmat/lz4/*\n- Copyright: 2011-2020, Yann Collet\n- URL: https://github.com/lz4/lz4\n- License: BSD-2-clause, https://github.com/lz4/lz4/blob/dev/lib/LICENSE\n\n### LZMA/Easylzma data compression library\n\n- Files: src/zmat/easylzma/*\n- Copyright: 2009, Lloyd Hilaiel, 2008, Igor Pavlov\n- License: public-domain\n- Comment:\n All the cruft you find here is public domain.  You don't have to\n credit anyone to use this code, but my personal request is that you mention\n Igor Pavlov for his hard, high quality work.\n\n### Miniz compression library\n\n- Files: src/zmat/miniz/*\n- Copyright 2013-2014 RAD Game Tools and Valve Software\n- Copyright 2010-2014 Rich Geldreich and Tenacious Software LLC\n- URL: https://github.com/richgel999/miniz\n- License: MIT-license, https://github.com/richgel999/miniz/blob/master/LICENSE\n\n### SSE Math library by Julien Pommier\n\nCopyright (C) 2007 Julien Pommier\n\nThis software is provided 'as-is', without any express or implied warranty. In \nno event will the authors be held liable for any damages arising from the use \nof this software.\n\nPermission is granted to anyone to use this software for any purpose, including \ncommercial applications, and to alter it and redistribute it freely, subject to \nthe following restrictions:\n\n1. The origin of this software must not be misrepresented; you must not claim \nthat you wrote the original software. If you use this software in a product, an \nacknowledgment in the product documentation would be appreciated but is not \nrequired.\n\n2. Altered source versions must be plainly marked as such, and must not be \nmisrepresented as being the original software.\n\n3. This notice may not be removed or altered from any source distribution.\n\n(this is the zlib license)\n\n### cJSON library by Dave Gamble\n\nCopyright (c) 2009 Dave Gamble\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of \nthis software and associated documentation files (the “Software”), to deal \nin the Software without restriction, including without limitation the rights to \nuse, copy, modify, merge, publish, distribute, sublicense, and/or sell copies \nof the Software, and to permit persons to whom the Software is furnished to do \nso, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all \ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR \nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, \nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE \nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER \nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, \nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE \nSOFTWARE.\n\n### SFMT library by Mutsuo Saito, Makoto Matsumoto and Hiroshima University\n\nCopyright (c) 2006,2007 Mutsuo Saito, Makoto Matsumoto and Hiroshima \nUniversity. All rights reserved.\n\nRedistribution and use in source and binary forms, with or without \nmodification, are permitted provided that the following conditions are met:\n\n-   Redistributions of source code must retain the above copyright \nnotice, this list of conditions and the following disclaimer. \n\n-   Redistributions in binary form must reproduce the above \ncopyright notice, this list of conditions and the following \ndisclaimer in the documentation and/or other materials provided \nwith the distribution.\n\n-   Neither the name of the Hiroshima University nor the names of\nits contributors may be used to endorse or promote products \nderived from this software without specific prior written \npermission.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” \nAND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE \nIMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE \nDISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR \nANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES \n(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; \nLOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON \nANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT \n(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS \nSOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n\n### drand48_r port for libgw32c by Free Software Foundation\n\nCopyright (C) 1995, 1997, 2001 Free Software Foundation, Inc. This file is part \nof the GNU C Library. Contributed by Ulrich Drepper \n\u0026lt;drepper@gnu.ai.mit.edu\u0026gt;, August 1995.\n\nThe GNU C Library is free software; you can redistribute it and/or modify it \nunder the terms of the GNU Lesser General Public License as published by the \nFree Software Foundation; either version 2.1 of the License, or (at your \noption) any later version.\n\nThe GNU C Library is distributed in the hope that it will be useful, but \nWITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or \nFITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for \nmore details.\n\nYou should have received a copy of the GNU Lesser General Public License along \nwith the GNU C Library; if not, write to the Free Software Foundation, Inc., 59 \nTemple Place, Suite 330, Boston, MA 02111-1307 USA.\n\n### git-rcs-keywords by Martin Turon (turon) at Github\n\nMMC includes a pair of git filters (`.git_filters/rcs-keywords.clean` and \n`.git_filters/rcs-keywords.smudge`) to automatically update SVN keywords in \n`mcx_utils.c`. The two simple filter scripts were licensed under the BSD license \naccording to this link:\n\n\u003chttps://github.com/turon/git-rcs-keywords/issues/4\u003e\n\nBoth filter files were significantly modified by Qianqian Fang.\n\n\nReference\n------------\n\n\n- [1] \u003chttp://iso2mesh.sf.net\u003e -- an image-based surface/volumetric mesh generator \n- [2] \u003chttp://mcx.sf.net\u003e -- Monte Carlo eXtreme: a GPU-accelerated MC code \n- [3] \u003chttps://cygwin.com/setup-x86_64.exe\u003e \n- [4] \u003chttp://developer.apple.com/mac/library/releasenotes/DeveloperTools/RN-llvm-gcc/index.html\u003e \n- [5] \u003chttp://iso2mesh.sourceforge.net/cgi-bin/index.cgi?Doc/AddPath\u003e \n- [6] \u003chttp://mcx.sf.net/cgi-bin/index.cgi?MMC/Doc/FAQ#How_do_I_interpret_MMC_s_output_data\u003e \n- [7] \u003chttp://iso2mesh.sourceforge.net/cgi-bin/index.cgi?fun/qmeshcut\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffangq%2Fmmc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffangq%2Fmmc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffangq%2Fmmc/lists"}