Skip to content

MMC 2016.1 Release (v1.0-beta-1, Cotton Candy)
Compare
Choose a tag to compare
@fangq fangq released this 05 Jan 18:24
· 842 commits to master since this release
v1.0-beta-1
9292441

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

code name: Cotton Candy, released on Jan. 05, 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)

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.

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 from
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

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:

new features

  • !!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.
  • !!key!! all area beams support convergence and divergence via focal length setting
    (the optional 4th element of srcdir vector).
  • !!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.
  • !!key!! MMCLAB for 64bit windows is now supported.
  • change drand48_r random number generator to erand48 for portability in Windows and Mac;

bug fixes

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

other improvement

  • add Colin27 brain atlas example
  • add mmclab script to systematically compare mcx and mmc
  • add examples and mmclab demo script for SFDI and planar sources
  • allow to specify endianness when loading mch files
  • report wide-field overhead in all ray-tracers
  • report absorption/total energy ratio
  • allow reseeding from the input file
  • add git filters to automatically update file versions when checking out
  • automatically download Digimouse and Colin27 atlas mesh when missing;
  • more tests for the replay feature
  • 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 [[MMC/ChangeLog|ChangeLog]]
and Git commit history pages.

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.

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).

Reference

Assets 2
Loading