From aa9b2f444c1fe0568cf7974db2dff33cb34b0bc8 Mon Sep 17 00:00:00 2001 From: Qianqian Fang Date: Sat, 12 Aug 2023 16:51:41 -0400 Subject: [PATCH] update documentation, prepare for v2023 release --- .github/workflows/build_all.yml | 2 +- AUTHORS.txt | 28 ++- ChangeLog.txt | 85 +++++++- LICENSE.txt | 2 +- Makefile | 2 +- NOTICE.txt | 10 +- README.md | 264 +++++++++++++++++++----- README.txt | 275 ++++++++++++++++++++----- TODO.txt | 8 +- inno/MCXStudio.iss | 2 +- mcxlab/README.txt | 59 +++++- mcxstudio/README.txt | 2 +- mcxstudio/mcxabout.lfm | 2 +- mcxstudio/mcxstudio.lpi | 349 ++------------------------------ src/mcx.c | 2 +- src/mcx_bench.c | 2 +- src/mcx_bench.h | 2 +- src/mcx_const.h | 2 +- src/mcx_core.cu | 2 +- src/mcx_core.h | 2 +- src/mcx_ieee754.h | 2 +- src/mcx_mie.cpp | 2 +- src/mcx_mie.h | 2 +- src/mcx_rand_posix.cu | 2 +- src/mcx_rand_xoroshiro128p.cu | 2 +- src/mcx_rand_xorshift128p.cu | 2 +- src/mcx_shapes.c | 2 +- src/mcx_shapes.h | 2 +- src/mcx_tictoc.c | 2 +- src/mcx_tictoc.h | 2 +- src/mcx_utils.c | 8 +- src/mcx_utils.h | 2 +- src/mcxlab.cpp | 4 +- src/pmcx.cpp | 4 +- 34 files changed, 648 insertions(+), 492 deletions(-) diff --git a/.github/workflows/build_all.yml b/.github/workflows/build_all.yml index 187322a5..1ae4e544 100644 --- a/.github/workflows/build_all.yml +++ b/.github/workflows/build_all.yml @@ -150,7 +150,7 @@ jobs: otool -L ../bin/mcx else make static - #objdump -p ../bin/mcx | grep "DLL Name:" + objdump -p ../bin/mcx | grep "DLL Name:" fi - name: Build mcxstudio if: ${{ runner.os != 'macOS' }} diff --git a/AUTHORS.txt b/AUTHORS.txt index 7e093b25..a61ec322 100644 --- a/AUTHORS.txt +++ b/AUTHORS.txt @@ -1,5 +1,5 @@ -Monte Carlo eXtreme (MCX) is written by Qianqian Fang. -Qianqian is currently an Associate Professor in the +Monte Carlo eXtreme (MCX) is primarily developed by Qianqian Fang. +Qianqian is currently Associate Professor in the Department of Bioengineering at Northeastern University, USA. Address: Dept. of Bioengineering @@ -11,3 +11,27 @@ Email: MCX Website : http://mcx.space MCX Wiki: http://mcx.space/wiki Source Code: http://github.com/fangq/mcx + + + +Other key contributors of MCX include + +* Shijie Yan +** Email: +** Shijie is a PhD student at Northeastern University, Dept of EECS, under the supervision of Dr. Fang. He has made the follow major contributions +*** split-voxel MC (SVMC) +*** modeling of polarized light +*** photon-sharing +*** MCX-Cloud server-side development +*** numerous bug fixes and code improvement + +* Matin Raayai Ardakani +** Email: +** Matin is a PhD student at Northeastern University, Dept of EECS, co-supervised by Dr. David Kaeli and Dr. Fang. He has made the follow major contributions +*** development of pmcx (Python binding for MCX) +*** development of Github action CI system + +* Yaoshen Yuan +** Email: +** Yaoshen was a PhD student at Northeastern University, Dept of EECS, under the supervision of Dr. Fang. He completed his PhD degree in 2020. He has made the follow major contributions +*** GPU based Adptive non-local-means (ANLM) filter \ No newline at end of file diff --git a/ChangeLog.txt b/ChangeLog.txt index 8e52e915..828f15ca 100644 --- a/ChangeLog.txt +++ b/ChangeLog.txt @@ -2,8 +2,89 @@ Major updates are marked with a "*" -== MCX v2022.10 (Heroic Hexagon - 1.9.7), FangQ == - +== MCX v2023 (Heroic Hadron - 2.0), FangQ == + 2023-08-07 [ac893cd] mcxplotvol: allow keeping x/y/z slice when switching between 4th dimension + 2023-08-07 [9aaba97] fix photon sharing 0 output issue in negative patterns + 2023-08-05 [da0beda] padding -0 instead of 0 when saving dref with mua_float medium + 2023-08-04 [82367f0] simplify dref/flux separation + 2023-08-04 [97fff3e] update zmatlib, use miniz, drop zlib for easy deployment + 2023-08-03 [4fbb4d6] bump pmcx version to 0.0.14 + 2023-08-03 [aaedf35] handle mirror bc in the reflection code + 2023-08-03*[198cd34] initial support of negative source and negative-patterns some test still fails, but feature is mostly working, need more work + 2023-07-27 [081c382] parse outputtype in json2mcx + 2023-07-21 [87167cb] simplify mua->0 approximation, drop high order term, #164 + 2023-07-21 [f063fd6] disable macos runner, macos no longer supports CUDA see https://github.com/actions/runner-images/discussions/7838 + 2023-07-21 [3067a26] fix incorrect handling of near-zero mus, fix #174, fix test + 2023-06-30 [ac06b05] CI: compress with upx on Linux + 2023-06-29 [527a5cc] add header, format with black, update action runners, #172 + 2023-05-21*[540931d] support trajectory-only mode with debuglevel=T + 2023-05-20*[0100212] mcxplotphotons: plotting photon tracks with patch and show weights + 2023-05-20 [615af1b] avoid recursion and segfault when resetting device + 2023-05-16 [c327541] add demo to build RF Jacobians using replay, by Pauliina Hirvi + 2023-05-05 [bd44f65] reformat pmcx python units with black + 2023-05-05 [c12310b] added cwdref function to compute CW diffuse reflectance + 2023-05-05 [0bd643e] added detweight function (using only numpy) to the utils.py in pmcx + 2023-05-04 [31c0fa3] fix incorrect stat.unitinmm output + 2023-04-29 [0c6b358] use svg vector graphs in mcxlab tutorial + 2023-04-29 [bed8f08] Update plots with GPU runtime outputs + 2023-04-29 [688ac78] Support mcxlabcl for non-GPU runtime on colab, add srctype tutorial + 2023-04-28 [4f53e12] add examples on getting trajectory data + 2023-04-27 [f271501] Update mcxlab jupyter notebook based tutorial + 2023-04-27*[be5a420] add jupyter-notebook based mcxlab tutorial + 2023-04-26 [eb68720] make static linking default on Windows + 2023-04-25 [e315dfe] fix incorrect comment regarding gaussian src, fix #165 + 2023-04-16 [b78c4e3] fix inaccurate output unit for energy output time + 2023-04-15 [2fd3594] accept jobs submitted from https://mcx.space/cloud + 2023-04-15*[7515611] fix mcxcloud job max duration bug, kill runtime>1min + 2023-04-13 [70b3b5e] Add photon replay demo codes for pmcx in jupyter notebook + 2023-04-13 [855aa40] pmcx: support photon replay, accept detphotons input + 2023-04-13 [8a49fe3] switch from cmake back to Makefile + 2023-04-01 [c2591aa] ask cmake to create Makefile + 2023-03-22 [67d1128] add pmcx jupyter notebook tutorial + 2023-03-22 [291adf5] allow mus=0, avoid unnecessary casting of scalars to double + 2023-03-17 [3a4f7ed] fix fluence for mua -> 0 + 2023-03-15 [46b4311] remove explicit dependency to GLScene in mcxstudio + 2023-03-10 [193158c] make volume rendering window available on main gui + 2023-03-10 [2d09e54] allow Open project dialog to also load nii and jnii files for rendering + 2023-03-09 [63a626d] fix progress bar stalling when setting cfg.issavedet to 3 + 2023-03-08 [8cab50f] add descriptions on how to start mcxstudio on an Mac, fix #162 + 2023-03-08 [da49503] allow early termination if -d 3 or cfg.issavedet=3 is set + 2023-03-04 [5d4d3c6] transition from openjdata.org to neurojson.org, fix #161 + 2023-03-02*[3c29fa5] mcxstudioL: loading and rendering jnifti based volume file + 2023-03-01 [b99f9a9] mcxstudioL: loading portable JSON/JNIFTI based MCX output data files + 2023-02-09 [32e3aef] fix RF replay in mcx binary, allow tweaking replay Jacobian for Born approx + 2023-02-05*[9abd3f3] adding additional native python pmcx functions + 2023-02-05 [63b80f4] add missing pmcx file + 2023-02-05 [e77ff2f] allow pmcx to use mixed binary extension and native function + 2023-02-01*[d9b2f2b] fix unmatched unit for RF replay, thanks to Pauliina Hirvi + 2023-02-01 [ce2a65c] add the l/length option in help info + 2023-02-01 [e67feed] support outputtype=length/l for saving total path lengths per voxel + 2023-01-25 [4344574] fix windows compilation error + 2023-01-25 [a7ce222] permit 3D plotting of DMMC output double-precision nii files + 2023-01-22 [cdabf68] automatically replace RCS keywords in pmcx action + 2023-01-22 [e527f4b] fix incomplete handling bc and isreflect setting combinations, fix #160 + 2023-01-20 [daa1dea] use standard CFLAGS and CPPFLAGS in compilation, remove --std99 error for g++ + 2023-01-11 [def38f6] Merge pull request #159 from matinraayai/master + 2023-01-11 [e077f86] Bump pmcx version to 0.0.7. + 2023-01-10 [7af2ea2] bump pmcx version to 0.0.6 + 2023-01-10 [820ce88] build macos binary wheels + 2023-01-09 [4f969d1] Removed the macOS builder VM. + 2023-01-09 [dd47cda] Updated README.md for pmcx. + 2023-01-09 [82ef430] Final version. + 2022-12-08 [eb9322f] Added Windows Wheel building job + fixed compilation errors for windows. + 2022-11-18 [d5a9beb] Update build_linux_manywheel.yml + 2022-11-18 [816c55f] Added Github workflow. + 2022-10-15 [084ffc1] update cmake file and remove zmat from pymcx and mex + 2022-10-14 [04000e2] remove zmatlib and ubj as dependency to mex and oct + 2022-10-14 [d033520] fix negative respin number bug + 2022-10-13 [ec4a29d] update version strings + 2022-10-13 [a3fe4ce] remove warning on replay output + 2022-10-10 [660dd31] update three.js to r145, fix volume render, fix thumbnail + +== MCX v2022.10 (only released to MCX'23 workshop participants), FangQ == + + 2022-10-08 [eaedca7] update installer to 2022.10 + 2022-10-08 [c31a0e2] update mcx version number to v2022.10 2022-10-05 [dc42951] prevent nan where log(rand) is calculated 2022-10-05 [63ffc1e] fix nan in detected photon data when using hyperboloid src, see https://groups.google.com/g/mcx-users/c/vyfHbzEO-0M/m/JzlpEZ3TBwAJ 2022-09-07 [e281f3e] allow to preview continuously varying medium (4D cfg.vol) diff --git a/LICENSE.txt b/LICENSE.txt index 6ab86c38..500d6d22 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -2,7 +2,7 @@ = Monte Carlo eXtreme (MCX) -- CUDA = ============================================================= -Copyright (c) 2010-2021 Qianqian Fang +Copyright (c) 2010-2023 Qianqian Fang ============================================================= diff --git a/Makefile b/Makefile index 58e3a5c4..748473b3 100644 --- a/Makefile +++ b/Makefile @@ -5,7 +5,7 @@ ############################################################ PKGNAME=mcx -VERSION=1.9.7 +VERSION=2.0.0 SOURCE=src GUI=mcxstudio diff --git a/NOTICE.txt b/NOTICE.txt index 02ab2d51..ea93de16 100644 --- a/NOTICE.txt +++ b/NOTICE.txt @@ -1,15 +1,15 @@ ============================================================= Monte Carlo eXtreme (MCX) Suite - version 2022.10 + version 2023 ============================================================= -Copyright (c) 2010-2022 Qianqian Fang +Copyright (c) 2010-2023 Qianqian Fang - Computational Optics & Translational Imaging (COTI) Lab (http://fanglab.org) - Department of Bioengineering, Northeastern University - 360 Huntington Ave, ISEC 206, Boston, MA 02115, USA - Website: http://mcx.space -- Github: http://github.com/mcextreme/ +- Github: https://github.com/mcx/ ============================================================= :: Acknowledgement: @@ -94,6 +94,10 @@ cite the relevant papers in your publications. === General MC algorithm === +[Hirvi2023] Hirvi P, Kuutela T, Fang Q, Hannukainen A, Hyvonen N, Nissilä I. Effects of atlas-based anatomy on modelled light transport in the neonatal head. Phys Med Biol. 2023 May 11. doi: 10.1088/1361-6560/acd48c. PMID: 37167982. +*Summary: RF replay and neonatal brain atlas +*Download: https://doi.org/10.1088/1361-6560/acd48c + [RaayaiArdakani2022] Matin Raayai Ardakani, Leiming Yu, David R. Kaeli, Qianqian Fang, "Framework for Denoising Monte Carlo Photon Transport Simulations Using Deep Learning," J Biomed Opt. 2022 May;27(8):083019. doi: 10.1117/1.JBO.27.8.083019 *Summary: DL-based MC denoising *Download: https://doi.org/10.1117/1.jbo.27.8.083019 diff --git a/README.md b/README.md index eda4023d..1fdc3970 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ Monte Carlo eXtreme (MCX) - CUDA Edition - Author: Qianqian Fang (q.fang at neu.edu) - License: GNU General Public License version 3 (GPLv3) -- Version: 1.9.7 (v2022.10, Heroic Hexagon) +- Version: 2.0 (v2023, Heroic Hadron) - Website: [![Build Status](https://travis-ci.com/fangq/mcx.svg?branch=master)](https://travis-ci.com/fangq/mcx) @@ -38,46 +38,138 @@ Table of Content: What's New ------------- -MCX v2022.10 introduces a major new feature - split-voxel MC (SVMC), published in -Biomedical Optics Express recently by Shijie Yan and Qianqian Fang, see +MCX v2023 is a milestone release since v2020 released 3 years ago. It contains all +the new features introduced in the two previous unofficial releases, v2022.10 and v2021.2, +along with extensive continuous integration (CI) development and numerous bug fixes. + +Specifically, MCX v2023 officially ships a major new feature - split-voxel MC (SVMC), +published in Biomedical Optics Express by Shijie Yan and Qianqian Fang, see [Yan2020](https://www.osapublishing.org/boe/abstract.cfm?uri=boe-11-11-6262) for details. Shortly, SVMC provides a level of accuracy close to mesh-based MC (MMC) in modeling curved boundaries but it is 4x to 6x faster than MMC. Several demo scripts of SVMC -can be found in the MCXLAB package under examples/demo_svmc_\*. In addition, MCX v2022.10 -supports GPU-based polarized light simulation, see our JBO paper -[Yan2022](https://doi.org/10.1117/1.JBO.27.8.083015). This release also includes -both the web-client and server scripts for MCX Cloud - an in-browser MC simulator -as we reported in [Fang2022](https://doi.org/10.1117/1.JBO.27.8.083008). Moreover, MCX -v2022.10 provides an official pymcx module to run stream-lined MCX simulations in -Python, offering mcxlab-like interface. +can be found in the MCXLAB package under examples/demo_svmc_\*. In addition, MCX v2023 +supports **GPU-based polarized light simulation**, see our JBO paper +[Yan2022](https://doi.org/10.1117/1.JBO.27.8.083015). Moreover, an **"RF replay"** +algorithm was implemented by Pauliina Hirvi et al. to create frequency-domain (RF) +Jacobians for both amplitude and phase components. Please read the details in +[Hirvi2023](https://iopscience.iop.org/article/10.1088/1361-6560/acd48c). This release +also includes both the web-client and server scripts for MCX Cloud - an in-browser MC +simulator as we reported in [Fang2022](https://doi.org/10.1117/1.JBO.27.8.083008). Lastly, MCX +v2023 provides an official Python mcx module (**pmcx**) to run stream-lined MCX simulations +in Python, offering mcxlab-like interface. In summary, v2023 is packed with exciting updates: - Introduced Split voxel MC (SVMC) to accurately model curved boundaries - GPU polarized light modeling (Stokes) with 900x speedup +- RF replay to build frequency-domain Jacobians for amplitude and phase - Web-based MCX Cloud platform including web-client and server scripts - pymcx - an mcxlab-like Python module for running MCX simulations in Python - Added Debian/Ubuntu packages for easy installation - Added a unified command line interface, photon, to call mcx/mcxcl/mmc - Fine-tuned Windows installer -- Support CMake in Travis-CI automation +- Extensively developed Github Action for automated building and packaging of mcx A detailed list of updates is summarized below (key features marked with “\*”): +Updates since v2022.10: + +- 2023-08-07 [ac893cd] \* mcxplotvol: allow keeping x/y/z slice when switching between 4th dimension +- 2023-08-07 [9aaba97] fix photon sharing 0 output issue in negative patterns +- 2023-08-05 [da0beda] padding -0 instead of 0 when saving dref with mua_float medium +- 2023-08-04 [82367f0] simplify dref/flux separation +- 2023-08-04 [97fff3e] update zmatlib, use miniz, drop zlib for easy deployment +- 2023-08-03 [4fbb4d6] bump pmcx version to 0.0.14 +- 2023-08-03 [aaedf35] handle mirror bc in the reflection code +- 2023-08-03 [198cd34] \* initial support of negative source and negative-patterns some test still fails, but feature is mostly working, need more work +- 2023-07-27 [081c382] parse outputtype in json2mcx +- 2023-07-21 [87167cb] simplify mua->0 approximation, drop high order term, #164 +- 2023-07-21 [f063fd6] disable macos runner, macos no longer supports CUDA see https://github.com/actions/runner-images/discussions/7838 +- 2023-07-21 [3067a26] fix incorrect handling of near-zero mus, fix #174, fix test +- 2023-06-30 [ac06b05] CI: compress with upx on Linux +- 2023-06-29 [527a5cc] add header, format with black, update action runners, #172 +- 2023-05-21 [540931d] \* support trajectory-only mode with debuglevel=T +- 2023-05-20 [0100212] \* mcxplotphotons: plotting photon tracks with patch and show weights +- 2023-05-20 [615af1b] avoid recursion and segfault when resetting device +- 2023-05-16 [c327541] add demo to build RF Jacobians using replay, by Pauliina Hirvi +- 2023-05-05 [bd44f65] reformat pmcx python units with black +- 2023-05-05 [c12310b] added cwdref function to compute CW diffuse reflectance +- 2023-05-05 [0bd643e] added detweight function (using only numpy) to the utils.py in pmcx +- 2023-05-04 [31c0fa3] fix incorrect stat.unitinmm output +- 2023-04-29 [0c6b358] use svg vector graphs in mcxlab tutorial +- 2023-04-29 [bed8f08] Update plots with GPU runtime outputs +- 2023-04-29 [688ac78] Support mcxlabcl for non-GPU runtime on colab, add srctype tutorial +- 2023-04-28 [4f53e12] add examples on getting trajectory data +- 2023-04-27 [f271501] Update mcxlab jupyter notebook based tutorial +- 2023-04-27 [be5a420] \* add jupyter-notebook based mcxlab tutorial +- 2023-04-26 [eb68720] make static linking default on Windows +- 2023-04-25 [e315dfe] fix incorrect comment regarding gaussian src, fix #165 +- 2023-04-16 [b78c4e3] fix inaccurate output unit for energy output time +- 2023-04-15 [2fd3594] accept jobs submitted from https://mcx.space/cloud +- 2023-04-15 [7515611] \* fix mcxcloud job max duration bug, kill runtime>1min +- 2023-04-13 [70b3b5e] Add photon replay demo codes for pmcx in jupyter notebook +- 2023-04-13 [855aa40] pmcx: support photon replay, accept detphotons input +- 2023-04-13 [8a49fe3] switch from cmake back to Makefile +- 2023-04-01 [c2591aa] ask cmake to create Makefile +- 2023-03-22 [67d1128] add pmcx jupyter notebook tutorial +- 2023-03-22 [291adf5] allow mus=0, avoid unnecessary casting of scalars to double +- 2023-03-17 [3a4f7ed] fix fluence for mua -> 0 +- 2023-03-15 [46b4311] remove explicit dependency to GLScene in mcxstudio +- 2023-03-10 [193158c] make volume rendering window available on main gui +- 2023-03-10 [2d09e54] allow Open project dialog to also load nii and jnii files for rendering +- 2023-03-09 [63a626d] fix progress bar stalling when setting cfg.issavedet to 3 +- 2023-03-08 [8cab50f] add descriptions on how to start mcxstudio on an Mac, fix #162 +- 2023-03-08 [da49503] allow early termination if -d 3 or cfg.issavedet=3 is set +- 2023-03-04 [5d4d3c6] transition from openjdata.org to neurojson.org, fix #161 +- 2023-03-02 [3c29fa5] \* mcxstudioL: loading and rendering jnifti based volume file +- 2023-03-01 [b99f9a9] mcxstudioL: loading portable JSON/JNIFTI based MCX output data files +- 2023-02-09 [32e3aef] fix RF replay in mcx binary, allow tweaking replay Jacobian for Born approx +- 2023-02-05 [9abd3f3] \* adding additional native python pmcx functions +- 2023-02-05 [63b80f4] add missing pmcx file +- 2023-02-05 [e77ff2f] allow pmcx to use mixed binary extension and native function +- 2023-02-01 [d9b2f2b] \* fix unmatched unit for RF replay, thanks to Pauliina Hirvi +- 2023-02-01 [ce2a65c] add the l/length option in help info +- 2023-02-01 [e67feed] support outputtype=length/l for saving total path lengths per voxel +- 2023-01-25 [4344574] fix windows compilation error +- 2023-01-25 [a7ce222] permit 3D plotting of DMMC output double-precision nii files +- 2023-01-22 [cdabf68] automatically replace RCS keywords in pmcx action +- 2023-01-22 [e527f4b] fix incomplete handling bc and isreflect setting combinations, fix #160 +- 2023-01-20 [daa1dea] use standard CFLAGS and CPPFLAGS in compilation, remove --std99 error for g++ +- 2023-01-11 [def38f6] Merge pull request #159 from matinraayai/master +- 2023-01-11 [e077f86] Bump pmcx version to 0.0.7. +- 2023-01-10 [7af2ea2] bump pmcx version to 0.0.6 +- 2023-01-10 [820ce88] build macos binary wheels +- 2023-01-09 [4f969d1] Removed the macOS builder VM. +- 2023-01-09 [dd47cda] Updated README.md for pmcx. +- 2023-01-09 [82ef430] Final version. +- 2022-12-08 [eb9322f] Added Windows Wheel building job + fixed compilation errors for windows. +- 2022-11-18 [d5a9beb] Update build_linux_manywheel.yml +- 2022-11-18 [816c55f] Added Github workflow. +- 2022-10-15 [084ffc1] update cmake file and remove zmat from pymcx and mex +- 2022-10-14 [04000e2] remove zmatlib and ubj as dependency to mex and oct +- 2022-10-14 [d033520] fix negative respin number bug +- 2022-10-13 [ec4a29d] update version strings +- 2022-10-13 [a3fe4ce] remove warning on replay output +- 2022-10-10 [660dd31] update three.js to r145, fix volume render, fix thumbnail + +Updates since v2021.2: + +- 2022-10-08 [eaedca7] update installer to 2022.10 +- 2022-10-08 [c31a0e2] update mcx version number to v2022.10 - 2022-10-05 [dc42951] prevent nan where log(rand) is calculated - 2022-10-05 [63ffc1e] fix nan in detected photon data when using hyperboloid src, see https://groups.google.com/g/mcx-users/c/vyfHbzEO-0M/m/JzlpEZ3TBwAJ -- 2022-09-07 [e281f3e] allow to preview continuously varying medium (4D cfg.vol) +- 2022-09-07 [e281f3e] \* allow to preview continuously varying medium (4D cfg.vol) - 2022-08-19 [10330ef] fix windows compilation error - 2022-08-17 [bbb4425] prevent zero-valued mus creating nan, #133 - 2022-08-12 [51f42f5] fix mcxlab log printing caused by commit f3beb75a -- 2022-08-12 [7058785] Lambertian launch for all focusable sources when focal-length is -inf +- 2022-08-12 [7058785] \* Lambertian launch for all focusable sources when focal-length is -inf - 2022-07-28 [6d64c0b] fix incorrect flag for skipvoid - 2022-06-27 [3d4fb26] partially fix rf replay - 2022-06-04 [8af3631] fix line source - 2022-05-22 [149b1ef] make code compile on windows - 2022-05-20 [e87bb49] use consistent file naming convention, remove outdated units -- 2022-05-20 [45d84d3] complete reformat source code using astyle, always run make pretty before committing +- 2022-05-20 [45d84d3] \* complete reformat source code using astyle, always run make pretty before committing - 2022-05-20 [aff8ff0] add source code formatting option - 2022-05-20 [f3beb75] use MATLAB_MEX_FILE to determine container environment -- 2022-05-18 [1295024] fix incorrect trajectory id, fix #147 +- 2022-05-18 [1295024] \* fix incorrect trajectory id, fix #147 - 2022-05-18 [ccd2deb] fix macro condition - 2022-05-18 [6f4ee88] use MCX_CONTAINER and env macros to replace extra PYMCX_CONTAINER - 2022-05-16 [6fa1580] avoid using clear all and ~ in return value @@ -92,7 +184,7 @@ A detailed list of updates is summarized below (key features marked with “\* - 2022-05-15 [7df8938] Added better + more informative exception handling for pymcx. - 2022-05-15 [6a741e8] Changed reinterpret_casts to direct object construction + added the stat dict to the output dict + defined PYBIND11_DETAILED_ERROR_MESSAGES for easier debugging. - 2022-05-15 [e4547ba] add pybind11 as submodule to build pymcx -- 2022-05-13 [f8da832] fix cyclic bc demo and srctype demo error, svmc still not working +- 2022-05-13 [f8da832] \* fix cyclic bc demo and srctype demo error, svmc still not working - 2022-05-13 [4bd3974] report register counts on sm_60 using nvcc --ptxas-options=-v - 2022-05-13 [e8f6a2d] fix cfg.unitinmm does not exist error - 2022-05-13 [447975f] complete dda ray-marching, cube60 benchmark gain 40% speed, others are similar @@ -118,7 +210,7 @@ A detailed list of updates is summarized below (key features marked with “\* - 2022-03-25 [04f1565] Add optimized isosurface rendering; add the ability to view cross-sectional slices of geometry - 2022-03-23 [200decb] Remove testing files - 2022-03-23 [e434553] Remove unnecessary variable -- 2022-03-22 [ebd5bee] update ubj to support BJData Draft 2, add JNIfTI _DataInfo_, fix #142 +- 2022-03-22 [ebd5bee] \* update ubj to support BJData Draft 2, add JNIfTI _DataInfo_, fix #142 - 2022-03-21 [6de0855] Enable event-based repainting; re-add shader refinement, remove animation frame bugs; remove unnecessary shader branches and discards - 2022-03-19 [7ef65a8] Added event-based repainting; shader optimizations - 2022-03-05 [a93f6fa] save user info in local storage to avoid retyping @@ -147,7 +239,7 @@ A detailed list of updates is summarized below (key features marked with “\* - 2022-01-25 [d6e2b9e] NaN value in mua_float and muamus_float signifies a 0-value voxel - 2022-01-24 [c9f2ad9] force threejs version to avoid breaking update in R136 - 2022-01-14 [51483eb] add template specialization for polarized mode -- 2022-01-12 [3487dfe] update the example for the polarized MCX +- 2022-01-12 [3487dfe] \* update the example for the polarized MCX - 2021-12-15 [b9e046a] fix out of bounds error due to limited precision of R_PI - 2021-12-15 [3b10265] fix the built-in example to match the update in e5dfd78f28f31d710e02206cb2835aabcd4d5508 - 2021-12-15 [dbe17af] no Stoke vector output for unpolarized MCX simulation @@ -163,7 +255,7 @@ A detailed list of updates is summarized below (key features marked with “\* - 2021-11-04 [2585471] making svmc matlab demos compatible with Octave 5 - 2021-11-03 [5976811] replace matlab-only function with more portable code - 2021-11-01 [37e121c] update preprint version url -- 2021-10-21 [7a77bf7] display rendering frame rate +- 2021-10-21 [7a77bf7] \* display rendering frame rate - 2021-10-18 [99592c1] fix: #114 improve robustness to unknown boundry conditions - 2021-10-14 [1aa2922] feat: Add one-sheet hyperboloid gaussian beam - 2021-10-07 [86d56c2] feat: output prop. along with det. photon profile @@ -218,11 +310,11 @@ A detailed list of updates is summarized below (key features marked with “\* - 2021-06-03 [1c29578] fix regression - 2021-06-03 [3aedee6] add LengthUnit, MediaFormat in schema, support number and string for DebugFlag/SaveDataMask - 2021-06-03 [64c5dd0] fix unnecessary shared memory allocation related to invcdf -- 2021-06-03 [ebf1ea1] support user-defined phase functions via cfg.invcdf, close #13 +- 2021-06-03 [ebf1ea1] \* support user-defined phase functions via cfg.invcdf, close #13 - 2021-06-03 [0731511] revert back to no restarting policy so that overtime jobs can be killed - 2021-06-02 [4d2a891] process cache,fix fullname,fix job status,fix server-side limit,kill overtime job - 2021-06-02 [a08d676] update the skinvessel benchmark -- 2021-06-02 [168db14] feat: save Mie function outputs mus, g to a file +- 2021-06-02 [168db14] \* feat: save Mie function outputs mus, g to a file - 2021-06-02 [57a44c5] feat: Add anisotropy g as an output of Mie func. - 2021-06-02 [7387394] finally fix crossdomain post, change jsonp to json,test simu lib edit - 2021-06-01 [95c6e1d] test:use default BC for all polarizedMC benchmarks @@ -241,7 +333,7 @@ A detailed list of updates is summarized below (key features marked with “\* - 2021-05-30 [55bb1ea] initial drag and drop support, not working - 2021-05-30 [fc9ca38] add meta headers, other minor adjustments - 2021-05-29 [96cf071] support embedding src pattern in the all-in-one json/jdata file -- 2021-05-28 [450462c] Add document for functions used in polarized MC +- 2021-05-28 [450462c] \* Add document for functions used in polarized MC - 2021-05-28 [cbc3340] Optimize Stokes vector computation - 2021-05-28 [9bd2ce0] Remove redundant code in preprocessing - 2021-05-28 [06a9c6b] fix: resolve nan results due to numerical error @@ -249,17 +341,17 @@ A detailed list of updates is summarized below (key features marked with “\* - 2021-05-28 [9195141] Add an example to show polarized photon simulation - 2021-05-27 [2b87275] fix: rewrite code for better readability - 2021-05-26 [d836c81] fix: correct formula for stokes parameter update -- 2021-05-25 [105d5a9] feat: Add stokes parameter output in MCXLAB -- 2021-05-25 [87d8847] feat: add polarized photon simulation +- 2021-05-25 [105d5a9] \* feat: Add stokes parameter output in MCXLAB +- 2021-05-25 [87d8847] \* feat: add polarized photon simulation - 2021-05-23 [d398cc9] add simulation restrictions for initial public testing of mcx cloud - 2021-05-23 [26536d3] feat: add preprocessing for polarized MC in mcxlab -- 2021-05-22 [f0975c5] support ring/annulus shaped source via disk source -- 2021-05-21 [6ed9727] support svmc in command line;add svmc example +- 2021-05-22 [f0975c5] \* support ring/annulus shaped source via disk source +- 2021-05-21 [6ed9727] \* support svmc in command line;add svmc example - 2021-05-21 [3d0a793] reading 8-byte svmc volume format from input file - 2021-05-20 [4010d99] move svmc repacking to mcx_preprocess - 2021-05-20 [3214c1b] remove duplicated preprocessing codes in mcx and mcxlab,fix detbc bug in command line - 2021-05-20 [54b0602] run batch of jobs in each call to fill all GPU devices -- 2021-05-20 [de9850c] add -K short option and svmc mediatype +- 2021-05-20 [de9850c] \* add -K short option and svmc mediatype - 2021-05-19 [660a8b8] relocate db and workspace folder to non www-data accessible paths - 2021-05-19 [64f3008] update acknowledgement list - 2021-05-19 [c168a87] can update thumbnail, add credit links @@ -267,7 +359,7 @@ A detailed list of updates is summarized below (key features marked with “\* - 2021-05-15 [cef630b] save volume in jdata format by default - 2021-05-15 [c50f871] define Frequency in json file instead of Omega - 2021-05-15 [b4e7b57] initial support RF mua Jacobian in replay, thx Ilkka Nissilä, formula based on Juha Heiskala PhD thesis p45 -- 2021-05-10 [073b168] mcxcloud initial preview at JBO hot-topics +- 2021-05-10 [073b168] \* mcxcloud initial preview at JBO hot-topics - 2021-05-05 [5732e6a] update front and backends - 2021-05-01 [ee3f88d] update and rename mcxcloudd and mcxserver.cgi - 2021-05-01 [eac952d] fix cylinder schema, add footer @@ -287,16 +379,19 @@ A detailed list of updates is summarized below (key features marked with “\* - 2021-03-25 [9b0cf95] fine tune fonts, add big tab initial screen, add svg background, add funding info - 2021-03-25 [77f8f7a] add three.js for 3d preview - 2021-03-24 [4274c77] rename mcxcloud.txt to mcxcloud -- 2021-03-24 [dc25a87] add mcx cloud service server and client files, partially working +- 2021-03-24 [dc25a87] \* add mcx cloud service server and client files, partially working - 2021-03-22 [f9bc07c] use tabs in mcxone, add jquery by default - 2021-03-18 [d8b88e1] fix unwanted double-precision math functions - 2021-03-11 [f6ce5bd] update variable and function name to follow the convention - 2021-03-11 [ca2ce60] add example: comparison of surface diffuse reflectance between MC and Diffusion - 2021-03-05 [bcbb324] change window sizes using 96dpi default setting - 2021-03-05 [5c8d27f] fix Name shape object schema -- 2021-03-03 [02add69] MCX json schema and json editor are working, added more Shapes objects +- 2021-03-03 [02add69] \* MCX json schema and json editor are working, added more Shapes objects - 2021-03-01 [940d725] wrapping up json input import feature in mcxstudio - 2021-02-28 [64d629c] parse src/detector, media and shape + +Updates since v2020: + - 2021-02-27 [a3b8457] \* open/import JSON input file in MCX Studio - 2021-01-07 [9811c83] reorder the input data layout to match the change in preprocessing - 2020-10-22 [991910e] add function comment and revert unnecessary changes @@ -349,7 +444,7 @@ A detailed list of updates is summarized below (key features marked with “\* - 2020-08-24 [782b4a3] massive update of documentation - 2020-08-24 [041e386] massive update to README to describe all output formats -Between 2020 and 2022, three new journal papers have been published as the +Between 2020 and 2023, seven new journal papers have been published as the result of this project, including [Yan2020]. Please see the full list at http://mcx.space/#publication @@ -362,17 +457,58 @@ http://mcx.space/#publication * [Yan2022] Shijie Yan, Steven L. Jacques, Jessica C. Ramella-Roman, Qianqian Fang, "Graphics processing unit-accelerated Monte Carlo simulation of polarized light in complex three-dimensional media," J. of Biomedical Optics, 27(8), 083015 (2022) +* [Zhang2022] Yuxuang Zhang, Qianqian Fang, "BlenderPhotonics – an integrated open-source + software environment for three-dimensional meshing and photon simulations in complex + tissues," J. of Biomedical Optics, 27(8), 083014 (2022) +* [RaayaiArdakani2022] Matin Raayai Ardakani, Leiming Yu, David R. Kaeli, Qianqian Fang, + "Framework for Denoising Monte Carlo Photon Transport Simulations Using Deep Learning," + J Biomed Opt. 2022 May;27(8):083019. doi: 10.1117/1.JBO.27.8.083019 +* [Yuan2021] Yaoshen Yuan, Shijie Yan, and Qianqian Fang*, "Light transport modeling in + highly complex tissues using the implicit mesh-based Monte Carlo algorithm," + Biomed. Optics Express, 12(1), 147-161, (2021) +* [Hirvi2023] Hirvi P, Kuutela T, Fang Q, Hannukainen A, Hyvonen N, Nissilä I. Effects of + atlas-based anatomy on modelled light transport in the neonatal head. Phys Med Biol. + 2023 May 11. doi: 10.1088/1361-6560/acd48c. PMID: 37167982. Introduction --------------- -Monte Carlo eXtreme (MCX) is a fast photon transport simulation software for 3D -heterogeneous turbid media. By taking advantage of the massively parallel -threads and extremely low memory latency in a modern graphics processing unit -(GPU), MCX is capable of performing Monte Carlo (MC) photon simulations at a -blazing speed, typically hundreds to a thousand times faster than a fully -optimized CPU-based MC implementation. +Monte Carlo eXtreme (MCX) is a fast physically-accurate photon simulation +software for 3D heterogeneous complex media. By taking advantage of +the massively parallel threads and extremely low memory latency in a +modern graphics processing unit (GPU), this program is able to perform Monte +Carlo (MC) simulations at a blazing speed, typically hundreds to +a thousand times faster than a single-threaded CPU-based MC implementation. + +MCX is written in C and NVIDIA CUDA. It only be executed on NVIDIA GPUs. +If you want to run hardware-accelerated MCX simulations on AMD/Intel GPUs +or CPUs, please download MCX-CL (MCX for OpenCL), which is written in OpenCL. +MCX and MCX-CL are highly compatible. + +Due to the nature of the underlying MC algorithms, MCX and MCX-CL are +ray-tracing/ray-casting software under-the-hood. Compared to commonly +seen ray-tracing libraries used in computer graphics or gaming +engines, MCX-CL and MCX have many unique characteristics. The most +important difference is that MCX/MCX-CL are rigorously based on physical +laws. They are numerical solvers to the underlying radiative transfer equation +(RTE) and their solutions have been validated across many publications +using optical instruments and experimental measurements. In comparison, +most graphics-oriented ray-tracers have to make many approximations in +order to achieve fast rendering, enable to provide quantitatively accurate +light simulation results. Because of this, MCX/MCX-CL have been extensively +used by biophotonics research communities to obtain reference solutions and +guide the development of novel medical imaging systems or clinical +applications. Additionally, MCX/MCX-CL are volumetric ray-tracers; they +traverse photon-rays throughout complex 3-D domains and computes physically +meaningful quantities such as spatially resolved fluence, flux, diffuse +reflectance/transmittance, energy deposition, partial pathlengths, +among many others. In contrast, most graphics ray-tracing engines +only trace the RGB color of a ray and render it on a flat 2-D screen. +In other words, MCX/MCX-CL gives physically accurate 3-D light distributions +while graphics ray-tracers focus on 2-D rendering of a scene at the camera. +Nonetheless, they share many similarities, such as ray-marching computation, +GPU acceleration, scattering/absorption handling etc. The algorithm of this software is detailed in the References [Fang2009,Yu2018,Yan2020]. A short summary of the main features includes: @@ -390,9 +526,10 @@ The algorithm of this software is detailed in the References - native Matlab/Octave support for high usability - flexible JSON interface for future extensions - multi-GPU support +- advanced features: photon-replay, photon-sharing, and more This software can be used on Windows, Linux and Mac OS. MCX is written in C/CUDA -and requires an NVIDIA GPU (support for AMD/Intel CPUs/GPUs via ROCm is still +and requires NVIDIA GPUs (support for AMD/Intel CPUs/GPUs via ROCm is still under development). A more portable OpenCL implementation of MCX, i.e. MCXCL, was announced on July, 2012 and supports almost all NVIDIA/AMD/Intel CPU and GPU models. If your hardware does not support CUDA, please download MCXCL from the @@ -480,7 +617,7 @@ supported parameters, as shown below: ``` ############################################################################### # Monte Carlo eXtreme (MCX) -- CUDA # -# Copyright (c) 2009-2022 Qianqian Fang # +# Copyright (c) 2009-2023 Qianqian Fang # # http://mcx.space/ # # # # Computational Optics & Translational Imaging (COTI) Lab- http://fanglab.org # @@ -488,7 +625,7 @@ supported parameters, as shown below: ############################################################################### # The MCX Project is funded by the NIH/NIGMS under grant R01-GM114365 # ############################################################################### -$Rev::dc4295$v2022.10$Date::Qianqian Fang $ by $Author::Qianqian Fang$ +$Rev::e02c77$ v2023 $Date::2023-08-12 14:16:55 -04$ by $Author::Qianqian Fang$ ############################################################################### usage: mcx ... @@ -589,11 +726,14 @@ where possible parameters include (the first value in [*|*] is the default) == Output options == -s sessionid (--session) a string to label all output file names - -O [X|XFEJPMR] (--outputtype) X - output flux, F - fluence, E - energy deposit + -O [X|XFEJPMRL](--outputtype) X - output flux, F - fluence, E - energy deposit /case insensitive/ J - Jacobian (replay mode), P - scattering, event counts at each voxel (replay mode only) M - momentum transfer; R - RF/FD Jacobian - -d [1|0] (--savedet) 1 to save photon info at detectors; 0 not save + L - total pathlength + -d [1|0-3] (--savedet) 1 to save photon info at detectors; 0 not save + 2 reserved, 3 terminate simulation when detected + photon buffer is filled -w [DP|DSPMXVW](--savedetflag)a string controlling detected photon data fields /case insensitive/ 1 D output detector ID (1) 2 S output partial scat. even counts (#media) @@ -618,17 +758,17 @@ where possible parameters include (the first value in [*|*] is the default) -S [1|0] (--save2pt) 1 to save the flux field; 0 do not save -F [mc2|...] (--outputformat) fluence data output format: mc2 - MCX mc2 format (binary 32bit float) - jnii - JNIfTI format (http://openjdata.org) - bnii - Binary JNIfTI (http://openjdata.org) + jnii - JNIfTI format (https://neurojson.org) + bnii - Binary JNIfTI (https://neurojson.org) nii - NIfTI format hdr - Analyze 7.5 hdr/img format tx3 - GL texture data for rendering (GL_RGBA32F) the bnii/jnii formats support compression (-Z) and generate small files load jnii (JSON) and bnii (UBJSON) files using below lightweight libs: - MATLAB/Octave: JNIfTI toolbox https://github.com/fangq/jnifti, - MATLAB/Octave: JSONLab toolbox https://github.com/fangq/jsonlab, + MATLAB/Octave: JNIfTI toolbox https://github.com/NeuroJSON/jnifti, + MATLAB/Octave: JSONLab toolbox https://github.com/NeuroJSON/jsonlab, Python: PyJData: https://pypi.org/project/jdata - JavaScript: JSData: https://github.com/fangq/jsdata + JavaScript: JSData: https://github.com/NeuroJSON/jsdata -Z [zlib|...] (--zip) set compression method if -F jnii or --dumpjson is used (when saving data to JSON/JNIfTI format) 0 zlib: zip format (moderate compression,fast) @@ -639,7 +779,7 @@ where possible parameters include (the first value in [*|*] is the default) 5 lz4: LZ4 format (low compression,extrem. fast) 6 lz4hc: LZ4HC format (moderate compression,fast) --dumpjson [-,0,1,'file.json'] export all settings, including volume data using - JSON/JData (http://openjdata.org) format for + JSON/JData (https://neurojson.org) format for easy sharing; can be reused using -f if followed by nothing or '-', mcx will print the JSON to the console; write to a file if file @@ -656,9 +796,10 @@ where possible parameters include (the first value in [*|*] is the default) == Debug options == -D [0|int] (--debug) print debug information (you can use an integer or or a string by combining the following flags) - -D [''|RMP] 1 R debug RNG + -D [''|RMPT] 1 R debug RNG /case insensitive/ 2 M store photon trajectory info 4 P print progress bar + 8 T save trajectory data only, disable flux/detp combine multiple items by using a string, or add selected numbers together == Additional options == @@ -1220,17 +1361,34 @@ seed data and saved as a JSON-compatible .jdat file. The overall structure of th Using MCXLAB in MATLAB and Octave ------------------------------------ -MCXLAB is the native MEX version of MCX for Matlab and GNU Octave. It includes +MCXLAB is the native MEX version of MCX for MATLAB and GNU Octave. It includes the entire MCX code in a MEX function which can be called directly inside -Matlab or Octave. The input and output files in MCX are replaced by convenient +MATLAB or Octave. The input and output files in MCX are replaced by convenient in-memory struct variables in MCXLAB, thus, making it much easier to use and -interact. Matlab/Octave also provides convenient plotting and data analysis -functions. With MCXLAB, your analysis can be streamlined and speed- up without +interact. MATLAB/Octave also provides convenient plotting and data analysis +functions. With MCXLAB, your analysis can be streamlined and simplified without involving disk files. Please read the mcxlab/README.txt file for more details on how to install and use MCXLAB. +Please also browse this interactive [Jupyter Notebook based MCXLAB tutorial](https://colab.research.google.com/github/fangq/mcx/blob/master/mcxlab/tutorials/mcxlab_getting_started.ipynb) +to see a suite of examples showing the key functionalities of MCXLAB (using GNU Octave). + + +Using PMCX in Python +------------------------------------ + +PMCX is the native binary binding of MCX for Python 3.6 or newer. Similar to +MCXLAB, PMCX can run GPU-based simulations inside Python environment with +efficient in-memory inputs and outputs. + +Please read the pmcx/README.txt file for more details on how to install and +use PMCX. + +Please also browse this interactive [Jupyter Notebook based PMCX tutorial](https://colab.research.google.com/github/fangq/mcx/blob/master/pmcx/tutorials/pmcx_getting_started.ipynb) +to see a suite of examples showing the key functionalities of PMCX. + Using MCX Studio GUI ----------------------- diff --git a/README.txt b/README.txt index 16109281..959e109d 100644 --- a/README.txt +++ b/README.txt @@ -5,7 +5,7 @@ *Author: Qianqian Fang *License: GNU General Public License version 3 (GPLv3) -*Version: 1.9.7 (v2022.10, Heroic Hexagon) +*Version: 2.0 (v2023, Heroic Hadron) *Website: http://mcx.space --------------------------------------------------------------------- @@ -18,30 +18,121 @@ Table of Content: == # What's New == -MCX v2022.10 introduces a major new feature - split-voxel MC (SVMC), published in -Biomedical Optics Express recently by Shijie Yan and Qianqian Fang, see -[Yan2020](https://www.osapublishing.org/boe/abstract.cfm?uri=boe-11-11-6262) for details. +MCX v2023 is a milestone release since v2020 released 3 years ago. It contains all +the new features introduced in the two previous unofficial releases, v2022.10 and v2021.2, +along with extensive continuous integration (CI) development and numerous bug fixes. + +Specifically, MCX v2023 officially ships a major new feature - split-voxel MC (SVMC), +published in Biomedical Optics Express by Shijie Yan and Qianqian Fang, see +[https://www.osapublishing.org/boe/abstract.cfm?uri=boe-11-11-6262 Yan2020] for details. Shortly, SVMC provides a level of accuracy close to mesh-based MC (MMC) in modeling curved boundaries but it is 4x to 6x faster than MMC. Several demo scripts of SVMC -can be found in the MCXLAB package under examples/demo_svmc_\*. In addition, MCX v2022.10 -supports GPU-based polarized light simulation, see our JBO paper -[Yan2022](https://doi.org/10.1117/1.JBO.27.8.083015). This release also includes -both the web-client and server scripts for MCX Cloud - an in-browser MC simulator -as we reported in [Fang2022](https://doi.org/10.1117/1.JBO.27.8.083008). Moreover, MCX -v2022.10 provides an official pymcx module to run stream-lined MCX simulations in -Python, offering mcxlab-like interface. +can be found in the MCXLAB package under examples/demo_svmc_*. In addition, MCX v2023 +supports '''GPU-based polarized light simulation''', see our JBO paper +[https://doi.org/10.1117/1.JBO.27.8.083015 Yan2022]. Moreover, an '''"RF replay"''' +algorithm was implemented by Pauliina Hirvi et al. to create frequency-domain (RF) +Jacobians for both amplitude and phase components. Please read the details in +[Hirvi2023](https://iopscience.iop.org/article/10.1088/1361-6560/acd48c). This release +also includes both the web-client and server scripts for MCX Cloud - an in-browser MC +simulator as we reported in [https://doi.org/10.1117/1.JBO.27.8.083008 Fang2022]. Lastly, MCX +v2023 provides an official Python mcx module ('''pmcx''') to run stream-lined MCX simulations +in Python, offering mcxlab-like interface. In summary, v2023 is packed with exciting updates: * Introduced Split voxel MC (SVMC) to accurately model curved boundaries * GPU polarized light modeling (Stokes) with 900x speedup +- RF replay to build frequency-domain Jacobians for amplitude and phase * Web-based MCX Cloud platform including web-client and server scripts * pymcx - an mcxlab-like Python module for running MCX simulations in Python * Added Debian/Ubuntu packages for easy installation * Added a unified command line interface, photon, to call mcx/mcxcl/mmc * Fine-tuned Windows installer -* Support CMake in Travis-CI automation +- Extensively developed Github Action for automated building and packaging of mcx A detailed list of updates is summarized below (key features marked with “*”): +Updates since v2022.10: +* 2023-08-07 [ac893cd] * mcxplotvol: allow keeping x/y/z slice when switching between 4th dimension +* 2023-08-07 [9aaba97] fix photon sharing 0 output issue in negative patterns +* 2023-08-05 [da0beda] padding -0 instead of 0 when saving dref with mua_float medium +* 2023-08-04 [82367f0] simplify dref/flux separation +* 2023-08-04 [97fff3e] update zmatlib, use miniz, drop zlib for easy deployment +* 2023-08-03 [4fbb4d6] bump pmcx version to 0.0.14 +* 2023-08-03 [aaedf35] handle mirror bc in the reflection code +* 2023-08-03 [198cd34] * initial support of negative source and negative-patterns some test still fails, but feature is mostly working, need more work +* 2023-07-27 [081c382] parse outputtype in json2mcx +* 2023-07-21 [87167cb] simplify mua->0 approximation, drop high order term, #164 +* 2023-07-21 [f063fd6] disable macos runner, macos no longer supports CUDA see https://github.com/actions/runner-images/discussions/7838 +* 2023-07-21 [3067a26] fix incorrect handling of near-zero mus, fix #174, fix test +* 2023-06-30 [ac06b05] CI: compress with upx on Linux +* 2023-06-29 [527a5cc] add header, format with black, update action runners, #172 +* 2023-05-21 [540931d] * support trajectory-only mode with debuglevel=T +* 2023-05-20 [0100212] * mcxplotphotons: plotting photon tracks with patch and show weights +* 2023-05-20 [615af1b] avoid recursion and segfault when resetting device +* 2023-05-16 [c327541] add demo to build RF Jacobians using replay, by Pauliina Hirvi +* 2023-05-05 [bd44f65] reformat pmcx python units with black +* 2023-05-05 [c12310b] added cwdref function to compute CW diffuse reflectance +* 2023-05-05 [0bd643e] added detweight function (using only numpy) to the utils.py in pmcx +* 2023-05-04 [31c0fa3] fix incorrect stat.unitinmm output +* 2023-04-29 [0c6b358] use svg vector graphs in mcxlab tutorial +* 2023-04-29 [bed8f08] Update plots with GPU runtime outputs +* 2023-04-29 [688ac78] Support mcxlabcl for non-GPU runtime on colab, add srctype tutorial +* 2023-04-28 [4f53e12] add examples on getting trajectory data +* 2023-04-27 [f271501] Update mcxlab jupyter notebook based tutorial +* 2023-04-27 [be5a420] * add jupyter-notebook based mcxlab tutorial +* 2023-04-26 [eb68720] make static linking default on Windows +* 2023-04-25 [e315dfe] fix incorrect comment regarding gaussian src, fix #165 +* 2023-04-16 [b78c4e3] fix inaccurate output unit for energy output time +* 2023-04-15 [2fd3594] accept jobs submitted from https://mcx.space/cloud +* 2023-04-15 [7515611] * fix mcxcloud job max duration bug, kill runtime>1min +* 2023-04-13 [70b3b5e] Add photon replay demo codes for pmcx in jupyter notebook +* 2023-04-13 [855aa40] pmcx: support photon replay, accept detphotons input +* 2023-04-13 [8a49fe3] switch from cmake back to Makefile +* 2023-04-01 [c2591aa] ask cmake to create Makefile +* 2023-03-22 [67d1128] add pmcx jupyter notebook tutorial +* 2023-03-22 [291adf5] allow mus=0, avoid unnecessary casting of scalars to double +* 2023-03-17 [3a4f7ed] fix fluence for mua -> 0 +* 2023-03-15 [46b4311] remove explicit dependency to GLScene in mcxstudio +* 2023-03-10 [193158c] make volume rendering window available on main gui +* 2023-03-10 [2d09e54] allow Open project dialog to also load nii and jnii files for rendering +* 2023-03-09 [63a626d] fix progress bar stalling when setting cfg.issavedet to 3 +* 2023-03-08 [8cab50f] add descriptions on how to start mcxstudio on an Mac, fix #162 +* 2023-03-08 [da49503] allow early termination if -d 3 or cfg.issavedet=3 is set +* 2023-03-04 [5d4d3c6] transition from openjdata.org to neurojson.org, fix #161 +* 2023-03-02 [3c29fa5] * mcxstudioL: loading and rendering jnifti based volume file +* 2023-03-01 [b99f9a9] mcxstudioL: loading portable JSON/JNIFTI based MCX output data files +* 2023-02-09 [32e3aef] fix RF replay in mcx binary, allow tweaking replay Jacobian for Born approx +* 2023-02-05 [9abd3f3] * adding additional native python pmcx functions +* 2023-02-05 [63b80f4] add missing pmcx file +* 2023-02-05 [e77ff2f] allow pmcx to use mixed binary extension and native function +* 2023-02-01 [d9b2f2b] * fix unmatched unit for RF replay, thanks to Pauliina Hirvi +* 2023-02-01 [ce2a65c] add the l/length option in help info +* 2023-02-01 [e67feed] support outputtype=length/l for saving total path lengths per voxel +* 2023-01-25 [4344574] fix windows compilation error +* 2023-01-25 [a7ce222] permit 3D plotting of DMMC output double-precision nii files +* 2023-01-22 [cdabf68] automatically replace RCS keywords in pmcx action +* 2023-01-22 [e527f4b] fix incomplete handling bc and isreflect setting combinations, fix #160 +* 2023-01-20 [daa1dea] use standard CFLAGS and CPPFLAGS in compilation, remove --std99 error for g++ +* 2023-01-11 [def38f6] Merge pull request #159 from matinraayai/master +* 2023-01-11 [e077f86] Bump pmcx version to 0.0.7. +* 2023-01-10 [7af2ea2] bump pmcx version to 0.0.6 +* 2023-01-10 [820ce88] build macos binary wheels +* 2023-01-09 [4f969d1] Removed the macOS builder VM. +* 2023-01-09 [dd47cda] Updated README.md for pmcx. +* 2023-01-09 [82ef430] Final version. +* 2022-12-08 [eb9322f] Added Windows Wheel building job + fixed compilation errors for windows. +* 2022-11-18 [d5a9beb] Update build_linux_manywheel.yml +* 2022-11-18 [816c55f] Added Github workflow. +* 2022-10-15 [084ffc1] update cmake file and remove zmat from pymcx and mex +* 2022-10-14 [04000e2] remove zmatlib and ubj as dependency to mex and oct +* 2022-10-14 [d033520] fix negative respin number bug +* 2022-10-13 [ec4a29d] update version strings +* 2022-10-13 [a3fe4ce] remove warning on replay output +* 2022-10-10 [660dd31] update three.js to r145, fix volume render, fix thumbnail + +Updates since v2021.2: + +* 2022-10-08 [eaedca7] update installer to 2022.10 +* 2022-10-08 [c31a0e2] update mcx version number to v2022.10 * 2022-10-05 [dc42951] prevent nan where log(rand) is calculated * 2022-10-05 [63ffc1e] fix nan in detected photon data when using hyperboloid src, see https://groups.google.com/g/mcx-users/c/vyfHbzEO-0M/m/JzlpEZ3TBwAJ * 2022-09-07 [e281f3e] allow to preview continuously varying medium (4D cfg.vol) @@ -198,11 +289,11 @@ A detailed list of updates is summarized below (key features marked with “*” * 2021-06-03 [1c29578] fix regression * 2021-06-03 [3aedee6] add LengthUnit, MediaFormat in schema, support number and string for DebugFlag/SaveDataMask * 2021-06-03 [64c5dd0] fix unnecessary shared memory allocation related to invcdf -* 2021-06-03 [ebf1ea1] support user-defined phase functions via cfg.invcdf, close #13 +* 2021-06-03 [ebf1ea1] * support user-defined phase functions via cfg.invcdf, close #13 * 2021-06-03 [0731511] revert back to no restarting policy so that overtime jobs can be killed * 2021-06-02 [4d2a891] process cache,fix fullname,fix job status,fix server-side limit,kill overtime job * 2021-06-02 [a08d676] update the skinvessel benchmark -* 2021-06-02 [168db14] feat: save Mie function outputs mus, g to a file +* 2021-06-02 [168db14] * feat: save Mie function outputs mus, g to a file * 2021-06-02 [57a44c5] feat: Add anisotropy g as an output of Mie func. * 2021-06-02 [7387394] finally fix crossdomain post, change jsonp to json,test simu lib edit * 2021-06-01 [95c6e1d] test:use default BC for all polarizedMC benchmarks @@ -221,7 +312,7 @@ A detailed list of updates is summarized below (key features marked with “*” * 2021-05-30 [55bb1ea] initial drag and drop support, not working * 2021-05-30 [fc9ca38] add meta headers, other minor adjustments * 2021-05-29 [96cf071] support embedding src pattern in the all-in-one json/jdata file -* 2021-05-28 [450462c] Add document for functions used in polarized MC +* 2021-05-28 [450462c] * Add document for functions used in polarized MC * 2021-05-28 [cbc3340] Optimize Stokes vector computation * 2021-05-28 [9bd2ce0] Remove redundant code in preprocessing * 2021-05-28 [06a9c6b] fix: resolve nan results due to numerical error @@ -229,17 +320,17 @@ A detailed list of updates is summarized below (key features marked with “*” * 2021-05-28 [9195141] Add an example to show polarized photon simulation * 2021-05-27 [2b87275] fix: rewrite code for better readability * 2021-05-26 [d836c81] fix: correct formula for stokes parameter update -* 2021-05-25 [105d5a9] feat: Add stokes parameter output in MCXLAB -* 2021-05-25 [87d8847] feat: add polarized photon simulation +* 2021-05-25 [105d5a9] * feat: Add stokes parameter output in MCXLAB +* 2021-05-25 [87d8847] * feat: add polarized photon simulation * 2021-05-23 [d398cc9] add simulation restrictions for initial public testing of mcx cloud * 2021-05-23 [26536d3] feat: add preprocessing for polarized MC in mcxlab -* 2021-05-22 [f0975c5] support ring/annulus shaped source via disk source -* 2021-05-21 [6ed9727] support svmc in command line;add svmc example +* 2021-05-22 [f0975c5] * support ring/annulus shaped source via disk source +* 2021-05-21 [6ed9727] * support svmc in command line;add svmc example * 2021-05-21 [3d0a793] reading 8-byte svmc volume format from input file * 2021-05-20 [4010d99] move svmc repacking to mcx_preprocess * 2021-05-20 [3214c1b] remove duplicated preprocessing codes in mcx and mcxlab,fix detbc bug in command line * 2021-05-20 [54b0602] run batch of jobs in each call to fill all GPU devices -* 2021-05-20 [de9850c] add -K short option and svmc mediatype +* 2021-05-20 [de9850c] * add -K short option and svmc mediatype * 2021-05-19 [660a8b8] relocate db and workspace folder to non www-data accessible paths * 2021-05-19 [64f3008] update acknowledgement list * 2021-05-19 [c168a87] can update thumbnail, add credit links @@ -247,7 +338,7 @@ A detailed list of updates is summarized below (key features marked with “*” * 2021-05-15 [cef630b] save volume in jdata format by default * 2021-05-15 [c50f871] define Frequency in json file instead of Omega * 2021-05-15 [b4e7b57] initial support RF mua Jacobian in replay, thx Ilkka Nissilä, formula based on Juha Heiskala PhD thesis p45 -* 2021-05-10 [073b168] mcxcloud initial preview at JBO hot-topics +* 2021-05-10 [073b168] * mcxcloud initial preview at JBO hot-topics * 2021-05-05 [5732e6a] update front and backends * 2021-05-01 [ee3f88d] update and rename mcxcloudd and mcxserver.cgi * 2021-05-01 [eac952d] fix cylinder schema, add footer @@ -267,16 +358,19 @@ A detailed list of updates is summarized below (key features marked with “*” * 2021-03-25 [9b0cf95] fine tune fonts, add big tab initial screen, add svg background, add funding info * 2021-03-25 [77f8f7a] add three.js for 3d preview * 2021-03-24 [4274c77] rename mcxcloud.txt to mcxcloud -* 2021-03-24 [dc25a87] add mcx cloud service server and client files, partially working +* 2021-03-24 [dc25a87] * add mcx cloud service server and client files, partially working * 2021-03-22 [f9bc07c] use tabs in mcxone, add jquery by default * 2021-03-18 [d8b88e1] fix unwanted double-precision math functions * 2021-03-11 [f6ce5bd] update variable and function name to follow the convention * 2021-03-11 [ca2ce60] add example: comparison of surface diffuse reflectance between MC and Diffusion * 2021-03-05 [bcbb324] change window sizes using 96dpi default setting * 2021-03-05 [5c8d27f] fix Name shape object schema -* 2021-03-03 [02add69] MCX json schema and json editor are working, added more Shapes objects +* 2021-03-03 [02add69] * MCX json schema and json editor are working, added more Shapes objects * 2021-03-01 [940d725] wrapping up json input import feature in mcxstudio * 2021-02-28 [64d629c] parse src/detector, media and shape + +Updates since v2020: + * 2021-02-27 [a3b8457]*open/import JSON input file in MCX Studio * 2021-01-07 [9811c83] reorder the input data layout to match the change in preprocessing * 2020-10-22 [991910e] add function comment and revert unnecessary changes @@ -329,7 +423,7 @@ A detailed list of updates is summarized below (key features marked with “*” * 2020-08-24 [782b4a3] massive update of documentation * 2020-08-24 [041e386] massive update to README to describe all output formats -Between 2020 and 2022, three new journal papers have been published as the +Between 2020 and 2023, seven new journal papers have been published as the result of this project, including [Yan2020]. Please see the full list at http://mcx.space/#publication @@ -342,17 +436,58 @@ http://mcx.space/#publication * [Yan2022] Shijie Yan, Steven L. Jacques, Jessica C. Ramella-Roman, Qianqian Fang, "Graphics processing unit-accelerated Monte Carlo simulation of polarized light in complex three-dimensional media," J. of Biomedical Optics, 27(8), 083015 (2022) +* [Zhang2022] Yuxuang Zhang, Qianqian Fang, "BlenderPhotonics – an integrated open-source + software environment for three-dimensional meshing and photon simulations in complex + tissues," J. of Biomedical Optics, 27(8), 083014 (2022) +* [RaayaiArdakani2022] Matin Raayai Ardakani, Leiming Yu, David R. Kaeli, Qianqian Fang, + "Framework for Denoising Monte Carlo Photon Transport Simulations Using Deep Learning," + J Biomed Opt. 2022 May;27(8):083019. doi: 10.1117/1.JBO.27.8.083019 +* [Yuan2021] Yaoshen Yuan, Shijie Yan, and Qianqian Fang*, "Light transport modeling in + highly complex tissues using the implicit mesh-based Monte Carlo algorithm," + Biomed. Optics Express, 12(1), 147-161, (2021) +* [Hirvi2023] Hirvi P, Kuutela T, Fang Q, Hannukainen A, Hyvonen N, Nissilä I. Effects of + atlas-based anatomy on modelled light transport in the neonatal head. Phys Med Biol. + 2023 May 11. doi: 10.1088/1361-6560/acd48c. PMID: 37167982. --------------------------------------------------------------------- == # Introduction == -Monte Carlo eXtreme (MCX) is a fast photon transport simulation software for 3D -heterogeneous turbid media. By taking advantage of the massively parallel -threads and extremely low memory latency in a modern graphics processing unit -(GPU), MCX is capable of performing Monte Carlo (MC) photon simulations at a -blazing speed, typically hundreds to a thousand times faster than a fully -optimized CPU-based MC implementation. +Monte Carlo eXtreme (MCX) is a fast physically-accurate photon simulation +software for 3D heterogeneous complex media. By taking advantage of +the massively parallel threads and extremely low memory latency in a +modern graphics processing unit (GPU), this program is able to perform Monte +Carlo (MC) simulations at a blazing speed, typically hundreds to +a thousand times faster than a single-threaded CPU-based MC implementation. + +MCX is written in C and NVIDIA CUDA. It only be executed on NVIDIA GPUs. +If you want to run hardware-accelerated MCX simulations on AMD/Intel GPUs +or CPUs, please download MCX-CL (MCX for OpenCL), which is written in OpenCL. +MCX and MCX-CL are highly compatible. + +Due to the nature of the underlying MC algorithms, MCX and MCX-CL are +ray-tracing/ray-casting software under-the-hood. Compared to commonly +seen ray-tracing libraries used in computer graphics or gaming +engines, MCX-CL and MCX have many unique characteristics. The most +important difference is that MCX/MCX-CL are rigorously based on physical +laws. They are numerical solvers to the underlying radiative transfer equation +(RTE) and their solutions have been validated across many publications +using optical instruments and experimental measurements. In comparison, +most graphics-oriented ray-tracers have to make many approximations in +order to achieve fast rendering, enable to provide quantitatively accurate +light simulation results. Because of this, MCX/MCX-CL have been extensively +used by biophotonics research communities to obtain reference solutions and +guide the development of novel medical imaging systems or clinical +applications. Additionally, MCX/MCX-CL are volumetric ray-tracers; they +traverse photon-rays throughout complex 3-D domains and computes physically +meaningful quantities such as spatially resolved fluence, flux, diffuse +reflectance/transmittance, energy deposition, partial pathlengths, +among many others. In contrast, most graphics ray-tracing engines +only trace the RGB color of a ray and render it on a flat 2-D screen. +In other words, MCX/MCX-CL gives physically accurate 3-D light distributions +while graphics ray-tracers focus on 2-D rendering of a scene at the camera. +Nonetheless, they share many similarities, such as ray-marching computation, +GPU acceleration, scattering/absorption handling etc. The algorithm of this software is detailed in the References [Fang2009,Yu2018,Yan2020]. A short summary of the main features includes: @@ -370,9 +505,10 @@ The algorithm of this software is detailed in the References * native Matlab/Octave support for high usability * flexible JSON interface for future extensions * multi-GPU support +* advanced features: photon-replay, photon-sharing, and more This software can be used on Windows, Linux and Mac OS. MCX is written in C/CUDA -and requires an NVIDIA GPU (support for AMD/Intel CPUs/GPUs via ROCm is still +and requires NVIDIA GPUs (support for AMD/Intel CPUs/GPUs via ROCm is still under development). A more portable OpenCL implementation of MCX, i.e. MCXCL, was announced on July, 2012 and supports almost all NVIDIA/AMD/Intel CPU and GPU models. If your hardware does not support CUDA, please download MCXCL from the @@ -399,7 +535,7 @@ MCX. A list of CUDA capable cards can be found at [2]. The oldest graphics card that MCX supports is the Fermi series (circa 2010). Using the latest NVIDIA card is expected to produce the best speed. You must have a fermi (GTX 4xx) or newer -(5xx/6xx/7xx/9xx/10xx/20xx series) graphics card. The default release +(9xx/10xx/20xx/30xx/40xx series) graphics card. The default release of MCX supports atomic operations and photon detection. In the below webpage, we summarized the speed differences between different generations of NVIDIA GPUs @@ -460,7 +596,7 @@ supported parameters, as shown below: 
###############################################################################
 #                      Monte Carlo eXtreme (MCX) -- CUDA                      #
