Grids#

Grid elements#


Grid boundaries#


Grid inner types#

template<class G>
struct grid_inner_types#

Small template class that holds a few types (static members) specialized for each grid type.

It is used for accessing those types from within the grid base classes.

See also

grid_inner_types<profile_grid_xt<S, C>>, grid_inner_types<raster_grid_xt<S, RC, C>>, grid_inner_types<trimesh_xt<S, N>>


Base classes and structures#

Defined in fastscapelib/grid/base.hpp.


enum class fastscapelib::node_status : std::uint8_t#

Node status values.

Node status is a label assigned to each grid/mesh node. It is used to define the structure and boundaries of the modeled domain.

The description of each value is given for indicative pruposes only. Exact semantics may differ depending on the grid type or the objects that are consuming grids.

For example, looped is used only for structured grids.

Values:

enumerator core#

Inner grid node.

enumerator fixed_value#

Dirichlet boundary condition.

enumerator fixed_gradient#

Neumann boundary condition.

enumerator looped#

Reflective boundaries.

struct node#

Represents a grid/mesh node.

Public Members

std::size_t idx#

Node index.

node_status status#

Node status.

struct neighbor#

Represents a grid/mesh node neighbor.

Public Members

std::size_t idx#

Index of the neighbor node.

double distance#

Distance to the neighbor node.

node_status status#

Status at the neighbor node.

class boundary_status#

Base class for setting the status at the border nodes of structured grids.

Subclassed by fastscapelib::profile_boundary_status, fastscapelib::raster_boundary_status

template<class G>
class grid#

Base class for all grid or mesh types.

This class defines grid properties as well as a common API for iterating through grid nodes and their neighbors.

Template Parameters:

G – The derived grid type.

Subclassed by fastscapelib::structured_grid< G >

Grid static properties

static constexpr bool is_structured()#

True if the grid is strutured or False if the grid is an unstructured mesh.

static constexpr bool is_uniform()#

True if the grid is uniform (i.e., constant spacing along each dimension).

static constexpr std::size_t xt_ndims()#

Number of dimensions of the grid field arrays.

static constexpr std::uint8_t n_neighbors_max()#

Maximum number of grid node neighbors.

For strutured grids this corresponds to the actual (fixed) number of neighbors.

Grid properties

inline size_type size() const noexcept#

Returns the total number of grid nodes.

inline shape_type shape() const noexcept#

Returns the shape of the grid node arrays.

const neighbors_cache_type &neighbors_indices_cache()#

Returns the cache used to store node neighbor indices.

Node methods

inline const nodes_status_type &nodes_status() const#

Returns a constant reference to the array of status at grid nodes.

inline node_status nodes_status(const size_type &idx) const#

Returns the status at a given grid node.

Parameters:

idx – The grid node flat index.

inline grid_nodes_indices<G> nodes_indices() const#

Returns a virtual container that may be used to iterate over all grid nodes.

inline grid_nodes_indices<G> nodes_indices(node_status status) const#

Returns a virtual container that may be used to iterate over all grid nodes of a given status.

Parameters:

status – The node status.

inline xt_type nodes_areas() const#

Returns the areas of the direct vicinity of each grid node as an array.

Note: this creates a new container or returns a copy.

inline grid_data_type nodes_areas(const size_type &idx) const noexcept#

Returns the area of the direct vicinity of a grid node.

Parameters:

idx – The grid node flat index.

Neighbor methods

inline size_type neighbors_count(const size_type &idx) const#

Returns the number of neighbors of a given grid node.

Parameters:

idx – The grid node flat index.

inline neighbors_distances_type neighbors_distances(const size_type &idx) const#

Returns an array of the distances to the neighbors of a given grid node.

Follows looped boundary conditions, if any.

Parameters:

idx – The grid node flat index.

inline neighbors_indices_type neighbors_indices(const size_type &idx)#

Returns an array of the indices of the neighbors of a given grid node.

Follows looped boundary conditions, if any.

Parameters:

idx – The grid node flat index.

inline neighbors_indices_type &neighbors_indices(const size_type &idx, neighbors_indices_type &neighbors_indices)#

Resize and fills an array with the neighbors indices of a given grid node.

Follows looped boundary conditions, if any.

This method prevents allocating a new container for better performance.

Parameters:

  • idx – The grid node flat index.

  • neighbors_indices – Reference to the container to be updated with the neighbors indices.

inline neighbors_type neighbors(const size_type &idx)#

Returns a vector of the neighbors of a given grid node.

Follows looped boundary conditions, if any.

Parameters:

idx – The grid node flat index.

