[doc] update documentation for v2024.2

fangq · Mar 7, 2024 · 2d4e355 · 2d4e355
1 parent ebefe98
commit 2d4e355
Show file tree

Hide file tree

Showing 41 changed files with 94 additions and 67 deletions.
diff --git a/ChangeLog.txt b/ChangeLog.txt
@@ -1,5 +1,10 @@
 Change Log
 
+== MMC 2.2.0 (v2024.2, Nougat), Qianqian Fang <q.fang at neu.edu> ==
+
+ 2024-03-07 [ebefe98] [feat] return trajectories data if -M S or cfg.debuglevel contains S
+ 2024-03-05 [10ea5ea] [bug] search 1st and 2nd nearest neighbors for edge-immc to reduce artifact
+
 == MMC 2.0.0 (v2023, Mochi), Qianqian Fang <q.fang at neu.edu> ==
 
  2023-09-17 [6569f48] add comments to nightly build script for deployment

diff --git a/LICENSE.txt b/LICENSE.txt
@@ -3,7 +3,7 @@
 =           Supporting Multi-threading with SSE4, OpenCL and CUDA             =
 ===============================================================================
 
-Copyright (C) 2010-2023  Qianqian Fang <q.fang at neu.edu>
+Copyright (C) 2010-2024  Qianqian Fang <q.fang at neu.edu>
 
 -------------------------------------------------------------------------------
 

diff --git a/README.md b/README.md
@@ -4,8 +4,8 @@ Mesh-based Monte Carlo (MMC) - SSE4 and OpenCL
 
 -   Author: Qianqian Fang (q.fang at neu.edu)
 -   License: GNU General Public License version 3 (GPL v3), see License.txt
