[doc] update documentation for v2024.2

ChangeLog.txt

@@ -4,6 +4,10 @@ Major updates are marked with a "*"
 
 == MCX v2024.2 (Interstellar Ion - 2.2), FangQ <q.fang (a) neu.edu> ==
 
+ 2024-03-13 [abdee14] [bug] fix multi-source replay bug, close #215
+ 2024-03-11 [9250a0d] [doc] make final doc update, bump pmcx to v0.3.2
+ 2024-03-10 [4e7f404] [ci] revert to windows-2019, add help info for #214, add note on nvidia-uvm
+ 2024-03-10 [2750d70] [ci] choco install is failing on Windows, see actions/runner-images#9477
  2024-03-10 [7b6e0e0] [optimize] cut hyperboloid gaussian register use from 15 to 3, #127,#214
  2024-03-10 [a2279d6] [optimize] reduce gaussian slit register use from 9 to 2, #214
  2024-03-08 [4708e10] [doc] Create pull_request_template.md

TODO.txt

@@ -2,16 +2,16 @@
 
 == Short term projects ==
 
-*. 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 ==
 
+[done] *. support mua/mus/g/n 8-byte continuous media format [opened by FangQ, 2023/08/12]
+[done] *. support simulations of multiple sources of the same type [https://github.com/fangq/mcx/issues/163]
+[done] *. support user-defined photon emission angular distribution [https://github.com/fangq/mcx/issues/129]
 [done] *. fluorescent material support via pattern3d source [2009/09/30, FangQ]
 [done] *. support multi-byte medium [2017/01/01, FangQ] [mcx/issues/21]
 [done] *. extend the reflection model to support mis-match at internal boundaries [2010/07/29, FangQ]

manpage/mcxcontest.1

@@ -1,26 +1,21 @@
 .\" Manpage for mcxcontest.
 .\" Contact [email protected] to correct errors or typos.
-.TH man 7 "08 February 2020" "v2021.2" "mcxcontest man page"
+.TH man 7 "14 March 2024" "v2024.2" "mcxcontest man page"
 .SH NAME
 mcxcontest \- benchmark your NVIDIA GPU hardware using MCX built-in tests
 .SH SYNOPSIS
 mcxcontest <option1> <option2> ...
 .SH DESCRIPTION
-Monte Carlo eXtreme (mcx) is a CUDA-based GPU-accelerated 3D photon transport 
-simulator developed by Dr. Qianqian Fang at the Computational Optics and 
-Translational Imaging (COTI) Lab, at Northeastern University, Boston,
+Monte Carlo eXtreme (mcx) is a CUDA-based GPU-accelerated 3D photon transportsimulator developed by Dr. Qianqian Fang at the Computational Optics andTranslational Imaging (COTI) Lab, at Northeastern University, Boston,
 USA. More details regarding mcx can be found at http://mcx.space/
 
 The `mcxcontest` script benchmarks your NVIDIA GPU using 3 built-in tests
-in `mcx`, namely `cube60`, `cube60b` and `cube60planar`. By default, a total 
-of 10^8 photons will be simulated and the running speed, in photon/ms, for 
-each benchmark is reported. The final score of the GPU is the summation of
+in `mcx`, namely `cube60`, `cube60b` and `cube60planar`. By default, a totalof 10^8 photons will be simulated and the running speed, in photon/ms, foreach benchmark is reported. The final score of the GPU is the summation of
 the 3 speed readings. The higher the score, the faster the GPU hardware.
 
 This script is written in Perl. If utility `curl` is installed, it uses
 `curl` to submit the hardware score to our database, should a user choose to
-do so. If `curl` is not installed, mcxcontest requires `LWP::UserAgent` and 
-`LWP::Simple` Perl modules to submit the user data.
+do so. If `curl` is not installed, mcxcontest requires `LWP::UserAgent` and`LWP::Simple` Perl modules to submit the user data.
 
 
 .SH OPTIONS
@@ -44,9 +39,7 @@ Use `-c` to generate JSON formatted benchmark reports in the compact format.
 
 .TP
 \fB-o 'additional mcx parameters'\fR
-Using `-o`, one can attach additional command line parameters to overwrite the 
-default MCX benchmark parameters. Therefore, any standard parameters permitted by 
-MCX is allowed to be used with this command.
+Using `-o`, one can attach additional command line parameters to overwrite thedefault MCX benchmark parameters. Therefore, any standard parameters permitted byMCX is allowed to be used with this command.
 
 .TP
 \fB-L\fR
@@ -68,8 +61,7 @@ GPU database URL is http://mcx.space/gpubench/
 
 .TP
 \fB--post URL_to_post_results_to_database\fR
-Use `--post` to set the database submission URL to a different location; the 
-default MCX GPU database URL is http://mcx.space/gpubench/gpucontest.cgi
+Use `--post` to set the database submission URL to a different location; thedefault MCX GPU database URL is http://mcx.space/gpubench/gpucontest.cgi
 
 .TP
 \fB--help\fR

manpage/mcxshow.1

@@ -1,17 +1,13 @@
 .\" Manpage for mcxshow.
 .\" Contact [email protected] to correct errors or typos.
-.TH man 7 "08 February 2020" "v2021.2" "v2020" "mcxshow man page"
+.TH man 7 "14 March 2024" "v2024.2" "mcxshow man page"
 .SH NAME
 mcxshow \- a 3D previewer for MCX/MCXCL/MMC photon transport simulations
 .SH SYNOPSIS
 mcxshow <-f input.json>
 .SH DESCRIPTION
 MCX Show is an OpenGL based 3D renderer for previewing photon simulation domain
-settings in mcx/mmc. Monte Carlo eXtreme (mcx) and Mesh-based Monte Carlo (mmc) are 
-rigirously validated, physically-accurate and GPU-accelerated 3D photon transport 
-simulators. The MCX/MMC simulators are developed by Dr. Qianqian Fang at the 
-Computational Optics and Translational Imaging (COTI) Lab, at Northeastern 
-University, Boston, USA. More details regarding mcx/mmc can be found at http://mcx.space
+settings in mcx/mmc. Monte Carlo eXtreme (mcx) and Mesh-based Monte Carlo (mmc) arerigirously validated, physically-accurate and GPU-accelerated 3D photon transportsimulators. The MCX/MMC simulators are developed by Dr. Qianqian Fang at theComputational Optics and Translational Imaging (COTI) Lab, at NortheasternUniversity, Boston, USA. More details regarding mcx/mmc can be found at http://mcx.space
 
 .SH OPTIONS
 If `mcxshow` command is executed without parameter, it opens a blank window, and

manpage/mcxstudio.1

@@ -1,6 +1,6 @@
 .\" Manpage for mcxstudio.
 .\" Contact [email protected] to correct errors or typos.
-.TH man 7 "08 February 2020" "v2021.2" "Monte Carlo eXtreme (MCX) Studio man page"
+.TH man 7 "14 March 2024" "v2024.2" "Monte Carlo eXtreme (MCX) Studio man page"
 .SH NAME
 MCXStudio \- a cross-platform GUI for managing MCX/MCXCL/MMC simulations
 .SH SYNOPSIS
@@ -11,8 +11,7 @@ MCXStudio is a light-weight graphical user interface (GUI) for MCX, MMC and MCX-
 parameters for a wide range of simulations. It also provides functionalities to
 save, edit and reopen a set of pre-defined simulations and share among users.
 
-The MCX//MCXCL/MMC simulators are developed by Dr. Qianqian Fang at the Computational 
-Optics and Translational Imaging (COTI) Lab, at Northeastern University, Boston,
+The MCX//MCXCL/MMC simulators are developed by Dr. Qianqian Fang at the ComputationalOptics and Translational Imaging (COTI) Lab, at Northeastern University, Boston,
 USA. More details regarding mcx/mmc can be found at http://mcx.space
 
 MCXStudio is written in Object Pascal using the open-source Lazarus
@@ -89,8 +88,7 @@ line options are accepted
 Use -f to specify a default MCX project file (*.mcxp)
     -f filename.mcxp
 
-If a .mcxp file is specified via the -p flag, mcxstudio loads this project file 
-at start time.
+If a .mcxp file is specified via the -p flag, mcxstudio loads this project fileat start time.
 
 .TP
 \fB-u/--user\fR
@@ -100,11 +98,9 @@ directory where `~` represents user's home directory. You should use this comman
 when mcxstudio is installed via an automated installer and is located in a system
 folder (such as `/usr/bin`).
 
-If this flag is not provided while `mcxstudio` was installed in a system folder 
-without write-permission, mcxstudio will attempt to create an output folder
+If this flag is not provided while `mcxstudio` was installed in a system folderwithout write-permission, mcxstudio will attempt to create an output folder
 named `MCXOutput` under the same parent folder as mcxstudio executable. If this
-fails, it falls back to creating and writing outputs to `~/MCXOutput`. If 
-`~/MCXOutput` can not be created or can not be written, mcx/mmc/mcxcl commands
+fails, it falls back to creating and writing outputs to `~/MCXOutput`. If`~/MCXOutput` can not be created or can not be written, mcx/mmc/mcxcl commands
 will throw an error.
 
 

manpage/mcxviewer.1

@@ -1,31 +1,25 @@
 .\" Manpage for mcxviewer.
 .\" Contact [email protected] to correct errors or typos.
-.TH man 7 "08 February 2020" "v2021.2" "mcxviewer man page"
+.TH man 7 "14 March 2024" "v2024.2" "mcxviewer man page"
 .SH NAME
 mcxviewer \- a 3D NIfTI/MC2 volumetric data renderer for MCX/MCXCL/MMC photon transport simulations
 .SH SYNOPSIS
 mcxviewer <-f input.nii>
 .SH DESCRIPTION
 MCX Viewer is an OpenGL based 3D renderer for visualization of the volumetric output
-from MCX/MCXCL/MMC. Monte Carlo eXtreme (mcx) and Mesh-based Monte Carlo (mmc) are 
-rigirously validated, physically-accurate and GPU-accelerated 3D photon transport 
-simulators. The MCX/MMC simulators are developed by Dr. Qianqian Fang at the 
-Computational Optics and Translational Imaging (COTI) Lab, at Northeastern 
-University, Boston, USA. More details regarding mcx/mmc can be found at http://mcx.space
+from MCX/MCXCL/MMC. Monte Carlo eXtreme (mcx) and Mesh-based Monte Carlo (mmc) arerigirously validated, physically-accurate and GPU-accelerated 3D photon transportsimulators. The MCX/MMC simulators are developed by Dr. Qianqian Fang at theComputational Optics and Translational Imaging (COTI) Lab, at NortheasternUniversity, Boston, USA. More details regarding mcx/mmc can be found at http://mcx.space
 
 .SH OPTIONS
 If `mcxviewer` command is executed without parameter, it opens a blank window, and
-user can click on the toolbar to load a .mc2/.nii MCX/MCXCL volumetric output file 
-to render.
+user can click on the toolbar to load a .mc2/.nii MCX/MCXCL volumetric output fileto render.
 
 However, one can also use the below options to load a default input file:
 
 .TP
 \fB-f/--file\fR
 .TP
 Use `-f` or `--file` flag to specify an MCX/MCXCL .nii output file.
-Currently, only 32-bit floating point data are accepted (default output format for 
-mcx/mcxcl)
+Currently, only 32-bit floating point data are accepted (default output format formcx/mcxcl)
 
 .SH SEE ALSO
 mcx(7), mmc(7), mcxcl(7), photon(7), mcxstudio(7), mcxshow(7)

manpage/photon.1

@@ -1,37 +1,30 @@
 .\" Manpage for photon.
 .\" Contact [email protected] to correct errors or typos.
-.TH man 7 "08 February 2020" "v2021.2" "photon man page"
+.TH man 7 "14 March 2024" "v2024.2" "photon man page"
 .SH NAME
 photon \- a unified command line interface for running MCX/MMC photon simulations
 .SH SYNOPSIS
 photon <option1> <option2> ...
 .SH DESCRIPTION
 Monte Carlo eXtreme (mcx) and Mesh-based Monte Carlo (mmc) are rigirously
 validated, physically-accurate and GPU-accelerated 3D photon transport simulators.
-The MCX/MMC simulators are developed by Dr. Qianqian Fang at the Computational 
-Optics and Translational Imaging (COTI) Lab, at Northeastern University, Boston,
+The MCX/MMC simulators are developed by Dr. Qianqian Fang at the ComputationalOptics and Translational Imaging (COTI) Lab, at Northeastern University, Boston,
 USA. More details regarding mcx/mmc can be found at http://mcx.space
 
-To simplify running mcx/mmc simulations, we have created a unified graphical user 
-interface (GUI) `mcxstudio`, and a unified command line interface `photon`.
-The command `photon` is a perl script that automatically selects between 
-`mcx` (CUDA-based), `mcxcl` (OpenCL based), and `mmc` (SSE4 CPU/OpenCL) based
+To simplify running mcx/mmc simulations, we have created a unified graphical userinterface (GUI) `mcxstudio`, and a unified command line interface `photon`.
+The command `photon` is a perl script that automatically selects between`mcx` (CUDA-based), `mcxcl` (OpenCL based), and `mmc` (SSE4 CPU/OpenCL) based
 on the following command line flags and input file data structures. In other
 words, one can simply replace a command starting with `mcx`, `mcxcl` and `mmc`
 by `photon` and photon runs the simulation according to a set of heuristics.
 
 
 .SH OPTIONS
-Running `photon` without any parameter prints the help information. 
-
-If additional command line flags are used, `photon` by default treats the input 
-flags in the format that are supported by `mcx`; however, `photon` further parses
-the use simulation input file and flags, and determines if `mmc` or `mcxcl` 
-should be used instead.
+Running `photon` without any parameter prints the help information.
+If additional command line flags are used, `photon` by default treats the inputflags in the format that are supported by `mcx`; however, `photon` further parses
+the use simulation input file and flags, and determines if `mmc` or `mcxcl`should be used instead.
 
 The supported options are fully compatible with those from MCX/MMC/MCXCL. Photon
-determines which of the simulators among mcx/mmc/mcxcl based on a set of simple 
-tests, the selected simulator and their conditions are listed below
+determines which of the simulators among mcx/mmc/mcxcl based on a set of simpletests, the selected simulator and their conditions are listed below
 
 .TP
 \fBchoose mmc\fR
@@ -48,8 +41,7 @@ and mcx -L failed to list any CUDA devices
 
 .TP
 \fBchoose mcx\fR
-when input does not contain mesh data, 
-and when `mcx -L` outputs valid CUDA devices
+when input does not contain mesh data,and when `mcx -L` outputs valid CUDA devices
 
 .TP
 \fB--mcx\fR