Preparation: Define the volume
The volume file is a binary file representing the tissue information of
a 3D volume. Each byte of the file is a label of a voxel - the label value
(0-255) is the index of the voxel's tissue type.

The volume file is specified in the JSON input file by the "VolumeFile" tag in
the "Domain" section. If one uses the legacy input file, the volume file is
specified on the 4th line.

Preparation: Legacy input file
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.

The legacy input file looks like the following:

1000000              # total photon, use -n to overwrite in the command line
29012392             # RNG seed, negative to generate
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 vx,vy,vz, last number is the focal length, nan for isotropic launch
0.e+00 1.e-09 1.e-10 # time-gates(s): start, end, step
semi60x60x60.bin     # volume ('unsigned char' format)
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            # z 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

Output: Fluence output
MCX outputs the 3D flux distribution by default (unless "-S 0" is used). Alternatively, if a user specifies "-O F", the output volume is the fluence; if "-O E" is used, the output volume is the energy deposit; if "-O J" or "-O T" is used, the output is the absorption sensitivity profile, i.e., the Jacobian of mua.

The volumetric output file has a suffix of ".mc2", and is a binary file with a size of (Nx x Ny x Nz x Nt x 4) bytes, where Nx/Ny/Nz are the dimensions of the input volume in the x/y/z direction, respectively, Nt is the total number of time gates, calculated by ceil((tend-tstart)/tstep), and the number 4 represents the byte length of a single-precision floating-point number. The first (Nx x Ny x Nz) floating-point numbers (4 bytes each) are the accumulated fluence distribution, in the unit of (1/(s*mm^2)), for the first time gate (averaged at the middle of the time gate); then the second gate, and so on.

By default, MCX's flux/fluence output is normalized to produce a time-domain Green's function, or time-domain point-spread function (TPSF) - i.e., the solution for an impulse input of unitary energy at t=0. One can disable the normalization by using "-U 0".

The mc2 file can be loaded into MATLAB using the loadmc2() function, provided under the mcx/utils folder. Please run help loadmc2 for details.

To convert the flux output to fluence, one simply multiplies the solution by the time gate width, tstep, defined in the input file. Similarly, dividing tstep from the fluence solution produces the flux.

Output: Detected photon info
By default, MCX saves the information of the detected photons. One can also enable this feature by appending "-d 1" in the command line. The output file with the detected photon info is named "session_name.mch".

The mch file can be loaded into MATLAB using the loadmch() function, provided under the mcx/utils folder. Please run help loadmch for details.

The mch file is a binary file containing the following 3 blocks: a 256-byte header, followed by a block of floating-point numbers for the partial path lengths, then followed by a block of byte arrays recording the random number generator (RNG) seed data for each detected photon (20 bytes per photon). An mch file may contain multiple repetitions of the above 3-block data chunks.

The header contains the following information:

typedef struct MCXHistoryHeader{
	char magic[4];                 /** magic bits= 'M','C','X','H' */
	unsigned int  version;         /** version of the mch file format */
	unsigned int  maxmedia;        /** number of media in the simulation */
	unsigned int  detnum;          /** number of detectors in the simulation */
	unsigned int  colcount;        /** how many output columns per detected photon */
	unsigned int  totalphoton;     /** how many total photons simulated */
	unsigned int  detected;        /** how many photons are detected (not necessarily all saved) */
	unsigned int  savedphoton;     /** how many detected photons are saved in this file */
	float unitinmm;                /** what is the voxel size of the simulation */
	unsigned int  seedbyte;        /** how many bytes per RNG seed */
        float normalizer;              /** what is the normalization factor */
	int respin;                    /** if positive, repeat count so total photon=totalphoton*respin; if negative, total number is processed in respin subset */
	unsigned int  srcnum;          /** number of sources for simultaneous pattern sources */
	unsigned int  savedetflag;     /** detected photon output specifier */
	int reserved[2];               /** reserved fields for future extension */
};

Following the header, a total of savedphoton*colcount words (32bit) represent the detected photon info; each photon occupies "colcount" words saved in the order of being detected. A typical detected photon record consists of the following:

  DetID, ScatNum, PP1, PP2, ..., PPN

where DetID is an integer, indicating the index of the detector that captures the photon; ScatNum records the total number of scattering events before the photon is captured; PP1 - PPN are floating-point numbers, denoting the partial path lengths for media type 1 to N.

Output: Command line output
MCX outputs a text log on the command line window (stdout). In this log,
one can find the thread/block configuration, timing of each section of the simulation,
the detected photon info, and normalization information.

When -p/--printlen is used in the command line, MCX also prints the final state
of the last photon simulated by each thread. This information can be used to
debug MCX.

When compiling MCX with "make debug", MCX can print step-by-step debug info
of each simulated photon.

Options


 
JSON Input
Short
Long command
MATLAB/Octave
Value
Meaning
MCX,
MCXLAB,
MCXCL,
MCXLABCL,
MMC,
MMCLAB,
MMCL,
MMCLABCL
 Optical Parameters 
Domain.VolumeFile
cfg.vol
2D or 3D array
Domain volume
Y
Y
Y
Y

Mesh.ID
cfg.{node,elem}
mesh data
Domain mesh
Y
Y
Y
Y
Mesh.InitElem
cfg.e0
integer
Initial element index (>0)
Y
Y
Y
Y
Domain.Media
cfg.prop
(media count+1)x4 array
Optical properties
Y
Y
Y
Y
Y
Y
Y
Y
Forward.T0
cfg.tstart
float
Start time in seconds
Y
Y
Y
Y
Y
Y
Y
Y
Forward.T1
cfg.tend
float
End time in seconds
Y
Y
Y
Y
Y
Y
Y
Y
Forward.Dt
cfg.tstep
float
Time gate width in seconds
Y
Y
Y
Y
Y
Y
Y
Y
Optode.Source.Type
cfg.srctype
string ('pencil')
Source type
Y
Y
Y
Y
Y
Y
Y
Y
Optode.Source.Pos
cfg.srcpos
1x4 float
Source position in grid units
Y
Y
Y
Y
Y
Y
Y
Y
Optode.Source.Dir
cfg.srcdir
1x4 float
Source direction (vx,vy,vz) and focal length
Y
Y
Y
Y
Y
Y
Y
Y
Optode.Source.Param1
cfg.srcparam1
1x4 float
Source parameters set 1
Y
Y
Y
Y
Y
Y
Y
Y
Optode.Source.Param2
cfg.srcparam2
1x4 float
Source parameters set 2
Y
Y
Y
Y
Y
Y
Y
Y
Optode.Source.Pattern
cfg.srcpattern
2D or 3D array
Source pattern data
Y
Y
Y
Y
Y
Y
Y
Y
Optode.Detector.{Pos/R}
cfg.detpos
Nx4 array
Detector positions and radii
Y
Y
Y
Y
Y
Y
Y
Y
Forward.N0
cfg.n0
float
Background refractive index
Y
Y
Y
Y
 MC Settings 