--   Version: 2.0.0 (v2023, Mochi)
--   URL: <http://mcx.space/mmc>
+-   Version: 2.2.0 (v2024.2, Nougat)
+-   URL: <https://mcx.space/mmc>
 
 ![Mex and Binaries](https://github.com/fangq/mcxcl/actions/workflows/build_all.yml/badge.svg)
 

diff --git a/README.txt b/README.txt
@@ -6,7 +6,7 @@
 
 *Author:  Qianqian Fang <q.fang at neu.edu>
 *License: GNU General Public License version 3 (GPL v3), see License.txt
-*Version: 2.0.0 (v2023, Mochi)
+*Version: 2.2.0 (v2024.2, Nougat)
 *URL:     http://mcx.space/mmc
 
 ---------------------------------------------------------------------

diff --git a/mmclab/README.txt b/mmclab/README.txt
@@ -2,8 +2,8 @@
 
 *Author: Qianqian Fang <q.fang at neu.edu>
 *License: GNU General Public License version 3 (GPLv3)
-*Version: this package is part of Mesh-based Monte Carlo (MMC) 1.9, v2020
-*URL: http://mcx.space/wiki/?Learn#mmc
+*Version: this package is part of Mesh-based Monte Carlo (MMC) 2.2, v2024.2
+*URL: https://mcx.space/wiki/?Learn#mmc
 
 <toc>
 
@@ -53,24 +53,30 @@ the verbose command line options in MMC.
 
 <pre>
  #############################################################################%
-          MMCLAB - Mesh-based Monte Carlo (MMC) for MATLAB/GNU Octave         %
-           Copyright (c) 2010-2019 Qianqian Fang <q.fang at neu.edu>          %
-                             http://mcx.space/#mmc                            %
+                      Mesh-based Monte Carlo (MMC) - OpenCL                   %
+           Copyright (c) 2010-2024 Qianqian Fang <q.fang at neu.edu>          %
+               https://mcx.space/#mmc  &  https://neurojson.io/               %
                                                                               %
-  Computational Optics & Translational Imaging (COTI) Lab- http://fanglab.org %
-             Department of Bioengineering, Northeastern University            %
+ Computational Optics & Translational Imaging (COTI) Lab  [http://fanglab.org]%
+    Department of Bioengineering, Northeastern University, Boston, MA, USA    %
+ #############################################################################%
+     The MCX Project is funded by the NIH/NIGMS under grant R01-GM114365      %
+ #############################################################################%
+   Open-source codes and reusable scientific data are essential for research, %
+  MCX proudly developed human-readable JSON-based data formats for easy reuse.%
                                                                               %
-                Research funded by NIH/NIGMS grant R01-GM114365               %
+ Please visit our free scientific data sharing portal at https://neurojson.io/%
+  and consider sharing your public datasets in standardized JSON/JData format %
  #############################################################################%
- $Rev::c38804$2019.4$Date::Qianqian Fang          $ by $Author::Qianqian Fang$%
+ $Rev::4ca899$v2024.2$Date::2023-09-11 17:37:07 -04$ by $Author::Qianqian Fang%
  #############################################################################%
 
   Format:
-     [fluence,detphoton,ncfg,seeds]=mmclab(cfg);
+     [fluence,detphoton,ncfg,seeds,traj]=mmclab(cfg);
            or
      fluence=mmclab(cfg);
      newcfg=mmclab(cfg,'prep');
-     [fluence,detphoton,ncfg,seeds]=mmclab(cfg, options);
+     [fluence,detphoton,ncfg,seeds,traj]=mmclab(cfg, options);
 
   Input:
      cfg: a struct, or struct array. Each element in cfg defines 
@@ -178,7 +184,6 @@ the verbose command line options in MMC.
                        source, see cfg.srctype='pattern' for details
                        Example <demo_photon_sharing.m>
        cfg.replaydet:  only works when cfg.outputtype is 'jacobian', 'wl', 'nscat', or 'wp' and cfg.seed is an array
-                       -1 replay all detectors and save in separate volumes (output has 5 dimensions)
                         0 replay all detectors and sum all Jacobians into one volume
                         a positive number: the index of the detector to replay and obtain Jacobians
        cfg.voidtime:   for wide-field sources, [1]-start timer at launch, 0-when entering
@@ -219,6 +224,9 @@ the verbose command line options in MMC.
                         'wp'- weighted scattering counts to build mus Jacobian (replay mode)
        cfg.debuglevel:  debug flag string, a subset of [MCBWDIOXATRPE], no space
        cfg.debugphoton: print the photon movement debug info only for a specified photon ID
+       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.
 
        fields marked with * are required; options in [] are the default values
        fields marked with - are calculated if not given (can be faster if precomputed)
@@ -235,8 +243,6 @@ the verbose command line options in MMC.
              or [size(cfg.elem,1), total-time-gates] if cfg.basisorder=0. 
              The content of the array is the normalized fluence-rate (or others 
              depending on cfg.outputtype) at each mesh node and time-gate.
-             In the "replay" mode, if cfg.replaydet is set to -1 and multiple 
-             detectors exist, fluence.data will add a 5th dimension for the detector number.
 
              If cfg.issaveref is set to 1, fluence(i).dref is not empty, and stores
              the surface diffuse reflectance (normalized by default). The surface mesh
@@ -260,6 +266,14 @@ the verbose command line options in MMC.
        seeds: (optional), if give, mmclab returns the seeds, in the form of
              a byte array (uint8) for each detected photon. The column number
              of seed equals that of detphoton.
+       trajectory: (optional), if given, mmclab returns the trajectory data for
+             each simulated photon. The output has 6 rows, the meanings are
+                id:  1:    index of the photon packet
+                pos: 2-4:  x/y/z/ of each trajectory position
+                     5:    current photon packet weight
+                     6:    enclosing element's ID
+             By default, mcxlab only records the first 1e7 positions along all
+             simulated photons; change cfg.maxjumpdebug to define a different limit.
 
   Example:
        cfg.nphoton=1e5;

diff --git a/mmclab/mmclab.m b/mmclab/mmclab.m
@@ -1,16 +1,22 @@
 function varargout=mmclab(varargin)
 %
 %#############################################################################%
-%         MMCLAB - Mesh-based Monte Carlo (MMC) for MATLAB/GNU Octave         %
-%          Copyright (c) 2010-2020 Qianqian Fang <q.fang at neu.edu>          %
-%                            http://mcx.space/#mmc                            %
+%                     Mesh-based Monte Carlo (MMC) - OpenCL                   %
+%          Copyright (c) 2010-2024 Qianqian Fang <q.fang at neu.edu>          %
+%              https://mcx.space/#mmc  &  https://neurojson.io/               %
 %                                                                             %
-% Computational Optics & Translational Imaging (COTI) Lab- http://fanglab.org %
-%            Department of Bioengineering, Northeastern University            %
+%Computational Optics & Translational Imaging (COTI) Lab  [http://fanglab.org]%
+%   Department of Bioengineering, Northeastern University, Boston, MA, USA    %
+%#############################################################################%
+%    The MCX Project is funded by the NIH/NIGMS under grant R01-GM114365      %
+%#############################################################################%
+%  Open-source codes and reusable scientific data are essential for research, %
+% MCX proudly developed human-readable JSON-based data formats for easy reuse.%
 %                                                                             %
-%               Research funded by NIH/NIGMS grant R01-GM114365               %
+%Please visit our free scientific data sharing portal at https://neurojson.io/%
+% and consider sharing your public datasets in standardized JSON/JData format %
 %#############################################################################%
-%$Rev::      $v2020 $Date::                       $ by $Author::             $%
+%$Rev::      $v2024.2$Date::                       $ by $Author::Qianqian Fang%
 %#############################################################################%
 %
 % Format:

diff --git a/src/mmc.c b/src/mmc.c
@@ -2,7 +2,7 @@
 **  \mainpage Mesh-based Monte Carlo (MMC) - a 3D photon simulator
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2010-2023
+**  \copyright Qianqian Fang, 2010-2024
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2010) Qianqian Fang, <a href="http://www.opticsinfobase.org/abstract.cfm?uri=boe-1-1-165">

diff --git a/src/mmc_bench.h b/src/mmc_bench.h
@@ -2,7 +2,7 @@
 **  \mainpage Mesh-based Monte Carlo (MMC) - a 3D photon simulator
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2010-2023
+**  \copyright Qianqian Fang, 2010-2024
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2010) Qianqian Fang, <a href="http://www.opticsinfobase.org/abstract.cfm?uri=boe-1-1-165">

diff --git a/src/mmc_cl_host.c b/src/mmc_cl_host.c
@@ -2,7 +2,7 @@
 **  \mainpage Mesh-based Monte Carlo (MMC) - a 3D photon simulator
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2010-2023
+**  \copyright Qianqian Fang, 2010-2024
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2010) Qianqian Fang, <a href="http://www.opticsinfobase.org/abstract.cfm?uri=boe-1-1-165">

