A grid discretization using hexagonal cells. More...

#include <hexagonal.hh>

Inheritance diagram for Utopia::HexagonalGrid< Space >:

Collaboration diagram for Utopia::HexagonalGrid< Space >:

Public Types
using	Base = Grid< Space >
	Base class type.

using	SpaceVec = typename Space::SpaceVec
	The type of vectors that have a relation to physical space.

using	MultiIndex = MultiIndexType< dim >
	The type of multi-index like arrays, e.g. the grid shape.

using	Config = DataIO::Config
	The configuration type.

Public Types inherited from Utopia::Grid< Space >
using	Self = Grid< Space >
	Type of this class, i.e. the base grid class.

using	SpaceVec = typename Space::SpaceVec
	The type of vectors that have a relation to physical space.

using	MultiIndex = MultiIndexType< dim >
	The type of multi-index like arrays, e.g. the grid shape.

using	Config = DataIO::Config
	The configuration type.

Public Member Functions
	HexagonalGrid (std::shared_ptr< Space > space, const Config &cfg)
	Construct a hexagonal grid discretization.

IndexType	num_cells () const override
	Number of hexagonal cells required to fill the physical space.

SpaceVec	effective_resolution () const override
	The effective cell resolution into each physical space dimension.

MultiIndex	shape () const override
	Get shape of the hexagonal grid.

GridStructure	structure () const override
	Structure of the grid.

MultiIndex	midx_of (const IndexType id) const override
	Returns the multi-index of the cell with the given ID.

SpaceVec	barycenter_of (const IndexType id) const override
	Returns the barycenter of the cell with the given ID.

SpaceVec	extent_of (const IndexType) const override
	Returns the extent of the cell with the given ID.

std::vector< SpaceVec >	vertices_of (const IndexType id) const override
	Returns the vertices of the cell with the given ID.

IndexType	cell_at (const SpaceVec &pos) const override
	Return the ID of the cell covering the given point in physical space.

std::set< IndexType >	boundary_cells (std::string select="all") const override
	Retrieve a set of cell indices that are at a specified boundary.

Public Member Functions inherited from Utopia::Grid< Space >
	Grid (std::shared_ptr< Space > space, const Config &cfg)
	Construct a grid discretization.

virtual	~Grid ()=default
	Virtual destructor to allow polymorphic destruction.

IndexContainer	neighbors_of (const IndexType id) const
	Returns the indices of the neighbors of the cell with the given ID.

void	select_neighborhood (NBMode nb_mode, const Config &nb_params={})

const NBMode &	nb_mode () const
	Const reference to the currently selected neighborhood mode.

const Config &	nb_params () const
	The neighborhood parameters of the currently selected neighborhood.

auto	nb_size () const
	Maximum size of the currently selected neighborhood.

auto	resolution () const
	Get scalar resolution value of this grid.

std::string	structure_name () const
	Structure of the grid as std::string.

const std::shared_ptr< Space > &	space () const
	Const reference to the space this grid maps to.

bool	is_periodic () const
	Whether the space this grid maps to is periodic.

Static Public Attributes
static constexpr DimType	dim = Space::dim
	The dimensionality of the space to be discretized (for easier access)

Static Public Attributes inherited from Utopia::Grid< Space >
static constexpr DimType	dim = Space::dim
	The dimensionality of the space to be discretized (for easier access)

Protected Member Functions
NBFuncID< Base >	get_nb_func (NBMode nb_mode, const Config &nb_params) override
	Retrieve the neighborhood function depending on the mode.

DistType	expected_num_neighbors (const NBMode &nb_mode, const Config &) const override
	Computes the expected number of neighbors for a neighborhood mode.

NBFuncID< Base >	get_nb_func_hexagonal (const Config &nb_params)
	Returns a standalone hexagonal neighborhood function.

template<DimType axis, bool periodic>
void	add_neighbors_in_ (const IndexType root_id, IndexContainer &neighbor_ids) const
	Add both direct neighbors to a container of indices.

template<bool check_shape = false>
DistType	get_nb_param_distance (const Config &params) const
	Extract the `distance` neighborhood parameter from the given config.

Protected Attributes
NBFuncID< Base >	_nb_hexagonal_periodic
	The Von-Neumann neighborhood for periodic grids.

NBFuncID< Base >	_nb_hexagonal_nonperiodic
	The Von-Neumann neighborhood for non-periodic grids.

Protected Attributes inherited from Utopia::Grid< Space >
const std::shared_ptr< Space >	_space
	The space that is to be discretized.

