uMCX (umcx) - GPU-accelerated 3D Monte Carlo photon simulator in less than 1000 lines

v0.5.0

Author: Qianqian Fang (q.fang at neu.edu)
License: GNU General Public License version 3 (GPLv3)
Version: 0.5.0 (Boxer Crab)
Website: https://mcx.space/umcx
Part of: the MCX suite v2026, https://mcx.space

Download

Pre-compiled packages (umcx and umcxlab, for Linux, Windows and macOS x86_64/arm64): umcx-<os>-<arch>-v2026.zip at https://mcx.space/nightly/release/v2026/
Also included in every MCX Studio package of the v2026 release, and in the Windows installer
Release notes of the MCX suite: https://mcx.space/wiki/index.cgi?Doc/ReleaseNotes/v2026

Special thanks

We would like to thank Mat Colgrove (@MatColgrove, NVIDIA) for showing on the NVIDIA developer forum how
to map the nested dynamic arrays of a class to the GPU with OpenMP, which made the first working
nvc++ GPU build possible

What's New

uMCX (umcx) v0.5.0 (Boxer Crab) is the first release of a miniaturized,
maximally portable Monte Carlo photon transport simulator, released together
with MCX, MCX-CL and MMC v2026 as part of the MCX suite. It implements the
core of MCX, 3D voxel-based Monte Carlo photon simulation of heterogeneous
turbid media with JSON input and output, in a single C++11 source file of
fewer than 1000 lines after rule-based formatting, with GPU acceleration
through standard OpenMP 4.5 target offloading or OpenACC 2.0 in place of
vendor-specific languages. The same code builds for multi-core CPUs, NVIDIA
GPUs (with nvc++, GCC or Clang) and AMD GPUs (with ROCm Clang), and is
written to be read, modified and adapted, as a starting point for new Monte
Carlo methods and for teaching.

umcx reads MCX's JSON input, including JData-encoded and compressed volumes,
runs MCX's built-in benchmarks, and writes MCX-compatible JData (JNIfTI/BNII)
outputs, so existing MCX simulations run with minimal modification. umcxlab,
its MATLAB/Octave mex interface, accepts mcxlab-style cfg structures.

Notable features of this release include:

3D voxel-based photon Monte Carlo with multi-region heterogeneous domains,
refractive-index mismatch with Fresnel reflection and refraction at
boundaries, and the Henyey-Greenstein phase function
pencil, isotropic, cone, disk, planar and Fourier sources, including
wide-field launch
time-gated simulations, volumetric fluence-rate, fluence or energy
deposition output, normalization, and photon detection with partial path
lengths (for DRS/DCS)
JSON and binary JData (BJData/BNII) input and output compatible with MCX,
compressed JData input (_ArrayZipData_, via the header-only zmat), and
MCX-style JSON shapes
MCX's built-in benchmarks (-Q/--bench) and online simulations from
NeuroJSON.io (-N/--net)
MCX-compatible command-line options, including -n, -f, -j, -b,
-t/-T/-G, -O, --session, --dumpjson and --dumpmask
GPU offloading by OpenMP 4.5 target or OpenACC 2.0 (make ACC=on); the
run's seeds are derived with std::mt19937, independent of the C library
umcxlab, the MATLAB/Octave mex of umcx, built and packaged for every
platform; the release packages carry the multi-core CPU build of umcx,
and GPU builds are compiled with make nvc, make nvidia,
make nvidiaclang or make amdclang

Supported compilers and hardware

CPU (multi-core): g++ 12 or newer (make/make multi)
NVIDIA GPUs: nvc++ with OpenMP or OpenACC (make nvc), GCC nvptx
offloading (make nvidia), Clang nvptx64 offloading (make nvidiaclang)
AMD GPUs: ROCm clang++ 17 or newer (make amdclang); GCC's amdgcn
offloading (make amd) is broken by a GCC 13 runtime bug
CMake builds for every target, and a MATLAB mex build (make mex)

The detailed updates can be found in the below change log

