Release Notes for Monte Carlo eXtreme v2018 (1.0.0)

Code name: Dark Matter, released on August 20, 2018

Click this link to download MCX 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 v2017.7
4. System requirements
5. Reference

0. Opening Remarks

After nearly 10 years continuous development, it is our great pleasure to announce that MCX 1.0 (v2018) has finally arrived! This release represents an important milestone for the MCX project, and signifies that MCX 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 transparency and openness.

Today, we celebrate MCX 1.0, we thank all the hard-works from the developers' team, particularly those PhD students who had made MCX a fast and better software - Fanny Nina-Paravecino, Leiming Yu, Ruoyang Yao, Yaoshen Yuan, and Shijie Yan, as well as the continual support and guidance from collaborators, Dr. David Kaeli and Dr. Xavier Intes. 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 MCX 2.0! We will continue accelerating our software by taking advantage of emerging GPU architectures, new hardware resources and algorithm optimizations, in the meantime, focusing on usability and broader dissemination.

1. Introduction

Monte Carlo eXtreme, or MCX, is an ultra-fast Monte Carlo light transport simulator for arbitrary 3D random media. It uses Graphics Processing Units (GPU) to run thousands of photons simultaneously, and is typically hundreds or thousands times faster than a single-threaded CPU-based simulation.

This release fully supports all major NVIDIA GPU architectures ranging from Fermi, Kepler, Maxwell, Pascal, and Volta, as well as future generations. The speed comparisons between different generations of NVIDIA GPUs can be found at

2. About this release

MCX v2018 (code named "Dark Matter") contains numerous improvements developed over the past 13 months, including a long list of new features and bug fixes. If you are currently using a previous release, you are urged to upgrade immediately to avoid using incorrect results.

In this new release, the most notable update is an easy-to-download, ready-to-use all-in-one MCXStudio package that combines all MC modeling tools we have developed, including MCX, MMC, MCX-CL, MCXLAB, MMCLAB and MCXLAB-CL. All modules are cleanly organized, fully tested and integrated, and can be called individually from the command line, via mcxstudio GUI or inside MATLAB/Octave. A unified package makes distributing and setting up MCX and associated software easier for a first-time user.

The cross-platform graphical user interface, mcxstudio, as part of the MCXStudio package, also received numerous updates, and was forged over the past year as a result of two MCX Training Workshops (MCX'17 and MCX-OSA'18). This GUI program has served our main tool for training users, and was heavily tested before and during the workshops. The GUI program unified the input parameters of all supported modules (MCX, MMC, MCX-CL) and added built-in domain visualization tool and volume rendering scripts (via MATLAB/Octave). Video tutorials of this tool can be browsed at the below link

Three critical bugs have been fixed -

  • one bug (Issues #17,#26,#29,#31) impacts all Windows users by generating low-quality random numbers and creating visible artifacts in wide-field simulations,
  • another one (#41) impacts all simulations involving large photon numbers (for example 1e8-1e9) by loosing intensity near the source.
  • the other bug impact all wide-field sources located outside of a refractive-index mismatched medium.

All three bugs have broad impact and all users are recommended to upgrade immediately to avoid using erroneous simulations.

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

3. What's new compared to v2017.7

Compared to the previous release (version v2017.7, released in July 2017), MCX v2018 gains the following new features and bug fixes:

  1. !!key!! mcx: fully validated replay feature (BOE paper in press)
  2. !!key!! mcx: use integer for media data, supporting up to 4000 tissue types (up from 128)
  3. !!key!! mcx: support 2D simulations
  4. !!key!! mcx: support simulations for DCS
  5. !!key!! mcx: added new pattern3d source
  6. !!key!! mcx: support photon number larger than 2^31-1 (new limit 2^63-1)
  7. !!key!! mcx: replay all detectors for full Jacobian using -Y -1
  8. !!key!! mcx: support mirror (perfectly reflecting) boundary condition
  9. !!key!! mcx: add doxygen-format comments for thorough documentation of the source code
  10. !!key!! mcx: positive respin (-r) now means repeat - to run more photons; negative respin means divide
  11. !!key!! mcx, mcxlab: output photon trajectories and save as .mct file
  12. !!key!! mcxlab: avoid "static TLC error" on newer MATLABs
  13. !!key!! mcxlab: display progress bar
  14. !!key!! mcxlab: return detected photon info using sufields
  15. !!key!! mcxlab: mcxpreview for previewing domain settings
  16. !!key!! mcxlab: exporting matlab cfg input to JSON file for mcx binary
  17. !!key!! mcxstudio: domain visualization, unified parameters, high-dpi display support
  18. !!key!! mcxstudio: true remote execution across separate machines
  19. mcxstudio: plot volume using matlab on windows
  20. mcx: fix diffuse reflectance bug - must be performed after boundary reflection
  21. mcx: added new RNG xoroshiro128+
  22. mcxlab: buildin tool to load nifti volumes
  23. mcxstudio: now compatible with mmc and mcxcl
  24. mcx: all important command line flags can be set in the JSON file

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

  1. !!key!! mcx, mcxlab: fixing low-quality random number generator on Windows; impacting all simulations using Windows
  2. !!key!! mcx, mcxlab: fixing high accumulation error when running large number of photons (for example 1e8-1e9)
  3. !!key!! mcx, mcxlab: fixing incorrect energy loss, impacting all wide-field sources
  4. mcx: fix volume mask saving bug
  5. mcxlab: fix mcxlab for octave crash due to an octave bug #48678
  6. mcx: fix crash when saving diffuse reflectance
  7. mcx,mcxlab: fix normalization bug in replayall mode

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, Maxwell, Pascal and Volta GPUs.

All released binaries are compiled and linked with CUDA 7.5 (which is "embedded" into the binary) due to faster speed. All pre-compiled binaries are meant to be executable out-of-box.

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 v2018, you need

  • a CUDA-enabled graphics card made by NVIDIA (essentially all GPUs made by NVIDIA today)
  • the latest graphics driver for your graphics card

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.

5. Reference

Powered by Habitat