const DistType	_resolution
	How many cells to place per length unit of space.

NBMode	_nb_mode
	Neighborhood mode.

Config	_nb_params
	Neighborhood parameters.

NBFuncID< Self >	_nb_func
	Neighborhood function (working on cell IDs)

NBFuncID< Self >	_nb_empty
	A neighborhood function for empty neighborhood.

Private Member Functions
MultiIndex	determine_shape () const
	Get shape of the hexagonal grid.

Private Attributes
const MultiIndex	_shape
	The (multi-index) shape of the grid, resulting from resolution.

const SpaceVec	_cell_extent
	The extent of each cell of this discretization (same for all)

Detailed Description

template<class Space>
class Utopia::HexagonalGrid< Space >

A grid discretization using hexagonal cells.

This is a grid discretization using hexagonal cells

The hexagonal tiling is constructed in pointy-topped orientation (one vertex of the hexagon pointing up) with an even row offset (every even row is displaced half a cell width to the right).

The hexagonal cellular arrangement covers a periodic space perfectly. In this setup the right-most cell in offset rows is half cut, covering the remaining space at the left boundary. Similarly, the tip of the cells in the upper-most row covers the free space at the lower boundary. In non-periodic space these cells are cut and at the opposite boundary space remains under-represented.

Top: pointy tops are cut off
Right: offset row cells are cut in half
Bottom: no cutoff, but unrepresented area the same shape as the top-side cutoff. Points within these triangles are mapped to nearest cell
Left: no cutoff, but unrepresented area the same shape as the right-side cutoff. Points within these half-cells are mapped to the nearest cell.

Note: Indices are constructed in "Fortran"-style, i.e. with the first index changing fastest (also called "column major"). For example, when iterating over the cell IDs and having a 2D space, the iteration goes first along the x-axis and then along the y-axis: 0, 1, …, N_x, N_x + 1, …, 2*N_x, 2*N_x + 1, …, N_x * N_y - 1

For more information on hexagonal grids, see this tutorial.

This class has been implemented following the above tutorial written by Amit Patel and published on www.redblobgames.com (last accessed version from May 2020).

Member Typedef Documentation

◆ Base

template<class Space >

using Utopia::HexagonalGrid< Space >::Base = Grid<Space>

Base class type.

◆ Config

template<class Space >

using Utopia::HexagonalGrid< Space >::Config = DataIO::Config

The configuration type.

◆ MultiIndex

template<class Space >

using Utopia::HexagonalGrid< Space >::MultiIndex = MultiIndexType<dim>

The type of multi-index like arrays, e.g. the grid shape.

◆ SpaceVec

template<class Space >

using Utopia::HexagonalGrid< Space >::SpaceVec = typename Space::SpaceVec

The type of vectors that have a relation to physical space.

Constructor & Destructor Documentation

◆ HexagonalGrid()

template<class Space >

Utopia::HexagonalGrid< Space >::HexagonalGrid	(	std::shared_ptr< Space >	space,
		const Config &	cfg
	)

inline

Construct a hexagonal grid discretization.

Parameters

space	The space to construct the discretization for
cfg	Further configuration parameters

    :
        Base(space, cfg),
        _shape(determine_shape()),
        _cell_extent(1./effective_resolution())
    {
        // Make sure the cells really are hexagonal
        static_assert(dim == 2, "Hexagonal grid is only implemented for 2D "
                                "space!");
                                
        const SpaceVec eff_res = effective_resolution();
 
        // check that the cell extent corresponds to that of pointy-topped 
        // hexagonal cells
        // NOTE the test only requires the aspect ratio is precise to 2% for 
        //      easy user experience. The hexagonal grid requires a space
        //      with an aspect ratio involving a sqrt(3)
        if (  fabs(_cell_extent[0] / _cell_extent[1] - sqrt(3.) / 2.)
            > get_as<double>("aspect_ratio_tolerance", cfg, 0.02))
        {
            SpaceVec required_space = SpaceVec({1., 0.75 * 2. / sqrt(3.)});
            required_space[0] = this->_space->extent[0];
            required_space[1] = _shape[1] * _cell_extent[0] * 1.5 /sqrt(3.);
            std::stringstream required_space_ss;
            required_space_ss << required_space;
 
            throw std::invalid_argument(fmt::format(
                "Given the extent of the physical space and the specified "
                "resolution, a mapping with hexagonal cells could not be "
                "found! Either adjust the the extent of physical space or the "
                "resolution of the grid. Alternatively increase the tolerance "
                "to distorted hexagons or choose another grid. \n"
                "The required aspect ratio of sqrt(3) / 2 is violated by {} "
                "(> `aspect_ratio_tolerance` = {})! \n"
                "With the given resolution, set the space extent to : \n"
                "{} or increase the resolution.",
                fabs(_cell_extent[0] / _cell_extent[1] - sqrt(3.) / 2.),
                get_as<double>("aspect_ratio_tolerance", cfg, 0.02),
                required_space_ss.str()
            ));
 
        }
    }

