Release Notes for Mesh-based Monte Carlo 1.4.8-1 (v2019.3-1)

code name: Pork Rinds, released on March 21, 2019

Click this link to download MMC/MMCLAB v2019.3-1

Acknowledgement: This software release is made possible with the funding support from the NIH/NIGMS under grant R01-GM114365.

1. Introduction
2. About this release
3. What's new compared to previous release
3.1. new features
3.2. other improvement
4. System requirements
5. Known issues
6. Reference

1. Introduction

Mesh-based Monte Carlo, or MMC, is a Monte Carlo light transport simulator designed for high accuracy for modeling tissues or domains with complex and smooth boundaries. Unlikely other existing MC software designed for layered (such as MCML) or voxel-based media (tMCimg, mcxyz and MCX), MMC can use a tetrahedral mesh to represent a complex domain, making it computationally and memory efficient.

MMC supports multi-threading based parallel computing. You can obtain a nearly linear speed-up when using more CPU cores in your simulation. Starting from version 0.8, MMC also supports the Single-Instruction Multiple-Data (SIMD) parallelism on modern CPUs, allowing MMC to take further advantage in parallel computing.

MMCLAB is the MATLAB mex version of the MMC software. It can be directly called inside MATLAB. This makes it easy to use with streamlined pre-processing (mesh generation using the Iso2Mesh toolbox) and post processing (visualization and data analysis).

2. About this release

MMC/MMCLAB v2019.3-1 contains an important bug-fix to v2019.3, released just a few days ago. This bug fix concerns simulations using the -M S (branchless Badouel method) and -M G (dual-grid MMC). With this fix, the handling to edge-crossing photons is more robust and yields more accurate solutions, especially when the mesh density is high.

MMC/MMCLAB v2019.3 contains a list of important new features as well as bug fixes.

The most important featured in this release is the completion of the "dual-grid MMC" or DMMC. DMMC is an improved MMC, allowing one to use coarse mesh to accelerate ray-tracing calculations, but in the meantime, permit the use of a voxelated grid, like the domain used in MCX, to store output fluence data. In our tests, this method can typically be 2-3 fold faster than the regular MMC, at the same time, providing higher accuracy in fluence output. This technique can be enabled by "-M G" or cfg.method='grid'. The details of our study can be found in the below paper:

[Yan2019] Shijie Yan, Anh Phong Tran, Qianqian Fang*, “A dual-grid mesh-based Monte Carlo algorithm for efficient photon transport simulations in complex 3-D media,” J. of Biomedical Optics, 24(2), 020503 (2019).

Another key feature added in this release is the initial support for "photon sharing" - a fast approach to simultaneously simulate multiple pattern src/det, as detailed in our Photoncs West 2019 talk by Ruoyang Yao/Shijie Yan

[Yao&Yan2019] Ruoyang Yao, Shijie Yan, Xavier Intes, Qianqian Fang, "Accelerating Monte Carlo forward model with structured light illumination via 'photon sharing'," Photonics West 2019, paper#10874-11, San Francisco, CA, USA. Full presentation for our invited talk

3. What's new compared to previous release

The v2019.3 release was improved upon the previous version, v2018 by fixing a list of bugs. They are:

3.1. new features

  1. !!key!! add xorshift128+ RNG, seed each thread by host RNG
  2. !!key!! support "photon sharing", added examples for mmclab
  3. !!key!! simultaneous replay for all pattern-based detectors
  4. !!key!! add USC 19.5 atlas example, add mcxyz skinvessel benchmark
  5. !!key!! add color to command line output, cmd options high priority
  6. add nightly build script for mmc deployment
  7. add initial webassembly support for web-based mmc
  8. support clang
  9. support mc2 and nii output for DMMC

3.2. other improvement

  1. fix a bug for doubling thread number every call to mmc, thanks to Shijie
  2. fix mmclab crash due to racing in multi-thread, similar to mcx issue #60
  3. fix wrong usage of free() on pointer returned by mxGetPr

Pre-compiled MMC binaries are provided for Windows, Linux and Mac OS. In all cases, a binary compiled with SSE4-accelerated ray-tracing algorithms is provided for each platform.

The best simulation speed can be typically achieved by using 

  mmc -M S -C 0 ....

One can recompile all binaries using an Intel C++ Compiler. It can generate binaries up to 25% faster than the equivalent binaries compiled with GCC.

The detailed change logs can be found in the ChangeLog and Git commit history pages.

4. System requirements

Although MMC/MMCLAB can be executed independently once all input data (including mesh data) are provided, most pre- and post-processing scripts in both packages require the installation of Iso2Mesh Toolbox - a MATLAB based 3D mesh generator. Please browse http://iso2mesh.sf.net for download and installation information.

The default ray-tracer in the released binaries require your computer to support SSE4 instructions. This can be determined by using the following command on Linux/MacOS 

  grep 'sse4' /proc/cpuinfo

or using a freeware "CPU-Z" on windows. If you attempt to run the SSE4 on an unsupported computer, you will get an error when executing the binary. In that case, you should recompile MMC using "make omp" command.

5. Known issues

  • One must use savemmcmesh.m to generate all mesh input files for MMC; otherwise, the element orientation is not guaranteed.
  • Currently, this code only supports element-based optical properties; nodal-based optical properties (for continuously varying media) will be added in a future release
  • The maximum photon number per MMC session is 2^32-1=4,294,967,295, if you need to run a large number of photons, we suggest you splitting the job into smaller jobs with each one running a smaller chunk of photons (for example 1E8). Each job should initialized with a different seed (-E).

6. Reference

Powered by Habitat