-f
--input
-
string
Input file (.json or .inp)
Y
Y
Y
Y
Y
Y
Y
Y
Session.Photons
-n
--photon
cfg.nphoton
integer (0)
Total photon number
Y
Y
Y
Y
Y
Y
Y
Y
-r
--repeat
cfg.repeat
integer (1)
Repeat count (positive int)
Y
Y
Y
Y

Session.DoMismatch
-b
--reflect
cfg.isreflect
bool (1)
Whether to do reflection/transmission
Y
Y
Y
Y
Y
Y
Y
Y
-B
--bc
cfg.bc
6-char string (______)
Boundary conditions at 6 directions
Y
Y
Y
Y

Domain.LengthUnit
-u
--unitinmm
cfg.unitinmm
float (1)
Voxel edge length in mm
Y
Y
Y
Y
Y
Y
Y
Y
Session.DoNormalize
-U
--normalize
cfg.isnormalize
bool (1)
Whether to normalize the solutions
Y
Y
Y
Y
Y
Y
Y
Y
Session.RNGSeed
-E
--seed
cfg.seed
integer (0)
RNG seed (or a .mch file if replay)
Y
Y
Y
Y
Y
Y
Y
Y
Domain.OriginType
-z
--srcfrom0
cfg.issrcfrom0
bool (0)
Whether the lower-corner of the domain is 0,0,0
Y
Y
Y
Y

-R
--skipradius
cfg.skipradius
float (-2)
Whether to use atomic operations
Y
Y
Y
Y

-k
--voidtime
cfg.voidtime
bool (1)
Whether to count the time-of-flight before entry
Y
Y
Y
Y
Y
Y
Y
Y
-Y
--replaydet
cfg.replaydet
integer (-1)
Which detector to be replayed
Y
Y
Y
Y
Y
Y
Y
Y
Session.DoSpecular
-V
--specular
cfg.isspecular
bool (1)
Whether to do specular reflection upon entry
Y
Y
Y
Y
Y
Y
Y
Y
-e
--minenergy
cfg.minenergy
float (0)
Minimum energy to trigger Russian Roulette
Y
Y
Y
Y
Y
Y
Y
Y
-g
--gategroup
cfg.maxgate
integer (1)
Maximum time gates to be simulated together
Y
Y
Y
Y
Y
Y
 GPU Settings
-L
--listgpu
mcxlab('gpuinfo')
List available GPUs
Y
Y
Y
Y
Y
Y
-t
--thread
cfg.nthread
integer (16384)
Number of total threads
Y
Y
Y
Y
Y
Y
-T
--blocksize
cfg.nblocksize
integer (64)
Size of thread block
Y
Y
Y
Y
Y
Y
Session.DoAutoThread
-A
--autopilot
cfg.autopilot
bool (1)
Choosing thread/block automatically
Y
Y
Y
Y
Y
Y
-G
--gpu
cfg.gpuid
integer (1) or 01 string
Specify which GPUs to use
Y
Y
Y
Y
Y
Y
-W
--workload
cfg.workload
float,float,...
Workload split between GPUs
Y
Y
Y
Y
Y
Y
-I
--printgpu
-
Print GPU information then run simulation
Y
Y

 Input 
Shapes
-P
--shapes
cfg.shapes
JSON string '{...}'
JSON-based domain descriptors
Y
Y
Y
Y

Domain.MediaFormat
-K
--mediabyte
array types in cfg.vol
1,2,4,101,... (1)
Volume data voxel format
Y
Y
Y
Y

-a
--array
-
bool (0)
Whether the array is in row-major
Y
Y

 Output Settings 
Session.ID
-s
--session
-
a string ('default')
Output file stub
Y
Y
Y
Y

Session.OutputType
-O
--outputtype
cfg.outputtype
XFEJPM (X)
Output data type
Y
Y
Y
Y
Y
Y
Y
Y
Session.DoPartialPath
-d
--savedet
2nd output of mcxlab
bool (1)
Whether to save detected photons
Y
Y
Y
Y
Y
Y
Y
Y
Session.SaveDataMask
-w
--savedetflag
cfg.savedetflag
DSPMXVW (DP)
What fields to save per detected photon
Y
Y
Y
Y

Session.DoSaveExit
-x
--saveexit
cfg.issaveexit
bool (0)
Whether to save exit positions and dir
Y
Y
Y
Y
Y
Y
Y
Y
-X
--saveref
cfg.issaveref
bool (0)
Whether to save diffuse reflectance
Y
Y
Y
Y
Y
Y
Y
Y
Session.DoDCS
-m
--momentum
cfg.ismomentum
bool (0)
Whether to save momentum transfer
Y
Y
Y
Y
Y
Y
Y
Y
Session.DoSaveSeed
-q
--saveseed
cfg.issaveseed
bool (0)
Whether to save RNG seeds for replay
Y
Y
Y
Y
Y
Y
Y
Y
-M
--dumpmask
3rd output of mcxlab
bool (0)
Return the preprocessed volume
Y
Y
Y
Y