Member Function Documentation

◆ add_neighbors_in_()

template<class Space >

template<DimType axis, bool periodic>

void Utopia::HexagonalGrid< Space >::add_neighbors_in_	(	const IndexType	root_id,
		IndexContainer &	neighbor_ids
	)		const

inlineprotected

Add both direct neighbors to a container of indices.

This function takes an index container and populates it with the indices of neighboring cells in different dimensions, specified by template parameter 0 < axis < number of dimensions - 1.

The algorithm first calculates whether the given root cell index has a front or back boundary in the chosen dimension. If so, the neighboring cell is only added if the grid is periodic.

Parameters

root_id	Which cell to find the agents of
neighbor_ids	The container to populate with the indices

Template Parameters

axis	The axis along which to add the neighbors (0-based!)
periodic	Whether the grid is periodic

Returns: void

    {
        // Assure the number of dimensions is supported
        static_assert(axis < 3);
 
        // left and right
        if constexpr (axis == 0) {
            // Compute a normalized id
            const IndexType nrm_id = root_id % _shape[0];
 
            // Check if at low value boundary
            if (nrm_id == 0) {
                // left most column
                if constexpr (periodic) {
                    neighbor_ids.push_back(root_id - 1 + _shape[0]);
                }
                // else: not periodic; nothing to add here
            }
            else {
                // Not at boundary; no need for the correction term
                neighbor_ids.push_back(root_id - 1);
            }
 
            // Check if at high value boundary
            if (nrm_id == _shape[0] - 1) {
                // right most column
                if constexpr (periodic) {
                    neighbor_ids.push_back(root_id + 1 - _shape[0]);
                }
                // else: not periodic; nothing to add here
            }
            else {
                // Not at boundary; no need for the correction term
                neighbor_ids.push_back(root_id + 1);
            }
        }
        // top-left and bottom-right
        else if constexpr (axis == 1) {
            // Compute normalized ids
            const IndexType nrm_id_0 = root_id % _shape[0]; // column
            const IndexType nrm_id_1 = (  (root_id % (_shape[0] * _shape[1]))
                                        / _shape[0]); // row
 
            // Check if at low value boundary
            if (nrm_id_1 == 0) {
                // bottom row
                if constexpr (periodic) {
                    if (nrm_id_0 < _shape[0] - 1) {
                        neighbor_ids.push_back(  root_id - _shape[0] + 1
                                               + _shape[0] * _shape[1]);
                    }
                    else {
                        // also right most
                        neighbor_ids.push_back(  root_id - 2*_shape[0] + 1
                                               + _shape[0] * _shape[1]);
                    }
                }
                // else: not periodic; nothing to add here
            }
            else if (nrm_id_0 == _shape[0] - 1 and nrm_id_1 % 2 == 0) {
                // right column, offset rows
                if constexpr (periodic) {
                    neighbor_ids.push_back(root_id - 2*_shape[0] + 1);
                }
                // else: not periodic; nothing to add here
            }
            else if (nrm_id_1 % 2 == 0) {
                // offset row
                // Not at boundary; no need for the correction term
                neighbor_ids.push_back(root_id - _shape[0] + 1);
            }
            else {
                // non-offset row
                neighbor_ids.push_back(root_id - _shape[0]);
            }
 
            // Check if at high value boundary
            if (nrm_id_1 == _shape[1] - 1) {
                // top row
                if constexpr (periodic) {
                    if (nrm_id_0 > 0) {
                        // is an non-offset row
                        neighbor_ids.push_back(  root_id + _shape[0] - 1
                                               - _shape[0] * _shape[1]);
                    }
                    else {
                        // left most cell
                        neighbor_ids.push_back(  root_id + 2*_shape[0] - 1
                                               - _shape[0] * _shape[1]);
                    }
                }
                // else: not periodic; nothing to add here
            }
            else if (nrm_id_0 == 0 and nrm_id_1 % 2 == 1){
                // left column impair row
                if constexpr (periodic) {
                    neighbor_ids.push_back(root_id + 2*_shape[0] - 1);                    
                }
            }
            else if (nrm_id_1 % 2 == 0) {
                // Not at boundary; no need for the correction term
                neighbor_ids.push_back(root_id + _shape[0]);
            }
            else {
                // non-offset row
                neighbor_ids.push_back(root_id + _shape[0] - 1);
            }
        }
        // top right and bottom left
        else {
            // Compute normalized ids
            const IndexType nrm_id_0 = root_id % _shape[0]; // column
            const IndexType nrm_id_1 = (  (root_id % (_shape[0] * _shape[1]))
                                        / _shape[0]); // row 
 
            if (nrm_id_1 == 0) {
                // bottom row
                if constexpr (periodic) {
                    neighbor_ids.push_back(  root_id - _shape[0]
                                           + _shape[0] * _shape[1]);
                }
                // else: not periodic; nothing to add here
            }
            else if (nrm_id_0 == 0 and nrm_id_1 % 2 == 1) {
                // left most, non-offset row
                if constexpr (periodic) {
                    neighbor_ids.push_back(root_id - 1);
                }
                // else: not periodic; nothing to add here
            }
            else if (nrm_id_1 % 2 == 1) {
                neighbor_ids.push_back(root_id - _shape[0] - 1);
            }
            else {
                neighbor_ids.push_back(root_id - _shape[0]);
            }
 
            if (nrm_id_1 == _shape[1] - 1) {
                // top row
                if constexpr (periodic) {
                    neighbor_ids.push_back(  root_id + _shape[0]
                                           - _shape[0] * _shape[1]);
                }
                // else: not periodic; nothing to add here
            }
            else if (nrm_id_0 == _shape[0] - 1 and nrm_id_1 % 2 == 0) {
                // right column in offset row
                if constexpr (periodic) {
                    neighbor_ids.push_back(root_id + 1);
                }
                // else: not periodic; nothing to add here
            }
            else if (nrm_id_1 % 2 == 0) {
                neighbor_ids.push_back(root_id + _shape[0] + 1);
            }
            else {
                neighbor_ids.push_back(root_id + _shape[0]);
            }
        }
    }

