From 12114e727551b17a077aa1b51dbd12e932c7413b Mon Sep 17 00:00:00 2001
From: Alice <alice.mazzoleni@psi.ch>
Date: Mon, 1 Sep 2025 15:29:58 +0200
Subject: [PATCH] added documentation

---
 docs/src/ClusterVector.rst        |  7 +++++
 docs/src/pyClusterVector.rst      | 15 ++++++++++-
 include/aare/ClusterVector.hpp    | 12 +++++++++
 python/src/bind_Cluster.hpp       | 11 +++++---
 python/src/bind_ClusterVector.hpp | 44 ++++++++++++++++++++++---------
 5 files changed, 73 insertions(+), 16 deletions(-)

diff --git a/docs/src/ClusterVector.rst b/docs/src/ClusterVector.rst
index 93d2c7b..92376a0 100644
--- a/docs/src/ClusterVector.rst
+++ b/docs/src/ClusterVector.rst
@@ -12,4 +12,11 @@ ClusterVector
    :members:
    :undoc-members:
    :private-members:
+   
+
+**Free Functions:** 
+
+.. doxygenfunction:: aare::reduce_to_3x3(const ClusterVector<Cluster<T, ClusterSizeX, ClusterSizeY, CoordType>>&)
+   
+.. doxygenfunction:: aare::reduce_to_2x2(const ClusterVector<Cluster<T, ClusterSizeX, ClusterSizeY, CoordType>>&)
    
\ No newline at end of file
diff --git a/docs/src/pyClusterVector.rst b/docs/src/pyClusterVector.rst
index ff115c9..0ca2b25 100644
--- a/docs/src/pyClusterVector.rst
+++ b/docs/src/pyClusterVector.rst
@@ -33,4 +33,17 @@ C++ functions that support the ClusterVector or to view it as a numpy array.
     :members:
     :undoc-members:
     :show-inheritance:
-    :inherited-members:
\ No newline at end of file
+    :inherited-members:
+
+
+**Free Functions:** 
+
+.. autofunction:: reduce_to_3x3
+   :noindex:
+
+   Reduce a single Cluster to 3x3 by taking the 3x3 subcluster with highest photon energy.
+
+.. autofunction:: reduce_to_2x2
+   :noindex:
+
+   Reduce a single Cluster to 2x2 by taking the 2x2 subcluster with highest photon energy.
diff --git a/include/aare/ClusterVector.hpp b/include/aare/ClusterVector.hpp
index 48bbbbd..00f4d25 100644
--- a/include/aare/ClusterVector.hpp
+++ b/include/aare/ClusterVector.hpp
@@ -172,6 +172,12 @@ class ClusterVector<Cluster<T, ClusterSizeX, ClusterSizeY, CoordType>> {
     }
 };
 