-H
--maxdetphoton
cfg.maxdetphoton
integer (1000000)
Maximum count of detected photons
Y
Y
Y
Y
Y
Y
Y
Y
Session.DoSaveVolume
-S
--save2pt
1st output of mcxlab
bool (1)
Whether to save fluence
Y
Y
Y
Y
Y
Y
Y
Y
Session.OutputFormat
-F
--outputformat
-
mc2,nii,hdr (mc2)
Output file format
Y
Y
Y
Y

 User IO
-h
--help
help mcxlab
Print help info
Y
Y
Y
Y
Y
Y
Y
Y
-v
--version
-
Print version info
Y
Y

-l
--log
-
bool (0)
Print info to a file
Y
Y
Y
Y

-i
--interactive
-
Interactive mode
Y
Y
Y
Y

 Advanced Settings 
Session.Debug
-D
--debug
cfg.debuglevel
RMP ('')
Debug flags
Y
Y
Y
Y
Y
Y
Y
Y
-k
--kernel
-
string ('')
Path to a user-specified kernel file
Y

-o
--optlevel
cfg.optlevel
0,1,2,3 (3)
OpenCL optimization level
Y
Y

-J
--compileropt
-
string ('')
OpenCL JIT compiler flags
Y
Y

Session.RootPath
--root
cfg.root
string ('')
Root path of the output files
Y
Y
Y
Y

--gscatter
cfg.gscatter
integer (1e9)
Number of scatter events before isotropic scattering
Y
Y
Y
Y
Y
Y
Y
Y
--maxvoidstep
cfg.maxvoidstep
integer (1000)
Maximum steps in the background
Y
Y
Y
Y

--maxjumpdebug
cfg.maxjumpdebug
integer (10000000)
Maximum trajectory points
Y
Y
Y
Y

--internalsrc
cfg.internalsrc
bool (0)
A point source inside a non-zero voxel
Y
Y

Help
Click on the items below to show help info

MCXLAB
MCXLAB is the native MEX version of MCX for MATLAB and GNU Octave. It compiles
the entire MCX code into a MEX function which can be called directly inside
MATLAB or Octave. The input and output files in MCX are replaced by convenient
in-memory struct variables in MCXLAB, thus making it much easier to use 
and interact with. MATLAB/Octave also provides convenient plotting and data
analysis functions. With MCXLAB, your analysis can be streamlined and sped
up without involving disk files.

Because MCXLAB contains the exact computational codes for the GPU calculations
as in the MCX binaries, MCXLAB is expected to have identical performance when
running simulations. By default, we compile MCXLAB with the support of recording
detected photon partial path lengths (i.e., the "make det" option). In addition,
we also provide "mcxlab_atom": an atomic version of mcxlab compiled similarly
to "make detbox" for MCX. It supports atomic operations using shared memory
enabled by setting the "cfg.sradius" input parameter to a positive number.

MCXStudio
MCXStudio is a cross-platform, easy-to-use GUI to use with MCX, MMC, and MCXCL. Click on the items below to show help info

Installation
MCX supports nearly all GPUs produced by NVIDIA after 2010. The pre-compiled binaries provided in 
our released packages support "Fermi" (circa 2010) and newer GPUs made by NVIDIA, even including future generations.

Please use the following steps to determine if all needed libraries are properly
installed on your computer.

MCXLAB: installation
MCXLAB is a toolbox for MATLAB and GNU Octave to enable streamlined MCX simulations in these platforms.

The core functionalities of the MCXLAB toolbox are provided by a MATLAB function mcxlab.m and 
the mcx.mex* mex file. The mcxlab.m script provides pre-/post-processing of MCX data, and the mcx.mex
file executes the actual GPU-based simulations.

The system requirements for MCXLAB are the same as MCX: you have to make
sure that you have a CUDA-capable graphics card with a properly configured 
graphics driver (you can run the standard MCX binary first to test if your 
system is capable of running MCXLAB). Of course, you need to have either MATLAB
or Octave installed.

Once you set up the CUDA toolkit and NVIDIA driver, you can then add the 
"mcxlab" directory to your MATLAB/Octave search path using the addpath command.
If you want to add this path permanently, please use the "pathtool" 
command, or edit your startup.m (~/.octaverc for Octave).

If everything works OK, typing "help mcxlab" in MATLAB/Octave will print the
help information. If you see any error, particularly any missing libraries,
please make sure you have downloaded the matching version built for your
platform. 

MCXLAB: first example
Let's take a look at one of the simplest examples provided in the 
mcxlab/examples/demo_mcxlab_basic.m demo script:



cfg.nphoton=1e7;                     % define total simulated photon number
cfg.vol=uint8(ones(60,60,60));       % define the volume - here a homogeneous 60x60x60 mm^3 domain with label 1
cfg.srcpos=[30 30 1];                % source position in voxel units (may be different from mm)
cfg.srcdir=[0 0 1];                  % unitary vector defining the initial incident direction of photons
cfg.prop=[0 0 1 1;0.005 1 0 1.37];   % define optical properties [mua (1/mm),mus (1/mm), g and n] for each tissue type; first one reserved for background/air, i.e. label 0
cfg.tstart=0;                        % start of the simulation time window (in seconds)
cfg.tend=5e-9;                       % end of the simulation time window (in seconds)
cfg.tstep=1e-10;                     % time gate width (in seconds), here we ask mcxlab to create a "video" at 50 time gates

cfg.gpuid=1; % cfg.gpuid='11';       % =1 use the first GPU, =2, use the 2nd, ='11' use both GPUs together
cfg.autopilot=1;                     % let mcxlab automatically decide the threads/blocks

fluencerate=mcxlab(cfg);             % calculate the normalized time-resolved fluence rate at all voxel locations
fluence=sum(fluencerate,4)*cfg.tstep;% calculate the CW fluence by integrating the time axis and multiplying time gate width



In the above example, you can see that only a few lines are needed to define a fully 
functional mcxlab simulation. Except for "cfg.gpuid" and "cfg.autopilot", all the 
defined subfields in the cfg parameter are the minimally required parameters.

MCXLAB: GPU speed contest
At the web page below:

  http://mcx.space/gpubench
  