-#          Copyright (c) 2009-2021 Qianqian Fang           #
+#          Copyright (c) 2009-2023 Qianqian Fang           #
 #                             http://mcx.space/                               #
 #                                                                             #
 # Computational Optics & Translational Imaging (COTI) Lab- http://fanglab.org #
@@ -468,7 +604,7 @@ supported parameters, as shown below:
 ###############################################################################
 #    The MCX Project is funded by the NIH/NIGMS under grant R01-GM114365      #
 ###############################################################################
-$Rev::e8fdb3$v2021.2$Date::2021-02-07 16:04:46 -05$ by $Author::Qianqian Fang $
+$Rev::e02c77$ v2023  $Date::2023-08-12 14:16:55 -04$ by $Author::Qianqian Fang$
 ###############################################################################
 
 usage: mcx   ...
@@ -543,24 +679,40 @@ where possible parameters include (the first value in [*|*] is the default)
                                this input can be used to modify all existing 
 			       settings defined by -f or --bench
  -K [1|int|str](--mediabyte)   volume data format, use either a number or a str
+       voxel binary data layouts are shown in {...}, where [] for byte,[i:]
+       for 4-byte integer, [s:] for 2-byte short, [h:] for 2-byte half float,
+       [f:] for 4-byte float; on Little-Endian systems, least-sig. bit on left
                                1 or byte: 0-128 tissue labels
 			       2 or short: 0-65535 (max to 4000) tissue labels
 			       4 or integer: integer tissue labels 
