terra::linalg Namespace Reference

Contains linear algebra utilities and functions for the Terra project. More...

Namespaces
namespace	detail
namespace	solvers
namespace	trafo
namespace	util

Classes
class	DiagonallyScaledOperator
	Given some operator \(K\) and a vector \(v\), this operator is equivalent to an operator \(A\) defined as. More...
class	VectorQ1IsoQ2Q1
	Block vector consisting of a Q1 vector and a Q1 scalar vector on distributed shell grids. More...
class	VectorQ1Scalar
	Q1 scalar finite element vector on a distributed shell grid. More...
class	VectorQ1Vec
	Static assertion: VectorQ1Scalar satisfies VectorLike concept. More...

Concepts
concept	LinearFormLike
	Concept for types that behave like linear forms.
concept	OperatorLike
	Concept for types that behave like linear operators.
concept	GCACapable
	Concept for types that can be used as Galerkin coarse-grid operators in a multigrid hierarchy. See galerkin_coarsening_linear.hpp for more information on GCA.
concept	Block2x2OperatorLike
	Concept for types that behave like block 2x2 operators. Extends OperatorLike and requires block types and accessors.
concept	VectorLike
	Concept for types that behave like vectors. Requires exposing ScalarType and implementations for linear algebra operations.
concept	Block2VectorLike
	Concept for types that behave like block 2-vectors. Extends VectorLike and requires block types and accessors.

Typedefs
template<OperatorLike Operator>
using	SrcOf = Operator::SrcVectorType
	Alias for the source vector type of an operator.
template<OperatorLike Operator>
using	DstOf = Operator::DstVectorType
	Alias for the destination vector type of an operator.
template<VectorLike Vector>
using	ScalarOf = typename Vector::ScalarType
	Alias for the scalar type of a vector.

Enumerations
enum class	OperatorApplyMode { Replace , Add }
	Modes for applying an operator to a vector. More...
enum class	OperatorCommunicationMode { SkipCommunication , CommunicateAdditively }
	Modes for communication during operator application. More...
enum class	OperatorStoredMatrixMode { Off , Full , Selective }
	Modes for applying stored matrices. More...

Functions
template<LinearFormLike LinearForm>
void	apply (LinearForm &L, typename LinearForm::DstVectorType &dst)
	Apply a linear form and write to a destination vector.
template<OperatorLike Operator>
void	apply (Operator &A, const SrcOf< Operator > &src, DstOf< Operator > &dst)
	Apply an operator to a source vector and write to a destination vector.
template<VectorLike Vector>
void	lincomb (Vector &y, const std::vector< ScalarOf< Vector > > &c, const std::vector< Vector > &x, const ScalarOf< Vector > &c0)
	Compute a linear combination of vectors. Implements: \( y = \sum_{i} c_i x_i + c_0 \).
template<VectorLike Vector>
void	lincomb (Vector &y, const std::vector< ScalarOf< Vector > > &c, const std::vector< Vector > &x)
	Compute a linear combination of vectors with zero scalar. Implements: \( y = \sum_{i} c_i x_i \).
template<VectorLike Vector>
void	assign (Vector &y, const ScalarOf< Vector > &c0)
	Assign a scalar value to a vector. Implements: \( y \gets c_0 \).
template<VectorLike Vector>
void	assign (Vector &y, const Vector &x)
	Assign one vector to another. Implements: \( y \gets x \).
template<VectorLike Vector>
ScalarOf< Vector >	dot (const Vector &y, const Vector &x)
	Compute the dot product of two vectors. Implements: \( y \cdot x = \sum_{i} y_i x_i \).
template<VectorLike Vector>
void	invert_entries (Vector &y)
	Invert the entries of a vector. For each entry \( y_i \), computes \( y_i = 1 / y_i \).
template<VectorLike Vector>
void	scale_in_place (Vector &y, const Vector &x)
	Scale a vector in place with another vector. For each entry \( y_i \), computes \( y_i = y_i \cdot x_i \).
template<VectorLike Vector>
void	randomize (Vector &y)
	Randomize the entries of a vector. Sets each entry of \( y \) to a random value.
template<VectorLike Vector>
ScalarOf< Vector >	norm_inf (const Vector &y)
	Compute the infinity norm (max absolute entry) of a vector. Implements: \( \|y\|_\infty = \max_i |y_i| \).
template<VectorLike Vector>
ScalarOf< Vector >	norm_2 (const Vector &y)
	Compute the 2-norm (Euclidean norm) of a vector. Implements: \( \|y\|_2 = \sqrt{ \sum_i y_i^2 } \).
template<VectorLike Vector>
ScalarOf< Vector >	norm_2_scaled (const Vector &y, const ScalarOf< Vector > &scaling_factor_under_the_root)
	Compute the scaled 2-norm of a vector. Implements: \( \|y\|_2^{\text{scaled}} = \sqrt{ (\sum_i y_i^2) \cdot s } \).
