A vector that can be distributed across processes. More...

#include <Vector.h>

Public Types
using	container_type = Container
	Container type.
using	value_type = container_type::value_type
	Scalar type.

Public Member Functions
	Vector (std::shared_ptr< const common::IndexMap > map, int bs)
	Create a distributed vector.
	Vector (std::shared_ptr< const common::IndexMap > map, int bs, std::shared_ptr< const common::Scatterer< ScatterContainer > > scatterer)
	Create a distributed vector using an existing scatterer.
	Vector (const Vector &x)=default
	Copy constructor.
	Vector (Vector &&x)=default
	Move constructor.
template<typename T0, typename Container0, typename ScatterContainer0>
	Vector (const Vector< T0, Container0, ScatterContainer0 > &x)
	Create a vector by copying and converting another vector.
Vector &	operator= (const Vector &x)=delete
Vector &	operator= (Vector &&x)=default
	Move assignment operator.
void	set (value_type v)
	Set all entries (including ghosts).
template<typename U, typename GetPtr> requires VectorPackKernel<U, container_type, ScatterContainer> and GetPtrConcept<GetPtr, Container, T>
void	scatter_fwd_begin (U pack, GetPtr get_ptr)
	Begin scatter (send) of local data that is ghosted on other processes.
void	scatter_fwd_begin ()
	Begin scatter (send) of local data that is ghosted on other processes (simplified CPU version).
template<typename U> requires VectorPackKernel<U, container_type, ScatterContainer>
void	scatter_fwd_end (U unpack)
	End scatter (send) of local data values that are ghosted on other processes.
void	scatter_fwd_end ()
	End scatter (send) of local data values that are ghosted on other processes (simplified CPU version).
void	scatter_fwd ()
	Scatter (send) of local data values that are ghosted on other processes and update ghost entry values (simplified CPU version).
template<typename U, typename GetPtr> requires VectorPackKernel<U, container_type, ScatterContainer> and GetPtrConcept<GetPtr, Container, T>
void	scatter_rev_begin (U pack, GetPtr get_ptr)
	Start scatter (send) of ghost entry data to the owning process of an index.
void	scatter_rev_begin ()
	Start scatter (send) of ghost entry data to the owning process of an index (simplified CPU version).
template<typename U> requires VectorPackKernel<U, container_type, ScatterContainer>
void	scatter_rev_end (U unpack)
	End scatter of ghost data to owner and update owned entries.
template<class BinaryOperation> requires requires(Container c) { { c.data() } -> std::same_as<T*>; }
void	scatter_rev (BinaryOperation op)
	Scatter (send) of ghost data values to the owning process and assign/accumulate into the owned data entries (simplified CPU version).
std::shared_ptr< const common::IndexMap >	index_map () const noexcept
	Get IndexMap.
std::shared_ptr< const common::Scatterer< ScatterContainer > >	scatterer () const noexcept
	Get the scatterer used for halo communication.
constexpr int	bs () const noexcept
	Get block size.
container_type &	array () noexcept
	Get the process-local part of the vector.
const container_type &	array () const noexcept
	Get the process-local part of the vector (const version).
container_type &	mutable_array () noexcept
	Get local part of the vector.

Detailed Description

template<typename T, typename Container = std::vector<T>, typename ScatterContainer = std::vector<std::int32_t>>
class dolfinx::la::Vector< T, Container, ScatterContainer >

A vector that can be distributed across processes.

Template Parameters

T	Scalar type of the vector.
Container	Data container type. This is typically std::vector<T> on CPUs, and thrust::device_vector<T> on GPUs.
ScatterContainer	Storage container type for the scatterer indices. This is typically std::vector<std::int32_t> on CPUs, and thrust::device_vector<std::int32_t> on GPUs.

Constructor & Destructor Documentation

◆ Vector() [1/3]

template<typename T, typename Container = std::vector<T>, typename ScatterContainer = std::vector<std::int32_t>>

Vector	(	std::shared_ptr< const common::IndexMap >	map,
		int	bs )

inline

Create a distributed vector.

This constructor creates a new Scatterer for the Vector. For applications that create many Vectors with the same parallel layout, constructing a distinct Scatterer for each Vector can exhaust the available MPI communicators. This can be avoided by creating one Scatterer and sharing it among those Vectors using the constructor that takes a shared pointer to an existing Scatterer.

Parameters

map	Index map that describes the parallel layout of the data.
bs	Number of entries per index map 'index' (block size).

◆ Vector() [2/3]

template<typename T, typename Container = std::vector<T>, typename ScatterContainer = std::vector<std::int32_t>>