+/**
+ * @brief Reduce a cluster to a 2x2 cluster by selecting the 2x2 block with the
+ * highest sum.
+ * @param cv Clustervector containing clusters to reduce
+ * @return Clustervector with reduced clusters
+ */
 template <typename T, uint8_t ClusterSizeX, uint8_t ClusterSizeY,
           typename CoordType = uint16_t>
 ClusterVector<Cluster<T, 2, 2, CoordType>> reduce_to_2x2(
@@ -184,6 +190,12 @@ ClusterVector<Cluster<T, 2, 2, CoordType>> reduce_to_2x2(
     return result;
 }
 
+/**
+ * @brief Reduce a cluster to a 3x3 cluster by selecting the 3x3 block with the
+ * highest sum.
+ * @param cv Clustervector containing clusters to reduce
+ * @return Clustervector with reduced clusters
+ */
 template <typename T, uint8_t ClusterSizeX, uint8_t ClusterSizeY,
           typename CoordType = uint16_t>
 ClusterVector<Cluster<T, 3, 3, CoordType>> reduce_to_3x3(
diff --git a/python/src/bind_Cluster.hpp b/python/src/bind_Cluster.hpp
index e7da481..d483ffd 100644
--- a/python/src/bind_Cluster.hpp
+++ b/python/src/bind_Cluster.hpp
@@ -24,7 +24,8 @@ void define_Cluster(py::module &m, const std::string &typestr) {
     py::class_<Cluster<Type, ClusterSizeX, ClusterSizeY, CoordType>>(
         m, class_name.c_str(), py::buffer_protocol())
 
-        .def(py::init([](uint8_t x, uint8_t y, py::array_t<Type> data) {
+        .def(py::init([](uint8_t x, uint8_t y,
+                         py::array_t<Type, py::array::forcecast> data) {
             py::buffer_info buf_info = data.request();
             Cluster<Type, ClusterSizeX, ClusterSizeY, CoordType> cluster;
             cluster.x = x;
@@ -69,7 +70,9 @@ void reduce_to_3x3(py::module &m) {
         [](const Cluster<T, ClusterSizeX, ClusterSizeY, CoordType> &cl) {
             return reduce_to_3x3(cl);
         },
-        py::return_value_policy::move);
+        py::return_value_policy::move,
+        "Reduce cluster to 3x3 subcluster by taking the 3x3 subcluster with "
+        "the highest photon energy.");
 }
 
 template <typename T, uint8_t ClusterSizeX, uint8_t ClusterSizeY,
@@ -81,7 +84,9 @@ void reduce_to_2x2(py::module &m) {
         [](const Cluster<T, ClusterSizeX, ClusterSizeY, CoordType> &cl) {
             return reduce_to_2x2(cl);
         },
-        py::return_value_policy::move);
+        py::return_value_policy::move,
+        "Reduce cluster to 2x2 subcluster by taking the 2x2 subcluster with "
+        "the highest photon energy.");
 }
 
 #pragma GCC diagnostic pop
\ No newline at end of file
diff --git a/python/src/bind_ClusterVector.hpp b/python/src/bind_ClusterVector.hpp
index 5166464..597ae5f 100644
--- a/python/src/bind_ClusterVector.hpp
+++ b/python/src/bind_ClusterVector.hpp
@@ -107,24 +107,44 @@ void define_ClusterVector(py::module &m, const std::string &typestr) {
 template <typename Type, uint8_t ClusterSizeX, uint8_t ClusterSizeY,
           typename CoordType = uint16_t>
 void define_2x2_reduction(py::module &m) {
-    m.def("reduce_to_2x2",
-          [](const ClusterVector<
-              Cluster<Type, ClusterSizeX, ClusterSizeY, CoordType>> &cv) {
-              return new ClusterVector<Cluster<Type, 2, 2, CoordType>>(
-                  reduce_to_2x2(cv));
-          });
+    m.def(
+        "reduce_to_2x2",
+        [](const ClusterVector<
+            Cluster<Type, ClusterSizeX, ClusterSizeY, CoordType>> &cv) {
+            return new ClusterVector<Cluster<Type, 2, 2, CoordType>>(
+                reduce_to_2x2(cv));
+        },
+        R"(
+        
+        Reduce cluster to 2x2 subcluster by taking the 2x2 subcluster with 
+        the highest photon energy."
+        Parameters
+        ----------
+        cv : ClusterVector   
+        )",
+        py::arg("clustervector"));
 }
 
 template <typename Type, uint8_t ClusterSizeX, uint8_t ClusterSizeY,
           typename CoordType = uint16_t>
 void define_3x3_reduction(py::module &m) {
 
-    m.def("reduce_to_3x3",
-          [](const ClusterVector<
-              Cluster<Type, ClusterSizeX, ClusterSizeY, CoordType>> &cv) {
-              return new ClusterVector<Cluster<Type, 3, 3, CoordType>>(
-                  reduce_to_3x3(cv));
-          });
+    m.def(
+        "reduce_to_3x3",
+        [](const ClusterVector<
+            Cluster<Type, ClusterSizeX, ClusterSizeY, CoordType>> &cv) {
+            return new ClusterVector<Cluster<Type, 3, 3, CoordType>>(
+                reduce_to_3x3(cv));
+        },
+        R"(
+        
+        Reduce cluster to 3x3 subcluster by taking the 3x3 subcluster with 
+        the highest photon energy."
+        Parameters
+        ----------
+        cv : ClusterVector   
+        )",
+        py::arg("clustervector"));
 }
 
 #pragma GCC diagnostic pop
\ No newline at end of file