diff --git a/docs/source/cxx/observers/gbxindex_observer.rst b/docs/source/cxx/observers/gbxindex_observer.rst index cb0f6b088..aeac027d8 100644 --- a/docs/source/cxx/observers/gbxindex_observer.rst +++ b/docs/source/cxx/observers/gbxindex_observer.rst @@ -1,12 +1,17 @@ -XXX Observer -============ +Gbxindex Observer +================= -// TODO(CB) write doc +Header file: ```` +`[source] `_ -Header file: ```` -`[source] `_ +.. doxygenstruct:: GbxIndexFunctor + :project: observers + :private-members: + :protected-members: + :members: + :undoc-members: -.. doxygenstruct:: XXXObserver +.. doxygenclass:: GbxindexObserver :project: observers :private-members: :protected-members: diff --git a/libs/observers/gbxindex_observer.hpp b/libs/observers/gbxindex_observer.hpp index c3fc03854..23908cd3b 100644 --- a/libs/observers/gbxindex_observer.hpp +++ b/libs/observers/gbxindex_observer.hpp @@ -34,28 +34,49 @@ #include "zarr/dataset.hpp" #include "zarr/xarray_zarr_array.hpp" +/** + * @struct GbxIndexFunctor + * @brief Functor for copying gridbox indexes to a view in device memory. + */ struct GbxIndexFunctor { - viewd_constgbx d_gbxs; // view of gridboxes - Buffer::mirrorviewd_buffer - d_data; // mirror view on device for gbxindex of every gridbox - + viewd_constgbx d_gbxs; /**< View of gridboxes. */ + Buffer::mirrorviewd_buffer d_data; /**< Mirror view on device for gridbox indexes. */ + + /** + * @brief Constructor for GbxIndexFunctor. + * @param d_gbxs View of gridboxes on device. + * @param d_data Mirror view on device of memory to copy gridbox indexes into. + */ GbxIndexFunctor(const viewd_constgbx d_gbxs, Buffer::mirrorviewd_buffer d_data) : d_gbxs(d_gbxs), d_data(d_data) {} - // Functor operator to perform copy of gbxindex of each gridbox to d_data in parallel + /** + * @brief Operator is functor for within a Kokkos::parallel_for loop. + * + * Copies a gridbox's gbxindex to d_data view (for each gridbox in parallel). + * + * @param ii index for the gridbox in the d_gbxs and d_data views. + */ KOKKOS_INLINE_FUNCTION void operator()(const size_t ii) const { d_data(ii) = d_gbxs(ii).get_gbxindex(); } }; -/* template observer which writes gbxindex for every gridbox out to a 1-D array -as a coordinate of an xarray dataset */ +/* @class GbxindexObserver + * @brief Observer to output gridbox indexes to a 1-D array as coordinate of an xarray dataset. + * @tparam Store Type of store for the dataset. + */ template class GbxindexObserver { private: - Dataset &dataset; ///< dataset to write gbxindex data to - std::shared_ptr> xzarr_ptr; ///< pointer to gbxindex array - - /* returns a view in the host memor of the gbxindex of every gridbox in d_gbxs */ + Dataset &dataset; /**< Dataset to write gridbox index data to. */ + std::shared_ptr> + xzarr_ptr; /**< Pointer to gridbox index array in dataset. */ + + /** + * @brief Collects gridbox indexes from g_gbxs into a host memory view. + * @param d_gbxs View of the gridboxes in device memory. + * @return View in host memory of gridbox index of every gridbox in d_gbxs. + */ Buffer::viewh_buffer collect_gbxindexes(const viewd_constgbx d_gbxs) const { const size_t ngbxs(d_gbxs.extent(0)); auto h_data = Buffer::viewh_buffer("h_data", ngbxs); @@ -67,6 +88,12 @@ class GbxindexObserver { } public: + /** + * @brief Constructor for GbxindexObserver. + * @param dataset Dataset to write gridbox index data to. + * @param maxchunk Maximum number of elements in a chunk (1-D vector size). + * @param ngbxs Number of gridboxes in final array. + */ GbxindexObserver(Dataset &dataset, const int maxchunk, const size_t ngbxs) : dataset(dataset), xzarr_ptr(std::make_shared>( @@ -75,8 +102,14 @@ class GbxindexObserver { ~GbxindexObserver() { dataset.write_arrayshape(xzarr_ptr); } - /* write the gbxindex of every gridbox in d_gbxs to the gbxindex array in the dataset and assert - the size of the gbxindex dimension in the dataset is correct */ + /** + * @brief Obsevers the gridboxes' gbxindexes before timestepping. + * + * Write the gbxindex of every gridbox in d_gbxs to the gbxindex array in the dataset and assert + * the size of the gbxindex dimension in the dataset is correct. + * + * @param d_gbxs View of gridboxes on device. + */ void before_timestepping(const viewd_constgbx d_gbxs) const { std::cout << "observer includes gbxindex observer\n"; auto h_data = collect_gbxindexes(d_gbxs); @@ -85,13 +118,41 @@ class GbxindexObserver { "inconsistent size of gbxindex data and dataset dimension"); } + /** + * @brief Placeholder for after timestepping functionality and to make class satisfy observer + * concept. + */ void after_timestepping() const {} + /** + * @brief Placeholder for functionality at the start of each timestep and to make class satisfy + * observer concept. + * @param t_mdl Current model timestep. + * @param d_gbxs View of gridboxes on device. + * @param totsupers View of superdrops on device. + */ void at_start_step(const unsigned int t_mdl, const viewd_constgbx d_gbxs, const viewd_constsupers totsupers) const {} + /** + * @brief Returns the timestep of the next observation. + * + * No observation during timestepping so function returns the largest possible timestep (largest + * unsigned integer). + * + * @param t_mdl Current model timestep. + * @return Next observation timestep. + */ unsigned int next_obs(const unsigned int t_mdl) const { return LIMITVALUES::uintmax; } + /** + * @brief Checks if the current timestep is an observation timestep. + * + * No observation during timestepping so function always returns false. + * + * @param t_mdl Current model timestep. + * @return boolean, false. + */ bool on_step(const unsigned int t_mdl) const { return false; } };