Showing revision 1

Release Notes for Mesh-based Monte Carlo Version 1.0-beta

code name: Cotton Candy, released on Dec. 18, 2015

1. Introduction
2. About this release
3. What's new compared to 0.9.5
3.1. new features
3.2. bug fixes
4. System requirements
5. Known issues
6. Preview of the next release
7. 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.

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 most important release, 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. 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 for 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.

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. fix matlab crashes when running mmclab with nojvm in newer matlab versions
  5. avoid crash from writing to a string literal in processing the input file
  6. fix bug to calculate scattering length at launch time

Pre-compiled MMC binaries are provided for Windows, Linux and Mac OS. In all cases, a binary compiled with a fast SFMT-19937 RNG (mmc_sfmt) is included along with the default binary (mmc) using the GLIBC RNG.

Using mmc_sfmt is generally recommended over mmc. The best simulation speed can be typically achieved by using 

  mmc_sfmt -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 "multicore" MMC binaries can be used on almost all computers (even those with a single-core processor).

The "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 has to specify the correct initial element ID in the input file, this can be done by using the matlab/octave function "tsearchn" before running the simulation
  • 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. Preview of the next release

The next release of MMC will be version 1.0. In this release, we will include wide-field illumination and MPI support to MMC, as a result of a collaboration between me and Dr. Xavier Intes and Jin Chen from RPI (this has been implemented and tested, Jin is now working on final polishing of the code). Stay tuned if you are interested.

7. Reference

Powered by Habitat