docs(observers): docstrings and rst file for wind velocities and ther…

…mo observers

docs/source/cxx/observers/thermo_observer.rst

@@ -1,14 +1,42 @@
-XXX Observer
-============
+Thermodynamics Observer
+=======================
 
-// TODO(CB) write doc
+Header file: ``<libs/observers/thermo_observer.hpp>``
+`[source] <https://github.com/yoctoyotta1024/CLEO/blob/main/libs/observers/thermo_observer.hpp>`_
 
-Header file: ``<libs/observers/XXX_observer.hpp>``
-`[source] <https://github.com/yoctoyotta1024/CLEO/blob/main/libs/observers/XXX_observer.hpp>`_
+.. doxygenfunction:: CollectThermoVariable
+   :project: observers
+
+.. doxygenstruct:: PressFunc
+   :project: observers
+   :private-members:
+   :protected-members:
+   :members:
+   :undoc-members:
 
-.. doxygenstruct:: XXXObserver
+.. doxygenstruct:: TempFunc
    :project: observers
    :private-members:
    :protected-members:
    :members:
    :undoc-members:
+
+.. doxygenstruct:: QvapFunc
+   :project: observers
+   :private-members:
+   :protected-members:
+   :members:
+   :undoc-members:
+
+.. doxygenstruct:: QcondFunc
+   :project: observers
+   :private-members:
+   :protected-members:
+   :members:
+   :undoc-members:
+
+.. doxygenfunction:: CollectThermo
+   :project: observers
+
+.. doxygenfunction:: ThermoObserver
+   :project: observers

docs/source/cxx/observers/windvel_observer.rst

@@ -4,6 +4,9 @@ WindVel Observer
 Header file: ``<libs/observers/windvel_observer.hpp>``
 `[source] <https://github.com/yoctoyotta1024/CLEO/blob/main/libs/observers/windvel_observer.hpp>`_
 
+.. doxygenfunc:: CollectWindVariable
+   :project: observers
+
 .. doxygenstruct:: WvelFunc
    :project: observers
    :private-members:
@@ -25,9 +28,6 @@ Header file: ``<libs/observers/windvel_observer.hpp>``
    :members:
    :undoc-members:
 
-.. doxygenfunction:: WindVelObserver
-   :project: observers
-
 .. doxygenfunction:: CollectWindVel
    :project: observers
 

libs/observers/thermo_observer.hpp

@@ -9,7 +9,7 @@
  * Author: Clara Bayley (CB)
  * Additional Contributors:
  * -----
- * Last Modified: Tuesday 9th April 2024
+ * Last Modified: Thursday 11th April 2024
  * Modified By: CB
  * -----
  * License: BSD 3-Clause "New" or "Revised" License
@@ -38,9 +38,23 @@
 #include "gridboxes/gridbox.hpp"
 #include "zarr/dataset.hpp"
 
