Showing revision 1.0

Release Notes for Mesh-based Monte Carlo 2.8 (v2025.10)

code name: Bubble Tea, released on October 12, 2025

Click this link to download MMC/MMCLAB v2025.10

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

1. What's New
2. Introduction
3. System requirements
4. Reference

1. What's New

MMC v2025.10 (2.8.0) is a maintenance release with multiple bug fixes and new features. It is highly recommended to upgrade for all users.

MMC v2025.10 adds the below key features

  • new Python module - pmmc (pip install pmmc)
  • pmmc supports Apple silicon
  • pmmc integrates with pyiso2mesh (pip install iso2mesh)
  • support focal length via cfg.srcdir(4), fix #108
  • support isotropic (cfg.srcdir(4)=nan) and Lambertian launch (cfg.srcdir(4)=-inf)
  • make implicit MMC (immc) available on OpenMP-only builds, such as Apple silicon (where SSE is not supported)
  • enable level-3 optimization (--optlevel 3) by default, accelerating simulations by 30%-100%

this release also fixed a list of bugs, including

  • fix a critical-level bug related to fluence normalization - affect all simulations starting v2025
  • fix a "photon-leakage" bug in implicit MMC (immc) #76
  • fix the 2nd-neighboring element search in implicit MMC (immc)
  • fix incorrect node passing to OpenCL kernel, fix #109
  • fix roulettesize type in OpenCL bug, fixed by Aiden Lewis
  • remove outdated replay preprocessing, use mcx workflow, fix #110
  • allow widefield source to search cfg->e0 first before searching srcelem

