PETSc linear algebra functions. More...

Classes
class	Vector
class	Matrix
class	KrylovSolver

Functions
std::vector< Vec >	create_vectors (MPI_Comm comm, const std::vector< std::span< const PetscScalar > > &x)
	Create PETSc vectors from the local data. The data is copied into the PETSc vectors and is not shared. Each vector's global size is determined by summing the corresponding local size across all ranks in comm.
Vec	create_vector (const common::IndexMap &map, int bs)
	Create a ghosted PETSc Vec.
Vec	create_vector (MPI_Comm comm, std::array< std::int64_t, 2 > range, std::span< const std::int64_t > ghosts, int bs)
	Create a ghosted PETSc Vec from a local range and ghost indices.
Vec	create_vector_wrap (const common::IndexMap &map, int bs, std::span< const PetscScalar > x)
	Create a PETSc Vec that wraps the data in an array.
template<class V>
Vec	create_vector_wrap (const la::Vector< V > &x)
	Create a PETSc Vec that wraps the data in an array.
std::vector< IS >	create_index_sets (const std::vector< std::pair< std::reference_wrapper< const common::IndexMap >, int > > &maps)
	Index sets addressing a stack of index maps in the calling rank's local numbering.
std::vector< IS >	create_global_index_sets (const std::vector< std::pair< std::reference_wrapper< const common::IndexMap >, int > > &maps)
	Index sets describing each field of a stack of index maps in the global numbering of the stacked problem.
std::vector< std::vector< PetscScalar > >	get_local_vectors (const Vec x, const std::vector< std::pair< std::reference_wrapper< const common::IndexMap >, int > > &maps)
	Copy blocks from Vec into local arrays.
void	scatter_local_vectors (Vec x, const std::vector< std::span< const PetscScalar > > &x_b, const std::vector< std::pair< std::reference_wrapper< const common::IndexMap >, int > > &maps)
	Scatter local vectors to Vec.
Mat	create_matrix (MPI_Comm comm, const SparsityPattern &sp, std::optional< std::string_view > type=std::nullopt, std::optional< ISLocalToGlobalMapping > rlgmap=std::nullopt, std::optional< ISLocalToGlobalMapping > clgmap=std::nullopt)
	Create a PETSc Mat. Caller is responsible for destroying the returned object.
MatNullSpace	create_nullspace (MPI_Comm comm, std::span< const Vec > basis)
	Create PETSc MatNullSpace. Caller is responsible for destruction returned object.

Detailed Description

PETSc linear algebra functions.

Function Documentation

◆ create_global_index_sets()

std::vector< IS > create_global_index_sets ( const std::vector< std::pair< std::reference_wrapper< const common::IndexMap >, int > > & maps )

Index sets describing each field of a stack of index maps in the global numbering of the stacked problem.

Each set covers one map's owned entries. Ghosts are excluded, as each is owned by exactly one rank, so the sets of all ranks partition the stacked problem. Preconditioners that split a problem into fields, such as PCBDDC and PCFIELDSPLIT, take sets of this form.

See also: create_index_sets for rank-local sets that include ghosts.

Note: The caller is responsible for destruction of each IS.

Parameters

[in] maps Index maps and corresponding block sizes. All maps must share a communicator.

Returns: One index set per map, created on the maps' communicator.

Exceptions

std::invalid_argument If the maps do not share a communicator.

◆ create_index_sets()

std::vector< IS > create_index_sets ( const std::vector< std::pair< std::reference_wrapper< const common::IndexMap >, int > > & maps )

Index sets addressing a stack of index maps in the calling rank's local numbering.

Each set covers one map's owned and ghost entries, at the offset that map occupies in the stack, so the sets address a rank's local block of a stacked problem, such as a sub-block of a blocked matrix.

If map[0] has 7 local entries (owned plus ghost) and map[1] has 4, then IS[0] = {0, 1, 2, 3, 4, 5, 6} and IS[1] = {7, 8, 9, 10}. The sets are rank-private: every rank numbers from zero.

See also: create_global_index_sets for sets that describe a field of the distributed problem in global numbering.

Todo: This function could take just the local sizes.

Note: The caller is responsible for destruction of each IS.

Parameters

[in] maps Index maps and corresponding block sizes.

Returns: One index set per map, created on PETSC_COMM_SELF.

◆ create_matrix()