Returns:

A vector of neighbor node objects.

inline neighbors_type &neighbors(const size_type &idx, neighbors_type &neighbors)#

Resize and fills a vactor with the neighbors of a given grid node.

Follows looped boundary conditions, if any.

This method prevents allocating a new container for better performance.

Parameters:

  • idx – The grid node flat index.

  • neighbors – Reference to the vector to be updated with the neighbor objects.

Public Types

using derived_grid_type = G#
using inner_types = grid_inner_types<derived_grid_type>#
using grid_data_type = typename inner_types::grid_data_type#
using xt_selector = typename inner_types::xt_selector#
using xt_type = xt_tensor_t<xt_selector, grid_data_type, inner_types::xt_ndims>#
using size_type = typename xt_type::size_type#
using shape_type = typename xt_type::shape_type#
using neighbors_cache_type = typename inner_types::neighbors_cache_type#
using neighbors_type = std::vector<neighbor>#
using neighbors_indices_type = xt::xtensor<size_type, 1>#
using neighbors_distances_type = xt::xtensor<grid_data_type, 1>#
using nodes_status_type = xt_tensor_t<xt_selector, node_status, inner_types::xt_ndims>#

Defined in fastscapelib/grid/structured_grid.hpp

template<class G>
class structured_grid : public fastscapelib::grid<G>#

Extends the common grid interface for all structured grid types.

Template Parameters:

G – The derived grid type.

Grid properties

inline spacing_t spacing() const noexcept#

Returns the (uniform) spacing between two adjacent grid nodes.

Depending on the dimensions of the grid, returns either a single value or an array (constant reference).

inline length_type length() const noexcept#

Returns the length of the grid for all its dimensions.

inline shape_type shape() const noexcept#

Returns the shape of the grid node arrays.

Public Types

using base_type = grid<G>#
using inner_types = grid_inner_types<G>#
using shape_type = typename base_type::shape_type#
using length_type = typename inner_types::length_type#
using spacing_type = typename inner_types::spacing_type#
using spacing_t = std::conditional_t<std::is_arithmetic<spacing_type>::value, spacing_type, const spacing_type&>#

Caching neighbor indices#

Defined in fastscapelib/grid/base.hpp.

A very common repetitive task in Fastscapelib is getting the node indices of all the node neighbors at a given grid node. Using a cache may speed-up this task (at the cost of memory usage), especially for structured grids with looped boundaries. In other cases using a cache won’t provide any benefit, like for unstructured meshes where the topology is already fully contained.


template<std::uint8_t N>
class neighbors_cache#

Provides a cache for grid neighbor indices look-up.

Template Parameters:

N – The size of each array entry in the cache (should correspond to the fixed maximum number of neighbors).

Public Types

template<class T>
using storage_type = std::array<T, N>#
using neighbors_indices_type = storage_type<std::size_t>#

Public Functions

inline neighbors_cache(std::size_t size)#
inline bool has(const std::size_t &idx) const#
inline neighbors_indices_type &get(const std::size_t &idx)#
inline neighbors_indices_type &get_storage(const std::size_t &idx)#
inline void store(const std::size_t &idx, const neighbors_indices_type &neighbors_indices)#
inline std::size_t cache_size() const#
inline std::size_t cache_used() const#
inline void reset()#
inline void remove(const std::size_t &idx)#

Public Static Attributes

static constexpr unsigned int cache_width = N#
template<unsigned int N>
class neighbors_no_cache#

A simple pass-through for grid neighbor indices look-up.

Template Parameters:

N – The size of temporary storage of indices (should correspond to the fixed maximum number of neighbors). If set to zero, the cache will use a variable size container (std::vector) storage type.

Public Types

template<class T>
using storage_type = std::conditional_t<N == 0, std::vector<T>, std::array<T, N>>#
using neighbors_indices_type = storage_type<std::size_t>#

Public Functions

inline neighbors_no_cache(std::size_t)#
inline bool has(const std::size_t&) const#
inline neighbors_indices_type &get(const std::size_t&)#
inline neighbors_indices_type &get_storage(const std::size_t&)#
inline void store(const std::size_t&, const neighbors_indices_type neighbors_indices)#
inline std::size_t cache_size() const#
inline std::size_t cache_used() const#
inline void reset()#
inline void remove(const std::size_t&)#

Public Static Attributes

static constexpr unsigned int cache_width = N#

Profile grid#

Defined in fastscapelib/grid/profile_grid.hpp.


class profile_boundary_status : public fastscapelib::boundary_status#

Status at grid boundary nodes.

Constructors

