English
资源说明：Monte Carlo eXtreme for OpenCL (MCXCL)
# Monte Carlo eXtreme (MCX-CL) - OpenCL Edition
- **Author:** Qianqian Fang (q.fang at neu.edu)
- **License:** GNU General Public License version 3 (GPLv3)
- **Version:** 0.9.9 (Eternity - Final)
- **Website:** [ http://mcx.space]( http://mcx.space)
[](https://travis-ci.com/fangq/mcxcl)
Table of Contents:
-------------
* [What's New](#whats-new)
* [Introduction](#introduction)
* [Requirement and Installation](#requirement-and-installation)
+ [Step 1. Verify your CPU/GPU support](#step-1-verify-your-cpugpu-support)
+ [Step 2. Install MATLAB or GNU Octave](#step-2-install-matlab-or-gnu-octave)
+ [Step 3. Installing MCXCL](#step-3-installing-mcxcl)
+ [Step 4. Start MCXStudio and query GPU information](#step-4-start-mcxstudio-and-query-gpu-information)
+ [Step 5. Run a trial simulation](#step-5-run-a-trial-simulation)
+ [Step 6. Test MATLAB for visualization](#step-6-test-matlab-for-visualization)
+ [Step 7. Setting up MATLAB search path](#step-7-setting-up-matlab-search-path)
* [Running Simulations](#running-simulations)
* [Using JSON-formatted input files](#using-json-formatted-input-files)
* [Using JSON-formatted shape description files](#using-json-formatted-shape-description-files)
* [Output data formats](#output-data-formats)
+ [Volumetric output](#volumetric-output)
+ [Detected photon data](#detected-photon-data)
+ [Photon trajectory data](#photon-trajectory-data)
* [Using mcxlabcl in MATLAB and Octave](#using-mcxlabcl-in-matlab-and-octave)
* [Using MCXStudio GUI](#using-mcxstudio-gui)
* [Interpreting the Output](#interpreting-the-output)
+ [Output files](#output-files)
+ [Guide for output units](#guide-for-output-units)
+ [Console print messages](#console-print-messages)
* [Best practices guide](#best-practices-guide)
* [Acknowledgement](#acknowledgement)
* [Reference](#reference)
What's New
-------------
In MCX-CL v2020 (0.9.9), we added a list of major new additions, including
* Support running on multiple NVIDIA GPUs (merged from nvidiaomp branch)
* Built-in benchmarks for easy testing and adoption by new users
* Transition to JSON/JNIfTI input/output files for easy data sharing
* Exporting simulation as JSON with binary volume data
* All-in-one Windows installer for MCXStudio/MCX/MMC/MCXCL
* Automated code building, testing and continuous integration via Travis-CI
* CMake based compilation and Visual Studio support
* 1.6x speedup on Pascal GPUs
* Add 4 built-in complex domain examples - Colin27 brain atlas, USC_19-5 brain atlas,
Digimouse, and mcxyz skin-vessel benchmark
* Support isotropic launch for all focuable sources - `gaussian`, `pattern`, `pattern3d`,
`fourier`, `disk`, `fourierx`, `fourierx2d`, and `slit` - by setting `cfg.srcdir(4)` to `nan`
* Add python-based `mch` file reader (by Shih-Cheng Tu), nightly build compilation
script, colored command line output, and more
Compared to MCXCL v2019.4 (0.9.8), MCX-CL has gained support of nearl all core features in MCX, i.e.
* Output momentum transfer for DCS simulations
* Output photon trajectory data
* Specifying one of the four boundary conditions for each of the 6 facets of the domain
* Output partial scattering event counts like MMC
* Photon replay
* Photon sharing - simultaneous simulations of multiple patterns
* 2D simulations
* Support photon numbers over 2^31-1 in one simulation
In addition, we also fixed a number of critical bugs, such as
* fix critical bug when output diffuse reflectance using a single pattern source
* fix bugs for incorrect results for isotropic source, cone source
* fix mcxlabcl gpuinfo output crash using multiple GPUs
* fix mcxlab crash when srcpattern/srcdir/srcpos/detpos are not in double precision
* fix mcxlab crash due to racing in multi-threads
* force g to 1 in region where mus is 0
Introduction
-------------
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), this program is able to perform Monte
Carlo (MC) simulations at a blazing speed, typically hundreds to
a thousand times faster than a fully optimized CPU-based MC
implementation.
MCX-CL is the OpenCL implementation of the MCX algorithm. Unlike MCX
which only be executed on NVIDIA GPUs, MCX-CL is written in OpenCL,
the Open Computing Language, and can be executed on most modern CPUs
and GPUs available today, including Intel and AMD CPUs and GPUs. MCX-CL
is highly portable, highly scalable and is feature rich like MCX.
The details of MCX-CL can be found in the below paper
> [Yu2018] Leiming Yu, Fanny Nina-Paravecino, David Kaeli, and Qianqian Fang,
"Scalable and massively parallel Monte Carlo photon transport simulations
for heterogeneous computing platforms," J. Biomed. Optics, 23(1), 010504 (2018) .
A short summary of the main features includes:
* 3D heterogeneous media represented by voxelated array
* support over a dozen source forms, including wide-field and pattern illuminations
* boundary reflection support
* time-resolved photon transport simulations
* saving photon partial path lengths and trajectories
* optimized random number generators
* build-in flux/fluence normalization to output Green's functions
* user adjustable voxel resolution
* improved accuracy with atomic operations
* cross-platform graphical user interface
* native Matlab/Octave support for high usability
* flexible JSON interface for future extensions
* multi-GPU support
MCX-CL can be used on Windows, Linux and Mac OS. Multiple user
interfaces are provided, including
- **Command line mode:** mcxcl can be executed in the command line, best suited
for batch data processing
- **Graphical User Interface with MCXStudio:** MCXStudio is a unified GUI program
for MCX, MCX-CL and MMC. One can intuitively set all parameters, including GPU
settings, MC settings and domain design, in the cross-platform interface
- **Calling inside MATLAB/Octave:** mcxlabcl is a mex function, one can call it
inside MATLAB or GNU Octave to get all functionalities as the command line version.
If a user is familiar with MATLAB/Octave, it is highly recommended to
use MCXCL in MATLAB/Octave to ease data visualization. If one prefers a
GUI, please use MCXStudio to start. For users who are familiar with MCX/MCXCL
and need it for regular data processing, using the command line mode is
recommended.
Requirement and Installation
----------------------------
With the up-to-date driver installed for your computers, MCXCL can run on
almost all computers. The requirements for using this software include
* a CPU, or
* a CUDA capable NVIDIA graphics card, or
* an AMD graphics card, and
* pre-installed graphics driver - typically includes the OpenCL library (`libOpenCL.*` or `OpenCL.dll`)
For speed differences between different CPUs/GPUs made by different vendors, please
see your above paper [1] and our websites
- http://mcx.space/computebench/
- http://mcx.space/mcxcl
Generally speaking, AMD and NVIDIA high-end dedicated GPU performs the best, about 20-60x
faster than a multi-core CPU; Intel's integrated GPU is about 3-4 times faster than
a multi-core CPU.
MCX-CL supports and has been fully tested with open-source OpenCL runtime
pocl (http://portablecl.org/) on the CPU. To install pocl, please run
```
sudo apt-get install pocl-opencl-icd
```
To install MCXCL, you simply download the binary executable corresponding to your
computer architecture and platform, extract the package
and run the executable under the `{mcxcl root}/bin` directory. For Linux
and MacOS users, please double check and make sure `libOpenCL.so` is installed under
the `/usr/lib` directory. If it is installed under a different directory, please
define environment variable `LD_LIBRARY_PATH` to include the path.
If `libOpenCL.so` or `OpenCL.dll` does not exist on your system or, please
make sure you have installed [CUDA SDK](https://developer.nvidia.com/cuda-toolkit) (if you are using an NVIDIA card)
or AMD APP SDK (if you are using an AMD card), e.g. [Radeon™ Software for Linux](https://www.amd.com/en/support) or [ROCm](https://github.com/RadeonOpenCompute/ROCm) where the option for OpenCL was selected.
Additionally, if you are on a Linux-based system you may require the below dependences - this command assumes you are running Ubuntu:
```
sudo apt-get install ocl-icd-libopencl1 opencl-headers ocl-icd-opencl-dev zlib1g-dev
```
The below installation steps can be browsed online at
http://mcx.space/wiki/index.cgi/wiki/index.cgi?Workshop/MCX18Preparation/MethodA
### Step 1. Verify your CPU/GPU support
MCX-CL supports a wide-range of processors, including Intel/AMD CPUs
and GPUs from NVIDIA/AMD/Intel. If your computer has been working previously,
in most cases, MCX-CL can simply run out-of-box. However, if you have trouble,
please follow the below detailed steps to verify and setup your OS to run
MCX-CL.
#### Verify GPU/CPU support
To verify if you have installed the OpenCL or CUDA support, you may
* if you have a windows machine, download and install the
[Everything Search](https://www.voidtools.com/) tool (a small and
fast file name search utility), and type `opencl.dll` in the search bar
**Expected result**: you must see `OpenCL.dll` (or `nvopencl.dll`
if you have an NVIDIA GPU) installed in the `Windows\System32` directory.
* if you have a Mac, open a terminal, and type `ls /System/Library/Frameworks/OpenCL.framework/Versions/A/OpenCL`
** **Expected result**: you should not see an error.
* if you have a Linux laptop, open a terminal, and type `locate libOpenCL.so`,
** **Expected result**: you should see one or multiple libOpenCL files
If the `OpenCL.dll` file is not found on your system, please
read the below sections. Otherwise, please go to Step 2: Install MATLAB.
#### Computers without discrete GPUs
In many cases, your computer runs on an Intel CPU with integrated graphics. In
this case, please make sure you have installed the latest Intel graphics drivers.
If you are certain that you have installed the graphics drivers, or your
graphics works smoothly, please skip this step.
If you want to double check, for Windows machine, you can download the
"Intel Driver&Support Assistant" to check if you have installed the
graphics drivers from https://downloadcenter.intel.com/download/24345/Intel-Driver-Support-Assistant
For a Mac, you need to use your App store to update the driver, see the
below link for details https://www.intel.com/content/www/us/en/support/articles/000022440/graphics-drivers.html
for a Linux (for example Ubuntu) laptop, the intel CPU OpenCL run-time
can be downloaded from https://software.intel.com/en-us/articles/opencl-drivers#latest_CPU_runtime
if you want to use both Intel CPU and GPU on Linux, you need to install
the OpenCL™ 2.0 GPU/CPU driver package for Linux* (this involves compiling a new kernel)
https://software.intel.com/en-us/articles/opencl-drivers#latest_linux_driver
#### Computers with discrete GPUs
If you have a computer with a discrete GPU, you need to make sure your
discrete GPU is configured with the appropriate GPU
driver installed. Again, if you have been using your laptop regularly and
the graphics has been smooth, likely your graphics driver has already been
installed.
If your GPU driver was not installed, and would like to install, or upgrade
from an older version, for an NVIDIA GPU, you may browse this link to
install the matching driver from http://www.nvidia.com/Download/index.aspx
If your GPU is an AMD GPU, please use the below link https://support.amd.com/en-us/download
It is also possible to simultaneously access Intel CPU along with your
discrete GPU. In this case, you need to download the latest Intel OpenCL
Runtime for CPU only if you haven't installed it already from
https://software.intel.com/en-us/articles/opencl-drivers#latest_CPU_runtime
**Note:** If you have an NVIDIA GPU, there is no need to install CUDA in
order for you to run MCX/MCXLAB.
### Step 2. Install MATLAB or GNU Octave
One must install either a MATLAB or GNU Octave if one needs to use mcxlabcl.
If you use a Mac or Linux laptop, you need to create a link (if this link does
not exist) so that your system can find MATLAB. To do this you start a terminal,
and type
sudo ln -s /path/to/matlab /usr/local/bin
please replace `/path/to/matlab` to the actual `matlab` command
full path (for Mac, this is typically `/Application/MATLAB_R20???.app/bin/matlab`,
for Linux, it is typically `/usr/local/MATLAB/R20???/bin/matlab`, `???`
is the year and release, such as 18a, 17b etc). You need to type your
password to create this link.
To verify your computer has MATLAB installed, please start a terminal on a
Mac or Linux, or type `cmd` and enter in Windows start menu, in the terminal,
type `matlab` and enter, you should see MATLAB starts.
### Step 3. Installing MCXCL
One can either choose to compile mcxcl locally or download pre-compiled binaries from MCX's website.
#### Compile From Source
This section assumes you are on a Linux-based machine, e.g. Ubunutu, CentOS, etc.
Clone this repository:
```
git clone https://github.com/fangq/mcxcl.git
```
From here we can either use the latest master branch (default) or latest release, which is v2020 currently.
To change which release you are using we have to enter the directory we just cloned:
```
cd mcxcl
```
From here we can change releases if desired:
```
git checkout v2020
```
After the version of mcxcl has been checkedout we can start compiling from source. Now enter the `src` folder:
```
cd src
```
We can do one of three things here - compile a standalone binary of mcxcl, a MATLAB/mex version, or an Octave/oct version.
##### Standalone Binary
Simply run: `make`
Which will compile a binary and place it in `mcxcl/bin`
##### MATLAB
Make sure you have mex in your `$PATH`, which can be done via:
```
export PATH="/path/to/matlab/bin/mex:$PATH"
```
Run: `make mex`
This will output the mex file to `mcxcl/mcxlabcl`
##### Octave
Make sure you have the following dependences - assuming you are running Ubuntu:
```
sudo apt install -y liboctave-dev
```
Run: `make oct`
This will output the octave/mex file to `mcxcl/mcxlabcl`
##### Misc
After you have compilied and copied your binary to a seperate location you can run `make clean` to remove all the build files that were
created during compilation.
#### Download MCXCL
One can download two separate MCXCL packages (standalone mcxcl binary, and mcxlabcl)
or download the integrated MCXStudio package (which contains mcx, mcxcl, mmc, mcxlab,
mcxlabcl and mmclab) where both packages, and many more, are included. The latest
stable released can be found on the MCX's website. However, if you want to use the
latest (but sometimes containing half-implemented features) software, you can access
the nightly-built packages from http://mcx.space/nightly/
If one has downloaded the mcxcl binary package, after extraction, you may open
a terminal (on Windows, type cmd the Start menu), cd mcxcl folder and then cd
the bin subfolder. Please type "mcxcl" and enter, if the binary is compatible with
your OS, you should see the printed help info. The next step is to run
mcxcl -L
This will query your system and find any hardware that can run mcxcl. If your
hardware (CPU and GPU) have proper driver installed, the above command will typically
return 1 or more available computing hardware. Then you can move to the next step.
If you do not see any processor printed, that means your CPU or GPU does not have
OpenCL support (because it is too old or no driver installed). You will need to
go to their vendor's website and download the latest driver. For Intel CPUs older
than Ivy Bridge (4xxx), OpenCL and MCXCl are not well supported. Please consider
installing dedicated GPU or use a different computer.
In the case one has installed the MCXStudio package, you may follow the below
procedure to test for hardware compatibility.
Please click on the folder matching your operating system (for example, if you run
a 64bit Windows, you need to navigate into `win64` folder), and download
the file named `"MCXStudio-nightlybuild-installer.exe"`.
Open this file, and unzip it to a working folder (for Windows, for example, the
`Documents` or `Downloads` folder). The package needs about 100 MB disk space.
Once unzipped, you should be able to see a folder named `MCXStudio`,
with a few executables and 3 subfolders underneath. See the folder structure below:
MCXStudio/
├── MATLAB/
│ ├── mcxlab/
│ ├── mcxlabcl/
│ └── mmclab/
├── MCXSuite/
│ ├── mcx/
│ ├── mcxcl/
│ └── mmc/
├── mcxstudio
├── mcxshow
└── mcxviewer
Please make sure that your downloaded `MCXStudio` must match your operating system.
#### Notes for Mac Users
**For Mac users:** Please unzip the package under your
[home directory](https://www.cnet.com/how-to/how-to-find-your-macs-home-folder-and-add-it-to-finder/) directly (Shift+Command+H).
#### Notes for Windows Users
When you start MCXStudio, you may see a dialog to ask you to modify the `TdrDelay` key
in the registry so that mcx can run more than 5 seconds. If you select `Yes`, some
of you may get an error saying you do not have permission.
To solve this problem, you need to quit MCXStudio, and then right-click on the
`mcxstudio.exe`, and select "Run as Administrator". Then, you should be
able to apply the registry change successfully.
Alternatively, one should open file browser, navigate into `mcxcl/setup/win64` folder,
and right-click on the `apply_timeout_registry_fix.bat` file and select
"Run as Administrator".
You must reboot your computer for this change to be effective!
### Step 4. Start MCXStudio and query GPU information
Now, navigate to the MCXStudio folder (i.e. the top folder of the extracted
software structure). On Windows, right-click on the executable named `"mcxstudio.exe"`
and select "Run as Administrator" for the first time only; on the Linux,
double click on the `mcxstudio` executable; on the Mac, open a
terminal and type
cd ~/MCXStudio
open mcxstudio.app
First, click on the "New" button to the top-left (green plus icon),
select the 3rd option "`NVIDIA/AMD/Intel CPUs/GPUs (MCX-CL)`",
and type a session name **"test"** in the field below. Then click
OK. You should see a blue/yellow "test" icon added to the left panel.
Now, click on the **"GPU"** button on the toolbar (6th button from
the left side), an Output window will popup, and wait for a few seconds,
you should see an output like
"-- Run Command --"
"mcxcl" -L
"-- Printing GPU Information --"
Platform [0] Name NVIDIA CUDA
============ GPU device ID 0 [1 of 2]: Graphics Device ============
Device 1 of 2: Graphics Device
Compute units : 80 core(s)
Global memory : 12644188160 B
Local memory : 49152 B
Constant memory : 65536 B
Clock speed : 1455 MHz
Compute Capacity: 7.0
Stream Processor: 10240
Vendor name : NVIDIA
Auto-thread : 655360
...
Platform [1] Name Intel(R) OpenCL
============ CPU device ID 2 [1 of 1]: Intel(R) Core(TM) i7-7700K CPU @ 4.20GHz ============
Device 3 of 1: Intel(R) Core(TM) i7-7700K CPU @ 4.20GHz
Compute units : 8 core(s)
Global memory : 33404575744 B
Local memory : 32768 B
Constant memory : 131072 B
Clock speed : 4200 MHz
Vendor name : Intel
Auto-thread : 512
Auto-block : 64
"-- Task completed --"
Your output may look different from above. If you do not see any output, or
it returns no GPU found, that means your OpenCL support was not installed
properly. Please go back to Steps 1-2 and reinstall the drivers.
If you have Intel CPU with Integrated GPU, you should be able to see a section with
**"Platform [?] Name Intel(R) OpenCL"** in the above output. You may see only
the CPU is listed, or both the CPU and the integrated GPU.
### Step 5. Run a trial simulation
If your above GPU query was successful, you should now see in the middle panel
of the MCXStudio window, under the Section entitled "GPU Settings", in a check-box
list under "Run MCX on", you should now see the available devices on your laptop.
To avoid running lengthy simulations, please change the _"Total photon number (-n)"_
field under the _"Basic Settings"_ from `1e6` to `1e5`.
Now, you can then run a trial simulation, by first clicking on the "Validate"
button (blue check-mark icon), and then click on "Run" (the button to the
right of validate). This will launch an MCXCL simulation. The output window
will show again, and you can see the messages printed from the simulation,
similar to the output below:
"-- Command: --"
mcxcl --session "preptest" --input "/Output/mcxclsessions/preptest/preptest.json" --root "/Output/mcxclsessions/preptest" --outputformat mc2 --gpu 10 --autopilot 1 --photon 10000000 --normalize 1 --save2pt 1 --reflect 1 --savedet 1 --unitinmm 1.00 --saveseed 0 --seed "1648335518" --compileropt "-D USE_ATOMIC" --array 0 --dumpmask 0 --repeat 1 --maxdetphoton 10000000
"-- Executing Simulation --"
==============================================================================
= Monte Carlo eXtreme (MCX) -- OpenCL =
= Copyright (c) 2010-2018 Qianqian Fang =
= http://mcx.space/ =
= =
= Computational Optics&Translational Imaging (COTI) Lab - http://fanglab.org =
= Department of Bioengineering, Northeastern University =
==============================================================================
= The MCX Project is funded by the NIH/NIGMS under grant R01-GM114365 =
==============================================================================
$Rev::6e839e $ Last $Date::2017-07-20 12:46:23 -04$ by $Author::Qianqian Fang$
==============================================================================
- variant name: [Detective MCXCL] compiled with OpenCL version [1]
- compiled with: [RNG] Logistic-Lattice [Seed Length] 5
initializing streams ... init complete : 0 ms
Building kernel with option: -cl-mad-enable -DMCX_USE_NATIVE -DMCX_SIMPLIFY_BRANCH -DMCX_VECTOR_INDEX -DMCX_SRC_PENCIL -D USE_ATOMIC -DUSE_ATOMIC -D MCX_SAVE_DETECTORS -D MCX_DO_REFLECTION
build program complete : 23 ms
- [device 0(1): Graphics Device] threadph=15 oddphotons=169600 np=10000000.0 nthread=655360 nblock=64 repetition=1
set kernel arguments complete : 23 ms
lauching mcx_main_loop for time window [0.0ns 5.0ns] ...
simulation run# 1 ...
kernel complete: 796 ms
retrieving flux ...
detected 0 photons, total: 0 transfer complete: 818 ms
normalizing raw data ... normalization factor alpha=20.000000
saving data to file ... 216000 1 saving data complete : 821 ms
simulated 10000000 photons (10000000) with 1 devices (repeat x1)
MCX simulation speed: 12953.37 photon/ms
total simulated energy: 10000000.00 absorbed: 27.22654%
(loss due to initial specular reflection is excluded in the total)
If this simulation is completed successfully, you should be able to see the
"Simulation speed" and total simulated energy reported at the end. Please
verify your "absorbed" percentage value printed at the end (in bold above),
and make sure it is **~27%**. We found that some Intel OpenCL library
versions produced incorrect results.
If your laptop shows an error for the Intel GPU, please choose another
device from the "GPU Settings" section, and run the simulation again.
If your GPU/CPU gives the below error (found on HD4400 GPU and 4th gen Intel CPUs)
error: OpenCL extension 'cl_khr_fp64' is unsupported
MCXCL ERROR(11):Error: Failed to build program executable! in unit mcx_host.cpp:510
You may add
-J "-DUSE_LL5_RAND"
in the `MCXStudio GUI`>`Advanced Settings`>`Additional Parameters`
field. This should allow it to run, but please verify the absorption fraction
is ~27%. For 4th generation Intel CPU, we found that install the Intel CPU
OpenCL run-time can produce correct simulations. Please download it from
https://software.intel.com/en-us/articles/opencl-drivers#latest_CPU_runtime
### Step 6. Test MATLAB for visualization
From v2019.3, MCXStudio provides builtin 3D volume visualization, this step is no longer needed.
### Step 7. Setting up MATLAB search path
The next step is to set up the search paths for MCXLAB/MMCLAB. You need to
start MATLAB, and in the Command window, please type
pathtool
this will popup a window. Click on the "Add with Subfolders ..." button
(the 2nd from the top), then browse the MCXStudio folder, then select
OK. Now you should see all needed MCX/MMC paths are added to MATLAB.
Before you quick this window, click on the "Save" button.
To verify if your MCXLAB/MMCLAB/MCXLABCL has been installed properly, please type
which mcxlab
which mmclab
which mcxlabcl
you should see their full paths printed.
To see if you can run MCXLAB-CL in your environment, please type
USE_MCXCL=1 ''%define this line in the base workspace, all subsequent mcxlab calls will use mcxcl''
info=mcxlab('gpuinfo')
clear USE_MCXCL
this should print a list of CPU/GPU devices using which you can run the MC simulations.
upload: matlab_gpu_verify.png
If you do not see any output, that means your CPU/GPU OpenCL driver was not installed
properly, you need to go back to Steps 1-2.
If you have an NVIDIA GPU, and have installed the proper GPU driver, you may run
info=mcxlab('gpuinfo') % notice the command is mcxlab instead of mcxlabcl
this should print a list of NVIDIA GPU from the MATLAB window.
Running Simulations
----------------------------
To run a simulation, the minimum input is a configuration (text) file,
and a volume (a binary file with each byte representing a medium
index). Typing the name of the executable without any parameters,
will print the help information and a list of supported parameters,
such as the following:
==============================================================================
= Monte Carlo eXtreme (MCX) -- OpenCL =
= Copyright (c) 2010-2020 Qianqian Fang =
= http://mcx.space/ =
= =
= Computational Optics&Translational Imaging (COTI) Lab - http://fanglab.org =
= Department of Bioengineering, Northeastern University, Boston, MA, USA =
==============================================================================
= The MCX Project is funded by the NIH/NIGMS under grant R01-GM114365 =
==============================================================================
$Rev::4fdc45$ v2020 $Date::2018-03-29 00:35:53 -04$ by $Author::Qianqian Fang$
==============================================================================
usage: mcxcl ...
where possible parameters include (the first value in [*|*] is the default)
== Required option ==
-f config (--input) read an input file in .json or .inp format
if the string starts with '{', it is parsed as
an inline JSON input file
or
--bench ['cube60','skinvessel',..] run a buint-in benchmark specified by name
run --bench without parameter to get a list
== MC options ==
-n [0|int] (--photon) total photon number (exponential form accepted)
-r [1|+/-int] (--repeat) if positive, repeat by r times,total= #photon*r
if negative, divide #photon into r subsets
-b [1|0] (--reflect) 1 to reflect photons at ext. boundary;0 to exit
-B '______' (--bc) per-face boundary condition (BC), 6 letters for
/case insensitive/ bounding box faces at -x,-y,-z,+x,+y,+z axes;
overwrite -b if given.
each letter can be one of the following:
'_': undefined, fallback to -b
'r': like -b 1, Fresnel reflection BC
'a': like -b 0, total absorption BC
'm': mirror or total reflection BC
'c': cyclic BC, enter from opposite face
if input contains additional 6 letters,
the 7th-12th letters can be:
'0': do not use this face to detect photon, or
'1': use this face for photon detection (-d 1)
the order of the faces for letters 7-12 is
the same as the first 6 letters
eg: --bc ______010 saves photons exiting at y=0
-u [1.|float] (--unitinmm) defines the length unit for the grid edge
-U [1|0] (--normalize) 1 to normalize flux to unitary; 0 save raw
-E [0|int|mch](--seed) set random-number-generator seed, -1 to generate
if an mch file is followed, MCX "replays"
the detected photon; the replay mode can be used
to calculate the mua/mus Jacobian matrices
-z [0|1] (--srcfrom0) 1 volume origin is [0 0 0]; 0: origin at [1 1 1]
-Y [0|int] (--replaydet) replay only the detected photons from a given
detector (det ID starts from 1), used with -E
if 0, replay all detectors and sum all Jacobians
if -1, replay all detectors and save separately
-V [0|1] (--specular) 1 source located in the background,0 inside mesh
-e [0.|float] (--minenergy) minimum energy level to trigger Russian roulette
-g [1|int] (--gategroup) number of maximum time gates per run
== GPU options ==
-L (--listgpu) print GPU information only
-t [16384|int](--thread) total thread number
-T [64|int] (--blocksize) thread number per block
-A [1|int] (--autopilot) auto thread config:1 enable;0 disable
-G [0|int] (--gpu) specify which GPU to use, list GPU by -L; 0 auto
or
-G '1101' (--gpu) using multiple devices (1 enable, 0 disable)
-W '50,30,20' (--workload) workload for active devices; normalized by sum
-I (--printgpu) print GPU information and run program
-o [1|int] (--optlevel) optimization level 0-no opt;1,2,3 more optimized
-J '-DMACRO' (--compileropt) specify additional JIT compiler options
A few built-in preprocessors include
-DMCX_GPU_DEBUG - print step-by-step debug info
-k my_simu.cl (--kernel) user specified OpenCL kernel source file
== Input options ==
-P '{...}' (--shapes) a JSON string for additional shapes in the grid.
only the root object named 'Shapes' is parsed
and added to the existing domain defined via -f
or --bench
-j '{...}' (--json) a JSON string for modifying all input settings.
this input can be used to modify all existing
settings defined by -f or --bench
-K [1|int|str](--mediabyte) volume data format, use either a number or a str
1 or byte: 0-128 tissue labels
2 or short: 0-65535 (max to 4000) tissue labels
4 or integer: integer tissue labels
100 or muamus_float: 2x 32bit floats for mua/mus
101 or mua_float: 1 float per voxel for mua
102 or muamus_half: 2x 16bit float for mua/mus
103 or asgn_byte: 4x byte gray-levels for mua/s/g/n
104 or muamus_short: 2x short gray-levels for mua/s
-a [0|1] (--array) 1 for C array (row-major); 0 for Matlab array
== Output options ==
-s sessionid (--session) a string to label all output file names
-O [X|XFEJP] (--outputtype) X - output flux, F - fluence, E - energy density
J - Jacobian (replay mode), P - scattering
event counts at each voxel (replay mode only)
-d [1|0] (--savedet) 1 to save photon info at detectors; 0 not save
-w [DP|DSPMXVW](--savedetflag)a string controlling detected photon data fields
/case insensitive/ 1 D output detector ID (1)
2 S output partial scat. even counts (#media)
4 P output partial path-lengths (#media)
8 M output momentum transfer (#media)
16 X output exit position (3)
32 V output exit direction (3)
64 W output initial weight (1)
combine multiple items by using a string, or add selected numbers together
by default, mcx only saves detector ID and partial-path data
-x [0|1] (--saveexit) 1 to save photon exit positions and directions
setting -x to 1 also implies setting '-d' to 1
same as adding 'XV' to -w.
-X [0|1] (--saveref) 1 to save diffuse reflectance at the air-voxels
right outside of the domain; if non-zero voxels
appear at the boundary, pad 0s before using -X
-m [0|1] (--momentum) 1 to save photon momentum transfer,0 not to save.
same as adding 'M' to the -w flag
-q [0|1] (--saveseed) 1 to save photon RNG seed for replay; 0 not save
-M [0|1] (--dumpmask) 1 to dump detector volume masks; 0 do not save
-H [1000000] (--maxdetphoton) max number of detected photons
-S [1|0] (--save2pt) 1 to save the flux field; 0 do not save
-F [mc2|...] (--outputformat) fluence data output format:
mc2 - MCX mc2 format (binary 32bit float)
jnii - JNIfTI format (http://openjdata.org)
bnii - Binary JNIfTI (http://openjdata.org)
nii - NIfTI format
hdr - Analyze 7.5 hdr/img format
tx3 - GL texture data for rendering (GL_RGBA32F)
the bnii/jnii formats support compression (-Z) and generate small files
load jnii (JSON) and bnii (UBJSON) files using below lightweight libs:
MATLAB/Octave: JNIfTI toolbox https://github.com/fangq/jnifti,
MATLAB/Octave: JSONLab toolbox https://github.com/fangq/jsonlab,
Python: PyJData: https://pypi.org/project/jdata
JavaScript: JSData: https://github.com/fangq/jsdata
-Z [zlib|...] (--zip) set compression method if -F jnii or --dumpjson
is used (when saving data to JSON/JNIfTI format)
0 zlib: zip format (moderate compression,fast)
1 gzip: gzip format (compatible with *.gz)
2 base64: base64 encoding with no compression
3 lzip: lzip format (high compression,very slow)
4 lzma: lzma format (high compression,very slow)
5 lz4: LZ4 format (low compression,extrem. fast)
6 lz4hc: LZ4HC format (moderate compression,fast)
--dumpjson [-,0,1,'file.json'] export all settings,including volume data using
JSON/JData (http://openjdata.org) format for
easy sharing; can be reused using -f
if followed by nothing or '-', mcx will print
the JSON to the console; write to a file if file
name is specified; by default, prints settings
after pre-processing; '--dumpjson 2' prints
raw inputs before pre-processing
== User IO options ==
-h (--help) print this message
-v (--version) print MCX revision number
-l (--log) print messages to a log file instead
-i (--interactive) interactive mode
== Debug options ==
-D [0|int] (--debug) print debug information (you can use an integer
or or a string by combining the following flags)
-D [''|RMP] 1 R debug RNG
/case insensitive/ 2 M store photon trajectory info
4 P print progress bar
combine multiple items by using a string, or add selected numbers together
== Additional options ==
--atomic [1|0] 1: use atomic operations; 0: do not use atomics
--voidtime [1|0] when src is outside, 1 enables timer inside void
--showkernel [1|0] 1:display the default or loaded (-k) MCXCL kernel
--root [''|string] full path to the folder storing the input files
--internalsrc [0|1] set to 1 to skip entry search to speedup launch
--gscatter [1e9|int] after a photon completes the specified number of
scattering events, mcx then ignores anisotropy g
and only performs isotropic scattering for speed
--maxvoidstep [1000|int] maximum distance (in voxel unit) of a photon that
can travel before entering the domain, if
launched outside (i.e. a widefield source)
--maxjumpdebug [10000000|int] when trajectory is requested (i.e. -D M),
use this parameter to set the maximum positions
stored (default: 1e7)
== Example ==
example: (list built-in benchmarks)
mcxcl --bench
or (list supported GPUs on the system)
mcxcl -L
or (use multiple devices - 1st,2nd and 4th GPUs - together with equal load)
mcxcl --bench cube60b -n 1e7 -G 1101 -W 10,10,10
or (use inline domain definition)
mcxcl -f input.json -P '{"Shapes":[{"ZLayers":[[1,10,1],[11,30,2],[31,60,3]]}]}'
or (use inline json setting modifier)
mcxcl -f input.json -j '{"Optode":{"Source":{"Type":"isotropic"}}}'
or (dump simulation in a single json file)
mcxcl --bench cube60planar --dumpjson
To further illustrate the command line options, below one can find a sample command
```
mcxcl -A 0 -t 16384 -T 64 -n 1e7 -G 1 -f input.json -r 2 -s test -g 10 -d 1 -w dpx -b 1
```
the command above asks mcxcl to manually (`-A 0`) set GPU threads, and launch 16384
GPU threads (`-t`) with every 64 threads a block (`-T`); a total of 1e7 photons (`-n`)
are simulated by the first GPU (`-G 1`) and repeat twice (`-r`) - i.e. total 2e7 photons;
the media/source configuration will be read from a JSON file named `input.json`
(`-f`) and the output will be labeled with the session id “test” (`-s`); the
simulation will run 10 concurrent time gates (`-g`) if the GPU memory can not
simulate all desired time gates at once. Photons passing through the defined
detector positions are saved for later rescaling (`-d`); refractive index
mismatch is considered at media boundaries (`-b`).
Historically, MCXCL supports an extended version of the input file format (.inp)
used by tMCimg. However, we are phasing out the .inp support and strongly
encourage users to adopt JSON formatted (.json) input files. Many of the
advanced MCX options are only supported in the JSON input format.
A legacy .inp MCXCL input file looks like this:
```
1000000 # total photon, use -n to overwrite in the command line
29012392 # RNG seed, negative to generate, use -E to overwrite
30.0 30.0 0.0 1 # source position (in grid unit), the last num (optional) sets --srcfrom0 (-z)
0 0 1 0 # initial directional vector, 4th number is the focal-length, 0 for collimated beam, nan for isotropic
0.e+00 1.e-09 1.e-10 # time-gates(s): start, end, step
semi60x60x60.bin # volume ('unsigned char' binary format, or specified by -K/--mediabyte)
1 60 1 60 # x voxel size in mm (isotropic only), dim, start/end indices
1 60 1 60 # y voxel size, must be same as x, dim, start/end indices
1 60 1 60 # y voxel size, must be same as x, dim, start/end indices
1 # num of media
1.010101 0.01 0.005 1.37 # scat. mus (1/mm), g, mua (1/mm), n
4 1.0 # detector number and default radius (in grid unit)
30.0 20.0 0.0 2.0 # detector 1 position (real numbers in grid unit) and individual radius (optional)
30.0 40.0 0.0 # ..., if individual radius is ignored, MCX will use the default radius
20.0 30.0 0.0 #
40.0 30.0 0.0 #
pencil # source type (optional)
0 0 0 0 # parameters (4 floats) for the selected source
0 0 0 0 # additional source parameters
```
Note that the scattering coefficient mus=musp/(1-g).
The volume file (`semi60x60x60.bin` in the above example), can be read in two
ways by MCX: row-major[3] or column-major depending on the value of the user
parameter `-a`. If the volume file was saved using matlab or fortran, the
byte order is column-major, and you should use `-a 0` or leave it out of
the command line. If it was saved using the `fwrite()` in C, the order is
row-major, and you can either use `-a 1`.
You may replace the binary volume file by a JSON-formatted shape file. Please
refer to Section V for details.
The time gate parameter is specified by three numbers: start time, end time and
time step size (in seconds). In the above example, the configuration specifies
a total time window of [0 1] ns, with a 0.1 ns resolution. That means the
total number of time gates is 10.
MCX provides an advanced option, -g, to run simulations when the GPU memory is
limited. It specifies how many time gates to simulate concurrently. Users may
want to limit that number to less than the total number specified in the input
file - and by default it runs one gate at a time in a single simulation. But if
there's enough memory based on the memory requirement in Section II, you can
simulate all 10 time gates (from the above example) concurrently by using
`-g 10` in which case you have to make sure the video card has at least
60\*60\*60\*10\*5=10MB of free memory. If you do not include the `-g`, MCX will
assume you want to simulate just 1 time gate at a time.. If you specify a
time-gate number greater than the total number in the input file, (e.g,
`-g 20`) MCX will stop when the 10 time-gates are completed. If you use the
autopilot mode (`-A`), then the time-gates are automatically estimated for you.
Using JSON-formatted input files
-----------------------------------
Starting from version 0.7.9, MCX accepts a JSON-formatted input file in
addition to the conventional tMCimg-like input format. JSON (JavaScript Object
Notation) is a portable, human-readable and “fat-free” text format to
represent complex and hierarchical data. Using the JSON format makes a input
file self-explanatory, extensible and easy-to-interface with other applications
(like MATLAB).
A sample JSON input file can be found under the examples/quicktest folder. The
same file, `qtest.json`, is also shown below:
```
{
"Help": {
"[en]": {
"Domain::VolumeFile": "file full path to the volume description file, can be a binary or JSON file",
"Domain::Dim": "dimension of the data array stored in the volume file",
"Domain::OriginType": "similar to --srcfrom0, 1 if the origin is [0 0 0], 0 if it is [1.0,1.0,1.0]",
"Domain::LengthUnit": "define the voxel length in mm, similar to --unitinmm",
"Domain::Media": "the first medium is always assigned to voxels with a value of 0 or outside of
the volume, the second row is for medium type 1, and so on. mua and mus must
be in 1/mm unit",
"Session::Photons": "if -n is not specified in the command line, this defines the total photon number",
"Session::ID": "if -s is not specified in the command line, this defines the output file name stub",
"Forward::T0": "the start time of the simulation, in seconds",
"Forward::T1": "the end time of the simulation, in seconds",
"Forward::Dt": "the width of each time window, in seconds",
"Optode::Source::Pos": "the grid position of the source, can be non-integers, in grid unit",
"Optode::Detector::Pos": "the grid position of a detector, can be non-integers, in grid unit",
"Optode::Source::Dir": "the unitary directional vector of the photon at launch",
"Optode::Source::Type": "source types, must be one of the following:
pencil,isotropic,cone,gaussian,planar,pattern,fourier,arcsine,disk,fourierx,fourierx2d,
zgaussian,line,slit,pencilarray,pattern3d",
"Optode::Source::Param1": "source parameters, 4 floating-point numbers",
"Optode::Source::Param2": "additional source parameters, 4 floating-point numbers"
}
},
"Domain": {
"VolumeFile": "semi60x60x60.bin",
"Dim": [60,60,60],
"OriginType": 1,
"LengthUnit": 1,
"Media": [
{"mua": 0.00, "mus": 0.0, "g": 1.00, "n": 1.0},
{"mua": 0.005,"mus": 1.0, "g": 0.01, "n": 1.0}
]
},
"Session": {
"Photons": 1000000,
"RNGSeed": 29012392,
"ID": "qtest"
},
"Forward": {
"T0": 0.0e+00,
"T1": 5.0e-09,
"Dt": 5.0e-09
},
"Optode": {
"Source": {
"Pos": [29.0, 29.0, 0.0],
"Dir": [0.0, 0.0, 1.0],
"Type": "pencil",
"Param1": [0.0, 0.0, 0.0, 0.0],
"Param2": [0.0, 0.0, 0.0, 0.0]
},
"Detector": [
{
"Pos": [29.0, 19.0, 0.0],
"R": 1.0
},
{
"Pos": [29.0, 39.0, 0.0],
"R": 1.0
},
{
"Pos": [19.0, 29.0, 0.0],
"R": 1.0
},
{
"Pos": [39.0, 29.0, 0.0],
"R": 1.0
}
]
}
}
```
A JSON input file requiers several root objects, namely `Domain`,
`Session`, `Forward` and `Optode`. Other root sections, like
`Help`, will be ignored. Each object is a data structure providing
information indicated by its name. Each object can contain various sub-fields.
The orders of the fields in the same level are flexible. For each field, you
can always find the equivalent fields in the `*.inp` input files. For example,
The `VolumeFile` field under the `Domain` object is the same as Line\#6
in `qtest.inp`; the `RNGSeed` under `Session` is the same as Line\#2; the
`Optode.Source.Pos` is the same as the triplet in Line\#3; the
`Forward.T0` is the same as the first number in Line\#5, etc.
An MCX JSON input file must be a valid JSON text file. You can validate your
input file by running a JSON validator, for example
本源码包内暂不包含可直接显示的源代码文件，请下载源码包。