The full changelog is listed below

  • 2025-10-02 [cc5179c] [doc] update doc for v2025.10, bump pmmc to 0.3.5
  • 2025-10-02 [7dd25d9] [bug] enable immc in omp only mode on Apple silicon, fix memory error when r->nexteid
  • 2025-10-02 [d21587a] [bug] build immc in omp mode without sse, such as on Apple silicon, result incorrect
  • 2025-10-02 [c2cbc3b] [amd] fix one more warning
  • 2025-10-02 [7f1b47e] [amd] remove jit warnings
  • 2025-10-02 [8d0c19d] [bug] critical bug fix - incorrect energytot and energyesc introduced in commit 072fafe4305cd3c2da78094b0622dc4c67267983 Oct 14 2024
  • 2025-10-01 [2f81f87] [clang] silence clang warnings, make optlevel 3 default with macros
  • 2025-09-29 [63b48a6] [bug] add the missing gcfg constants when using -o 4 optimization
  • 2025-09-27 [2649e36] [doc] update documentation for v2025.10
  • 2025-09-19 [74191ba] [ci] avoid using slow choco octave installation
  • 2025-09-15 [688c1ba] [feat] support focal length via cfg.srcdir(4), fix #108
  • 2025-08-25 [38f8e8a] [pmmc] bump version to 0.3.0 to include expanded mcx utils functions
  • 2025-08-21 [c085223] [pmmc] bump pmmc to v0.2.6 to include the bug fixes for immc
  • 2025-08-21 [3ab80db] [ci] adjust pybind11 version for various python
  • 2025-08-21 [aaf588c] [ci] avoid pybind11 upgrade for python 3.6
  • 2025-08-21 [6d93cd6] [ci] fetch tags before checking out specific version
  • 2025-08-21 [1d9b118] [ci] downgrade pybind11 to v2 to avoid ci errors
  • 2025-08-20 [0c43144] [bug] fix immc photon leakage from edge cases in tracer #76
  • 2025-08-18 [0d3cf79] [bug] fix 2nd neighbor element ID referencing, fixing notch artifact thanks to the debugging info provided by Aiden Lewis
  • 2025-07-30 [0798ba2] [format] reformat c and matlab with formatters
  • 2025-07-30 [f80d541] [bug] remove outdated replay preprocessing, use mcx workflow, fix #110
  • 2025-07-19 [f86c824] [ci] upload updated pmmc for apple silicon, bump 0.2.5
  • 2025-07-19 [3d6803a] [ci] build pmmc on apple silicon
  • 2025-07-19 [97543d3] [pmmc] statically link with libomp, build on apple silicon
  • 2025-07-19 [7328d46] [pmmc] use libgomp-1.dll from sparse_numba, bump to 0.2.4
  • 2025-07-18 [a808bd1] [ci] update pmmc version to use statically linked _pmmc module
  • 2025-07-18 [7c97cf0] [ci] install intel opencl runtime on windows 2022
  • 2025-07-18 [8923673] [ci] print verbose info to debug windows pmmc wheel build
  • 2025-07-18 [e68a427] [bug] allow widefield source to search cfg->e0 first before searching srcelem
  • 2025-07-17 [16031dd] [ci] build windows wheels for python 3.13, bump version 0.2.2
  • 2025-07-17 [504730f] [ci] only update pybind11 for 3.13
  • 2025-07-17 [542ae94] [ci] check out submodule
  • 2025-07-16 [792f809] [ci] use git version of pybind11 for windows pmmc build
  • 2025-06-25 [24dab0b] [ci] remove windows python 3.13 build due to errors
  • 2025-06-25 [7607095] [pmmc] bump to 0.2.1, add iso2mesh example, add 3.13 on win
  • 2025-06-25 [65642f1] [bug] fix roulettesize type in OpenCL bug, fixed by Aiden Lewis
  • 2025-06-07 [a69ed21] [pmmc] first fully working version, bump to v0.2.0
  • 2025-06-07 [e6b6540] [pmmc] fix pyvista tetgen mesh bug, need to flip element
  • 2025-06-07 [40ab888] [pmmc] bump version to 0.1.0
  • 2025-06-07 [b104d02] [ci] fix macos pmmc
  • 2025-06-07 [031cc06] [ci] macos pmmc build missing omp.h
  • 2025-06-07 [8e06991] [ci] fix windows pmmc build
  • 2025-06-07 [d747603] [ci] macos pmmc build error
  • 2025-06-07 [a3342d8] [ci] remove ubuntu-20.04 from linux, debug macos pmmc build
  • 2025-06-07 [98a11dc] [ci] debug windows and macos pmmc build
  • 2025-06-07 [f910e0a] [ci] try fixing macos build
  • 2025-06-07 [12346b7] [ci] build pmmc
  • 2025-06-07 [5ef7a78] [pmmc] version 0.0.1
  • 2025-06-06 [edacffb] [pmmc] fix memory error, runs locally
  • 2025-06-06 [a537219] [bug] fix some run time bugs, still crashes
  • 2025-06-05 [ef159b8] [pmmc] make pmmc module loadable in python3
  • 2025-06-05 [09d2499] [pmmc] fix all compilation errors
  • 2025-06-05 [eb0a506] [feat] initial units for pmmc
  • 2025-05-20 [b85e750] [bug] fix incorrect node passing to OpenCL kernel, fix #109

2. Introduction

Mesh-based Monte Carlo (MMC) is a 3D Monte Carlo (MC) simulation software for photon transport in complex turbid media. MMC combines the strengths of the MC-based technique and the finite-element (FE) method: on the one hand, it can handle general media, including low-scattering ones, as in the MC method; on the other hand, it can use an FE-like tetrahedral mesh to represent curved boundaries and complex structures, making it even more accurate, flexible, and memory efficient. MMC uses the state-of-the-art ray-tracing techniques to simulate photon propagation in a mesh space. It has been extensively optimized for excellent computational efficiency and portability. MMC currently supports multi-threaded parallel computing via OpenMP, Single Instruction Multiple Data (SIMD) parallelism via SSE and, starting from v2019.10, OpenCL to support a wide range of CPUs/GPUs from nearly all vendors.

To run an MMC simulation, one has to prepare an FE mesh first to discretize the problem domain. Image-based 3D mesh generation has been a very challenging task only until recently. One can now use a powerful yet easy-to-use mesh generator, iso2mesh [1], to make tetrahedral meshes directly from volumetric medical images. You should download and install the latest iso2mesh toolbox in order to run the build-in examples in MMC.

The most relevant publication describing this work is the GPU-accelerated MMC paper:

Qianqian Fang and Shijie Yan, "GPU-accelerated mesh-based Monte Carlo photon transport simulations," J. of Biomedical Optics, in press, 2019. Preprint URL: https://www.biorxiv.org/content/10.1101/815977v1

