Template Class BlockIterator

• Defined in File block_iterator.hpp

Inheritance Relationships

Derived Type

• public ripple::IndexedIterator< T, Space > (Template Class IndexedIterator)

Class Documentation

template<typename T, typename Space>
class ripple::BlockIterator

The BlockIterator class defines a iterator over a block, for a given space which defines the region of the block.

The iterator only iterates over the internal space of the block, not over the padding, and does not have any knowledge of the where the block is in the global context, or where the iterator is in the block. It is ideal for cases where such information is not required, and operations are relative to the iterator (i.e stencil-like operations, operations which required neighbour data, and work on shared memory data).

The type T for the iterator can be either a normal type, or type which implements the StridableLayout interface. Regardless, the use is the same, and the iterator operator as if it was a pointer to T.

Todo:

Modify the implementation to take a reference to the space, so that the space can be stored in shared memory due to the iterator requiring a significant number of registers in 3D.

The iterator only iterates over the internal space of the block, not over the padding, and does not have any knowledge of the where the block is in the global context, or where the iterator is in the block. It is ideal for cases where such information is not required, and operations are relative to the iterator (i.e stencil-like operations, operations which required neighbour data, and work on shared memory data).

Template Parameters

• T: The data type which the iterator will access.

• Space: The type which defines the iteration space.

The type T for the iterator can be either a normal type, or type which implements the StridableLayout interface. Regardless, the use is the same, and the iterator operator as if it was a pointer to T.

Template Parameters

• T: The data type which the iterator will access.

• Space: The type which defines the iteration space.

Subclassed by ripple::IndexedIterator< T, Space >

Public Types

using RawPtr = typename LayoutTraits::RawPtr

Defines the type of the raw pointer to the data.

using ConstRawPtr = typename LayoutTraits::ConstRawPtr

Defines the type of a const raw pointer to the data.

Public Functions

BlockIterator(Storage data_ptr, Space space) noexcept

Constructor to create the iterator from the storage type and a space over which the iterator can iterate.

If the type T is a StridableLayout type, then the storage must be an implementation of the StorageAccessor interface, otherwise (for regular types) the storage must be a pointer to the type.

Parameters

• data_ptr: A pointer (or type which points) to the data.

• space: The space over which the iterator can iterate.

auto operator*() noexcept -> Ref

Overload of the dereference operator to access the type T pointed to by the iterator.

Return

A reference to the type stored in the iterator.

auto operator*() const noexcept -> ConstRef

Overload of the dereference operator to access the type T pointed to by the iterator.

Return

A const reference to the type T pointer to by the iterator.

auto operator->() noexcept -> Ptr

Overload of the access operator to access the underlying data.

Return

A pointer, or pointer-like object for the iterated type.

auto operator->() const noexcept -> ConstPtr

Overload of the access operator to access the underlying data.

Return

A pointer, or pointer-like oject to the iterated type.

auto unwrap() const noexcept -> CopyType

Unwraps the iterated type.

Return

A copy of the data to which the iterator points.

template<typename Dim>
constexpr auto offset(Dim &&dim, int amount) const noexcept -> BlockIterator

Offsets the iterator by amount positions in the block in the dim dimension.

Return

A new iterator to the the offset location.

Parameters

• dim: The dimension to offset in

• amount: The amount to offset by.

Template Parameters

• Dim: The type of the dimension specifier.

template<typename Dim>
constexpr auto shift(Dim &&dim, int amount) noexcept -> void

Shifts the iterator by amount positions in the block in the dim dimension.

This modifies the iterator to be at the shifted location.

Parameters

• dim: The dimension to offset in

• amount: The amount to offset by.

Template Parameters

• Dim: The type of the dimension specifier.

auto data() noexcept -> RawPtr

Provides access to the underlying data for the iterator.

Return

A pointer to the underlying data.

auto data() const noexcept -> ConstRawPtr