we maintain a GPU benchmark database characterizing the MCX/MCXLAB simulation speed at a wide range
of GPU architectures and graphics cards. The speed data in this database were submitted by our 
developers or contributed by our users, like you. To participate, please download MCXLAB and 
run the mcx_gpu_contest.m script (under examples) inside MATLAB, or run the 
speedcontest/mcxcontest script (Windows requires either Cygwin or MSYS2).

We used 3 built-in benchmarks (list using 'mcx --bench'), 'cube60', 'cubesph60b' and 'cube60planar'
to characterize the overall speed for a range of domain settings and simulation types supported by
MCX. The score of this GPU contest script is basically the summation of the speeds in photons/ms 
for the 3 benchmarks. The higher the score, the better the overall performance of MCX on the tested
GPU.

MCXLAB: test built-in examples
In the mcxlab/example folder, we have provided over a dozen built-in example scripts. In these 
example scripts, we show users how to use mcxlab to create and execute simulations and display the results. Reading
these examples and understanding the purposes for each setting is greatly helpful when you customize them with
your own simulations.

demo_mcxlab_basic.m

In this example, we show the most basic usage of MCXLAB. This includes
how to define the input configuration structure, launch MCX simulations,
and interpret and plot the resulting data.

demo_validation_homogeneous.m

In this example, we validate MCXLAB with a homogeneous medium in a 
cubic domain. This is exactly the example shown in Fig. 5 of [Fang2009].

You can also use alternative optical properties that have a high g
value to observe the similarity between the two scattering/g configurations.

demo_validation_heterogeneous.m

In this example, we validate the MCXLAB solver with a heterogeneous
domain and the analytical solution of the diffusion model. We also 
demonstrate how to use sub-pixel resolution to refine the representation
of heterogeneities. The domain consists of a 6x6x6 cm box with a 
2cm diameter sphere embedded at the center. 

This test is identical to that used for Fig. 3 in [Fang2010].

demo_fullhead_atlas.m
In this example, we demonstrate light transport simulation in a full-head 
atlas template (USC 19.5 year group [Sanchez2012]). 
This demo is identical to the MCX simulation used for Fig. 9(a) in
[TranYan2020].

demo_mcxyz_skinvessel.m
In this example, we compare MCX with mcxyz written by Dr. Steven Jacques.
The same benchmark can be found at https://omlc.org/software/mc/mcxyz/index.html

demo_digimouse_sfdi.m
This simulates a wide-field SFDI source using the Digimouse atlas. There are
21 tissue types in the atlas.

demo_4layer_head.m

In this example, we simulate a 4-layer brain model using MCXLAB.
We will investigate the differences between the solutions with and 
without boundary reflections (both external and internal) and show
you how to display and analyze the resulting data.

demo_mcxlab_srctype.m
This demo script shows how to use 9 different types of sources in your
simulations. These 9 source types include pencil beam, isotropic source,
Gaussian beam, uniform planar source, uniform disk source, Fourier 
pattern illumination (spatial frequency domain sources), arcsine 
distribution beam, uniform cone beam, and an arbitrary light pattern 
(defined by a 2D image).

demo_mcxlab_2d.m
In this example, we show how to use MCX to run a 2D simulation.
You must define a 3D array with one singleton dimension (with length 1).
Unfortunately, if you define z as singleton, MATLAB will make the array 2D
instead of 3D, so we have to permute it to make the 1st dimension
singleton.

demo_photon_sharing.m
This script demonstrates the "photon sharing" feature (Yao & Yan et al., 2019, 
Photonics West) to simultaneously create forward solutions for multiple
patterned sources.

demo_replay_timedomain.m
In this example, we show how to use replay to obtain time-resolved
Jacobians - setting cfg.replaydet to -1 to replay all detectors.

demo_replay_vs_pmc_timedomain.m
In this example, we compare perturbation MC and replay in predicting
time-resolved measurement changes with respect to mua change in a layer.

demo_sphere_cube_subpixel.m

In this example, we demonstrate how to use sub-pixel resolution 
to represent the problem domain. The domain consists of a 
6x6x6 cm box with a 2cm diameter sphere embedded at the center.

MCXLAB: verify MCXLAB installation
To verify if MCXLAB has been installed and is compatible with your system, please first run: 

    which mcx


inside MATLAB or GNU Octave. If the above command prints a path to the mcx.mex* file that you have installed,
that means MCXLAB is now installed on your MATLAB or Octave.

Next, you need to verify if your GPU hardware is properly configured for MCX. You should run:

    info=mcxlab('gpuinfo')


If your system has an NVIDIA GPU and is properly configured, you should get non-empty output.
Otherwise, please verify that your GPU driver was properly installed, and reinstall if needed.

MCXLAB: help info
MCXLAB accepts the input parameters below (type help mcxlab to display)

 ====================================================================
 
      MCXLAB - Monte Carlo eXtreme (MCX) for MATLAB/GNU Octave 
 --------------------------------------------------------------------
       Copyright (c) 2011-2019 Qianqian Fang (q.fang at neu.edu)
                       URL: http://mcx.space
 ====================================================================
 
  
Format:
     fluence=mcxlab(cfg);
        or
     [fluence,detphoton,vol,seed,trajectory]=mcxlab(cfg);
     [fluence,detphoton,vol,seed,trajectory]=mcxlab(cfg, option);
 
  
Input:
     cfg: a struct, or struct array. Each element of cfg defines 
          the parameters associated with a simulation. 
          if cfg='gpuinfo': return the supported GPUs and their parameters,
          see sample script at the bottom
     option: (optional), option is a string, specifying additional options
          option='preview': this plots the domain configuration using mcxpreview(cfg)
          option='opencl':  force using mcxcl.mex* instead of mcx.mex* on NVIDIA/AMD/Intel hardware
          option='cuda':    force using mcx.mex* instead of mcxcl.mex* on NVIDIA GPUs
 
     if one defines USE_MCXCL=1 in MATLAB command line window, all following
     mcxlab and mcxlabcl calls will use mcxcl.mex; by setting option='cuda', one can
     force both mcxlab and mcxlabcl to use mcx (CUDA version). Similarly, if
     USE_MCXCL=0, all mcxlabcl and mcxlab calls will use mcx.mex by default, unless
     one sets option='opencl'.
 
     cfg may contain the following fields:
 
 
