Utopia::Space< num_dims > Struct Template Reference

The Space bundles properties about the physical space a model resides in. More...

#include <space.hh>

Public Types
using	SpaceVec = SpaceVecType< dim >
	The type for vectors relating to physical space.

Public Member Functions
	Space (const Config &cfg)
	Construct a Space using information from a config node.
	Space ()
	Default constructor i.e. constructing a space with default parameters.
template<bool include_high_value_boundary = true>
bool	contains (const SpaceVec &pos) const
	Whether this space contains the given coordinate (without mapping it)
SpaceVec	map_into_space (const SpaceVec &pos) const
	Map a position (potentially outside space's extent) back into space.
SpaceVec	displacement (const SpaceVec &pos_0, const SpaceVec &pos_1) const
	Compute the displacement vector between two coordinates.
template<class NormType = std::size_t>
auto	distance (const SpaceVec &pos_0, const SpaceVec &pos_1, const NormType p=2) const
	The distance of two coordinates in space.

Public Attributes
const bool	periodic
	Whether the space is to be assumed periodic.
const SpaceVec	extent
	The physical (euclidean) extent of the space.

Static Public Attributes
static constexpr std::size_t	dim = num_dims
	The dimensionality of the space.

Private Member Functions
bool	setup_periodic (const Config &cfg) const
	Setup the member periodic from a config node.
SpaceVec	setup_extent () const
	Construct a default space extent vector (valued 1 in each dimension)
SpaceVec	setup_extent (const Config &cfg) const
	Construct a space extent vector from a config node.

Detailed Description

template<std::size_t num_dims>
struct Utopia::Space< num_dims >

The Space bundles properties about the physical space a model resides in.

It is, for example, used by the CellManager and its Grid discretization and by the AgentManager to properly map agent positions and movements within the spatial domain.

Template Parameters

num_dims

The dimensionality of the space

Member Typedef Documentation

SpaceVec

template<std::size_t num_dims>

using Utopia::Space< num_dims >::SpaceVec = SpaceVecType<dim>

The type for vectors relating to physical space.

Constructor & Destructor Documentation

Space() [1/2]

template<std::size_t num_dims>

Utopia::Space< num_dims >::Space ( const Config &  cfg )

inline

Construct a Space using information from a config node.

Parameters

cfg	The config node to read the periodic and extent entries from.

    :
        periodic(setup_periodic(cfg)),
        extent(setup_extent(cfg))
    {
        static_assert(dim > 0, "Space::dim needs to be >= 1");
    }

Space() [2/2]

template<std::size_t num_dims>

Utopia::Space< num_dims >::Space ( )

inline

Default constructor i.e. constructing a space with default parameters.

The default space is non-periodic and has default extent of 1. into each dimension.

    :
        periodic(false),
        extent(setup_extent())
    {
        static_assert(dim > 0, "Space::dim needs to be >= 1");
    }

Member Function Documentation

contains()

template<std::size_t num_dims>

template<bool include_high_value_boundary = true>

bool Utopia::Space< num_dims >::contains ( const SpaceVec &  pos ) const

inline

Whether this space contains the given coordinate (without mapping it)

Checks whether the given coordinate is within this space's extent by computing the relative position and checking whether it is within [0, 1] or [0, 1) for all elements.

Note

No distinction is made between periodic and non-periodic space.

Template Parameters

include_high_value_boundary

Whether to check the closed or the half-open interval. The latter case is useful when working with periodic grids, allowing to map values on the high-value boundary back to the low-value boundary.

                                             {
        // Calculate the relative position within the space
        const auto rel_pos = pos / extent;  // element-wise division
 
        // Check that all relative positions are in the respective interval
        if constexpr (include_high_value_boundary) {
            return arma::all(rel_pos >= 0. and rel_pos <= 1.);  // [0, 1]
        }
        else {
            return arma::all(rel_pos >= 0. and rel_pos <  1.);  // [0, 1)
        }
    }

displacement()

template<std::size_t num_dims>

SpaceVec Utopia::Space< num_dims >::displacement ( const SpaceVec &  pos_0, const SpaceVec &  pos_1  ) const

inline

Compute the displacement vector between two coordinates.

Calculates vector pointing from pos_0 to pos_1. In periodic space, it calculates the shorter displacement.

Warning

The displacement of two coordinates in periodic boundary can be maximum of half the domain size, i.e. moving away from a coordinate in a certain direction will decrease the displacement once reached half the domain size.

                                                                              {
        SpaceVec dx = pos_1 - pos_0;
 
        if (not periodic) {
            return dx;
        }
        // else: Need to get shortest distance
 
        return dx - arma::round(dx / extent) % extent;
    }

distance()

template<std::size_t num_dims>

template<class NormType = std::size_t>

auto Utopia::Space< num_dims >::distance ( const SpaceVec &  pos_0, const SpaceVec &  pos_1, const NormType  p = 2  ) const

inline

The distance of two coordinates in space.

Calculates the distance of two coordinates using the norm implemented within Armadillo. In periodic boundary it calculates the shorter distance.

Warning

The distance of two coordinates in periodic boundary can be maximum of half the domain size wrt every dimension, i.e. moving away from a coordinate in a certain direction will decrease the distance once reached half the domain size.

Parameters

p	The norm used to compute the distance, see arma::norm. Can be either an integer >= 1 or one of: "-inf", "inf", "fro"

    {
        return arma::norm(displacement(pos_0, pos_1), p);
    }

map_into_space()

template<std::size_t num_dims>

SpaceVec Utopia::Space< num_dims >::map_into_space ( const SpaceVec &  pos ) const

inline

Map a position (potentially outside space's extent) back into space.

This is intended for use with periodic space. It will also work with non-periodic space, but the input value should not have been permitted in the first place.

Note

The high-value boundary is is mapped back to the low-value boundary, such that all points are well-defined.

                                                       {
        // If it is already within space, nothing to map
        // Check whether it is contained (_excluding_ high value boundary)
        if (contains<false>(pos)) {
            return pos;
        }
        // else: Need to transform back into space
 
        return pos - arma::floor(pos / extent) % extent;
    }

setup_extent() [1/2]

template<std::size_t num_dims>

SpaceVec Utopia::Space< num_dims >::setup_extent ( ) const

inlineprivate

Construct a default space extent vector (valued 1 in each dimension)

                                  {
        SpaceVec ext;
        ext.fill(1.);
        return ext;
    }

setup_extent() [2/2]

template<std::size_t num_dims>

SpaceVec Utopia::Space< num_dims >::setup_extent ( const Config &  cfg ) const

inlineprivate

Construct a space extent vector from a config node.

Parameters

cfg	The config node to read the extent parameter from. If that entry is missing, the default extent (1) is used. If the entry is a scalar, space will be set up to have equal extent in all dimensions. Otherwise, it is expected to be a sequence node.

                                                   {
        if (cfg["extent"]) {
            SpaceVec ext;
 
            if (cfg["extent"].IsScalar()) {
                ext.fill(get_as<double>("extent", cfg));
            }
            else {
                if (dim != cfg["extent"].size()) {
                    throw std::invalid_argument(fmt::format(
                        "Invalid size of `space.extent` sequence ({}) for "
                        "selected space dimensionality ({})!",
                        cfg["extent"].size(), dim
                    ));
                }
                ext = get_as_SpaceVec<dim>("extent", cfg);
            }
 
            if (ext.min() <= 0.) {
                ext.print("Invalid `space.extent`:");
                throw std::invalid_argument(
                    "The space extent needs to be strictly positive in "
                    "all entries, but it contained at least one element <= 0! "
                    "Check the `space.extent` config node to address this."
                );
            }
 
            return ext;
        }
        else {
            // Return the default extent, needs no check
            return setup_extent();
        }
    }

setup_periodic()

template<std::size_t num_dims>

bool Utopia::Space< num_dims >::setup_periodic ( const Config &  cfg ) const

inlineprivate

Setup the member periodic from a config node.

                                                 {
        if (not cfg["periodic"]) {
            throw std::invalid_argument("Missing config entry `periodic` to "
                                        "set up a Space object!");
        }
        return get_as<bool>("periodic", cfg);
    }

Member Data Documentation

dim

template<std::size_t num_dims>

constexpr std::size_t Utopia::Space< num_dims >::dim = num_dims

staticconstexpr

The dimensionality of the space.

extent

template<std::size_t num_dims>

const SpaceVec Utopia::Space< num_dims >::extent

The physical (euclidean) extent of the space.

periodic

template<std::size_t num_dims>

const bool Utopia::Space< num_dims >::periodic

Whether the space is to be assumed periodic.

---

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

• include/utopia/core/space.hh