updates to documentation for 6.2

KrisThielemans · Jul 23, 2024 · 37636b4 · 37636b4
1 parent bbcdf58
commit 37636b4
Show file tree

Hide file tree

Showing 7 changed files with 182 additions and 12 deletions.
diff --git a/documentation/STIR-UsersGuide.tex b/documentation/STIR-UsersGuide.tex
@@ -44,7 +44,7 @@
 \\[3cm]
 
 \textbf{{\huge User's Guide\\
- Version 6.1}}
+ Version 6.2}}
 \end{center}
 
 \end{spacing}
@@ -1092,17 +1092,18 @@ \subsubsection{
 the same idea while still allowing preserving some of the obliqueness. 
 For instance, for a dataset with 9 segments, \textbf{SSRB} can produce 
 a new dataset with only 3 segments. This essentially increases 
-the axial compression (or \textit{span} in CTI terminology), see the 
+the axial compression (or \textit{span} in CTI/Siemens terminology), see the 
 \textit{STIR} Glossary on axial compression. In addition, \textbf{SSRB} can 
 introduce extra \textit{mashing} (see the \textit{STIR} Glossary) of the data, 
-i.e. add views together.
+i.e. add views and/or TOF bins together.
 
 
 \textit{Usage:}
 
 \cmdline{SSRB output\_filename input\_projdata\_name {\textbackslash} \\
 num\_segments\_to\_combine [num\_views\_to\_combine {\textbackslash}\\
-{[}do\_normalisation [max\_in\_segment\_num\_to\_process ]]]}
+{[}do\_normalisation [max\_in\_segment\_num\_to\_process {\textbackslash}\\
+{[}num\_tof\_bins\_to\_combine ]]]]}
 or
 \cmdline{SSRB --template template\_filename output\_filename input\_projdata\_name [do\_normalisation]}
 