== Required ==
      *cfg.nphoton:    the total number of photons to be simulated (integer)
                       maximum supported value is 2^63-1
      *cfg.vol:        a 3D array specifying the media index in the domain.
                       can be uint8, uint16, uint32, single or double
                       arrays.
                       2D simulations are supported if cfg.vol has a singleton
                       dimension (in x or y); srcpos/srcdir must belong to
                       the 2D plane in such cases.
                       for 2D simulations, Example: demo_mcxlab_2d.m
 
                       mcxlab also accepts 4D arrays to define continuously varying media. 
                       The following formats are accepted:
                         1 x Nx x Ny x Nz float32 array: mua values for each voxel (must use permute to make 1st dimension singleton)
                         2 x Nx x Ny x Nz float32 array: mua/mus values for each voxel (g/n use prop(2,:))
                         4 x Nx x Ny x Nz uint8 array: mua/mus/g/n gray-scale (0-255) interpolating between prop(2,:) and prop(3,:)
                         2 x Nx x Ny x Nz uint16 array: mua/mus gray-scale (0-65535) interpolating between prop(2,:) and prop(3,:)
                         Example: demo_continuous_mua_mus.m. If voxel-based media are used, partial-path/momentum outputs are disabled
      *cfg.prop:       an N by 4 array, each row specifies [mua, mus, g, n] in order.
                       the first row corresponds to medium type 0
                       (background) which is typically [0 0 1 1]. The
                       second row is type 1, and so on. The background
                       medium (type 0) has special meanings: a photon
                       terminates when moving from a non-zero to zero voxel.
      *cfg.tstart:     starting time of the simulation (in seconds)
      *cfg.tstep:      time-gate width of the simulation (in seconds)
      *cfg.tend:       ending time of the simulation (in seconds)
      *cfg.srcpos:     a 1 by 3 vector, the position of the source in grid units
      *cfg.srcdir:     a 1 by 3 vector, specifying the incident vector; if srcdir
                       contains a 4th element, it specifies the focal length of
                       the source (only valid for focusable src, such as planar, disk,
                       fourier, gaussian, pattern, slit, etc); if the focal length
                       is nan, all photons will be launched isotropically regardless
                       of the srcdir direction.
 
 
== MC simulation settings ==
       cfg.seed:       seed for the random number generator (integer) [0]
                       if set to a uint8 array, the binary data in each column is used 
                       to seed a photon (i.e., the "replay" mode)
                       Example: demo_mcxlab_replay.m
       cfg.respin:     repeat simulation for the given time (integer) [1]
                       if negative, divide the total photon number into respin subsets
       cfg.isreflect:  [1]-consider refractive index mismatch, 0-matched index
       cfg.bc          per-face boundary condition (BC), a string of 6 letters (case insensitive) for
                       bounding box faces at -x,-y,-z,+x,+y,+z axes;
 		               overwrite cfg.isreflect if given.
                       each letter can be one of the following:
                       '_': undefined, fall back to cfg.isreflect
                       'r': like cfg.isreflect=1, Fresnel reflection BC
                       'a': like cfg.isreflect=0, total absorption BC
                       'm': mirror or total reflection BC
                       'c': cyclic BC, enter from opposite face
       cfg.isnormalized:[1]-normalize the output fluence to unitary source, 0-no normalization
       cfg.isspecular: 1-calculate specular reflection if source is outside, [0] no specular reflection
       cfg.maxgate:    the number of time-gates per simulation
       cfg.minenergy:  terminate photon when weight is less than this level (float) [0.0]
       cfg.unitinmm:   defines the length unit for a grid edge length [1.0]
                       Example: demo_sphere_cube_subpixel.m
       cfg.shapes:     a JSON string for additional shapes in the grid
                       Example: demo_mcxyz_skinvessel.m
       cfg.gscatter:   after a photon completes the specified number of
                       scattering events, MCX then ignores anisotropy g
                       and only performs isotropic scattering for speed [1e9]
 
 
== GPU settings ==
       cfg.autopilot:  1-automatically set threads and blocks, [0]-use nthread/nblocksize
       cfg.nblocksize: how many CUDA thread blocks to be used [64]
       cfg.nthread:    the total CUDA thread number [2048]
       cfg.gpuid:      which GPU to use (run 'mcx -L' to list all GPUs) [1]
                       if set to an integer, gpuid specifies the index (starts at 1)
                       of the GPU for the simulation; if set to a binary string made
                       of 1s and 0s, it enables multiple GPUs. For example, '1101'
                       allows using the 1st, 2nd and 4th GPUs together.
                       Example: mcx_gpu_benchmarks.m
       cfg.workload    an array denoting the relative loads of each selected GPU. 
                       for example, [50,20,30] allocates 50%, 20% and 30% photons to the
                       3 selected GPUs, respectively; [10,10] evenly divides the load 
                       between 2 active GPUs. A simple load balancing strategy is to 
                       use the GPU core counts as the weight.
       cfg.isgpuinfo:  1-print GPU info, [0]-do not print
 
 