Provides const access to the underlying data for the iterator.

Return

A pointer to the underlying data.

decltype(auto) storage() noexcept

Returns a reference to the storage type.

decltype(auto) storage() const noexcept

Returns a reference to the storage type.

template<typename Dim>
auto is_valid(Dim &&dim) const noexcept -> bool

Determines if the iterator is valid in the dimension, that is, its index is less than the size of the global grid.

Return

true if the iterator is valid.

Parameters

• dim: The dimension to check validity in.

Template Parameters

• Dim: The type of the dimension specifier.

constexpr auto dimensions() const noexcept -> size_t

Provides the number of dimension for the iterator.

Return

The number of dimensions for the iterator.

template<typename Dim>
constexpr auto backward_diff(Dim &&dim, int amount = 1) const noexcept -> CopyType

Computes the backward difference between this iterator and the iterator amount places from from this iterator in dimension dim.

\begin{equation} \Delta \phi = \phi_{d}(i) - \phi_{d}(i - \textrm{amount}) \end{equation}

The default is that amount is 1, i.e:

// The following is the same:
auto diff = it.backward_diff(ripple::dim_x);
auto diff = it.backward_diff(ripple::dim_x, 1);

Note

If the iterated data is a vector type, the difference is computed elementwise for each component.

Return

The backward difference of this iterator and the one behind it in the given dimension.

Parameters

• dim: The dimension to offset in.

• amount: The amount to offset the iterator by.

Template Parameters

• Dim: The type of the dimension.

template<typename Dim>
constexpr auto forward_diff(Dim &&dim, int amount = 1) const noexcept -> CopyType

Computes the forward difference between this iterator and the iterator amount places from from this iterator in dimension dim.

\begin{equation} \Delta \phi = \phi_{d}(i + \textrm{amount}) - \phi_{d}(i) \end{equation}

The default is that amount is 1, i.e:

// The following is the same:
auto diff = it.forward_diff(ripple::dim_x);
auto diff = it.forward_diff(ripple::dim_x, 1);

Note

If the iterated data is a vector type, the difference is computed elementwise for each component.

Return

The forward difference of the iterator ahead of this iterator and this iterator in the given dimension.

Parameters

• dim: The dimension to offset in.

• amount: The amount to offset the iterator by.

Template Parameters

• Dim: The type of the dimension.

template<typename Dim, typename Index>
constexpr auto central_diff(Dim &&dim, Index &&index, int amount) const noexcept -> UnderlyingType

Computes the central difference for the cell pointed to by this iterator, using the iterator amount forward and amount backward of this iterator in the dim dimension.

\begin{equation} \Delta \phi = \phi_{d}(i + \textrm{amount}) - \phi_{d}(i - \textrm{amount}) \end{equation}

The default is that amount is 1, i.e:

// The following is the same:
auto diff = it.central_diff(ripple::dim_x);
auto diff = it.central_diff(ripple::dim_x, 1);

Note

If the iterated data is a vector type, the difference is computed elementwise for each component.

Return

The difference between the underlying data ahead and behind of this iterator in the given dimension.

Parameters

• dim: The dimension to offset in.

• amount: The amount to offset the iterator by.

Template Parameters

• Dim: The type of the dimension.

template<typename Dim>
constexpr auto central_diff(Dim &&dim, int amount = 1) const noexcept -> CopyType

Computes the central difference for the cell pointed to by this iterator, using the iterator amount forward and amount backward of this iterator in the dim dimension.

\begin{equation} \Delta \phi = \phi_{d}(i + \textrm{amount}) - \phi_{d}(i - \textrm{amount}) \end{equation}

The default is that amount is 1, i.e:

// The following is the same:
auto diff = it.central_diff(ripple::dim_x);
auto diff = it.central_diff(ripple::dim_x, 1);

Note

If the iterated data is a vector type, the difference is computed elementwise for each component.

Return

