Release Notes for Mesh-based Monte Carlo 1.0-beta (2016.1)

code name: Cotton Candy, released on Jan. 01, 2016

Acknowledgement: This software release is made possible with the funding support from NIH/NIGMS under the grant number R01-GM114365. It is also a result of a collaboration with Dr. Xavier Intes's group at Rensselaer Polytechnic Institute (RPI), particularly the contributions from Ruoyang Yao.

Publication: Yao R, Intes X, Fang Q, "Generalized mesh-based Monte Carlo for wide-field illumination and detection via mesh retessellation," Biomed. Optics Express, 7(1), 171-184 (2016)

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

1. Introduction

Mesh-based Monte Carlo, or MMC, is a Monte Carlo simulation package designed for simulating photon transport in 3D heterogeneous media. MMC can use a volumetric 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.

Starting from this release, a generalized MMC algorithm that can efficiently model complex wide-field sources and detectors is included in the software. Over 10 different commonly used source forms are supported, similarly to our previously released wide-field MCX software.

This is the first release through our new time-based release strategy. We plan to announce 4 releases each year - one release per 3 months.

The download link to this release can be accessed from here.

2. About this release

MMC 1.0-beta is a stable preview to the upcoming milestone, version 1.0, of MMC. It contains significantly improved capability to model complex widefield sources and detectors, as well as a number of fixes to several high priority bugs. Thanks to the contributions from Ruoyang Yao in Dr. Xavier Intes's Lab at RPI, the complex widefield source forms previously supported in MCX have now been successfully ported to Mesh-based MC simulations through an efficient mesh-retessellation algorithm. This collaborative work is reported in our paper appearing on Biomed. Optics Express today [2]

https://www.osapublishing.org/boe/abstract.cfm?uri=boe-7-1-171

3. What's new compared to 0.9.5

The new release of 1.0-beta was significantly improved upon the previous version, v0.9.5, published nearly two years ago. The key changes include:

3.1. new features

  1. !!key!! a dozen of wide-field complex source forms are supported, including SFDI sources, Gaussian beams, cone beams, planar beam, arbitrary 2D pattern, and more.
  2. !!key!! all area beams support convergence and divergence via focal length setting (the optional 4th element of srcdir vector).
  3. !!key!! complex-shaped wide-field detectors are now supported in MMC; the detector can have arbitrary aperture shapes and can be outside of the target mesh.
  4. !!key!! make SSE4 ray-tracing algorithm (Havel ray-tracer) the default algorithm
  5. !!key!! MMCLAB for 64bit windows is now supported.
  6. change drand48_r random number generator to erand48 for better portability for Windows and OSX;

3.2. bug fixes

  1. !!critical!! fix direction vector normalization bug when reflection is enabled;
  2. !!critical!! fix crashes caused by round-off near the end of the simulation time-window;
  3. !!critical!! fix floating-point round-off limit bug that influences the scattering calculations;
  4. !!critical!! fix crashed caused by inaccurate ray-tracing in Havel SSE4 ray-tracer
  5. fix matlab crashes when running mmclab with -nojvm in matlab 2013a or newer
  6. avoid crash when writing to a string literal in processing the input file
  7. fix bug to calculate scattering length at launch time

3.3. other improvement

  1. add Colin27 brain atlas example
  2. add mmclab script to systematically compare mcx and mmc
  3. add examples and mmclab demo script for SFDI and planar sources
  4. allow to specify endianness when loading mch files
  5. report wide-field overhead in all ray-tracers
  6. report absorption/total energy ratio
  7. allow reseeding from the input file
  8. add git filters to automatically update file versions when checking out
  9. automatically download Digimouse and Colin27 atlas mesh when missing;
  10. more tests for the replay feature
  11. synchronize cJSON to the latest version

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

The default "SSE4" 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 switch to the "multicore" binaries.

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