inline profile_boundary_status(const node_status status)#

Set the same status for all boundary nodes.

inline profile_boundary_status(const node_status left_status, const node_status right_status)#

Set status at the left and right edge nodes of a profile grid.

inline profile_boundary_status(const std::array<node_status, 2> &status)#

Set status at the left and right edge nodes of a profile grid.

inline bool is_horizontal_looped() const#

Return true if periodic (looped) conditions are set for left and right.

Public Members

node_status left = node_status::core#

Status at left edge/border node(s)

node_status right = node_status::core#

Status at right edge/border node(s)

template<class S, class C>
struct grid_inner_types<profile_grid_xt<S, C>>#

Profile grid specialized types.

Public Types

using grid_data_type = double#
using xt_selector = S#
using neighbors_cache_type = C#
using length_type = double#
using spacing_type = double#

Public Static Attributes

static constexpr bool is_structured = true#
static constexpr bool is_uniform = true#
static constexpr std::size_t xt_ndims = 1#
static constexpr uint8_t n_neighbors_max = 2u#
template<class S, class C = neighbors_cache<2>>
class profile_grid_xt#

1-dimensional uniform grid.

Useful for modeling single channel or hillslope profiles.

Template Parameters:

  • S – The xtensor container selector for data array members.

  • C – The grid neighbor nodes cache type.

Constructors

profile_grid_xt(size_type size, spacing_type spacing, const profile_boundary_status &bounds_status, const nodes_status_map_type &nodes_status = {})#

Creates a new profile grid.

Parameters:

  • size – Total number of grid nodes.

  • spacing – Distance between two adjacent grid nodes.

  • bounds_status – Status at boundary nodes (left/right grid edges).

  • nodes_status – Manually define the status at any node on the grid.

Factories

static profile_grid_xt from_length(size_type size, length_type length, const profile_boundary_status &bounds_status, const nodes_status_map_type &nodes_status = {})#

Creates a new profile grid.

Parameters:

  • size – Total number of grid nodes.

  • length – Total physical length of the grid.

  • bounds_status – Status at boundary nodes (left & right grid edges).

  • nodes_status – Manually define the status at any node on the grid.

Public Types

using self_type = profile_grid_xt<S, C>#
using base_type = structured_grid<self_type>#
using inner_types = grid_inner_types<self_type>#
using grid_data_type = typename base_type::grid_data_type#
using xt_selector = typename base_type::xt_selector#
using xt_type = xt_tensor_t<xt_selector, grid_data_type, inner_types::xt_ndims>#
using size_type = typename base_type::size_type#
using shape_type = typename base_type::shape_type#
using length_type = typename base_type::length_type#
using spacing_type = typename base_type::spacing_type#
using code_type = std::uint8_t#
using neighbors_type = typename base_type::neighbors_type#
using neighbors_indices_type = typename base_type::neighbors_indices_type#
using neighbors_distances_type = typename base_type::neighbors_distances_type#
using nodes_status_type = typename base_type::nodes_status_type#
using nodes_status_map_type = typename std::map<size_type, node_status>#
typedef profile_grid_xt<xt_selector> fastscapelib::profile_grid#

Alias template on profile_grid_xt with xt::xtensor used as array container type for data members.

This is mainly for convenience when using in C++ applications.


Raster grid#

Defined in fastscapelib/grid/raster_grid.hpp.


struct raster_node#

Represents a raster grid node.

Public Members

std::size_t row#

Row index.

std::size_t col#

Column index.

node_status status#

Node status.

struct raster_neighbor#

Represents a raster grid node neighbor.

Public Members

std::size_t flatten_idx#

Flat index of the neighbor node.

std::size_t row#

Row index of the neighbor node.

std::size_t col#

Column index of the neighbor node.

double distance#

Distance to the neighbor node.

node_status status#

Status at the neighbor node.

class raster_boundary_status : public fastscapelib::boundary_status#

Status at grid boundary nodes.

To disambiguate the cases at each of the four raster grid corners, node status is set from one of their two overlaping borders according to the following precedance order:

fixed value > fixed gradient > looped > core

Constructors

inline raster_boundary_status(node_status status)#

Set the same status for all boundary nodes.

inline raster_boundary_status(const std::array<node_status, 4> &status)#

Set status at the left, right, top and bottom border nodes of a raster grid.

inline bool is_vertical_looped() const#

Return true if periodic (looped) conditions are set for top and bottom.

inline bool is_horizontal_looped() const#

Return true if periodic (looped) conditions are set for left and right.

Public Members

node_status left = node_status::core#

Status at left border nodes.

