mcx
v2024.2 (Interstellar Ion)
Table of Content:
MCX v2024.2 contains both major new features and critical bug fixes. It is a strongly recommended upgrade for all users.
Specifically, MCX v2024.2 received three important new features:
Similar to the user-defined phase-function feature included in
MCX v2023, the first feature allows users to define the zenith angle distribution for
launching a photon, relative to the source-direction vector, also via
a discretized inverse CDF (cumulative distribution function).
In MATLAB/Octave, they can be set as cfg.invcdf or cfg.angleinvcdf,
respectively. We provided ready-to-use demo scripts in
mcxlab/examples/demo_mcxlab_phasefun.m and demo_mcxlab_launchangle.m.
The second feature allow users to specify more then one sources of the
same type when defining srcpos, srcdir, srcparam1 and srcparam2.
Each source can have independent weight controled by the 4th element of srcpos.
Aside from new features, a severe bug was discovered that affects all
pattern and pattern3d simulations that do not use photon-sharing,
please see
#212
Because of this bug, MCX/MCX-CL in older releases has been simulating squared pattern/pattern3d data instead of the pattern itself. If your simulation uses these two source types and you do not use photon-sharing (i.e. simulating multiple patterns together), please upgrade your MCX/MCX-CL and rerun your simulations. This bug only affect volumetric fluence/flux outputs; it does not affect diffuse reflectance outputs or binary patterns.
It also includes a bug fix from #195 regarding precision loss when saving diffuse reflectance.
We want to thank Haohui Zhang for reporting a number of critical issues (#195 and #212), Liam Keegan for contributing a patch to extend the slit source (#214). ShijieYan and fanyuyen have also contributed to the bug fixes and improvements.
The detailed updates can be found in the below change log
Monte Carlo eXtreme (MCX) is a fast physically-accurate photon simulation software for 3D heterogeneous complex 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 single-threaded CPU-based MC implementation.
MCX is written in C and NVIDIA CUDA. It only be executed on NVIDIA GPUs. If you want to run hardware-accelerated MCX simulations on AMD/Intel GPUs or CPUs, please download MCX-CL (MCX for OpenCL), which is written in OpenCL. MCX and MCX-CL are highly compatible.
Due to the nature of the underlying MC algorithms, MCX and MCX-CL are ray-tracing/ray-casting software under-the-hood. Compared to commonly seen ray-tracing libraries used in computer graphics or gaming engines, MCX-CL and MCX have many unique characteristics. The most important difference is that MCX/MCX-CL are rigorously based on physical laws. They are numerical solvers to the underlying radiative transfer equation (RTE) and their solutions have been validated across many publications using optical instruments and experimental measurements. In comparison, most graphics-oriented ray-tracers have to make many approximations in order to achieve fast rendering, enable to provide quantitatively accurate light simulation results. Because of this, MCX/MCX-CL have been extensively used by biophotonics research communities to obtain reference solutions and guide the development of novel medical imaging systems or clinical applications. Additionally, MCX/MCX-CL are volumetric ray-tracers; they traverse photon-rays throughout complex 3-D domains and computes physically meaningful quantities such as spatially resolved fluence, flux, diffuse reflectance/transmittance, energy deposition, partial pathlengths, among many others. In contrast, most graphics ray-tracing engines only trace the RGB color of a ray and render it on a flat 2-D screen. In other words, MCX/MCX-CL gives physically accurate 3-D light distributions while graphics ray-tracers focus on 2-D rendering of a scene at the camera. Nonetheless, they share many similarities, such as ray-marching computation, GPU acceleration, scattering/absorption handling etc.
The algorithm of this software is detailed in the References [Fang2009,Yu2018,Yan2020]. A short summary of the main features includes:
This software can be used on Windows, Linux and Mac OS. MCX is written in C/CUDA and requires NVIDIA GPUs (support for AMD/Intel CPUs/GPUs via ROCm is still under development). A more portable OpenCL implementation of MCX, i.e. MCXCL, was announced on July, 2012 and supports almost all NVIDIA/AMD/Intel CPU and GPU models. If your hardware does not support CUDA, please download MCXCL from the below URL:
https://mcx.space/wiki/index.cgi?Learn#mcxcl
Please read this section carefully. The majority of failures using MCX were found related to incorrect installation of NVIDIA GPU driver.
Please browse https://mcx.space/#documentation for step-by-step instructions.
For MCX-CUDA, the requirements for using this software include
You must make sure that your NVIDIA graphics driver was installed properly.
A list of CUDA capable cards can be found at [2]. The oldest
GPU architecture that MCX source code can be compiled is Fermi (sm_20).
Using the latest NVIDIA card is expected to produce the best
speed. The officially released binaries (including mex files and pmcx modules)
can run on NVIDIA GPUs as old as Kepler (GTX-730, sm_35). All MCX binaries
can run directly on future generations of NVIDIA GPUs without needing to
be recompiled, therefore forward-compatible.
In the below webpage, we summarized the speed differences between different generations of NVIDIA GPUs
https://mcx.space/gpubench/
For simulations with large volumes, sufficient graphics memory is also required to perform the simulation. The minimum amount of graphics memory required for a MC simulation is Nx*Ny*Nz bytes for the input tissue data plus Nx*Ny*Nz*Ng*4*2 bytes for the output flux/fluence data - where Nx,Ny,Nz are the dimensions of the tissue volume, Ng is the number of concurrent time gates, 4 is the size of a single-precision floating-point number, 2 is for the extra memory needed to ensure output accuracy (#41). MCX does not require double-precision support in your hardware.
MCX stores optical properties and detector positions in the constant memory. Usually, NVIDIA GPUs provides about 64 kB constant memory. As a result, we can only the total number of optical properties plus the number of detectors can not exceed 4000 (4000 * 4 * 4 = 64 k).
In addition, MCX stores detected photon data inside the shared memory, which also ranges between 42 kB to 100 kB per stream processor across different GPU generations. If your domain contains many medium types, it is possible that the allocation of the shared memory can exceed the limit. You will also receive an "out of memory" error.
To install MCX, you need to download the binary executable compiled for your
computer architecture (32 or 64bit) and platform, extract the package and run
the executable under the {mcx root}/bin directory.
For Windows users, you must make sure you have installed the appropriate NVIDIA
driver for your GPU. You should also configure your OS to run CUDA simulations.
This requires you to open the mcx/setup/win64 folder using your file explorer,
right-click on the apply_timeout_registry_fix.bat file and select
“Run as administrator”. After confirmation, you should see a windows
command window with message
Patching your registry
Done
Press any key to continue ...
You MUST REBOOT your Windows computer to make this setting effective. The above patch modifies your driver settings so that you can run MCX simulations for longer than a few seconds. Otherwise, when running MCX for over a few seconds, you will get a CUDA error: “unspecified error”.
Please see the below link for details
https://mcx.space/wiki/index.cgi?Doc/FAQ#I_am_getting_a_kernel_launch_timed_out_error_what_is_that
If you use Linux, you may enable Intel integrated GPU (iGPU) for display while
leaving your NVIDIA GPU dedicated for computing using nvidia-prime, see
https://forums.developer.nvidia.com/t/solved-run-cuda-on-dedicated-nvidia-gpu-while-connecting-monitors-to-intel-hd-graphics-is-this-possible/47690/6
or choose one of the 4 other approaches in this blog post
https://nvidia.custhelp.com/app/answers/detail/a_id/3029/~/using-cuda-and-x
We noticed that running Ubuntu Linux 22.04 with a 6.5 kernel on a laptop with a hybrid GPU with an Intel iGPU and an NVIDIA GPU, you must configure the laptop to use the NVIDIA GPU as the primary GPU by choosing "NVIDIA (Performance Mode)" in the PRIME Profiles section of NVIDIA X Server Settings. You can also run
sudo prime-select nvidia
to achieve the same goal. Otherwise, the simulation may hang your system after running for a few seconds. A hybrid GPU laptop combing an NVIDIA GPU with an AMD iGPU does not seem to have this issue if using Linux.
In addition, NVIDIA drirver (520 or newer) has a known glitch running on Linux kernel 6.x (such as those in Ubuntu 22.04). See
https://forums.developer.nvidia.com/t/dev-nvidia-uvm-io-error-on-ubuntu-22-04-520-to-535-driver-versions/262153
When the laptop is in the "performance" mode and wakes up from suspension, MCX or any CUDA program fails to run with an error
MCX ERROR(-999):unknown error in unit mcx_core.cu:2523
This is because the kernel module nvida-uvm fails to be reloaded after suspension.
If you had an open MATLAB session, you must close MATLAB first, and
run the below commands (if MATLAB is open, you will see rmmod: ERROR: Module nvidia_uvm is in use)
sudo rmmod /dev/nvidia-uvm
sudo modprobe nvidia-uvm
after the above command, MCX should be able to run again.
New generations of Mac computers no longer support NVIDIA or AMD GPUs. you will have to use the OpenCL version of MCX, MCX-CL by downloading it from
https://mcx.space/wiki/?Learn#mcxcl
To run a simulation, the minimum input is a configuration (text) file, and, if
the input file does not contain built-in domain shape descriptions, an external
volume file (a binary file with a specified voxel format via -K/--mediabyte).
Typing mcx without any parameters prints the help information and a list of
supported parameters, as shown below:
###############################################################################
# Monte Carlo eXtreme (MCX) -- CUDA #
# Copyright (c) 2009-2024 Qianqian Fang <q.fang at neu.edu> #
# https://mcx.space/ & https://neurojson.io/ #
# #
# 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 #
###############################################################################
# Open-source codes and reusable scientific data are essential for research, #
# MCX proudly developed human-readable JSON-based data formats for easy reuse.#
# #
#Please visit our free scientific data sharing portal at https://neurojson.io/#
# and consider sharing your public datasets in standardized JSON/JData format #
###############################################################################
$Rev::d593a0$v2024.2 $Date::2024-03-04 00:04:10 -05$ by $Author::Qianqian Fang$
###############################################################################
usage: mcx <param1> <param2> ...
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)
max accepted value:9.2234e+18 on 64bit systems
-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 [1648335518|int|mch](--seed) set rand-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]
-k [1|0] (--voidtime) when src is outside, 1 enables timer inside void
-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) 1 let mcx decide thread/block size, 0 use -T/-t
-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
--atomic [1|0] 1: use atomic operations to avoid thread racing
0: do not use atomic operation (not recommended)
== 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
voxel binary data layouts are shown in {...}, where [] for byte,[i:]
for 4-byte integer, [s:] for 2-byte short, [h:] for 2-byte half float,
[f:] for 4-byte float; on Little-Endian systems, least-sig. bit on left
1 or byte: 0-128 tissue labels
2 or short: 0-65535 (max to 4000) tissue labels
4 or integer: integer tissue labels
96 or asgn_float: mua/mus/g/n 4xfloat format
{[f:mua][f:mus][f:g][f:n]}
97 or svmc: split-voxel MC 8-byte format
{[n.z][n.y][n.x][p.z][p.y][p.x][upper][lower]}
98 or mixlabel: label1+label2+label1_percentage
{[label1][label2][s:0-32767 label1 percentage]}
99 or labelplus: 32bit composite voxel format
{[h:mua/mus/g/n][s:(B15-16:0/1/2/3)(label)]}
100 or muamus_float: 2x 32bit floats for mua/mus
{[f:mua][f:mus]}; g/n from medium type 1
101 or mua_float: 1 float per voxel for mua
{[f:mua]}; mus/g/n from medium type 1
102 or muamus_half: 2x 16bit float for mua/mus
{[h:mua][h:mus]}; g/n from medium type 1
103 or asgn_byte: 4x byte gray-levels for mua/s/g/n
{[mua][mus][g][n]}; 0-255 mixing prop types 1&2
104 or muamus_short: 2x short gray-levels for mua/s
{[s:mua][s:mus]}; 0-65535 mixing prop types 1&2
when formats 99 or 102 is used, the mua/mus values in the input volume
binary data must be pre-scaled by voxel size (unitinmm) if it is not 1.
pre-scaling is not needed when using these 2 formats in mcxlab/pmcx
-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|XFEJPMRL](--outputtype) X - output flux, F - fluence, E - energy deposit
/case insensitive/ J - Jacobian (replay mode), P - scattering,
event counts at each voxel (replay mode only)
M - momentum transfer; R - RF/FD Jacobian
L - total pathlength
-d [1|0-3] (--savedet) 1 to save photon info at detectors; 0 not save
2 reserved, 3 terminate simulation when detected
photon buffer is filled
-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 [jnii|...](--outputformat) fluence data output format:
mc2 - MCX mc2 format (binary 32bit float)
jnii - JNIfTI format (https://neurojson.org)
bnii - Binary JNIfTI (https://neurojson.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://neurojson.org/download/jnifti
MATLAB/Octave: JSONLab toolbox https://neurojson.org/download/jsonlab
Python: PyJData: https://neurojson.org/download/pyjdata
JavaScript: JSData: https://neurojson.org/download/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 (https://neurojson.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 [''|RMPT] 1 R debug RNG
/case insensitive/ 2 M store photon trajectory info
4 P print progress bar
8 T save trajectory data only, disable flux/detp
combine multiple items by using a string, or add selected numbers together
== Additional options ==
--root [''|string] full path to the folder storing the input files
--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
--srcid [0|-1,0,1,2,..] -1 simulate multi-source separately;0 all sources
together; a positive integer runs a single source
--internalsrc [0|1] set to 1 to skip entry search to speedup launch
--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)
mcx --bench
or (list supported GPUs on the system)
mcx -L
or (use multiple devices - 1st,2nd and 4th GPUs - together with equal load)
mcx --bench cube60b -n 1e7 -G 1101 -W 10,10,10
or (use inline domain definition)
mcx -f input.json -P '{"Shapes":[{"ZLayers":[[1,10,1],[11,30,2],[31,60,3]]}]}'
or (use inline json setting modifier)
mcx -f input.json -j '{"Optode":{"Source":{"Type":"isotropic"}}}'
or (dump simulation in a single json file)
mcx --bench cube60planar --dumpjson
To further illustrate the command line options, below one can find a sample command
mcx -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 mcx 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, MCX 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 MCX 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.
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
