   #[1]Monte Carlo eXtreme: GPU-based Monte Carlo Simulations

Installation Instructions for MCX

          1. [2]System Requirements

          2. [3]Download and Install

          3. [4]Testing hardware support

          4. [5]Testing hardware support for MCXLAB and PMCX

          5. [6]Running MCX with GUI

          6. [7]Compiling MCX from source code

                6.1. [8]Download the source code

                6.2. [9]Install the compilers

                6.3. [10]Compile with make

                6.4. [11]Compile with cmake, and for AMD GPUs

                6.5. [12]Testing your build

1. System Requirements

   We aim to port MCX to all modern GPUs. Currently, we have two MCX
   editions: the CUDA edition (MCX), which runs on NVIDIA GPUs and, when
   compiled with ROCm/HIP, on AMD GPUs; and an [13]OpenCL edition (MCX-CL),
   which runs on all OpenCL-compliant devices, including NVIDIA/AMD/Intel
   GPUs, Intel/AMD CPUs and Apple silicon. In order to run MCX (CUDA
   edition), you need

     * a CUDA capable NVIDIA graphics card
     * an up-to-date NVIDIA graphics driver, see [14]NVIDIA's website

   or, for the ROCm/HIP build,

     * a ROCm capable AMD graphics card
     * the AMD ROCm toolkit (including HIP)

   MCX/MCXLAB/PMCX released packages are compiled with the CUDA runtime
   library statically linked. Therefore, you do not need to install the
   CUDA toolkit in order to run MCX, MCXLAB or PMCX; only the driver is
   needed.

   A list of CUDA capable cards can be found [15]here. The officially
   released binaries (including mex files and pmcx modules) can run on
   NVIDIA GPUs as old as Kepler (sm_35), and on all newer GPUs without
   recompilation. Using a recent NVIDIA card is expected to produce the
   best speed. In the below webpage, we summarized the speed differences
   between different generations of NVIDIA GPUs

   [16]https://mcx.space/gpubench/

   The released Linux binaries are built against glibc 2.17
   (manylinux2014), and run on most Linux distributions released since
   2014.

   New generations of Mac computers no longer support NVIDIA or AMD GPUs;
   please use [17]MCX-CL on macOS.

   Windows users: the graphics driver stops any GPU kernel running longer
   than a few seconds on a GPU that also drives a display. If you install
   MCX using the Windows installer, this is configured for you. Otherwise,
   please open the mcx/setup/win64 folder, right-click on
   apply_timeout_registry_fix.bat and select "Run as administrator", and
   then reboot. See the [18]FAQ for details. This is important!

2. Download and Install

   Please see Download.txt or our [19]download page for all available
   packages. In short, you may

     * download the all-in-one MCX Studio package for your platform, or the
       mcx package, extract it and run the executables under the bin/
       folder; you may add this folder to your PATH environment variable
     * on Windows, run the MCX Studio installer, or "winget install
       coti.mcxstudio"
     * for Python, run "python3 -m pip install pmcx"
     * for MATLAB/Octave, download the mcxlab package, extract it and run
       addpath('/path/to/mcxlab') in MATLAB or Octave
     * use the Docker image "fangqq/mcx"

3. Testing hardware support

   To test if your system supports MCX, you need to open a terminal (for
   Windows users, please click on the Start menu and type "cmd", then
   enter), and type

 cd "path/to/mcx/bin"

   where path/to/mcx/bin should be replaced to the actual extracted bin
   folder from the downloaded package. If your path contains space, you
   must enclose it with double-quotes.

   Once you are in the bin/ folder, you can then type

 mcx -L

   You may see 3 possible outcomes

     * 1. mcx successfully prints at least 1 supported GPU on your system
       - to this end, MCX is ready to use. You may run a built-in
       benchmark using "mcx -Q cube60" to verify.
     * 2. mcx shows the below error

 MCX ERROR(-1):No GPU device found

   If your are certain your system has a working NVIDIA GPU, it is likely
   that your GPU driver was not up to date or was not installed properly.
   Please check your driver installation again. On Linux, you may run
   "nvidia-smi" to check if the driver is loaded.
     * 3. mcx gives an error or pops up an error window showing that some
       libraries (*.dll on Windows, or *.so on Linux, or *.dylib on Mac)
       are missing. The released binaries only depend on the NVIDIA driver
       and system libraries; if you compiled mcx yourself with a
       dynamically linked CUDA runtime, please add the folder containing
       the CUDA runtime library to your library search path.

   In the event that your system does not have a supported GPU, you may
   consider using [20]MCX-CL instead - MCX-CL has the same functionality
   and input/output formats as MCX, but it can also be executed on
   AMD/Intel/Apple GPUs and CPUs.