@@ -1116,8 +1117,8 @@ \subsubsection{
 the result is normalised, i.e. divided by \textit{num\_segments\_to\_combine*num\_views\_to\_combine}. 
 This is appropriate for rebinning data where normalisation has 
 already been applied, but inappropriate otherwise.
-
-\item[template\_filename] inicated by the \textit{--template} flag, 
+\item[num\_tof\_bins\_to\_combine] defaults to 1, so TOF bins are not combined.
+\item[template\_filename] indicated by the \textit{--template} flag, 
 is the sinogram type that the \textit{input\_projdata\_name} will 
 be mapped to. This allows for the effective use of 
 \textit{num\_segments\_to\_combine} to be an even number, 
@@ -4446,6 +4447,12 @@ \subsubsection{
   END Relative Difference Prior Parameters:=
   \end{verbatim}
 
+  Note that if you have the \em{CUDA} drivers (and toolkit when building), setting
+  \begin{verbatim}
+  prior type := Cuda Relative Difference Prior
+  \end{verbatim}
+  will enable a \em{CUDA} implementation (with some restrictions). Other parameter
+  settings are identical.
 
 { \subsubsubsection{Logcosh} \label{sec:priors:Logcosh}
 }

diff --git a/documentation/STIR-developers-overview.tex b/documentation/STIR-developers-overview.tex
@@ -16,7 +16,7 @@
 \textbf{{\huge STIR \\
 Overview for developers}}\\
 \textbf{Kris Thielemans}\\
-\textbf{\textit{version 6.0}}
+\textbf{\textit{version 6.2}}
 
 \end{center}
 
@@ -60,8 +60,8 @@ \section{
 doxygen on the source files that come in the STIR distribution). 
 
 \subsection{Language support}
-STIR is written in C++ and currently requires C++-14, but it is compatible with newer versions of the C++ standard.
-We will enforce C++-16 from STIR 6.2.
+STIR is written in C++ and currently requires C++-17, but it is compatible with newer versions of the C++ standard.
+We will enforce C++-20 from STIR 7.0 (possibly earlier).
 
 Python and MATLAB support is provided via \R2Lurl{http://www.swig.org/}{SWIG}. This means that Python/MATLAB interfaces follow
 the C++ classes closely, although some differences are required as these languages do not support templates for instance.
@@ -392,7 +392,7 @@ \subsection{
 with info on the file and line number where the assertion failed.
 
 \subsection{C++ conventions}
-STIR uses C++-14 and is compatible with C++-20 to the best of our knowledge.
+STIR uses C++-17 and is compatible with C++-20 to the best of our knowledge.
 For legacy reasons, we have some preprocessor 
 macros (see \textit{stir/common.h}) to define the stir namespace (see below).
 These should disappear at a 
@@ -622,6 +622,12 @@ \subsubsection{typedefs}
 };
 \end{verbatim}
 
+\section{CUDA support}
+STIR 6.2 introduced first versions of some CUDA code. The include file
+\texttt{cuda\_utilities.h} contains some helpers classes to copy
+arrays to/from the device. This is still work-in-progress as objects
+cannot remain on the device.
+
 \section{
 Overview of classes}
 

diff --git a/documentation/STIR-glossary.tex b/documentation/STIR-glossary.tex
@@ -14,7 +14,7 @@
 \end{center}
 
 \begin{center}
-\textit{Version 6.0}\\
+\textit{Version 6.2}\\
 Originally based on PARAPET Deliverable 4.1,
 Extended for Quantitative Reconstruction and motion compensation
 
@@ -207,7 +207,7 @@ \section*{Different (lossy) data compressions used}
 by the scanner (in list-mode) over the actual number of TOF bins. Currently in STIR, this
 ratio has to be an integer. The size of a TOF bin is computed by multiplying the
 \textbf{TOF mashing factor} with the \textbf{size of unmashed TOF time bins}, with the latter
-defined as a scanner property.\\
+defined as a scanner property. \texttt{SSRB} can be used to increase the TOF mashing factor.\\
 Note that many PET scanners use a \textbf{TOF mashing factor} greater than 1
 for their standard histogrammed projection data.
 

diff --git a/documentation/history.htm b/documentation/history.htm
@@ -11,6 +11,7 @@ <h1>History of public releases of the STIR software</h1>
 The following links give you a summary what has changed. However,
 the ChangeLog is the definite (but tedious) information.
 <ul >
+<li><a href="release_6.2.htm">version 6.2.0 (dated 23 June 2024)</a></li>
 <li><a href="release_6.1.htm">version 6.1.0 (dated 16 May 2024)</a></li>
 <li><a href="release_6.0.htm">version 6.0.0 (dated 07 February 2024)</a></li>
 <li><a href="release_5.2.htm">version 5.2.0 (dated 30 October 2023)</a></li>

diff --git a/git-fame-output.txt b/git-fame-output.txt
@@ -0,0 +1,68 @@
+Total commits: 9090
+Total ctimes: 132759
+Total files: 4764
+Total loc: 298972
+| Author                 |    loc |   coms |   fils |  distribution   |
+|:-----------------------|-------:|-------:|-------:|:----------------|
+| Kris Thielemans        | 212176 |   6343 |   1663 | 71.0/69.8/34.9  |
+| Sanida Mustafovic      |  13223 |    343 |    224 | 4.4/ 3.8/ 4.7   |
+| Nikos Efthimiou        |  13153 |    368 |    287 | 4.4/ 4.0/ 6.0   |
+| Richard Brown          |   9092 |    121 |    438 | 3.0/ 1.3/ 9.2   |
+| Robert Twyman Skelly   |   7121 |    334 |    182 | 2.4/ 3.7/ 3.8   |
+| Daniel Deidda          |   5773 |    316 |    191 | 1.9/ 3.5/ 4.0   |
+| Charalampos Tsoumpas   |   5699 |    371 |    206 | 1.9/ 4.1/ 4.3   |
+| Carles Falcon          |   3196 |      2 |      6 | 1.1/ 0.0/ 0.1   |
+| Markus Jehl            |   2539 |     71 |    398 | 0.8/ 0.8/ 8.4   |
+| Tim Borgeaud           |   2301 |     23 |     52 | 0.8/ 0.3/ 1.1   |
+| Matthew Strugari       |   2204 |     18 |     25 | 0.7/ 0.2/ 0.5   |
+| Parisa Khateri         |   2133 |     26 |     43 | 0.7/ 0.3/ 0.9   |
+| Palak Wadhwa           |   2122 |     68 |     49 | 0.7/ 0.7/ 1.0   |
+| Tobias Beisel          |   2063 |      2 |     24 | 0.7/ 0.0/ 0.5   |
+| Elise Emond            |   1976 |     50 |    141 | 0.7/ 0.6/ 3.0   |
+| Ashley Gillman         |   1465 |     50 |     35 | 0.5/ 0.6/ 0.7   |
+| Matthew Jacobson       |   1419 |     73 |     54 | 0.5/ 0.8/ 1.1   |
+| Alexey Zverovich       |   1125 |      6 |     39 | 0.4/ 0.1/ 0.8   |
+| Ander Biguri           |    962 |     63 |     37 | 0.3/ 0.7/ 0.8   |
+| Jannis Fischer         |    957 |     14 |     32 | 0.3/ 0.2/ 0.7   |
+| Michael Roethlisberger |    762 |      5 |     28 | 0.3/ 0.1/ 0.6   |
+| Ottavia Bertolli       |    673 |     24 |     22 | 0.2/ 0.3/ 0.5   |
+| Ludovica Brusaferri    |    652 |     29 |     22 | 0.2/ 0.3/ 0.5   |
+| Benjamin Thomas        |    604 |     23 |     12 | 0.2/ 0.3/ 0.3   |
+| Edoardo Pasca          |    596 |      2 |     14 | 0.2/ 0.0/ 0.3   |
+| Pablo Aguiar           |    520 |     28 |     24 | 0.2/ 0.3/ 0.5   |
+| Tahereh Niknejad       |    504 |      5 |      4 | 0.2/ 0.1/ 0.1   |
+| stir_maintenance       |    478 |      3 |    267 | 0.2/ 0.0/ 5.6   |
+| Nacer Kerrouche        |    316 |     11 |      6 | 0.1/ 0.1/ 0.1   |
+| Nikos Dikaios          |    310 |     50 |     17 | 0.1/ 0.6/ 0.4   |
+| Gemma Fardell          |    306 |     18 |     13 | 0.1/ 0.2/ 0.3   |
+| Matthias Ehrhardt      |    299 |      6 |     48 | 0.1/ 0.1/ 1.0   |
+| Imraj-Singh            |    296 |     11 |      9 | 0.1/ 0.1/ 0.2   |
+| C. Ross Schmidtlein    |    292 |      2 |      4 | 0.1/ 0.0/ 0.1   |
+| Evgueni Ovtchinnikov   |    287 |     31 |     24 | 0.1/ 0.3/ 0.5   |
+| Patrick Valente        |    236 |      2 |      5 | 0.1/ 0.0/ 0.1   |
+| NicoleJurjew           |    206 |      3 |     12 | 0.1/ 0.0/ 0.3   |
+| Claire Labbe           |    162 |     43 |      8 | 0.1/ 0.5/ 0.2   |
+| Georg Schramm          |    157 |     12 |      9 | 0.1/ 0.1/ 0.2   |
+| David Völgyes          |    125 |     17 |     32 | 0.0/ 0.2/ 0.7   |
+| Nicole Jurjew          |    119 |     19 |      8 | 0.0/ 0.2/ 0.2   |
+| Katie Dinelle          |     85 |      9 |      9 | 0.0/ 0.1/ 0.2   |
+| Daniel Ching           |     56 |      1 |      3 | 0.0/ 0.0/ 0.1   |
+| Harry Tunnicliffe      |     48 |     10 |      2 | 0.0/ 0.1/ 0.0   |
+| Viet Anh Dao           |     44 |      1 |      7 | 0.0/ 0.0/ 0.1   |
+| Gefei Chen             |     36 |      7 |      3 | 0.0/ 0.1/ 0.1   |
+| Sam D Porter           |     31 |      4 |      5 | 0.0/ 0.0/ 0.1   |
+| Ekaterina Mikhaylova   |     31 |     12 |      5 | 0.0/ 0.1/ 0.1   |
+| Casper da Costa-Luis   |     12 |      2 |      2 | 0.0/ 0.0/ 0.0   |
+| Alexander C. Whitehead |      7 |      6 |      2 | 0.0/ 0.1/ 0.0   |
+| license change         |      6 |      1 |      3 | 0.0/ 0.0/ 0.1   |
+| Alaleh Rashidnasab     |      6 |      1 |      2 | 0.0/ 0.0/ 0.0   |
+| Yu-jung Tsai           |      3 |      1 |      1 | 0.0/ 0.0/ 0.0   |
+| Rebecca Gillen         |      2 |      2 |      1 | 0.0/ 0.0/ 0.0   |
+| Jayson Vavrek          |      2 |      1 |      1 | 0.0/ 0.0/ 0.0   |
+| Darren Hague           |      1 |     13 |      1 | 0.0/ 0.1/ 0.0   |
+| Holger Kohr            |      1 |      1 |      1 | 0.0/ 0.0/ 0.0   |
+| tokkot                 |      1 |      1 |      1 | 0.0/ 0.0/ 0.0   |
+| Mahmoud El Katib       |      1 |      1 |      1 | 0.0/ 0.0/ 0.0   |
+| Damiano Belluzzo       |      0 |      3 |      0 | 0.0/ 0.0/ 0.0   |
+| Imraj Singh            |      0 |      4 |      0 | 0.0/ 0.0/ 0.0   |
+| Mustapha Sadki         |      0 |      3 |      0 | 0.0/ 0.0/ 0.0   |
diff --git a/recon_test_pack/OSMAPOSL_test_Parallelproj_CUDARDP.par b/recon_test_pack/OSMAPOSL_test_Parallelproj_CUDARDP.par
@@ -0,0 +1,44 @@
+OSMAPOSLParameters :=
+; test file for OSMAPOSL with a quadratic prior (and ray tracing projection matrix)
+
+objective function type:= PoissonLogLikelihoodWithLinearModelForMeanAndProjData
+PoissonLogLikelihoodWithLinearModelForMeanAndProjData Parameters:=
+
+input file := Utahscat600k_ca_seg4.hs
+zero end planes of segment 0:= 1
+; if disabled, defaults to maximum segment number in the file
+maximum absolute segment number to process := 3
+
+; change to STIR 2.x default for compatibility 
+use subset sensitivities:=0
+sensitivity filename:= RPTsens_seg3_PM.hv
+
+projector pair type := parallelproj
+  Projector Pair Using Parallelproj Parameters:=
+  End Projector Pair Using Parallelproj Parameters:=
+
+prior type := CUDA Relative Difference Prior
+  Relative Difference Prior Parameters:=
+  penalisation factor := 0.5
+  ; next defaults to 0, set to 1 for 2D inverse Euclidean weights, 0 for 3D 
+  only 2D:= 0
+  END Relative Difference Prior Parameters:=
+
+end PoissonLogLikelihoodWithLinearModelForMeanAndProjData Parameters:=
+
+output filename prefix := my_test_image_Parallelproj_CUDARDP
+number of subsets:= 12
+start at subset:= 0
+number of subiterations:= 6
+save estimates at subiteration intervals:= 6
+enforce initial positivity condition:=1
+initial estimate := my_uniform_image_circular.hv
+
+map model := multiplicative
+
+; for compatibility with STIR 1.x
+inter-iteration filter subiteration interval:= 1
+inter-iteration filter type := Truncate To Cylindrical FOV
+Truncate To Cylindrical FOV Parameters:=
+End Truncate To Cylindrical FOV Parameters:=
+END :=
diff --git a/recon_test_pack/OSMAPOSL_test_Parallelproj_RDP.par b/recon_test_pack/OSMAPOSL_test_Parallelproj_RDP.par
@@ -0,0 +1,44 @@
+OSMAPOSLParameters :=
+; test file for OSMAPOSL with a quadratic prior (and ray tracing projection matrix)
+
+objective function type:= PoissonLogLikelihoodWithLinearModelForMeanAndProjData
+PoissonLogLikelihoodWithLinearModelForMeanAndProjData Parameters:=
+
+input file := Utahscat600k_ca_seg4.hs
+zero end planes of segment 0:= 1
+; if disabled, defaults to maximum segment number in the file
+maximum absolute segment number to process := 3
+
+; change to STIR 2.x default for compatibility 
+use subset sensitivities:=0
+sensitivity filename:= RPTsens_seg3_PM.hv
+
+projector pair type := parallelproj
+  Projector Pair Using Parallelproj Parameters:=
+  End Projector Pair Using Parallelproj Parameters:=
+
+prior type := Relative Difference Prior
+  Relative Difference Prior Parameters:=
+  penalisation factor := 5000
+  ; next defaults to 0, set to 1 for 2D inverse Euclidean weights, 0 for 3D 
+  only 2D:= 0
+  END Relative Difference Prior Parameters:=
+
+end PoissonLogLikelihoodWithLinearModelForMeanAndProjData Parameters:=
+
+output filename prefix := my_test_image_Parallelproj_RDP
+number of subsets:= 12
+start at subset:= 0
+number of subiterations:= 6
+save estimates at subiteration intervals:= 6
+enforce initial positivity condition:=1
+initial estimate := my_uniform_image_circular.hv
+
+map model := multiplicative
+
+; for compatibility with STIR 1.x
+inter-iteration filter subiteration interval:= 1
+inter-iteration filter type := Truncate To Cylindrical FOV
+Truncate To Cylindrical FOV Parameters:=
+End Truncate To Cylindrical FOV Parameters:=
+END :=