UCL · KrisThielemans · Feb 6, 2023 · Feb 5, 2023 · Feb 6, 2023 · Feb 6, 2023
diff --git a/documentation/release_5.1.htm b/documentation/release_5.1.htm
@@ -138,6 +138,7 @@ <h3>Build system and dependencies</h3>
     </li>
     <li>Various <code>find_package</code> statements and messages have been improved, see
       e.g. <a href="https://github.com/UCL/STIR/pull/1140/">PR #1140</a>.
+    </li>
 </ul>
 
 

diff --git a/documentation/release_5.2.htm b/documentation/release_5.2.htm
@@ -0,0 +1,79 @@
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+<html>
+  <head>
+    <title>Summary of changes in STIR release 5.2</title>
+  </head>
+
+  <body>
+    <h1>Summary of changes in STIR release 5.2</h1>
+
+<p>This version is 100% backwards compatible with STIR 5.0.
+</p>
+<h2>Overall summary</h2>
+
+<p>Of course, there is also the usual code-cleanup and 
+  improvements to the documentation. See also <a href="https://github.com/UCL/STIR/milestone/6">the
+    5.2 milestone on GitHub</a>.
+</p>
+<p>Overall code management and assistance by Kris Thielemans (UCL and ASC).</p>
+
+<h2>Patch release info</h2>
+<ul>
+  <li> 5.2.0 released ??/??/2023</li>
+</ul>
+
+<h2> Summary for end users (also to be read by developers)</h2>
+
+<h3>Bug fixes</h3>
+<ul>
+</ul>
+
+<h3>New functionality</h3>
+<ul>
+</ul>
+
+<h3>New examples</h3>
+<ul>
+</ul>
+
+<h4>Python</h4>
+<ul>
+</ul>
+
+<h3>Changed functionality</h3>
+<ul>
+  <li>energy resolution functions and keywords have now more documentation. <code>Scanner::check_consistency</code> also checks if the energy resolution is less than 20 (as it is FWHM/reference_energy).
+  <a href="https://github.com/UCL/STIR/pull/1149/">PR #1149</a>.
+  </li>
+</ul>
+
+<h3>Build system and dependencies</h3>
+<ul>
+</ul>
+
+
+<h3>Known problems</h3>
+<ul>
+<li>See <a href=https://github.com/UCL/STIR/labels/bug>our issue tracker</a>.</li>
+</ul>
+
+
+<h3>Minor (?) bug fixes</h3>
+<ul>
+</ul>
+
+<h3>Documentation changes</h3>
+<ul>
+</ul>
+
+<h3>recon_test_pack changes</h3>
+<ul>
+</ul>
+
+<h3>Other changes to tests</h3>
+<ul>
+  <li><tt>test_Scanner.cxx</tt> tests for energy resolution. <a href="https://github.com/UCL/STIR/pull/1149/">PR #1149</a>.</li>
+</ul>
+</body>
+
+</html>
diff --git a/examples/samples/PET_Interfile_header.hs b/examples/samples/PET_Interfile_header.hs
@@ -38,11 +38,13 @@ image duration (sec)[1] := 3
 image relative start time (sec)[1] := 1
 
 number of energy windows:=1
+; lower/upper level (in keV)
 energy window lower level[1]:=425
 energy window upper level[1]:=650
 
 Scanner parameters:= 
 Scanner type := unknown
+; energy resolution as a fraction at the reference energy
 Energy resolution := 0.145
 Reference energy (in keV) := 511
 

diff --git a/src/buildblock/Scanner.cxx b/src/buildblock/Scanner.cxx
@@ -4,7 +4,7 @@
     Copyright (C) 2011, Kris Thielemans
     Copyright (C) 2010-2013, King's College London
     Copyright 2017 ETH Zurich, Institute of Particle Physics and Astrophysics
-    Copyright (C) 2013-2016,2019-2021 University College London
+    Copyright (C) 2013-2016,2019-2021, 2923 University College London
     Copyright (C) 2017-2018, University of Leeds
     This file is part of STIR.
 