◆ barycenter_of()

template<class Space >

SpaceVec Utopia::HexagonalGrid< Space >::barycenter_of ( const IndexType id ) const

inlineoverridevirtual

Returns the barycenter of the cell with the given ID.

Note: This method does not perform bounds checking of the given ID!

Implements Utopia::Grid< Space >.

                                                              {
        MultiIndex mid = midx_of(id);
        if (mid[1] % 2 == 0) {
            // even row
            return    (mid % SpaceVec({1., 0.75}) + SpaceVec({1., 0.5}))
                    % _cell_extent;
        }
        else {
            // odd row
            return (  (mid % SpaceVec({1, 0.75}) + SpaceVec({0.5, 0.5}))
                    % _cell_extent);
        }
    }

◆ boundary_cells()

template<class Space >

std::set< IndexType > Utopia::HexagonalGrid< Space >::boundary_cells ( std::string select = "all" ) const

inlineoverridevirtual

Retrieve a set of cell indices that are at a specified boundary.

Note: For a periodic space, an empty container is returned; no error or warning is emitted.

Parameters

select Which boundary to return the cell IDs of. If 'all', all boundary cells are returned. Other available values depend on the dimensionality of the grid: 2D: left, right, bottom, top

Implements Utopia::Grid< Space >.

    {
        if (    select != "all"
            and select != "left" and select != "right"
            and select != "bottom" and select != "top")
        {
            throw std::invalid_argument("Invalid value for argument "
                "`select` in call to method SquareGrid::boundary_cells! "
                "Available arguments (for currently selected "
                "dimensionality) are: "
                "'all', 'left', 'right', 'bottom', 'top'. Given value: '"
                + select + "'");
        }
 
        // The target set all IDs are to be emplaced in
        std::set<IndexType> bc_ids;
        
        // For periodic space, this is easy:
        if (this->is_periodic()) {
            return {};
        }
 
        // NOTE It is important to use the hinting features of std::set
        //      here, which allow to run the following in amortized
        //      constant time instead of logarithmic with set size.
        //      Below, it always makes sense to hint at inserting right
        //      before the end.
        // Hint for the first element needs to be the beginning
        auto hint = bc_ids.begin();
 
        // Bottom boundary (lowest IDs)
        if (select == "all" or select == "bottom") {
            // 0, ..., _shape[0] - 1    
            for (DistType id = 0; id < _shape[0]; id++) {
                bc_ids.emplace_hint(hint, id);
                hint = bc_ids.end();
            }
        }
 
        // Left boundary
        if (select == "left") {
            // First IDs in _shape[1] rows:  0, _shape[0], 2*_shape[0], ...
            for (DistType row = 0; row < _shape[1]; row++) {
                bc_ids.emplace_hint(hint, row * _shape[0]);
                hint = bc_ids.end();
            }
        }
 
        // Right boundary
        if (select == "right") {
            // Last IDs in _shape[1] rows
            const auto offset = _shape[0] - 1;
 
            for (DistType row = 0; row < _shape[1]; row++) {
                bc_ids.emplace_hint(hint, offset + row * _shape[0]);
                hint = bc_ids.end();
            }
        }
 
        // Left AND right (only for 'all' case, allows better hints)
        if (select == "all") {
            // First and last IDs in _shape[1] rows
            const auto offset = _shape[0] - 1;
 
            for (DistType row = 0; row < _shape[1]; row++) {
                // Left boundary cell
                bc_ids.emplace_hint(hint, row * _shape[0]);
 
                // Right boundary cell (higher than left cell ID)
                bc_ids.emplace_hint(bc_ids.end(),
                                    offset + row * _shape[0]);
 
                hint = bc_ids.end();
            }
        }
 
        // Top boundary (highest IDs)
        if (select == "all" or select == "top") {
            // _shape[0] * (_shape[1]-1), ..., _shape[0] * _shape[1] - 1
            for (DistType id = _shape[0] * (_shape[1]-1);
                    id < _shape[0] * _shape[1]; id++)
            {
                bc_ids.emplace_hint(hint, id);
                hint = bc_ids.end();
            }
        }
 
        return bc_ids;
    }