4. Testing hardware support for MCXLAB and PMCX

   If you use MCXLAB, you may use the below procedure to test if it can
   use your GPU. First, open MATLAB or Octave, then type

 addpath('/path/to/mcxlab/')

   so that the mcx.mex* file is in the search path. You may type

 which mcx

   or
 which mcxlab

   to confirm it is added to MATLAB. Then you can use the below command to
   query your GPUs

 info=mcxlab('gpuinfo')

   You must see valid output from this call, otherwise, your system does
   not have GPU or it is not properly configured to run MCXLAB.

   The Octave mex files released for Windows and macOS are linked against
   liboctmex and require Octave 10 or newer. The Linux Octave mex file
   works with any recent Octave version.

   For Python, after installing pmcx, run

 python3 -c "import pmcx; print(pmcx.gpuinfo())"

5. Running MCX with GUI

   If you prefer a graphical interface, you can find an executable named
   mcxstudio in the all-in-one MCX Studio package. Starting from v2026,
   mcxstudio is built from [21]MCX Studio 2, a cross-platform GUI for MCX,
   MCX-CL and MMC. It opens and saves the same .json input files used by
   mcx, shows the command line that will be run, and can render the
   domain, the output fluence and photon trajectories in 3-D. Please read
   mcxstudio2/README.md or "man mcxstudio" for details.

   You may also run MCX simulations in a web browser, without installing
   any software, using [22]MCX Cloud.

6. Compiling MCX from source code

   If you want to compile an executable on your machine from the source
   code, you should follow the steps described below.

6.1. Download the source code

   You can download the source code package from the [23]Download page, or
   clone the latest code from GitHub

 git clone --recursive https://github.com/fangq/mcx.git mcx

6.2. Install the compilers

   You need to install the CUDA and C/C++ compilers on your system, this
   includes
     * 1. CUDA toolkit: download and install the CUDA toolkit from
       [24]NVIDIA's website. The official release packages are built with
       CUDA 10.2; any newer CUDA version can also be used. Make sure the
       nvcc compiler is in your PATH, for example, by adding
       /usr/local/cuda/bin to PATH on Linux.
     * 2. C/C++ compiler and make: you need gcc/g++ (or clang on macOS) and
       make. For example
          + for Debian-based Linux users, you can get these basic
            compiling tools by a single command:
sudo apt-get install build-essential
          + for Redhat-based systems:
sudo dnf groupinstall "Development Tools"
          + for Mac OS users, the compilers can be installed from Xcode;
            note that macOS 10.13 is the last version supported by CUDA
            (CUDA 10.2)
     * 3. For Windows, you need to install Microsoft Visual C++ (the free
       Visual Studio Build Tools is sufficient; it must be a version
       supported by your CUDA toolkit), and MSYS2 or Cygwin to provide
       make and the shell environment.
     * 4. (optional) MATLAB or Octave (liboctave-dev on Debian/Ubuntu) to
       compile MCXLAB, and Python 3 with pip to build PMCX.

