From 2aca07e9f3daf602c6bbad1791822c878d3b9d81 Mon Sep 17 00:00:00 2001 From: "clara.bayley" Date: Thu, 11 Apr 2024 19:17:02 +0200 Subject: [PATCH] docs(observers): docstrings and rst file for wind velocities and thermo observers --- docs/source/cxx/observers/thermo_observer.rst | 40 +++++- .../source/cxx/observers/windvel_observer.rst | 6 +- libs/observers/thermo_observer.hpp | 115 +++++++++++++++--- libs/observers/windvel_observer.hpp | 14 +-- 4 files changed, 138 insertions(+), 37 deletions(-) diff --git a/docs/source/cxx/observers/thermo_observer.rst b/docs/source/cxx/observers/thermo_observer.rst index cb0f6b088..6bcc4dd9b 100644 --- a/docs/source/cxx/observers/thermo_observer.rst +++ b/docs/source/cxx/observers/thermo_observer.rst @@ -1,14 +1,42 @@ -XXX Observer -============ +Thermodynamics Observer +======================= -// TODO(CB) write doc +Header file: ```` +`[source] `_ -Header file: ```` -`[source] `_ +.. 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 diff --git a/docs/source/cxx/observers/windvel_observer.rst b/docs/source/cxx/observers/windvel_observer.rst index 59da6f4d3..60c0c4182 100644 --- a/docs/source/cxx/observers/windvel_observer.rst +++ b/docs/source/cxx/observers/windvel_observer.rst @@ -4,6 +4,9 @@ WindVel Observer Header file: ```` `[source] `_ +.. doxygenfunc:: CollectWindVariable + :project: observers + .. doxygenstruct:: WvelFunc :project: observers :private-members: @@ -25,9 +28,6 @@ Header file: ```` :members: :undoc-members: -.. doxygenfunction:: WindVelObserver - :project: observers - .. doxygenfunction:: CollectWindVel :project: observers diff --git a/libs/observers/thermo_observer.hpp b/libs/observers/thermo_observer.hpp index c4ebe6fbf..74954bfae 100644 --- a/libs/observers/thermo_observer.hpp +++ b/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 An instance satisfying the CollectDataForDataset concept for + * collecting a 2-D floating point variable (e.g. a thermodynamic variable) from each gridbox. + */ template CollectDataForDataset auto CollectThermoVariable(const Dataset &dataset, const FunctorFunc ffunc, @@ -56,8 +70,19 @@ CollectDataForDataset auto CollectThermoVariable(const Dataset &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 An instance of CollectDataForDataset for collecting + * thermodynamics from the state of each gridbox. + */ template inline CollectDataForDataset auto CollectThermo(const Dataset &dataset, const int maxchunk, const size_t ngbxs) { @@ -123,8 +190,18 @@ inline CollectDataForDataset auto CollectThermo(const Dataset &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 inline Observer auto ThermoObserver(const unsigned int interval, const Dataset &dataset, const int maxchunk, const size_t ngbxs) { diff --git a/libs/observers/windvel_observer.hpp b/libs/observers/windvel_observer.hpp index 801ac1dd9..2424bb63a 100644 --- a/libs/observers/windvel_observer.hpp +++ b/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 auto CollectWindVel(const Dataset &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