◆ cell_at()

template<class Space >

IndexType Utopia::HexagonalGrid< Space >::cell_at ( const SpaceVec & pos ) const

inlineoverridevirtual

Return the ID of the cell covering the given point in physical space.

Cells are interpreted as covering half-open intervals in space, i.e., including their low-value edges and excluding their high-value edges. The special case of points on high-value edges for non-periodic space behaves such that these points are associated with the cells at the boundary.

For non-periodic space only: The offset geometry of the hexagonal lattice does not permit to cover a rectangular non-periodic space perfectly. At the boundary, a position in uncovered space is mapped to the closest cell. Details: The hexagonal cellular arrangement is covering the periodic equivalent perfectly. In this setup the right-most cell in offset rows is half cut, covering the space at the left boundary. Similarly, the tip of the cells in the upper-most row covers the free space at the lower boundary. In non-periodic space these cells are cut and at the opposite boundary space remains under-represented. Positions in this space are mapped to the closest cell.

Top: pointy tops are cut off
Right: offset row cells are cut in half
Bottom: no cutoff, but unrepresented area the same shape as the top-side cutoff. Points within these triangles are mapped to nearest cell
Left: no cutoff, but unrepresented area the same shape as the right-side cutoff. Points within these half-cells are mapped to the nearest cell.

Note: This function always returns IDs of cells that are inside physical space. For non-periodic space, a check is performed whether the given point is inside the physical space associated with this grid. For periodic space, the given position is mapped back into the physical space.

Implements Utopia::Grid< Space >.

                                                          {
        SpaceVec ridx = pos;
        // check position
        if (this->is_periodic()) {
            ridx = this->_space->map_into_space(pos);
        }
        else if (not this->_space->contains(pos)) {
            throw std::invalid_argument("The given position is outside "
                "the non-periodic space associated with this grid!");
        }
 
        // relative and centered in cell 0
        ridx = ridx / _cell_extent - SpaceVec({1., 0.5});
 
        arma::Col<int>::fixed<dim> midx = {
            static_cast<int>(std::round(ridx[0] + 2. / 3. * ridx[1])),
            static_cast<int>(std::round(4. / 3. * ridx[1]))
        };
 
        // correct for offset
        midx[0] -= std::floor(midx[1] / 2.);
 
        if (not this->is_periodic()) {
            // remap not represented space to first cell in this row
            // NOTE this distorts the cells, but the rectangular space is 
            //      correctly represented
            if (midx[0] == -1) {
                midx[0]++;
            }
            if (midx[1] == -1) {
                midx[1]++;
            }
 
            // Associate points on high-value boundaries with boundary cells
            if (midx[0] == static_cast<int>(_shape[0])) {
                midx[0]--;
            }
        }
        else {
            midx[0] = (midx[0] + _shape[0]) % _shape[0];
            midx[1] = (midx[1] + _shape[1]) % _shape[1];
        }
 
        // From the multi index, calculate the corresponding ID
        return static_cast<IndexType>(midx[0] + (midx[1] * _shape[0]));
        // Equivalent to:
        //     midx[0] * id_shift<0>()
        //   + midx[1] * id_shift<1>()
    }

