pmcxcl 0.0.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. pmcxcl-0.0.1/PKG-INFO +174 -0
  2. pmcxcl-0.0.1/README.md +148 -0
  3. pmcxcl-0.0.1/pmcxcl/__init__.py +42 -0
  4. pmcxcl-0.0.1/pmcxcl/bench.py +46 -0
  5. pmcxcl-0.0.1/pmcxcl.egg-info/PKG-INFO +174 -0
  6. pmcxcl-0.0.1/pmcxcl.egg-info/SOURCES.txt +9 -0
  7. pmcxcl-0.0.1/pmcxcl.egg-info/dependency_links.txt +1 -0
  8. pmcxcl-0.0.1/pmcxcl.egg-info/not-zip-safe +1 -0
  9. pmcxcl-0.0.1/pmcxcl.egg-info/top_level.txt +1 -0
  10. pmcxcl-0.0.1/setup.cfg +4 -0
  11. pmcxcl-0.0.1/setup.py +152 -0
pmcxcl-0.0.1/PKG-INFO ADDED
@@ -0,0 +1,174 @@
1
+ Metadata-Version: 2.1
2
+ Name: pmcxcl
3
+ Version: 0.0.1
4
+ Summary: Python bindings for Monte Carlo eXtreme photon transport simulator
5
+ Home-page: https://github.com/fangq/mcxcl
6
+ Download-URL: http://mcx.space
7
+ Author: Matin Raayai Ardakani, Qianqian Fang
8
+ Author-email: raayaiardakani.m@northeastern.edu, q.fang@neu.edu
9
+ Maintainer: Qianqian Fang
10
+ License: GPLv3+
11
+ Keywords: Monte Carlo simulation,Biophotonics,Ray-tracing,Rendering,GPU,Modeling,Biomedical Optics,Tissue Optics,Simulator,Optics
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Science/Research
14
+ Classifier: Environment :: GPU :: NVIDIA CUDA
15
+ Classifier: Topic :: Scientific/Engineering :: Physics
16
+ Classifier: License :: OSI Approved :: Apache Software License
17
+ Classifier: Programming Language :: Python :: 3.6
18
+ Classifier: Programming Language :: Python :: 3.7
19
+ Classifier: Programming Language :: Python :: 3.8
20
+ Classifier: Programming Language :: Python :: 3.9
21
+ Classifier: Programming Language :: Python :: 3.10
22
+ Classifier: Programming Language :: Python :: 3.11
23
+ Requires: numpy
24
+ Requires-Python: >=3.6
25
+ Description-Content-Type: text/markdown
26
+
27
+ ![](http://mcx.space/img/mcx18_banner.png)
28
+
29
+ # PMCX-CL - Python bindings for Monte Carlo eXtreme photon transport simulator
30
+
31
+ - Copyright: (C) Matin Raayai Ardakani (2022-2023) <raayaiardakani.m at northeastern.edu>
32
+ and Qianqian Fang (2019-2023) <q.fang at neu.edu>
33
+ - License: GNU Public License V3 or later
34
+ - Version: 0.0.1
35
+ - URL: https://pypi.org/project/pmcxcl/
36
+ - Github: https://github.com/fangq/mcxcl
37
+
38
+ [![Build Status](https://travis-ci.com/fangq/mcx.svg?branch=master)](https://travis-ci.com/fangq/mcxcl)
39
+
40
+ This module provides a Python binding for Monte Carlo eXtreme (MCX).
41
+ For other binaries, including the standalone executable and the MATLAB bindings, see [our website](http://mcx.space).
42
+
43
+ Monte Carlo eXtreme (MCX) is a fast photon transport simulation software for 3D
44
+ heterogeneous turbid media. By taking advantage of the massively parallel
45
+ threads and extremely low memory latency in a modern graphics processing unit
46
+ (GPU), MCX is capable of performing Monte Carlo (MC) photon simulations at a
47
+ blazing speed, typically hundreds to a thousand times faster than a fully
48
+ optimized CPU-based MC implementation.
49
+
50
+ ## How to Install
51
+
52
+ * PIP: ```pip install pmcxcl``` see https://pypi.org/project/pmcxcl/
53
+
54
+ ## Runtime Dependencies
55
+ * **OpenCL runtime for CPU or GPU**: A OpenCL-capable GPU and driver is required to run MCX. An up-to-date driver is recommended.
56
+ The binary wheel distributed over pip runs on drivers. For more details on driver versions and their CUDA support, see the
57
+ [CUDA Release Notes](https://docs.nvidia.com/cuda/cuda-toolkit-release-notes/index.html).
58
+ To download the latest driver for your system, see the
59
+ [NVIDIA Driver Download Page](https://www.nvidia.com/download/index.aspx).
60
+ **You shouldn't need to have CUDA toolkit installed**. MCX is built with the static CUDA runtime library.
61
+ * **Python**: Python 3.6 and newer is required. **Python 2 is not supported**.
62
+ * **numpy**: Used to pass/receive volumetric information to/from pmcxcl. To install, use either conda or pip
63
+ package managers: `pip install numpy` or `conda install numpy`
64
+ * (optional) **jdata**: Only needed to read/write JNIfTI output files. To install, use pip: `pip install jdata`
65
+ on all operating systems; For Debian-based Linux distributions, you can also install to the system interpreter
66
+ using apt-get: `sudo apt-get install python3-jdata`. See https://pypi.org/project/jdata/ for more details.
67
+ * (optional) **bjdata**: Only needed to read/write BJData/UBJSON files. To install, run `pip install bjdata`
68
+ on all operating systems; For Debian-based Linux distributions, you can also install to the system interpreter
69
+ using apt-get: `sudo apt-get install python3-bjdata`. See https://pypi.org/project/bjdata/ for more details.
70
+ * (optional) **matplotlib**: For plotting the results. To install, run either `pip install matplotlib` or
71
+ `conda install matplotlib`
72
+
73
+ ## Build Instructions
74
+
75
+ ### Build Dependencies
76
+ * **Operating System**: Windows and Linux are fully supported; For building MCX on macOS, OSX 10.13 (High Sierra) and
77
+ older are highly recommended since 10.13 was the last version of macOS with NVIDIA CUDA support, and matching the CUDA
78
+ compiler version with the C/C++ compiler shipped with Xcode is easier. Newer macOS versions can be used for building MCX,
79
+ but need to have System Integrity Protection disabled prior to installing the CUDA toolkit due to the NVIDIA installer copying
80
+ its payload under the ```/Developer``` directory under root.
81
+ * **NVIDIA CUDA Toolkit**: CUDA 7.5 or newer is required. On macOS, 10.2 is the last available CUDA version.
82
+ For details on how to install CUDA, see the [CUDA Download Page](https://developer.nvidia.com/cuda-downloads).
83
+ The NVIDIA GPU driver of the target system must support the selected CUDA toolkit.
84
+ * **Python Interpreter**: Python 3.6 or above. The ```pip``` Python package manager and the ```wheel``` package (available
85
+ via ```pip```) are not required but recommended.
86
+ * **C/C++ Compiler**: CUDA Toolkit supports only the following compilers:
87
+ * GNU GCC for Linux-based distributions.
88
+ * Microsoft Visual Studio C/C++ Compiler for Windows.
89
+ * Apple Clang for macOS, available via Xcode. The last Xcode version supported by CUDA 10.2 is 10.3. If using an OSX
90
+ version higher than 10.15 it can be downloaded and installed from [Apple's Developer Website](https://developer.apple.com/download/)
91
+ with an Apple ID. After installation, select the proper Xcode version from the commandline, and set the ```SDKROOT```
92
+ environment variable:
93
+ ```zsh
94
+ sudo xcode-select -s /Applications/Xcode_10.3.app/Contents/Developer/
95
+ export SDKROOT=/Applications/Xcode_10.3.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk
96
+ ```
97
+
98
+ Refer to each OS's online documentations for more in-depth information on how to install these compilers.
99
+ Note that the version of the C/C++ compiler used must be supported by the CUDA toolkit version. If not, compilation
100
+ will fail with an error notifying you of this problem. See the [CUDA Installation Guides](https://developer.nvidia.com/cuda-toolkit-archive)
101
+ for more details.
102
+ * **OpenMP**: The installed C/C++ Compiler should have support for [OpenMP](https://www.openmp.org/).
103
+ GCC and Microsoft Visual Studio compiler support OpenMP out of the box. Apple Clang, however, requires manual
104
+ installation of OpenMP libraries for Apple Clang. The easiest way to do this is via the [Brew](https://brew.sh/) package
105
+ manager, preferably after selecting the correct Xcode version:
106
+ ```zsh
107
+ brew install libomp
108
+ brew link --force libomp
109
+ ```
110
+
111
+ * **CMake**: CMake version 3.15 and later is required. Refer to the [CMake website](https://cmake.org/download/) for more information on how to download.
112
+ CMake is also widely available on package managers across all operating systems.
113
+ Additionally, on Windows, make sure **Visual Studio's C++ CMake tools for Windows** is also installed by selecting its option
114
+ during installation.
115
+ * **Zlib Compression Development Headers**: On Linux, this is generally available via the built-in package manager. For
116
+ example, on Debian-based distributions like Ubuntu it is available via ```apt``` under the name ```zlib1g-dev```. On
117
+ macOS, brew provides it under the name ```zlib```. No packaged versions of Zlib are available for windows, therefore it must be
118
+ downloaded manually and added to the CMake environment variables in your working Powershell session:
119
+ ```powershell
120
+ 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
121
+ Expand-Archive .\zlib.zip -DestinationPath zlib\
122
+ $env:CMAKE_INCLUDE_PATH=$PWD\zlib\include
123
+ $env:CMAKE_LIBRARY_PATH=$PWD\zlib\lib
124
+ ```
125
+
126
+ ### Build Steps
127
+ 1. Ensure that ```cmake```, ```nvcc``` (NVIDIA CUDA Compiler) and the C/C++ compiler are all located over your ```PATH```.
128
+ This can be queried via ```echo $env:PATH``` on Windows or ```echo $PATH``` on Linux. If not, locate them and add their folder to the ```PATH```.
129
+
130
+ 2. Clone the repository and switch to the ```pmcxcl/``` folder:
131
+ ```bash
132
+ git clone --recursive https://github.com/fangq/mcx.git
133
+ cd mcx/pmcxcl
134
+ ```
135
+
136
+ 3. Either run ```python setup.py install``` or ```pip install .``` to directly install, or run ```pip wheel .``` to only
137
+ build the Python wheel without installing it.
138
+
139
+
140
+ ## How to use
141
+
142
+ The PMCXCL module is easy to use. You can use the `pmcxcl.gpuinfo()` function to first verify
143
+ if you have NVIDIA/CUDA compatible GPUs installed; if there are NVIDIA GPUs detected,
144
+ you can then call the `run()` function to launch a photon simulation.
145
+
146
+ A simulation can be defined conveniently in two approaches - a one-liner and a two-liner:
147
+
148
+ * For the one-liner, one simply pass on each MCX simulation setting as positional
149
+ argument. The supported setting names are compatible to nearly all the input fields
150
+ for the MATLAB version of MCX - [MCXLAB](https://github.com/fangq/mcx/blob/master/mcxlab/mcxlab.m))
151
+
152
+ ```python3
153
+ import pmcxcl
154
+ import numpy as np
155
+ import matplotlib.pyplot as plt
156
+
157
+ res = pmcxcl.run(nphoton=1000000, vol=np.ones([60, 60, 60], dtype='uint8'), tstart=0, tend=5e-9,
158
+ 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]]))
159
+ res['flux'].shape
160
+
161
+ plt.imshow(np.log10(res['flux'][30,:, :]))
162
+ plt.show()
163
+ ```
164
+
165
+ * Alternatively, one can also define a Python dict object containing each setting
166
+ as a key, and pass on the dict object to `pmcxcl.run()`
167
+
168
+ ```python3
169
+ import pmcxcl
170
+ import numpy as np
171
+ cfg = {'nphoton': 1000000, 'vol':np.ones([60,60,60],dtype='uint8'), 'tstart':0, 'tend':5e-9, 'tstep':5e-9,
172
+ 'srcpos': [30,30,0], 'srcdir':[0,0,1], 'prop':[[0,0,1,1],[0.005,1,0.01,1.37]]}
173
+ res = pmcxcl.run(cfg)
174
+ ```
pmcxcl-0.0.1/README.md ADDED
@@ -0,0 +1,148 @@
1
+ ![](http://mcx.space/img/mcx18_banner.png)
2
+
3
+ # PMCX-CL - Python bindings for Monte Carlo eXtreme photon transport simulator
4
+
5
+ - Copyright: (C) Matin Raayai Ardakani (2022-2023) <raayaiardakani.m at northeastern.edu>
6
+ and Qianqian Fang (2019-2023) <q.fang at neu.edu>
7
+ - License: GNU Public License V3 or later
8
+ - Version: 0.0.1
9
+ - URL: https://pypi.org/project/pmcxcl/
10
+ - Github: https://github.com/fangq/mcxcl
11
+
12
+ [![Build Status](https://travis-ci.com/fangq/mcx.svg?branch=master)](https://travis-ci.com/fangq/mcxcl)
13
+
14
+ This module provides a Python binding for Monte Carlo eXtreme (MCX).
15
+ For other binaries, including the standalone executable and the MATLAB bindings, see [our website](http://mcx.space).
16
+
17
+ Monte Carlo eXtreme (MCX) is a fast photon transport simulation software for 3D
18
+ heterogeneous turbid media. By taking advantage of the massively parallel
19
+ threads and extremely low memory latency in a modern graphics processing unit
20
+ (GPU), MCX is capable of performing Monte Carlo (MC) photon simulations at a
21
+ blazing speed, typically hundreds to a thousand times faster than a fully
22
+ optimized CPU-based MC implementation.
23
+
24
+ ## How to Install
25
+
26
+ * PIP: ```pip install pmcxcl``` see https://pypi.org/project/pmcxcl/
27
+
28
+ ## Runtime Dependencies
29
+ * **OpenCL runtime for CPU or GPU**: A OpenCL-capable GPU and driver is required to run MCX. An up-to-date driver is recommended.
30
+ The binary wheel distributed over pip runs on drivers. For more details on driver versions and their CUDA support, see the
31
+ [CUDA Release Notes](https://docs.nvidia.com/cuda/cuda-toolkit-release-notes/index.html).
32
+ To download the latest driver for your system, see the
33
+ [NVIDIA Driver Download Page](https://www.nvidia.com/download/index.aspx).
34
+ **You shouldn't need to have CUDA toolkit installed**. MCX is built with the static CUDA runtime library.
35
+ * **Python**: Python 3.6 and newer is required. **Python 2 is not supported**.
36
+ * **numpy**: Used to pass/receive volumetric information to/from pmcxcl. To install, use either conda or pip
37
+ package managers: `pip install numpy` or `conda install numpy`
38
+ * (optional) **jdata**: Only needed to read/write JNIfTI output files. To install, use pip: `pip install jdata`
39
+ on all operating systems; For Debian-based Linux distributions, you can also install to the system interpreter
40
+ using apt-get: `sudo apt-get install python3-jdata`. See https://pypi.org/project/jdata/ for more details.
41
+ * (optional) **bjdata**: Only needed to read/write BJData/UBJSON files. To install, run `pip install bjdata`
42
+ on all operating systems; For Debian-based Linux distributions, you can also install to the system interpreter
43
+ using apt-get: `sudo apt-get install python3-bjdata`. See https://pypi.org/project/bjdata/ for more details.
44
+ * (optional) **matplotlib**: For plotting the results. To install, run either `pip install matplotlib` or
45
+ `conda install matplotlib`
46
+
47
+ ## Build Instructions
48
+
49
+ ### Build Dependencies
50
+ * **Operating System**: Windows and Linux are fully supported; For building MCX on macOS, OSX 10.13 (High Sierra) and
51
+ older are highly recommended since 10.13 was the last version of macOS with NVIDIA CUDA support, and matching the CUDA
52
+ compiler version with the C/C++ compiler shipped with Xcode is easier. Newer macOS versions can be used for building MCX,
53
+ but need to have System Integrity Protection disabled prior to installing the CUDA toolkit due to the NVIDIA installer copying
54
+ its payload under the ```/Developer``` directory under root.
55
+ * **NVIDIA CUDA Toolkit**: CUDA 7.5 or newer is required. On macOS, 10.2 is the last available CUDA version.
56
+ For details on how to install CUDA, see the [CUDA Download Page](https://developer.nvidia.com/cuda-downloads).
57
+ The NVIDIA GPU driver of the target system must support the selected CUDA toolkit.
58
+ * **Python Interpreter**: Python 3.6 or above. The ```pip``` Python package manager and the ```wheel``` package (available
59
+ via ```pip```) are not required but recommended.
60
+ * **C/C++ Compiler**: CUDA Toolkit supports only the following compilers:
61
+ * GNU GCC for Linux-based distributions.
62
+ * Microsoft Visual Studio C/C++ Compiler for Windows.
63
+ * Apple Clang for macOS, available via Xcode. The last Xcode version supported by CUDA 10.2 is 10.3. If using an OSX
64
+ version higher than 10.15 it can be downloaded and installed from [Apple's Developer Website](https://developer.apple.com/download/)
65
+ with an Apple ID. After installation, select the proper Xcode version from the commandline, and set the ```SDKROOT```
66
+ environment variable:
67
+ ```zsh
68
+ sudo xcode-select -s /Applications/Xcode_10.3.app/Contents/Developer/
69
+ export SDKROOT=/Applications/Xcode_10.3.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk
70
+ ```
71
+
72
+ Refer to each OS's online documentations for more in-depth information on how to install these compilers.
73
+ Note that the version of the C/C++ compiler used must be supported by the CUDA toolkit version. If not, compilation
74
+ will fail with an error notifying you of this problem. See the [CUDA Installation Guides](https://developer.nvidia.com/cuda-toolkit-archive)
75
+ for more details.
76
+ * **OpenMP**: The installed C/C++ Compiler should have support for [OpenMP](https://www.openmp.org/).
77
+ GCC and Microsoft Visual Studio compiler support OpenMP out of the box. Apple Clang, however, requires manual
78
+ installation of OpenMP libraries for Apple Clang. The easiest way to do this is via the [Brew](https://brew.sh/) package
79
+ manager, preferably after selecting the correct Xcode version:
80
+ ```zsh
81
+ brew install libomp
82
+ brew link --force libomp
83
+ ```
84
+
85
+ * **CMake**: CMake version 3.15 and later is required. Refer to the [CMake website](https://cmake.org/download/) for more information on how to download.
86
+ CMake is also widely available on package managers across all operating systems.
87
+ Additionally, on Windows, make sure **Visual Studio's C++ CMake tools for Windows** is also installed by selecting its option
88
+ during installation.
89
+ * **Zlib Compression Development Headers**: On Linux, this is generally available via the built-in package manager. For
90
+ example, on Debian-based distributions like Ubuntu it is available via ```apt``` under the name ```zlib1g-dev```. On
91
+ macOS, brew provides it under the name ```zlib```. No packaged versions of Zlib are available for windows, therefore it must be
92
+ downloaded manually and added to the CMake environment variables in your working Powershell session:
93
+ ```powershell
94
+ 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
95
+ Expand-Archive .\zlib.zip -DestinationPath zlib\
96
+ $env:CMAKE_INCLUDE_PATH=$PWD\zlib\include
97
+ $env:CMAKE_LIBRARY_PATH=$PWD\zlib\lib
98
+ ```
99
+
100
+ ### Build Steps
101
+ 1. Ensure that ```cmake```, ```nvcc``` (NVIDIA CUDA Compiler) and the C/C++ compiler are all located over your ```PATH```.
102
+ This can be queried via ```echo $env:PATH``` on Windows or ```echo $PATH``` on Linux. If not, locate them and add their folder to the ```PATH```.
103
+
104
+ 2. Clone the repository and switch to the ```pmcxcl/``` folder:
105
+ ```bash
106
+ git clone --recursive https://github.com/fangq/mcx.git
107
+ cd mcx/pmcxcl
108
+ ```
109
+
110
+ 3. Either run ```python setup.py install``` or ```pip install .``` to directly install, or run ```pip wheel .``` to only
111
+ build the Python wheel without installing it.
112
+
113
+
114
+ ## How to use
115
+
116
+ The PMCXCL module is easy to use. You can use the `pmcxcl.gpuinfo()` function to first verify
117
+ if you have NVIDIA/CUDA compatible GPUs installed; if there are NVIDIA GPUs detected,
118
+ you can then call the `run()` function to launch a photon simulation.
119
+
120
+ A simulation can be defined conveniently in two approaches - a one-liner and a two-liner:
121
+
122
+ * For the one-liner, one simply pass on each MCX simulation setting as positional
123
+ argument. The supported setting names are compatible to nearly all the input fields
124
+ for the MATLAB version of MCX - [MCXLAB](https://github.com/fangq/mcx/blob/master/mcxlab/mcxlab.m))
125
+
126
+ ```python3
127
+ import pmcxcl
128
+ import numpy as np
129
+ import matplotlib.pyplot as plt
130
+
131
+ res = pmcxcl.run(nphoton=1000000, vol=np.ones([60, 60, 60], dtype='uint8'), tstart=0, tend=5e-9,
132
+ 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]]))
133
+ res['flux'].shape
134
+
135
+ plt.imshow(np.log10(res['flux'][30,:, :]))
136
+ plt.show()
137
+ ```
138
+
139
+ * Alternatively, one can also define a Python dict object containing each setting
140
+ as a key, and pass on the dict object to `pmcxcl.run()`
141
+
142
+ ```python3
143
+ import pmcxcl
144
+ import numpy as np
145
+ cfg = {'nphoton': 1000000, 'vol':np.ones([60,60,60],dtype='uint8'), 'tstart':0, 'tend':5e-9, 'tstep':5e-9,
146
+ 'srcpos': [30,30,0], 'srcdir':[0,0,1], 'prop':[[0,0,1,1],[0.005,1,0.01,1.37]]}
147
+ res = pmcxcl.run(cfg)
148
+ ```
pmcxcl-0.0.1/pmcxcl/__init__.py ADDED
@@ -0,0 +1,42 @@
1
+ # Copyright (c) 2022-2023 Matin Raayai Ardakani <raayaiardakani.m at northeastern.edu>. All rights reserved.
2
+ # Copyright (c) 2022-2023 Qianqian Fang <q.fang at neu.edu>. All rights reserved.
3
+ #
4
+ # This program is free software: you can redistribute it and/or modify
5
+ # it under the terms of the GNU General Public License as published by
6
+ # the Free Software Foundation, either version 3 of the License, or
7
+ # (at your option) any later version.
8
+ #
9
+ # This program is distributed in the hope that it will be useful,
10
+ # but WITHOUT ANY WARRANTY; without even the implied warranty of
11
+ # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12
+ # GNU General Public License for more details.
13
+ #
14
+ # You should have received a copy of the GNU General Public License
15
+ # along with this program. If not, see <http://www.gnu.org/licenses/>.
16
+
17
+ """PMCXCL - Python bindings for Monte Carlo eXtreme photon transport simulator
18
+
19
+ Example usage:
20
+
21
+ # To list available GPUs
22
+ import pmcxcl
23
+ pmcxcl.gpuinfo()
24
+
25
+ # To run a simulation
26
+ res = pmcxcl.run(nphoton=1000000, vol=np.ones([60, 60, 60], dtype='uint8'),
27
+ tstart=0, tend=5e-9, tstep=5e-9, srcpos=[30,30,0],
28
+ srcdir=[0,0,1], prop=np.array([[0, 0, 1, 1], [0.005, 1, 0.01, 1.37]]))
29
+ """
30
+
31
+ try:
32
+ from _pmcxcl import gpuinfo, run
33
+ except ImportError: # pragma: no cover
34
+ print("the pmcxcl binary extension (_pmcxcl) is not compiled! please compile first")
35
+
36
+ # from .utils import detweight, cwdref
37
+ # from .files import loadmc2, loadmch, load, save
38
+ from .bench import bench
39
+
40
+ __version__ = "0.0.1"
41
+
42
+ __all__ = ("gpuinfo", "run", "bench")
pmcxcl-0.0.1/pmcxcl/bench.py ADDED
@@ -0,0 +1,46 @@
1
+ # Copyright (c) 2022-2023 Matin Raayai Ardakani <raayaiardakani.m at northeastern.edu>. All rights reserved.
2
+ # Copyright (c) 2022-2023 Qianqian Fang <q.fang at neu.edu>. All rights reserved.
3
+ #
4
+ # This program is free software: you can redistribute it and/or modify
5
+ # it under the terms of the GNU General Public License as published by
6
+ # the Free Software Foundation, either version 3 of the License, or
7
+ # (at your option) any later version.
8
+ #
9
+ # This program is distributed in the hope that it will be useful,
10
+ # but WITHOUT ANY WARRANTY; without even the implied warranty of
11
+ # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12
+ # GNU General Public License for more details.
13
+ #
14
+ # You should have received a copy of the GNU General Public License
15
+ # along with this program. If not, see <http://www.gnu.org/licenses/>.
16
+
17
+ """Built-in benchmark configurations"""
18
+
19
+ import numpy as np
20
+ import copy
21
+
22
+ bench = {}
23
+ bench["cube60"] = {
24
+ "nphoton": 1000000,
25
+ "vol": np.ones([60, 60, 60], dtype="uint8"),
26
+ "tstart": 0,
27
+ "tend": 5e-9,
28
+ "tstep": 5e-9,
29
+ "srcpos": [29, 29, 0],
30
+ "srcdir": [0, 0, 1],
31
+ "prop": [[0, 0, 1, 1], [0.005, 1, 0.01, 1.37], [0.002, 5, 0.9, 1]],
32
+ "isreflect": 0,
33
+ "seed": 1648335518,
34
+ "session": "cube60",
35
+ "detpos": [[29, 19, 0, 1], [29, 39, 0, 1], [19, 29, 0, 1], [39, 29, 0, 1]],
36
+ "issrcfrom0": 1,
37
+ }
38
+
39
+ bench["cube60b"] = copy.deepcopy(bench["cube60"])
40
+ bench["cube60b"]["isreflect"] = 1
41
+
42
+ bench["cube60planar"] = copy.deepcopy(bench["cube60b"])
43
+ bench["cube60planar"]["srctype"] = "planar"
44
+ bench["cube60planar"]["srcpos"] = [10, 10, -10]
45
+ bench["cube60planar"]["srcparam1"] = [40, 0, 0, 0]
46
+ bench["cube60planar"]["srcparam2"] = [0, 40, 0, 0]
pmcxcl-0.0.1/pmcxcl.egg-info/PKG-INFO ADDED
@@ -0,0 +1,174 @@
1
+ Metadata-Version: 2.1
2
+ Name: pmcxcl
3
+ Version: 0.0.1
4
+ Summary: Python bindings for Monte Carlo eXtreme photon transport simulator
5
+ Home-page: https://github.com/fangq/mcxcl
6
+ Download-URL: http://mcx.space
7
+ Author: Matin Raayai Ardakani, Qianqian Fang
8
+ Author-email: raayaiardakani.m@northeastern.edu, q.fang@neu.edu
9
+ Maintainer: Qianqian Fang
10
+ License: GPLv3+
11
+ Keywords: Monte Carlo simulation,Biophotonics,Ray-tracing,Rendering,GPU,Modeling,Biomedical Optics,Tissue Optics,Simulator,Optics
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Science/Research
14
+ Classifier: Environment :: GPU :: NVIDIA CUDA
15
+ Classifier: Topic :: Scientific/Engineering :: Physics
16
+ Classifier: License :: OSI Approved :: Apache Software License
17
+ Classifier: Programming Language :: Python :: 3.6
18
+ Classifier: Programming Language :: Python :: 3.7
19
+ Classifier: Programming Language :: Python :: 3.8
20
+ Classifier: Programming Language :: Python :: 3.9
21
+ Classifier: Programming Language :: Python :: 3.10
22
+ Classifier: Programming Language :: Python :: 3.11
23
+ Requires: numpy
24
+ Requires-Python: >=3.6
25
+ Description-Content-Type: text/markdown
26
+
27
+ ![](http://mcx.space/img/mcx18_banner.png)
28
+
29
+ # PMCX-CL - Python bindings for Monte Carlo eXtreme photon transport simulator
30
+
31
+ - Copyright: (C) Matin Raayai Ardakani (2022-2023) <raayaiardakani.m at northeastern.edu>
32
+ and Qianqian Fang (2019-2023) <q.fang at neu.edu>
33
+ - License: GNU Public License V3 or later
34
+ - Version: 0.0.1
35
+ - URL: https://pypi.org/project/pmcxcl/
36
+ - Github: https://github.com/fangq/mcxcl
37
+
38
+ [![Build Status](https://travis-ci.com/fangq/mcx.svg?branch=master)](https://travis-ci.com/fangq/mcxcl)
39
+
40
+ This module provides a Python binding for Monte Carlo eXtreme (MCX).
41
+ For other binaries, including the standalone executable and the MATLAB bindings, see [our website](http://mcx.space).
42
+
43
+ Monte Carlo eXtreme (MCX) is a fast photon transport simulation software for 3D
44
+ heterogeneous turbid media. By taking advantage of the massively parallel
45
+ threads and extremely low memory latency in a modern graphics processing unit
46
+ (GPU), MCX is capable of performing Monte Carlo (MC) photon simulations at a
47
+ blazing speed, typically hundreds to a thousand times faster than a fully
48
+ optimized CPU-based MC implementation.
49
+
50
+ ## How to Install
51
+
52
+ * PIP: ```pip install pmcxcl``` see https://pypi.org/project/pmcxcl/
53
+
54
+ ## Runtime Dependencies
55
+ * **OpenCL runtime for CPU or GPU**: A OpenCL-capable GPU and driver is required to run MCX. An up-to-date driver is recommended.
56
+ The binary wheel distributed over pip runs on drivers. For more details on driver versions and their CUDA support, see the
57
+ [CUDA Release Notes](https://docs.nvidia.com/cuda/cuda-toolkit-release-notes/index.html).
58
+ To download the latest driver for your system, see the
59
+ [NVIDIA Driver Download Page](https://www.nvidia.com/download/index.aspx).
60
+ **You shouldn't need to have CUDA toolkit installed**. MCX is built with the static CUDA runtime library.
61
+ * **Python**: Python 3.6 and newer is required. **Python 2 is not supported**.
62
+ * **numpy**: Used to pass/receive volumetric information to/from pmcxcl. To install, use either conda or pip
63
+ package managers: `pip install numpy` or `conda install numpy`
64
+ * (optional) **jdata**: Only needed to read/write JNIfTI output files. To install, use pip: `pip install jdata`
65
+ on all operating systems; For Debian-based Linux distributions, you can also install to the system interpreter
66
+ using apt-get: `sudo apt-get install python3-jdata`. See https://pypi.org/project/jdata/ for more details.
67
+ * (optional) **bjdata**: Only needed to read/write BJData/UBJSON files. To install, run `pip install bjdata`
68
+ on all operating systems; For Debian-based Linux distributions, you can also install to the system interpreter
69
+ using apt-get: `sudo apt-get install python3-bjdata`. See https://pypi.org/project/bjdata/ for more details.
70
+ * (optional) **matplotlib**: For plotting the results. To install, run either `pip install matplotlib` or
71
+ `conda install matplotlib`
72
+
73
+ ## Build Instructions
74
+
75
+ ### Build Dependencies
76
+ * **Operating System**: Windows and Linux are fully supported; For building MCX on macOS, OSX 10.13 (High Sierra) and
77
+ older are highly recommended since 10.13 was the last version of macOS with NVIDIA CUDA support, and matching the CUDA
78
+ compiler version with the C/C++ compiler shipped with Xcode is easier. Newer macOS versions can be used for building MCX,
79
+ but need to have System Integrity Protection disabled prior to installing the CUDA toolkit due to the NVIDIA installer copying
80
+ its payload under the ```/Developer``` directory under root.
81
+ * **NVIDIA CUDA Toolkit**: CUDA 7.5 or newer is required. On macOS, 10.2 is the last available CUDA version.
82
+ For details on how to install CUDA, see the [CUDA Download Page](https://developer.nvidia.com/cuda-downloads).
83
+ The NVIDIA GPU driver of the target system must support the selected CUDA toolkit.
84
+ * **Python Interpreter**: Python 3.6 or above. The ```pip``` Python package manager and the ```wheel``` package (available
85
+ via ```pip```) are not required but recommended.
86
+ * **C/C++ Compiler**: CUDA Toolkit supports only the following compilers:
87
+ * GNU GCC for Linux-based distributions.
88
+ * Microsoft Visual Studio C/C++ Compiler for Windows.
89
+ * Apple Clang for macOS, available via Xcode. The last Xcode version supported by CUDA 10.2 is 10.3. If using an OSX
90
+ version higher than 10.15 it can be downloaded and installed from [Apple's Developer Website](https://developer.apple.com/download/)
91
+ with an Apple ID. After installation, select the proper Xcode version from the commandline, and set the ```SDKROOT```
92
+ environment variable:
93
+ ```zsh
94
+ sudo xcode-select -s /Applications/Xcode_10.3.app/Contents/Developer/
95
+ export SDKROOT=/Applications/Xcode_10.3.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk
96
+ ```
97
+
98
+ Refer to each OS's online documentations for more in-depth information on how to install these compilers.
99
+ Note that the version of the C/C++ compiler used must be supported by the CUDA toolkit version. If not, compilation
100
+ will fail with an error notifying you of this problem. See the [CUDA Installation Guides](https://developer.nvidia.com/cuda-toolkit-archive)
101
+ for more details.
102
+ * **OpenMP**: The installed C/C++ Compiler should have support for [OpenMP](https://www.openmp.org/).
103
+ GCC and Microsoft Visual Studio compiler support OpenMP out of the box. Apple Clang, however, requires manual
104
+ installation of OpenMP libraries for Apple Clang. The easiest way to do this is via the [Brew](https://brew.sh/) package
105
+ manager, preferably after selecting the correct Xcode version:
106
+ ```zsh
107
+ brew install libomp
108
+ brew link --force libomp
109
+ ```
110
+
111
+ * **CMake**: CMake version 3.15 and later is required. Refer to the [CMake website](https://cmake.org/download/) for more information on how to download.
112
+ CMake is also widely available on package managers across all operating systems.
113
+ Additionally, on Windows, make sure **Visual Studio's C++ CMake tools for Windows** is also installed by selecting its option
114
+ during installation.
115
+ * **Zlib Compression Development Headers**: On Linux, this is generally available via the built-in package manager. For
116
+ example, on Debian-based distributions like Ubuntu it is available via ```apt``` under the name ```zlib1g-dev```. On
117
+ macOS, brew provides it under the name ```zlib```. No packaged versions of Zlib are available for windows, therefore it must be
118
+ downloaded manually and added to the CMake environment variables in your working Powershell session:
119
+ ```powershell
120
+ 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
121
+ Expand-Archive .\zlib.zip -DestinationPath zlib\
122
+ $env:CMAKE_INCLUDE_PATH=$PWD\zlib\include
123
+ $env:CMAKE_LIBRARY_PATH=$PWD\zlib\lib
124
+ ```
125
+
126
+ ### Build Steps
127
+ 1. Ensure that ```cmake```, ```nvcc``` (NVIDIA CUDA Compiler) and the C/C++ compiler are all located over your ```PATH```.
128
+ This can be queried via ```echo $env:PATH``` on Windows or ```echo $PATH``` on Linux. If not, locate them and add their folder to the ```PATH```.
129
+
130
+ 2. Clone the repository and switch to the ```pmcxcl/``` folder:
131
+ ```bash
132
+ git clone --recursive https://github.com/fangq/mcx.git
133
+ cd mcx/pmcxcl
134
+ ```
135
+
136
+ 3. Either run ```python setup.py install``` or ```pip install .``` to directly install, or run ```pip wheel .``` to only
137
+ build the Python wheel without installing it.
138
+
139
+
140
+ ## How to use
141
+
142
+ The PMCXCL module is easy to use. You can use the `pmcxcl.gpuinfo()` function to first verify
143
+ if you have NVIDIA/CUDA compatible GPUs installed; if there are NVIDIA GPUs detected,
144
+ you can then call the `run()` function to launch a photon simulation.
145
+
146
+ A simulation can be defined conveniently in two approaches - a one-liner and a two-liner:
147
+
148
+ * For the one-liner, one simply pass on each MCX simulation setting as positional
149
+ argument. The supported setting names are compatible to nearly all the input fields
150
+ for the MATLAB version of MCX - [MCXLAB](https://github.com/fangq/mcx/blob/master/mcxlab/mcxlab.m))
151
+
152
+ ```python3
153
+ import pmcxcl
154
+ import numpy as np
155
+ import matplotlib.pyplot as plt
156
+
157
+ res = pmcxcl.run(nphoton=1000000, vol=np.ones([60, 60, 60], dtype='uint8'), tstart=0, tend=5e-9,
158
+ 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]]))
159
+ res['flux'].shape
160
+
161
+ plt.imshow(np.log10(res['flux'][30,:, :]))
162
+ plt.show()
163
+ ```
164
+
165
+ * Alternatively, one can also define a Python dict object containing each setting
166
+ as a key, and pass on the dict object to `pmcxcl.run()`
167
+
168
+ ```python3
169
+ import pmcxcl
170
+ import numpy as np
171
+ cfg = {'nphoton': 1000000, 'vol':np.ones([60,60,60],dtype='uint8'), 'tstart':0, 'tend':5e-9, 'tstep':5e-9,
172
+ 'srcpos': [30,30,0], 'srcdir':[0,0,1], 'prop':[[0,0,1,1],[0.005,1,0.01,1.37]]}
173
+ res = pmcxcl.run(cfg)
174
+ ```
pmcxcl-0.0.1/pmcxcl.egg-info/SOURCES.txt ADDED
@@ -0,0 +1,9 @@
1
+ README.md
2
+ setup.py
3
+ pmcxcl/__init__.py
4
+ pmcxcl/bench.py
5
+ pmcxcl.egg-info/PKG-INFO
6
+ pmcxcl.egg-info/SOURCES.txt
7
+ pmcxcl.egg-info/dependency_links.txt
8
+ pmcxcl.egg-info/not-zip-safe
9
+ pmcxcl.egg-info/top_level.txt
pmcxcl-0.0.1/pmcxcl.egg-info/not-zip-safe ADDED
@@ -0,0 +1 @@
1
+
pmcxcl-0.0.1/pmcxcl.egg-info/top_level.txt ADDED
@@ -0,0 +1 @@
1
+ pmcxcl
pmcxcl-0.0.1/setup.cfg ADDED
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
pmcxcl-0.0.1/setup.py ADDED
@@ -0,0 +1,152 @@
1
+ """
2
+ The original code was taken from Pybind11's CMake Example: https://github.com/pybind/cmake_example.git
3
+ """
4
+ import os
5
+ import re
6
+ import subprocess
7
+ import sys
8
+
9
+ from setuptools import Extension, setup
10
+ from setuptools.command.build_ext import build_ext
11
+
12
+ with open("README.md", "r") as fh:
13
+ readme = fh.read()
14
+
15
+ # Convert distutils Windows platform specifiers to CMake -A arguments
16
+ PLAT_TO_CMAKE = {
17
+ "win32": "Win32",
18
+ "win-amd64": "x64",
19
+ "win-arm32": "ARM",
20
+ "win-arm64": "ARM64",
21
+ }
22
+
23
+
24
+ class CMakeExtension(Extension):
25
+ def __init__(self, name, target, source_dir=""):
26
+ Extension.__init__(self, name, sources=[])
27
+ self.source_dir = os.path.abspath(source_dir)
28
+ self.target = target
29
+
30
+
31
+ class CMakeBuild(build_ext):
32
+ def build_extension(self, ext):
33
+ extdir = os.path.abspath(os.path.dirname(self.get_ext_fullpath(ext.name)))
34
+
35
+ # required for auto-detection & inclusion of auxiliary "native" libs
36
+ if not extdir.endswith(os.path.sep):
37
+ extdir += os.path.sep
38
+
39
+ debug = int(os.environ.get("DEBUG", 0)) if self.debug is None else self.debug
40
+ cfg = "Debug" if debug else "Release"
41
+
42
+ # CMake lets you override the generator - we need to check this.
43
+ # Can be set with Conda-Build, for example.
44
+ cmake_generator = os.environ.get("CMAKE_GENERATOR", "")
45
+
46
+ cmake_args = [
47
+ f"-DPython3_ROOT_DIR={sys.exec_prefix}",
48
+ f"-DCMAKE_LIBRARY_OUTPUT_DIRECTORY={extdir}",
49
+ f"-DPYTHON_EXECUTABLE={sys.executable}",
50
+ f"-DCMAKE_BUILD_TYPE={cfg}", # not used on MSVC, but no harm
51
+ "-DBUILD_PYTHON=true"
52
+ ]
53
+ build_args = []
54
+ # Adding CMake arguments set as environment variable
55
+ # (needed e.g. to build for ARM OSx on conda-forge)
56
+ if "CMAKE_ARGS" in os.environ:
57
+ cmake_args += [item for item in os.environ["CMAKE_ARGS"].split(" ") if item]
58
+
59
+ if self.compiler.compiler_type != "msvc":
60
+ # Using Ninja-build since it a) is available as a wheel and b)
61
+ # multithreads automatically. MSVC would require all variables be
62
+ # exported for Ninja to pick it up, which is a little tricky to do.
63
+ # Users can override the generator with CMAKE_GENERATOR in CMake
64
+ # 3.15+.
65
+ if not cmake_generator:
66
+ try:
67
+ import ninja # noqa: F401
68
+
69
+ cmake_args += ["-GNinja"]
70
+ except ImportError:
71
+ pass
72
+
73
+ else:
74
+
75
+ # Single config generators are handled "normally"
76
+ single_config = any(x in cmake_generator for x in {"NMake", "Ninja"})
77
+
78
+ # CMake allows an arch-in-generator style for backward compatibility
79
+ contains_arch = any(x in cmake_generator for x in {"ARM", "Win64"})
80
+
81
+ # Specify the arch if using MSVC generator, but only if it doesn't
82
+ # contain a backward-compatibility arch spec already in the
83
+ # generator name.
84
+ if not single_config and not contains_arch:
85
+ cmake_args += ["-A", PLAT_TO_CMAKE[self.plat_name]]
86
+
87
+ # Multi-config generators have a different way to specify configs
88
+ if not single_config:
89
+ cmake_args += [
90
+ f"-DCMAKE_LIBRARY_OUTPUT_DIRECTORY_{cfg.upper()}={extdir}"
91
+ ]
92
+ build_args += ["--config", cfg]
93
+
94
+ if sys.platform.startswith("darwin"):
95
+ # Cross-compile support for macOS - respect ARCHFLAGS if set
96
+ archs = re.findall(r"-arch (\S+)", os.environ.get("ARCHFLAGS", ""))
97
+ if archs:
98
+ cmake_args += ["-DCMAKE_OSX_ARCHITECTURES={}".format(";".join(archs))]
99
+
100
+ # Set CMAKE_BUILD_PARALLEL_LEVEL to control the parallel build level
101
+ # across all generators.
102
+ if "CMAKE_BUILD_PARALLEL_LEVEL" not in os.environ:
103
+ # self.parallel is a Python 3 only way to set parallel jobs by hand
104
+ # using -j in the build_ext call, not supported by pip or PyPA-build.
105
+ if hasattr(self, "parallel") and self.parallel:
106
+ # CMake 3.12+ only.
107
+ build_args += [f"-j{self.parallel}"]
108
+
109
+ build_temp = os.path.join(self.build_temp, ext.name)
110
+ if not os.path.exists(build_temp):
111
+ os.makedirs(build_temp)
112
+
113
+ subprocess.check_call(["cmake", ext.source_dir] + cmake_args, cwd=build_temp)
114
+ subprocess.check_call(["cmake", "--build", ".", "--target", ext.target] + build_args, cwd=build_temp)
115
+
116
+
117
+ # The information here can also be placed in setup.cfg - better separation of
118
+ # logic and declaration, and simpler if you include description/version in a file.
119
+ setup(
120
+ name="pmcxcl",
121
+ packages=['pmcxcl'],
122
+ version="0.0.1",
123
+ requires=['numpy'],
124
+ license='GPLv3+',
125
+ author="Matin Raayai Ardakani, Qianqian Fang",
126
+ author_email="raayaiardakani.m@northeastern.edu, q.fang@neu.edu",
127
+ description="Python bindings for Monte Carlo eXtreme photon transport simulator",
128
+ long_description=readme,
129
+ long_description_content_type="text/markdown",
130
+ maintainer= 'Qianqian Fang',
131
+ url='https://github.com/fangq/mcxcl',
132
+ download_url='http://mcx.space',
133
+ keywords=['Monte Carlo simulation', 'Biophotonics', 'Ray-tracing', 'Rendering', 'GPU', 'Modeling',
134
+ 'Biomedical Optics', 'Tissue Optics', 'Simulator', 'Optics'],
135
+ #ext_modules=[CMakeExtension("_pmcxcl", target="_pmcxcl", source_dir="../src/")],
136
+ #cmdclass={"build_ext": CMakeBuild},
137
+ zip_safe=False,
138
+ python_requires=">=3.6",
139
+ classifiers=[
140
+ 'Development Status :: 4 - Beta',
141
+ 'Intended Audience :: Science/Research',
142
+ 'Environment :: GPU :: NVIDIA CUDA',
143
+ 'Topic :: Scientific/Engineering :: Physics',
144
+ 'License :: OSI Approved :: Apache Software License',
145
+ 'Programming Language :: Python :: 3.6',
146
+ 'Programming Language :: Python :: 3.7',
147
+ 'Programming Language :: Python :: 3.8',
148
+ 'Programming Language :: Python :: 3.9',
149
+ 'Programming Language :: Python :: 3.10',
150
+ 'Programming Language :: Python :: 3.11'
151
+ ]
152
+ )