Vector	(	std::shared_ptr< const common::IndexMap >	map,
		int	bs,
		std::shared_ptr< const common::Scatterer< ScatterContainer > >	scatterer )

inline

Create a distributed vector using an existing scatterer.

Parameters

[in]	map	Index map that describes the parallel layout of the data.
[in]	bs	Number of entries per index map 'index' (block size).
[in]	scatterer	Scatterer compatible with map.

◆ Vector() [3/3]

template<typename T, typename Container = std::vector<T>, typename ScatterContainer = std::vector<std::int32_t>>

template<typename T0, typename Container0, typename ScatterContainer0>

Vector ( const Vector< T0, Container0, ScatterContainer0 > & x )

inlineexplicit

Create a vector by copying and converting another vector.

The local vector data, including ghost values, is copied and converted to T and Container. The index map is shared with x. If the scatter container types are the same, the scatterer is also shared; otherwise, a converted copy of the scatterer is created.

This constructor can be used to convert the scalar type, e.g. from double to float, or to transfer a vector between CPU and GPU storage.

Note: Construction is collective when ScatterContainer and ScatterContainer0 differ because copying the scatterer duplicates its MPI neighbourhood communicators.

Template Parameters

T0	Scalar type of the Vector being copied.
Container0	Data container type of the Vector being copied.
ScatterContainer0	Scatterer container type of the Vector being copied.

Parameters

[in] x Vector to copy and convert.

Member Function Documentation

◆ array() [1/2]

template<typename T, typename Container = std::vector<T>, typename ScatterContainer = std::vector<std::int32_t>>

const container_type & array ( ) const

inlinenoexcept

Get the process-local part of the vector (const version).

Owned entries appear first, followed by ghosted entries.

◆ array() [2/2]

template<typename T, typename Container = std::vector<T>, typename ScatterContainer = std::vector<std::int32_t>>

container_type & array ( )

inlinenoexcept

Get the process-local part of the vector.

Owned entries appear first, followed by ghosted entries.

◆ mutable_array()

template<typename T, typename Container = std::vector<T>, typename ScatterContainer = std::vector<std::int32_t>>

container_type & mutable_array ( )

inlinenoexcept

Get local part of the vector.

Deprecated: Use ::array instead.

◆ scatter_fwd()

template<typename T, typename Container = std::vector<T>, typename ScatterContainer = std::vector<std::int32_t>>

void scatter_fwd ( )

inline

Scatter (send) of local data values that are ghosted on other processes and update ghost entry values (simplified CPU version).

Suitable for scatter operations on a CPU with std::vector storage. The send buffer is packed and the receive buffer unpacked by a function that is suitable for use on a CPU.

Note: Collective MPI operation. Every rank in the communicator must call this function, including ranks without neighbours.

◆ scatter_fwd_begin() [1/2]

template<typename T, typename Container = std::vector<T>, typename ScatterContainer = std::vector<std::int32_t>>

void scatter_fwd_begin ( )

inline

Begin scatter (send) of local data that is ghosted on other processes (simplified CPU version).

Suitable for scatter operations on a CPU with std::vector storage. The send buffer is packed internally by a function that is suitable for use on a CPU.

Note: Collective MPI operation. Every rank in the communicator must call this function, including ranks without neighbours.

◆ scatter_fwd_begin() [2/2]

template<typename T, typename Container = std::vector<T>, typename ScatterContainer = std::vector<std::int32_t>>

template<typename U, typename GetPtr>
requires VectorPackKernel<U, container_type, ScatterContainer> and GetPtrConcept<GetPtr, Container, T>

void scatter_fwd_begin	(	U	pack,
		GetPtr	get_ptr )

inline

Begin scatter (send) of local data that is ghosted on other processes.

The user provides the function to pack to the send buffer. Typical use is a specialised function to pack data that resides on a GPU.

Note: Collective MPI operation. Every rank in the communicator must call this function, including ranks without neighbours.

Template Parameters

U	Pack function type.
GetPtr	Function type that accesses a container's data pointer.

Parameters

pack	Function that packs owned data into a send buffer.
get_ptr	Function that for a Container type returns the pointer to the underlying data.

◆ scatter_fwd_end() [1/2]

template<typename T, typename Container = std::vector<T>, typename ScatterContainer = std::vector<std::int32_t>>

void scatter_fwd_end ( )

inline

End scatter (send) of local data values that are ghosted on other processes (simplified CPU version).

Suitable for scatter operations on a CPU with std::vector storage. The receive buffer is unpacked internally by a function that is suitable for use on a CPU.

Note: Local completion of the caller's own request, not itself collective. Every rank that called ::scatter_fwd_begin must still call this before reusing the buffers.

◆ scatter_fwd_end() [2/2]

