Release Notes for Monte Carlo eXtreme - OpenCL v2024.2 (1.2)

code name: Genesis, released on March 15, 2024

Click this link to download MCX-CL/MCXLAB-CL v2024.2

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

MCX-CL v2024.2 contains both new major features and critical bug fixes. It is a strongly recommended upgrade for all users.

Specifically, MCX-CL v2024.2 received two important features ported from MCX:

  • user-defined scattering phase function (fangq/mcx#129) and
  • user-defined photon launch angle distribution (fangq/mcx#13)

The first feature allows users to define a scattering zenith angle distribution via a discretized inverse CDF (cumulative distribution function). The second feature allows users to define the zenith angle distribution for launching a photon, relative to the source-direction vector, also via a discretized inverse CDF. In MATLAB/Octave, they can be set as cfg.invcdf or cfg.angleinvcdf, respectively. We provided ready-to-use demo scripts in mcxlabcl/examples/demo_mcxlab_phasefun.m and demo_mcxlab_launchangle.m.

Additionally, in this release, we further improved the simulations when using Intel CPU or integrated GPU.

Aside from new features, a severe bug was discovered that affects all pattern and pattern3d simulations that do not use photon-sharing, please see

https://github.com/fangq/mcx/issues/212

Because of this bug, MCX/MCX-CL in older releases has been simulating squared pattern/pattern3d data instead of the pattern itself. If your simulation uses these two source types and you do not use photon-sharing (i.e. simulating multiple patterns together), please upgrade your MCX/MCX-CL and rerun your simulations. This bug only affect volumetric fluence/flux outputs; it does not affect diffuse reflectance outputs or binary patterns.

We also ported a bug fix from fangq/mcx#195 regarding precision loss when saving diffuse reflectance. Finally, starting from this release, we are providing native binary packages built for Apple M1/M2 (arm64) processors. All Apple silicon packages are labeled with macos-arm64 in the package names.

We want to thank Haohui Zhang for reporting a number of critical issues (fangq/mcx#195 and fangq/mcx#212). ShijieYan and fanyuyen have also contributed to the bug fixes and improvements.

The detailed updates can be found in the below change log

  • 2024-03-12 [1fc8286] [ci] building binaries on Apple M1 macos-14 runner
  • 2024-03-12 [bf89aff] [ci] update nightly build script
  • 2024-03-08 [4891c72] [ci] remove mcxlabcl gcc warnings
  • 2024-03-05 [80551a4] [bug] remove duplicated and overwritten cfg initialization
  • 2024-03-04 [84c64ec] [bug] fix cuda core count for Ada and Blackwell
  • 2024-03-01 [1e56f5b] [doc] update documentation for v2024.2
  • 2024-03-01 [d4fb874] [ci] bump pmcxcl to v0.1.6
  • 2024-03-01 [0d9f77f] [doc] update neurojson website url to https://neurojson.io
  • 2024-02-29 [580cb27] [format] reformat all MATLAB codes with miss_hit
  • 2024-02-29 [ce1d374] [bug] fixes to pass tests on Intel CPU, AMD GPU and pthread-AMD
  • 2024-02-29 [2f70174] [bug] free ginvcdf and gangleinvcdf buffers
  • 2024-02-29 [9aee8ce] [bug] fix many errors after testing, still need to fix replay
  • 2024-02-29 [b82c856] [feat] add missing demo scripts
  • 2024-02-29 [21e1e72]*[feat] port scattering and launch angle invcdf from fangq/mcx#129 fangq/mcx#13
  • 2024-02-28 [90a28f3] [ci] remove macos-11 as brew fails for octave, Homebrew/brew#16209
  • 2024-02-28 [fbe270b] [pmcxcl] bump pmcxcl to 0.1.4 after fixing fangq/mcx#212
  • 2024-02-27 [4e1ec7f] [ci] fix windows cmake zlib error, fix mac libomp error
  • 2024-02-27 [3d18b78]*[bug] fix critical bug, squaring pattern/pattern3d, fangq/mcx#212
  • 2023-11-10 [26ec422] [ci] install mingw 8.1 for matlab mex build, matlab-actions/setup-matlab#75
  • 2023-11-10 [5a96d02] [ci] set MW_MINGW64_LOC to octave bunded mingw, matlab-actions/setup-matlab#75
  • 2023-10-31 [337c51c] [bug] apply fangq/mcx#195 fix to avoid dref accuracy loss
  • 2023-10-29 [3b01475] further simplify bc handling, #47
  • 2023-10-29 [f816140] latest matlab fails to respect MW_MINGW64_LOC on windows, use R2022a
  • 2023-10-29 [adc0316] simplify boundary condition handling, fix #47
  • 2023-10-07 [04a7155] bump pmcxcl to 0.1.3
  • 2023-10-07 [e930448] remove opencl jit warnings, adjust optlevel order
  • 2023-10-07 [1a30e5c] update copyright dates
  • 2023-10-07 [dcdb117] fix unitinmm double-scaling bug, close #46, close #45
  • 2023-10-03 [fa8dbb2] fix bc mcxlab/pmcxcl memory error,fangq/mcx#191,fangq/mcx#192
  • 2023-09-29 [aa5da8c] fix -F flag overwrite bug
  • 2023-09-26 [507b37b] fix continuous media scaling issue,pmcxcl 0.1.2, fangq/mcx#185
  • 2023-09-26 [378f4eb] fix group load balancing for --optlevel 4
  • 2023-09-24 [07bc297] additional patch to handle half-formatted cont. media

2. Introduction

Monte Carlo eXtreme (MCX) is a fast physically-accurate photon simulation software for 3D heterogeneous complex media. By taking advantage of the massively parallel threads and extremely low memory latency in a modern graphics processing unit (GPU), this program is able to perform Monte Carlo (MC) simulations at a blazing speed, typically hundreds to a thousand times faster than a single-threaded CPU-based MC implementation.

MCX-CL is the OpenCL implementation of the MCX algorithm. Unlike MCX which can only be executed on NVIDIA GPUs, MCX-CL is written in OpenCL, the Open Computing Language, and can be executed on most modern CPUs and GPUs available today, including Intel and AMD CPUs and GPUs. MCX-CL is highly portable, highly scalable and is feature-rich just like MCX.

MCX-CL shares nearly identical command line options and input file formats as MCX. The simulation settings designed for MCX can be simply used for MCX-CL simulations without major modifications. As of v2020, MCX-CL contains almost all features currently supported in MCX (with additional support of AMD/Intel CPUs and GPUs as well as JIT compilation and -J flag).

Similar to MCXLAB, MCXLAB-CL is the MATLAB mex version of the MCXCL software. It can be directly called inside MATLAB and GNU Octave. It also uses the same input structure settings as in MCXLAB, making both packages highly compatible. One can even define USE_MCXCL=1 in MATLAB command window, and all MCXLAB calls will call MCXLAB-CL automatically.

3. System requirements

By default, MCX-CL uses OpenCL-based simulations to utilize all GPUs and CPUs installed on your system. If you have a GPU (NVIDIA, AMD or Intel), 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

Step-by-step installation guide can be found in this link.

4. Reference

Powered by Habitat