Package: pmcxcl
PMCX-CL - Python bindings for Monte Carlo eXtreme (OpenCL) photon transport simulatorCopyright: (C) Matin Raayai Ardakani (2022-2023) <raayaiardakani.m at northeastern.edu>
and Qianqian Fang (2019-2023) <q.fang at neu.edu>License: GNU Public License V3 or laterVersion: 0.1.4URL:https://pypi.org/project/pmcxcl/Github:https://github.com/fangq/mcxclThis module provides a Python binding for Monte Carlo eXtreme for OpenCL (MCXCL).
For other binaries, including the standalone executable and the MATLAB bindings,
seeour website.Monte Carlo eXtreme (MCX) is a fast photon transport simulation software for 3D
heterogeneous turbid media. By taking advantage of the massively parallel
threads and extremely low memory latency in a modern graphics processing unit
(GPU), MCX is capable of performing Monte Carlo (MC) photon simulations at a
blazing speed, typically hundreds to a thousand times faster than a single-threaded
CPU-based MC implementation.How to InstallPIP:pip install pmcxcl, seehttps://pypi.org/project/pmcxcl/Runtime DependenciesCPU or GPU: An OpenCL-capable CPU or GPU; most modern CPUs or GPUs support OpenCL -
an industrial-standard heterogeneous computing library and specification (https://www.khronos.org/opencl/)OpenCL CPU or GPU runtime/driver: Both NVIDIA and AMD GPU graphics drivers should contain
out-of-box OpenCL runtimes or drivers; for Intel GPUs, one should install additional OpenCL runtime
support fromhttps://github.com/intel/compute-runtimeor install theintel-opencl-icdpackage
if the OS provides (such as Ubuntu 22.04); one can also install an open-source OpenCL runtimePOCL, using package manager such assudo apt-get install pocl-opencl-icd. However,
POCL's support is largely limited to CPUs. Youdo not needto install CUDA SDK to use pmcxcl.Python: Python 3.6 and newer is required.Python 2 is not supported.numpy: Used to pass/receive volumetric information to/from pmcxcl. To install, use either conda or pip
package managers:pip install numpyorconda install numpy(optional)jdata: Only needed to read/write JNIfTI output files. To install, use pip:pip install jdataon all operating systems; For Debian-based Linux distributions, you can also install to the system interpreter
using apt-get:sudo apt-get install python3-jdata. Seehttps://pypi.org/project/jdata/for more details.(optional)bjdata: Only needed to read/write BJData/UBJSON files. To install, runpip install bjdataon all operating systems; For Debian-based Linux distributions, you can also install to the system interpreter
using apt-get:sudo apt-get install python3-bjdata. Seehttps://pypi.org/project/bjdata/for more details.(optional)matplotlib: For plotting the results. To install, run eitherpip install matplotliborconda install matplotlibBuild InstructionsBuild DependenciesOperating System: pmcxcl and mcxcl can be compiled on most OSes, including Windows, Linux and MacOS.OpenCL library: compiling mcxcl or pmcxcl requires to link withlibOpenCL.soon Linux, orlibOpenCL.dylibon MacOS orOpenCL.dllon Windows. These libraries should have been installed by either graphics driver or
OpenCL runtimes.Python Interpreter: Python 3.6 or above. ThepipPython package manager and thewheelpackage (available
viapip) are not required but recommended.C/C++ Compiler: pmcxcl can be compiled using a wide variety of C compilers, includingGNU GCC for Linux, MacOS (intalled via MacPorts or brew), and Windows (installed via msys2, mingw64 or cygwin64)Microsoft Visual Studio C/C++ Compiler for Windows.Apple Clang for macOS, available via Xcode.Refer to each OS's online documentations for more in-depth information on how to install these compilers.
MacOS provides built-in OpenCL library support.OpenMP: The installed C/C++ Compiler should have support forOpenMP.
GCC and Microsoft Visual Studio compiler support OpenMP out of the box. Apple Clang, however, requires manual
installation of OpenMP libraries for Apple Clang. The easiest way to do this is via theBrewpackage
manager, preferably after selecting the correct Xcode version:brewinstalllibompbrewlink--forcelibompCMake: CMake version 3.15 and later is required. Refer to theCMake websitefor more information on how to download.
CMake is also widely available on package managers across all operating systems.Build StepsEnsure thatcmake,pythonand the C/C++ compiler are all located over yourPATH.
This can be queried viaecho $env:PATHon Windows orecho $PATHon Linux. If not, locate them and add their folder to thePATH.Clone the repository and switch to thepmcxcl/folder:gitclone--recursivehttps://github.com/fangq/mcx.gitcdmcx/pmcxclOne can runpython3 setup.py installorpython3 -m pip install .to both locally build and install the moduleIf one only wants to locally build the module, one should runpython3 -m pip wheel .If the binary module is successfully built locally, you should see a binary wheel filepmcxcl-X.X.X-cpXX-cpXX-*.whlstored inside themcxcl/pmcxclfolder. You can install this wheel package usingpython3 -m pip install --force-reinstall pmcxcl-*.whlto force installing this locally compiledpmcxclmodule and overwrite any previously installed versions.How to useThe PMCXCL module is easy to use. You can use thepmcxcl.gpuinfo()function to first verify
if you have NVIDIA/CUDA compatible GPUs installed; if there are NVIDIA GPUs detected,
you can then call therun()function to launch a photon simulation.A simulation can be defined conveniently in two approaches - a one-liner and a two-liner:For the one-liner, one simply pass on each MCX simulation setting as positional
argument. The supported setting names are compatible to nearly all the input fields
for the MATLAB version of MCX/MCXCL -MCXLAB)importpmcxclimportnumpyasnpimportmatplotlib.pyplotaspltres=pmcxcl.run(nphoton=1000000,vol=np.ones([60,60,60],dtype='uint8'),tstart=0,tend=5e-9,tstep=5e-9,srcpos=[30,30,0],srcdir=[0,0,1],prop=np.array([[0,0,1,1],[0.005,1,0.01,1.37]]))res['flux'].shapeplt.imshow(np.log10(res['flux'][30,:,:]))plt.show()Alternatively, one can also define a Python dict object containing each setting
as a key, and pass on the dict object topmcxcl.run()importpmcxclimportnumpyasnpcfg={'nphoton':1000000,'vol':np.ones([60,60,60],dtype='uint8'),'tstart':0,'tend':5e-9,'tstep':5e-9,'srcpos':[30,30,0],'srcdir':[0,0,1],'prop':[[0,0,1,1],[0.005,1,0.01,1.37]]}res=pmcxcl.run(cfg)