improve FieldContainer and lightly refactor fill_field_vals

Author: mabruzzo

tests/grtestutils/field_container.cpp

@@ -14,6 +14,7 @@
 #include "./field_container.hpp"
 #include "./field_info_detail.hpp"
 #include "./status.hpp"
+#include "./utils.hpp"
 
 #include "grackle.h"
 #include "status_reporting.h"
@@ -63,7 +64,7 @@ namespace field_detail {
 /// The returned where the keys are the names of every active Grackle field
 /// and the associated values are all nullptr
 static MapType make_nullptr_map_(const GrackleCtxPack& ctx_pack,
-                                 bool exclude_metal) {
+                                 const std::set<std::string>& exclude_fields) {
   MapType m;
   // fill up m with (field, nullptr) pairs for each field enabled by ctx_pack
   auto fn = [&m](const char* name, const FieldInfo& info) {
@@ -73,8 +74,8 @@ static MapType make_nullptr_map_(const GrackleCtxPack& ctx_pack,
   };
   for_each_named_field(ctx_pack, fn);
 
-  if (exclude_metal) {
-    auto search = m.find("metal_density");
+  for (const std::string& name : exclude_fields) {
+    auto search = m.find(name);
     if (search != m.end()) {
       m.erase(search);
     }
@@ -141,14 +142,15 @@ std::pair<CorePack, Status> CorePack::setup_1d(MapType&& premade_map,
 }  // namespace field_detail
 
 std::pair<FieldContainer, Status> FieldContainer::create_1d(
-    const GrackleCtxPack& ctx_pack, int buf_size, bool disable_metal) {
+    const GrackleCtxPack& ctx_pack, int buf_size,
+    const std::set<std::string>& exclude_fields) {
   if (!ctx_pack.is_initialized()) {
     return {FieldContainer{}, error::Adhoc("ctx_pack isn't initialized")};
   }
 
   // construct a map for each relevant field (the values are all nullptr)
   field_detail::MapType m =
-      field_detail::make_nullptr_map_(ctx_pack, disable_metal);
+      field_detail::make_nullptr_map_(ctx_pack, exclude_fields);
   std::pair<field_detail::CorePack, Status> tmp =
       field_detail::CorePack::setup_1d(std::move(m), buf_size);
   if (tmp.second.is_err()) {
@@ -162,14 +164,14 @@ std::pair<FieldContainer, Status> FieldContainer::create_1d(
 
 std::pair<FieldContainer, Status> FieldContainer::create(
     const GrackleCtxPack& ctx_pack, const GridLayout& layout,
-    bool disable_metal) {
+    const std::set<std::string>& exclude_fields) {
   int total_count = layout.n_elements();
 
   std::pair<FieldContainer, Status> tmp =
-      FieldContainer::create_1d(ctx_pack, total_count, disable_metal);
+      FieldContainer::create_1d(ctx_pack, total_count, exclude_fields);
 
   if (tmp.second.is_ok()) {
-    (*tmp.first.data_.layout) = layout;
+    tmp.first.data_.override_layout(layout);
   }
   return tmp;
 }
@@ -181,13 +183,13 @@ FieldContainer FieldContainer::clone() const {
   field_detail::MapType m = this->data_.map;
   std::pair<field_detail::CorePack, Status> tmp =
       field_detail::CorePack::setup_1d(std::move(m),
-                                       this->elements_per_field());
+                                       this->grid_layout().n_elements());
   // it shouldn't be possible for tmp.second.is_err() to return true
   FieldContainer out;
   out.data_ = std::move(tmp.first);
 
   // copy over layout properties
-  (*out.data_.layout) = *this->data_.layout;
+  out.data_.override_layout(*this->data_.layout);
 
   // now copy over field values
   copy_into_helper_(out);
@@ -204,7 +206,7 @@ void FieldContainer::copy_into_helper_(FieldContainer& other) const {
 
   const gr_float* src = this->data_.data_buf.get();
   gr_float* dst = other.data_.data_buf.get();
-  int length = this->elements_per_field() * this->n_fields();
+  int length = this->grid_layout().n_elements() * this->n_fields();
   std::memcpy(dst, src, length * sizeof(gr_float));
 }
 
@@ -222,4 +224,20 @@ bool FieldContainer::same_fields(const FieldContainer& other) const {
   return true;
 }
 
+void PrintTo(const FieldContainer& fc, std::ostream* os) {
+  const GridLayout& layout = fc.grid_layout();
+  *os << "FieldContainer{\n"
+      << "  " << layout.to_string() << ",\n"
+      << "  grid_dx = " << fc.data_.my_fields->grid_dx << ",\n"
+      << "  fields = {\n";
+  std::size_t n_elements = layout.n_elements();
+  for (const auto& it : fc) {
+    const std::string& field_name = it.first;
+    const gr_float* ptr = it.second;
+    *os << "    " << field_name << " =\n";
+    *os << "      " << ptr_to_string(ptr, n_elements) << '\n';
+  }
+  *os << "  }\n}\n";
+}
+
 }  // namespace grtest

tests/grtestutils/field_container.hpp

@@ -23,6 +23,7 @@
 #include <map>
 #include <memory>  // std::map
 #include <optional>
+#include <set>
 #include <string>
 #include <string_view>
 #include <utility>  // std::pair
@@ -136,6 +137,17 @@ class GridLayout {
   }
 
 public:
+  /// factory method
+  ///
+  /// This is for the common case where we want a 1D layout with a hardcoded
+  /// number of entries (and we know at compile-time that it can't fail)
+  template <int N>
+  static GridLayout create_1d() noexcept {
+    static_assert(N >= 1, "N must be positive");
+    int dim[3] = {N, 0, 0};
+    return GridLayout::create_(1, dim, nullptr, nullptr).first;
+  }
+
   /// factory method
   static std::pair<GridLayout, Status> try_from_dim(int rank, const int* dim) {
     return GridLayout::create_(rank, dim, nullptr, nullptr);
@@ -245,6 +257,19 @@ struct CorePack {
   /// maps field names to pointers
   MapType map;
 
+  /// prefer this method over directly modifying layout
+  ///
+  /// @note This obviously requires that this->layout and this->my_fields are
+  /// not nullptr.
+  void override_layout(const GridLayout& new_layout) noexcept {
+    // overriding this->layout implicitly updates the members of `my_fields`,
+    // `my_fields->grid_(dimension|start|end)`, because these members all point
+    // to statically sized C array members of GridLayout
+    *this->layout = new_layout;
+    // make sure grid_rank remains up to date
+    this->my_fields->grid_rank = this->layout->rank();
+  }
+
   /// factory method that consumes a @p premade_map
   ///
   /// @param premade_map A string to pointer mapping. The keys of this argument
@@ -285,13 +310,24 @@ class FieldContainer {
   ~FieldContainer() = default;
 
   /// A factory method to make a simple 1d container
+  ///
+  /// @param ctx_pack The Grackle Configuration used for initialization
+  /// @param buf_size The positive number of elements in the container
+  /// @param exclude_fields Names of fields that should be excluded
+  ///
+  /// @note This is provided as a convenience. Do we really need it?
   static std::pair<FieldContainer, Status> create_1d(
-      const GrackleCtxPack& ctx_pack, int buf_size, bool disable_metal = false);
+      const GrackleCtxPack& ctx_pack, int buf_size,
+      const std::set<std::string>& exclude_fields = {});
 
   /// A factory method to make a container
+  ///
+  /// @param ctx_pack The Grackle Configuration used for initialization
+  /// @param layout The Grid layout to use
+  /// @param exclude_fields Names of fields that should be excluded
   static std::pair<FieldContainer, Status> create(
       const GrackleCtxPack& ctx_pack, const GridLayout& layout,
-      bool disable_metal = false);
+      const std::set<std::string>& exclude_fields = {});
 
   /// Create a clone of FieldContainer
   FieldContainer clone() const;
@@ -302,7 +338,8 @@ class FieldContainer {
   ///
   /// @warning
   /// Setting bypass_check to `true` is risky. It primarily exists for the
-  /// case where you call this method in a loop
+  /// case where you call this method in a loop and we already know that 2
+  /// containers are compatible
   Status copy_into(FieldContainer& dest, bool bypass_check = false) const {
     if (!(bypass_check || this->same_grid_props(dest))) {
       return error::Adhoc("grid properties are incompatible");
@@ -321,9 +358,20 @@ class FieldContainer {
   /// returns whether `this` and @p other contains the same set of fields
   bool same_fields(const FieldContainer& other) const;
 
+  /**@{*/
+  /// get the pointer to the wrapped @ref grackle_field_data instance
+  ///
+  /// @note
+  /// This primarily exists to support Grackle API function. Avoid mutating
+  /// the returned pointer
   const grackle_field_data* get_ptr() const { return data_.my_fields.get(); }
+
+  // NOLINTNEXTLINE(readability-make-member-function-const)
   grackle_field_data* get_ptr() { return data_.my_fields.get(); }
+  /**@}*/
 
+  /**@{*/
+  /// finds the field data pointer for the field with the specified name
   std::optional<gr_float*> find(std::string_view key) {
     auto s = data_.map.find(key);
     return (s != data_.map.end()) ? std::optional{s->second} : std::nullopt;
@@ -333,18 +381,40 @@ class FieldContainer {
     auto s = data_.map.find(key);
     return (s != data_.map.end()) ? std::optional{s->second} : std::nullopt;
   }
+  /**@}*/
+
+  /**@{*/
+  /// finds the field data pointer or aborts the program
+  gr_float* get_or_abort(std::string_view key) {
+    std::optional<gr_float*> tmp = find(key);
+    if (!tmp.has_value()) {
+      std::string key_copy{key};  // required b/c key isn't '\0' terminated
+      GR_INTERNAL_ERROR("\"%s\" field wasn't found", key_copy.c_str());
+    }
+    return *tmp;
+  }
 
-  int n_fields() const { return static_cast<int>(data_.map.size()); }
+  const gr_float* get_or_abort(std::string_view key) const {
+    std::optional<const gr_float*> tmp = find(key);
+    if (!tmp.has_value()) {
+      std::string key_copy{key};  // required b/c key isn't '\0' terminated
+      GR_INTERNAL_ERROR("\"%s\" field wasn't found", key_copy.c_str());
+    }
+    return *tmp;
+  }
+  /**@}*/
 
-  int rank() const { return data_.my_fields->grid_rank; }
+  const GridLayout& grid_layout() const { return *data_.layout; }
 
-  /// the number of elements per field (unaffected by ghost zones)
-  int elements_per_field() const { return data_.layout->n_elements(); }
+  int n_fields() const { return static_cast<int>(data_.map.size()); }
 
   // we define both of the following methods to support the writing of
   // range-based for-loops to iterate over key-buffer pairs
   MapType::const_iterator begin() const { return data_.map.begin(); }
   MapType::const_iterator end() const { return data_.map.end(); }
+
+  // teach googletest how to print this type
+  friend void PrintTo(const FieldContainer& fc, std::ostream* os);
 };
 }  // namespace grtest
 

tests/grtestutils/fill_field_vals.hpp

@@ -25,20 +25,55 @@
 
 namespace grtest {
 
+/// @defgroup fillfieldsgrp Logic for filling field values
+///
+/// This group of entities defines the logic for initializing values in a
+/// @ref FluidContainer.
+///
+/// Since our testing tools may be used to test (or benchmark) scenarios with
+/// an arbitrarily large number of elements, we adopt a general-purpose scheme
+/// where we essentially repeat a "tile" of field values 1 or more times.
+///
+/// In general, a "tile" refers to an instance of a generic type that implements
+/// the methods illustrated in the following snippet.
+///
+/// @code{C++}
+/// struct MySampleTileType {
+///   /// number of elements in the tile
+///   int get_n_vals() const noexcept;
+///
+///   // iF field_name is known, fill buf with associated values associated
+///   // and return true. Otherwise, return false.
+///   //
+///   // buf should have a length given by get_n_vals()
+///   bool fill_buf(gr_float* buf, std::string_view field_name) const noexcept;
+/// };
+/// @endcode
+///
+/// This approach was picked to maximize flexibility.
+/// - it can work for initializing a single value or an arbitrary number of
+///   values. This reduces the maintenance burden (at the cost of some
+///   performance)
+/// - it should be easy enough to implement a new tile type
+/// - it is conceivable that we could reuse this machinery for initializing
+///   a field from serialized values (maybe from a json or toml or hdf5 file)
+/**@{*/  // open the doxygen group
+
 /// Fill in the values of @p fc by repeating the values from @p field_tile
 ///
-/// @param[in, out] fc The field container that will be filled
 /// @param[in] field_tile Specifies the values to use
+/// @param[in, out] fc The field container that will be filled
 template <class Tile>
-Status fill_field_vals(FieldContainer& fc, const Tile& field_tile) {
+Status fill_field_vals(const Tile& field_tile, FieldContainer& fc) {
   // access field grid index properties
-  int rank = fc.rank();
-  int ix_start = fc.get_ptr()->grid_start[0];
-  int ix_stop = fc.get_ptr()->grid_end[0] + 1;
-  int iy_start = (rank >= 2) ? fc.get_ptr()->grid_start[1] : 0;
-  int iy_stop = (rank >= 2) ? fc.get_ptr()->grid_end[1] + 1 : 1;
-  int iz_start = (rank == 3) ? fc.get_ptr()->grid_start[2] : 0;
-  int iz_stop = (rank == 3) ? fc.get_ptr()->grid_end[2] + 1 : 1;
+  const GridLayout& layout = fc.grid_layout();
+  int rank = layout.rank();
+  int ix_start = layout.start()[0];
+  int ix_stop = layout.stop()[0];
+  int iy_start = (rank >= 2) ? layout.start()[1] : 0;
+  int iy_stop = (rank >= 2) ? layout.stop()[1] : 1;
+  int iz_start = (rank == 3) ? layout.start()[2] : 0;
+  int iz_stop = (rank == 3) ? layout.stop()[2] : 1;
 
   int mx = fc.get_ptr()->grid_dimension[0];
   int my = (rank >= 2) ? fc.get_ptr()->grid_dimension[1] : 1;
@@ -78,6 +113,30 @@ Status fill_field_vals(FieldContainer& fc, const Tile& field_tile) {
   return OkStatus();
 }
 
+/// Create a @ref FieldContainer and fill in values by repeating the values from
+/// @p field_tile
+///
+/// @param field_tile Specifies the values to use
+/// @param ctx_pack The Grackle Configuration used for initialization
+/// @param layout The Grid layout to use
+/// @param exclude_fields Field names that should be excluded during creation
+///
+/// This function is simple: it just calls @ref FieldContainer::create and
+/// @ref fill_field_vals. But because this sequence of events is relatively
+/// common, the aggregation of @ref Status instance is quite convenient.
+template <class Tile>
+std::pair<FieldContainer, Status> create_and_fill_FieldContainer(
+    const Tile& field_tile, const GrackleCtxPack& ctx_pack,
+    const GridLayout& layout,
+    const std::set<std::string>& exclude_fields = {}) {
+  std::pair<grtest::FieldContainer, grtest::Status> out =
+      grtest::FieldContainer::create(ctx_pack, layout, exclude_fields);
+  if (out.second.is_ok()) {
+    out.second = fill_field_vals(field_tile, out.first);
+  }
+  return out;
+}
+
 /// Represents a very simplistic set of conditions
 struct SimpleFieldTile {
   double mfrac_metal;
@@ -89,8 +148,14 @@ struct SimpleFieldTile {
   double common_density;
   double common_eint;
 
+  /// number of values specified by the tile
   int get_n_vals() const noexcept { return 1; }
 
+  /// fill @p buf with values associated with the specified @p field_name
+  ///
+  /// @param[out] buf This is filled. The length is given by @ref get_n_vals()
+  /// @param[in] field_name Name of the field
+  /// @returns `true` if the field is known. Otherwise, returns `false`
   bool fill_buf(gr_float* buf, std::string_view field_name) const noexcept {
     if (field_name == "density") {
       buf[0] = common_density;
@@ -145,6 +210,8 @@ inline SimpleFieldTile make_simple_tile(const GrackleCtxPack& ctx_pack,
       /* common_eint = */ common_eint};
 }
 
+/**@}*/  // close the doxygen group
+
 }  // namespace grtest
 
 #endif  // GRTESTUTILS_SET_FIELD_CONDITIONS_HPP