Field.h

This header defines various block field types. The essential block field is a scalar field. Components of higher rank tensors are built using the corresponding scalar field type. The memory layout of a field is a structure of arrays. Face fields are handled separately for each dimension in DIM. The FaceContainer type is a convenience type for a compound of DIM face fields with the corresponding index range for each direction.

struct FieldState

Default meta data (state) of a block field.

Minimal (default) state of a field is empty. Custom field state types my add additional state to describe meta data of a field. A field state type must define copy semantics. Components in TensorField types and FaceContainer types share one instance of a state.

template<typename T, Cubism::EntityType Entity, size_t DIM = CUBISM_DIMENSION, typename State = FieldState, template<typename> class Alloc = AlignedBlockAllocator>
class Cubism::Block::Field : public Cubism::Block::Data<T, Entity, DIM, Alloc<T>>

Block scalar field base class.

Generic block scalar field type used by Grid classes to compose a certain topology of block fields.

Template Parameters

  • T: Field data type

  • Entity: Entity type

  • DIM: Field dimension

  • State: Field state type

  • Alloc: Memory allocator

Public Types

using iterator = IteratorBase<DataType>

Iterator for underlying data.

using const_iterator = IteratorBase<const DataType>

const iterator for underlying data

Public Functions

Field() = delete

Default constructor.

inline explicit Field(const IndexRangeType &r, const FieldStateType &fs = FieldStateType())

Main field constructor.

Parameters

  • r: Index range that spans the data

  • fs: Field state

inline explicit Field(const IndexRangeType &r, FieldStateType *pfs)

Low-level field constructor (for higher rank tensors)

Parameters

  • r: Index range that spans the data

  • pfs: Field state pointer (externally managed)

inline Field(const Field &f, const typename BlockDataType::MemoryOwner o)

Low-level copy constructor for deep and shallow copies.

Parameters

  • f: Field to be copied

  • o: Memory ownership (BlockDataType::MemoryOwner::Yes: deep copy)

inline Field(const Field &f, const typename BlockDataType::MemoryOwner o, FieldStateType *pfs)

Low-level copy constructor for deep and shallow copies (for higher rank tensors)

Parameters

  • f: Field to be copied

  • o: Memory ownership (BlockDataType::MemoryOwner::Yes: deep copy)

  • pfs: External field state

inline Field(const NestedVector<IndexRangeType> &range_list, const NestedVector<DataType*> &ptr_list, const NestedVector<size_t> &bytes_list, const NestedVector<FieldStateType*> &state_list, const bool subfield = false)

Low-level constructor for external memory management.

The nested vector data structure is used to simplify the interface between scalar fields, tensor fields and face field containers. A subfield component applies to higher rank tensors and face field containers which share the field state among each others.

Parameters

  • range_list: Vector of index range

  • ptr_list: Vector of block data pointer

  • bytes_list: Number of bytes pointed to by pointer in ptr_list

  • state_list: Vector of field state pointer

  • subfield: Subfield component indicator

inline Field(const BlockDataType &d)

Low-level constructor for use with a block data type.

Useful for a FieldLab and Cubsim::IO routines for example.

Parameters

  • d: Base block data object (owns memory)

inline Field(const Field &c)

Standard copy constructor for a scalar field.

This constructor is not designed to be used with individual components of a rank > 0 tensor or face containers. The copy constructors of these data structures should be used instead (unless you know what you do).

Parameters

  • c: Field to copy from

inline Field(Field &&c) noexcept

Standard move constructor.

Parameters

  • c: Field to move from

inline ~Field() override

Virtual destructor.

inline Field &operator=(const Field &c)

Standard copy assignment operator.

Note

Only field data is copied by this operator, not state.

Return

This field with contents copied from c

Parameters

  • c: Field to copy from

inline Field &operator=(Field &&c)

Standard move assignment operator.

Note

This operator moves data and state.

Return

This field with contents moved from c

Parameters

  • c: Field to move from

inline iterator begin() noexcept

Begin of data.

Return

Iterator

inline iterator end() noexcept

End of data.

Return

Iterator

inline const_iterator cbegin() const noexcept

Begin of data.

Return

const iterator

inline const_iterator cend() const noexcept

End of data.

Return

const iterator

inline size_t size() const

Number of data elements carried by field.

Return

Size of data index range

inline bool isScalar() const

Test if field belongs to scalar class.

Return

Boolean (true if scalar, false if higher rank tensor class)

inline FieldStateType &getState()

Get field state.

Return

reference to state