6.3. Compile with make

   On Linux/Mac OS, open a terminal, "cd" to <mcx>/src, and type

 make

   This compiles mcx for the GPU architecture detected by nvcc (or sm_35
   if none is found) with the default xorshift128+ RNG and fast-math. You
   may target a specific GPU architecture using "make kepler", "make
   maxwell", "make pascal", "make volta", "make turing" or "make ampere",
   or set the architecture manually, for example

 make CUGENCODE=-arch=sm_86

   To link the CUDA runtime statically, use "make BACKEND=cudastatic". If
   everything is working ok, you should see a binary file generated under
   <mcx>/bin. To compile MCXLAB, use "make mex" (MATLAB) or "make oct"
   (Octave); the mex file is written to <mcx>/mcxlab.

   On Windows, open an MSYS2 or Cygwin terminal in which nvcc and cl.exe
   are in the PATH (for example, from a Visual Studio developer command
   prompt), then type "cd /path/to/your/mcx/src" and "make". The binary
   will be generated as <mcx>/bin/mcx.exe.

   To build PMCX, "cd" to <mcx>/pmcx and run "python3 -m pip install ."
   (please see pmcx/README.md for details).

6.4. Compile with cmake, and for AMD GPUs

   MCX can also be compiled with cmake

 cmake -S src -B build
 cmake --build build

   To compile MCX for AMD GPUs using ROCm/HIP, enable HIP and select the
   target GPU architecture, for example

 cmake -S src -B build -DUSE_HIP=ON -DCMAKE_HIP_ARCHITECTURES=gfx90a
 cmake --build build

   CMAKE_HIP_ARCHITECTURES accepts any ROCm GPU target (for example gfx90a
   or gfx1100); if omitted, it defaults to gfx90a. The HIP build is also
   named mcx and accepts the same options as the CUDA build.

6.5. Testing your build

   After compiling mcx, you may run the test suites under <mcx>/test

 cd src && make unittest    # CPU-only unit tests of the ray-tracing helpers
 cd test && ./testmcx.sh    # feature tests, needs a GPU
 cd test && ./testtraj.sh   # step-by-step trajectory tests

   Please read test/README.md for details.

References

   1. https://mcx.space/wiki/index.cgi?action=rss
   2. https://mcx.space/wiki/index.cgi?Doc/Installation#System_Requirements
   3. https://mcx.space/wiki/index.cgi?Doc/Installation#Download_and_Install
   4. https://mcx.space/wiki/index.cgi?Doc/Installation#Testing_hardware_support
   5. https://mcx.space/wiki/index.cgi?Doc/Installation#Testing_hardware_support_for_MCXLAB_and_PMCX
   6. https://mcx.space/wiki/index.cgi?Doc/Installation#Running_MCX_with_GUI
   7. https://mcx.space/wiki/index.cgi?Doc/Installation#Compiling_MCX_from_source_code
   8. https://mcx.space/wiki/index.cgi?Doc/Installation#Download_the_source_code
   9. https://mcx.space/wiki/index.cgi?Doc/Installation#Install_the_compilers
  10. https://mcx.space/wiki/index.cgi?Doc/Installation#Compile_with_make
  11. https://mcx.space/wiki/index.cgi?Doc/Installation#Compile_with_cmake_and_for_AMD_GPUs
  12. https://mcx.space/wiki/index.cgi?Doc/Installation#Testing_your_build
  13. https://mcx.space/wiki/index.cgi?MCXCL
  14. https://www.nvidia.com/Download/index.aspx
  15. https://developer.nvidia.com/cuda-gpus
  16. https://mcx.space/gpubench/
  17. https://mcx.space/wiki/index.cgi?MCXCL
  18. https://mcx.space/wiki/index.cgi?Doc/FAQ#I_am_getting_a_kernel_launch_timed_out_error_what_is_that
  19. https://mcx.space/wiki/?Get
  20. https://mcx.space/wiki/index.cgi?MCXCL
  21. https://github.com/fangq/mcx/tree/master/mcxstudio2
  22. https://mcx.space/cloud/
  23. https://mcx.space/wiki/index.cgi?Download
  24. https://developer.nvidia.com/cuda-toolkit
