bramth / mcx Goto Github PK
View Code? Open in Web Editor NEWThis project forked from fangq/mcx
Monte Carlo eXtreme (MCX) - GPU-accelerated photon transport simulator
Home Page: http://mcx.space
License: Other
This project forked from fangq/mcx
Monte Carlo eXtreme (MCX) - GPU-accelerated photon transport simulator
Home Page: http://mcx.space
License: Other
--------------------------------------------------------------------- Monte Carlo eXtreme (MCX) CUDA Edition --------------------------------------------------------------------- Author: Qianqian Fang <q.fang at neu.edu> License: GNU General Public License version 3 (GPLv3) Version: 1.4.9 (v2019.4, Ether Dome - RC1) Website: http://mcx.space --------------------------------------------------------------------- Table of Content: O. What's New I. Introduction II. Requirement and Installation III. Running Simulations IV. Using JSON-formatted input files V. Using JSON-formatted shape description files VI. Using MCXLAB in MATLAB and Octave VII. Using MCX Studio GUI VIII. Interpreting the Outputs IX. Best practices guide X. Acknowledgement XI. Reference --------------------------------------------------------------------- O. What's New In MCX v2019.4 (1.4.9), several important key features were added * Support continuously varying media - mua/mus can vary in every voxel * Support -w / --savedetflag to specify which det photon data to output * Add json2mcx, converting from json file to mcxlab cfg * Can simulate infinite domain using cylic BC - added MCXLAB example * A new output type - partial-path data on all exiting voxels (experimental) In MCX v2019.3 (1.4.8), we added a list of major new additions, including * Support 4 different boundary conditions (total absorption, total reflection/mirror, Fresnel reflection and cylic), controlled independently (--bc/cfg.bc) at 6 facets of the domain * 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 GPU-ANLM denoiser, mcxfilter.m, to mcxlab to reduce MC fluence noise, detailed in our [Yao2018] paper * Initial support of "photon sharing" - a fast approach to simultaneouly simulate multiple pattern src/det, as detailed in our Photoncs West 2019 talk by Ruoyang Yao/Shijie Yan [Yao&Yan2019] * First release of MCX Viewer - a built in 3D fluence rendering tool in mcxstudio (mcxviewer and mcxshow also provided separately) * Output partial scattering event counts in detected photon data, similar to MMC * Add CMake support, python-based mch file reader (by Shih-Cheng Tu), nightly build compilation script, colored command line output, and more In addition, we also fixed a number of critical bugs, such as * fix mcxlab gpuinfo output crash using multiple GPUs * disable linking to Intel OMP library (libiomp5) to avoid MATLAB 2016-2017 crash * fix mcxlab crash when srcpattern/srcdir/srcpos/detpos are not in double precision * fix shared memory allocation size bug * add the missing photon exit position in the trajectory output * fix mcxlab crash due to racing in multi-threads * force g to 1 in region where mus is 0 [Yuan2018] Yaoshen Yuan, Leiming Yu, Zafer Doğan, Qianqian Fang*, "Graphics processing units-accelerated adaptive nonlocal means filter for denoising three-dimensional Monte Carlo photon transport simulations," J. of Biomedical Optics, 23(12), 121618 (2018), URL: https://doi.org/10.1117/1.JBO.23.12.121618 [Yao&Yan2019] Ruoyang Yao, Shijie Yan, Xavier Intes, Qianqian Fang, "Accelerating Monte Carlo forward model with structured light illumination via 'photon sharing'," Photonics West 2019, paper#10874-11, San Francisco, CA, USA. [https://www.spiedigitallibrary.org/conference-presentations/10874/108740B/Accelerating-Monte-Carlo-forward-model-with-structured-light-illumination-via/10.1117/12.2510291?SSO=1 Full presentation for our invited talk] --------------------------------------------------------------------- I. 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. The algorithm of this software is detailed in the References [Fang2009,Yu2018]. 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 This software can be used on Windows, Linux and Mac OS. MCX is written in CUDA and can be used with NVIDIA hardware with the native NVIDIA drivers, or used with the open-source GPU Ocelot libraries for CPUs and AMD GPUs. An OpenCL implementation of MCX, i.e. MCXCL, was announced on July, 2012. It supports NVIDIA/AMD/Intel hardware out-of-box. If your hardware does not support CUDA, please download MCXCL from the below URL: http://mcx.space/wiki/index.cgi?Learn#mcxcl --------------------------------------------------------------------------- II. Requirement and Installation Please read this section carefully. The majority of failures using MCX were found related to incorrect installation of CUDA library and NVIDIA driver. Please browse http://mcx.space/#documentation for step-by-step instructions. For MCX-CUDA, the requirements for using this software include *. a CUDA capable NVIDIA graphics card *. pre-installed NVIDIA graphics driver You must use a CUDA capable NVIDIA graphics card in order to use MCX. A list of CUDA capable cards can be found at [2]. The oldest graphics card that MCX supports is the Fermi series (circa 2010). Using the latest NVIDIA card is expected to produce the best speed. You must have a fermi (GTX 4xx) or newer (5xx/6xx/7xx/9xx/10xx series) graphics card. The default release of MCX supports atomic operations and photon detection within a single binary. In the below webpage, we summarized the speed differences between different generations of NVIDIA GPUs http://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*Ng bytes for the input tissue data plus Nx*Ny*Nz*Ng*4 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. MCX does not require double-precision support in your hardware. 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 http://mcx.space/wiki/index.cgi?Doc/FAQ#I_am_getting_a_kernel_launch_timed_out_error_what_is_that III.Running Simulations To run a simulation, the minimum input is a configuration (text) file, and a volume file (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: <pre>############################################################################### # Monte Carlo eXtreme (MCX) -- CUDA # # Copyright (c) 2009-2019 Qianqian Fang <q.fang at neu.edu> # # 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::5e0f0c$2019.4 $Date::2019-04-22 18:40:07 -04$ 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 == 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 -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] -R [-2|float] (--skipradius) -2: use atomics for the entire domain (default) 0: vanilla MCX, no atomic operations >0: radius in which use shared-memory atomics -1: use crop0/crop1 to determine atomic zone -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 terminate a photon -g [1|int] (--gategroup) number of 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 == Input options == -P '{...}' (--shapes) a JSON string for additional shapes in the grid -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|XFEJPM] (--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; -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) nii - Nifti format hdr - Analyze 7.5 hdr/img format tx3 - GL texture data for rendering (GL_RGBA32F) == 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 == --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 --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) --faststep [0|1] 1-use fast 1mm stepping, [0]-precise ray-tracing == Example == example: (autopilot mode) mcx -A 1 -n 1e7 -f input.inp -G 1 -D P or (manual mode) mcx -t 16384 -T 64 -n 1e7 -f input.inp -s test -r 2 -g 10 -d 1 -w dpx -b 1 -G 1 or (use multiple devices - 1st,2nd and 4th GPUs - together with equal load) mcx -A -n 1e7 -f input.inp -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]]}]}' </pre> the 2nd command above will launch 16384 GPU threads (-t) with every 64 threads a block (-T); a total of 1e7 photons will be simulated by the first GPU (-G 1) with two equally divided runs (-r); the media/source configuration will be read from input.inp (-f) and the output will be labeled with the session id "test" (-s); the simulation will run 10 concurrent time gates (-g). Photons passing through the defined detector positions will be 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 used by tMCimg. The difference is that MCX allows comments in the input file. A typical MCX input file looks like this: 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, 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) 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. --------------------------------------------------------------------------- IV. 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 http://jsonlint.com/ You should always use "" to quote a "name" and separate parallel items by ",". MCX accepts an alternative form of JSON input, but using it is not recommended. In the alternative format, you can use "rootobj_name.field_name": value to represent any parameter directly in the root level. For example { "Domain.VolumeFile": "semi60x60x60.json", "Session.Photons": 10000000, ... } You can even mix the alternative format with the standard format. If any input parameter has values in both formats in a single input file, the standard-formatted value has higher priority. To invoke the JSON-formatted input file in your simulations, you can use the "-f" command line option with MCX, just like using an .inp file. For example: mcx -A 1 -n 20 -f onecube.json -s onecubejson The input file must have a ".json" suffix in order for MCX to recognize. If the input information is set in both command line, and input file, the command line value has higher priority (this is the same for .inp input files). For example, when using "-n 20", the value set in "Session"/"Photons" is overwritten to 20; when using "-s onecubejson", the "Session"/"ID" value is modified. If your JSON input file is invalid, MCX will quit and point out where the format is incorrect. --------------------------------------------------------------------------- V. Using JSON-formatted shape description files Starting from v0.7.9, MCX can also use a shape description file in the place of the volume file. Using a shape-description file can save you from making a binary .bin volume. A shape file uses more descriptive syntax and can be easily understood and shared with others. Samples on how to use the shape files are included under the example/shapetest folder. The sample shape file, shapes.json, is shown below: { "MCX_Shape_Command_Help":{ "Shapes::Common Rules": "Shapes is an array object. The Tag field sets the voxel value for each region; if Tag is missing, use 0. Tag must be smaller than the maximum media number in the input file.Most parameters are in floating-point (FP). If a parameter is a coordinate, it assumes the origin is defined at the lowest corner of the first voxel, unless user overwrite with an Origin object. The default origin of all shapes is initialized by user's --srcfrom0 setting: if srcfrom0=1, the lowest corner of the 1st voxel is [0,0,0]; otherwise, it is [1,1,1]", "Shapes::Name": "Just for documentation purposes, not parsed in MCX", "Shapes::Origin": "A floating-point (FP) triplet, set coordinate origin for the subsequent objects", "Shapes::Grid": "Recreate the background grid with the given dimension (Size) and fill-value (Tag)", "Shapes::Sphere": "A 3D sphere, centered at C0 with radius R, both have FP values", "Shapes::Box": "A 3D box, with lower corner O and edge length Size, both have FP values", "Shapes::SubGrid": "A sub-section of the grid, integer O- and Size-triplet, inclusive of both ends", "Shapes::XLayers/YLayers/ZLayers": "Layered structures, defined by an array of integer triples: [start,end,tag]. Ends are inclusive in MATLAB array indices. XLayers are perpendicular to x-axis, and so on", "Shapes::XSlabs/YSlabs/ZSlabs": "Slab structures, consisted of a list of FP pairs [start,end] both ends are inclusive in MATLAB array indices, all XSlabs are perpendicular to x-axis, and so on", "Shapes::Cylinder": "A finite cylinder, defined by the two ends, C0 and C1, along the axis and a radius R", "Shapes::UpperSpace": "A semi-space defined by inequality A*x+B*y+C*z>D, Coef is required, but not Equ" }, "Shapes": [ {"Name": "Test"}, {"Origin": [0,0,0]}, {"Grid": {"Tag":1, "Size":[40,60,50]}}, {"Sphere": {"Tag":2, "O":[30,30,30],"R":20}}, {"Box": {"Tag":0, "O":[10,10,10],"Size":[10,10,10]}}, {"Subgrid": {"Tag":1, "O":[13,13,13],"Size":[5,5,5]}}, {"UpperSpace":{"Tag":3,"Coef":[1,-1,0,0],"Equ":"A*x+B*y+C*z>D"}}, {"XSlabs": {"Tag":4, "Bound":[[5,15],[35,40]]}}, {"Cylinder": {"Tag":2, "C0": [0.0,0.0,0.0], "C1": [15.0,8.0,10.0], "R": 4.0}}, {"ZLayers": [[1,10,1],[11,30,2],[31,50,3]]} ] } A shape file must contain a "Shapes" object in the root level. Other root-level fields are ignored. The "Shapes" object is a JSON array, with each element representing a 3D object or setting. The object-class commands include "Grid", "Sphere", "Box" etc. Each of these object include a number of sub-fields to specify the parameters of the object. For example, the "Sphere" object has 3 subfields, "O", "R" and "Tag". Field "O" has a value of 1x3 array, representing the center of the sphere; "R" is a scalar for the radius; "Tag" is the voxel values. The most useful command is "[XYZ]Layers". It contains a series of integer triplets, specifying the starting index, ending index and voxel value of a layered structure. If multiple objects are included, the subsequent objects always overwrite the overlapping regions covered by the previous objects. There are a few ways for you to use shape description records in your MCX simulations. You can save it to a JSON shape file, and put the file name in Line#6 of yoru .inp file, or set as the value for Domain.VolumeFile field in a .json input file. In these cases, a shape file must have a suffix of .json. You can also merge the Shapes section with a .json input file by simply appending the Shapes section to the root-level object. You can find an example, jsonshape_allinone.json, under examples/shapetest. In this case, you no longer need to define the "VolumeFile" field in the input. Another way to use Shapes is to specify it using the -P (or --shapes) command line flag. For example: mcx -f input.json -P '{"Shapes":[{"ZLayers":[[1,10,1],[11,30,2],[31,60,3]]}]}' This will first initialize a volume based on the settings in the input .json file, and then rasterize new objects to the domain and overwrite regions that are overlapping. For both JSON-formatted input and shape files, you can use the JSONlab toolbox [4] to load and process in MATLAB. --------------------------------------------------------------------------- VI. Using MCXLAB in MATLAB and Octave MCXLAB is the native MEX version of MCX for Matlab and GNU Octave. It includes the entire MCX code in 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. Matlab/Octave also provides convenient plotting and data analysis functions. With MCXLAB, your analysis can be streamlined and speed- up without involving disk files. Please read the mcxlab/README.txt file for more details on how to install and use MCXLAB. --------------------------------------------------------------------------- VII. Using MCX Studio GUI MCX Studio is a graphics user interface (GUI) for MCX. It gives users a straightforward way to set the command line options and simulation parameters. It also allows users to create different simulation tasks and organize them into a project and save for later use. MCX Studio can be run on many platforms such as Windows, GNU Linux and Mac OS. To use MCX Studio, it is suggested to put the mcxstudio binary in the same directory as the mcx command; alternatively, you can also add the path to mcx command to your PATH environment variable. Once launched, MCX Studio will automatically check if mcx binary is in the search path, if so, the "GPU" button in the toolbar will be enabled. It is suggested to click on this button once, and see if you can see a list of GPUs and their parameters printed in the output field at the bottom part of the window. If you are able to see this information, your system is ready to run MCX simulations. If you get error messages or not able to see any usable GPU, please check the following: * are you running MCX Studio/MCX on a computer with a supported card? * have you installed the CUDA/NVIDIA drivers correctly? * did you put mcx in the same folder as mcxstudio or add its path to PATH? If your system has been properly configured, you can now add new simulations by clicking the "New" button. MCX Studio will ask you to give a session ID string for this new simulation. Then you are allowed to adjust the parameters based on your needs. Once you finish the adjustment, you should click the "Verify" button to see if there are missing settings. If everything looks fine, the "Run" button will be activated. Click on it once will start your simulation. If you want to abort the current simulation, you can click the "Stop" button. You can create multiple tasks with MCX Studio by hitting the "New" button again. The information for all session configurations can be saved as a project file (with .mcxp extension) by clicking the "Save" button. You can load a previously saved project file back to MCX Studio by clicking the "Load" button. --------------------------------------------------------------------------- VIII. Interpreting the Output MCX output consists of two parts, the flux volume file and messages printed on the screen. 8.1 Output files An mc2 file contains the fluence-rate distribution from the simulation in the given medium. By default, this fluence-rate is a normalized solution (as opposed to the raw probability) therefore, one can compare this directly to the analytical solutions (i.e. Green's function). The order of storage in the mc2 files is the same as the input file: i.e., if the input is row-major, the output is row-major, and so on. The dimensions of the file are Nx, Ny, Nz, and Ng where Ng is the total number of time gates. By default, MCX produces the '''Green's function''' of the '''fluence rate''' for the given domain and source. Sometime it is also known as the time-domain "two-point" function. If you run MCX with the following command mcx -f input.inp -s output .... the fluence-rate data will be saved in a file named "output.dat" under the current folder. If you run MCX without "-s output", the output file will be named as "input.inp.dat". To understand this further, you need to know that a '''fluence-rate (Phi(r,t))''' is measured by number of particles passing through an infinitesimal spherical surface per '''unit time''' at '''a given location''' regardless of directions. The unit of the MCX output is "W/mm<sup>2 = J/(mm<sup>2</sup>s)", if it is interpreted as the "energy fluence-rate" [6], or "1/(mm<sup>2</sup>s)", if the output is interpreted as the "particle fluence-rate" [6]. The Green's function of the fluence-rate means that it is produced by a '''unitary source'''. In simple terms, this represents the fraction of particles/energy that arrives a location per second under '''the radiation of 1 unit (packet or J) of particle or energy at time t=0'''. The Green's function is calculated by a process referred to as the "normalization" in the MCX code and is detailed in the MCX paper [6] (MCX and MMC outputs share the same meanings). Please be aware that the output flux is calculated at each time-window defined in the input file. For example, if you type 0.e+00 5.e-09 1e-10 # time-gates(s): start, end, step in the 5th row in the input file, MCX will produce 50 fluence-rate snapshots, corresponding to the time-windows at [0 0.1] ns, [0.1 0.2]ns ... and [4.9,5.0] ns. To convert the fluence rate to the fluence for each time-window, you just need to multiply each solution by the width of the window, 0.1 ns in this case. To convert the time-dependent fluence-rate to continuous-wave (CW) fluence (fluence in short), you need to integrate the fluence-rate along the time dimension. Assuming the fluence-rate after 5 ns is negligible, then the CW fluence is simply sum(flux_i*0.1 ns, i=1,50). You can read <tt>mcx/examples/validation/plotsimudata.m</tt> and <tt>mcx/examples/sphbox/plotresults.m</tt> for examples to compare an MCX output with the analytical fluence-rate/fluence solutions. One can load an mc2 output file into Matlab or Octave using the loadmc2 function in the <mcx root>/utils folder. To get a continuous-wave solution, run a simulation with a sufficiently long time window, and sum the flux along the time dimension, for example mcx=loadmc2('output.mc2',[60 60 60 10],'float'); cw_mcx=sum(mcx,4); Note that for time-resolved simulations, the corresponding solution in the results approximates the flux at the center point of each time window. For example, if the simulation time window setting is [t0,t0+dt,t0+2dt,t0+3dt...,t1], the time points for the snapshots stored in the solution file is located at [t0+dt/2, t0+3*dt/2, t0+5*dt/2, ... ,t1-dt/2] A more detailed interpretation of the output data can be found at http://mcx.sf.net/cgi-bin/index.cgi?MMC/Doc/FAQ#How_do_I_interpret_MMC_s_output_data MCX can also output "current density" (J(r,t), unit W/m^2, same as Phi(r,t)) - referring to the expected number of photons or Joule of energy flowing through a unit area pointing towards a particular direction per unit time. The current density can be calculated at the boundary of the domain by two means: 1. using the detected photon partial path output (i.e. the second output of mcxlab.m), one can compute the total energy E received by a detector, then one can divide E by the area/aperture of the detector to obtain the J(r) at a detector (E should be calculated as a function of t by using the time-of-fly of detected photons, the E(t)/A gives J(r,t); if you integrate all time gates, the total E/A gives the current I(r), instead of the current density). 2. use -X 1 or --saveref/cfg.issaveref option in mcx to enable the diffuse reflectance recordings on the boundary. the diffuse reflectance is represented by the current density J(r) flowing outward from the domain. The current density has, as mentioned, the same unit as fluence rate, but the difference is that J(r,t) is a vector, and Phi(r,t) is a scalar. Both measuring the energy flow across a small area (the are has direction in the case of J) per unit time. You can find more rigorous definitions of these quantities in Lihong Wang's Biomedical Optics book, Chapter 5. 8.2 Console print messages Timing information is printed on the screen (stdout). The clock starts (at time T0) right before the initialization data is copied from CPU to GPU. For each simulation, the elapsed time from T0 is printed (in ms). Also the accumulated elapsed time is printed for all memory transaction from GPU to CPU. When a user specifies "-D P" in the command line, or set cfg.debuglevel='P', MCX or MCXLAB prints a progress bar showing the percentage of completition. --------------------------------------------------------------------------- IX. Best practices guide To maximize MCX's performance on your hardware, you should follow the best practices guide listed below: === Use dedicated GPUs === A dedicated GPU is a GPU that is not connected to a monitor. If you use a non-dedicated GPU, any kernel (GPU function) can not run more than a few seconds. This greatly limits the efficiency of MCX. To set up a dedicated GPU, it is suggested to install two graphics cards on your computer, one is set up for displays, the other one is used for GPU computation only. If you have a dual-GPU card, you can also connect one GPU to a single monitor, and use the other GPU for computation (selected by -G in mcx). If you have to use a non-dedicated GPU, you can either use the pure command-line mode (for Linux, you need to stop X server), or use the "-r" flag to divide the total simulation into a set of simulations with less photons, so that each simulation only lasts a few seconds. === Launch as many threads as possible === It has been shown that MCX's speed is related to the thread number (-t). Generally, the more threads, the better speed, until all GPU resources are fully occupied. For higher-end GPUs, a thread number over 10,000 is recommended. Please use the autopilot mode, "-A", to let MCX determine the "optimal" thread number when you are not sure what to use. --------------------------------------------------------------------------- X. Acknowledgement === cJSON library by Dave Gamble === Files included: mcx/src/cJSON folder Copyright (c) 2009 Dave Gamble Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. === myslicer toolbox by Anders Brun === Files included: mcx/utils/{islicer.m, slice3i.m, image3i.m} Copyright (c) 2009 Anders Brun, [email protected] Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution * Neither the name of the Centre for Image Analysis nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. === Texture3D Sample Project in the GLScene Project by Jürgen Abel === Copyright (c) 2003 Jürgen Abel The MCX volume renderer (mcxviewer) was adapted based on the Texture3D Example provided by the GLScene Project (http://glscene.org). The original author of this example is Jürgen Abel. The license for GLScene is GLScene is distributed under Mozilla Public Licence (MPL 2.0), which means, in short, that it is free for both freeware and commercial use. The code is still copyrighted (in that it isn't public domain), but you can use it in products with closed or open-source freely. The only requirements are: Acknowledge GLScene is used somewhere in your application (in an about box, credits page or printed manual, etc. with at least a link to http://glscene.org) Modifications made to GLScene units must be made public (no need to publish the full code, only to state which parts were altered, and how), but feel welcome to open-source your code if you so wish. Some Delphi units, API headers and DLLs are included in the GLScene package for convenience but are not part of GLScene, may use different licensing scheme and have different copyright owners, such files have an explicit notice attached to them or placed in their directory. --------------------------------------------------------------------------- XI. Reference [Fang2009] Qianqian Fang and David A. Boas, "Monte Carlo Simulation of Photon \ Migration in 3D Turbid Media Accelerated by Graphics Processing Units," Optics Express, vol. 17, issue 22, pp. 20178-20190 (2009). [Yu2019] Leiming Yu, Fanny Nina-Paravecino, David Kaeli, Qianqian Fang, \ "Scalable and massively parallel Monte Carlo photon transport simulations \ for heterogeneous computing platforms," J. Biomed. Opt. 23(1), 010504 (2018). If you use MCX in your research, the author of this software would like you to cite the above papers in your related publications. Links: [1] http://developer.nvidia.com/cuda-downloads [2] http://www.nvidia.com/object/cuda_gpus.html [3] http://en.wikipedia.org/wiki/Row-major_order [4] http://iso2mesh.sourceforge.net/cgi-bin/index.cgi?jsonlab [5] http://science.jrank.org/pages/60024/particle-fluence.html [6] http://www.opticsinfobase.org/oe/abstract.cfm?uri=oe-17-22-20178
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.