-/* returns CollectDataForDataset which writes a state variable from
-each gridbox to an array in a dataset in a given store for a given datatype and using a given
-function-like functor */
+/**
+ * @brief Constructs type sastifying the CollectDataForDataset concept for a given Store (using an
+ * instance of the GenericCollectData class) which writes a thermodynamic variable to an Xarray in a
+ * dataset.
+ *
+ * Function return type writes a thermodyanmic varaible "name" to an Xarray as a 4-byte floating
+ * point type by collecting data according to the given FunctorFunc from within a
+ * Kokkos::parallel_for loop over gridboxes with a range policy.
+ *
+ * @param dataset The dataset to write the variable to.
+ * @param ffunc The functor function to collect the variable from within a parallel range policy
+ * over gridboxes.
+ * @param maxchunk The maximum chunk size (number of elements).
+ * @param ngbxs The number of gridboxes.
+ * @return CollectDataForDataset<Store> An instance satisfying the CollectDataForDataset concept for
+ * collecting a 2-D floating point variable (e.g. a thermodynamic variable) from each gridbox.
+ */
 template <typename Store, typename FunctorFunc>
 CollectDataForDataset<Store> auto CollectThermoVariable(const Dataset<Store> &dataset,
                                                         const FunctorFunc ffunc,
@@ -56,8 +70,19 @@ CollectDataForDataset<Store> auto CollectThermoVariable(const Dataset<Store> &da
   return GenericCollectData(ffunc, xzarr, ngbxs);
 }
 
-/* Operator is functor to perform copy of pressure in each gridbox to d_data in parallel.
-Note conversion of pressure from double (8 bytes) to single precision (4 bytes float) in output */
+/**
+ * @brief Functor operator to perform a copy of the pressure from the state of each gridbox to
+ * d_data within Kokkos::parallel_for loop over gridboxes with range policy.
+ *
+ * Signature of operator such that type can be used by GenericCollectData struct for FunctorFunc.
+ *
+ * _Note:_ Conversion of press from double (8 bytes) to single precision float (4 bytes).
+ *
+ * @param ii The index of the gridbox.
+ * @param d_gbxs The view of gridboxes on device.
+ * @param totsupers The view of superdroplets on device.
+ * @param d_data The mirror view buffer for the number of superdroplets.
+ */
 struct PressFunc {
   KOKKOS_INLINE_FUNCTION
   void operator()(const size_t ii, viewd_constgbx d_gbxs, const viewd_constsupers totsupers,
@@ -67,9 +92,19 @@ struct PressFunc {
   }
 };
 
-/* Operator is functor to perform copy of temperature in each gridbox to d_data in parallel.
-Note conversion of temperature from double (8 bytes) to single precision (4 bytes float) in
-output */
+/**
+ * @brief Functor operator to perform a copy of the temperature from the state of each gridbox to
+ * d_data within Kokkos::parallel_for loop over gridboxes with range policy.
+ *
+ * Signature of operator such that type can be used by GenericCollectData struct for FunctorFunc.
+ *
+ * _Note:_ Conversion of temp from double (8 bytes) to single precision float (4 bytes).
+ *
+ * @param ii The index of the gridbox.
+ * @param d_gbxs The view of gridboxes on device.
+ * @param totsupers The view of superdroplets on device.
+ * @param d_data The mirror view buffer for the number of superdroplets.
+ */
 struct TempFunc {
   KOKKOS_INLINE_FUNCTION
   void operator()(const size_t ii, viewd_constgbx d_gbxs, const viewd_constsupers totsupers,
@@ -79,9 +114,19 @@ struct TempFunc {
   }
 };
 
-/* Operator is functor to perform copy of vapour mass mixing ratio (qvap) in each gridbox to d_data
-in parallel. Note conversion of qvap from double (8 bytes) to single precision (4 bytes float) in
-output */
+/**
+ * @brief Functor operator to perform a copy of the vapour mass mixing ratio "qvap" from the state
+ * of each gridbox to d_data within Kokkos::parallel_for loop over gridboxes with range policy.
+ *
+ * Signature of operator such that type can be used by GenericCollectData struct for FunctorFunc.
+ *
+ * _Note:_ Conversion of qvap from double (8 bytes) to single precision float (4 bytes).
+ *
+ * @param ii The index of the gridbox.
+ * @param d_gbxs The view of gridboxes on device.
+ * @param totsupers The view of superdroplets on device.
+ * @param d_data The mirror view buffer for the number of superdroplets.
+ */
 struct QvapFunc {
   KOKKOS_INLINE_FUNCTION
   void operator()(const size_t ii, viewd_constgbx d_gbxs, const viewd_constsupers totsupers,
@@ -91,9 +136,19 @@ struct QvapFunc {
   }
 };
 
-/* Operator is functor to perform copy of liquid mass mixing ratio (qcond) in each gridbox to d_data
-in parallel. Note conversion of qcond from double (8 bytes) to single precision (4 bytes
-float) in output */
+/**
+ * @brief Functor operator to perform a copy of the liquid ass mixing ratio "qcond" from the state
+ * of each gridbox to d_data within Kokkos::parallel_for loop over gridboxes with range policy.
+ *
+ * Signature of operator such that type can be used by GenericCollectData struct for FunctorFunc.
+ *
+ * _Note:_ Conversion of qcond from double (8 bytes) to single precision float (4 bytes).
+ *
+ * @param ii The index of the gridbox.
+ * @param d_gbxs The view of gridboxes on device.
+ * @param totsupers The view of superdroplets on device.
+ * @param d_data The mirror view buffer for the number of superdroplets.
+ */
 struct QcondFunc {
   KOKKOS_INLINE_FUNCTION
   void operator()(const size_t ii, viewd_constgbx d_gbxs, const viewd_constsupers totsupers,
@@ -103,8 +158,20 @@ struct QcondFunc {
   }
 };
 
-/* constructs CollectDataForDataset for a given Store which writes writes thermodynamic variables
-from the state of each gridbox using an instance of the GenericCollectData class */
+/**
+ * @brief Constructs a type satisyfing the CollectDataForDataset concept for collecting multiple
+ * thermodyanmcis variables from each gridbox and writing them to a dataset.
+ *
+ * This function combines CollectDataForDataset types for many thermodynamic variables from each
+ * gridbox (e.g. press, temp, qvap, qcond, etc.) using instances of the GenericCollectData class.
+ *
+ * @tparam Store The type of the dataset store.
+ * @param dataset The dataset to write the wind velocity components to.
+ * @param maxchunk The maximum chunk size (number of elements).
+ * @param ngbxs The number of gridboxes.
+ * @return CollectDataForDataset<Store> An instance of CollectDataForDataset for collecting
+ * thermodynamics from the state of each gridbox.
+ */
 template <typename Store>
 inline CollectDataForDataset<Store> auto CollectThermo(const Dataset<Store> &dataset,
                                                        const int maxchunk, const size_t ngbxs) {
@@ -123,8 +190,18 @@ inline CollectDataForDataset<Store> auto CollectThermo(const Dataset<Store> &dat
   return press >> temp >> qvap >> qcond;
 }
 
-/* constructs observer which writes writes thermodynamic variables from the state of each gridbox
-with a constant timestep 'interval' using an instance of the WriteToDatasetObserver class */
+/**
+ * @brief Constructs an observer which writes thermodyanmcis from each gridbox (e.g. press, temp,
+ * qvap, etc.) at start of each observation timestep to an array with a constant
+ * observation timestep "interval".
+ *
+ * @tparam Store Type of store for dataset.
+ * @param interval Observation timestep.
+ * @param dataset Dataset to write time data to.
+ * @param maxchunk Maximum number of elements in a chunk (1-D vector size).
+ * @param ngbxs The number of gridboxes.
+ * @return Observer An observer instance for writing thermodynamic variables from each gridbox.
+ */
 template <typename Store>
 inline Observer auto ThermoObserver(const unsigned int interval, const Dataset<Store> &dataset,
                                     const int maxchunk, const size_t ngbxs) {

libs/observers/windvel_observer.hpp

@@ -40,12 +40,12 @@
 
 /**
  * @brief Constructs type sastifying the CollectDataForDataset concept for a given Store (using an
- * instance of the GenericCollectData class) which writes a wind velocity component.
+ * instance of the GenericCollectData class) which writes a wind velocity component to an Xarray in
+ * a dataset.
  *
- * Function return type writes a wind velocity component writes a wind velocity component to an
- * Xarray as a 4-byte floating point type with units "m/s" by collecting data according
- * to the given FunctorFunc from within a Kokkos::parallel_for loop over gridboxes with a range
- * policy.
+ * Function return type writes a wind velocity component to an Xarray as a 4-byte floating point
+ * type with units "m/s" by collecting data according to the given FunctorFunc from within a
+ * Kokkos::parallel_for loop over gridboxes with a range policy.
  *
  * @param dataset The dataset to write the wind velocity component to.
  * @param ffunc The functor function to collect the wind velocity component from within a parallel
@@ -165,10 +165,6 @@ inline CollectDataForDataset<Store> auto CollectWindVel(const Dataset<Store> &da
   return vvel >> uvel >> wvel;
 }
 
-/* constructs observer which writes writes the wind velocity at center of
-each gridbox with a constant timestep 'interval' using an instance of the WriteToDatasetObserver
-class */
-
 /**
  * @brief Constructs an observer which writes the wind velocity components in each gridbox (wvel,
  * vvel and uvel) at start of each observation timestep to an array with a constant observation