== Source-detector parameters ==
       cfg.detpos:     an N by 4 array, each row specifying a detector: [x,y,z,radius]
       cfg.maxdetphoton:   maximum number of photons saved by the detectors [1000000]
       cfg.srctype:    source type, the parameters of the src are specified by cfg.srcparam{1,2}
                               Example: demo_mcxlab_srctype.m
                       'pencil' - default, pencil beam, no param needed
                       'isotropic' - isotropic source, no param needed
                       'cone' - uniform cone beam, srcparam1(1) is the half-angle in radians
                       'gaussian' [*] - a collimated gaussian beam, srcparam1(1) specifies the waist radius (in voxels)
                       'planar' [*] - a 3D quadrilateral uniform planar source, with three corners specified 
                                 by srcpos, srcpos+srcparam1(1:3) and srcpos+srcparam2(1:3)
                       'pattern' [*] - a 3D quadrilateral pattern illumination, same as above, except
                                 srcparam1(4) and srcparam2(4) specify the pattern array x/y dimensions,
                                 and srcpattern is a floating-point pattern array, with values between [0-1]. 
                                 if cfg.srcnum>1, srcpattern must be a floating-point array with 
                                 a dimension of [srcnum srcparam1(4) srcparam2(4)]
                                 Example: demo_photon_sharing.m
                       'pattern3d' [*] - a 3D illumination pattern. srcparam1{x,y,z} defines the dimensions,
                                 and srcpattern is a floating-point pattern array, with values between [0-1]. 
                       'fourier' [*] - spatial frequency domain source, similar to 'planar', except
                                 the integer parts of srcparam1(4) and srcparam2(4) represent
                                 the x/y frequencies; the fractional part of srcparam1(4) multiplied by
                                 2*pi represents the phase shift (phi0); 1.0 minus the fractional part of
                                 srcparam2(4) is the modulation depth (M). Put in equations:
                                     S=0.5*[1+M*cos(2*pi*(fx*x+fy*y)+phi0)], (0<=x,y,M<=1)
                       'arcsine' - similar to isotropic, except the zenith angle follows a uniform
                                 distribution, rather than a sine distribution.
                       'disk' [*] - a uniform disk source pointing along srcdir; the radius is 
                                set by srcparam1(1) (in grid units)
                       'fourierx' [*] - a general Fourier source, the parameters are 
                                srcparam1: [v1x,v1y,v1z,|v2|], srcparam2: [kx,ky,phi0,M]
                                normalized vectors satisfy: srcdir cross v1=v2
                                the phase shift is phi0*2*pi
                       'fourierx2d' [*] - a general 2D Fourier basis, parameters
                                srcparam1: [v1x,v1y,v1z,|v2|], srcparam2: [kx,ky,phix,phiy]
                                the phase shift is phi{x,y}*2*pi
                       'zgaussian' - an angular gaussian beam, srcparam1(0) specifies the variance in the zenith angle
                       'line' - a line source, emitting from the line segment between 
                                cfg.srcpos and cfg.srcpos+cfg.srcparam(1:3), radiating 
                                uniformly in the perpendicular direction
                       'slit' [*] - a collimated slit beam emitting from the line segment between 
                                cfg.srcpos and cfg.srcpos+cfg.srcparam(1:3), with the initial  
                                dir specified by cfg.srcdir
                       'pencilarray' - a rectangular array of pencil beams. The srcparam1 and srcparam2
                                are defined similarly to 'fourier', except that srcparam1(4) and srcparam2(4)
                                are both integers, denoting the element counts in the x/y dimensions, respectively. 
                                For example, srcparam1=[10 0 0 4] and srcparam2=[0 20 0 5] represent a 4x5 pencil beam array
                                spanning 10 grids in the x-axis and 20 grids in the y-axis (5-voxel spacing)
                       source types marked with [*] can be focused using the
                       focal length parameter (4th element of cfg.srcdir)
       cfg.{srcparam1,srcparam2}: 1x4 vectors, see cfg.srctype for details
       cfg.srcpattern: see cfg.srctype for details
       cfg.srcnum:     the number of source patterns that are
                       simultaneously simulated; only works for 'pattern'
                       source, see cfg.srctype='pattern' for details
                       Example demo_photon_sharing.m
       cfg.issrcfrom0: 1-first voxel is [0 0 0], [0]- first voxel is [1 1 1]
       cfg.replaydet:  only works when cfg.outputtype is 'jacobian', 'wl', 'nscat', or 'wp' and cfg.seed is an array
                       -1 replay all detectors and save in separate volumes (output has 5 dimensions)
                        0 replay all detectors and sum all Jacobians into one volume
                        a positive number: the index of the detector to replay and obtain Jacobians
       cfg.voidtime:   for wide-field sources, [1]-start timer at launch, or 0-when entering 
                       the first non-zero voxel
 
 
== Output control ==
       cfg.savedetflag: ['dp'] - a string (case insensitive) controlling the output detected photon data fields
                           1 d  output detector ID (1)
                           2 s  output partial scat. event 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 (d) and partial-path data (p)
       cfg.issaveexit: [0]-save the position (x,y,z) and (vx,vy,vz) for a detected photon
                       same as adding 'xv' to cfg.savedetflag. Example: demo_lambertian_exit_angle.m
       cfg.ismomentum: 1 to save photon momentum transfer, [0] not to save.
                       same as adding 'M' to cfg.savedetflag string
       cfg.issaveref:  [0]-save diffuse reflectance/transmittance in the non-zero voxels
                       next to a boundary voxel. The reflectance data are stored as 
                       negative values; must pad zeros next to boundaries
                       Example: see the demo script at the bottom
       cfg.outputtype: 'flux' - fluence rate, (default value)
                       'fluence' - fluence integrated over each time gate, 
                       'energy' - energy deposit per voxel
                       'jacobian' or 'wl' - mua Jacobian (replay mode), 
                       'nscat' or 'wp' - weighted scattering counts for computing Jacobian for mus (replay mode)
                       for type jacobian/wl/wp, example: demo_mcxlab_replay.m
                       and  demo_replay_timedomain.m
       cfg.session:    a string for output file names (only used when no return variables)
 
 
== Debug ==
       cfg.debuglevel:  debug flag string (case insensitive), one or a combination of ['R','M','P'], no space
                     'R':  debug RNG, output fluence.data is filled with 0-1 random numbers
                     'M':  return photon trajectory data as the 5th output
                     'P':  show progress bar
       cfg.maxjumpdebug: [10000000|int] when trajectory is requested in the output, 
                      use this parameter to set the maximum position stored. By default,
                      only the first 1e7 positions are stored.
 
       fields with * are required; options in [] are the default values
 
  
