Merge pull request #1478 from KrisThielemans/v6.2.0prep

V6.2.0prep

Author: KrisThielemans

LICENSE.txt

@@ -1,4 +1,4 @@
-Licensing information for STIR 6.0.0
+Licensing information for STIR 6.2.0
 ----------------------------------
 
 See for more info http://stir.sourceforge.net, section Registration.
@@ -209,6 +209,7 @@ Explicit list of files that carry the PARAPET license
 ./src/include/stir/recon_buildblock/BackProjectorByBinUsingInterpolation.h
 ./src/include/stir/recon_buildblock/SymmetryOperations_PET_CartesianGrid.h
 ./src/include/stir/recon_buildblock/ProjMatrixElemsForOneBin.h
+./src/include/stir/recon_buildblock/distributable.txx
 ./src/include/stir/recon_buildblock/RelatedBins.h
 ./src/include/stir/recon_buildblock/RelatedDensels.inl
 ./src/include/stir/recon_buildblock/ProjMatrixByBin.h
@@ -219,6 +220,7 @@ Explicit list of files that carry the PARAPET license
 ./src/include/stir/CPUTimer.h
 ./src/include/stir/VoxelsOnCartesianGrid.inl
 ./src/include/stir/stream.h
+./src/include/stir/HigherPrecision.h
 ./src/include/stir_experimental/phantoms/Utah.h
 ./src/test/test_ByteOrder.cxx
 ./src/test/test_VectorWithOffset.cxx

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}
 }

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}
 

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.
 

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 July 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>

documentation/release_6.2.htm

@@ -7,14 +7,18 @@
   <body>
     <h1>Summary of changes in STIR release 6.2</h1>
 
-    <p>
-      This version is 100% backwards compatible with STIR 6.1, aside from the default of the
-      tail-fitting of the scatter estimator (see below). However, C++-17 is now required.
-    </p>
 
 <h2>Overall summary</h2>
     <p>
-     
+      This version is 100% backwards compatible with STIR 6.1, aside from a bug fix for
+      the blocks-on-cylindrical set-up which caused the wrong geometry, and a changed
+      default of the tail-fitting of the scatter estimator (see below). However,
+      C++-17 is now required.
+    </p>
+    <p>
+      Main new features are the capability to mash TOF bins (via <tt>SSRB</tt> utility/code)
+      and a CUDA version of the Relative Difference Prior. There are also some
+      import bug fixes, as well as some speed-up (hopefully) in the use of arrays.
     </p>
 
     <p>
@@ -29,15 +33,9 @@ <h2>Overall summary</h2>
 <h2>Patch release info</h2>
 <ul>
   <li>
-    6.2.0 released ??/2024<br>
+    6.2.0 released 23/07/2024<br>
     <a href="https://github.com/UCL/STIR/milestone/11">GitHub Milestone 6.2</a>
   </li>
-  <!--
-      <li> 4.0.1 released 28/04/2020
-        <ul>
-          <li><a href=https://github.com/UCL/STIR/pull/513>PR 513</a>  (suppress warnings with clang)</li>
-        </ul>
-        -->
 </ul>
 
 <h2> Summary for end users (also to be read by developers)</h2>
@@ -56,7 +54,7 @@ <h3>New functionality</h3>
     New prior <code>CudaRelativeDifferencePrior</code> (use <tt>Cuda Relative Difference Prior</tt> in <tt>.par</tt> files), only
     available if the CUDA toolkit is found during building. Results are identical to <code>RelativeDifferencePrior</code>
     up to numerical rounding issues. However, the code is currently limited to 3x3x3 weights.<br>
-    Added timings for the RDP (both non-CUDA and CUDA) tothe  <tt>stir_timings</tt> utility.<br>
+    Added timings for the RDP (both non-CUDA and CUDA) to the <tt>stir_timings</tt> utility.<br>
     <a href=https://github.com/UCL/STIR/pull/1408>PR #1408</a>
   </li>
 </ul>
@@ -70,7 +68,7 @@ <h3>Changed functionality</h3>
     (see <a href=https://github.com/UCL/STIR/issues/1280>issue #1280</a>.<br>
     <strong>WARNING:</strong><i>This potentially changes your scatter estimates</i>. (You can check log files
     of the scatter estimation to see what the scaling factors are.) However,
-    the Siemens mMR example files already lowered the default scale factor to .1, so if you used
+    the Siemens mMR example files already lowered the default scale factor to .1, so if you use(d)
     those, you will get identical results.
   </li>
   <li>
@@ -94,10 +92,10 @@ <h3>Changed functionality</h3>
   <li>
     <tt>SPECT_dicom_to_interfile</tt> improvements:
     <ul>
-      <li>remove requirement for the <tt>is_planar</tt> parameters.    
+      <li>remove requirement for the <tt>is_planar</tt> parameters.
         As STIR can only read SPECT sinograms, we now read/set all fields
         from a planar scan as well. There is therefore no need anymore for
-        the boolean, and it is just ignored.    
+        the boolean, and it is just ignored.
         Output of a conversion of planar data is now directly readable into STIR.
       </li>
       <li>
@@ -131,10 +129,19 @@ <h3>Bug fixes</h3>
 </ul>
 
 <h3>Build system</h3>
-<ul
+<ul>
   <li>
     C++-17 is now required.
   </li>
+  <li>
+    Force C++ version according to CERN ROOT versions: ROOT 6.28.10 needs C++17 and 6.30.2 needs C++20.
+    Also some fixes when relying on <code>root-config</code>.
+  </li>
+  <li>
+    Optionally enable CUDA as a CMake language (for the CUDA RDP). <strong>You should use CMake 3.23 or later</strong>
+    if you use CUDA. If you have the CUDA Toolkit but an old version of CMake that you cannot update,
+    you will have to set <tt>DISABLE_STIR_CUDA</tt> to <tt>ON</tt>.
+  </li>
 </ul>
 
 <h3>Known problems</h3>
@@ -175,7 +182,7 @@ <h3>Other code changes</h3>
     Fixed an incompatibility with C++20.
   </li>
   <li>
-    Enabled OpenMP for <code>Array</code> members <code>find_max(), find_min(), sum(), sum_positivie()</code>.
+    Enabled OpenMP for <code>Array</code> members <code>find_max(), find_min(), sum(), sum_positive()</code>.
     <br>
     <a href=https://github.com/UCL/STIR/pull/1449>PR #1449</a>.
   </li>
@@ -184,18 +191,6 @@ <h3>Other code changes</h3>
   </li>
 </ul>
 
-<h3>Build system</h3>
-<ul>
-  <li>
-    Force C++ version according to CERN ROOT versions: ROOT 6.28.10 needs C++17 and 6.30.2 needs C++20.
-    Also some fixes when relying on <code>root-config</code>.
-  </li>
-  <li>
-    Optionally enable CUDA as a CMake language (for the CUDA RDP). <strong>You should use CMake 3.23 or later</strong>
-    if you use CUDA.
-  </li>
-</ul>
-
 <h3>Test changes</h3>
 
 <h4>C++ tests</h4>
@@ -210,8 +205,8 @@ <h4>C++ tests</h4>
 <h4>recon_test_pack</h4>
 <ul>
   <li>
-    The output of <tt>simulate_PET_data_for_tests.sh</tt> can now varied by setting environment variables, e.g.
-    <code>max_rd</code>.
+    The output of <tt>simulate_PET_data_for_tests.sh</tt> can now be varied by setting environment variables, e.g.
+    <code>max_rd</code>. (Do not forget to unset those variables afterwards!)
   </li>
   <li>
     New test <tt>run_test_SSRB.sh</tt>