node_status right = node_status::core#

Status at right border nodes.

node_status top = node_status::core#

Status at top border nodes.

node_status bottom = node_status::core#

Status at bottom border nodes.

enum class fastscapelib::raster_connect#

Raster grid node connectivity.

Values:

enumerator rook#

4-connectivity (vertical or horizontal)

enumerator queen#

8-connectivity (including diagonals)

enumerator bishop#

4-connectivity (only diagonals)

template<class S, raster_connect RC, class C>
struct grid_inner_types<raster_grid_xt<S, RC, C>>#

Raster grid specialized types.

Public Types

using grid_data_type = double#
using xt_selector = S#
using neighbors_cache_type = C#
using length_type = xt::xtensor_fixed<grid_data_type, xt::xshape<2>>#
using spacing_type = xt::xtensor_fixed<grid_data_type, xt::xshape<2>>#

Public Static Attributes

static constexpr bool is_structured = true#
static constexpr bool is_uniform = true#
static constexpr std::size_t xt_ndims = 2#
static constexpr uint8_t n_neighbors_max = raster_neighbors<RC>::_n_neighbors_max#
template<class S, raster_connect RC, class C = neighbors_cache<raster_neighbors<RC>::_n_neighbors_max>>
class raster_grid_xt#

2-dimensional uniform (raster) grid.

Template Parameters:

  • S – The xtensor container selector for data array members.

  • RC – The kind of raster node connectivity.

  • C – The grid neighbor nodes cache type.

Grid properties

shape_type shape() const noexcept#

Returns the shape of the grid node arrays.

raster_boundary_status bounds_status() const noexcept#

Returns the grid node status at grid left / right / top / bottom borders.

Node methods

inline code_type nodes_codes(const size_type &row, const size_type &col) const noexcept#

Given row and col indices, return a code in the range [0,8], which corresponds to one of the following characteristic locations on the grid (i.e., inner/border/corner).

Use a row-major layout:

0 &#8212; 1 &#8212; 2 | | 3 4 5 | | 6 &#8212; 7 &#8212; 8

inline code_type nodes_codes(const size_type &idx) const noexcept#

Given a flat index, return a code in the range [0,8], which corresponds to one of the following characteristic locations on the grid (i.e., inner/border/corner).

Use a row-major layout:

0 &#8212; 1 &#8212; 2 | | 3 4 5 | | 6 &#8212; 7 &#8212; 8

Neighbor methods

inline neighbors_indices_raster_type &neighbors_indices(const size_type &row, const size_type &col, neighbors_indices_raster_type &neighbors_indices)#

Resize and fills an array with the neighbors indices of a given grid node.

Follows looped boundary conditions, if any.

This method prevents allocating a new container for better performance.

Parameters:

  • row – The grid node row index.

  • col – The grid node column index.

  • neighbors_indices – Reference to the container to be updated with the neighbors indices.

inline neighbors_indices_raster_type neighbors_indices(const size_type &row, const size_type &col)#

Returns an array of the indices of the neighbors of a given grid node.

Follows looped boundary conditions, if any.

Parameters:

  • row – The grid node row index.

  • col – The grid node column index.

inline neighbors_raster_type &neighbors(const size_type &row, const size_type &col, neighbors_raster_type &neighbors)#

Resize and fills a vactor with the neighbors of a given grid node.

Follows looped boundary conditions, if any.

This method prevents allocating a new container for better performance.

Parameters:

  • row – The grid node row index.

  • col – The grid node column index.

  • neighbors – Reference to the vector to be updated with the neighbor objects.

inline neighbors_raster_type neighbors(const size_type &row, const size_type &col)#

Returns a vector of the neighbors of a given grid node.

Follows looped boundary conditions, if any.

Parameters:

  • row – The grid node row index.

  • col – The grid node column index.

Returns:

A vector of neighbor node objects.

Constructors

raster_grid_xt(const shape_type &shape, const spacing_type &spacing, const raster_boundary_status &bounds_status, const nodes_status_map_type &nodes_status = {})#

Creates a new raster grid.

Parameters:

  • shape – Shape of the grid (number of rows and cols).

  • spacing – Distance between two adjacent rows / cols.

  • bounds_status – Status at boundary nodes (left/right/top/bottom borders).

  • nodes_status – Manually define the status at any node on the grid.

Factories

static raster_grid_xt from_length(const shape_type &shape, const length_type &length, const raster_boundary_status &bounds_status, const nodes_status_map_type &nodes_status = {})#

Creates a new raster grid.

