Skip to content

MMC 1.0 Final (v2018 - Sachima)
Compare
Choose a tag to compare
@fangq fangq released this 26 Aug 16:10
· 715 commits to master since this release
v1.0
feab0bd

Release Notes for Mesh-based Monte Carlo 1.0 Final (v2018)

code name: Sachima, released on August 20, 2018

Click this link to download MMC/MMCLAB v2018

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

Opening Remarks

After over 8 years continuous development, it is our great pleasure to announce that MMC 1.0 (v2018) has finally arrived! This release represents an important milestone for the MCX/MMC project, and signifies that MMC has grown from a unique research idea to become a mature, robust, full-featured, and general purpose Monte Carlo simulation platform that empowers thousands of biophotonics researchers around the globe to explore, to teach and to create. This also marks the start of a wonderful new journey where many exciting new ideas, methods, features await ahead.

As of today, our combined registered MCX and MMC user number (with unique emails) has exceeded 1,500, with people coming from every corner of the world. The total download number in the past 7 years has exceeded 22,500 from our Sourceforge site alone. There are over 780 academic publications cited our works, and more than 1,200 questions/replies were received in our mailing lists, subscribed by over 250 active users. We are proud of these achievements and feel deeply honored to contribute, even in a small way, to many ongoing exciting new research, and are committed to continue dedicating our efforts in maintaining and improving our software. We will continue working with every one of you, addressing your concerns and new feature requests, bringing the latest and fastest software to you with complete transparency and openness.

Today, we celebrate MMC 1.0, we thank all the hard-works from the developers' team, particularly those PhD students who had made MMC a fast and better software - particularly Ruoyang Yao, Shijie Yan, and Anh Phong Tran, as well as the close collaboration with Dr. Xavier Intes from RPI. We also thank all the valuable feedback received from our users, your bug reports and constructive discussions are crucial for us to improve our software. Last, but not the least, we thank NIH/NIGMS for funding this endeavor. It is not possible for us to get where we are today without this support.

Today, we also kickoff the new development cycle for MMC 2.0! We will complete our works to port MMC to the GPU, finalize our dual-grid MMC (DMMC) algorithm, and in the meantime, focusing on usability and broader dissemination.

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

About this release

MMC/MMCLAB 1.0 contains a [MMC/ChangeLog list of important new features as well as bug fixes].

The most important featured added/mature in this release is the "photon replay" approach for conveniently build Jacobian matrices for solving inverse problems. While this method was initially implemented a few years ago, over the past year, we were able to systematically validate and improve this algorithm and applied it for solving real-world tomography problems. Our paper, first authored by Ruoyang Yao, on this method is recently accepted by Biomed. Optics Express, and is expected to be published online soon. A preview of the accepted manuscript can be found at

https://groups.google.com/forum/?hl=en#!topic/mmc-users/3ZDxrhhD3DQ

Also, a single-replay to create Jacobians for all detection-patterns is implemented by Ruoyang Yao. This is particularly valuable for wide-field illumination/detection imaging systems.

Moreover, an important new variation of MMC, called dual-grid MMC or DMMC, was implemented and systematically tested over the past year. In this method, we combined the ideas of both mesh-based and voxel-based MC algorithms, by using a coarsely tessellated mesh for ray-tracing and a coincident voxelated grid for storing the output fluence. The decoupling between the forward mesh and the storage grid not only result in 2x or more speed acceleration, but also simultaneously results in higher output accuracy. Our paper, first-authored by Shijie Yan, is currently under review.

What's new compared to previous release

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

# new features

  1. !!key!! implemented dual-grid MMC or DMMC (paper in review)
  2. !!key!! systematically validated and accelerated photon replay (paper in press)
  3. !!key!! simultaneous replay for all pattern-based detectors
  4. !!key!! output accumulated photon weight as time-resolved 2D images
  5. !!key!! add detailed http://mcx.space/doc/mmc/html/ doxygen documentation
  6. !!key!! force matlab to use multi-threading with mmc
  7. !!key!! make mesh elem and facenb flexible to support non-tetrahedron elements
  8. fix a crash in branchless_badouel_raytet ray-tracer: bary.x of -Inf value
  9. fix atomic condition for havel element basis

# other improvement

  1. make mmclab compatible with older version of MATLAB
  2. fix mmclab for octave crash due to an octave bug #48678
  3. fix normalization, validation of dmmc
  4. for windows MMCLAB packages, we included the necessary DLLs in the package

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.

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.

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