@@ -1197,6 +1197,14 @@ check_consistency() const
 
   }
 
+  if (this->energy_resolution > 20.F)
+    {
+      warning("Scanner: energy resolution is a ratio (FWHM/reference_energy) and expected to be less than 1 "
+              "(although we allow up to 20 to denote no energy information), but it is set to " +
+              std::to_string(this->energy_resolution));
+      return Succeeded::no;
+    }
+
   return Succeeded::yes;
 }
 
@@ -1381,11 +1389,10 @@ Scanner* Scanner::ask_parameters()
   // old scanners. This should stay here as a transitional step.
   if (scanner_ptr->type != Unknown_scanner && scanner_ptr->type != User_defined_scanner)
     {
-      info("more options are available for the scanner: \n(a) Energy Resolution :=\n(b) Reference energy (in keV)\t:="
-        "\n(c) Scanner geometry ( BlocksOnCylindrical / Cylindrical / Generic ) \n(d) Scanner orientation (X or Y)\t:="
-        "\n\n(a) and (b) are used in Scatter Simulation. \n (c) is used to choose more precise models of the scanner. "
-        "\n(d) is used in BlocksOnCylindrical Geometry to build the proper crystal map."
-        "\nIn case, you need them, set them manually in your interfile header before 'end scanner parameters:='.");
+      if (!scanner_ptr->has_energy_information())
+          warning("Energy information not set, which is needed in scatter simulation. If you need it, set"
+               "\n Energy Resolution :=\n Reference energy (in keV)\t:="
+               "\nmanually in your interfile header before 'end scanner parameters:='.");
 
       //This is needed for finding effective central bin size, because it is different for different geometries.
       const string ScannerGeometry =
@@ -1445,7 +1452,7 @@ Scanner* Scanner::ask_parameters()
         ask_num("Enter number of transaxial crystals per singles unit: ", 0, num_detectors_per_ring, 1);
 
      float EnergyResolution =
-          ask_num("Enter the energy resolution of the scanner : ", 0.0f, 1000.0f, -1.0f);
+          ask_num("Enter the energy resolution (as FWHM/reference_energy) of the scanner (expected to be less than 1): ", 0.0f, 20.0f, -1.0f);
 
       float ReferenceEnergy =
           ask_num("Enter the reference energy for the energy resolution (in keV):", 0.0f, 1000.0f, -1.0f);

diff --git a/src/include/stir/IO/InterfileHeader.h b/src/include/stir/IO/InterfileHeader.h
@@ -282,9 +282,10 @@ class InterfilePDFSHeader : public InterfileHeader
   int num_axial_crystals_per_singles_unit;
   int num_transaxial_crystals_per_singles_unit;
   int num_detector_layers;
-  //! Energy resolution of the system in keV.
+  //! Energy resolution of the scanner at the reference energy as a ratio
+  /*! An energy resolution of 0.1 indicates a 10 percent FWHM */
   float energy_resolution;
-  //! Reference energy.
+  //! Reference energy used for the energy resolution
   float reference_energy;
 
   //! \name new variables for block geometry

diff --git a/src/include/stir/Scanner.h b/src/include/stir/Scanner.h
@@ -2,7 +2,7 @@
     Copyright (C) 2000 PARAPET partners
     Copyright (C) 2000-2010, Hammersmith Imanet Ltd
     Copyright (C) 2011-2013, King's College London
-    Copyright (C) 2016, 2019, 2021 UCL
+    Copyright (C) 2016, 2019, 2021, 2023 UCL
     Copyright 2017 ETH Zurich, Institute of Particle Physics and Astrophysics
     Copyright (C 2017-2018, University of Leeds
     This file is part of STIR.
@@ -344,15 +344,22 @@ class Scanner
 
   //@} (end of get geometrical info)
 
-   //! \name Functions to get detector responce info
+   //! \name Functions to get detector response info
   //@{
 
-  //! get the energy resolution of the system
+  //! get the energy resolution as a fraction at the reference energy
+  /*! Values for PET scanners are around 0.1 at 511 keV, depending on the scanner of course.
+
+    If less than or equal to 0, it is assumed to be unknown.
+  */
   inline float get_energy_resolution() const;
-  //! get the reference energy of the energy resolution
+  //! get the reference energy in keV of the energy resolution
+  /*! For PET, normally set to 511 */
   inline float get_reference_energy() const;
+  //! \c true if energy_resolution and reference_energy are set
+  inline bool has_energy_information() const;
 
-  //@} (end of get detector responce info)
+  //@} (end of get detector response info)
 
   //! \name Functions setting info
   /*! Be careful to keep consistency by setting all relevant parameters.
@@ -425,13 +432,12 @@ class Scanner
 
   //@} (end of block/bucket info)
   //! set the energy resolution of the system
-  //! A negative value indicates, unknown || not set
+  /*! \sa get_energy_resolution() */
   inline void set_energy_resolution(const float new_num);
-  //! set the reference energy of the energy resolution
-  //! A negative value indicates, unknown || not set
+  //! set the reference energy (in keV) of the energy resolution
+  /*! \sa get_reference_energy() */
   inline void set_reference_energy(const float new_num);
 
-  inline bool has_energy_information() const;
   //@} (end of set info)
 
   // Calculate a singles bin index from axial and transaxial singles bin coordinates.
@@ -491,8 +497,7 @@ class Scanner
   int num_transaxial_crystals_per_singles_unit;
 
    //!
-  //! \brief energy_resolution
-  //! \author Nikos Efthimiou
+  //! \brief energy resolution (FWHM as a fraction of the reference_energy)
   //! \details This is the energy resolution of the system.
   //! A negative value indicates, unknown.
   //! This value is dominated by the material of the scintilation crystal

diff --git a/src/include/stir/scatter/ScatterSimulation.h b/src/include/stir/scatter/ScatterSimulation.h
@@ -281,6 +281,18 @@ class ScatterSimulation : public RegisteredObject<ScatterSimulation>
      * @{
      */
 
+    //! gamma-energy-part of the detection efficiency
+    /*! 
+      Formula used is based on a Gaussian pdf for the efficiency, with
+      \f[ FWHM_E = \alpha  \sqrt(E) \f]
+      where the proportionality constant \f$\alpha\f$ is determined by the
+      energy FWHM of the Scanner at the reference energy.
+
+      This pdf is then integrated from the lower to the upper energy window limits.
+
+      \sa Scanner::get_energy_resolution
+      \sa Scanner::get_reference_energy
+    */
     float detection_efficiency(const float energy) const;
 
 

diff --git a/src/scatter_buildblock/scatter_detection_modelling.cxx b/src/scatter_buildblock/scatter_detection_modelling.cxx
@@ -116,6 +116,18 @@ detection_efficiency(const float energy) const
   if (!this->_already_set_up)
         error("ScatterSimulation::find_detectors: need to call set_up() first");
 #endif
+  /*
+    motivation for formula:
+
+    FWHM_at_E = alpha * sqrt(E)
+
+    FWHM_at_ref = alpha * sqrt[E_ref)
+    = E_ref * resolution
+
+    hence
+
+    alpha = sqrt(E_ref) *resolution_at_ref
+  */
 
   // factor 2.35482 is used to convert FWHM to sigma
   const float sigma_times_sqrt2=
-Original file line number
+Diff line change
@@ Expand Up / @@ -138,6 +138,7 @@ <h3>Build system and dependencies</h3> @@
         </li>
         <li>Various <code>find_package</code> statements and messages have been improved, see
           e.g. <a href="https://github.com/UCL/STIR/pull/1140/">PR #1140</a>.
+        </li>
     </ul>
@@ Expand Down @@