inline const FieldStateType &getState() const

Get field state.

Return

const reference to state

inline BCVector &getBC()

Get list of boundary conditions.

Return

Reference to vector of BC’s

inline const BCVector &getBC() const

Get list of boundary conditions.

Return

const reference to vector of BC’s

template<typename T, size_t RANK, Cubism::EntityType Entity, size_t DIM = CUBISM_DIMENSION, typename State = FieldState, template<typename> class Alloc = AlignedBlockAllocator>
class Cubism::Block::TensorField : public Cubism::Block::FieldContainer<Field<T, Entity, DIM, State, Alloc>>

Generic tensor field.

Template Parameters

  • T: Field data type

  • RANK: Tensor rank

  • Entity: Entity type

  • DIM: Field dimension

  • State: Field state type

  • Alloc: Memory allocator

Public Functions

TensorField() = delete

Default constructor.

inline explicit TensorField(const IndexRangeType &r, const FieldStateType &fs = FieldStateType())

Main constructor to generate a tensor field.

Parameters

  • r: Index range spanned by the field data

  • fs: Field state initial value

inline explicit TensorField(const IndexRangeType &r, FieldStateType *pfs)

Low-level field constructor (for higher rank tensors)

Parameters

  • r: Index range that spans the data

  • pfs: Field state pointer (externally managed)

inline TensorField(const TensorField &tfc, const MemoryOwner o)

Low-level copy constructor for deep and shallow copies.

Parameters

  • tfc: Tensor field container to be copied

  • o: Memory ownership (BlockDataType::MemoryOwner::Yes: deep copy)

inline TensorField(const TensorField &tfc, const MemoryOwner o, const FieldStateType *pfs)

Low-level copy constructor for deep and shallow copies (for higher rank tensors)

Parameters

  • tfc: Tensor field container to be copied

  • o: Memory ownership (BlockDataType::MemoryOwner::Yes: deep copy)

  • pfs: External field state

inline TensorField(const NestedVector<IndexRangeType> &range_list, const NestedVector<DataType*> &ptr_list, const NestedVector<size_t> &bytes_list, const NestedVector<FieldStateType*> &state_list, const bool subfield = false)

Low-level constructor for external memory management.

The nested vector data structure is used to simplify the interface between scalar fields, tensor fields and face field containers. A subfield component applies to higher rank tensors and face field containers which share the field state among each others.

Parameters

  • range_list: Vector of index range

  • ptr_list: Vector of block data pointer

  • bytes_list: Number of bytes pointed to by pointer in ptr_list

  • state_list: Vector of field state pointer

  • subfield: Subfield component indicator

inline TensorField(const TensorField &c)

Copy constructor.

Parameters

  • c: Tensor field to copy from

inline IndexRangeType getIndexRange(const size_t = 0) const

Get index range.

Return

Index range spanned by the data

inline FieldStateType &getState()

Get field state.

A tensor field shares one field state instance with all its components.

Return

Reference to state

inline const FieldStateType &getState() const

Get field state.

A tensor field shares one field state instance with all its components.

Return

const reference to state

inline MemoryOwner getMemoryOwnership() const

Get memory ownership.

Return

Enumeration type describing the memory ownership

inline FieldType &operator[](const size_t i)

Component field access.

Parameters

  • i: Component index

inline const FieldType &operator[](const size_t i) const

Component field access.

Parameters

  • i: Component index

template<typename TComp>
inline FieldType &operator[](const TComp &t)

Component field access.

Template Parameters

  • TComp: Special type that defines a cast to size_t

Parameters

  • t: Component of tensor

template<typename TComp>
inline const FieldType &operator[](const TComp &t) const

Component field access.

Template Parameters

  • TComp: Special type that defines a cast to size_t

Parameters

  • t: Component of tensor

template<typename TField>
class Cubism::Block::FaceContainer : public Cubism::Block::FieldContainer<TField>

Container class for all faces in a CUBISM_DIMENSION-ional problem.

For CUBISM_DIMENSION in {1,2,3}, the face field for faces with normal in the X direction can be obtained with ff[0] or ff[Cubism::Dir::X] for example, where ff is of type FaceContainer.

Template Parameters

  • TField: Face field type (scalar or tensor)

Public Functions

FaceContainer() = delete

Default constructor.

inline explicit FaceContainer(const IndexRangeType &cell_domain, const FieldStateType &fs = FieldStateType())

Main constructor to generate a face container.

Parameters

  • cell_domain: Index range spanned by the cell domain

  • fs: Field state initial value