Output:
       fluence: a struct array, with a length equal to that of cfg.
             For each element of fluence, fluence(i).data is a 4D array with
             dimensions specified by [size(vol) total-time-gates]. 
             The content of the array is the normalized fluence at 
             each voxel of each time-gate.
       detphoton: (optional) a struct array, with a length equal to that of cfg.
             Starting from v2018, the detphoton contains the subfields below:
               detphoton.detid: the ID(>0) of the detector that captures the photon
               detphoton.nscat: cumulative scattering event counts in each medium
               detphoton.ppath: cumulative path lengths in each medium (partial path length)
                    one needs to multiply cfg.unitinmm with ppath to convert it to mm.
               detphoton.mom: cumulative cos_theta for momentum transfer in each medium  
               detphoton.p or .v: exit position and direction, when cfg.issaveexit=1
               detphoton.w0: photon initial weight at launch time
               detphoton.prop: optical properties, a copy of cfg.prop
               detphoton.data: a concatenated and transposed array in the order of
                     [detid nscat ppath mom p v w0]'
               "data" is the only subfield in all mcxlab releases before 2018
       vol: (optional) a struct array, each element is a preprocessed volume
             corresponding to each instance of cfg. Each volume is a 3D int32 array.
       seeds: (optional), if given, mcxlab returns the seeds, in the form of
             a byte array (uint8) for each detected photon. The column number
             of seed equals that of detphoton.
       trajectory: (optional), if given, mcxlab returns the trajectory data for
             each simulated photon. The output has 6 rows, the meanings are: 
                id:  1:    index of the photon packet
                pos: 2-4:  x/y/z of each trajectory position
                     5:    current photon packet weight
                     6:    reserved
             By default, mcxlab only records the first 1e7 positions along all
             simulated photons; change cfg.maxjumpdebug to define a different limit.
 
 
  
Example:
       % first query if you have supported GPU(s)
       info=mcxlab('gpuinfo')
 
       % define the simulation using a struct
       cfg.nphoton=1e7;
       cfg.vol=uint8(ones(60,60,60));
       cfg.vol(20:40,20:40,10:30)=2;    % add an inclusion
       cfg.prop=[0 0 1 1;0.005 1 0 1.37; 0.2 10 0.9 1.37]; % [mua,mus,g,n]
       cfg.issrcfrom0=1;
       cfg.srcpos=[30 30 1];
       cfg.srcdir=[0 0 1];
       cfg.detpos=[30 20 1 1;30 40 1 1;20 30 1 1;40 30 1 1];
       cfg.vol(:,:,1)=0;   % pad a layer of 0s to get diffuse reflectance
       cfg.issaveref=1;
       cfg.gpuid=1;
       cfg.autopilot=1;
       cfg.tstart=0;
       cfg.tend=5e-9;
       cfg.tstep=5e-10;
       % calculate the fluence distribution with the given config
       [fluence,detpt,vol,seeds,traj]=mcxlab(cfg);
 
       % integrate time-axis (4th dimension) to get CW solutions
       cwfluence=sum(fluence.data,4);  % fluence rate
       cwdref=sum(fluence.dref,4);     % diffuse reflectance
       % plot configuration and results
       subplot(231);
       mcxpreview(cfg);title('domain preview');
       subplot(232);
       imagesc(squeeze(log(cwfluence(:,30,:))));title('fluence at y=30');
       subplot(233);
       hist(detpt.ppath(:,1),50); title('partial path tissue #1');
       subplot(234);
       plot(squeeze(fluence.data(30,30,30,:)),'-o');title('TPSF at [30,30,30]');
       subplot(235);
       newtraj=mcxplotphotons(traj);title('photon trajectories')
       subplot(236);
       imagesc(squeeze(log(cwdref(:,:,1))));title('diffuse refle. at z=1');
 
  This function is part of Monte Carlo eXtreme (MCX) URL: http://mcx.space
 
  License: GNU General Public License version 3, please read LICENSE.txt for details

Installation: GPU Hardware
Your computer must have a CUDA-enabled GPU.

Generally speaking, all graphics cards made by NVIDIA after 2010 are CUDA-enabled.
However, if you use an integrated GPU (Intel) or AMD GPU, you may not be able to run MCX
(you should consider MCXCL).

The more cores (stream processors) in your GPU generally means better simulation
speed. On the other hand, MCX does not require large GPU memory. Therefore,
an NVIDIA Tesla card is not entirely needed unless you need to simulate a very
large domain with many time gates.

If you are not sure what type of graphics card is on your operating system, please
use the following instructions:

* Windows: download and run GPU-Z, a freeware.
* Mac OSX: open a terminal, run command "system_profiler"
* Linux: open a terminal, run command "lspci | grep -i --color 'vga\|3d\|2d'"

You should see at least one NVIDIA graphics card that is available. In addition,
you should also have installed the proper driver for the graphics card. Please
consult your graphics card installation guide for details.

Installation: GPU driver
You must install the proper GPU driver in order for MCX to access your
GPU hardware. If you have already been using your NVIDIA GPU for computer display and graphics
rendering, this has typically been completed as part of your computer installation.

To download the latest driver, please use the URL below:

https://www.nvidia.com/Download/index.aspx

If you experience trouble using the graphics on your computer, this typically indicates a graphics
driver problem, and you must fix the graphics driver problem before using MCX.

Starting from MCX 2017.3, the additional installation of CUDA libraries is no longer needed. 
CUDA libraries are now directly built into the MCX/MCXLAB binaries.

For Windows users, starting from version 1.0-beta, we have included the needed
library files (.dll on Windows) in our binary packages. However, if you run MCX
and receive an error message complaining about "cuda*.dll is missing", please search
for this filename in a search engine and find a download link. Once you download the
DLL file, you should save it under your Windows folder (typically C:\Windows).

Installation: Initial test
Once you have verified your GPU hardware and proper installation of GPU drivers,
you may test MCX by running the following command:

    mcx -L

Type this in a terminal (In Windows, Start menu\Run\cmd). You should see a list
of supported graphics card(s). If you see an error, that means either your hardware
does not support MCX, or the CUDA library is missing.

You may also run the NVIDIA tool "nvidia-smi" on your computer to make sure you
can see CUDA-capable GPUs listed. If not, it is likely your NVIDIA driver or
GPU hardware was not properly installed.