diff --git a/src/mmc_cl_host.h b/src/mmc_cl_host.h
@@ -2,7 +2,7 @@
 **  \mainpage Mesh-based Monte Carlo (MMC) - a 3D photon simulator
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2010-2023
+**  \copyright Qianqian Fang, 2010-2024
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2010) Qianqian Fang, <a href="http://www.opticsinfobase.org/abstract.cfm?uri=boe-1-1-165">

diff --git a/src/mmc_cl_utils.c b/src/mmc_cl_utils.c
@@ -2,7 +2,7 @@
 **  \mainpage Mesh-based Monte Carlo (MMC) - a 3D photon simulator
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2010-2023
+**  \copyright Qianqian Fang, 2010-2024
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2010) Qianqian Fang, <a href="http://www.opticsinfobase.org/abstract.cfm?uri=boe-1-1-165">

diff --git a/src/mmc_cl_utils.h b/src/mmc_cl_utils.h
@@ -2,7 +2,7 @@
 **  \mainpage Mesh-based Monte Carlo (MMC) - a 3D photon simulator
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2010-2023
+**  \copyright Qianqian Fang, 2010-2024
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2010) Qianqian Fang, <a href="http://www.opticsinfobase.org/abstract.cfm?uri=boe-1-1-165">

diff --git a/src/mmc_const.h b/src/mmc_const.h
@@ -2,7 +2,7 @@
 **  \mainpage Mesh-based Monte Carlo (MMC) - a 3D photon simulator
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2010-2023
+**  \copyright Qianqian Fang, 2010-2024
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2010) Qianqian Fang, <a href="http://www.opticsinfobase.org/abstract.cfm?uri=boe-1-1-165">
@@ -32,9 +32,9 @@
 #ifndef _MCEXTREME_CONSTANT_H
 #define _MCEXTREME_CONSTANT_H
 
