Showing revision 1.0

Release Notes for Monte Carlo eXtreme - OpenCL v2018

code name: Sachima, released on August 20, 2018

Click this link to download MCX-CL/MCXLAB-CL v2018

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

0. Opening Remarks

We are proud to share with you that the first official release of MCX-CL (v2018) is finally here! MCXCL is the first reported general purpose OpenCL-based MC simulator for photon transport modeling. It extends our GPU accelerated MC work (MCX) from NVIDIA-only hardware to nearly all mainstream CPUs and GPUs that are available today. The portability and scalability of MCXCL is unprecedented - it runs on Intel CPUs, Intel's integrated GPUs, almost all AMD CPUs and GPUs as well as NVIDIA GPUs currently in production (and future generations). If your processor has four cores, MCXCL will happily use all 4; if it has 4000 cores, MCXCL will make use of all of them too without needing to change one line of code. It not only can run on different processors made by different vendors, but also can run simulations on multiple of them, even mixing CPUs and GPUs, to maximize throughput.

Although the initial working version of MCX-CL was coded back in 2010, we have been continuously developing, studying, optimizing this unique software and keeping it in sync for every new feature we added to it's CUDA sibling, MCX. Over the past two years, we have been systematic studying and benchmarking MCXCL and optimize its performance. The results of these investigations were summarized in a JBO Letter paper we published earlier this year

We demonstrated that MCXCL can get impressive speedup, similar to MCX, when running on a high-performance GPU; even running it on a multi-core CPU can be faster than other existing CPU-only MC codes. We also showed our GPU optimization methods, load-balancing strategies as well as benchmark results across many different processors.

As of today, MCXCL has most core features as in MCX - wide-field illumination, 3D arbitrary media, partial-path length and detected photon data storage, matlab mex file, JSON input, and many more. In fact, both MCXCL binary and MCXLAB-CL share nearly identical input parameters and interface as their CUDA counterparts. An input file that works for MCX can be directly executed using MCXCL and MCXLAB-CL without change.

1. Introduction

MCX-CL (or MCX for OpenCL) is a high-performance, highly scalable and general-purpose Monte Carlo photon transport simulator for biophotonics applications. Compared to MCX (implemented with NVIDIA CUDA), MCXCL is written in the OpenCL framework, and is capable of launching parallel photon simulations on most modern CPUs and GPUs produced by many vendors, including NVIDIA, AMD and Intel.

MCXLAB-CL is the MATLAB mex version of the MCXCL software. It can be directly called inside MATLAB.

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

3. 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:

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

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

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