◆ determine_shape()

template<class Space >

MultiIndex Utopia::HexagonalGrid< Space >::determine_shape ( ) const

inlineprivate

Get shape of the hexagonal grid.

Integer rounding takes place here. A physical space of extents of 2.1 length units in each dimension (resp. the shape of the hexagon) and a resolution of two cells per unit length will result in 4 cells in each dimension, each cell's size scaled up slightly and the effective resolution thus slightly smaller than the specified resolution.

Note: In non-periodic space the the number of rows needs to be a pair value in pointy-top orientation.; Note the offset rows are cut and the right end of the domain (if not periodic). Therefore the width of the cells is such, that N * width = Length, that is non-offset rows span the entire width.

                                       {
        MultiIndex shape;
        
        // obtain the sidelength of a unit area hexagon
        // A = 3^1.5 / 2 s^2
        double s = sqrt(2. / (3 * sqrt(3)));
        double width = sqrt(3) * s;
        double height = 2 * s;
 
        shape[0] = std::round(  this->_space->extent[0] / width
                              * this->_resolution);
        shape[1] = std::round(  this->_space->extent[1] / (0.75 * height)
                              * this->_resolution);
        
        // in non periodic space pair number of rows required
        if (this->is_periodic()) {
            shape[1] = shape[1] - shape[1] % 2;
        }
 
        return shape;
    }

◆ effective_resolution()

template<class Space >

SpaceVec Utopia::HexagonalGrid< Space >::effective_resolution ( ) const

inlineoverridevirtual

The effective cell resolution into each physical space dimension.

Implements Utopia::Grid< Space >.

                                                   {
        return SpaceVec({static_cast<double>(_shape[0]), 0.75*_shape[1]})
                / this->_space->extent;
    }

◆ expected_num_neighbors()

template<class Space >

DistType Utopia::HexagonalGrid< Space >::expected_num_neighbors	(	const NBMode &	nb_mode,
		const Config &
	)		const

inlineoverrideprotectedvirtual

Computes the expected number of neighbors for a neighborhood mode.

Implements Utopia::Grid< Space >.

    {
        if (nb_mode == NBMode::empty) {
            return 0;
        }
        else if (nb_mode == NBMode::hexagonal) {
            return 6;
        }
        else {
            throw std::invalid_argument("No '" + nb_mode_to_string(nb_mode)
                + "' neighborhood available for HexagonalGrid! "
                  "Available modes: empty, hexagonal.");
        }
    }

◆ extent_of()

template<class Space >

SpaceVec Utopia::HexagonalGrid< Space >::extent_of ( const IndexType ) const

inlineoverridevirtual

Returns the extent of the cell with the given ID.

The cell's extent corresponds to the tip-to-tip distance of the cell

Note: This method does not perform bounds checking of the given ID!

Implements Utopia::Grid< Space >.

                                                       {
        return _cell_extent;
    }

◆ get_nb_func()

template<class Space >

NBFuncID< Base > Utopia::HexagonalGrid< Space >::get_nb_func	(	NBMode	nb_mode,
		const Config &	nb_params
	)

inlineoverrideprotectedvirtual

Retrieve the neighborhood function depending on the mode.

Implements Utopia::Grid< Space >.

    {
        if (nb_mode == NBMode::empty) {
            return this->_nb_empty;
        }
        else if (nb_mode == NBMode::hexagonal) {
            return get_nb_func_hexagonal(nb_params);
        }
        else {
            throw std::invalid_argument("No '" + nb_mode_to_string(nb_mode)
                + "' neighborhood available for HexagonalGrid! "
                  "Available modes: empty, hexagonal.");
        }
    }

◆ get_nb_func_hexagonal()

template<class Space >

NBFuncID< Base > Utopia::HexagonalGrid< Space >::get_nb_func_hexagonal ( const Config & nb_params )

inlineprotected

Returns a standalone hexagonal neighborhood function.

It extracts the distance parameter from the configuration and depending on the distance parameter and the periodicity of the space decides between four different neighborhood calculation functions. The returned callable does rely on the SquareGrid object, but it includes all parameters from the configuration that can be computed once and then captured; this avoids recomputation.

Parameters

