{"id":17744076,"url":"https://github.com/fangq/mcxcl","last_synced_at":"2025-04-04T18:07:55.243Z","repository":{"id":3959423,"uuid":"5053035","full_name":"fangq/mcxcl","owner":"fangq","description":"Monte Carlo eXtreme for OpenCL (MCXCL)","archived":false,"fork":false,"pushed_at":"2025-02-14T03:19:55.000Z","size":6904,"stargazers_count":42,"open_issues_count":0,"forks_count":29,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-02T02:31:27.815Z","etag":null,"topics":["c","c-plus-plus","gpu","heterogeneous-computing","matlab","monte-carlo","opencl","photonics"],"latest_commit_sha":null,"homepage":"http://mcx.space/wiki/?Learn#mcxcl","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fangq.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog.txt","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.txt","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-07-15T02:53:35.000Z","updated_at":"2025-03-13T08:50:18.000Z","dependencies_parsed_at":"2023-07-06T05:57:25.816Z","dependency_job_id":"57b5dc7e-8f12-4b66-b3e3-b82f314bb04f","html_url":"https://github.com/fangq/mcxcl","commit_stats":{"total_commits":607,"total_committers":12,"mean_commits":"50.583333333333336","dds":0.1482701812191104,"last_synced_commit":"0f642c366b35a1d1ca985c45e1255b9c0a9aa137"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fangq%2Fmcxcl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fangq%2Fmcxcl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fangq%2Fmcxcl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fangq%2Fmcxcl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fangq","download_url":"https://codeload.github.com/fangq/mcxcl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247226215,"owners_count":20904465,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c","c-plus-plus","gpu","heterogeneous-computing","matlab","monte-carlo","opencl","photonics"],"created_at":"2024-10-26T06:41:53.863Z","updated_at":"2025-04-04T18:07:55.222Z","avatar_url":"https://github.com/fangq.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Monte Carlo eXtreme (MCX-CL) - OpenCL Edition\n\n- **Author:** Qianqian Fang (q.fang at neu.edu)\n- **License:** GNU General Public License version 3 (GPLv3)\n- **Version:** 1.6 (Harmonic)\n- **Website:** [ https://mcx.space]( https://mcx.space)\n\n![Mex and Binaries](https://github.com/fangq/mcxcl/actions/workflows/build_all.yml/badge.svg)\\\n![Linux Python Module](https://github.com/fangq/mcxcl/actions/workflows/build_linux_manywheel.yml/badge.svg)\\\n![MacOS Python Module](https://github.com/fangq/mcxcl/actions/workflows/build_macos_wheel.yml/badge.svg)\\\n![Windows Python Module](https://github.com/fangq/mcxcl/actions/workflows/build_windows_wheel.yml/badge.svg)\n\n\nTable of Contents:\n-------------\n\n * [What's New](#whats-new)\n * [Introduction](#introduction)\n * [Requirement and Installation](#requirement-and-installation)\n + [Step 1. Verify your CPU/GPU support](#step-1-verify-your-cpugpu-support)\n + [Step 2. Install MATLAB or GNU Octave](#step-2-install-matlab-or-gnu-octave)\n + [Step 3. Installing MCXCL](#step-3-installing-mcxcl)\n + [Step 4. Start MCXStudio and query GPU information](#step-4-start-mcxstudio-and-query-gpu-information)\n + [Step 5. Run a trial simulation](#step-5-run-a-trial-simulation)\n + [Step 6. Test MATLAB for visualization](#step-6-test-matlab-for-visualization)\n + [Step 7. Setting up MATLAB search path](#step-7-setting-up-matlab-search-path)\n * [Running Simulations](#running-simulations)\n * [Using JSON-formatted input files](#using-json-formatted-input-files)\n * [Using JSON-formatted shape description files](#using-json-formatted-shape-description-files)\n * [Output data formats](#output-data-formats)\n + [Volumetric output](#volumetric-output)\n + [Detected photon data](#detected-photon-data)\n + [Photon trajectory data](#photon-trajectory-data)\n * [Using mcxlabcl in MATLAB and Octave](#using-mcxlabcl-in-matlab-and-octave)\n * [Using MCXStudio GUI](#using-mcxstudio-gui)\n * [Interpreting the Output](#interpreting-the-output)\n + [Output files](#output-files)\n + [Guide for output units](#guide-for-output-units)\n + [Console print messages](#console-print-messages)\n * [Best practices guide](#best-practices-guide)\n * [Acknowledgement](#acknowledgement)\n * [Reference](#reference)\n\n\nWhat's New\n-------------\n\nMCX-CL v2025 is a maintenance release with multiple bug fixes and minor new features.\nIt is highly recommended to upgrade for all users.\n\nNotable major bug fixes include\n* a high priority bug fangq/mcx#222, introduced in 198cd34, was fixed. this bug affects all simulations\n since v2023. Particularly, when a photon has a long pathlength, with weight drops to numerical 0,\n its pathlength data is carried in the immediately launched new photon, causing skews in the\n detected photon pathlength distributions\n* multi-GPU simulations was not working (serialized) in v2024.2, this has been fixed\n* further updates to the handling of low absorption medium (fangq/mcx#164), previously affect not-so-low mua values\n* fix incorrect angleinvcdf and invcdf buffer length, ported from fangq/mcx#233\n* fix missing nscat output due to incorrect macro, fix #56\n* add missing --maxjumpdebug flag, accept float, fix #54\n* avoid double-base64-encoding when -Z 2 is used, fangq/mcx#219\n* for all brain related simulations, we have updated the CSF mua value of 0.004/mm that was\n previously used in Custo et al. 2006 paper to 0.0004/mm, matching its upstream reference Strangman et al. 2003.\n However, we want to highlight that both literature may not provide the best mua value for CSF - as such low\n mua/mus CSF properties are mostly for CSF in the inner part of the brain, but not representiative to those in\n the subarachnoid space. A few literature have shown that CSF in the subarachnoid space may have a higher\n mus' value, in the range between 0.16/mm to 0.32/mm, as shown in Okada et al. 2003\n\n* [Okada_2003] E. Okada and D. T. Delpy, “Near-infrared light propagation in an adult head model. I. Modeling of low-level scattering in the cerebrospinal fluid layer,” Applied Optics 42, 2906–2914 (2003)\n* [Custo_2006] A. Custo, W. M. Wells III., A. H. Barnett, et al., “Effective scattering coefficient of the cerebral spinal fluid in adult head models for diffuse optical imaging,” Applied Optics 45, 4747 (2006)\n* [Strangman_2003] G. Strangman, M. A. Franceschini, and D. A. Boas, “Factors affecting the accuracy of near-infrared spectroscopy concentration calculations for focal changes in oxygenation parameters,” NeuroImage 18, 865–879 (2003)\n\nIn addition, in this release, we also added the following key new features\n\n* optimize thread configurations on Apple processors (M1/M2/M3/M4) and achieve 7x speed acceleration\n* the new `-N/--net` command line flag allows one to browse and run growing number of community-contributed\n simulations hosted on https://neurojson.io (one can browse the list at https://neurojson.org/db/mcx)\n* mcx can read stdin (standard input) using pipe, allow one to use advanced text processing utilities in the shell,\n such as `sed, perl, jq` to modify JSON inputs at runtime. For example `mcx -N cube60 | jq '.Forward.Dt=1e-10' | mcx -f`\n* a new shortcut option `-Q` for `--bench` to conveniently browse and run built-in benchmarks\n* mcxlabcl and pmcxcl cam set `cfg.flog=1` or 0 to disable printing of mcxcl banner\n\n\nThe detailed updates can be found in the below change log\n\n* 2025-01-23 [2a9476b] [feat] support reading pipe from command line with -f -\n* 2025-01-22 [febd932] [bug] fix incorrect per-voxel pathlength when mua-\u003e0, fangq/mcx#164\n* 2025-01-21 [3640d79] [bug] fix windows -N error\n* 2025-01-21 [44f63c0] [cmake] update cmake to add -N support\n* 2025-01-20 [6de71b0] [neurojson] avoid needing c++11, fix ci\n* 2025-01-20 [3cb78c4] [ci] fix mac warnings and errors\n* 2025-01-20 [29b0f3b] [feat] add -N/--net to download simulations from NeuroJSON.io, add -Q\n* 2024-11-13 [d79f6ed] [ci] remove mac local file\n* 2024-11-13 [96b8dbc] [ci] speedup macos-13 and windows octave download\n* 2024-11-13 [299b920] [ci] add install octave using dmg\n* 2024-11-13 [f8bb370] [ci] add windows octave mex build back\n* 2024-09-30 [0f642c3] [pmcxcl] bump pmcxcl version to 0.2.1 to include fix in fangq/mcx#233\n* 2024-09-29 [42917da] [bug] fix incorrect angleinvcdf and invcdf length, fangq/mcx#233\n* 2024-09-14 [f15814c] [ci] revert pybind11 version further for python3.6\n* 2024-09-14 [d3baf8c] [ci] add ubuntu-24.04 and macos-14\n* 2024-09-14 [e2fa087] [ci] remove DL_LDFLAGS\n* 2024-09-14 [dd99f92] [ci] macos ci fails with -shared\n* 2024-09-14 [7a3e4aa] [ci] test without macos-14\n* 2024-09-13 [4b9e21b] [bug] fix the potential typo in Custo et al for CSF mua, fangq/mcx#232\n* 2024-09-11 [c13dcf2] [ci] remove upx as github disabled upx for macos\n* 2024-09-11 [2191885] [ci] allow make oct to link with OpenCL on macos\n* 2024-09-03 [7c57318] [ci] fix action alert related to download-artifact https://github.com/NeuroJSON/zmat/security/dependabot/1\n* 2024-08-20 [8f84acf] [ci] use gcc-12 on macos runner\n* 2024-08-18 [d7defeb] [bug] fix lzma memory leakage, NeuroJSON/zmat#11, lloyd/easylzma#4\n* 2024-07-19 [9c86f6b] [bug] fix multi-gpu serialization bug on nvidia GPUs the bug was introduced in https://github.com/fangq/mcxcl/commit/9b4d76f03d86c2c9f3f449e340925649d4514379\n* 2024-06-12 [953c4e9] [ci] remove compiler warnings\n* 2024-06-12 [57612d0] [test] make mcxcl pass all tests on Alder lake Intel iGPU\n* 2024-06-12 [4609451] [bug] detector radius is not squared, fix #58\n* 2024-06-11 [2b91626] [intel] pass all tests and remove all warnings on old i7-2635QM on mac\n* 2024-06-11 [59d88a0] [test] sync test script between mcx and mcxcl after #57\n* 2024-06-11 [88899f9] [bug] reset replay.tof when tof too big, improve replay test, fix #57\n* 2024-06-09 [6e91fe3] [opencl] optimizing thread number on Apple silicon, gain 7x speedup\n* 2024-06-09 [c2bbf7f] [ci] test on macos-13\n* 2024-06-09 [7b558a4] [bug] fix colin27 failure on Apple silicon, fix #49\n* 2024-06-08 [93c589c] [ci] trying to fix macos-12 build\n* 2024-06-08 [9e84ecc] [bug] apply the same patch to ensure shared mem reset, fangq/mcx#222\n* 2024-06-08 [1154916] [bug] fix missing nscat output due to incorrect macro, fix #56\n* 2024-06-05 [8918150] [bug] add missing --maxjumpdebug flag, accept float, fix #54\n* 2024-06-04 [4b00f6d] [bug] fix double fclose error, close #53\n* 2024-04-25 [027cc55] [bug] avoid double-base64-encoding when -Z 2 is used, fangq/mcx#219\n* 2024-03-29 [cbfa564] [ci] modify DL_LDFLAGS\n* 2024-03-29 [ac879dc] [ci] revert LDFLAGS changes to compare difference on macos-12\n* 2024-03-29 [d175187] [ci] print verbose mkoctfile log to debug macos-12\n* 2024-03-29 [334c882] [package] copy LFLAGS to LDFLAGS, close #50\n\n\nIntroduction\n-------------\n\nMonte Carlo eXtreme (MCX) is a fast physically-accurate photon simulation \nsoftware for 3D heterogeneous complex media. By taking advantage of \nthe massively parallel threads and extremely low memory latency in a \nmodern graphics processing unit (GPU), this program is able to perform Monte \nCarlo (MC) simulations at a blazing speed, typically hundreds to\na thousand times faster than a single-threaded CPU-based MC implementation.\n\nMCX-CL is the OpenCL implementation of the MCX algorithm. Unlike MCX\nwhich can only be executed on NVIDIA GPUs, MCX-CL is written in OpenCL,\nthe Open Computing Language, and can be executed on most modern CPUs\nand GPUs available today, including Intel and AMD CPUs and GPUs. MCX-CL\nis highly portable, highly scalable and is feature-rich just like MCX.\n\nDue to the nature of the underlying MC algorithms, MCX and MCX-CL are\nray-tracing/ray-casting software under-the-hood. Compared to commonly\nseen ray-tracing libraries used in computer graphics or gaming\nengines, MCX-CL and MCX have many unique characteristics. The most\nimportant difference is that MCX/MCX-CL are rigorously based on physical\nlaws. They are numerical solvers to the underlying radiative transfer equation\n(RTE) and their solutions have been validated across many publications\nusing optical instruments and experimental measurements. In comparison,\nmost graphics-oriented ray-tracers have to make many approximations in\norder to achieve fast rendering, enable to provide quantitatively accurate\nlight simulation results. Because of this, MCX/MCX-CL have been extensively\nused by biophotonics research communities to obtain reference solutions and\nguide the development of novel medical imaging systems or clinical\napplications. Additionally, MCX/MCX-CL are volumetric ray-tracers; they\ntraverse photon-rays throughout complex 3-D domains and computes physically\nmeaningful quantities such as spatially resolved fluence, flux, diffuse\nreflectance/transmittance, energy deposition, partial pathlengths,\namong many others. In contrast, most graphics ray-tracing engines\nonly trace the RGB color of a ray and render it on a flat 2-D screen.\nIn other words, MCX/MCX-CL gives physically accurate 3-D light distributions\nwhile graphics ray-tracers focus on 2-D rendering of a scene at the camera.\nNonetheless, they share many similarities, such as ray-marching computation,\nGPU acceleration, scattering/absorption handling etc.\n\nThe details of MCX-CL can be found in the below paper\n\n\u003e [Yu2018] Leiming Yu, Fanny Nina-Paravecino, David Kaeli, and Qianqian Fang, \n\"Scalable and massively parallel Monte Carlo photon transport simulations \nfor heterogeneous computing platforms,\" J. Biomed. Optics, 23(1), 010504 (2018).\n\nA short summary of the main features includes:\n\n* 3D heterogeneous media represented by voxelated array\n* support over a dozen source forms, including wide-field and pattern illuminations\n* support a number of boundary conditions\n* time-resolved photon transport simulations\n* saving photon partial path lengths, trajectories and other per-photon data\n* optimized random number generators\n* build-in flux/fluence normalization to output Green's functions\n* user-adjustable voxel resolution\n* improved accuracy with atomic operations\n* cross-platform graphical user interface\n* native Matlab/Octave/Python interfaces for high usability\n* flexible JSON interface for future extensions\n* multi-GPU support\n* advanced features: photon-replay, photon-sharing, and more\n\nMCX-CL can be used on Windows, Linux and Mac OS. Multiple user \ninterfaces are provided, including\n\n- **Command line mode:** mcxcl can be executed in the command line, best suited \n for batch data processing\n- **Graphical User Interface with MCXStudio:** MCXStudio is a unified GUI program \n for MCX, MCX-CL and MMC. One can intuitively set all parameters, including GPU \n settings, MC settings and domain design, in the cross-platform interface\n- **Calling inside MATLAB/Octave:** mcxlabcl is a mex function, one can call it \n inside MATLAB or GNU Octave to get all functionalities as the command line version.\n- **Calling inside Python:** `pmcxcl` is a Python module wrapping the entire mcxcl\n simulation in an easy-to-use interface. One can install pmcxcl via `pip install pmcxcl`\n\nIf a user is familiar with MATLAB/Octave/Python, it is highly recommended to \nuse MCXCL in MATLAB/Octave/Python to ease data visualization. If one prefers a \nGUI, please use MCXStudio to start. For users who are familiar with MCX/MCXCL \nand need it for regular data processing, using the command line mode is \nrecommended.\n\n\nRequirement and Installation\n----------------------------\n\nWith the up-to-date driver installed for your computers, MCXCL can run on\nalmost all computers. The requirements for using this software include\n\n* a modern CPU or GPU (Intel, NVIDIA, AMD, among others)\n* pre-installed graphics driver - typically includes the OpenCL runtime (`libOpenCL.*` or `OpenCL.dll`)\n\nFor speed differences between different CPUs/GPUs made by different vendors, please\nsee your above paper [1] and our websites\n\n- http://mcx.space/computebench/\n- http://mcx.space/mcxcl\n\nGenerally speaking, AMD and NVIDIA high-end dedicated GPUs perform the best, about 20-60x \nfaster than a multi-core CPU; Intel's integrated GPU is about 3-4 times faster than\na multi-core CPU.\n\nMCX-CL supports and has been fully tested with open-source OpenCL runtime \npocl (http://portablecl.org/) on the CPU. To install pocl, please run\n```\nsudo apt-get install pocl-opencl-icd\n```\n\nTo install MCXCL, you simply download the binary executable corresponding to your \ncomputer architecture and platform, extract the package \nand run the executable under the `{mcxcl root}/bin` directory. For Linux\nand MacOS users, please double check and make sure `libOpenCL.so` is installed under \nthe `/usr/lib` directory. If it is installed under a different directory, please\ndefine environment variable `LD_LIBRARY_PATH` to include the path.\n\nIf `libOpenCL.so` or `OpenCL.dll` does not exist on your system or, please\nmake sure you have installed [CUDA SDK](https://developer.nvidia.com/cuda-toolkit) (if you are using an NVIDIA card)\nor AMD APP SDK (if you are using an AMD card), e.g. [Radeon™ Software for Linux](https://www.amd.com/en/support) or [ROCm](https://github.com/RadeonOpenCompute/ROCm) where the option for OpenCL was selected. \n\nAdditionally, if you are on a Linux-based system you may require the below dependences - this command assumes you are running Ubuntu:\n```\nsudo apt-get install ocl-icd-libopencl1 opencl-headers ocl-icd-opencl-dev zlib1g-dev \n```\n\nThe below installation steps can be browsed online at \n\nhttp://mcx.space/wiki/index.cgi/wiki/index.cgi?Workshop/MCX18Preparation/MethodA\n\n\n### Step 1. Verify your CPU/GPU support\n\nMCX-CL supports a wide-range of processors, including Intel/AMD CPUs \nand GPUs from NVIDIA/AMD/Intel. If your computer has been working previously,\nin most cases, MCX-CL can simply run out-of-box. However, if you have trouble,\nplease follow the below detailed steps to verify and setup your OS to run\nMCX-CL.\n\n#### Verify GPU/CPU support\n\nTo verify if you have installed the OpenCL or CUDA support, you may\n\n* if you have a windows machine, download and install the \n[Everything Search](https://www.voidtools.com/) tool (a small and \n fast file name search utility), and type `opencl.dll` in the search bar \n **Expected result**: you must see `OpenCL.dll` (or `nvopencl.dll`\n if you have an NVIDIA GPU) installed in the `Windows\\System32` directory.\n* if you have a Mac, open a terminal, and type `ls /System/Library/Frameworks/OpenCL.framework/Versions/A/OpenCL`\n** **Expected result**: you should not see an error.\n* if you have a Linux laptop, open a terminal, and type `locate libOpenCL.so`, \n** **Expected result**: you should see one or multiple libOpenCL files\n\nIf the `OpenCL.dll` file is not found on your Windows machine, please \nread the below sections. Otherwise, please go to Step 2: Install MATLAB.\n\n#### Computers without discrete GPUs\n\nIn many cases, your computer runs on an Intel CPU with integrated graphics. In \nthis case, please make sure you have installed the latest Intel graphics drivers. \nIf you are certain that you have installed the graphics drivers, or your \ngraphics works smoothly, please skip this step.\n\nIf you want to double check, for Windows machine, you can download the \n\"Intel Driver\u0026Support Assistant\" to check if you have installed the \ngraphics drivers from https://www.intel.com/content/www/us/en/developer/articles/tool/opencl-drivers.html\n\nFor a Mac, you need to use your App store to update the driver, see the \nbelow link for details https://www.intel.com/content/www/us/en/support/articles/000022440/graphics-drivers.html\n\nfor a Linux (for example Ubuntu) laptop, the intel CPU OpenCL run-time \ncan be downloaded from https://software.intel.com/en-us/articles/opencl-drivers#latest_CPU_runtime\n\nif you want to use both Intel CPU and GPU on Linux, you need to install \nthe OpenCL™ 2.0 GPU/CPU driver package for Linux* (this involves compiling a new kernel) \nhttps://software.intel.com/en-us/articles/opencl-drivers#latest_linux_driver\n\n#### Computers with discrete GPUs\n\nIf you have a computer with a discrete GPU, you need to make sure your \ndiscrete GPU is configured with the appropriate GPU \ndriver installed. Again, if you have been using your laptop regularly and \nthe graphics has been smooth, likely your graphics driver has already been \ninstalled.\n\nIf your GPU driver was not installed, and would like to install, or upgrade \nfrom an older version, for an NVIDIA GPU, you may browse this link to \ninstall the matching driver from http://www.nvidia.com/Download/index.aspx\n\nIf your GPU is an AMD GPU, please use the below link https://support.amd.com/en-us/download\n\nIt is also possible to simultaneously access Intel CPU along with your \ndiscrete GPU. In this case, you need to download the latest Intel OpenCL \nRuntime for CPU only if you haven't installed it already from \nhttps://software.intel.com/en-us/articles/opencl-drivers#latest_CPU_runtime\n\n**Note:** If you have an NVIDIA GPU, there is no need to install CUDA in \norder for you to run MCX-CL/MCXLABCL.\n\n#### Computers with hybrid GPUs\n\nWe noticed that running Ubuntu Linux 22.04 with a 6.5 kernel on a laptop with \na hybrid GPU with an Intel iGPU and an NVIDIA GPU, you must configure the\nlaptop to use the NVIDIA GPU as the primary GPU by choosing \"NVIDIA (Performance Mode)\"\nin the PRIME Profiles section of **NVIDIA X Server Settings**. You can also run \n\n```\nsudo prime-select nvidia\n```\n\nto achieve the same goal. Otherwise, the simulation may hang your system\nafter running for a few seconds. A hybrid GPU laptop combing an NVIDIA GPU \nwith an AMD iGPU does not seem to have this issue if using Linux.\n\nIn addition, NVIDIA drirver (520 or newer) has a known glitch running on Linux kernel\n6.x (such as those in Ubuntu 22.04). See\n\nhttps://forums.developer.nvidia.com/t/dev-nvidia-uvm-io-error-on-ubuntu-22-04-520-to-535-driver-versions/262153\n\nWhen the laptop is in the \"performance\" mode and wakes up from suspension, MCX/MCX-CL/MMC or any\nCUDA program fails to run with an error\n\n\n```\nMCX ERROR(-999):unknown error in unit mcx_core.cu:2523\n```\n\nThis is because the kernel module `nvida-uvm` fails to be reloaded after suspension.\nIf you had an open MATLAB session, you must close MATLAB first, and\nrun the below commands (if MATLAB is open, you will see `rmmod: ERROR: Module nvidia_uvm is in use`)\n\n```\nsudo rmmod /dev/nvidia-uvm\nsudo modprobe nvidia-uvm\n```\n\nafter the above command, MCX-CL should be able to run again.\n\n\n### Step 2. Install MATLAB or GNU Octave\n\nOne must install either a MATLAB or GNU Octave if one needs to use `mcxlabcl`.\nIf you use a Mac or Linux laptop, you need to create a link (if this link does\nnot exist) so that your system can find MATLAB. To do this you start a terminal, \nand type\n\n\tsudo ln -s /path/to/matlab /usr/local/bin\n\nplease replace `/path/to/matlab` to the actual `matlab` command \nfull path (for Mac, this is typically `/Application/MATLAB_R20???.app/bin/matlab`, \nfor Linux, it is typically `/usr/local/MATLAB/R20???/bin/matlab`, `???` \nis the year and release, such as 18a, 17b etc). You need to type your \npassword to create this link.\n\nTo verify your computer has MATLAB installed, please start a terminal on a \nMac or Linux, or type `cmd` and enter in Windows start menu, in the terminal, \ntype `matlab` and enter, you should see MATLAB starts.\n\n### Step 3. Installing MCXCL\n\nOne can either choose to compile mcxcl locally or download pre-compiled binaries from MCX's website. \n\n#### Compile From Source\n\nThis section assumes you are on a Linux-based machine, e.g. Ubunutu, CentOS, etc.\n\nClone this repository:\n```\ngit clone https://github.com/fangq/mcxcl.git\n```\n\nFrom here we can either use the latest master branch (default) or latest release, which is v2020 currently. \nTo change which release you are using we have to enter the directory we just cloned:\n```\ncd mcxcl\n```\n\nWe can start compiling from source. Now enter the `src` folder:\n```\ncd src\n```\nWe can do one of three things here - compile a standalone binary of mcxcl, a MATLAB/mex version, or an Octave/oct version. \n\n##### Standalone Binary\n\nSimply run: `make` \n\nWhich will compile a binary and place it in `mcxcl/bin`\n\n##### MATLAB\n\nMake sure you have mex in your `$PATH`, which can be done via:\n```\nexport PATH=\"/path/to/matlab/bin/mex:$PATH\"\n```\n\nRun: `make mex`\n\nThis will output the mex file to `mcxcl/mcxlabcl`\n\n##### Octave\n\nMake sure you have the following dependences - assuming you are running Ubuntu:\n\n```\nsudo apt install -y liboctave-dev\n```\n\nRun: `make oct`\n\nThis will output the octave/mex file to `mcxcl/mcxlabcl`\n\n##### Python\n\nMake sure you have the following dependences - assuming you are running Ubuntu:\n\n```\nsudo apt install -y python3-dev python3-pip python3-wheel cmake\n```\n\nRun: `cd pmcxcl \u0026\u0026 python3 -m pip wheel .`\n\nThis will output a binary wheel file `pmcxcl-X.Y.Z-cpXX-*.whl` in the `pmcxcl` folder.\nOne can install it using\n\n```\npython3 -m pip install pmcxcl*.whl\n```\n\n##### Misc\n\nAfter you have compilied and copied your binary to a seperate location you can run `make clean` to remove all the build files that were \ncreated during compilation. \n\n#### Download MCXCL\n\nOne can download two separate MCXCL packages (standalone mcxcl binary, and mcxlabcl)\nor download the integrated MCXStudio package (which contains mcx, mcxcl, mmc, mcxlab, \nmcxlabcl and mmclab) where both packages, and many more, are included. The latest\nstable released can be found on the MCX's website. However, if you want to use the\nlatest (but sometimes containing half-implemented features) software, you can access\nthe nightly-built packages from http://mcx.space/nightly/\n\nIf one has downloaded the mcxcl binary package, after extraction, you may open\na terminal (on Windows, type cmd the Start menu), cd mcxcl folder and then cd\nthe bin subfolder. Please type \"mcxcl\" and enter, if the binary is compatible with\nyour OS, you should see the printed help info. The next step is to run \n\n\tmcxcl -L\n\nThis will query your system and find any hardware that can run mcxcl. If your\nhardware (CPU and GPU) have proper driver installed, the above command will typically\nreturn 1 or more available computing hardware. Then you can move to the next step.\n\nIf you do not see any processor printed, that means your CPU or GPU does not have\nOpenCL support (because it is too old or no driver installed). You will need to \ngo to their vendor's website and download the latest driver. For Intel CPUs older\nthan Ivy Bridge (4xxx), OpenCL and MCXCl are not well supported. Please consider\ninstalling dedicated GPU or use a different computer.\n\nIn the case one has installed the MCXStudio package, you may follow the below \nprocedure to test for hardware compatibility.\n\nPlease click on the folder matching your operating system (for example, if you run \na 64bit Windows, you need to navigate into `win64` folder), and download \nthe file named `\"MCXStudio-nightlybuild-installer.exe\"`.\n\nOpen this file, and unzip it to a working folder (for Windows, for example, the \n`Documents` or `Downloads` folder). The package needs about 100 MB disk space.\n\nOnce unzipped, you should be able to see a folder named `MCXStudio`, \nwith a few executables and 3 subfolders underneath. See the folder structure below:\n\n\u003cpre\u003eMCXStudio/\n├── MATLAB/\n│   ├── mcxlab/\n│   ├── mcxlabcl/\n│   └── mmclab/\n├── MCXSuite/\n│   ├── mcx/\n│   ├── mcxcl/\n│   └── mmc/\n├── mcxstudio\n├── mcxshow\n└── mcxviewer\n\u003c/pre\u003e\n\nPlease make sure that your downloaded `MCXStudio` must match your operating system.\n\n#### Notes for Mac Users\n**For Mac users:** Please unzip the package under your \n[home directory](https://www.cnet.com/how-to/how-to-find-your-macs-home-folder-and-add-it-to-finder/) directly (Shift+Command+H).\n\n#### Notes for Windows Users\nWhen you start MCXStudio, you may see a dialog to ask you to modify the `TdrDelay` key \nin the registry so that mcx can run more than 5 seconds. If you select `Yes`, some \nof you may get an error saying you do not have permission. \n\nTo solve this problem, you need to quit MCXStudio, and then right-click on the \n`mcxstudio.exe`, and select \"Run as Administrator\". Then, you should be \nable to apply the registry change successfully. \n\nAlternatively, one should open file browser, navigate into `mcxcl/setup/win64` folder,\nand right-click on the `apply_timeout_registry_fix.bat` file and select \n\"Run as Administrator\".\n\n\tYou must reboot your computer for this change to be effective!\n\n### Step 4. Start MCXStudio and query GPU information\n\nNow, navigate to the MCXStudio folder (i.e. the top folder of the extracted \nsoftware structure). On Windows, right-click on the executable named `\"mcxstudio.exe\"` \nand select \"Run as Administrator\" for the first time only; on the Linux, \ndouble click on the `mcxstudio` executable; on the Mac, open a \nterminal and type\n\n\tcd ~/MCXStudio\n\topen mcxstudio.app\n\nFirst, click on the \"New\" button to the top-left (green plus icon), \nselect the 3rd option \"`NVIDIA/AMD/Intel CPUs/GPUs (MCX-CL)`\", \nand type a session name **\"test\"** in the field below. Then click \nOK. You should see a blue/yellow \"test\" icon added to the left panel. \n\nNow, click on the **\"GPU\"** button on the toolbar (6th button from \nthe left side), an Output window will popup, and wait for a few seconds, \nyou should see an output like\n\n\u003cpre\u003e\"-- Run Command --\"\n\"mcxcl\" -L\n\"-- Printing GPU Information --\"\nPlatform [0] Name NVIDIA CUDA\n============ GPU device ID 0 [1 of 2]: Graphics Device ============\n Device 1 of 2:\t\tGraphics Device\n Compute units :\t80 core(s)\n Global memory :\t12644188160 B\n Local memory :\t49152 B\n Constant memory :\t65536 B\n Clock speed :\t1455 MHz\n Compute Capacity:\t7.0\n Stream Processor:\t10240\n Vendor name :\tNVIDIA\n Auto-thread :\t655360\n...\nPlatform [1] Name Intel(R) OpenCL\n============ CPU device ID 2 [1 of 1]: Intel(R) Core(TM) i7-7700K CPU @ 4.20GHz ============\n Device 3 of 1:\t\tIntel(R) Core(TM) i7-7700K CPU @ 4.20GHz\n Compute units :\t8 core(s)\n Global memory :\t33404575744 B\n Local memory :\t32768 B\n Constant memory :\t131072 B\n Clock speed :\t4200 MHz\n Vendor name :\tIntel\n Auto-thread :\t512\n Auto-block :\t64\n\n\"-- Task completed --\"\n\u003c/pre\u003e\n\nYour output may look different from above. If you do not see any output, or \nit returns no GPU found, that means your OpenCL support was not installed \nproperly. Please go back to Steps 1-2 and reinstall the drivers. \n\nIf you have Intel CPU with Integrated GPU, you should be able to see a section with \n**\"Platform [?] Name Intel(R) OpenCL\"** in the above output. You may see only \nthe CPU is listed, or both the CPU and the integrated GPU.\n\n\n### Step 5. Run a trial simulation\n\nIf your above GPU query was successful, you should now see in the middle panel \nof the MCXStudio window, under the Section entitled \"GPU Settings\", in a check-box \nlist under \"Run MCX on\", you should now see the available devices on your laptop. \n\nTo avoid running lengthy simulations, please change the _\"Total photon number (-n)\"_ \nfield under the _\"Basic Settings\"_ from `1e6` to `1e5`.\n\nNow, you can then run a trial simulation, by first clicking on the \"Validate\" \nbutton (blue check-mark icon), and then click on \"Run\" (the button to the \nright of validate). This will launch an MCXCL simulation. The output window \nwill show again, and you can see the messages printed from the simulation, \nsimilar to the output below:\n\n\u003cpre\u003e\"-- Command: --\"\nmcxcl --session \"preptest\" --input \"/Output/mcxclsessions/preptest/preptest.json\" --root \"/Output/mcxclsessions/preptest\" --outputformat mc2 --gpu 10 --autopilot 1 --photon 10000000 --normalize 1 --save2pt 1 --reflect 1 --savedet 1 --unitinmm 1.00 --saveseed 0 --seed \"1648335518\" --compileropt \"-D USE_ATOMIC\" --array 0 --dumpmask 0 --repeat 1 --maxdetphoton 10000000\n\"-- Executing Simulation --\"\n==============================================================================\n= Monte Carlo eXtreme (MCX) -- OpenCL =\n= Copyright (c) 2010-2025 Qianqian Fang \u003cq.fang at neu.edu\u003e =\n= https://mcx.space/ \u0026 https://neurojson.io =\n= =\n= Computational Optics\u0026Translational Imaging (COTI) Lab - http://fanglab.org =\n= Department of Bioengineering, Northeastern University, Boston, MA, USA =\n==============================================================================\n= The MCX Project is funded by the NIH/NIGMS under grant R01-GM114365 =\n==============================================================================\n= Open-source codes and reusable scientific data are essential for research, =\n= MCX proudly developed human-readable JSON-based data formats for easy reuse=\n= =\n=Please visit our free scientific data sharing portal at https://neurojson.io=\n= and consider sharing your public datasets in standardized JSON/JData format=\n==============================================================================\n$Rev::4fdc45 $ v2025 $Date::2018-03-29 00:35:53 -04$by $Author::Qianqian Fang$\n==============================================================================\n- variant name: [Detective MCXCL] compiled with OpenCL version [1]\n- compiled with: [RNG] Logistic-Lattice [Seed Length] 5\ninitializing streams ...\tinit complete : 0 ms\n\nBuilding kernel with option: -cl-mad-enable -DMCX_USE_NATIVE -DMCX_SIMPLIFY_BRANCH -DMCX_VECTOR_INDEX -DMCX_SRC_PENCIL -D USE_ATOMIC -DUSE_ATOMIC -D MCX_SAVE_DETECTORS -D MCX_DO_REFLECTION\nbuild program complete : 23 ms\n- [device 0(1): Graphics Device] threadph=15 oddphotons=169600 np=10000000.0 nthread=655360 nblock=64 repetition=1\nset kernel arguments complete : 23 ms\nlauching mcx_main_loop for time window [0.0ns 5.0ns] ...\nsimulation run# 1 ... \n\nkernel complete: \t796 ms\nretrieving flux ... \t\ndetected 0 photons, total: 0\ttransfer complete: 818 ms\nnormalizing raw data ...\tnormalization factor alpha=20.000000\nsaving data to file ... 216000 1\tsaving data complete : 821 ms\n\nsimulated 10000000 photons (10000000) with 1 devices (repeat x1)\nMCX simulation speed: 12953.37 photon/ms\ntotal simulated energy: 10000000.00\tabsorbed: 27.22654%\n(loss due to initial specular reflection is excluded in the total)\n\u003c/pre\u003e\n\nIf this simulation is completed successfully, you should be able to see the \n\"Simulation speed\" and total simulated energy reported at the end. Please \nverify your \"absorbed\" percentage value printed at the end (in bold above), \nand make sure it is **~27%**. We found that some Intel OpenCL runtime\nversions produced incorrect results. \n\nIf your laptop shows an error for the Intel GPU, please choose another \ndevice from the \"GPU Settings\" section, and run the simulation again. \n\nIf your GPU/CPU gives the below error (found on HD4400 GPU and 4th gen Intel CPUs)\n\n\terror: OpenCL extension 'cl_khr_fp64' is unsupported\n\tMCXCL ERROR(11):Error: Failed to build program executable! in unit mcx_host.cpp:510\n\nYou may add \n\n\t-J \"-DUSE_LL5_RAND\"\n\nin the `MCXStudio GUI`\u003e`Advanced Settings`\u003e`Additional Parameters` \nfield. This should allow it to run, but please verify the absorption fraction \nis ~27%. For 4th generation Intel CPU, we found that install the Intel CPU \nOpenCL run-time can produce correct simulations. Please download it from \nhttps://software.intel.com/en-us/articles/opencl-drivers#latest_CPU_runtime\n\n### Step 6. Test MATLAB for visualization\n\nFrom v2019.3, MCXStudio provides builtin 3D volume visualization, this step is no longer needed.\n\n### Step 7. Setting up MATLAB search path\n\nThe next step is to set up the search paths for MCXLAB/MMCLAB. You need to \nstart MATLAB, and in the Command window, please type \n\n\tpathtool\n\nthis will popup a window. Click on the \"Add with Subfolders ...\" button \n(the 2nd from the top), then browse the MCXStudio folder, then select \nOK. Now you should see all needed MCX/MMC paths are added to MATLAB. \nBefore you quick this window, click on the \"Save\" button.\n\nTo verify if your MCXLAB/MMCLAB/MCXLABCL has been installed properly, please type\n\n\twhich mcxlab\n\twhich mmclab\n\twhich mcxlabcl\n\nyou should see their full paths printed. \n\n\nTo see if you can run MCXLAB-CL in your environment, please type \n\n\tUSE_MCXCL=1 ''%define this line in the base workspace, all subsequent mcxlab calls will use mcxcl''\n\tinfo=mcxlab('gpuinfo')\n\tclear USE_MCXCL\n\nthis should print a list of CPU/GPU devices using which you can run the MC simulations.\n\n\tupload: matlab_gpu_verify.png\n\nIf you do not see any output, that means your CPU/GPU OpenCL driver was not installed \nproperly, you need to go back to Steps 1-2.\n\nIf you have an NVIDIA GPU, and have installed the proper GPU driver, you may run\n\n\tinfo=mcxlab('gpuinfo') % notice the command is mcxlab instead of mcxlabcl\n\nthis should print a list of NVIDIA GPU from the MATLAB window.\n\n\nRunning Simulations\n----------------------------\n\nTo run a simulation, the minimum input is a configuration (text) file,\nand a volume (a binary file with each byte representing a medium \nindex). Typing the name of the executable without any parameters, \nwill print the help information and a list of supported parameters, \nsuch as the following:\n\n\u003cpre\u003e==============================================================================\n= Monte Carlo eXtreme (MCX) -- OpenCL =\n= Copyright (c) 2010-2025 Qianqian Fang \u003cq.fang at neu.edu\u003e =\n= https://mcx.space/ \u0026 https://neurojson.io =\n= =\n= Computational Optics\u0026Translational Imaging (COTI) Lab - http://fanglab.org =\n= Department of Bioengineering, Northeastern University, Boston, MA, USA =\n==============================================================================\n= The MCX Project is funded by the NIH/NIGMS under grant R01-GM114365 =\n==============================================================================\n= Open-source codes and reusable scientific data are essential for research, =\n= MCX proudly developed human-readable JSON-based data formats for easy reuse=\n= =\n=Please visit our free scientific data sharing portal at https://neurojson.io=\n= and consider sharing your public datasets in standardized JSON/JData format=\n==============================================================================\n$Rev::4fdc45 $ v2025 $Date::2018-03-29 00:35:53 -04$by $Author::Qianqian Fang$\n==============================================================================\n\nusage: mcxcl \u003cparam1\u003e \u003cparam2\u003e ...\nwhere possible parameters include (the first value in [*|*] is the default)\n\n== Required option ==\n -f config.json (--input) read an input file in the .json format,if config\n string starts with '{',it is parsed as an inline\n JSON input file; if -f is followed by nothing or\n a single '-', it reads input from stdin via pipe\n or\n -Q/--bench [cube60, skinvessel,...] run a buint-in benchmark specified by name\n run -Q without parameter to get a list\n -N benchmark (--net) get benchmark from NeuroJSON.io, -N only to list\n benchmark can be dataset URL,or dbname/benchname\n requires 'curl', install from https://curl.se/\n\n== MC options ==\n -n [0|int] (--photon) total photon number (exponential form accepted)\n -r [1|+/-int] (--repeat) if positive, repeat by r times,total= #photon*r\n if negative, divide #photon into r subsets\n -b [1|0] (--reflect) 1 to reflect photons at ext. boundary;0 to exit\n -B '______' (--bc) per-face boundary condition (BC), 6 letters for\n /case insensitive/ bounding box faces at -x,-y,-z,+x,+y,+z axes;\n overwrite -b if given. \n each letter can be one of the following:\n '_': undefined, fallback to -b\n 'r': like -b 1, Fresnel reflection BC\n 'a': like -b 0, total absorption BC\n 'm': mirror or total reflection BC\n 'c': cyclic BC, enter from opposite face\n\n if input contains additional 6 letters,\n the 7th-12th letters can be:\n '0': do not use this face to detect photon, or\n '1': use this face for photon detection (-d 1)\n the order of the faces for letters 7-12 is \n the same as the first 6 letters\n eg: --bc ______010 saves photons exiting at y=0\n -u [1.|float] (--unitinmm) defines the length unit for the grid edge\n -U [1|0] (--normalize) 1 to normalize flux to unitary; 0 save raw\n -E [0|int|.jdat] (--seed) set random-number-generator seed, -1 to generate\n if a jdat/mch file is followed, MCX \"replays\" \n the detected photon; the replay mode can be used\n to calculate the mua/mus Jacobian matrices\n -z [0|1] (--srcfrom0) 1 volume origin is [0 0 0]; 0: origin at [1 1 1]\n -Y [0|int] (--replaydet) replay only the detected photons from a given \n detector (det ID starts from 1), used with -E \n if 0, replay all detectors and sum all Jacobians\n if -1, replay all detectors and save separately\n -V [0|1] (--specular) 1 source located in the background,0 inside mesh\n -e [0.|float] (--minenergy) minimum energy level to trigger Russian roulette\n -g [1|int] (--gategroup) number of maximum time gates per run\n\n== GPU options ==\n -L (--listgpu) print GPU information only\n -t [16384|int](--thread) total thread number\n -T [64|int] (--blocksize) thread number per block\n -A [1|int] (--autopilot) auto thread config:1 enable;0 disable\n -G [0|int] (--gpu) specify which GPU to use, list GPU by -L; 0 auto\n or\n -G '1101' (--gpu) using multiple devices (1 enable, 0 disable)\n -W '50,30,20' (--workload) workload for active devices; normalized by sum\n -I (--printgpu) print GPU information and run program\n -o [1|int] (--optlevel) optimization level 0-no opt;1-4 more optimized\n -J '-DMACRO' (--compileropt) specify additional JIT compiler options\n A few built-in preprocessors include\n -DMCX_GPU_DEBUG - print step-by-step debug info\n -k my_simu.cl (--kernel) user specified OpenCL kernel source file\n\n== Input options ==\n -P '{...}' (--shapes) a JSON string for additional shapes in the grid.\n only the root object named 'Shapes' is parsed \n and added to the existing domain defined via -f \n or --bench\n -j '{...}' (--json) a JSON string for modifying all input settings.\n this input can be used to modify all existing \n settings defined by -f or --bench\n -K [1|int|str](--mediabyte) volume data format, use either a number or a str\n voxel binary data layouts are shown in {...}, where [] for byte,[i:]\n for 4-byte integer, [s:] for 2-byte short, [h:] for 2-byte half float,\n [f:] for 4-byte float; on Little-Endian systems, least-sig. bit on left\n 1 or byte: 0-128 tissue labels\n 2 or short: 0-65535 (max to 4000) tissue labels\n 4 or integer: integer tissue labels \n 98 or mixlabel: label1+label2+label1_percentage\n {[label1][label2][s:0-32767 label1 percentage]}\n 99 or labelplus: 32bit composite voxel format\n {[h:mua/mus/g/n][s:(B15-16:0/1/2/3)(label)]}\n 100 or muamus_float: 2x 32bit floats for mua/mus\n {[f:mua][f:mus]}; g/n from medium type 1\n 101 or mua_float: 1 float per voxel for mua\n {[f:mua]}; mus/g/n from medium type 1\n 102 or muamus_half: 2x 16bit float for mua/mus\n {[h:mua][h:mus]}; g/n from medium type 1\n 103 or asgn_byte: 4x byte gray-levels for mua/s/g/n\n {[mua][mus][g][n]}; 0-255 mixing prop types 1\u00262\n 104 or muamus_short: 2x short gray-levels for mua/s\n {[s:mua][s:mus]}; 0-65535 mixing prop types 1\u00262\n when formats 99 or 102 is used, the mua/mus values in the input volume\n binary data must be pre-scaled by voxel size (unitinmm) if it is not 1.\n pre-scaling is not needed when using these 2 formats in mcxlab/pmcx\n -a [0|1] (--array) 1 for C array (row-major); 0 for Matlab array\n\n== Output options ==\n -s sessionid (--session) a string to label all output file names\n -O [X|XFEJPML](--outputtype) X - output flux, F - fluence, E - energy density\n J - Jacobian (replay mode), P - scattering\n event counts at each voxel (replay mode only)\n M - momentum transfer; L - total pathlength\n -d [1|0-3] (--savedet) 1 to save photon info at detectors; 0 not save\n 2 reserved, 3 terminate simulation when detected\n photon buffer is filled\n -w [DP|DSPMXVW](--savedetflag)a string controlling detected photon data fields\n /case insensitive/ 1 D output detector ID (1)\n 2 S output partial scat. even counts (#media)\n 4 P output partial path-lengths (#media)\n 8 M output momentum transfer (#media)\n 16 X output exit position (3)\n 32 V output exit direction (3)\n 64 W output initial weight (1)\n combine multiple items by using a string, or add selected numbers together\n by default, mcx only saves detector ID and partial-path data\n -x [0|1] (--saveexit) 1 to save photon exit positions and directions\n setting -x to 1 also implies setting '-d' to 1\n same as adding 'XV' to -w.\n -X [0|1] (--saveref) 1 to save diffuse reflectance at the air-voxels\n right outside of the domain; if non-zero voxels\n appear at the boundary, pad 0s before using -X\n -m [0|1] (--momentum) 1 to save photon momentum transfer,0 not to save.\n same as adding 'M' to the -w flag\n -q [0|1] (--saveseed) 1 to save photon RNG seed for replay; 0 not save\n -M [0|1] (--dumpmask) 1 to dump detector volume masks; 0 do not save\n -H [1000000] (--maxdetphoton) max number of detected photons\n -S [1|0] (--save2pt) 1 to save the flux field; 0 do not save\n -F [jnii|...](--outputformat) fluence data output format:\n mc2 - MCX mc2 format (binary 32bit float)\n jnii - JNIfTI format (https://neurojson.org)\n bnii - Binary JNIfTI (https://neurojson.org)\n nii - NIfTI format\n hdr - Analyze 7.5 hdr/img format\n tx3 - GL texture data for rendering (GL_RGBA32F)\n the bnii/jnii formats support compression (-Z) and generate small files\n load jnii (JSON) and bnii (UBJSON) files using below lightweight libs:\n MATLAB/Octave: JNIfTI toolbox https://github.com/NeuroJSON/jnifti, \n MATLAB/Octave: JSONLab toolbox https://github.com/NeuroJSON/jsonlab,\n Python: PyJData: https://pypi.org/project/jdata\n JavaScript: JSData: https://github.com/NeuroJSON/jsdata\n -Z [zlib|...] (--zip) set compression method if -F jnii or --dumpjson\n is used (when saving data to JSON/JNIfTI format)\n 0 zlib: zip format (moderate compression,fast) \n 1 gzip: gzip format (compatible with *.gz)\n 2 base64: base64 encoding with no compression\n 3 lzip: lzip format (high compression,very slow)\n 4 lzma: lzma format (high compression,very slow)\n 5 lz4: LZ4 format (low compression,extrem. fast)\n 6 lz4hc: LZ4HC format (moderate compression,fast)\n --dumpjson [-,0,1,'file.json'] export all settings,including volume data using\n JSON/JData (https://neurojson.org) format for\n easy sharing; can be reused using -f\n if followed by nothing or '-', mcx will print\n the JSON to the console; write to a file if file\n name is specified; by default, prints settings\n after pre-processing; '--dumpjson 2' prints \n raw inputs before pre-processing\n\n== User IO options ==\n -h (--help) print this message\n -v (--version) print MCX revision number\n -l (--log) print messages to a log file instead\n -i (--interactive) interactive mode\n\n== Debug options ==\n -D [0|int] (--debug) print debug information (you can use an integer\n or or a string by combining the following flags)\n -D [''|RMPT] 1 R debug RNG\n /case insensitive/ 2 M store photon trajectory info\n 4 P print progress bar\n 8 T save trajectory data only, disable flux/detp\n combine multiple items by using a string, or add selected numbers together\n\n== Additional options ==\n --atomic [1|0] 1: use atomic operations; 0: do not use atomics\n --voidtime [1|0] when src is outside, 1 enables timer inside void\n --showkernel [1|0] 1:display the default or loaded (-k) MCXCL kernel\n --root [''|string] full path to the folder storing the input files\n --internalsrc [0|1] set to 1 to skip entry search to speedup launch\n --gscatter [1e9|int] after a photon completes the specified number of\n scattering events, mcx then ignores anisotropy g\n and only performs isotropic scattering for speed\n --maxvoidstep [1000|int] maximum distance (in voxel unit) of a photon that\n can travel before entering the domain, if \n launched outside (i.e. a widefield source)\n --maxjumpdebug [10000000|int] when trajectory is requested (i.e. -D M),\n use this parameter to set the maximum positions\n stored (default: 1e7)\n\n== Example ==\nexample: (list built-in benchmarks: -Q/--bench)\n mcxcl -Q\nor (list supported GPUs on the system: -L/--listgpu)\n mcxcl -L\nor (use multiple devices - 1st,2nd and 4th GPUs - together with equal load)\n mcxcl -Q cube60b -n 1e7 -G 1101 -W 10,10,10\nor (use inline domain definition)\n mcxcl -f input.json -P '{\"Shapes\":[{\"ZLayers\":[[1,10,1],[11,30,2],[31,60,3]]}]}'\nor (use inline json setting modifier)\n mcxcl -f input.json -j '{\"Optode\":{\"Source\":{\"Type\":\"isotropic\"}}}'\nor (dump simulation in a single json file)\n mcxcl -Q cube60planar --dumpjson\nor (use -N/--net to browse community-contributed mcxcl simulations at https://neurojson.io)\n mcxcl -N\nor (run user-shared mcxcl simulations, see full list at https://neurojson.org/db/mcx)\n mcxcl -N aircube60\nor (use -f - to read piped input file modified by shell text processing utilities)\n mcxcl -Q cube60 --dumpjson | sed -e 's/pencil/cone/g' | mcxcl -f -\nor (download/modify simulations from NeuroJSON.io and run with mcxcl -f)\n curl -s -X GET https://neurojson.io:7777/mcx/aircube60 | jq '.Forward.Dt = 1e-9' | mcxcl -f\n\u003c/pre\u003e\n\nTo further illustrate the command line options, below one can find a sample command\n```\nmcxcl -A 0 -t 16384 -T 64 -n 1e7 -G 1 -f input.json -r 2 -s test -g 10 -d 1 -w dpx -b 1\n```\nthe command above asks mcxcl to manually (`-A 0`) set GPU threads, and launch 16384 \nGPU threads (`-t`) with every 64 threads a block (`-T`); a total of 1e7 photons (`-n`)\nare simulated by the first GPU (`-G 1`) and repeat twice (`-r`) - i.e. total 2e7 photons;\nthe media/source configuration will be read from a JSON file named `input.json` \n(`-f`) and the output will be labeled with the session id “test” (`-s`); the \nsimulation will run 10 concurrent time gates (`-g`) if the GPU memory can not \nsimulate all desired time gates at once. Photons passing through the defined \ndetector positions are saved for later rescaling (`-d`); refractive index \nmismatch is considered at media boundaries (`-b`).\n\nHistorically, MCXCL supports an extended version of the input file format (.inp)\nused by tMCimg. However, we are phasing out the .inp support and strongly \nencourage users to adopt JSON formatted (.json) input files. Many of the \nadvanced MCX options are only supported in the JSON input format.\n\nA legacy .inp MCXCL input file looks like this:\n\n```\n1000000 # total photon, use -n to overwrite in the command line\n29012392 # RNG seed, negative to generate, use -E to overwrite\n30.0 30.0 0.0 1 # source position (in grid unit), the last num (optional) sets --srcfrom0 (-z)\n0 0 1 0 # initial directional vector, 4th number is the focal-length, 0 for collimated beam, nan for isotropic\n0.e+00 1.e-09 1.e-10 # time-gates(s): start, end, step\nsemi60x60x60.bin # volume ('unsigned char' binary format, or specified by -K/--mediabyte)\n1 60 1 60 # x voxel size in mm (isotropic only), dim, start/end indices\n1 60 1 60 # y voxel size, must be same as x, dim, start/end indices \n1 60 1 60 # y voxel size, must be same as x, dim, start/end indices\n1 # num of media\n1.010101 0.01 0.005 1.37 # scat. mus (1/mm), g, mua (1/mm), n\n4 1.0 # detector number and default radius (in grid unit)\n30.0 20.0 0.0 2.0 # detector 1 position (real numbers in grid unit) and individual radius (optional)\n30.0 40.0 0.0 # ..., if individual radius is ignored, MCX will use the default radius\n20.0 30.0 0.0 #\n40.0 30.0 0.0 # \npencil # source type (optional)\n0 0 0 0 # parameters (4 floats) for the selected source\n0 0 0 0 # additional source parameters\n```\n\nNote that the scattering coefficient mus=musp/(1-g).\n\nThe volume file (`semi60x60x60.bin` in the above example), can be read in two \nways by MCX: row-major[3] or column-major depending on the value of the user \nparameter `-a`. If the volume file was saved using matlab or fortran, the \nbyte order is column-major, and you should use `-a 0` or leave it out of \nthe command line. If it was saved using the `fwrite()` in C, the order is \nrow-major, and you can either use `-a 1`.\n\nYou may replace the binary volume file by a JSON-formatted shape file. Please \nrefer to Section V for details.\n\nThe time gate parameter is specified by three numbers: start time, end time and \ntime step size (in seconds). In the above example, the configuration specifies \na total time window of [0 1] ns, with a 0.1 ns resolution. That means the \ntotal number of time gates is 10.\n\nMCX provides an advanced option, -g, to run simulations when the GPU memory is \nlimited. It specifies how many time gates to simulate concurrently. Users may \nwant to limit that number to less than the total number specified in the input \nfile - and by default it runs one gate at a time in a single simulation. But if \nthere's enough memory based on the memory requirement in Section II, you can \nsimulate all 10 time gates (from the above example) concurrently by using \n`-g 10` in which case you have to make sure the video card has at least \n60\\*60\\*60\\*10\\*5=10MB of free memory. If you do not include the `-g`, MCX will \nassume you want to simulate just 1 time gate at a time.. If you specify a \ntime-gate number greater than the total number in the input file, (e.g, \n`-g 20`) MCX will stop when the 10 time-gates are completed. If you use the \nautopilot mode (`-A`), then the time-gates are automatically estimated for you.\n\n\nUsing JSON-formatted input files\n-----------------------------------\n\nStarting from version 0.7.9, MCX accepts a JSON-formatted input file in \naddition to the conventional tMCimg-like input format. JSON (JavaScript Object \nNotation) is a portable, human-readable and “fat-free” text format to \nrepresent complex and hierarchical data. Using the JSON format makes a input \nfile self-explanatory, extensible and easy-to-interface with other applications \n(like MATLAB).\n\nA sample JSON input file can be found under the examples/quicktest folder. The \nsame file, `qtest.json`, is also shown below:\n```\n{\n \"Help\": {\n \"[en]\": {\n \"Domain::VolumeFile\": \"file full path to the volume description file, can be a binary or JSON file\",\n \"Domain::Dim\": \"dimension of the data array stored in the volume file\",\n \"Domain::OriginType\": \"similar to --srcfrom0, 1 if the origin is [0 0 0], 0 if it is [1.0,1.0,1.0]\",\n\t\"Domain::LengthUnit\": \"define the voxel length in mm, similar to --unitinmm\",\n \"Domain::Media\": \"the first medium is always assigned to voxels with a value of 0 or outside of\n the volume, the second row is for medium type 1, and so on. mua and mus must \n be in 1/mm unit\",\n \"Session::Photons\": \"if -n is not specified in the command line, this defines the total photon number\",\n \"Session::ID\": \"if -s is not specified in the command line, this defines the output file name stub\",\n \"Forward::T0\": \"the start time of the simulation, in seconds\",\n \"Forward::T1\": \"the end time of the simulation, in seconds\",\n \"Forward::Dt\": \"the width of each time window, in seconds\",\n \"Optode::Source::Pos\": \"the grid position of the source, can be non-integers, in grid unit\",\n \"Optode::Detector::Pos\": \"the grid position of a detector, can be non-integers, in grid unit\",\n \"Optode::Source::Dir\": \"the unitary directional vector of the photon at launch\",\n \"Optode::Source::Type\": \"source types, must be one of the following: \n pencil,isotropic,cone,gaussian,planar,pattern,fourier,arcsine,disk,fourierx,fourierx2d,\n\t\t zgaussian,line,slit,pencilarray,pattern3d\",\n \"Optode::Source::Param1\": \"source parameters, 4 floating-point numbers\",\n \"Optode::Source::Param2\": \"additional source parameters, 4 floating-point numbers\"\n }\n },\n \"Domain\": {\n\t\"VolumeFile\": \"semi60x60x60.bin\",\n \"Dim\": [60,60,60],\n \"OriginType\": 1,\n\t\"LengthUnit\": 1,\n \"Media\": [\n {\"mua\": 0.00, \"mus\": 0.0, \"g\": 1.00, \"n\": 1.0},\n {\"mua\": 0.005,\"mus\": 1.0, \"g\": 0.01, \"n\": 1.0}\n ]\n },\n \"Session\": {\n\t\"Photons\": 1000000,\n\t\"RNGSeed\": 29012392,\n\t\"ID\": \"qtest\"\n },\n \"Forward\": {\n\t\"T0\": 0.0e+00,\n\t\"T1\": 5.0e-09,\n\t\"Dt\": 5.0e-09\n },\n \"Optode\": {\n\t\"Source\": {\n\t \"Pos\": [29.0, 29.0, 0.0],\n\t \"Dir\": [0.0, 0.0, 1.0],\n\t \"Type\": \"pencil\",\n\t \"Param1\": [0.0, 0.0, 0.0, 0.0],\n\t \"Param2\": [0.0, 0.0, 0.0, 0.0]\n\t},\n\t\"Detector\": [\n\t {\n\t\t\"Pos\": [29.0, 19.0, 0.0],\n\t\t\"R\": 1.0\n\t },\n {\n \"Pos\": [29.0, 39.0, 0.0],\n \"R\": 1.0\n },\n {\n \"Pos\": [19.0, 29.0, 0.0],\n \"R\": 1.0\n },\n {\n \"Pos\": [39.0, 29.0, 0.0],\n \"R\": 1.0\n }\n\t]\n }\n}\n```\n\nA JSON input file requiers several root objects, namely `Domain`, \n`Session`, `Forward` and `Optode`. Other root sections, like \n`Help`, will be ignored. Each object is a data structure providing \ninformation indicated by its name. Each object can contain various sub-fields. \nThe orders of the fields in the same level are flexible. For each field, you \ncan always find the equivalent fields in the `*.inp` input files. For example, \nThe `VolumeFile` field under the `Domain` object is the same as Line\\#6 \nin `qtest.inp`; the `RNGSeed` under `Session` is the same as Line\\#2; the \n`Optode.Source.Pos` is the same as the triplet in Line\\#3; the \n`Forward.T0` is the same as the first number in Line\\#5, etc.\n\nAn MCX JSON input file must be a valid JSON text file. You can validate your \ninput file by running a JSON validator, for example \u003chttp://jsonlint.com/\u003e You \nshould always use \"\" to quote a “name” and separate parallel items by \n“,”.\n\nMCX accepts an alternative form of JSON input, but using it is not recommended. \nIn the alternative format, you can use “`rootobj_name.field_name`”`: value` \nto represent any parameter directly in the root level. For example\n\n {\n \"Domain.VolumeFile\": \"semi60x60x60.json\",\n \"Session.Photons\": 10000000,\n ...\n }\n\nYou can even mix the alternative format with the standard format. If any input \nparameter has values in both formats in a single input file, the \nstandard-formatted value has higher priority.\n\nTo invoke the JSON-formatted input file in your simulations, you can use the \n`-f` command line option with MCX, just like using an `.inp` file. For \nexample:\n\n mcx -A 1 -n 20 -f onecube.json -s onecubejson\n\nThe input file must have a `.json` suffix in order for MCX to recognize. If \nthe input information is set in both command line, and input file, the command \nline value has higher priority (this is the same for `.inp` input files). For \nexample, when using `-n 20`, the value set in `Session`/`Photons`\nis overwritten to 20; when using `-s onecubejson`, the \n`Session`/`ID` value is modified. If your JSON input file is invalid, \nMCX will quit and point out where the format is incorrect.\n\n\nUsing JSON-formatted shape description files\n-----------------------------------------------\n\nStarting from v0.7.9, MCX can also use a shape description file in the place of \nthe volume file. Using a shape-description file can save you from making a \nbinary `.bin` volume. A shape file uses more descriptive syntax and can be easily \nunderstood and shared with others.\n\nSamples on how to use the shape files are included under the example/shapetest \nfolder.\n\nThe sample shape file, `shapes.json`, is shown below:\n```\n{\n \"MCX_Shape_Command_Help\":{\n \"Shapes::Common Rules\": \"Shapes is an array object. The Tag field sets the voxel value for each\n region; if Tag is missing, use 0. Tag must be smaller than the maximum media number in the\n input file.Most parameters are in floating-point (FP). If a parameter is a coordinate, it\n assumes the origin is defined at the lowest corner of the first voxel, unless user overwrite\n with an Origin object. The default origin of all shapes is initialized by user's --srcfrom0\n setting: if srcfrom0=1, the lowest corner of the 1st voxel is [0,0,0]; otherwise, it is [1,1,1]\",\n \"Shapes::Name\": \"Just for documentation purposes, not parsed in MCX\",\n \"Shapes::Origin\": \"A floating-point (FP) triplet, set coordinate origin for the subsequent objects\",\n \"Shapes::Grid\": \"Recreate the background grid with the given dimension (Size) and fill-value (Tag)\",\n \"Shapes::Sphere\": \"A 3D sphere, centered at C0 with radius R, both have FP values\",\n \"Shapes::Box\": \"A 3D box, with lower corner O and edge length Size, both have FP values\",\n \"Shapes::SubGrid\": \"A sub-section of the grid, integer O- and Size-triplet, inclusive of both ends\",\n \"Shapes::XLayers/YLayers/ZLayers\": \"Layered structures, defined by an array of integer triples:\n [start,end,tag]. Ends are inclusive in MATLAB array indices. XLayers are perpendicular to x-axis, and so on\",\n \"Shapes::XSlabs/YSlabs/ZSlabs\": \"Slab structures, consisted of a list of FP pairs [start,end]\n both ends are inclusive in MATLAB array indices, all XSlabs are perpendicular to x-axis, and so on\",\n \"Shapes::Cylinder\": \"A finite cylinder, defined by the two ends, C0 and C1, along the axis and a radius R\",\n \"Shapes::UpperSpace\": \"A semi-space defined by inequality A*x+B*y+C*z\u003eD, Coef is required, but not Equ\"\n },\n \"Shapes\": [\n {\"Name\": \"Test\"},\n {\"Origin\": [0,0,0]},\n {\"Grid\": {\"Tag\":1, \"Size\":[40,60,50]}},\n {\"Sphere\": {\"Tag\":2, \"O\":[30,30,30],\"R\":20}},\n {\"Box\": {\"Tag\":0, \"O\":[10,10,10],\"Size\":[10,10,10]}},\n {\"Subgrid\": {\"Tag\":1, \"O\":[13,13,13],\"Size\":[5,5,5]}},\n {\"UpperSpace\":{\"Tag\":3,\"Coef\":[1,-1,0,0],\"Equ\":\"A*x+B*y+C*z\u003eD\"}},\n {\"XSlabs\": {\"Tag\":4, \"Bound\":[[5,15],[35,40]]}},\n {\"Cylinder\": {\"Tag\":2, \"C0\": [0.0,0.0,0.0], \"C1\": [15.0,8.0,10.0], \"R\": 4.0}},\n {\"ZLayers\": [[1,10,1],[11,30,2],[31,50,3]]}\n ]\n }\n```\nA shape file must contain a `Shapes` object in the root level. Other \nroot-level fields are ignored. The `Shapes` object is a JSON array, with \neach element representing a 3D object or setting. The object-class commands \ninclude `Grid`, `Sphere`, `Box` etc. Each of these object include a \nnumber of sub-fields to specify the parameters of the object. For example, the \n`Sphere` object has 3 subfields, `O`, `R` and `Tag`. Field \n`O` has a value of 1x3 array, representing the center of the sphere; \n`R` is a scalar for the radius; `Tag` is the voxel values. The most \nuseful command is `[XYZ]Layers`. It contains a series of integer \ntriplets, specifying the starting index, ending index and voxel value of a \nlayered structure. If multiple objects are included, the subsequent objects \nalways overwrite the overlapping regions covered by the previous objects.\n\nThere are a few ways for you to use shape description records in your MCX \nsimulations. You can save it to a JSON shape file, and put the file name in \nLine\\#6 of your `.inp` file, or set as the value for Domain.VolumeFile field in a \n`.json` input file. In these cases, a shape file must have a suffix of `.json`.\n\nYou can also merge the Shapes section with a `.json` input file by simply \nappending the Shapes section to the root-level object. You can find an example, \n`jsonshape_allinone.json`, under examples/shapetest. In this case, you no longer \nneed to define the `VolumeFile` field in the input.\n\nAnother way to use Shapes is to specify it using the `-P` (or `--shapes`) command \nline flag. For example:\n```\n mcx -f input.json -P '{\"Shapes\":[{\"ZLayers\":[[1,10,1],[11,30,2],[31,60,3]]}]}'\n```\nThis will first initialize a volume based on the settings in the input `.json` \nfile, and then rasterize new objects to the domain and overwrite regions that \nare overlapping.\n\nFor both JSON-formatted input and shape files, you can use the JSONlab toolbox \n[4] to load and process in MATLAB.\n\n\nOutput data formats\n------------------------------------\n\nMCX may produces several output files depending user's simulation settings.\nOverall, MCX produces two types of outputs, 1) data accummulated within the \n3D volume of the domain (volumetric output), and 2) data stored for each detected\nphoton (detected photon data).\n\n### Volumetric output\n\nBy default, MCX stores a 4D array denoting the fluence-rate at each voxel in \nthe volume, with a dimension of Nx*Ny*Nz*Ng, where Nx/Ny/Nz are the voxel dimension\nof the domain, and Ng is the total number of time gates. The output data are\nstored in the format of single-precision floating point numbers. One may choose\nto output different physical quantities by setting the `-O` option. When the\nflag `-X/--saveref` is used, the output volume may contain the total diffuse\nreflectance only along the background-voxels adjacent to non-zero voxels. \nA negative sign is added for the diffuse reflectance raw output to distinguish\nit from the fuence data in the interior voxels.\n\nWhen photon-sharing (simultaneous simulations of multiple patterns) or photon-replay\n(the Jacobian of all source/detector pairs) is used, the output array may be extended\nto a 5D array, with the left-most/fastest index being the number of patterns Ns (in the\ncase of photon-sharing) or src/det pairs (in replay), denoted as Ns.\n\nSeveral data formats can be used to store the 3D/4D/5D volumetric output. Starting\nin MCX-CL v2023, JSON-based jnii format is the default format for saving the volumetric\ndata. Before v2023, the mc2 format is the default format.\n\n#### jnii files\n\nThe JNIfTI format represents the next-generation scientific data storage \nand exchange standard and is part of the NeuroJSON initiative (https://neurojson.org)\nled by the MCX author Dr. Qianqian Fang. The NeuroJSON project aims at developing\neasy-to-parse, human-readable and easy-to-reuse data storage formats based on\nthe ubiquitously supported JSON/binary JSON formats and portable JData data annotation\nkeywords. In short, .jnii file is simply a JSON file with capability of storing \nbinary strongly-typed data with internal compression and built in metadata.\n\nThe format standard (Draft 1) of the JNIfTI file can be found at\n\nhttps://github.com/NeuroJSON/jnifti\n\nA .jnii output file can be generated by using `-F jnii` in the command line.\n\nThe .jnii file can be potentially read in nearly all programming languages \nbecause it is 100% comaptible to the JSON format. However, to properly decode\nthe ND array with built-in compression, one should call JData compatible\nlibraries, which can be found at https://neurojson.org/wiki\n\nSpecifically, to parse/save .jnii files in MATLAB, you should use\n- JSONLab for MATLAB (https://github.com/fangq/jsonlab) or install `octave-jsonlab` on Fedora/Debian/Ubuntu\n- `jsonencode/jsondecode` in MATLAB + `jdataencode/jdatadecode` from JSONLab (https://github.com/fangq/jsonlab)\n\nTo parse/save .jnii files in Python, you should use\n- PyJData module (https://pypi.org/project/jdata/) or install `python3-jdata` on Debian/Ubuntu\n\nIn Python, the volumetric data is loaded as a `dict` object where `data['NIFTIData']` \nis a NumPy `ndarray` object storing the volumetric data.\n\n\n#### bnii files\n\nThe binary JNIfTI file is also part of the JNIfTI specification and the NeuroJSON\nproject. In comparison to text-based JSON format, .bnii files can be much smaller\nand faster to parse. The .bnii format is also defined in the BJData specification\n\nhttps://github.com/fangq/bjdata\n\nand is the binary interface to .jnii. A .bnii output file can be generated by \nusing `-F bnii` in the command line.\n\nThe .bnii file can be potentially read in nearly all programming languages \nbecause it was based on UBJSON (Universal Binary JSON). However, to properly decode\nthe ND array with built-in compression, one should call JData compatible\nlibraries, which can be found at https://neurojson.org/wiki\n\nSpecifically, to parse/save .jnii files in MATLAB, you should use one of\n- JSONLab for MATLAB (https://github.com/fangq/jsonlab) or install `octave-jsonlab` on Fedora/Debian/Ubuntu\n- `jsonencode/jsondecode` in MATLAB + `jdataencode/jdatadecode` from JSONLab (https://github.com/fangq/jsonlab)\n\nTo parse/save .jnii files in Python, you should use\n- PyJData module (https://pypi.org/project/jdata/) or install `python3-jdata` on Debian/Ubuntu\n\nIn Python, the volumetric data is loaded as a `dict` object where `data['NIFTIData']` \nis a NumPy `ndarray` object storing the volumetric data.\n\n#### mc2 files\n\nThe `.mc2` format is simply a binary dump of the entire volumetric data output,\nconsisted of the voxel values (single-precision floating-point) of all voxels and\ntime gates. The file contains a continuous buffer of a single-precision (4-byte) \n5D array of dimension Ns\\*Nx\\*Ny\\*Nz\\*Ng, with the fastest index being the left-most \ndimension (i.e. column-major, similar to MATLAB/FORTRAN).\n\nTo load the mc2 file, one should call `loadmc2.m` and must provide explicitly\nthe dimensions of the data. This is because mc2 file does not contain the data\ndimension information.\n\nSaving to .mc2 volumetric file is depreciated as we are transitioning towards\nJNIfTI/JData formatted outputs (.jnii). \n\n#### nii files\n\nThe NIfTI-1 (.nii) format is widely used in neuroimaging and MRI community to\nstore and exchange ND numerical arrays. It contains a 352 byte header, followed\nby the raw binary stream of the output data. In the header, the data dimension\ninformation as well as other metadata is stored. \n\nA .nii output file can be generated by using `-F nii` in the command line.\n\nThe .nii file is widely supported among data processing platforms, including\nMATLAB and Python. For example\n- niftiread.m/niftiwrite in MATLAB Image Processing Toolbox\n- JNIfTI toolbox by Qianqian Fang (https://github.com/NeuroJSON/jnifti/tree/master/lib/matlab)\n- PyNIfTI for Python http://niftilib.sourceforge.net/pynifti/intro.html\n\n\n### Detected photon data\n\nIf one defines detectors, MCX is able to store a variety of photon data when a photon\nis captured by these detectors. One can selectively store various supported data fields,\nincluding partial pathlengths, exit position and direction, by using the `-w/--savedetflag`\nflag. The storage of detected photon information is enabled by default, and can be\ndisabled using the `-d` flag.\n\nThe detected photon data are stored in a separate file from the volumetric output.\nThe supported data file formats are explained below.\n\n#### jdat files\n\nBy default, or when `-F jnii` is explicitly specified, a `.jdat` file is written, which is a\npure JSON file. This file contains a hierachical data record of the following JSON structure\n\n````\n {\n \"MCXData\": {\n \"Info\":{\n \"Version\":\n\t \"MediaNum\":\n\t \"DetNum\":\n\t ...\n\t \"Media\":{\n\t ...\n\t }\n },\n \"PhotonData\":{\n \"detid\":\n\t \"nscat\":\n\t \"ppath\":\n\t \"mom\":\n\t \"p\":\n\t \"v\":\n\t \"w0\":\n },\n \"Trajectory\":{\n \"photonid\":\n\t \"p\":\n\t \"w0\":\n },\n \"Seed\":[\n ...\n ]\n }\n }\n````\nwhere \"Info\" is required, and other subfields are optional depends on users' input.\nEach subfield in this file may contain JData 1-D or 2-D array constructs to allow \nstoring binary and compressed data.\n\nAlthough .jdat and .jnii have different suffix, they are both JSON/JData files and\ncan be opened/written by the same JData compatible libraries mentioned above, i.e.\n\nFor MATLAB\n- JSONLab for MATLAB (https://github.com/fangq/jsonlab) or install `octave-jsonlab` on Fedora/Debian/Ubuntu\n- `jsonencode/jsondecode` in MATLAB + `jdataencode/jdatadecode` from JSONLab (https://github.com/fangq/jsonlab)\n\nFor Python\n- PyJData module (https://pypi.org/project/jdata/) or install `python3-jdata` on Debian/Ubuntu\n\nIn Python, the volumetric data is loaded as a `dict` object where `data['MCXData']['PhotonData']` \nstores the photon data, `data['MCXData']['Trajectory']` stores the trajectory data etc.\n\n\n#### mch files\n\nThe .mch file, or MC history file, is stored by default, but we strongly encourage users\nto adpot the newly implemented JSON/.jdat format for easy data sharing. \n\nThe .mch file contains a 256 byte binary header, followed by a 2-D numerical array\nof dimensions `#savedphoton * #colcount` as recorded in the header.\n```\n typedef struct MCXHistoryHeader{\n\tchar magic[4]; // magic bits= 'M','C','X','H'\n\tunsigned int version; // version of the mch file format \n\tunsigned int maxmedia; // number of media in the simulation \n\tunsigned int detnum; // number of detectors in the simulation \n\tunsigned int colcount; // how many output files per detected photon \n\tunsigned int totalphoton; // how many total photon simulated \n\tunsigned int detected; // how many photons are detected (not necessarily all saved) \n\tunsigned int savedphoton; // how many detected photons are saved in this file \n\tfloat unitinmm; // what is the voxel size of the simulation \n\tunsigned int seedbyte; // how many bytes per RNG seed\n float normalizer; // what is the normalization factor\n\tint respin; // if positive, repeat count so total photon=totalphoton*respin; if negative, total number is processed in respin subset \n\tunsigned int srcnum; // number of sources for simultaneous pattern sources \n\tunsigned int savedetflag; // number of sources for simultaneous pattern sources \n\tint reserved[2]; // reserved fields for future extension \n } History;\n```\nWhen the `-q` flag is set to 1, the detected photon initial seeds are also stored\nfollowing the detected photon data, consisting of a 2-D byte array of `#savedphoton * #seedbyte`.\n\nTo load the mch file, one should call `loadmch.m` in MATLAB/Octave.\n\nSaving to .mch history file is depreciated as we are transitioning towards\nJSON/JData formatted outputs (`.jdat`).\n\n### Photon trajectory data\n\nFor debugging and plotting purposes, MCX can output photon trajectories, as polylines,\nwhen `-D M` or `-D T` flag is attached, or mcxlab is asked for the 5th output. Such information\ncan be stored in one of the following formats.\n\n#### jdat files\n\nBy default, or when `-F jnii` is used, MCX-Cl merges the trajectory data with the detected photon and\nseed data and saved as a JSON-compatible .jdat file. The overall structure of the\n.jdat file as well as the relevant parsers can be found in the above section.\n\n#### mct files\n\nIf `-F mc2` is used, MCX-CL stores the photon trajectory data in to a .mct file MC trajectory, which\nuses the same binary format as .mch but renamed as .mct. This file can be loaded to\nMATLAB using the same `loadmch.m` function. \n\nUsing .mct file is depreciated and users are encouraged to migrate to .jdat file\nas described below.\n\nUsing mcxlabcl in MATLAB and Octave\n----------------------------\n\nmcxlabcl is the native MEX version of MCX-CL for Matlab and GNU Octave. It includes\nthe entire MCX-CL code in a MEX function which can be called directly inside\nMatlab or Octave. The input and output files in MCX-CL are replaced by convenient\nin-memory struct variables in mcxlabcl, thus, making it much easier to use\nand interact. Matlab/Octave also provides convenient plotting and data\nanalysis functions. With mcxlabcl, your analysis can be streamlined and speed-\nup without involving disk files.\n\nPlease read the `mcxlab/README` file for more details on how to\ninstall and use MCXLAB.\n\nSpecifically, please add the path to `mcxlabcl.m` and `mcxcl.mex*` to your\nMATLAB or octave following Step 7 in Section II Installation.\n\nTo use `mcxlabcl`, the first step is to see if your system has any supported\nprocessors. To do this, you can use one of the following 3 ways\n\n\tinfo=mcxlabcl('gpuinfo')\n\nor run\n\n\tinfo=mcxlab('gpuinfo','opencl')\n\nor\n\n\tUSE_MCXCL=1\n\tinfo=mcxlab('gpuinfo')\n\nOverall, mcxlabcl and mcxlab is highly compatible with nearly identical features\nand interfaces. If yo have a working mcxlab script, the simpliest way to use it\nwith mcxlabcl on non-NVIDIA devices is to insert the below command\n\n\teval('base','USE_MCXCL=1');\n\nat the begining of the script, and insert \n\n\teval('base','USE_MCXCL=0');\n\nat the end of the script.\n\nIf you have supported processors, please then run the demo mcxlabcl scripts\ninside mcxlabcl/examples. mcxlabcl and mcxlab has a high compatibility in interfaces\nand features. If you have a previously written MCXLAB script, you are likely able\nto run it without modification when calling `mcxlabcl`. All you need to do\nis to define\n\n\tUSE_MCXCL=1\n \nin matlab's base workspace (command line window). Alternatively, you may replace\n`mcxlab()` calls by `mcxlab(...,'opencl')`, or by `mcxlabcl()`.\n\nPlease make sure you select the fastest processor on your system by using the `cfg.gpuid`\nfield. \n\n\nUsing PMCX-CL in Python\n------------------------------------\n\nPMCX-CL is the native binary binding of MCX-CL for Python 3.6 or newer. Similar to\nMCXLAB, PMCX-CL can run GPU-based simulations inside Python environment with\nefficient in-memory inputs and outputs. \n\nPlease read the pmcxcl/README.txt file for more details on how to install and \nuse PMCX-CL.\n\nPlease also browse this interactive [Jupyter Notebook based PMCX-CL tutorial](https://colab.research.google.com/github/fangq/mcx/blob/master/pmcx/tutorials/pmcx_getting_started.ipynb)\nto see a suite of examples showing the key functionalities of PMCX-CL.\n\nUsing MCXStudio GUI\n----------------------------\n\nMCXStudio is a graphics user interface (GUI) for MCX/MCXCL and MMC. It gives users\na straightforward way to set the command line options and simulation\nparameters. It also allows users to create different simulation tasks \nand organize them into a project and save for later use.\nMCX Studio can be run on many platforms such as Windows,\nGNU Linux and Mac OS.\n\nTo use MCXStudio, it is suggested to put the mcxstudio binary\nin the same directory as the mcx command; alternatively, you can\nalso add the path to mcx command to your PATH environment variable.\n\nOnce launched, MCX Studio will automatically check if mcx/mcxcl\nbinary is in the search path, if so, the \"GPU\" button in the \ntoolbar will be enabled. It is suggested to click on this button\nonce, and see if you can see a list of GPUs and their parameters \nprinted in the output field at the bottom part of the window. \nIf you are able to see this information, your system is ready\nto run MCX simulations. If you get error messages or not able\nto see any usable GPU, please check the following:\n\n* are you running MCX Studio/MCX on a computer with a supported card?\n* have you installed the CUDA/NVIDIA drivers correctly?\n* did you put mcx in the same folder as mcxstudio or add its path to PATH?\n\nIf your system has been properly configured, you can now add new simulations \nby clicking the \"New\" button. MCX Studio will ask you to give a session\nID string for this new simulation. Then you are allowed to adjust the parameters\nbased on your needs. Once you finish the adjustment, you should click the \n\"Verify\" button to see if there are missing settings. If everything looks\nfine, the \"Run\" button will be activated. Click on it once will start your\nsimulation. If you want to abort the current simulation, you can click\nthe \"Stop\" button.\n\nYou can create multiple tasks with MCX Studio by hitting the \"New\"\nbutton again. The information for all session configurations can\nbe saved as a project file (with .mcxp extension) by clicking the\n\"Save\" button. You can load a previously saved project file back\nto MCX Studio by clicking the \"Load\" button.\n\n\nInterpreting the Output\n----------------------------\n\nMCX/MCX-CL output consists of two parts, the flux volume \nfile and messages printed on the screen.\n\n##### Output files\n\nA `.jnii` file contains the fluence-rate distribution from the simulation in \nthe given medium. By default, this fluence-rate is a normalized solution \n(as opposed to the raw probability) therefore, one can compare this directly \nto the analytical solutions (i.e. Green's function). The order of storage in the \n`.jnii` files is the same as the input file: i.e., if the input is row-major, the \noutput is row-major, and so on. The dimensions of the file are Nx, Ny, Nz, and Ng\nwhere Ng is the total number of time gates.\n\nBy default, MCX produces the **Green's function** of the \n**fluence rate** for the given domain and source. Sometime it is also \nknown as the time-domain \"two-point\" function. If you run MCX with the following command\n\n\tmcxcl -f input.json -s output ....\n\nthe fluence-rate data will be saved in a file named `output.dat` under\nthe current folder. If you run MCX without `-s output`, the\noutput file will be named as `input.json.dat`.\n\nTo understand this further, you need to know that a **fluence-rate `Phi(r,t)`** is\nmeasured by number of particles passing through an infinitesimal \nspherical surface per **unit time** at **a given location** regardless of directions.\nThe unit of the MCX output is \u003csup\u003eW\u003c/sup\u003e\u0026frasl;\u003csub\u003emm\u003csup\u003e2\u003c/sup\u003e s \u003c/sub\u003e = \u003csup\u003eJ\u003c/sup\u003e\u0026frasl;\u003csub\u003emm\u003csup\u003e2\u003c/sup\u003es\u003c/sub\u003e, if it is interpreted as the \n\"energy fluence-rate\" [6], or \u003csup\u003e1\u003c/sup\u003e\u0026frasl;\u003csub\u003emm\u003csup\u003e2\u003c/sup\u003es \u003c/sub\u003e, if the output is interpreted as the \n\"particle fluence-rate\" [6].\n\nThe Green's function of the fluence-rate means that it is produced\nby a **unitary source**. In simple terms, this represents the \nfraction of particles/energy that arrives a location per second \nunder **the radiation of 1 unit (packet or J) of particle or energy \nat time t=0**. The Green's function is calculated by a process referred\nto as the \"normalization\" in the MCX code and is detailed in the \nMCX paper [6] (MCX and MMC outputs share the same meanings).\n\nPlease be aware that the output flux is calculated at each time-window \ndefined in the input file. For example, if you type \n\n\t0.e+00 5.e-09 1e-10 # time-gates(s): start, end, step\n\nin the 5th row in the input file, MCX will produce 50 fluence-rate\nsnapshots, corresponding to the time-windows at [0 0.1] ns, \n[0.1 0.2]ns ... and [4.9,5.0] ns. To convert the fluence rate\nto the fluence for each time-window, you just need to\nmultiply each solution by the width of the window, 0.1 ns in this case. \nTo convert the time-dependent fluence-rate to continuous-wave (CW) \nfluence (fluence in short), you need to integrate the\nfluence-rate along the time dimension. Assuming the fluence-rate after \n5 ns is negligible, then the CW fluence is simply `sum(flux_i*0.1 ns, i=1,50)`. \nYou can read `mcx/examples/validation/plotsimudata.m`\nand `mcx/examples/sphbox/plotresults.m` for examples \nto compare an MCX output with the analytical fluence-rate/fluence solutions.\n\nOne can load an `mc2` output file into Matlab or Octave using the\n`loadmc2` function in the `{mcx root}/utils` folder. \n\nTo get a continuous-wave solution, run a simulation with a sufficiently \nlong time window, and sum the flux along the time dimension, for \nexample\n\n\tfluence=loadmc2('output.mc2',[60 60 60 10],'float');\n\tcw_mcx=sum(fluence,4);\n\nNote that for time-resolved simulations, the corresponding solution\nin the results approximates the flux at the center point\nof each time window. For example, if the simulation time window \nsetting is [t\u003csub\u003e0\u003c/sub\u003e,t\u003csub\u003e0\u003c/sub\u003e+dt,t\u003csub\u003e0\u003c/sub\u003e+2dt,t\u003csub\u003e0\u003c/sub\u003e+3dt...,t1], the time points for the \nsnapshots stored in the solution file is located at \n[t\u003csub\u003e0\u003c/sub\u003e+dt/2, t\u003csub\u003e0\u003c/sub\u003e+3*dt/2, t\u003csub\u003e0\u003c/sub\u003e+5*dt/2, ... ,t\u003csub\u003e1\u003c/sub\u003e-dt/2]\n\nA more detailed interpretation of the output data can be found at \n\u003chttp://mcx.sf.net/cgi-bin/index.cgi?MMC/Doc/FAQ#How_do_I_interpret_MMC_s_output_data\u003e\n\nMCX can also output \"current density\" (`J(r,t)`, unit \u003csup\u003eW\u003c/sup\u003e\u0026frasl;\u003csub\u003em\u003csup\u003e2\u003csup\u003e\u003c/sub\u003e, same as \n`Phi(r,t)`) - referring to the expected number of photons or Joule of energy \nflowing through a unit area pointing towards a particular direction per unit\ntime. The current density can be calculated at the boundary of the domain by \ntwo means:\n\n1. using the detected photon partial path output (i.e. the second output of \n mcxlab.m), one can compute the total energy `E` received by a detector, then one \n can divide E by the area/aperture of the detector to obtain the `J(r)` at a \n detector (E should be calculated as a function of t by using the time-of-fly of \n detected photons, the `E(t)/A` gives `J(r,t)`; if you integrate all time gates, \n the total E/A gives the current I(r), instead of the current density).\n2. use `-X 1 or --saveref/cfg.issaveref` option in mcx to enable the diffuse \n reflectance recordings on the boundary. the diffuse reflectance is represented \n by the current density `J(r)` flowing outward from the domain.\n\nThe current density has, as mentioned, the same unit as fluence rate, but the \ndifference is that `J(r,t)` is a vector, and `Phi(r,t)` is a scalar. Both \nmeasuring the energy flow across a small area (the are has direction in the \ncase of J) per unit\ntime.\n\nYou can find more rigorous definitions of these quantities in Lihong Wang's \nBiomedical Optics book, Chapter 5.\n\n##### Guide for output units\n\n- Flux (\u003csup\u003eW\u003c/sup\u003e \u0026frasl; \u003csub\u003e mm\u003csup\u003e2\u003c/sup\u003e J \u003c/sub\u003e): Normalized energy flux/fluence-rate. \nOr (\u003csup\u003e1\u003c/sup\u003e \u0026frasl; \u003csub\u003e mm\u003csup\u003e2\u003c/sup\u003e s \u003c/sub\u003e) which is the normalized particle fluence-rate.\n\n- Fluence (\u003csup\u003eJ\u003c/sup\u003e \u0026frasl; \u003csub\u003e mm\u003csup\u003e2\u003c/sup\u003e J \u003c/sub\u003e): Normalized energy fluence. \nOr (\u003csup\u003e1\u003c/sup\u003e \u0026frasl; \u003csub\u003e mm\u003csup\u003e2\u003c/sup\u003e \u003c/sub\u003e) which is the normalized particle fluence.\n\t\n- Energy (\u003csup\u003eJ\u003c/sup\u003e \u0026frasl; \u003csub\u003e mm\u003csup\u003e2\u003c/sup\u003e J \u003c/sub\u003e): Normalized energy deposition. \nOr (\u003csup\u003e1\u003c/sup\u003e \u0026frasl; \u003csub\u003e mm\u003csup\u003e3\u003c/sup\u003e \u003c/sub\u003e) which is the normalized particle deposition.\n\nFor example if one wanted an image of the fluence through their system \n(such that `--outputtype` is `fluence`) you would multiply the output from `mcxcl` by\nthe amount of joules delivered. \n\n##### Console print messages\n\nTiming information is printed on the screen (stdout). The clock starts (at time \nT0) right before the initialization data is copied from CPU to GPU. For each \nsimulation, the elapsed time from T0 is printed (in ms). Also the accumulated \nelapsed time is printed for all memory transaction from GPU to CPU.\n\nWhen a user specifies `-D P` in the command line, or set `cfg.debuglevel='P'`, \nMCXCL or MCXLABCL prints a progress bar showing the percentage of completition.\n\nWhen a user adds `-J \"-DMCX_GPU_DEBUG\"` in the command line, MCXCL prints\nstep-by-step photon movement information for easy debugging. Please restrict the photon\nto a small number, such as `-n 1` to avoid long output.\n\n\nBest practices guide\n----------------------------\n\nTo maximize MCX-CL's performance on your hardware, you should follow the best \npractices guide listed below:\n\n**Use dedicated GPUs:** A dedicated GPU is a GPU that is not connected to a monitor. If you use\na non-dedicated GPU, any kernel (GPU function) can not run more than a\nfew seconds. This greatly limits the efficiency of MCX. To set up a \ndedicated GPU, it is suggested to install two graphics cards on your \ncomputer, one is set up for displays, the other one is used for GPU \ncomputation only. If you have a dual-GPU card, you can also connect \none GPU to a single monitor, and use the other GPU for computation\n(selected by `-G` in mcx/mcxcl). If you have to use a non-dedicated GPU, you\ncan either use the pure command-line mode (for Linux, you need to \nstop X server), or use the `-r` flag to divide the total simulation \ninto a set of simulations with less photons, so that each simulation \nonly lasts a few seconds.\n\n**Launch as many threads as possible:** It has been shown that MCX-CL's \nspeed is related to the thread number (`-t`).\nGenerally, the more threads, the better speed, until all GPU resources\nare fully occupied. For higher-end GPUs, a thread number over 10,000 \nis recommended. Please use the autopilot mode, `-A`, to let MCX determine\nthe \"optimal\" thread number when you are not sure what to use.\n\n\nAcknowledgement\n------------------\n\nMCX contains modified versions of the below source codes from other \nopen-source projects (with a compatible license).\n\n### cJSON library by Dave Gamble\n\n- Files: src/cJSON folder\n- Copyright (c) 2009 Dave Gamble\n- URL: https://github.com/DaveGamble/cJSON\n- License: MIT License, https://github.com/DaveGamble/cJSON/blob/master/LICENSE\n\n### ZMat data compression unit\n\n- Files: src/zmat/*\n- Copyright: 2019-2020 Qianqian Fang\n- URL: https://github.com/fangq/zmat\n- License: GPL version 3 or later, https://github.com/fangq/zmat/blob/master/LICENSE.txt\n\n### LZ4 data compression library\n\n- Files: src/zmat/lz4/*\n- Copyright: 2011-2020, Yann Collet\n- URL: https://github.com/lz4/lz4\n- License: BSD-2-clause, https://github.com/lz4/lz4/blob/dev/lib/LICENSE\n\n### LZMA/Easylzma data compression library\n\n- Files: src/zmat/easylzma/*\n- Copyright: 2009, Lloyd Hilaiel, 2008, Igor Pavlov\n- License: public-domain\n- Comment:\n All the cruft you find here is public domain. You don't have to\n credit anyone to use this code, but my personal request is that you mention\n Igor Pavlov for his hard, high quality work.\n\n### myslicer toolbox by Anders Brun\n\n- Files: utils/{islicer.m, slice3i.m, image3i.m}\n- Copyright (c) 2009 Anders Brun, anders@cb.uu.se\n- URL: https://www.mathworks.com/matlabcentral/fileexchange/25923-myslicer-make-mouse-interactive-slices-of-a-3-d-volume\n- License: BSD-3-clause License, https://www.mathworks.com/matlabcentral/fileexchange/25923-myslicer-make-mouse-interactive-slices-of-a-3-d-volume#license_modal\n\n\nReference\n----------------------------\n\n- [1] Leiming Yu, Fanny Nina-Paravecino, David Kaeli, and Qianqian Fang, \n\"Scalable and massively parallel Monte Carlo photon transport simulations \nfor heterogeneous computing platforms\", J. Biomed. Optics, 23(1), 010504 (2018) .\n- [2] Qianqian Fang and David A. Boas, \"Monte Carlo Simulation of Photon \nMigration in 3D Turbid Media Accelerated by Graphics Processing Units,\" \nOptics Express, vol. 17, issue 22, pp. 20178-20190 (2009).\n\nIf you used MCX in your research, the authors of this software would like\nyou to cite the above paper in your related publications.\n\n**Links:** \n\n- [1] http://www.nvidia.com/object/cuda_get.html\n- [2] http://www.nvidia.com/object/cuda_learn_products.html\n- [3] http://en.wikipedia.org/wiki/Row-major_order\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffangq%2Fmcxcl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffangq%2Fmcxcl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffangq%2Fmcxcl/lists"}