Run: show MCX help
Running "mcx" without parameters prints the help information, including
all supported command line options. This is also the first command to test after
installing MCX. If you see an error, such as missing libraries, this typically
indicates a problem with your NVIDIA driver or CUDA toolkit.

Run: list GPU
Running "mcx -L" lists all supported GPUs on your computer. A sample output
looks like the following:
fangq@wazu:mcx/bin$ ./mcx -L
=============================   GPU Information  ================================
Device 1 of 4:		GeForce GTX 980 Ti
Compute Capability:	5.2
Global Memory:		2147287040 B
Constant Memory:	65536 B
Shared Memory:		49152 B
Registers:		65536
Clock Speed:		1.19 GHz
Number of MPs:		22
Number of Cores:	2816
SMX count:		22
=============================   GPU Information  ================================
Device 2 of 4:		GeForce GTX 590
Compute Capability:	2.0
Global Memory:		1610285056 B
Constant Memory:	65536 B
Shared Memory:		49152 B
Registers:		32768
Clock Speed:		1.26 GHz
Number of MPs:		16
Number of Cores:	512
SMX count:		16
=============================   GPU Information  ================================
Device 3 of 4:		GeForce GTX 590
Compute Capability:	2.0
Global Memory:		1609760768 B
Constant Memory:	65536 B
Shared Memory:		49152 B
Registers:		32768
Clock Speed:		1.26 GHz
Number of MPs:		16
Number of Cores:	512
SMX count:		16
=============================   GPU Information  ================================
Device 4 of 4:		GeForce GT 730
Compute Capability:	3.5
Global Memory:		1073545216 B
Constant Memory:	65536 B
Shared Memory:		49152 B
Registers:		65536
Clock Speed:		0.90 GHz
Number of MPs:		2
Number of Cores:	384
SMX count:		2

Run: autopilot mode
The command "mcx -A -n 1e6 -f input.json" asks MCX to simulate 10^6 photons (-n)
using the settings specified (-f) in the input file "input.json"; it also asks
MCX to automatically configure (-A) the thread and block sizes to maximize
speed. If the simulation successfully completes, an output named "input.json.mc2"
will be created in the current folder.

In the autopilot mode, MCX uses a built-in heuristic algorithm to determine the
thread and block sizes. The goal is to launch as many threads as possible to keep
all GPU hardware busy, thus achieving maximized efficiency.

Run: session name and voxel size
The command "mcx -A -n 1e6 -f input.json -s test -u 0.5" adds two additional
options to the previous command:

-s test: instead of writing the output file as input.json.mc2, the output files
         will be named as test.mc2

-u 0.5:  by default, MCX assumes isotropic 1 x 1 x 1 mm^3 voxels in the volume;
         if your volume has a voxel dimension larger or smaller than 1mm, you
         may specify it with the -u flag. Here we specify that all voxels are
         0.5 x 0.5 x 0.5 mm^3 in size

Run: manual thread configuration
Instead of using the autopilot mode (-A), in this command,
"mcx -t 10240 -T 32 -n 1e6 -f input.json", we explicitly specify the thread
and block sizes using the -t and -T flags, respectively. 

Preparation
Click on the items below to show help info

Output

Overall, MCX/MCXLAB produces 3 types of output data: 

1. volumetric data
2. detected photon data, and
3. photon trajectories

The first type of output is typically stored as a 3D, 4D or 5D single-precision floating-point
array. By default, this volumetric output is the normalized fluence rate (W/mm^2 or J/(s*mm^2))
as a 4D array, with the first 3 dimensions as x/y/z and the last dimension as the time-gate. However,
by using the '--outputtype' flag or cfg.outputtype, one can also ask MCX to output fluence,
energy density, or the Jacobian of mua (in the replay mode). These outputs are also in the form of a 
3D or 4D array. When "photon-sharing" is used, the output data corresponding to all simultaneously
simulated source patterns are stored as a 5D array. The default output file format for the volumetric
data is ".mc2" - a simple binary buffer dump of the 3D/4D/5D floating-point buffer in column-major 
order. It is highly recommended to use '-F jnii' or '-F bnii' or '-F nii' to store this output as 
JSON, binary JSON or NIfTI format for greater portability and readability (if saved as .jnii).
These files can be loaded into MATLAB using loadmc2, loadjson or loadbj commands, respectively.
This output can be disabled by setting '--save2pt 0' or cfg.issave2pt=0.

The 2nd type of output is typically stored in the form of a binary 2D array encoded in a '.mch' 
(MC history file). The .mch file contains a simple 256-byte header, followed by an Np x Nc 2D 
floating-point array, where Np is the number of detected photons, and Nc is the number of the 
per-photon data numbers, or columns. The per-photon data includes the index of the 
detector, the partial path lengths, partial scattering counts, etc. One can specify the output
columns by using -w or --savedetflag followed by a series of characters. If -q or --saveseed is 
set, a block of Np x Nb byte array follows the main data table, storing the per-photon RNG 
seeds, where Nb is the number of bytes per RNG seed. The default output
file format is .mch; however, you are also recommended to use -F jnii or -F bnii to save these
into JSON or binary JSON format. If jnii or bnii output is used, the detected photon data are stored
under the "PhotonData" key under the "MCXData" root object, and the photon seeds, if desired, are stored
under the "Seed" key. This output can be disabled by setting --savedet 0 or ignoring
the 2nd output of mcxlab.

The 3rd type of output is also by default stored in a '.mch' formatted file, but renamed as 
.mct for better management. The .mct file has exactly the same format as .mch, containing
a 2D table of Np x 6 floating-point array, where Np is the number of simulated photons, and the fields in 
the columns are: 
  photonid, x, y, z, weight, reserved
When -F jnii or -F bnii is used, this output is merged with the 2nd output file and all
trajectory data are stored under the "Trajectory" key under the "MCXData" root object. This output
can be enabled by "-D M" or by asking mcxlab to return the 5th output.

Run
Click on the sample command below to show help info