+			      97 or svmc: split-voxel MC 8-byte format
+			        {[n.z][n.y][n.x][p.z][p.y][p.x][upper][lower]}
+			      98 or mixlabel: label1+label2+label1_percentage
+			        {[label1][label2][s:0-65535 label1 percentage]}
 			      99 or labelplus: 32bit composite voxel format
+			        {[h:mua/mus/g/n][s:(B15-16:0/1/2/3)(label)]}
                              100 or muamus_float: 2x 32bit floats for mua/mus
+			        {[f:mua][f:mus]}; g/n from medium type 1
                              101 or mua_float: 1 float per voxel for mua
+			        {[f:mua]}; mus/g/n from medium type 1
 			     102 or muamus_half: 2x 16bit float for mua/mus
+			        {[h:mua][h:mus]}; g/n from medium type 1
 			     103 or asgn_byte: 4x byte gray-levels for mua/s/g/n
+			        {[mua][mus][g][n]}; 0-255 mixing prop types 1&2
 			     104 or muamus_short: 2x short gray-levels for mua/s
+			        {[s:mua][s:mus]}; 0-65535 mixing prop types 1&2
  -a [0|1]      (--array)       1 for C array (row-major); 0 for Matlab array
 
 == Output options ==
  -s sessionid  (--session)     a string to label all output file names