inline FaceContainer(const FaceContainer &ffc, const MemoryOwner o)

Low-level copy constructor for deep and shallow copies.

Parameters

  • ffc: Face field container to be copied

  • o: Memory ownership (BlockDataType::MemoryOwner::Yes: deep copy)

inline FaceContainer(const NestedVector<IndexRangeType> &range_list, const NestedVector<DataType*> &ptr_list, const NestedVector<size_t> &bytes_list, const NestedVector<FieldStateType*> &state_list, const bool subfield = false)

Low-level constructor for external memory management.

The nested vector data structure is used to simplify the interface between scalar fields, tensor fields and face field containers. A subfield component applies to higher rank tensors and face field containers which share the field state among each others.

Parameters

  • range_list: Vector of index range

  • ptr_list: Vector of block data pointer

  • bytes_list: Number of bytes pointed to by pointer in ptr_list

  • state_list: Vector of field state pointer

  • subfield: Subfield component indicator

inline FaceContainer(const FaceContainer &c)

Copy constructor.

Parameters

  • c: Face container to copy from

inline IndexRangeType getIndexRange(const size_t i) const

Get index range.

Return

Index range spanned by the data

Parameters

  • i: Direction index

template<typename Dir>
inline IndexRangeType getIndexRange(const Dir t) const

Get index range.

Return

Index range spanned by the data

Template Parameters

  • Dir: Special type that defines a cast to size_t

Parameters

  • t: Direction of face

inline FieldStateType &getState()

Get field state.

A face field container shares one field state instance with all its components.

Return

Reference to state

inline const FieldStateType &getState() const

Get field state.

A face field container shares one field state instance with all its components.

Return

const reference to state

inline MemoryOwner getMemoryOwnership() const

Get memory ownership.

Return

Enumeration type describing the memory ownership

inline FaceComponentType &operator[](const size_t i)

Face component access.

Return

Reference to face component

Parameters

  • i: Direction index

inline const FaceComponentType &operator[](const size_t i) const

Face component access.

Return

const reference to face component

Parameters

  • i: Direction index

template<typename Dir>
inline FaceComponentType &operator[](const Dir &t)

Face component access.

Return

Reference to face component

Template Parameters

  • Dir: Special type that defines a cast to size_t

Parameters

  • t: Direction of face

template<typename Dir>
inline const FaceComponentType &operator[](const Dir &t) const

Face component access.

Return

const reference to face component

Template Parameters

  • Dir: Special type that defines a cast to size_t

Parameters

  • t: Direction of face

template<typename TField>
class Cubism::Block::FieldContainer

Field container type.

This is an actively managed field container. Unlike std::vector, the destructors of the container elements are called upon destruction of the container. An incomplete container contains nullptr for some of its components.

Template Parameters

  • TField: Type of field

Subclassed by Cubism::Block::FaceContainer< TField >

Public Types

using iterator = typename ContainerType::iterator

Iterator for field pointers in ContainerType.

using const_iterator = typename ContainerType::const_iterator

const iterator for field pointers in ContainerType

using reverse_iterator = typename ContainerType::reverse_iterator

Reverse iterator for field pointers in ContainerType.

using const_reverse_iterator = typename ContainerType::const_reverse_iterator

const reverse iterator for field pointers in ContainerType

Public Functions

FieldContainer() = default

Default constructor.

inline FieldContainer(const size_t n, const IndexRangeType &r, const FieldStateType &fs = FieldStateType())

Standard constructor for field container.

Parameters

  • n: Number of components

  • r: Index range spanned by field data

  • fs: Field state initial value

inline FieldContainer(const std::vector<BaseType*> &vf)

Construct from a list of pointers.

Parameters

  • vf: Vector of pointers to underlying type (may be nullptr)

inline FieldContainer(const FieldContainer &c)

Standard copy constructor.

Parameters

  • c: Field container to copy from

inline FieldContainer(FieldContainer &&c) noexcept

Standard move constructor.

Parameters

  • c: Field container to move from

inline virtual ~FieldContainer()

Virtual destructor.

inline FieldContainer &operator=(const FieldContainer &rhs)

Standard copy assignment operator.

Return

This field container with copied contents from rhs

Parameters

  • rhs: Field container to assign from

inline FieldContainer &operator=(FieldContainer &&rhs)

Standard move assignment operator.

Return

This field container with moved contents from rhs

Parameters

  • rhs: Field container to assign from

inline iterator begin() noexcept

Begin of fields.

Return

Iterator

inline iterator end() noexcept

End of fields.