nb_params The configuration for the hexagonal neighborhood method. Expected keys: distance (optional, defaults to 1), which refers to the Manhattan distance of included neighbors.

                                                                  {
        // Extract the optional distance parameter
        constexpr bool check_shape = true;
        const auto distance = get_nb_param_distance<check_shape>(nb_params);
 
        // For distance 1, use the specialized functions which are defined as
        // class members (to don't bloat this method even more). Those
        // functions do not require any calculation or capture that goes beyond
        // the capture of ``this``.
        if (distance <= 1) {
            if (this->is_periodic()) {
                return _nb_hexagonal_periodic;
            }
            else {
                return _nb_hexagonal_nonperiodic;
            }
        }
        // else: distance is > 1. Depending on periodicity of the grid, define
        // the relevant lambda and let it capture as many values as possible in
        // order to avoid recomputation.
 
        throw std::invalid_argument(fmt::format(
            "Hexagonal neighborhood is not implemented for a "
            "distance larger than 1. Requested distance was {}.",
            distance
        ));
    }

◆ get_nb_param_distance()

template<class Space >

template<bool check_shape = false>

DistType Utopia::HexagonalGrid< Space >::get_nb_param_distance ( const Config & params ) const

inlineprotected

Extract the distance neighborhood parameter from the given config.

Note: This will never return a KeyError; if the key is not given, this method will return 1.

Template Parameters

check_shape Whether to check the shape of the grid is large enough for this distance. For all SquareGrid neighborhoods in periodic space, the grid needs to be at least 2 * distance + 1 cells wide in each dimension.

Parameters

params The neighborhood parameters to extract the distance parameter from.

                                                               {
        const auto distance = get_as<DistType>("distance", params, 1);
 
        // Check the value is smaller than the grid shape. It needs to fit into
        // the shape of the grid, otherwise all the algorithms above would have
        // to check for duplicate entries and be set-based, which would be
        // very inefficient.
        if constexpr (check_shape) {
            if (    this->is_periodic()
                and (distance * 2 + 1 > this->shape().min()))
            {
                // To inform about the grid shape, print it to the stringstream
                // and include it in the error message below.
                std::stringstream shape_ss;
                this->shape().print(shape_ss, "Grid Shape:");
 
                throw std::invalid_argument("The grid shape is too small to "
                    "accomodate a neighborhood with 'distance' parameter set "
                    "to " + get_as<std::string>("distance", params, "1")
                    + " in a periodic space!\n" + shape_ss.str());
            }
        }
 
        return distance;
    }

◆ midx_of()

template<class Space >

MultiIndex Utopia::HexagonalGrid< Space >::midx_of ( const IndexType id ) const

inlineoverridevirtual

Returns the multi-index of the cell with the given ID.

Note: This method does not perform bounds checking of the given ID!

Implements Utopia::Grid< Space >.

                                                          {
        return MultiIndex({id % _shape[0], id / _shape[0]});
    }

◆ num_cells()

template<class Space >

IndexType Utopia::HexagonalGrid< Space >::num_cells ( ) const

inlineoverridevirtual

Number of hexagonal cells required to fill the physical space.

This is calculated simply from the _shape member.

Implements Utopia::Grid< Space >.

                                         {
        return _shape[0] * _shape[1];
    }

◆ shape()

template<class Space >

MultiIndex Utopia::HexagonalGrid< Space >::shape ( ) const

inlineoverridevirtual

Get shape of the hexagonal grid.

Implements Utopia::Grid< Space >.

                                      {
        return _shape;
    }

◆ structure()

template<class Space >

GridStructure Utopia::HexagonalGrid< Space >::structure ( ) const

inlineoverridevirtual

Structure of the grid.

Implements Utopia::Grid< Space >.

                                             {
        return GridStructure::hexagonal;
    }

◆ vertices_of()

template<class Space >

std::vector< SpaceVec > Utopia::HexagonalGrid< Space >::vertices_of ( const IndexType id ) const

inlineoverridevirtual

Returns the vertices of the cell with the given ID.