-#define MMC_VERSION        "v2023"
+#define MMC_VERSION        "v2024.2"
 #define MMC_VERSION_MAJOR  2
-#define MMC_VERSION_MINOR  0
+#define MMC_VERSION_MINOR  2
 #define MMC_VERSION_PATCH  0
 
 #define DET_MASK           0xFFFF0000

diff --git a/src/mmc_core.cl b/src/mmc_core.cl
@@ -2,7 +2,7 @@
 **  \mainpage Mesh-based Monte Carlo (MMC) - a 3D photon simulator
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2010-2023
+**  \copyright Qianqian Fang, 2010-2024
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2010) Qianqian Fang, <a href="http://www.opticsinfobase.org/abstract.cfm?uri=boe-1-1-165">

diff --git a/src/mmc_cu_host.h b/src/mmc_cu_host.h
@@ -2,7 +2,7 @@
 **  \mainpage Mesh-based Monte Carlo (MMC) - a 3D photon simulator
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2010-2023
+**  \copyright Qianqian Fang, 2010-2024
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2010) Qianqian Fang, <a href="http://www.opticsinfobase.org/abstract.cfm?uri=boe-1-1-165">

diff --git a/src/mmc_fastmath.h b/src/mmc_fastmath.h
@@ -2,7 +2,7 @@
 **  \mainpage Mesh-based Monte Carlo (MMC) - a 3D photon simulator
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2010-2023
+**  \copyright Qianqian Fang, 2010-2024
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2010) Qianqian Fang, <a href="http://www.opticsinfobase.org/abstract.cfm?uri=boe-1-1-165">

diff --git a/src/mmc_highorder.cpp b/src/mmc_highorder.cpp
@@ -2,7 +2,7 @@
 **  \mainpage Mesh-based Monte Carlo (MMC) - a 3D photon simulator
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2010-2023
+**  \copyright Qianqian Fang, 2010-2024
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2010) Qianqian Fang, <a href="http://www.opticsinfobase.org/abstract.cfm?uri=boe-1-1-165">

diff --git a/src/mmc_highorder.h b/src/mmc_highorder.h
@@ -2,7 +2,7 @@
 **  \mainpage Mesh-based Monte Carlo (MMC) - a 3D photon simulator
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2010-2023
+**  \copyright Qianqian Fang, 2010-2024
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2010) Qianqian Fang, <a href="http://www.opticsinfobase.org/abstract.cfm?uri=boe-1-1-165">

diff --git a/src/mmc_host.c b/src/mmc_host.c
@@ -2,7 +2,7 @@
 **  \mainpage Mesh-based Monte Carlo (MMC) - a 3D photon simulator
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2010-2023
+**  \copyright Qianqian Fang, 2010-2024
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2010) Qianqian Fang, <a href="http://www.opticsinfobase.org/abstract.cfm?uri=boe-1-1-165">

diff --git a/src/mmc_host.h b/src/mmc_host.h
@@ -2,7 +2,7 @@
 **  \mainpage Mesh-based Monte Carlo (MMC) - a 3D photon simulator
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2010-2023
+**  \copyright Qianqian Fang, 2010-2024
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2010) Qianqian Fang, <a href="http://www.opticsinfobase.org/abstract.cfm?uri=boe-1-1-165">

diff --git a/src/mmc_mesh.c b/src/mmc_mesh.c
@@ -2,7 +2,7 @@
 **  \mainpage Mesh-based Monte Carlo (MMC) - a 3D photon simulator
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2010-2023
+**  \copyright Qianqian Fang, 2010-2024
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2010) Qianqian Fang, <a href="http://www.opticsinfobase.org/abstract.cfm?uri=boe-1-1-165">

diff --git a/src/mmc_mesh.h b/src/mmc_mesh.h
@@ -2,7 +2,7 @@
 **  \mainpage Mesh-based Monte Carlo (MMC) - a 3D photon simulator
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2010-2023
+**  \copyright Qianqian Fang, 2010-2024
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2010) Qianqian Fang, <a href="http://www.opticsinfobase.org/abstract.cfm?uri=boe-1-1-165">