Return

Iterator

inline reverse_iterator rbegin() noexcept

Begin of reversed fields.

Return

Reverse iterator

inline reverse_iterator rend() noexcept

End of reversed fields.

Return

Reverse iterator

inline const_iterator cbegin() const noexcept

Begin of fields.

Return

const iterator

inline const_iterator cend() const noexcept

End of fields.

Return

const iterator

inline const_reverse_iterator crbegin() const noexcept

Begin of reversed fields.

Return

const reverse iterator

inline const_reverse_iterator crend() const noexcept

End of reversed fields.

Return

const reverse iterator

inline size_t size() const

Number of fields contained.

Return

Size of container

inline ContainerType &getContainer()

Get container of raw data.

Return

STL vector with BaseType pointers

inline const ContainerType &getContainer() const

Get container of raw data.

Return

const STL vector with BaseType pointers

inline bool contains(const BaseType &element) const

Check if element is contained.

Return

True if element is in this container

Parameters

  • element: Reference element

inline void copyData(const FieldContainer &rhs)

Forced deep copy of underlying fields.

This copies FieldType::BaseType data only.

Example: fv is a field view and f is another field (either view or memory owner)

fv = f; // shallow copy of f to fv [updates pointers in fv only]
fv.copyData(f); // deep copy of data in f to fv [expensive operation]

Parameters

  • rhs: Field container to copy from

inline void pushBack(BaseType *p)

Append new component at the end of container.

The destructor of FieldContainer calls the destructor of p when the object is destroyed.

Parameters

  • p: Pointer to new component

inline void clear()

Destroy container components.

Unlike to std::vector, this calls the destructor of each container component effectively destroying the object. The size of the container after this operation is zero.

inline BaseType &operator[](const size_t i)

Access to fields.

This method throws a std::runtime_error if the component is a nullptr.

Return

Reference to component i

Parameters

  • i: Component ID of field to be accessed

inline const BaseType &operator[](const size_t i) const

Access to fields.

This method throws a std::runtime_error if the component is a nullptr.

Return

const reference to component i

Parameters

  • i: Component ID of field to be accessed

template<typename T>
inline BaseType &operator[](const T &t)

Generic access to fields.

This method throws a std::runtime_error if the component is a nullptr.

Return

Reference to component t

Template Parameters

  • T: Generic index type that defines casting to size_t

Parameters

  • t: Component ID of field to be accessed

template<typename T>
inline const BaseType &operator[](const T &t) const

Generic access to fields.

This method throws a std::runtime_error if the component is a nullptr.

Return

const reference to component t

Template Parameters

  • T: Generic index type that defines casting to size_t

Parameters

  • t: Component ID of field to be accessed

template<typename TField>
class Cubism::Block::FieldView : public TField

Field view type.

Provides a view (shallow copy) for scalar fields, tensor fields or face field containers. The corresponding field interface is inherited.

Note

A view type never owns memory.

Template Parameters

  • TField: Field type

Public Functions

inline FieldView(const BaseType &f)

Main constructor to generate a field view.

Parameters

  • f: Field for which to generate the view

inline void setView(const BaseType &c)

Set new internal view.

Parameters

  • c: Base field be be viewed at

inline BaseType copy() const

Force a deep copy of the viewed field.

Return

Deep copy (new allocation) of field view

using Cubism::Block::CellField = Field<T, EntityType::Cell, DIM, State, Alloc>

Basic cell-centered data field.

Template Parameters

  • T: Data type (must be POD)

  • DIM: Field dimension

  • State: State type

  • Alloc: Allocator type

using Cubism::Block::NodeField = Field<T, EntityType::Node, DIM, State, Alloc>

Basic node-centered data field.

Template Parameters

  • T: Data type (must be POD)

  • DIM: Field dimension

  • State: State type

  • Alloc: Allocator type

using Cubism::Block::FaceField = Field<T, EntityType::Face, DIM, State, Alloc>

Basic face-centered data field.

Faces are stored individually for the dimensionality specified by CUBISM_DIMENSION at compile time. See the FaceContainer type for a container of size CUBISM_DIMENSION.

Template Parameters

  • T: Data type (must be POD)

  • DIM: Field dimension

  • State: State type

  • Alloc: Allocator type

using Cubism::Block::VectorField = TensorField<T, 1, Entity, DIM, State, Alloc>

Convenience type for vector fields.

Template Parameters

  • T: Field data type

  • Entity: Entity type

  • DIM: Field dimension

  • State: Field state type

  • Alloc: Memory allocator