Please keep in mind that MMC is only a partial implementation of the general Mesh-based Monte Carlo Method (MMCM). The limitations and issues you observed in the current software will likely be removed in the future version of the software. If you plan to perform comparison studies with other works, please communicate with the software author to make sure you have correctly understood the details of the implementation.

The details of MMCM can be found in the following paper:

Qianqian Fang, "Mesh-based Monte Carlo method using fast ray-tracing in Plücker coordinates," Biomed. Opt. Express 1, 165-175 (2010) URL: https://www.osapublishing.org/boe/abstract.cfm?uri=boe-1-1-165

While the original MMC paper was based on the Plücker coordinates, a number of more efficient SIMD-based ray-tracers, namely, Havel SSE4 ray-tracer, Badouel SSE ray-tracer and branchless-Badouel SSE ray-tracer (fastest) have been added since 2011. These methods can be selected by the -M flag. The details of these methods can be found in the below paper

Qianqian Fang and David R. Kaeli, "Accelerating mesh-based Monte Carlo method on modern CPU architectures," Biomed. Opt. Express 3(12), 3223-3230 (2012) URL: https://www.osapublishing.org/boe/abstract.cfm?uri=boe-3-12-3223

and their key differences compared to another mesh-based MC simulator, TIM-OS, are discussed in

Qianqian Fang, "Comment on 'A study on tetrahedron-based inhomogeneous Monte-Carlo optical simulation'," Biomed. Opt. Express, vol. 2(5) 1258-1264, 2011. URL: https://www.osapublishing.org/boe/abstract.cfm?uri=boe-2-5-1258

In addition, the generalized MMC algorithm for wide-field sources and detectors are described in the following paper, and was made possible with the collaboration with Ruoyang Yao and Prof. Xavier Intes from RPI

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) URL: https://www.osapublishing.org/boe/abstract.cfm?uri=boe-7-1-171

In addition, we have been developing a fast approach to build the Jacobian matrix for solving inverse problems. The technique is called "photon replay", and is described in details in the below paper:

Yao R, Intes X, Fang Q, "A direct approach to compute Jacobians for diffuse optical tomography using perturbation Monte Carlo-based photon 'replay'," Biomed. Optics Express, in press, (2018)

In 2019, we published an improved MMC algorithm, named "dual-grid MMC", or DMMC, in the below JBO Letter. This method allows to use separate mesh for ray-tracing and fluence storage, and can be 2 to 3 fold faster than the original MMC without loss of accuracy.

Shijie Yan, Anh Phong Tran, Qianqian Fang*, "A dual-grid mesh-based Monte Carlo algorithm for efficient photon1transport simulations in complex 3-D media," J. of Biomedical Optics, 24(2), 020503 (2019).

The authors of the papers are greatly appreciated if you can cite the above papers as references if you use MMC and related software in your publication.

3. System requirements

Although MMC/MMCLAB can be executed independently if 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.

By default, MMC/MMCLAB uses OpenCL-based simulations to utilize all GPUs and CPUs installed on your system. If you have a GPU (NVIDIA, AMD or Inel), the OpenCL support is typically installed if you have correctly installed the latest version of the graphics driver. Please verify that the OpenCL library (libOpenCL.so* on Linux, OpenCL.dll on Windows or /System/Library/Frameworks/OpenCL.framework/Versions/A/OpenCL on the Mac) must exist in your system.

Generally speaking, AMD and NVIDIA high-end dedicated GPU performs the best, about 20-60x faster than a multi-core CPU; Intel's integrated GPU is about 3-4 times faster than a multi-core CPU.

In addition, MMC has been fully tested with the open-source OpenCL runtime pocl (http://portablecl.org/) on the CPU. To install pocl on a Ubuntu/Debian system, please run 

  sudo apt-get install pocl-opencl-icd

If you happen to use a system that does not have OpenCL support, you may still use MMC/MMCLAB by calling it in the CPU-only SSE4 mode, with -G -1 or cfg.gpuid=-1. To verify your CPU supports SSE4, please run 

  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.

4. Reference

Powered by Habitat