template<VectorLike Vector>
bool	has_nan_or_inf (const Vector &y)
	Check if a vector contains NaN or inf entries. Returns true if any entry of \( y \) is NaN or inf.
template<VectorLike Vector>
void	swap (Vector &x, Vector &y)
	Swap the contents of two vectors. Exchanges the entries of \( x \) and \( y \).
template<typename ValueType , int VecDim = 3>
VectorQ1IsoQ2Q1< ValueType, VecDim >	allocate_vector_q1isoq2_q1 (const std::string label, const grid::shell::DistributedDomain &distributed_domain_fine, const grid::shell::DistributedDomain &distributed_domain_coarse, const int level)
	Static assertion: VectorQ1IsoQ2Q1 satisfies Block2VectorLike concept.

Detailed Description

Contains linear algebra utilities and functions for the Terra project.

This namespace provides vector and matrix operations, including linear combinations, dot products, and vector manipulations. It defines concepts for vector-like types and block 2-vectors, ensuring that types conform to expected interfaces for linear algebra operations. The utilities are designed to work with various vector implementations, allowing for flexibility and extensibility in numerical computations.

Note

For both, vector-vector and operator-vector operations, users should use the free functions provided in vector.hpp and operator.hpp.

Typedef Documentation

DstOf

template<OperatorLike Operator>

using terra::linalg::DstOf = typedef Operator::DstVectorType

Alias for the destination vector type of an operator.

ScalarOf

template<VectorLike Vector>

using terra::linalg::ScalarOf = typedef typename Vector::ScalarType

Alias for the scalar type of a vector.

SrcOf

template<OperatorLike Operator>

using terra::linalg::SrcOf = typedef Operator::SrcVectorType

Alias for the source vector type of an operator.

Enumeration Type Documentation

OperatorApplyMode

enum class terra::linalg::OperatorApplyMode

strong

Modes for applying an operator to a vector.

Note

It is important to pair the modes correctly. If unsure, use temporary vectors, apply each operator individually (typically defaulting to modes 'Replace' and 'CommunicateAdditively'), and add the results in the end.

Elementwise operators have to communicate after all local values have been updated. The general approach is to communicate and sum up values of overlapping nodes. If the 'ApplyMode' is set to 'Add' and additive communication follows that, then also previous values will be included in the sum.

The modes are, for instance, useful for block matrices like the Stokes operator. If you want to execute, e.g., \( y \gets Au + B^T p \) then you could execute this as follows:

\[ \begin{aligned} y &\gets Au && \qquad \text{replace and skip communication} \\ y &\gets y + B^Tp && \qquad \text{add and communicate additively} \\ \end{aligned} \]

Note that if communication is not skipped in the first step in this example, the subdomain boundary data will be wrong.

Enumerator
Replace	Overwrite the destination vector.
Add	Add to the destination vector.

OperatorCommunicationMode

enum class terra::linalg::OperatorCommunicationMode

strong

Modes for communication during operator application.

Note

See OperatorApplyMode for more details.

Enumerator
SkipCommunication	Do not communicate.
CommunicateAdditively	Communicate and add results.

OperatorStoredMatrixMode

enum class terra::linalg::OperatorStoredMatrixMode

strong

Modes for applying stored matrices.

Enumerator
Off	Do not use stored matrices.
Full	Use stored matrices on all elements.
Selective	Use stored matrices on selected, marked elements only, assemble on all others.

Function Documentation

allocate_vector_q1isoq2_q1()

template<typename ValueType , int VecDim = 3>

VectorQ1IsoQ2Q1< ValueType, VecDim > terra::linalg::allocate_vector_q1isoq2_q1	(	const std::string	label,
		const grid::shell::DistributedDomain &	distributed_domain_fine,
		const grid::shell::DistributedDomain &	distributed_domain_coarse,
		const int	level
	)

Static assertion: VectorQ1IsoQ2Q1 satisfies Block2VectorLike concept.

Allocate a VectorQ1IsoQ2Q1 block vector with grid data for both blocks.

Parameters

label	Name for the vector.
distributed_domain_fine	Distributed shell domain for the vector block.
distributed_domain_coarse	Distributed shell domain for the scalar block.
level	Multigrid level.

Returns

Allocated VectorQ1IsoQ2Q1 block vector.

apply() [1/2]

template<LinearFormLike LinearForm>

void terra::linalg::apply	(	LinearForm &	L,
		typename LinearForm::DstVectorType &	dst
	)

Apply a linear form and write to a destination vector.

Parameters

L	Linear form to apply.
dst	Destination vector.

apply() [2/2]