Parameters:

  • shape – Shape of the grid (number of rows and cols).

  • length – Total physical lengths of the grid.

  • bounds_status – Status at boundary nodes (left/right/top/bottom borders).

  • nodes_status – Manually define the status at any node on the grid.

Public Types

using self_type = raster_grid_xt<S, RC, C>#
using base_type = structured_grid<self_type>#
using inner_types = grid_inner_types<self_type>#
using grid_data_type = typename base_type::grid_data_type#
using xt_selector = typename base_type::xt_selector#
using xt_type = xt_tensor_t<xt_selector, grid_data_type, inner_types::xt_ndims>#
using size_type = typename base_type::size_type#
using shape_type = typename base_type::shape_type#
using length_type = typename base_type::length_type#
using spacing_type = typename base_type::spacing_type#
using code_type = std::uint8_t#
using raster_idx_type = std::pair<size_type, size_type>#
using neighbors_type = typename base_type::neighbors_type#
using neighbors_indices_type = typename base_type::neighbors_indices_type#
using neighbors_distances_type = typename base_type::neighbors_distances_type#
using neighbors_indices_raster_type = std::vector<raster_idx_type>#
using neighbors_raster_type = std::vector<raster_neighbor>#
using nodes_status_type = typename base_type::nodes_status_type#
using nodes_status_map_type = typename std::map<raster_idx_type, node_status>#
typedef raster_grid_xt<xt_selector, raster_connect::queen> fastscapelib::raster_grid#

Alias template on raster_grid_xt with xt::xtensor used as array container type for data members.

This is mainly for convenience when using in C++ applications.


Triangular mesh#

Defined in fastscapelib/grid/trimesh.hpp.


template<class S, unsigned int N>
struct grid_inner_types<trimesh_xt<S, N>>#

2-d triangular mesh specialized types.

Public Types

using grid_data_type = double#
using xt_selector = S#
using neighbors_cache_type = neighbors_no_cache<0>#

Public Static Attributes

static constexpr bool is_structured = false#
static constexpr bool is_uniform = false#
static constexpr std::size_t xt_ndims = 1#
static constexpr uint8_t n_neighbors_max = N#
template<class S, unsigned int N = 20>
class trimesh_xt#

2-dimensional triangular (unstructured) mesh.

Fastscapelib grid adapter for a 2-d triangular mesh. This class requires an input mesh (it doesn’t provide any meshing capability).

Template Parameters:

  • S – The xtensor container selector for data array members.

  • N – The maximum number of node neighbors.

Constructors

trimesh_xt(const points_type &points, const triangles_type &triangles, const nodes_status_map_type &nodes_status = {})#

Creates a new triangular mesh.

If nodes_status is empty, a “fixed value” status is set for all boundary nodes (i.e., the end-points of all the edges that are not shared by more than one triangle).

Parameters:

  • points – The mesh node x,y coordinates (array of shape [N, 2]).

  • triangles – The node indices of the triangles (array of shape [K, 3]).

  • nodes_status – Manually define the status at any node on the mesh.

trimesh_xt(const points_type &points, const triangles_type &triangles, const nodes_status_array_type &nodes_status)#

Creates a new triangular mesh.

Parameters:

  • points – The mesh node x,y coordinates (array of shape [N, 2]).

  • triangles – The node indices of the triangles (array of shape [K, 3]).

  • nodes_status – The status of all nodes on the mesh (array of shape [N]).

Public Types

using self_type = trimesh_xt<S, N>#
using base_type = grid<self_type>#
using grid_data_type = typename base_type::grid_data_type#
using xt_selector = typename base_type::xt_selector#
using size_type = typename base_type::size_type#
using shape_type = typename base_type::shape_type#
using points_type = xt_tensor_t<xt_selector, grid_data_type, 2>#
using triangles_type = xt_tensor_t<xt_selector, size_type, 2>#
using indices_type = xt_tensor_t<xt_selector, size_type, 1>#
using areas_type = xt_tensor_t<xt_selector, grid_data_type, 1>#
using neighbors_type = typename base_type::neighbors_type#
using neighbors_indices_type = typename base_type::neighbors_indices_type#
using neighbors_distances_type = typename base_type::neighbors_distances_type#
using nodes_status_type = typename base_type::nodes_status_type#
using nodes_status_map_type = typename std::map<size_type, node_status>#
using nodes_status_array_type = xt_tensor_t<xt_selector, node_status, 1>#
typedef trimesh_xt<xt_selector> fastscapelib::trimesh#

Alias template on trimesh_xt with xt::xtensor used as array container type for data members.

This is mainly for convenience when using in C++ applications.