Utopia  2
Framework for studying models of complex & adaptive systems.
base.hh
Go to the documentation of this file.
1 #ifndef UTOPIA_CORE_GRIDS_BASE_HH
2 #define UTOPIA_CORE_GRIDS_BASE_HH
3 
4 #include "../types.hh"
5 
6 namespace Utopia {
13 enum class GridStructure {
15  square,
17  triangular,
19  hexagonal
20 };
21 // NOTE When adding new grid structure type, take care to update
22 // grid_structure_map!
23 
25 const std::map<std::string, GridStructure> grid_structure_map {
26  {"square", GridStructure::square},
27  {"triangular", GridStructure::triangular},
28  {"hexagonal", GridStructure::hexagonal}
29 };
30 
32 
35 std::string grid_structure_to_string(const GridStructure& structure) {
36  for (const auto& m : grid_structure_map) {
37  if (m.second == structure) {
38  return m.first;
39  }
40  }
41  // Entry is missing; this should not happen, as the
42  // grid_structure_to_string is meant to include all possible enum values.
43  throw std::invalid_argument(
44  "The given grid structure was not available in the "
45  "grid_structure_map! Are all GridStructure enum values represented "
46  "in the map?"
47  );
48 };
49 
50 
52 enum class NBMode {
54  empty = 0,
56  vonNeumann = 1,
58  Moore = 2,
60  hexagonal = 3
61 };
62 // NOTE When adding new neighborhood types, take care to update nb_mode_map!
63 // Also, some high-level error messages (e.g. in the CellManager) might
64 // need to be adapted.
65 
67 const std::map<std::string, NBMode> nb_mode_map {
68  {"empty", NBMode::empty},
69  {"vonNeumann", NBMode::vonNeumann},
70  {"Moore", NBMode::Moore},
71  {"hexagonal", NBMode::hexagonal}
72 };
73 
75 
78 std::string nb_mode_to_string(const NBMode& nb_mode) {
79  for (const auto& m : nb_mode_map) {
80  if (m.second == nb_mode) {
81  return m.first;
82  }
83  }
84  // Entry is missing; this should not happen, as the nb_mode_map is meant to
85  // include all possible enum values. Inform about it ...
86  throw std::invalid_argument("The given nb_mode was not available in the "
87  "nb_mode_map! Are all NBMode enum values represented in the map?");
88 };
89 
91 template<class Grid>
92 using NBFuncID = std::function<IndexContainer(const IndexType)>;
93 
94 
95 // ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
96 
98 template<class Space>
99 class Grid {
100 public:
102  using Self = Grid<Space>;
103 
105  static constexpr DimType dim = Space::dim;
106 
108  using SpaceVec = typename Space::SpaceVec;
109 
112 
115 
116 
117 protected:
118  // -- Members -------------------------------------------------------------
120  const std::shared_ptr<Space> _space;
121 
123 
128 
131 
134 
137 
138 
139 public:
140  // -- Constructors and Destructors ----------------------------------------
142 
145  Grid (std::shared_ptr<Space> space, const Config& cfg)
146  :
147  _space(space),
148  _resolution([&cfg](){
149  if (not cfg["resolution"]) {
150  throw std::invalid_argument("Missing grid configuration "
151  "parameter 'resolution'! Please supply an integer >= 1.");
152  }
153 
154  // Read in as signed int (allows throwing error for negative value)
155  const auto res = get_as<long long>("resolution", cfg);
156 
157  if (res < 1) {
158  throw std::invalid_argument("Grid resolution needs to be a "
159  "positive integer, was < 1!");
160  }
161  return res;
162  }()),
164  _nb_params()
165  {
166  // Set the neighborhood function to not return anything
168  }
169 
171  virtual ~Grid() = default;
172 
173 
174  // -- Public interface ----------------------------------------------------
175  // .. Neighborhood interface ..............................................
176 
179  return _nb_func(id);
180  }
181 
183  const Config& nb_params = {})
184  {
185  try {
187  }
188  catch (std::exception& e) {
189  throw std::invalid_argument("Failed to select neighborhood: "
190  + ((std::string) e.what()));
191  }
192 
193  _nb_mode = nb_mode;
195  }
196 
198  const NBMode& nb_mode() const {
199  return _nb_mode;
200  }
201 
203  const Config& nb_params() const {
204  return _nb_params;
205  }
206 
208  auto nb_size() const {
210  }
211 
212 
213  // .. Position-related methods ............................................
215 
217  virtual MultiIndex midx_of(const IndexType) const = 0;
218 
220 
222  virtual SpaceVec barycenter_of(const IndexType) const = 0;
223 
225 
227  virtual SpaceVec extent_of(const IndexType) const = 0;
228 
230 
235  virtual std::vector<SpaceVec> vertices_of(const IndexType) const = 0;
236 
238 
250  virtual IndexType cell_at(const SpaceVec&) const = 0;
251 
253 
263  virtual std::set<IndexType> boundary_cells(std::string={}) const = 0;
264 
265 
266  // .. Getters .............................................................
268 
271  virtual IndexType num_cells() const = 0;
272 
274  auto resolution() const {
275  return _resolution;
276  }
277 
279 
285  virtual SpaceVec effective_resolution() const = 0;
286 
288  virtual MultiIndex shape() const = 0;
289 
291  virtual GridStructure structure() const = 0;
292 
294  std::string structure_name() const {
296  }
297 
299  const std::shared_ptr<Space>& space() const {
300  return _space;
301  }
302 
304  bool is_periodic() const {
305  return _space->periodic;
306  }
307 
308 
309 protected:
310  // -- Neighborhood functions ----------------------------------------------
312 
315  virtual NBFuncID<Self> get_nb_func(NBMode, const Config&) = 0;
316 
320  const Config&) const = 0;
321 
324  IndexContainer idcs{};
325  idcs.reserve(0);
326  return idcs;
327  };
328 };
329 
330 
331 // end group CellManager
336 } // namespace Utopia
337 
338 #endif // UTOPIA_CORE_GRIDS_BASE_HH
The base class for all grid discretizations used by the CellManager.
Definition: base.hh:99
const DistType _resolution
How many cells to place per length unit of space.
Definition: base.hh:127
bool is_periodic() const
Whether the space this grid maps to is periodic.
Definition: base.hh:304
const NBMode & nb_mode() const
Const reference to the currently selected neighborhood mode.
Definition: base.hh:198
virtual ~Grid()=default
Virtual destructor to allow polymorphic destruction.
MultiIndexType< dim > MultiIndex
The type of multi-index like arrays, e.g. the grid shape.
Definition: base.hh:111
NBFuncID< Self > _nb_func
Neighborhood function (working on cell IDs)
Definition: base.hh:136
static constexpr DimType dim
The dimensionality of the space to be discretized (for easier access)
Definition: base.hh:105
virtual GridStructure structure() const =0
Structure of the grid.
virtual std::set< IndexType > boundary_cells(std::string={}) const =0
Retrieve a set of cell indices that are at a specified boundary.
const std::shared_ptr< Space > _space
The space that is to be discretized.
Definition: base.hh:120
Grid(std::shared_ptr< Space > space, const Config &cfg)
Construct a grid discretization.
Definition: base.hh:145
NBMode _nb_mode
Neighborhood mode.
Definition: base.hh:130
std::string structure_name() const
Structure of the grid as std::string.
Definition: base.hh:294
virtual IndexType num_cells() const =0
Get number of cells.
virtual SpaceVec extent_of(const IndexType) const =0
Returns the extent of the cell with the given ID.
const Config & nb_params() const
The neighborhood parameters of the currently selected neighborhood.
Definition: base.hh:203
NBFuncID< Self > _nb_empty
A neighborhood function for empty neighborhood.
Definition: base.hh:323
virtual SpaceVec barycenter_of(const IndexType) const =0
Returns the barycenter of the cell with the given ID.
virtual MultiIndex shape() const =0
Get the shape of the grid discretization.
virtual SpaceVec effective_resolution() const =0
Returns the effective resolution into each dimension of the grid.
IndexContainer neighbors_of(const IndexType id) const
Returns the indices of the neighbors of the cell with the given ID.
Definition: base.hh:178
virtual MultiIndex midx_of(const IndexType) const =0
Returns the multi-index of the cell with the given ID.
virtual IndexType cell_at(const SpaceVec &) const =0
Return the ID of the cell covering the given point in physical space.
const std::shared_ptr< Space > & space() const
Const reference to the space this grid maps to.
Definition: base.hh:299
auto resolution() const
Get scalar resolution value of this grid.
Definition: base.hh:274
virtual NBFuncID< Self > get_nb_func(NBMode, const Config &)=0
Retrieve the neighborhood function depending on the mode.
Config _nb_params
Neighborhood parameters.
Definition: base.hh:133
void select_neighborhood(NBMode nb_mode, const Config &nb_params={})
Definition: base.hh:182
virtual DistType expected_num_neighbors(const NBMode &, const Config &) const =0
virtual std::vector< SpaceVec > vertices_of(const IndexType) const =0
Returns the vertices of the cell with the given ID.
auto nb_size() const
Maximum size of the currently selected neighborhood.
Definition: base.hh:208
typename Space::SpaceVec SpaceVec
The type of vectors that have a relation to physical space.
Definition: base.hh:108
DataIO::Config Config
The configuration type.
Definition: base.hh:114
std::string grid_structure_to_string(const GridStructure &structure)
Given an GridStructure enum value, return the corresponding string key.
Definition: base.hh:35
NBMode
Possible neighborhood types; availability depends on choice of grid.
Definition: base.hh:52
const std::map< std::string, GridStructure > grid_structure_map
A map from strings to grid structure enum values.
Definition: base.hh:25
const std::map< std::string, NBMode > nb_mode_map
A map from strings to neighborhood enum values.
Definition: base.hh:67
std::string nb_mode_to_string(const NBMode &nb_mode)
Given an NBMode enum value, return the corresponding string key.
Definition: base.hh:78
GridStructure
Available grid implementations.
Definition: base.hh:13
std::function< IndexContainer(const IndexType)> NBFuncID
Type of the neighborhood calculating function.
Definition: base.hh:92
@ vonNeumann
The vonNeumann neighborhood, i.e. only nearest neighbors.
@ hexagonal
The hexagonal neighbourhood, i.e. the neighbourhood on a hexagonal grid.
@ Moore
The Moore neighborhood, i.e. nearest and next nearest neighbors.
@ empty
Every entity is utterly alone in the world.
@ hexagonal
A hexagonal lattice grid.
@ square
A square lattice grid.
@ triangular
A triangular lattice grid.
YAML::Node Config
Type of a variadic dictionary-like data structure used throughout Utopia.
Definition: types.hh:71
Definition: agent.hh:11
arma::Col< IndexType >::fixed< dim > MultiIndexType
Type for index type vectors that are associated with a physical space.
Definition: types.hh:53
std::vector< IndexType > IndexContainer
Type for container of indices.
Definition: types.hh:43
unsigned short DimType
Type for dimensions, i.e. very small unsigned integers.
Definition: types.hh:34
unsigned int DistType
Type for distancens, i.e. intermediately long unsigned integers.
Definition: types.hh:37
std::size_t IndexType
Type for indices, i.e. values used for container indexing, agent IDs, ...
Definition: types.hh:40
SpaceVecType< dim > SpaceVec
The type for vectors relating to physical space.
Definition: space.hh:33
static constexpr std::size_t dim
The dimensionality of the space.
Definition: space.hh:30