The vertices (pointy-topped arrangement) are given in counter-clockwise order, starting with the position of the bottom left-hand vertex (8 o'clock) of the cell.

Note: This method does not perform bounds checking of the given ID!

Implements Utopia::Grid< Space >.

                                                                       {
        std::vector<SpaceVec> vertices{};
        vertices.reserve(6);
 
        const SpaceVec center = barycenter_of(id);
 
        vertices.push_back(center + SpaceVec({-0.5, -0.25}) % _cell_extent);
        vertices.push_back(center + SpaceVec({ 0. , -0.5 }) % _cell_extent);
        vertices.push_back(center + SpaceVec({ 0.5, -0.25}) % _cell_extent);
        vertices.push_back(center + SpaceVec({ 0.5,  0.25}) % _cell_extent);
        vertices.push_back(center + SpaceVec({ 0. ,  0.5 }) % _cell_extent);
        vertices.push_back(center + SpaceVec({-0.5,  0.25}) % _cell_extent);
 
        return vertices;
    }

Member Data Documentation

◆ _cell_extent

template<class Space >

const SpaceVec Utopia::HexagonalGrid< Space >::_cell_extent

private

The extent of each cell of this discretization (same for all)

The cell's extent corresponds to the tip-to-tip distance

◆ _nb_hexagonal_nonperiodic

template<class Space >

NBFuncID<Base> Utopia::HexagonalGrid< Space >::_nb_hexagonal_nonperiodic

protected

Initial value:

= 
        [this](const IndexType root_id)
    {
        
        IndexContainer neighbor_ids{};
 
        neighbor_ids.reserve(2 * dim);
 
        add_neighbors_in_<0, false>(root_id, neighbor_ids);
        add_neighbors_in_<1, false>(root_id, neighbor_ids);
        add_neighbors_in_<2, false>(root_id, neighbor_ids);
 
        return neighbor_ids;
    }

The Von-Neumann neighborhood for non-periodic grids.

    {
        // Instantiate container in which to store the neighboring cell IDs
        IndexContainer neighbor_ids{};
 
        // The number of neighbors is known; pre-allocating space brings a
        // speed improvement of about factor 2
        neighbor_ids.reserve(2 * dim);
 
        // Depending on the number of dimensions, add the IDs of neighboring
        // cells in those dimensions
        add_neighbors_in_<0, false>(root_id, neighbor_ids);
        add_neighbors_in_<1, false>(root_id, neighbor_ids);
        add_neighbors_in_<2, false>(root_id, neighbor_ids);
 
        // Return the container of cell indices
        return neighbor_ids;
    };

◆ _nb_hexagonal_periodic

template<class Space >

NBFuncID<Base> Utopia::HexagonalGrid< Space >::_nb_hexagonal_periodic

protected

Initial value:

= 
        [this](const IndexType root_id)
    {
        
        IndexContainer neighbor_ids{};
 
        neighbor_ids.reserve(3 * dim);
 
        add_neighbors_in_<0, true>(root_id, neighbor_ids);
        add_neighbors_in_<1, true>(root_id, neighbor_ids);
        add_neighbors_in_<2, true>(root_id, neighbor_ids);
 
        return neighbor_ids;
    }

The Von-Neumann neighborhood for periodic grids.

    {
        // Instantiate container in which to store the neighboring cell IDs
        IndexContainer neighbor_ids{};
 
        // The number of neighbors is known; pre-allocating space brings a
        // speed improvement of about factor 2.
        neighbor_ids.reserve(3 * dim);
 
        // Depending on the number of dimensions, add the IDs of neighboring
        // cells in those dimensions
        add_neighbors_in_<0, true>(root_id, neighbor_ids);
        add_neighbors_in_<1, true>(root_id, neighbor_ids);
        add_neighbors_in_<2, true>(root_id, neighbor_ids);
 
        // Return the container of cell indices
        return neighbor_ids;
    };

◆ _shape

template<class Space >

const MultiIndex Utopia::HexagonalGrid< Space >::_shape

private

The (multi-index) shape of the grid, resulting from resolution.

◆ dim

template<class Space >

constexpr DimType Utopia::HexagonalGrid< Space >::dim = Space::dim

staticconstexpr

The dimensionality of the space to be discretized (for easier access)

The documentation for this class was generated from the following file:

include/utopia/core/grids/hexagonal.hh

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ Base

◆ Config

◆ MultiIndex

◆ SpaceVec

Constructor & Destructor Documentation

◆ HexagonalGrid()

Member Function Documentation

◆ add_neighbors_in_()

◆ barycenter_of()

◆ boundary_cells()

◆ cell_at()

◆ determine_shape()

◆ effective_resolution()

◆ expected_num_neighbors()

◆ extent_of()

◆ get_nb_func()

◆ get_nb_func_hexagonal()

◆ get_nb_param_distance()

◆ midx_of()

◆ num_cells()

◆ shape()

◆ structure()

◆ vertices_of()

Member Data Documentation

◆ _cell_extent

◆ _nb_hexagonal_nonperiodic

◆ _nb_hexagonal_periodic

◆ _shape

◆ dim