2026-10-31 [f33ba5f] Merge branch 'umcxlab-pkg': build and package umcxlab, std::mt19937 host seeds
2026-10-31 [fb359ca] [feat] derive the run's seeds with std::mt19937 instead of the C library rand()
2026-10-31 [ac630c2] [doc] help: align the -Q/--bench description with the other flags
2026-10-31 [8f96a62] [feat] build and package umcxlab, the MATLAB/Octave mex of umcx
2026-10-30 [6c98bae] [doc] help: print the version and code name, copyright to 2026
2026-10-28 [4e32a0f] [doc] use an ASCII parenthesis in the version line of README
2026-10-27 [7006af4] [ci] drop umcx_amd from the Linux release package, avoid patchelf padding
2026-10-27 [0fe693a] [ci] bump actions/checkout to v4 (v3 runs on the deprecated Node.js 20)
2026-10-27 [4535c69] [ci] use matlab-actions v2 and tolerate license failures when running the mex test, like mcx
2026-10-27 [19b93c2] [bug] copy a photon template in the loop: gcc nvptx can not emit its constructor
2026-10-27 [7cf861a] [ci] link GCC runtime statically, add portable macOS and Windows packages
2026-10-27 [45b6724] [ci] build portable Linux release package with nvc++ (umcx) and ROCm clang (umcx_amd)
2026-10-27 [26d9d48] [test] add unit tests, libFuzzer target and code coverage
2026-10-27 [19b4b5b] [bug] fix memory errors, hangs and wrong results found by unit tests and fuzzing
2026-06-26 [86944c9] [ci] force nvc produce code x86-64 target to avoid landing on avx-512 node
2026-05-31 [742cc3e] [bug] fix typo in Box shape parser, close #3
2026-05-10 [27817ad] [umcxlab] fix binary json function name
2026-05-09 [b030db1] [ci] fix single-element Shapes being flattened
2026-05-09 [20131f8] [ci] disable compression in passing bjdata cfg to umcx
2026-05-09 [07ba3fb] [ci] use the matching libstdc++
2026-05-09 [b42bf22] [ci] fix matlab mex test; add colin27 and digimouse
2026-05-09 [54d5c5d] [ci] build matlab mex file and run test
2026-05-09 [780987b] [ci] only keep linux nvc tests
2026-05-09 [2d17a28] [ci] add make nvc tests
2026-05-09 [c2c95da] [ci] fix g++-11 build error as only sm_35 is supported
2026-05-09 [48a0d26] [normalization] return total launched photon and properly normalize fourier src
2026-05-09 [f11ec8c] [ci] fix g++-11 build errors
2026-05-09 [a95c9a3] [normalization] restore only returning energyescape, g++ nvidia builds but wrong results
2026-05-08 [306f341] [ci] use array wrap to fix g++-12 error
2026-05-08 [4ddded6] [ci] bypass g++-11 nvptx test, too buggy
2026-05-08 [f4e971c] [ci] fix gcc nvptx segfault by mapping energytotal to device
2026-05-07 [fe9c939] [ci] fix gcc nvptx offloading linking error
2026-05-06 [1c20385] [ci] cannot use std inside omp target region, update README
2026-05-06 [fa83bd5] [bug] fix normalization, support Fourier src, digimouse benchmark runs
2026-05-06 [c484a01] [bug] fix ArrayData/ArrayZipData parsing, use row-major, DoMismatch defaults to 1
2026-05-05 [d4d2396] [doc] update in-code documentation
2026-05-05 [4d18f22] [cmake] add cmake option BUILD_MEX, codename use amazing tiny creatures
2026-05-05 [e8148cf] [ci] fix all ci warnings
2026-05-05 [d9b2c09] [feat] support compressed JData input, add zmat header-only lib
2026-05-04 [5624d99] [matlab] use bjdata to pass data, update mcx2json, fix mex data parsing
2026-05-04 [d910cca] [json] update json to dev version supporting bjdata Draft-4 SOA parsing, use bjdata in umcxlab
2026-05-04 [9f73d36] [mex] add matlab wrapper function
2026-05-03 [31150d4] [mex] support matlab mex file
2026-05-02 [bc876b8] shrink umcx.cpp by 39 lines (847 -> 808) under strict readability rules
2026-05-02 [ae9b6c4] [ci] fix g++-11 cmake nvidia offloading test error
2026-05-02 [9aa0c9b] [ci] fix cmake gcc error
2026-05-02 [dbbe7b6] [ci] fix cmake gcc nvidia tests
2026-05-02 [a6443b8] [ci] try to remove all warnings in ci tests
2026-05-02 [9229639] [ci] remove most ci warnings
2026-05-02 [3807450] [ci] revert back to cuda 11 to support sm_50 with clang++
2026-05-02 [46a7d15] [ci] fix cmake builds, remove fallback to activate true tests
2026-05-02 [32e6590] [ci] add ACC=on in github action
2026-05-02 [158ace1] [doc] add webpage, update README, generated by Claude
2026-05-02 [cf0503f] [nvidia] build fat binary with ptx
2026-05-02 [06e25b4] [nvidia] add ptx to nvc target, create fatbin to run on new gpus
2026-05-02 [c0fc45d] [amdgcn] add amdclang++ compiler, g++ amdgcn support is broken
2026-05-01 [c66b918] [gcc] improve gcc speed by 3x by removing 31/32 redundant computation
2026-05-01 [e6a5104] [cmake] add cmake, fix ci windows error
2026-05-01 [d512b32] [ci] fix windows ci error by statically linking -static-libgcc -static-libstdc++
2026-05-01 [7da5603] [ci] debug windows crash
2026-05-01 [111870a] [ci] debug windows crash
2026-05-01 [93dd534] [ci] debug windows crash
2026-05-01 [8f9bf0b] [ci] fix windows crash
2026-04-30 [301fc6f] [ci] remove ppa, launchpad.net is offline
2026-04-30 [73442fb] [ci] fix cuda installation
2026-04-30 [b019455] [ci] fix ci errors
2026-04-25 [8f33639] [ci] create detailed README with Claude
2025-01-22 [d791ca4] [amd] add amdclang target to test amdgcn offloading on clang++-17
2025-01-20 [d87a382] [feat] use -Q as shortopt for --bench
2025-01-18 [c3d746d] [bug] fix incorrect dimensions
2025-01-18 [33e9399] [ci] fix skinvessel test error, fix c++ warning
2025-01-18 [05dd194] [bug] fix several bugs to make skinvessel benchmark work, add test
2025-01-17 [b8648d2] [nvc] build nvc binary for all supported arch
2025-01-17 [f2afa4f] [doc] build doxygen documentation using make doc
2025-01-14 [9dbf57b] [acc] use fixed vector_length in acc, suggested by MatColgrove@NVIDIA
2025-01-14 [bccce26] [bug] fix macro typo
2025-01-14 [f94b306] [acc] unify omp and acc pragma using macros
2025-01-14 [bd20f65] [omp] turns out copy order matters, this fixes gcc 13/14 errors
2025-01-14 [73db164] [feat] support openacc, build with make ACC=on
2025-01-13 [2a699ac] [bug] set benchmark session ID
2025-01-13 [5d8ded3] [feat] add -N/--net flag to download data from neurojson.io
2025-01-12 [b03cdf6] [ci] shorten code by 2 lines
2025-01-12 [f6d3d83] [feat] support 5 source types, widefield launch, more tests, cube60planar
2025-01-12 [b80a505] [feat] add try-catch to handle errors
2025-01-11 [c78a3ad] [speed] fix the 5x slow down because of 10x less threads this change was git bisect identified, introduced in 86b4fbe
2025-01-11 [5aebece] [ci] run test script for clang
2025-01-11 [e028651] [ci] fix photon detection test match
2025-01-11 [9b41808] [ci] update test, downgrade mingw
2025-01-11 [001de56] [gcc] fix gcc nvptx -d 0 error, remove unwanted openacc directives
2025-01-11 [321e6c7] [bug] fix bug 11 templateid run twice
2025-01-10 [dc10c78] [omp] disable static private array when issavedet is false to reduce register
2025-01-10 [5a8d413] [omp] move omp target to a template function to enable specialization
2025-01-10 [10dbca7] [feat] complete saving detected photon, private detphotonbuffer still needs work
2025-01-09 [54463cb] [ci] remove debugging printf
2025-01-09 [9bdf443] [ci] trouble shooting windows cpu ci
2025-01-09 [b416d2e] [ci] trouble shooting windows cpu ci
2025-01-09 [646de6f] [feat] partial implementation of photon detection
2025-01-08 [38f087b] [ci] set fluence-rate 'x' as default outputtype
2025-01-08 [2d335c8] [feat] add --session, --dumpjson and --dumpmask, support normalization
2025-01-05 [13da510] [ci] windows mingw path update
2025-01-05 [ba9cf1e] [ci] add cpu test for windows, fix clang LD PATH
2025-01-05 [4fde0f0] [ci] use cuda 11.8 for clang
2025-01-05 [b15e2fd] [ci] add macos multi-core cpu test
2025-01-05 [f7095e1] [ci] add macos multi-core cpu test, debug clang-17 building error
2025-01-05 [f54f57f] [ci] add USERCXXFLAGS and USERLINKFLAGS in action
2025-01-05 [c62674f] [ci] add USERCXXFLAGS and USERLINKFLAGS in makefile
2025-01-05 [0691981] [ci] use mcx ci code to install cuda 9
2025-01-05 [5a024d8] [ci] separate tests for clang and gcc
2025-01-05 [76b8515] [ci] add clang 17 ppa
2025-01-05 [39088ec] [ci] build with clang 17 and clang 18
2025-01-05 [6a27fbc] [code] simplify logic, shorten code lines, update comments
2025-01-05 [fc2e6ed] [ci] run benchmarks and report speed
2025-01-05 [4153409] [ci] run but bypass nvptx tests
2025-01-05 [d114548] [ci] test nvptx offloaded code
2025-01-05 [f2742c0] [ci] fix g++-13 missing libgomp.spec error
2025-01-05 [f92f8f3] [ci] fix g++-13 missing libgomp.spec error; add g++-14
2025-01-05 [63767ca] [test] fix g++-11 nvptx dependency
2025-01-05 [1b10f05] [test] fix nvptx build test
2025-01-05 [9a4c3de] [test] add ci and unitests
2025-01-05 [afa3b0c] [doc] add license and authors info
2025-01-05 [a9f7cd2] [doc] add project rationale, fix RNG seed, shorten code
2025-01-05 [1370220] [bug] fix incorrect cfg name inside offloading section
2025-01-05 [86b4fbe] [feat] support -t/-T/-G for thread/block/GPU setting, support -O, update help
2025-01-05 [4ce5285] [feat] support cfg.seed and cfg.unitinmm
2025-01-04 [ec1d73c] [feat] compatible with c++-11,support json shapes,add most benchmarks
2025-01-03 [d807e7e] [makefile] update nvidiaclang command
2025-01-03 [b767385] [clang] make nvidiaclang now support clang++-17 or above
2025-01-03 [7e9c87b] [bench] make cube60/cube60b benchmark matching mcx cube60/cube60b
2025-01-03 [667515a] [clang] add nvidiaclang make tagetm but not working yet
2025-01-03 [72c8be7] [opt] use template to reduce register, but somehow increased from 66 to 68
2025-01-02 [36677c6] [feat] support -n/-b/-f/-j/--bench flags, use template to reduce registers
2025-01-02 [90cce04] [code] add back float4/dim4/short4 constructors, reduce lines, add back -pedantic
2025-01-01 [24b9187] [doc] remove declare mapper as it is not supported anywhere
2025-01-01 [fcfee38] [gcc] set nvptx block size to {32*2}=64, accept JSON option in commandline
2024-12-31 [99545de] [omp] restore block size
2024-12-31 [9646771] [gcc] binary built by make nvidia CXX=g++-12 runs, correctly, but slow
2024-12-31 [fa64e72] [amdgcn] allow building amdgcn with g++, binary crashes
2024-12-31 [3338454] [makefile] disable offloading for multi/single, map prop[] to target, link -lm for nvptx
2024-12-31 [9ec534a] [gcc] fix unresolved symbol sinf error when building with make nvidia with g++
2024-12-31 [3c3b4c7] [bug] fix incorrect boundary reflection, now cube60b produces 27.234% absorption
2024-12-31 [1f11c12] [feat] add parameter struct, save time-resolved fluence, control reflection
2024-12-30 [702e06b] [gcc] avoid g++-14 error when building on macos
2024-12-30 [eaab077] [omp] define constant vars as const, no speed up, use num_teams() set total threads
2024-12-30 [692d8ca] [json] use optimized BJData ND array to speed up bnii loading by 530x
2024-12-30 [d752035] [omp] avoid recreating p and ran every loop pass, speed increase 10%
2024-12-30 [d5efa34] [feat] alloc and map nested dynamic arrays, thanks to MatColgrove at NVIDIA forum use -gpu=mem:managed, see https://forums.developer.nvidia.com/t/how-to-use-openmp-map-directive-to-map-dynamic-array-inside-a-struct-class-to-the-gpu/318270/4 make nvc produced binary is working! 3x speed up compared to 64-core CPU using an RTX 2080S
2024-12-29 [2a9c6f7] [omp] attempt to add declare mapper to map dynamic array, not working
2024-12-29 [190b51c] [feat] built-in test,fix energy deposit,simplify float4/short4/dim4 use compond literals for float4/short4/dim4 value setting, add nvc, nvidia, amd target, tested on gcc-13 and nvc++-24-11
2024-12-29 [4a69c0d] [std] build binary on the Mac
2024-12-29 [79a0e36] [feat] initial openmp directive for nvptx offloading
2024-12-28 [a0c5f8d] [feat] support reflection, add column major flag, standard omp
2024-12-28 [f0a4567] [feat] basic OpenMP support, print timing, saving data to bnii
2024-12-28 [2770f73] [feat] nearly complete photon movement code, no reflection
2024-12-25 [ec4f213] [init] initial partial implementation of umcx.cpp
2023-11-07 [3e01809] initial

Navigation Menu

Repository navigation

uMCX v0.5.0 (Boxer Crab)

Choose a tag to compare

Sorry, something went wrong.