diff --git a/src/mmc_rand_common.h b/src/mmc_rand_common.h
@@ -2,7 +2,7 @@
 **  \mainpage Mesh-based Monte Carlo (MMC) - a 3D photon simulator
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2010-2023
+**  \copyright Qianqian Fang, 2010-2024
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2010) Qianqian Fang, <a href="http://www.opticsinfobase.org/abstract.cfm?uri=boe-1-1-165">

diff --git a/src/mmc_rand_drand48.c b/src/mmc_rand_drand48.c
@@ -2,7 +2,7 @@
 **  \mainpage Mesh-based Monte Carlo (MMC) - a 3D photon simulator
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2010-2023
+**  \copyright Qianqian Fang, 2010-2024
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2010) Qianqian Fang, <a href="http://www.opticsinfobase.org/abstract.cfm?uri=boe-1-1-165">

diff --git a/src/mmc_rand_drand48.h b/src/mmc_rand_drand48.h
@@ -2,7 +2,7 @@
 **  \mainpage Mesh-based Monte Carlo (MMC) - a 3D photon simulator
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2010-2023
+**  \copyright Qianqian Fang, 2010-2024
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2010) Qianqian Fang, <a href="http://www.opticsinfobase.org/abstract.cfm?uri=boe-1-1-165">

diff --git a/src/mmc_rand_logistic.c b/src/mmc_rand_logistic.c
@@ -2,7 +2,7 @@
 **  \mainpage Mesh-based Monte Carlo (MMC) - a 3D photon simulator
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2010-2023
+**  \copyright Qianqian Fang, 2010-2024
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2010) Qianqian Fang, <a href="http://www.opticsinfobase.org/abstract.cfm?uri=boe-1-1-165">

diff --git a/src/mmc_rand_logistic.h b/src/mmc_rand_logistic.h
@@ -2,7 +2,7 @@
 **  \mainpage Mesh-based Monte Carlo (MMC) - a 3D photon simulator
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2010-2023
+**  \copyright Qianqian Fang, 2010-2024
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2010) Qianqian Fang, <a href="http://www.opticsinfobase.org/abstract.cfm?uri=boe-1-1-165">

diff --git a/src/mmc_rand_posix.c b/src/mmc_rand_posix.c
@@ -2,7 +2,7 @@
 **  \mainpage Mesh-based Monte Carlo (MMC) - a 3D photon simulator
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2010-2023
+**  \copyright Qianqian Fang, 2010-2024
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2010) Qianqian Fang, <a href="http://www.opticsinfobase.org/abstract.cfm?uri=boe-1-1-165">

diff --git a/src/mmc_rand_posix.h b/src/mmc_rand_posix.h
@@ -2,7 +2,7 @@
 **  \mainpage Mesh-based Monte Carlo (MMC) - a 3D photon simulator
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2010-2023
+**  \copyright Qianqian Fang, 2010-2024
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2010) Qianqian Fang, <a href="http://www.opticsinfobase.org/abstract.cfm?uri=boe-1-1-165">

diff --git a/src/mmc_rand_sfmt.c b/src/mmc_rand_sfmt.c
@@ -2,7 +2,7 @@
 **  \mainpage Mesh-based Monte Carlo (MMC) - a 3D photon simulator
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2010-2023
+**  \copyright Qianqian Fang, 2010-2024
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2010) Qianqian Fang, <a href="http://www.opticsinfobase.org/abstract.cfm?uri=boe-1-1-165">

diff --git a/src/mmc_rand_sfmt.h b/src/mmc_rand_sfmt.h
@@ -2,7 +2,7 @@
 **  \mainpage Mesh-based Monte Carlo (MMC) - a 3D photon simulator
 **
 **  \author Qianqian Fang <q.fang at neu.edu>
-**  \copyright Qianqian Fang, 2010-2023
+**  \copyright Qianqian Fang, 2010-2024
 **
 **  \section sref Reference:
 **  \li \c (\b Fang2010) Qianqian Fang, <a href="http://www.opticsinfobase.org/abstract.cfm?uri=boe-1-1-165">