template<typename T, typename Container = std::vector<T>, typename ScatterContainer = std::vector<std::int32_t>>

template<typename U>
requires VectorPackKernel<U, container_type, ScatterContainer>

void scatter_fwd_end ( U unpack )

inline

End scatter (send) of local data values that are ghosted on other processes.

The user provides the function to unpack the receive buffer. Typical use is a specialised function to unpack data that resides on a GPU.

Note: Local completion of the caller's own request, not itself collective. Every rank that called ::scatter_fwd_begin must still call this before reusing the buffers.

Template Parameters

U	Unpack function type.

Parameters

unpack Function to unpack the receive buffer into the ghost entries.

◆ scatter_rev()

template<typename T, typename Container = std::vector<T>, typename ScatterContainer = std::vector<std::int32_t>>

template<class BinaryOperation>
requires requires(Container c) { { c.data() } -> std::same_as<T*>; }

void scatter_rev ( BinaryOperation op )

inline

Scatter (send) of ghost data values to the owning process and assign/accumulate into the owned data entries (simplified CPU version).

For an owned entry, data from more than one process may be received. The received data can be summed or inserted into the owning entry. This is controlled by the op function.

Note: Collective MPI operation. Every rank in the communicator must call this function, including ranks without neighbours.

Parameters

op	IndexMap operation (add or insert).

◆ scatter_rev_begin() [1/2]

template<typename T, typename Container = std::vector<T>, typename ScatterContainer = std::vector<std::int32_t>>

void scatter_rev_begin ( )

inline

Start scatter (send) of ghost entry data to the owning process of an index (simplified CPU version).

Suitable for scatter operations on a CPU with std::vector storage. The send buffer is packed internally by a function that is suitable for use on a CPU.

Note: Collective MPI operation. Every rank in the communicator must call this function, including ranks without neighbours.

◆ scatter_rev_begin() [2/2]

template<typename T, typename Container = std::vector<T>, typename ScatterContainer = std::vector<std::int32_t>>

template<typename U, typename GetPtr>
requires VectorPackKernel<U, container_type, ScatterContainer> and GetPtrConcept<GetPtr, Container, T>

void scatter_rev_begin	(	U	pack,
		GetPtr	get_ptr )

inline

Start scatter (send) of ghost entry data to the owning process of an index.

The user provides the function to pack to the send buffer. Typical use is a specialised function to pack data that resides on a GPU.

Note: Collective MPI operation. Every rank in the communicator must call this function, including ranks without neighbours.

Template Parameters

U	Pack function type.
GetPtr	Function type that accesses a container's data pointer.

Parameters

pack	Function that packs ghost data into a send buffer.
get_ptr	Function that for a Container type returns the pointer to the underlying data.

◆ scatter_rev_end()

template<typename T, typename Container = std::vector<T>, typename ScatterContainer = std::vector<std::int32_t>>

template<typename U>
requires VectorPackKernel<U, container_type, ScatterContainer>

void scatter_rev_end ( U unpack )

inline

End scatter of ghost data to owner and update owned entries.

For an owned entry, data from more than one process may be received. The received data can be summed or inserted into the owning entry by the unpack function.

Note: Local completion of the caller's own request, not itself collective. Every rank that called ::scatter_rev_begin must still call this before reusing the buffers.

Template Parameters

U	Unpack function type.

◆ scatterer()

template<typename T, typename Container = std::vector<T>, typename ScatterContainer = std::vector<std::int32_t>>

std::shared_ptr< const common::Scatterer< ScatterContainer > > scatterer ( ) const

inlinenoexcept

Get the scatterer used for halo communication.

Returns: The scatterer.

◆ set()

template<typename T, typename Container = std::vector<T>, typename ScatterContainer = std::vector<std::int32_t>>

void set ( value_type v )

inline

Set all entries (including ghosts).

Deprecated: Use std::ranges::fill(u.array(), v) instead.

Parameters

[in] v Value to set all entries to (on calling rank).

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

/__w/dolfinx/dolfinx/cpp/dolfinx/la/Vector.h

Public Types

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Vector() [1/3]

◆ Vector() [2/3]

◆ Vector() [3/3]

Member Function Documentation

◆ array() [1/2]

◆ array() [2/2]

◆ mutable_array()

◆ scatter_fwd()

◆ scatter_fwd_begin() [1/2]

◆ scatter_fwd_begin() [2/2]

◆ scatter_fwd_end() [1/2]

◆ scatter_fwd_end() [2/2]

◆ scatter_rev()

◆ scatter_rev_begin() [1/2]

◆ scatter_rev_begin() [2/2]

◆ scatter_rev_end()

◆ scatterer()

◆ set()