The difference between the underlying data ahead and behind of this iterator in the given dimension.

Parameters

• dim: The dimension to offset in.

• amount: The amount to offset the iterator by.

Template Parameters

• Dim: The type of the dimension.

template<typename Dim>
constexpr auto second_diff(Dim &&dim, int amount = 1) const noexcept -> CopyType

Computes the second derivative with respect to the given dimension.

\begin{equation} \phi_{dd} = \phi_{d + \textrm{amount}) - 2 \phi_{d} + \phi_{d - \textrm{amount}) \end{equation}

The default is that

amount is 1, i.e:

Note

This does not do the divison by $h^2$, as it assumes that it is 1.

// The following is the same:
auto diff = it.second_diff(ripple::dim_x);
auto diff = it.second_diff(ripple::dim_x, 1);

Note

If the iterated data is a vector type, the difference is computed elementwise for each component.

Return

The second difference in the given dimension.

Parameters

• dim: The dimension to offset in.

• amount: The amount to offset the iterator by.

Template Parameters

• Dim: The type of the dimension.

template<typename Dim1, typename Dim2>
constexpr auto second_partial_diff(Dim1 &&dim1, Dim2 &&dim2, int amount = 1) const noexcept -> CopyType

Computes the second partialderivative with respect to the given dimensions:

\begin{equation} \phi_{dd} = \frac{ \phi_{d1 + \textrm{a}, d2 + \textrm{a}) - \phi_{d1 + \textrm{a}, d2 - \textrm{a}) - \phi_{d1 - \textrm{a}, d2 + \textrm{a}) + \phi_{d1 - \textrm{a}, d2 - \textrm{a}) }{4} \end{equation}

The default is that

amount is 1, i.e:

Note

This does not do the divison by $h^2$, as it assumes that it is 1.

// The following is the same:
auto diff = it.second_diff(ripple::dim_x);
auto diff = it.second_diff(ripple::dim_x, 1);

Note

If the iterated data is a vector type, the difference is computed elementwise for each component.

Return

The second difference in the given dimension.

Parameters

• dim: The dimension to offset in.

• amount: The amount to offset the iterator by.

Template Parameters

• Dim: The type of the dimension.

template<typename DataType>
constexpr auto grad(DataType dh = 1) const noexcept -> Vec

Computes the gradient of the data iterated over, as:

\begin{equation} \nabla \phi = \left[ \frac{d}{dx}, .., \frac{d}{dn} \right] \phi \end{equation}

For a given dimension, the compuatation is:

\begin{eqution} \frac{d \phi}{dx} = \frac{\phi(x + dh) - \phi(x - dh)}{2 dh} \end{equation}

Note

The gradient computation for each deimension uses the central difference, thus the iterator must be valid on both sides in all dimensions, otherwise the resulting behaviour is undefined.

Note

If the iterated data is a vector type, the gradient is computed elementwise for each component.

See

grad_dim

Return

A vector of N dimensions, with the value in each dimension set to the gradient in the given dimension.

Parameters

• dh: The resolution of the grid the iterator iterates over.

Template Parameters

• DataType: The type of the resolution operator.

template<typename Dim, typename DataType>
constexpr auto grad_dim(Dim &&dim, DataType dh = 1) const noexcept -> CopyType

Computes the gradient of the iterated data in a specific dimension as:

\begin{eqution} \frac{d \phi}{dx} = \frac{\phi(x + dh) - \phi(x - dh)}{2dh} \end{equation}

Note

The gradient computation uses the central difference, so the data on each side of the iterator must be valid, otherwise the resulting behaviour is undefined.

Note

If the iterated data is a vector type, the gradient is computed elementwise for each component.

Return

The gradient of the iterated data in the given dimension.

Parameters

• dim: The dimension to get the gradient in.

• dh: The resolution of the grid the iterator iterates over.

Template Parameters

• Dim: The type of the dimension specifier.