Mat create_matrix	(	MPI_Comm	comm,
		const SparsityPattern &	sp,
		std::optional< std::string_view >	type = std::nullopt,
		std::optional< ISLocalToGlobalMapping >	rlgmap = std::nullopt,
		std::optional< ISLocalToGlobalMapping >	clgmap = std::nullopt )

Create a PETSc Mat. Caller is responsible for destroying the returned object.

Note: MAT_IGNORE_ZERO_ENTRIES skips exact-zero insertions. Enable it before assembly to reduce storage only if the matrix is assembled once. For re-assembly, enable it after the first full assembly so initially zero entries remain in the sparsity pattern. Otherwise, a later non-zero insertion can fail because MAT_NEW_NONZERO_ALLOCATION_ERR is set.

Parameters

[in]	comm	The MPI communicator
[in]	sp	The sparsity pattern that determines the layout and non-zero structure of the matrix
[in]	type	The PETSc Mat type to create. If std::nullopt or an empty string, the PETSc default is used.
[in]	rlgmap	Row local-to-global map to attach to the matrix. If std::nullopt, a map is built from the row input index map of sp.
[in]	clgmap	Column local-to-global map to attach to the matrix. If std::nullopt, a map is built from the column input index map of sp.

Note: A supplied map must be created on comm; MATIS requires the maps to share the matrix communicator.

◆ create_nullspace()

MatNullSpace create_nullspace	(	MPI_Comm	comm,
		std::span< const Vec >	basis )

Create PETSc MatNullSpace. Caller is responsible for destruction returned object.

Parameters

[in]	comm	The MPI communicator
[in]	basis	The nullspace basis vectors

Returns: A PETSc nullspace object

◆ create_vector() [1/2]

Vec create_vector	(	const common::IndexMap &	map,
		int	bs )

Create a ghosted PETSc Vec.

Note: Caller is responsible for destroying the returned object

Parameters

[in]	map	The index map describing the parallel layout (by block)
[in]	bs	The block size

Returns: A PETSc Vec

◆ create_vector() [2/2]

Vec create_vector	(	MPI_Comm	comm,
		std::array< std::int64_t, 2 >	range,
		std::span< const std::int64_t >	ghosts,
		int	bs )

Create a ghosted PETSc Vec from a local range and ghost indices.

Note: Caller is responsible for freeing the returned object

Parameters

[in]	comm	The MPI communicator
[in]	range	The local ownership range (by blocks)
[in]	ghosts	Ghost blocks
[in]	bs	The block size. The total number of local entries is bs * (range[1] - range[0]).

Returns: A PETSc Vec

◆ create_vector_wrap() [1/2]

Vec create_vector_wrap	(	const common::IndexMap &	map,
		int	bs,
		std::span< const PetscScalar >	x )

Create a PETSc Vec that wraps the data in an array.

Parameters

[in]	map	The index map that describes the parallel layout of the distributed vector (by block)
[in]	bs	Block size
[in]	x	The local part of the vector, including ghost entries. Must have size at least bs * (map.size_local() + map.num_ghosts()).

Returns: A PETSc Vec object that shares the data in x

Note: The array x must be kept alive to use the PETSc Vec object; The caller should call VecDestroy to free the return PETSc vector

◆ create_vector_wrap() [2/2]

template<class V>

Vec create_vector_wrap ( const la::Vector< V > & x )

Create a PETSc Vec that wraps the data in an array.

Parameters

[in] x The vector to be wrapped

Returns: A PETSc Vec object that shares the data in x

◆ create_vectors()

std::vector< Vec > create_vectors	(	MPI_Comm	comm,
		const std::vector< std::span< const PetscScalar > > &	x )

Create PETSc vectors from the local data. The data is copied into the PETSc vectors and is not shared. Each vector's global size is determined by summing the corresponding local size across all ranks in comm.

Note: Caller is responsible for destroying the returned object

Parameters

[in]	comm	The MPI communicator
[in]	x	The vector data owned by the calling rank

Returns: Array of PETSc vectors

Classes

Functions

Detailed Description

Function Documentation

◆ create_global_index_sets()

◆ create_index_sets()

◆ create_matrix()

◆ create_nullspace()

◆ create_vector() [1/2]

◆ create_vector() [2/2]

◆ create_vector_wrap() [1/2]

◆ create_vector_wrap() [2/2]

◆ create_vectors()