Release Notes for Monte Carlo eXtreme v2017.3

Code name: Dark Matter, released on April 2, 2017

Click this link to download MCX v2017.3

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

1. Introduction
2. About this release
3. What's new compared to v2016.4
4. System requirements
5. Reference

1. Introduction

Monte Carlo eXtreme, or MCX, is a fast Monte Carlo software package for photon transport simulation in 3D heterogeneous media. It uses Graphics Processing Units (GPU) for massively parallel simulations and offers hundreds times acceleration compared to a traditional single-threaded CPU-based simulation.

This release fully supports NVIDIA Pascal GPUs. The speed comparisons between different generations of NVIDIA GPUs can be found at

2. About this release

MCX v2017.3 (code named "Dark Matter") is a Release Candidate for MCX v1.0. It is a result of numerous improvements developed over the past year, and contains a list of new features and bug fixes. If you are using a previous release, you are strongly recommended to upgrade immediately.

In this new release, MCX adds support for a number of highly requested features, such as recording diffuse reflectance, saving photon exit position/direction, showing progress bar, and supporting converting and diverging widefield beams. It has also been carefully optimized to obtain better speed on a modern GPU. Using various GPU programming techniques (including C++ template, branch divergence removal etc), we have managed to further improve the MCX speed by 1.7-2.5 fold for Kepler, Maxwell and Pascal GPUs.

The MCX/MCXLAB software in this release was also improved in portability. We have developed automated compilation scripts that work seamlessly on Windows, Linux and Mac OS. Starting from Apr. 2016, we have announced and enabled a nightly-build service - the latest MCX/MCXLAB source codes are downloaded, compiled and packaged everyday - to bring our latest development to the user community in a timely manner.

The nightly-build software repository can be found at

Please visit our website ( for more detailed documentation, demos and tutorials.

3. What's new compared to v2016.4

Compared to the previous release (version v2016.4, released in Apr. 2016), MCX v2017.3 gains the following new features and bug fixes:

  1. !!key!! record diffuse reflectance/transmittance
  2. !!key!! save detected photon position and direction using -x 1
  3. !!key!! save photon trajectories -D M
  4. !!key!! support diverging and converging widefield source beams
  5. !!key!! show simulation progress bar using -D P
  6. !!key!! enable autobuild in Windows and Linux and Mac OSX
  7. !!key!! photon "replay" for building mua and mus Jacobians (paper submission pending)
  8. !!key!! support Pascal GPUs
  9. !!key!! significant (1.5-2.5x) speed improvement for Kepler, Maxwell and Pascal GPUs
  10. use c++ template to avoid branching in launchnewphoton (Gustavo Maia and Fanny Paravecino)
  11. support Russian roulette
  12. elegantly terminate mcxlab when an exception is raised

In the meantime, a number of critical bugs were fixed:

  1. fix a bug to avoid hanging in mcxlab when mus=0
  2. fix voxel [0 0 0] is always zero bug, regression since v2016.4
  3. remove -code flags to create arch independent binaries, it also produces faster binaries with cuda 7.5
  4. fix workload and gpuid bug when handeling 0 masks
  5. fix multi-GPU hanging problem
  6. ignore user specified nonexistent devices in workload calculations
  7. fix Gaussian beam waist radius scaling issue

Pre-compiled MCX are provided for Windows (64 bit), Linux (64bit) and Mac OS (64bit). In the case of MCXLAB, mex files for both Matlab and Octave on these platforms are provided. All binaries have been tested on Fermi/Kepler and Maxwell GPUs.

The provided binaries require a Fermi (Compute Capability 2.0) or newer GPU. If you have an older GPU (CC 1.0 or 1.1), you will have to recompile mcx using "make fast".

The detailed change logs can be found in the ChangeLog and Github commit history pages.

4. System requirements

To install MCX version v2017.3, you need

  • a CUDA-enabled graphics card made by NVIDIA, a full list of supported cards can be found here
  • a computer running GNU/Linux, Windows or Mac OS

The CUDA toolkit is no longer required in this release, however, if you run into CUDA errors, please download the latest CUDA driver, you can download from here

In this release, all precompiled binaries, including both mcx executables and mcxlab mex files, have built-in CUDA run-time libraries via static linking. Therefore, downloading/setting CUDA toolkit and the run-time librarie files (cudart.dll/ are no longer needed.

However, if you run into CUDA errors, please first try to update your NVIDIA graphics driver to the latest version

If the latest graphics driver still can not solve the problem, please download the "developer driver" for your GPU. You may download the developer driver as part of the CUDA Toolkit installation package.

To use MCXLAB v2017.3 in GNU Octave, you must install the following:

  • GNU Octave
  • libblas, libgfortran and libhdf5

Be aware, if you have a Maxwell GPU (GTX 980Ti and 980) and plan to run MCX on it, please first test the benchmark script "" or "run_benchmark1.bat" under the mcx/example folder. You are expected to see ~29,000 photon/ms for 980Ti and 20,000 photon/ms for 980. If your simulation speed is around 1,200 to 1,500 photon/ms, that means you are impacted by a bug in the CUDA driver. Please recompile MCX using CUDA 7.0 or 6.5, update your NVIDIA driver to version 375 or later. For details, please see

5. Reference

Qianqian Fang and David A. Boas, "Monte Carlo Simulation of Photon Migration in 3D Turbid Media Accelerated by Graphics Processing Units," Opt. Express, vol. 17, issue 22, pp. 20178-20190 (2009)

Powered by Habitat