template<OperatorLike Operator>

void terra::linalg::apply	(	Operator &	A,
		const SrcOf< Operator > &	src,
		DstOf< Operator > &	dst
	)

Apply an operator to a source vector and write to a destination vector.

Parameters

A	Operator to apply.
src	Source vector.
dst	Destination vector.

assign() [1/2]

template<VectorLike Vector>

void terra::linalg::assign	(	Vector &	y,
		const ScalarOf< Vector > &	c0
	)

Assign a scalar value to a vector. Implements: \( y \gets c_0 \).

Parameters

y	Output vector.
c0	Scalar value \( c_0 \).

assign() [2/2]

template<VectorLike Vector>

void terra::linalg::assign	(	Vector &	y,
		const Vector &	x
	)

Assign one vector to another. Implements: \( y \gets x \).

Parameters

y	Output vector.
x	Input vector.

dot()

template<VectorLike Vector>

ScalarOf< Vector > terra::linalg::dot	(	const Vector &	y,
		const Vector &	x
	)

Compute the dot product of two vectors. Implements: \( y \cdot x = \sum_{i} y_i x_i \).

Parameters

y	First vector.
x	Second vector.

Returns

Dot product value.

has_nan_or_inf()

template<VectorLike Vector>

bool terra::linalg::has_nan_or_inf

(

const Vector &

y

)

Check if a vector contains NaN or inf entries. Returns true if any entry of \( y \) is NaN or inf.

Parameters

y	Input vector.

Returns

True if NaN or inf is present, false otherwise.

invert_entries()

template<VectorLike Vector>

void terra::linalg::invert_entries

(

Vector &

y

)

Invert the entries of a vector. For each entry \( y_i \), computes \( y_i = 1 / y_i \).

Parameters

y	Vector to invert.

lincomb() [1/2]

template<VectorLike Vector>

void terra::linalg::lincomb	(	Vector &	y,
		const std::vector< ScalarOf< Vector > > &	c,
		const std::vector< Vector > &	x
	)

Compute a linear combination of vectors with zero scalar. Implements: \( y = \sum_{i} c_i x_i \).

Parameters

y	Output vector.
c	Coefficients \( c_i \).
x	Input vectors \( x_i \).

lincomb() [2/2]

template<VectorLike Vector>

void terra::linalg::lincomb	(	Vector &	y,
		const std::vector< ScalarOf< Vector > > &	c,
		const std::vector< Vector > &	x,
		const ScalarOf< Vector > &	c0
	)

Compute a linear combination of vectors. Implements: \( y = \sum_{i} c_i x_i + c_0 \).

Parameters

y	Output vector.
c	Coefficients \( c_i \).
x	Input vectors \( x_i \).
c0	Scalar to add \( c_0 \).

norm_2()

template<VectorLike Vector>

ScalarOf< Vector > terra::linalg::norm_2

(

const Vector &

y

)

Compute the 2-norm (Euclidean norm) of a vector. Implements: \( \|y\|_2 = \sqrt{ \sum_i y_i^2 } \).

Parameters

y	Input vector.

Returns

2-norm value.

norm_2_scaled()

template<VectorLike Vector>

ScalarOf< Vector > terra::linalg::norm_2_scaled	(	const Vector &	y,
		const ScalarOf< Vector > &	scaling_factor_under_the_root
	)

Compute the scaled 2-norm of a vector. Implements: \( \|y\|_2^{\text{scaled}} = \sqrt{ (\sum_i y_i^2) \cdot s } \).

Parameters

y	Input vector.
scaling_factor_under_the_root	Scaling factor \( s \) under the square root.

Returns

Scaled 2-norm value.

norm_inf()

template<VectorLike Vector>

ScalarOf< Vector > terra::linalg::norm_inf

(

const Vector &

y

)

Compute the infinity norm (max absolute entry) of a vector. Implements: \( \|y\|_\infty = \max_i |y_i| \).

Parameters

y	Input vector.

Returns

Infinity norm value.

randomize()

template<VectorLike Vector>

void terra::linalg::randomize

(

Vector &

y

)

Randomize the entries of a vector. Sets each entry of \( y \) to a random value.

Parameters

y	Vector to randomize.

scale_in_place()

template<VectorLike Vector>

void terra::linalg::scale_in_place	(	Vector &	y,
		const Vector &	x
	)

Scale a vector in place with another vector. For each entry \( y_i \), computes \( y_i = y_i \cdot x_i \).

Parameters

y	Vector to scale.
x	Scaling vector.

swap()

template<VectorLike Vector>

void terra::linalg::swap	(	Vector &	x,
		Vector &	y
	)

Swap the contents of two vectors. Exchanges the entries of \( x \) and \( y \).

Parameters

x	First vector.
y	Second vector.