• DataType: The type of the discretization resolution.

template<typename DataType>
constexpr auto norm(DataType dh = DataType(1)) const noexcept -> Vec

Computes the norm of the data, which is defined as:

\begin{equation}

• \frac{\nabla \phi}{|\nabla \phi|} \end{equation}

Note

If the iterated data is a vector type the computation is performed elementwise for each component of the vector type.

Note

This will assert in debug if the division is too close to zero.

Return

The norm of the iterated data.

Parameters

• dh: The resolution of the grid the iterator iterates over.

Template Parameters

• DataType: The type of the discretization resolution.

template<typename DataType>
constexpr auto norm_sd(DataType dh = 1) const noexcept -> Vec

Computes the norm of the data, which is defined as:

\begin{equation} -\frac{\nabla \phi}{|\nabla \phi|} \end{equation}

for the case that it is known that $phi$ is a signed distance function and hence that $|\nabla \phi| = 1$.

In this case, the computation of the magnitude, and the subsequent division by its square root can be avoided, which is a significant performance improvement.

Note

If the iterated data is a vector type the computation is performed elementwise for each component of the vector type.

Return

The norm of the iterated data.

Parameters

• dh: The resolution of the grid the iterator iterates over.

Template Parameters

• DataType: The type of descretization resolution.

template<typename DataType>
constexpr auto curvature(DataType dh = 1) const noexcept -> DataType

Computes the curvature for the iterator, which is defined as:

\begin{equation} \kappa = \nabla \cdot \eft( \frac{\nabla \phi}{|\nabla \phi|} \right) \end{equation}

Return

A value of the curvature.

Parameters

• dh: The resolution of the iteration domain.

Template Parameters

• DataType: The type of the data for the resolution.

template<typename DataType>
constexpr auto curvature_2d(DataType dh = 1) const noexcept -> DataType

Computes the curvature for the iterator, which is defined as:

\begin{equation} \kappa = \nabla \cdot \eft( \frac{\nabla \phi}{|\nabla \phi|} \right) \end{equation}

Return

A value of the curvature.

Parameters

• dh: The resolution of the iteration domain.

Template Parameters

• DataType: The type of the data for the resolution.

template<typename DataType>
constexpr auto curvature_3d(DataType dh = 1) const noexcept -> DataType

Computes the curvature for the iterator, which is defined as:

\begin{equation} \kappa = \nabla \cdot \eft( \frac{\nabla \phi}{|\nabla \phi|} \right) \end{equation}

Note

This computes the mean curvature, which for a sphere is equal to $-\frac{1}{R}$, rather than the *Gaussian curvature$ which would be equal to $-\frac{1}{R^2}$.

Return

A value of the curvature.

Parameters

• dh: The resolution of the iteration domain.

Template Parameters

• DataType: The type of the data for the resolution.

constexpr auto size() const noexcept -> size_t

Gets the total size of the iteration space.

Note

The size does not include padding elements.

Return

The total number of elements in the iteration space.

template<typename Dim>
constexpr auto size(Dim &&dim) const noexcept -> size_t

Getss the size of the iteration space in the given dimension dim.

Note

The size does not include padding elements.

Return

The number of elements in the iteration space for the given dimension.

Parameters

• dim: The dimension to get the size of.

Template Parameters

• Dim: The type of the dimension specifier.

template<typename Dim>
constexpr auto resize(Dim &&dim, size_t size) noexcept -> void

Resizes the given dimension to the given number of elements.

constexpr auto padding() const noexcept -> size_t

Gets the amount of padding for the iteration space.

Note

All dimensions have this amount of padding on each side of the dimension.

Return

The amount of padding for a single side of a dimension in the iteration space.

Public Static Attributes

constexpr size_t dims = space_traits_t<Space>::dimensions

The number of dimensions for the iterator.

Protected Attributes

Storage data_ptr_

A pointer to the data.

Space space_

The space over which to iterate.