- -O [X|XFEJPM] (--outputtype)  X - output flux, F - fluence, E - energy deposit
+ -O [X|XFEJPMRL](--outputtype) X - output flux, F - fluence, E - energy deposit
     /case insensitive/         J - Jacobian (replay mode),   P - scattering, 
 			       event counts at each voxel (replay mode only)
-                               M - momentum transfer; 
- -d [1|0]      (--savedet)     1 to save photon info at detectors; 0 not save
+                               M - momentum transfer; R - RF/FD Jacobian
+                               L - total pathlength
+ -d [1|0-3]    (--savedet)     1 to save photon info at detectors; 0 not save
+                               2 reserved, 3 terminate simulation when detected
+                               photon buffer is filled
  -w [DP|DSPMXVW](--savedetflag)a string controlling detected photon data fields
     /case insensitive/         1 D  output detector ID (1)
                                2 S  output partial scat. even counts (#media)
@@ -585,17 +737,17 @@ where possible parameters include (the first value in [*|*] is the default)
  -S [1|0]      (--save2pt)     1 to save the flux field; 0 do not save
  -F [mc2|...] (--outputformat) fluence data output format:
                                mc2 - MCX mc2 format (binary 32bit float)
-                               jnii - JNIfTI format (http://openjdata.org)
-                               bnii - Binary JNIfTI (http://openjdata.org)
+                               jnii - JNIfTI format (https://neurojson.org)
+                               bnii - Binary JNIfTI (https://neurojson.org)
                                nii - NIfTI format
                                hdr - Analyze 7.5 hdr/img format
                                tx3 - GL texture data for rendering (GL_RGBA32F)
 	the bnii/jnii formats support compression (-Z) and generate small files
 	load jnii (JSON) and bnii (UBJSON) files using below lightweight libs:
-	  MATLAB/Octave: JNIfTI toolbox   https://github.com/fangq/jnifti, 
-	  MATLAB/Octave: JSONLab toolbox  https://github.com/fangq/jsonlab, 
+	  MATLAB/Octave: JNIfTI toolbox   https://github.com/NeuroJSON/jnifti,
+	  MATLAB/Octave: JSONLab toolbox  https://github.com/NeuroJSON/jsonlab,
 	  Python:        PyJData:         https://pypi.org/project/jdata
-	  JavaScript:    JSData:          https://github.com/fangq/jsdata
+	  JavaScript:    JSData:          https://github.com/NeuroJSON/jsdata
  -Z [zlib|...] (--zip)         set compression method if -F jnii or --dumpjson
                                is used (when saving data to JSON/JNIfTI format)
 			       0 zlib: zip format (moderate compression,fast) 
@@ -606,7 +758,7 @@ where possible parameters include (the first value in [*|*] is the default)
 			       5 lz4: LZ4 format (low compression,extrem. fast)
 			       6 lz4hc: LZ4HC format (moderate compression,fast)
  --dumpjson [-,0,1,'file.json']  export all settings, including volume data using
-                               JSON/JData (http://openjdata.org) format for 
+                               JSON/JData (https://neurojson.org) format for
 			       easy sharing; can be reused using -f
 			       if followed by nothing or '-', mcx will print
 			       the JSON to the console; write to a file if file
@@ -623,9 +775,10 @@ where possible parameters include (the first value in [*|*] is the default)
 == Debug options ==
  -D [0|int]    (--debug)       print debug information (you can use an integer
   or                           or a string by combining the following flags)
- -D [''|RMP]                   1 R  debug RNG
+ -D [''|RMPT]                  1 R  debug RNG
     /case insensitive/         2 M  store photon trajectory info
                                4 P  print progress bar
+                               8 T  save trajectory data only, disable flux/detp
       combine multiple items by using a string, or add selected numbers together
 
 == Additional options ==
@@ -1200,16 +1353,32 @@ seed data and saved as a JSON-compatible .jdat file. The overall structure of th
 ---------------------------------------------------------------------------
 == # Using MCXLAB in MATLAB and Octave ==
 
-MCXLAB is the native MEX version of MCX for Matlab and GNU Octave. It includes
-the entire MCX code in a MEX function which can be called directly inside
-Matlab or Octave. The input and output files in MCX are replaced by convenient
-in-memory struct variables in MCXLAB, thus, making it much easier to use
-and interact. Matlab/Octave also provides convenient plotting and data
-analysis functions. With MCXLAB, your analysis can be streamlined and speed-
-up without involving disk files.
+MCXLAB is the native MEX version of MCX for MATLAB and GNU Octave. It includes 
+the entire MCX code in a MEX function which can be called directly inside 
+MATLAB or Octave. The input and output files in MCX are replaced by convenient 
+in-memory struct variables in MCXLAB, thus, making it much easier to use and 
+interact. MATLAB/Octave also provides convenient plotting and data analysis 
+functions. With MCXLAB, your analysis can be streamlined and simplified without 
+involving disk files.
+
+Please read the mcxlab/README.txt file for more details on how to install and 
+use MCXLAB.
+
+Please also browse this interactive [https://colab.research.google.com/github/fangq/mcx/blob/master/mcxlab/tutorials/mcxlab_getting_started.ipynb Jupyter Notebook based MCXLAB tutorial]
+to see a suite of examples showing the key functionalities of MCXLAB (using GNU Octave).
+
+---------------------------------------------------------------------------
+== # Using PMCX in Python ==
+
+PMCX is the native binary binding of MCX for Python 3.6 or newer. Similar to
+MCXLAB, PMCX can run GPU-based simulations inside Python environment with
+efficient in-memory inputs and outputs. 
+
+Please read the pmcx/README.txt file for more details on how to install and 
+use PMCX.
 
-Please read the mcxlab/README.txt file for more details on how to
-install and use MCXLAB.
+Please also browse this interactive [https://colab.research.google.com/github/fangq/mcx/blob/master/pmcx/tutorials/pmcx_getting_started.ipynb Jupyter Notebook based PMCX tutorial]
+to see a suite of examples showing the key functionalities of PMCX.
 
 
 ---------------------------------------------------------------------------
diff --git a/TODO.txt b/TODO.txt
index feb91156..24076513 100644
--- a/TODO.txt
+++ b/TODO.txt
@@ -2,10 +2,13 @@
 
 == Short term projects ==
 
-*. support user defined phase functions [opened by FangQ, 2018/01/28]
+*. support user-defined photon emission angular distribution [https://github.com/fangq/mcx/issues/129]
+*. support simulations of multiple sources of the same type [https://github.com/fangq/mcx/issues/163]
 *. support anisotropic voxels [opened by FangQ, 2018/01/28]
 *. support non-uniform grid [opened by FangQ, 2018/01/28]
 *. support dual-grid MMC like ray-tracing [opened by FangQ, 2018/01/28]
+*. support mua/mus/g/n 8-byte continuous media format [opened by FangQ, 2023/08/12]
+*. support TPM based continuous media [opened by FangQ, 2023/08/12]
 
 == Completed ==
 
@@ -25,8 +28,9 @@
 [done] *. OpenCL variant of MCX [2009/10/21, FangQ] [2010/02/10, FangQ]
 [dropped] *. Brook+ variant of MCX [2009/10/21, FangQ]
 [dropped] *. support ini based input file format (or perl script format) [2009/04/30, FangQ]
-[dropped] *. support NIFTI input & output [2009/04/30, FangQ]
+[done] *. support NIFTI input & output [2009/04/30, FangQ]
 [done] *. support more complicated source forms [2009/09/30, FangQ], [2013/09/18, FangQ]
 [done] *. precise ray-tracing in a grid space [2012/01/11, FangQ]
 [done] *. multiple-GPU support [2009/09/30, FangQ]
 [dropped] study the round-off errors for the two RNGs [2009/04/30, FangQ]
+[done] *. support user defined phase functions [opened by FangQ, 2018/01/28] [https://github.com/fangq/mcx/issues/13]
diff --git a/inno/MCXStudio.iss b/inno/MCXStudio.iss
index bd13fe8a..2b9d7b49 100755
--- a/inno/MCXStudio.iss
+++ b/inno/MCXStudio.iss
@@ -10,7 +10,7 @@
 
 #define MyAppName "MCX Studio"
 #define MyAppDir "MCXStudio"
-#define MyAppVersion "v2022.10"
+#define MyAppVersion "v2023"
 #define MyAppPublisher "COTILab"
 #define MyAppURL "http://mcx.space"
 #define MyAppExeName "mcxstudio.exe"
diff --git a/mcxlab/README.txt b/mcxlab/README.txt
index 08cd9706..3ef22b18 100644
--- a/mcxlab/README.txt
+++ b/mcxlab/README.txt
@@ -2,7 +2,7 @@
 
 Author: Qianqian Fang 
 License: GNU General Public License version 3 (GPLv3)
-Version: this package is part of Monte Carlo eXtreme (MCX) v2022.10
+Version: this package is part of Monte Carlo eXtreme (MCX) v2023
 
 
 
@@ -19,7 +19,7 @@ up without involving disk files.
 
 Because MCXLAB contains the exact computational codes for the GPU calculations
 as in the MCX binaries, MCXLAB is expected to have identical performance when
-running simulations.
+running simulations compared to the standalone version of MCX.
 
 
 == # Installation ==
@@ -58,9 +58,9 @@ formats and examples. The input cfg structure has very similar field names as
 the verbose command line options in MCX.
 
 
 ====================================================================
-       MCXLAB - Monte Carlo eXtreme (MCX) for MATLAB/GNU Octave
+       mcxlab - Monte Carlo eXtreme (MCX) for MATLAB/GNU Octave
  --------------------------------------------------------------------
- Copyright (c) 2011-2022 Qianqian Fang 
+ Copyright (c) 2011-2023 Qianqian Fang 
                        URL: http://mcx.space
  ====================================================================
  
@@ -99,7 +99,7 @@ the verbose command line options in MCX.
                        the 2D plane in such case.
                        for 2D simulations, Example: 
  
-                       MCXLAB also accepts 4D arrays to define continuously varying media. 
+                       mcxlab also accepts 4D arrays to define continuously varying media. 
                        The following formats are accepted
                          1 x Nx x Ny x Nz float32 array: mua values for each voxel (must use permute to make 1st dimension singleton)
                          2 x Nx x Ny x Nz float32 array: mua/mus values for each voxel (g/n use prop(2,:))
@@ -165,6 +165,15 @@ the verbose command line options in MCX.
                        or detphoton.data subfield (as a 2D array). cfg.detphotons can use
                        a subset of the detected photon selected by the user.
                        Example: 
+       cfg.polprop:    an N by 5 array, each row specifies [mua, radius(micron), volume
+                       density(1/micron^3), sphere refractive index, ambient medium
+                       refractive index] in order. The first row is type 1,
+                       and so on. The background medium (type 0) should be
+                       defined in the first row of cfg.prop. For polprop type
+                       i, if prop(i,2) is not zero: 1) if prop(i,3) == 1, the
+                       density polprop(i,3) will be adjusted to achieve the target
+                       mus prop(i,2); 2) if prop(i,3) < 1, polprop(i,3) will be
+                       adjusted to achieve the target mus' prop(i,2)*(1-prop(i,3))
  
  == GPU settings ==
        cfg.autopilot:  1-automatically set threads and blocks, [0]-use nthread/nblocksize
@@ -192,6 +201,9 @@ the verbose command line options in MCX.
                        'isotropic' - isotropic source, no param needed
                        'cone' - uniform cone beam, srcparam1(1) is the half-angle in radian
                        'gaussian' [*] - a collimated gaussian beam, srcparam1(1) specifies the waist radius (in voxels)
+                       'hyperboloid' [*] - a one-sheeted hyperboloid gaussian beam, srcparam1(1) specifies the waist
+                                 radius (in voxels), srcparam1(2) specifies distance between launch plane and focus,
+                                 srcparam1(3) specifies rayleigh range
                        'planar' [*] - a 3D quadrilateral uniform planar source, with three corners specified 
                                  by srcpos, srcpos+srcparam1(1:3) and srcpos+srcparam2(1:3)
                        'pattern' [*] - a 3D quadrilateral pattern illumination, same as above, except
@@ -211,7 +223,9 @@ the verbose command line options in MCX.
                        'arcsine' - similar to isotropic, except the zenith angle is uniform
                                  distribution, rather than a sine distribution.
                        'disk' [*] - a uniform disk source pointing along srcdir; the radius is 
-                                set by srcparam1(1) (in grid unit)
+                                set by srcparam1(1) (in grid unit); if srcparam1(2) is set to a non-zero
+                                value, this source defines a ring (annulus) shaped source, with
+                                srcparam1(2) denoting the inner circle's radius, here srcparam1(1)>=srcparam1(2)
                        'fourierx' [*] - a general Fourier source, the parameters are 
                                 srcparam1: [v1x,v1y,v1z,|v2|], srcparam2: [kx,ky,phi0,M]
                                 normalized vectors satisfy: srcdir cross v1=v2
@@ -219,7 +233,7 @@ the verbose command line options in MCX.
                        'fourierx2d' [*] - a general 2D Fourier basis, parameters
                                 srcparam1: [v1x,v1y,v1z,|v2|], srcparam2: [kx,ky,phix,phiy]
                                 the phase shift is phi{x,y}*2*pi
-                       'zgaussian' - an angular gaussian beam, srcparam1(0) specifies the variance in the zenith angle
+                       'zgaussian' - an angular gaussian beam, srcparam1(1) specifies the variance in the zenith angle
                        'line' - a line source, emitting from the line segment between 
                                 cfg.srcpos and cfg.srcpos+cfg.srcparam(1:3), radiating 
                                 uniformly in the perpendicular direction
@@ -239,6 +253,16 @@ the verbose command line options in MCX.
                        simultaneously simulated; only works for 'pattern'
                        source, see cfg.srctype='pattern' for details
                        Example 
+       cfg.omega: source modulation frequency (rad/s) for RF replay, 2*pi*f
+       cfg.srciquv: 1x4 vector [I,Q,U,V], Stokes vector of the incident light
+                    I: total light intensity (I >= 0)
+                    Q: balance between horizontal and vertical linearly
+                    polaized light (-1 <= Q <= 1)
+                    U: balance between +45° and -45° linearly polaized
+                    light (-1 <= Q <= 1)
+                    V: balance between right and left circularly polaized
+                    light (-1 <= Q <= 1)
+       cfg.lambda: source light wavelength (nm) for polarized MC
        cfg.issrcfrom0: 1-first voxel is [0 0 0], [0]- first voxel is [1 1 1]
        cfg.replaydet:  only works when cfg.outputtype is 'jacobian', 'wl', 'nscat', or 'wp' and cfg.seed is an array
                        -1 replay all detectors and save in separate volumes (output has 5 dimensions)
@@ -256,6 +280,7 @@ the verbose command line options in MCX.
                           16 x  output exit position (3)
                           32 v  output exit direction (3)
                           64 w  output initial weight (1)
+                         128 i  output stokes vector (4)
                        combine multiple items by using a string, or add selected numbers together
                        by default, mcx only saves detector ID (d) and partial-path data (p)
        cfg.issaveexit: [0]-save the position (x,y,z) and (vx,vy,vz) for a detected photon
@@ -266,20 +291,32 @@ the verbose command line options in MCX.
                        next to a boundary voxel. The reflectance data are stored as 
                        negative values; must pad zeros next to boundaries
                        Example: see the demo script at the bottom
+       cfg.issave2pt:  [1]-save volumetric output in the first output fluence.data; user can disable this output
+                       by explicitly setting cfg.issave2pt=0, this way, even the first output fluence presents
+                       in mcxlab call, volume data will not be saved, this can speed up simulation when only 
+                       detphoton is needed
+       cfg.issavedet:  if the 2nd output is requested, this will be set to 1; in such case, user can force
+                       setting it to 3 to enable early termination of simulation if the detected photon
+                       buffer (length controlled by cfg.maxdetphoton) is filled; if the 2nd output is not
+                       present, this will be set to 0 regardless user input.
        cfg.outputtype: 'flux' - fluence-rate, (default value)
                        'fluence' - fluence integrated over each time gate, 
                        'energy' - energy deposit per voxel
                        'jacobian' or 'wl' - mua Jacobian (replay mode), 
                        'nscat' or 'wp' - weighted scattering counts for computing Jacobian for mus (replay mode)
+                       'wm' - weighted momentum transfer for a source/detector pair (replay mode)
+                       'rf' frequency-domain (FD/RF) mua Jacobian (replay mode),
+                       'length' total pathlengths accumulated per voxel,
                        for type jacobian/wl/wp, example: 
                        and  
        cfg.session:    a string for output file names (only used when no return variables)
  
  == Debug ==
-       cfg.debuglevel:  debug flag string (case insensitive), one or a combination of ['R','M','P'], no space
+       cfg.debuglevel:  debug flag string (case insensitive), one or a combination of ['R','M','P','T'], no space
                      'R':  debug RNG, output fluence.data is filled with 0-1 random numbers
                      'M':  return photon trajectory data as the 5th output
                      'P':  show progress bar
+                     'T':  save photon trajectory data only, as the 1st output, disable flux/detp/seeds outputs
        cfg.maxjumpdebug: [10000000|int] when trajectory is requested in the output, 
                       use this parameter to set the maximum position stored. By default,
                       only the first 1e6 positions are stored.
@@ -293,6 +330,9 @@ the verbose command line options in MCX.
                   dimensions specified by [size(vol) total-time-gates]. 
                   The content of the array is the normalized fluence at 
                   each voxel of each time-gate.
+ 
+                  when cfg.debuglevel contains 'T', fluence(i).data stores trajectory
+                  output, see below
              fluence(i).dref is a 4D array with the same dimension as fluence(i).data
                   if cfg.issaveref is set to 1, containing only non-zero values in the 
                   layer of voxels immediately next to the non-zero voxels in cfg.vol,
@@ -316,10 +356,11 @@ the verbose command line options in MCX.
                detphoton.mom: cummulative cos_theta for momentum transfer in each medium  
                detphoton.p or .v: exit position and direction, when cfg.issaveexit=1
                detphoton.w0: photon initial weight at launch time
+               detphoton.s: exit Stokes parameters for polarized photon
                detphoton.prop: optical properties, a copy of cfg.prop
                detphoton.data: a concatenated and transposed array in the order of
                      [detid nscat ppath mom p v w0]'
-               "data" is the is the only subfield in all MCXLAB before 2018
+               "data" is the is the only subfield in all mcxlab before 2018
        vol: (optional) a struct array, each element is a preprocessed volume
              corresponding to each instance of cfg. Each volume is a 3D int32 array.
        seeds: (optional), if give, mcxlab returns the seeds, in the form of
diff --git a/mcxstudio/README.txt b/mcxstudio/README.txt
index af27cde5..bf633871 100644
--- a/mcxstudio/README.txt
+++ b/mcxstudio/README.txt
@@ -4,7 +4,7 @@
 
 Author:  Qianqian Fang 
 License: GNU General Public License version 3 (GPLv3)
-Version: 0.9.9 (v2022.10)
+Version: 1.0 (v2023)
 Website: http://mcx.space
 
 ---------------------------------------------------------------------
diff --git a/mcxstudio/mcxabout.lfm b/mcxstudio/mcxabout.lfm
index d61a4914..593e1951 100644
--- a/mcxstudio/mcxabout.lfm
+++ b/mcxstudio/mcxabout.lfm
@@ -45,7 +45,7 @@ object fmAbout: TfmAbout
     BorderStyle = bsNone
     Font.Color = clWhite
     Lines.Strings = (
-      'MCXStudio version: v2023.03'
+      'MCXStudio version: v2023'
       ''
       'Funding Support:'
       '  This project is funded by the NIH/NIGMS under '
diff --git a/mcxstudio/mcxstudio.lpi b/mcxstudio/mcxstudio.lpi
index 6fa5cb1e..bc096183 100755
--- a/mcxstudio/mcxstudio.lpi
+++ b/mcxstudio/mcxstudio.lpi
@@ -1,9 +1,11 @@
 
 
   
-    
+    
     
-      
+      
+        
+      
       
       <Scaled Value="True"/>
       <UseXPManifest Value="True"/>
@@ -21,7 +23,7 @@
       <BuildNr Value="559"/>
       <StringTable Comments="A unified GUI for MCX, MMC and MCXCL" CompanyName="Northeastern University" FileDescription="MCX Studio" InternalName="MCX Studio" LegalCopyright="2009,2010 Qianqian Fang" LegalTrademarks="MCX Studio" ProductName="MCX Studio" ProductVersion="0.0.0.1"/>
     </VersionInfo>
-    <BuildModes Count="3" Active="Debug">
+    <BuildModes Count="3" Active="Release">
       <Item1 Name="default" Default="True"/>
       <Item2 Name="Debug">
         <CompilerOptions>
@@ -103,11 +105,14 @@
       <Version Value="2"/>
     </PublishOptions>
     <RunParams>
+      <local>
+        <LaunchingApplication PathPlusParams="/usr/X11R6/bin/xterm -T 'Lazarus Run Output' -e $(LazarusDir)/tools/runwait.sh $(TargetCmdLine)"/>
+      </local>
       <FormatVersion Value="2"/>
       <Modes Count="1">
         <Mode0 Name="default">
           <local>
-            <LaunchingApplication PathPlusParams="/usr/X11R6/bin/xterm -T 'Lazarus Run Output' -e $(LazarusDir)/tools/runwait.sh $(TargetCmdLine)"/>
+            <LaunchingApplication PathPlusParams="/usr/X11R6/bin/xterm -T 'Lazarus Run Output' -e $(LazarusDir)/tools/runwait.sh $(TargetCmdLine)"/>
           </local>
         </Mode0>
       </Modes>
@@ -130,7 +135,7 @@
         <PackageName Value="LCL"/>
       </Item5>
     </RequiredPackages>
-    <Units Count="44">
+    <Units Count="17">
       <Unit0>
         <Filename Value="mcxstudio.lpr"/>
         <IsPartOfProject Value="True"/>
@@ -298,20 +303,6 @@
         <UsageCount Value="201"/>
       </Unit15>
       <Unit16>
-        <Filename Value="../../../../../../../lazarus/fpc/3.0.4/source/rtl/objpas/sysutils/diskh.inc"/>
-        <EditorIndex Value="-1"/>
-        <CursorPos X="26" Y="23"/>
-        <UsageCount Value="2"/>
-      </Unit16>
-      <Unit17>
-        <Filename Value="/usr/share/lazarus/2.0.8/lcl/asyncprocess.pp"/>
-        <UnitName Value="AsyncProcess"/>
-        <EditorIndex Value="-1"/>
-        <TopLine Value="87"/>
-        <CursorPos Y="106"/>
-        <UsageCount Value="3"/>
-      </Unit17>
-      <Unit18>
         <Filename Value="lazhelphtml.pas"/>
         <IsPartOfProject Value="True"/>
         <EditorIndex Value="-1"/>
@@ -319,297 +310,12 @@
         <TopLine Value="-1"/>
         <CursorPos X="-1" Y="-1"/>
         <UsageCount Value="116"/>
-      </Unit18>
-      <Unit19>
-        <Filename Value="glscene/GLGraph.pas"/>
-        <EditorIndex Value="-1"/>
-        <TopLine Value="308"/>
-        <CursorPos X="17" Y="321"/>
-        <UsageCount Value="3"/>
-      </Unit19>
-      <Unit20>
-        <Filename Value="/usr/share/fpcsrc/3.0.4/packages/fcl-json/src/fpjson.pp"/>
-        <EditorIndex Value="-1"/>
-        <TopLine Value="395"/>
-        <CursorPos X="36" Y="426"/>
-        <UsageCount Value="32"/>
-      </Unit20>
-      <Unit21>
-        <Filename Value="/usr/share/lazarus/2.0.8/lcl/include/customform.inc"/>
-        <EditorIndex Value="-1"/>
-        <TopLine Value="195"/>
-        <CursorPos Y="218"/>
-        <UsageCount Value="4"/>
-      </Unit21>
-      <Unit22>
-        <Filename Value="/usr/share/lazarus/2.0.8/lcl/include/application.inc"/>
-        <EditorIndex Value="-1"/>
-        <TopLine Value="1077"/>
-        <CursorPos Y="1099"/>
-        <UsageCount Value="4"/>
-      </Unit22>
-      <Unit23>
-        <Filename Value="/usr/share/lazarus/2.0.8/lcl/forms.pp"/>
-        <UnitName Value="Forms"/>
-        <EditorIndex Value="-1"/>
-        <UsageCount Value="3"/>
-      </Unit23>
-      <Unit24>
-        <Filename Value="/usr/share/lazarus/2.0.2/lcl/include/customform.inc"/>
-        <EditorIndex Value="-1"/>
-        <TopLine Value="193"/>
-        <CursorPos Y="218"/>
-        <UsageCount Value="22"/>
-      </Unit24>
-      <Unit25>
-        <Filename Value="/usr/share/fpcsrc/3.0.4/packages/fcl-json/src/jsonparser.pp"/>
-        <EditorIndex Value="-1"/>
-        <TopLine Value="21"/>
-        <CursorPos X="3" Y="28"/>
-        <UsageCount Value="24"/>
-      </Unit25>
-      <Unit26>
-        <Filename Value="/usr/share/fpcsrc/3.0.4/packages/fcl-json/src/jsonscanner.pp"/>
-        <EditorIndex Value="-1"/>
-        <TopLine Value="37"/>
-        <CursorPos X="33" Y="56"/>
-        <UsageCount Value="17"/>
-      </Unit26>
-      <Unit27>
-        <Filename Value="/usr/share/fpcsrc/3.0.4/rtl/objpas/sysutils/finah.inc"/>
-        <EditorIndex Value="-1"/>
-        <TopLine Value="6"/>
-        <CursorPos X="10" Y="23"/>
-        <UsageCount Value="15"/>
-      </Unit27>
-      <Unit28>
-        <Filename Value="glscene/XOpenGL.pas"/>
-        <EditorIndex Value="-1"/>
-        <TopLine Value="176"/>
-        <CursorPos X="61" Y="192"/>
-        <UsageCount Value="12"/>
-      </Unit28>
-      <Unit29>
-        <Filename Value="/usr/share/lazarus/2.0.2/lcl/include/containedaction.inc"/>
-        <EditorIndex Value="-1"/>
-        <TopLine Value="64"/>
-        <CursorPos Y="100"/>
-        <UsageCount Value="8"/>
-      </Unit29>
-      <Unit30>
-        <Filename Value="/usr/share/lazarus/2.0.2/lcl/include/customaction.inc"/>
-        <EditorIndex Value="-1"/>
-        <TopLine Value="223"/>
-        <CursorPos X="32" Y="241"/>
-        <UsageCount Value="8"/>
-      </Unit30>
-      <Unit31>
-        <Filename Value="glscene/OpenGLTokens.pas"/>
-        <EditorIndex Value="-1"/>
-        <TopLine Value="5176"/>
-        <CursorPos X="14" Y="5212"/>
-        <UsageCount Value="21"/>
-      </Unit31>
-      <Unit32>
-        <Filename Value="/usr/share/fpcsrc/3.0.4/packages/fcl-base/src/base64.pp"/>
-        <EditorIndex Value="-1"/>
-        <TopLine Value="82"/>
-        <UsageCount Value="8"/>
-      </Unit32>
-      <Unit33>
-        <Filename Value="glscene/GLContext.pas"/>
-        <EditorIndex Value="-1"/>
-        <TopLine Value="2062"/>
-        <CursorPos X="41" Y="2074"/>
-        <UsageCount Value="18"/>
-      </Unit33>
-      <Unit34>
-        <Filename Value="/usr/share/lazarus/2.0.2/lcl/include/customcheckbox.inc"/>
-        <EditorIndex Value="-1"/>
-        <TopLine Value="123"/>
-        <CursorPos Y="143"/>
-        <UsageCount Value="18"/>
-      </Unit34>
-      <Unit35>
-        <Filename Value="/usr/share/fpcsrc/3.0.4/packages/paszlib/src/zipper.pp"/>
-        <EditorIndex Value="-1"/>
-        <TopLine Value="507"/>
-        <CursorPos X="17" Y="521"/>
-        <UsageCount Value="12"/>
-      </Unit35>
-      <Unit36>
-        <Filename Value="/usr/share/fpcsrc/3.0.4/rtl/inc/objpash.inc"/>
-        <EditorIndex Value="-1"/>
-        <TopLine Value="181"/>
-        <CursorPos X="22" Y="196"/>
-        <UsageCount Value="10"/>
-      </Unit36>
-      <Unit37>
-        <Filename Value="/usr/share/fpcsrc/3.0.4/packages/paszlib/src/zstream.pp"/>
-        <EditorIndex Value="-1"/>
-        <TopLine Value="43"/>
-        <CursorPos X="29" Y="65"/>
-        <UsageCount Value="12"/>
-      </Unit37>
-      <Unit38>
-        <Filename Value="/usr/share/fpcsrc/3.0.4/rtl/objpas/classes/classesh.inc"/>
-        <EditorIndex Value="-1"/>
-        <TopLine Value="849"/>
-        <CursorPos X="71" Y="871"/>
-        <UsageCount Value="9"/>
-      </Unit38>
-      <Unit39>
-        <Filename Value="/usr/share/lazarus/2.0.2/lcl/include/application.inc"/>
-        <EditorIndex Value="-1"/>
-        <TopLine Value="1073"/>
-        <CursorPos Y="1099"/>
-        <UsageCount Value="12"/>
-      </Unit39>
-      <Unit40>
-        <Filename Value="/usr/share/lazarus/2.0.2/lcl/forms.pp"/>
-        <UnitName Value="Forms"/>
-        <EditorIndex Value="-1"/>
-        <UsageCount Value="10"/>
-      </Unit40>
-      <Unit41>
-        <Filename Value="glscene/GLVectorGeometry.pas"/>
-        <EditorIndex Value="-1"/>
-        <TopLine Value="344"/>
-        <CursorPos X="39" Y="362"/>
-        <UsageCount Value="10"/>
-      </Unit41>
-      <Unit42>
-        <Filename Value="glscene/GLWindowsFont.pas"/>
-        <EditorIndex Value="-1"/>
-        <CursorPos X="60" Y="10"/>
-        <UsageCount Value="10"/>
-      </Unit42>
-      <Unit43>
-        <Filename Value="/usr/share/fpcsrc/3.0.4/packages/rtl-objpas/src/inc/strutils.pp"/>
-        <EditorIndex Value="7"/>
-        <CursorPos X="20" Y="19"/>
-        <UsageCount Value="11"/>
-        <Loaded Value="True"/>
-      </Unit43>
+      </Unit16>
     </Units>
     <Build>
       <CleanOutputFileMask Value="*.ppu;*.ppl;*.o;*.or"/>
     </Build>
-    <JumpHistory Count="30" HistoryIndex="29">
-      <Position1>
-        <Filename Value="mcxgui.pas"/>
-      </Position1>
-      <Position2>
-        <Filename Value="mcxgui.pas"/>
-        <Caret Line="1210" Column="36" TopLine="1194"/>
-      </Position2>
-      <Position3>
-        <Filename Value="mcxview.pas"/>
-        <Caret Line="108" Column="26" TopLine="91"/>
-      </Position3>
-      <Position4>
-        <Filename Value="mcxview.pas"/>
-        <Caret Line="173" Column="20" TopLine="143"/>
-      </Position4>
-      <Position5>
-        <Filename Value="mcxgui.pas"/>
-        <Caret Line="1205" Column="67" TopLine="1194"/>
-      </Position5>
-      <Position6>
-        <Filename Value="mcxview.pas"/>
-        <Caret Line="534" Column="42" TopLine="512"/>
-      </Position6>
-      <Position7>
-        <Filename Value="mcxview.pas"/>
-        <Caret Line="237" Column="53" TopLine="225"/>
-      </Position7>
-      <Position8>
-        <Filename Value="mcxview.pas"/>
-        <Caret Line="19" TopLine="19"/>
-      </Position8>
-      <Position9>
-        <Filename Value="mcxview.pas"/>
-      </Position9>
-      <Position10>
-        <Filename Value="texture_3d.pas"/>
-        <Caret Line="364" Column="43" TopLine="355"/>
-      </Position10>
-      <Position11>
-        <Filename Value="texture_3d.pas"/>
-      </Position11>
-      <Position12>
-        <Filename Value="texture_3d.pas"/>
-        <Caret Line="115" Column="38" TopLine="95"/>
-      </Position12>
-      <Position13>
-        <Filename Value="texture_3d.pas"/>
-        <Caret Line="308" Column="36" TopLine="288"/>
-      </Position13>
-      <Position14>
-        <Filename Value="texture_3d.pas"/>
-        <Caret Line="274" Column="59" TopLine="256"/>
-      </Position14>
-      <Position15>
-        <Filename Value="texture_3d.pas"/>
-      </Position15>
-      <Position16>
-        <Filename Value="mcxgui.pas"/>
-        <Caret Line="1212" Column="57" TopLine="1190"/>
-      </Position16>
-      <Position17>
-        <Filename Value="mcxgui.pas"/>
-        <Caret Line="2023" Column="37" TopLine="2006"/>
-      </Position17>
-      <Position18>
-        <Filename Value="mcxgui.pas"/>
-        <Caret Line="2007" Column="5" TopLine="2005"/>
-      </Position18>
-      <Position19>
-        <Filename Value="mcxgui.pas"/>
-        <Caret Line="2008" Column="5" TopLine="2006"/>
-      </Position19>
-      <Position20>
-        <Filename Value="mcxgui.pas"/>
-        <Caret Line="2022" Column="16" TopLine="2007"/>
-      </Position20>
-      <Position21>
-        <Filename Value="mcxgui.pas"/>
-      </Position21>
-      <Position22>
-        <Filename Value="mcxgui.pas"/>
-        <Caret Line="358" Column="36" TopLine="330"/>
-      </Position22>
-      <Position23>
-        <Filename Value="mcxgui.pas"/>
-      </Position23>
-      <Position24>
-        <Filename Value="mcxgui.pas"/>
-        <Caret Line="358" Column="36" TopLine="329"/>
-      </Position24>
-      <Position25>
-        <Filename Value="mcxgui.pas"/>
-        <Caret Line="1297" Column="39" TopLine="1267"/>
-      </Position25>
-      <Position26>
-        <Filename Value="mcxgui.pas"/>
-        <Caret Line="356" Column="46" TopLine="341"/>
-      </Position26>
-      <Position27>
-        <Filename Value="mcxgui.pas"/>
-        <Caret Line="2452" Column="37" TopLine="2451"/>
-      </Position27>
-      <Position28>
-        <Filename Value="mcxgui.pas"/>
-        <Caret Line="1938" Column="45" TopLine="1918"/>
-      </Position28>
-      <Position29>
-        <Filename Value="mcxgui.pas"/>
-      </Position29>
-      <Position30>
-        <Filename Value="mcxgui.pas"/>
-        <Caret Line="1210" TopLine="1188"/>
-      </Position30>
-    </JumpHistory>
+    <JumpHistory HistoryIndex="-1"/>
   </ProjectOptions>
   <CompilerOptions>
     <Version Value="11"/>
@@ -641,35 +347,4 @@
       </Options>
     </Linking>
   </CompilerOptions>
-  <Debugging>
-    <BreakPoints Count="2">
-      <Item1>
-        <Kind Value="bpkSource"/>
-        <WatchScope Value="wpsLocal"/>
-        <WatchKind Value="wpkWrite"/>
-        <Source Value="/usr/share/fpcsrc/3.0.4/packages/fcl-json/src/jsonscanner.pp"/>
-        <Line Value="304"/>
-      </Item1>
-      <Item2>
-        <Kind Value="bpkSource"/>
-        <WatchScope Value="wpsLocal"/>
-        <WatchKind Value="wpkWrite"/>
-        <Source Value="/usr/share/fpcsrc/3.0.4/packages/fcl-json/src/jsonscanner.pp"/>
-        <Line Value="308"/>
-      </Item2>
-    </BreakPoints>
-    <Watches Count="2">
-      <Item1>
-        <Expression Value="lines.Text"/>
-      </Item1>
-      <Item2>
-        <Expression Value="bufin"/>
-      </Item2>
-    </Watches>
-    <Exceptions Count="1">
-      <Item1>
-        <Name Value="RunError(216)"/>
-      </Item1>
-    </Exceptions>
-  </Debugging>
 </CONFIG>
diff --git a/src/mcx.c b/src/mcx.c
index dbf96d62..0d5998fa 100644
--- a/src/mcx.c
+++ b/src/mcx.c
@@ -2,7 +2,7 @@
 **  \mainpage Monte Carlo eXtreme - GPU accelerated Monte Carlo Photon Migration
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2009-2022
+**  \copyright Qianqian Fang, 2009-2023
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2009) Qianqian Fang and David A. Boas,
diff --git a/src/mcx_bench.c b/src/mcx_bench.c
index a0336f2a..47d74b9c 100644
--- a/src/mcx_bench.c
+++ b/src/mcx_bench.c
@@ -2,7 +2,7 @@
 **  \mainpage Monte Carlo eXtreme - GPU accelerated Monte Carlo Photon Migration
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2009-2022
+**  \copyright Qianqian Fang, 2009-2023
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2009) Qianqian Fang and David A. Boas, 
diff --git a/src/mcx_bench.h b/src/mcx_bench.h
index b1fd32f1..91c72b60 100644
--- a/src/mcx_bench.h
+++ b/src/mcx_bench.h
@@ -2,7 +2,7 @@
 **  \mainpage Monte Carlo eXtreme - GPU accelerated Monte Carlo Photon Migration
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2009-2022
+**  \copyright Qianqian Fang, 2009-2023
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2009) Qianqian Fang and David A. Boas,
diff --git a/src/mcx_const.h b/src/mcx_const.h
index dc470385..82d0a0d7 100644
--- a/src/mcx_const.h
+++ b/src/mcx_const.h
@@ -2,7 +2,7 @@
 **  \mainpage Monte Carlo eXtreme - GPU accelerated Monte Carlo Photon Migration
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2009-2022
+**  \copyright Qianqian Fang, 2009-2023
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2009) Qianqian Fang and David A. Boas,
diff --git a/src/mcx_core.cu b/src/mcx_core.cu
index 4caa3ed5..d16732e3 100644
--- a/src/mcx_core.cu
+++ b/src/mcx_core.cu
@@ -2,7 +2,7 @@
 **  \mainpage Monte Carlo eXtreme - GPU accelerated Monte Carlo Photon Migration
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2009-2022
+**  \copyright Qianqian Fang, 2009-2023
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2009) Qianqian Fang and David A. Boas,
diff --git a/src/mcx_core.h b/src/mcx_core.h
index ff92a668..03636652 100644
--- a/src/mcx_core.h
+++ b/src/mcx_core.h
@@ -2,7 +2,7 @@
 **  \mainpage Monte Carlo eXtreme - GPU accelerated Monte Carlo Photon Migration
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2009-2022
+**  \copyright Qianqian Fang, 2009-2023
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2009) Qianqian Fang and David A. Boas,
diff --git a/src/mcx_ieee754.h b/src/mcx_ieee754.h
index 4bcc8157..8d7b4bd3 100644
--- a/src/mcx_ieee754.h
+++ b/src/mcx_ieee754.h
@@ -2,7 +2,7 @@
 **  \mainpage Monte Carlo eXtreme - GPU accelerated Monte Carlo Photon Migration
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2009-2022
+**  \copyright Qianqian Fang, 2009-2023
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2009) Qianqian Fang and David A. Boas,
diff --git a/src/mcx_mie.cpp b/src/mcx_mie.cpp
index 2eb8639b..55382067 100644
--- a/src/mcx_mie.cpp
+++ b/src/mcx_mie.cpp
@@ -2,7 +2,7 @@
 **  \mainpage Monte Carlo eXtreme - GPU accelerated Monte Carlo Photon Migration
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2009-2022
+**  \copyright Qianqian Fang, 2009-2023
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2009) Qianqian Fang and David A. Boas,
diff --git a/src/mcx_mie.h b/src/mcx_mie.h
index 3219ac1e..b9cc5bc4 100644
--- a/src/mcx_mie.h
+++ b/src/mcx_mie.h
@@ -2,7 +2,7 @@
 **  \mainpage Monte Carlo eXtreme - GPU accelerated Monte Carlo Photon Migration
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2009-2022
+**  \copyright Qianqian Fang, 2009-2023
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2009) Qianqian Fang and David A. Boas,
diff --git a/src/mcx_rand_posix.cu b/src/mcx_rand_posix.cu
index ab26af06..25269c33 100644
--- a/src/mcx_rand_posix.cu
+++ b/src/mcx_rand_posix.cu
@@ -2,7 +2,7 @@
 **  \mainpage Monte Carlo eXtreme - GPU accelerated Monte Carlo Photon Migration
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2009-2022
+**  \copyright Qianqian Fang, 2009-2023
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2009) Qianqian Fang and David A. Boas,
diff --git a/src/mcx_rand_xoroshiro128p.cu b/src/mcx_rand_xoroshiro128p.cu
index 1bd6d679..4533d27c 100644
--- a/src/mcx_rand_xoroshiro128p.cu
+++ b/src/mcx_rand_xoroshiro128p.cu
@@ -2,7 +2,7 @@
 **  \mainpage Monte Carlo eXtreme - GPU accelerated Monte Carlo Photon Migration
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2009-2022
+**  \copyright Qianqian Fang, 2009-2023
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2009) Qianqian Fang and David A. Boas,
diff --git a/src/mcx_rand_xorshift128p.cu b/src/mcx_rand_xorshift128p.cu
index 219aefb8..d6949bf7 100644
--- a/src/mcx_rand_xorshift128p.cu
+++ b/src/mcx_rand_xorshift128p.cu
@@ -2,7 +2,7 @@
 **  \mainpage Monte Carlo eXtreme - GPU accelerated Monte Carlo Photon Migration
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2009-2022
+**  \copyright Qianqian Fang, 2009-2023
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2009) Qianqian Fang and David A. Boas,
diff --git a/src/mcx_shapes.c b/src/mcx_shapes.c
index c393fa8d..c8450f64 100644
--- a/src/mcx_shapes.c
+++ b/src/mcx_shapes.c
@@ -2,7 +2,7 @@
 **  \mainpage Monte Carlo eXtreme - GPU accelerated Monte Carlo Photon Migration
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2009-2022
+**  \copyright Qianqian Fang, 2009-2023
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2009) Qianqian Fang and David A. Boas,
diff --git a/src/mcx_shapes.h b/src/mcx_shapes.h
index d6a99251..3f0ea34f 100644
--- a/src/mcx_shapes.h
+++ b/src/mcx_shapes.h
@@ -2,7 +2,7 @@
 **  \mainpage Monte Carlo eXtreme - GPU accelerated Monte Carlo Photon Migration
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2009-2022
+**  \copyright Qianqian Fang, 2009-2023
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2009) Qianqian Fang and David A. Boas,
diff --git a/src/mcx_tictoc.c b/src/mcx_tictoc.c
index c59009e8..6c1f94a1 100644
--- a/src/mcx_tictoc.c
+++ b/src/mcx_tictoc.c
@@ -2,7 +2,7 @@
 **  \mainpage Monte Carlo eXtreme - GPU accelerated Monte Carlo Photon Migration
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2009-2022
+**  \copyright Qianqian Fang, 2009-2023
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2009) Qianqian Fang and David A. Boas,
diff --git a/src/mcx_tictoc.h b/src/mcx_tictoc.h
index 0a56230b..ac6c13d8 100644
--- a/src/mcx_tictoc.h
+++ b/src/mcx_tictoc.h
@@ -2,7 +2,7 @@
 **  \mainpage Monte Carlo eXtreme - GPU accelerated Monte Carlo Photon Migration
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2009-2022
+**  \copyright Qianqian Fang, 2009-2023
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2009) Qianqian Fang and David A. Boas,
diff --git a/src/mcx_utils.c b/src/mcx_utils.c
index f7b41fd3..d5fa567b 100644
--- a/src/mcx_utils.c
+++ b/src/mcx_utils.c
@@ -2,7 +2,7 @@
 **  \mainpage Monte Carlo eXtreme - GPU accelerated Monte Carlo Photon Migration
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2009-2022
+**  \copyright Qianqian Fang, 2009-2023
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2009) Qianqian Fang and David A. Boas,
@@ -4904,7 +4904,7 @@ int mcx_lookupindex(char* key, const char* index) {
  */
 
 void mcx_version(Config* cfg) {
-    const char ver[] = "$Rev::      $v2022.10";
+    const char ver[] = "$Rev::      $ v2023";
     int v = 0;
     sscanf(ver, "$Rev::%x", &v);
     MCX_FPRINTF(cfg->flog, "MCX Revision %x\n", v);
@@ -4979,7 +4979,7 @@ void mcx_printheader(Config* cfg) {
     MCX_FPRINTF(cfg->flog, S_GREEN"\
 ###############################################################################\n\
 #                      Monte Carlo eXtreme (MCX) -- CUDA                      #\n\
-#          Copyright (c) 2009-2022 Qianqian Fang <q.fang at neu.edu>          #\n\
+#          Copyright (c) 2009-2023 Qianqian Fang <q.fang at neu.edu>          #\n\
 #                             http://mcx.space/                               #\n\
 #                                                                             #\n\
 # Computational Optics & Translational Imaging (COTI) Lab- http://fanglab.org #\n\
@@ -4987,7 +4987,7 @@ void mcx_printheader(Config* cfg) {
 ###############################################################################\n\
 #    The MCX Project is funded by the NIH/NIGMS under grant R01-GM114365      #\n\
 ###############################################################################\n\
-$Rev::      $v2022.10$Date::                       $ by $Author::             $\n\
+$Rev::      $ v2023  $Date::                       $ by $Author::             $\n\
 ###############################################################################\n" S_RESET);
 }
 
diff --git a/src/mcx_utils.h b/src/mcx_utils.h
index fbbefddc..018424ff 100644
--- a/src/mcx_utils.h
+++ b/src/mcx_utils.h
@@ -2,7 +2,7 @@
 **  \mainpage Monte Carlo eXtreme - GPU accelerated Monte Carlo Photon Migration
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2009-2022
+**  \copyright Qianqian Fang, 2009-2023
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2009) Qianqian Fang and David A. Boas,
diff --git a/src/mcxlab.cpp b/src/mcxlab.cpp
index 88c923b3..4498337d 100644
--- a/src/mcxlab.cpp
+++ b/src/mcxlab.cpp
@@ -2,7 +2,7 @@
 **  \mainpage Monte Carlo eXtreme - GPU accelerated Monte Carlo Photon Migration
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2009-2022
+**  \copyright Qianqian Fang, 2009-2023
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2009) Qianqian Fang and David A. Boas,
@@ -1349,7 +1349,7 @@ extern "C" int mcx_throw_exception(const int id, const char* msg, const char* fi
  */
 
 void mcxlab_usage() {
-    printf("MCXLAB v2022.10\nUsage:\n    [flux,detphoton,vol,seeds]=mcxlab(cfg);\n\nPlease run 'help mcxlab' for more details.\n");
+    printf("MCXLAB v2023\nUsage:\n    [flux,detphoton,vol,seeds]=mcxlab(cfg);\n\nPlease run 'help mcxlab' for more details.\n");
 }
 
 /**
diff --git a/src/pmcx.cpp b/src/pmcx.cpp
index d1cae42c..1efeac8d 100644
--- a/src/pmcx.cpp
+++ b/src/pmcx.cpp
@@ -1144,7 +1144,7 @@ int mcx_throw_exception(const int id, const char* msg, const char* filename, con
 
 void print_mcx_usage() {
     std::cout
-            << "PMCX v2022.10\nUsage:\n    output = pmcx.run(cfg);\n\nRun 'help(pmcx.run)' for more details.\n";
+            << "PMCX v2023\nUsage:\n    output = pmcx.run(cfg);\n\nRun 'help(pmcx.run)' for more details.\n";
 }
 
 /**
@@ -1202,7 +1202,7 @@ py::list get_GPU_info() {
 }
 
 PYBIND11_MODULE(_pmcx, m) {
-    m.doc() = "PMCX: Python bindings for Monte Carlo eXtreme photon transport simulator, http://mcx.space";
+    m.doc() = "PMCX (v2023): Python bindings for Monte Carlo eXtreme photon transport simulator, http://mcx.space";
     m.def("run", &pmcx_interface, "Runs MCX with the given config.", py::call_guard<py::scoped_ostream_redirect,
           py::scoped_estream_redirect>());
     m.def("run", &pmcx_interface_wargs, "Runs MCX with the given config.", py::call_guard<py::scoped_ostream_redirect,