Python bindings for Monte Carlo eXtreme photon transport simulator
Project description
PMCX - Python bindings for Monte Carlo eXtreme photon transport simulator
- Copyright: (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 later
- Version: 0.0.13
- URL: https://pypi.org/project/pmcx/
- Github: https://github.com/fangq/mcx
This module provides a Python binding for Monte Carlo eXtreme (MCX). For other binaries, including the standalone executable and the MATLAB bindings, see our 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 fully optimized CPU-based MC implementation.
How to Install
- PIP:
pip install pmcx
see https://pypi.org/project/pmcx/
Runtime Dependencies
- NVIDIA GPU Driver: A CUDA-capable NVIDIA GPU and driver is required to run MCX. An up-to-date driver is recommended. The binary wheel distributed over pip runs on NVIDIA drivers with CUDA 10.1 support on Windows, CUDA 9.2 support on Linux, and CUDA 10.2 support on macOS, respectively. For more details on driver versions and their CUDA support, see the CUDA Release Notes. To download the latest driver for your system, see the NVIDIA Driver Download Page. You shouldn't need to have CUDA toolkit installed. MCX is built with the static CUDA runtime library.
- Python: Python 3.6 and newer is required. Python 2 is not supported.
- numpy: Used to pass/receive volumetric information to/from pmcx. To install, use either conda or pip
package managers:
pip install numpy
orconda install numpy
- (optional) jdata: Only needed to read/write JNIfTI output files. To install, use pip:
pip install jdata
on 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
. See https://pypi.org/project/jdata/ for more details. - (optional) bjdata: Only needed to read/write BJData/UBJSON files. To install, run
pip install bjdata
on 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
. See https://pypi.org/project/bjdata/ for more details. - (optional) matplotlib: For plotting the results. To install, run either
pip install matplotlib
orconda install matplotlib
Build Instructions
Build Dependencies
-
Operating System: Windows and Linux are fully supported; For building MCX on macOS, OSX 10.13 (High Sierra) and older are highly recommended since 10.13 was the last version of macOS with NVIDIA CUDA support, and matching the CUDA compiler version with the C/C++ compiler shipped with Xcode is easier. Newer macOS versions can be used for building MCX, but need to have System Integrity Protection disabled prior to installing the CUDA toolkit due to the NVIDIA installer copying its payload under the
/Developer
directory under root. -
NVIDIA CUDA Toolkit: CUDA 7.5 or newer is required. On macOS, 10.2 is the last available CUDA version. For details on how to install CUDA, see the CUDA Download Page. The NVIDIA GPU driver of the target system must support the selected CUDA toolkit.
-
Python Interpreter: Python 3.6 or above. The
pip
Python package manager and thewheel
package (available viapip
) are not required but recommended. -
C/C++ Compiler: CUDA Toolkit supports only the following compilers:
- GNU GCC for Linux-based distributions.
- Microsoft Visual Studio C/C++ Compiler for Windows.
- Apple Clang for macOS, available via Xcode. The last Xcode version supported by CUDA 10.2 is 10.3. If using an OSX
version higher than 10.15 it can be downloaded and installed from Apple's Developer Website
with an Apple ID. After installation, select the proper Xcode version from the commandline, and set the
SDKROOT
environment variable:sudo xcode-select -s /Applications/Xcode_10.3.app/Contents/Developer/ export SDKROOT=/Applications/Xcode_10.3.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk
Refer to each OS's online documentations for more in-depth information on how to install these compilers. Note that the version of the C/C++ compiler used must be supported by the CUDA toolkit version. If not, compilation will fail with an error notifying you of this problem. See the CUDA Installation Guides for more details.
-
OpenMP: The installed C/C++ Compiler should have support for OpenMP. 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 the Brew package manager, preferably after selecting the correct Xcode version:
brew install libomp brew link --force libomp
-
CMake: CMake version 3.15 and later is required. Refer to the CMake website for more information on how to download. CMake is also widely available on package managers across all operating systems. Additionally, on Windows, make sure Visual Studio's C++ CMake tools for Windows is also installed by selecting its option during installation.
-
Zlib Compression Development Headers: On Linux, this is generally available via the built-in package manager. For example, on Debian-based distributions like Ubuntu it is available via
apt
under the namezlib1g-dev
. On macOS, brew provides it under the namezlib
. No packaged versions of Zlib are available for windows, therefore it must be downloaded manually and added to the CMake environment variables in your working Powershell session:curl.exe --retry 3 -kL https://cytranet.dl.sourceforge.net/project/gnuwin32/zlib/1.2.3/zlib-1.2.3-lib.zip --output zlib.zip Expand-Archive .\zlib.zip -DestinationPath zlib\ $env:CMAKE_INCLUDE_PATH=$PWD\zlib\include $env:CMAKE_LIBRARY_PATH=$PWD\zlib\lib
Build Steps
-
Ensure that
cmake
,nvcc
(NVIDIA CUDA Compiler) and the C/C++ compiler are all located over yourPATH
. This can be queried viaecho $env:PATH
on Windows orecho $PATH
on Linux. If not, locate them and add their folder to thePATH
. -
Clone the repository and switch to the
pmcx/
folder:git clone --recursive https://github.com/fangq/mcx.git cd mcx/pmcx
-
Either run
python setup.py install
orpip install .
to directly install, or runpip wheel .
to only build the Python wheel without installing it.
How to use
The PMCX module is easy to use. You can use the pmcx.gpuinfo()
function to first verify
if you have NVIDIA/CUDA compatible GPUs installed; if there are NVIDIA GPUs detected,
you can then call the run()
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 - MCXLAB)
import pmcx
import numpy as np
import matplotlib.pyplot as plt
res = pmcx.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'].shape
plt.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 to
pmcx.run()
import pmcx
import numpy as np
cfg = {'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 = pmcx.run(cfg)
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distributions
Hashes for pmcx-0.0.13-pp39-pypy39_pp73-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7a716cccd7e36556f93fab3f57ebde0bcc216bc814eb70f9cb19521e74beac82 |
|
MD5 | 463212f1ba87dc6ec768b69c2d30a3b1 |
|
BLAKE2b-256 | 6f2869dcaedba3cdad4a8cb6843f6844c4afe8308675dc4bab524e661026f05d |
Hashes for pmcx-0.0.13-pp39-pypy39_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3032c5d0af938d60e2e4cfc2d2ec802cdc31d0dc5549a7b68b913e9c5cd58da7 |
|
MD5 | 36b83ac9c35753ed4fb2912b8f0483ce |
|
BLAKE2b-256 | bfdfec9bbc10afda74b24de9ea7a3deafeaab626ae6e3b9fc508e2e8fbf4eb81 |
Hashes for pmcx-0.0.13-pp38-pypy38_pp73-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4c0278d71d88584dd053bf57935924483ca425a6f722a1ebb5763a0db919408f |
|
MD5 | 54512cfff8db1fb024a30394bf911d13 |
|
BLAKE2b-256 | 90b456bee42d30be559b8654296fff0bce7fd5177872c42354eceac64ef89923 |
Hashes for pmcx-0.0.13-pp38-pypy38_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e534d0c4bef3af22ecac8b5251e0061c2065d96c54f288608b53f26b748f5491 |
|
MD5 | 5138cb83d584b7116aab57dfd7dba09b |
|
BLAKE2b-256 | ec818a26702ccefec42dbfb3b441bc87196454b7ddb0275d29db857c533d94d2 |
Hashes for pmcx-0.0.13-pp37-pypy37_pp73-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | dc68e20613e9539fdb50bafb304cd02df047967bf80ed1b019e4e9f21a6eef66 |
|
MD5 | 439475ece2fd7d83585c8ab431ca7a5e |
|
BLAKE2b-256 | fd365776d7fd314ea806b77f911af939a273dcc5e303c5ea2ac2a565db122019 |
Hashes for pmcx-0.0.13-pp37-pypy37_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7fee449d3d7685fbfddab0a31227075061543d19ff74ee9a68ace9992799da14 |
|
MD5 | d3afd4b8847143035a5e114e3f7523ff |
|
BLAKE2b-256 | ecbca6c6a1aa764cf5babbd3ff71ab04288d3bae8b72d04a4283604598d140ac |
Hashes for pmcx-0.0.13-cp311-cp311-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ca9676c3ce771b369cb995ded95557a8ee6675bb4f8f284fbca6856e13a0659b |
|
MD5 | 4a92b712a69afe1a7aec326b9844947a |
|
BLAKE2b-256 | fab97675cf8316fa2d68ad4af050b5919a008074cdbb16dc33bb678a85880306 |
Hashes for pmcx-0.0.13-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d9a990f61e73ba59b1d9d624d308d066894063d495ac200ec5b3c26ed4abc151 |
|
MD5 | 18ca950605adf309f0d635a38cb79450 |
|
BLAKE2b-256 | 38d3da98dd3bc6297450755fcbdbc33bcf9db03381ef5e2f0625c0fc382c50fb |
Hashes for pmcx-0.0.13-cp310-cp310-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a7d473ec4a2d8e14edbd0c21789da31a2a3e77dd2e234e339eb82bb7170dd966 |
|
MD5 | 42afd6b4b8ea03ef26b8ed67d62e33cf |
|
BLAKE2b-256 | 4ccba53629ceede40cbfba3315d6903cf2a6d91185191eb46466f436f5b9dc6f |
Hashes for pmcx-0.0.13-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 487ce185a7c9d0ebc9aff106bbcc01d36383d5fbeaafe8210517b676fa6c9416 |
|
MD5 | 7807e630c207b804120063edca43c4e1 |
|
BLAKE2b-256 | b83b9afe7390e99e12e98ae42511348139123d11ab5a69a4e75e7dab82602ef6 |
Hashes for pmcx-0.0.13-cp39-cp39-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | cced4739cf60d37fb2be6aecf986ecf26ff01e02293db1390e4b459fcd844e55 |
|
MD5 | 79209bcf9886e66670f7e92520685cc0 |
|
BLAKE2b-256 | d893804eb6ecffea57e3a8c9eb45d574fa2ee098d3ccae6aa0de5ab4e3ce0164 |
Hashes for pmcx-0.0.13-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9b5936428b7c3593b9af5b79be20672e5817400e1381164efc8d4d773eabf2ba |
|
MD5 | 3f72ab750546e2382f368b8761d4aa09 |
|
BLAKE2b-256 | 0d1f93495657bc0c81f61a292f7ac5e097fd75f98424d4ca92b1dc8db5467a97 |
Hashes for pmcx-0.0.13-cp38-cp38-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d6095cfe740434bd263905f87283942f1b5431f6e213165d7ae22e780dd2cbe3 |
|
MD5 | ba0b3330f950f9d087eb0b9ca22a3ffa |
|
BLAKE2b-256 | edea7e4f86f56602ff19c2af4141902ec3c5674cfdc5519fb03a113fce37b984 |
Hashes for pmcx-0.0.13-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ef2b9345744570d117fd8da5e9fd78d31cef4075ef23e138a7cb6f9e688e3851 |
|
MD5 | e158408173bdc2d137e1a94aad351eb5 |
|
BLAKE2b-256 | 3fc7f2edccdda17200ca9c6f7599c471f30d287f99e9601b2e3761d463a802c1 |
Hashes for pmcx-0.0.13-cp37-cp37m-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7f93ba906719dba15061b82bdfcea1935ce91561f94a240430cd81d22a5bb96c |
|
MD5 | 57433f3f01461f0efeb06f462f99b420 |
|
BLAKE2b-256 | ba081ca18c73786e114624486b51aba6317839ebe55e87c5c8bd6e1c2da563c5 |
Hashes for pmcx-0.0.13-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c617688d81a76a5111a16b13f8b92e24aba62646961045602d55b4c95c809a95 |
|
MD5 | 3af9f0186450a3b2ce1b76f7a07de07c |
|
BLAKE2b-256 | d838a1f09af894bfdf72bd4c92e513694b07e4fca6a76daacda5ee1f2174e146 |
Hashes for pmcx-0.0.13-cp36-cp36m-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6e95f596126b1e281cc6ff0facc941283988b9140a19ae2189026dc039a43628 |
|
MD5 | 5567c208451f6873a70179be32493bb2 |
|
BLAKE2b-256 | 8531d83cde4cc83211554a2207dec5838331a55ece3b81e8081aaa0d1caccc46 |
Hashes for pmcx-0.0.13-cp36-cp36m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | aea9710e41007cb86ed56c6393c52806e715587823eb2aaade5ac95fc4d95c70 |
|
MD5 | e982b6b0951776fd05bd12f0192a6262 |
|
BLAKE2b-256 | 3910c23d24476be5bbf927bf527e2caae74cfca7eac484c995d869d54e9e3932 |