Nullspace represents the (right or left) nullspace of an operator and is the orthogonal projector \( P = I - V V^H \) onto its complement, where \( V \) is an orthonormal basis of the nullspace. More...

#include <ginkgo/core/solver/nullspace.hpp>

Inheritance diagram for gko::solver::Nullspace< ValueType >:

[legend]

Collaboration diagram for gko::solver::Nullspace< ValueType >:

[legend]

Public Types
using	value_type = ValueType

using	absolute_type = remove_complex< ValueType >

Public Types inherited from gko::EnableCloneable< Nullspace< ValueType > >
using	result_type = Nullspace< ValueType >

Public Types inherited from gko::ConvertibleTo< ResultType >
using	result_type = ResultType

Public Member Functions
bool	contains_constant () const noexcept

size_type	get_dimension () const noexcept

std::shared_ptr< const LinOp >	get_basis () const noexcept

void	project (ptr_param< LinOp > v) const
	Applies the projector in place: \( v \leftarrow (I - V V^H) v \), for each column of `v` independently. More...

Nullspace &	operator= (const Nullspace &other)

Nullspace &	operator= (Nullspace &&other)

	Nullspace (const Nullspace &other)

	Nullspace (Nullspace &&other)

Public Member Functions inherited from gko::LinOp
void	apply (ptr_param< const LinOp > b, ptr_param< LinOp > x) const
	Applies a linear operator to a vector (or a sequence of vectors). More...

void	apply (ptr_param< const LinOp > alpha, ptr_param< const LinOp > b, ptr_param< const LinOp > beta, ptr_param< LinOp > x) const
	Performs the operation x = alpha * op(b) + beta * x. More...

const dim< 2 > &	get_size () const noexcept
	Returns the size of the operator. More...

virtual bool	apply_uses_initial_guess () const
	Returns true if the linear operator uses the data given in x as an initial guess. More...

LinOp &	operator= (const LinOp &)=default
	Copy-assigns a LinOp. More...

LinOp &	operator= (LinOp &&other)
	Move-assigns a LinOp. More...

	LinOp (const LinOp &)=default
	Copy-constructs a LinOp. More...

	LinOp (LinOp &&other)
	Move-constructs a LinOp. More...

Public Member Functions inherited from gko::PolymorphicObject
virtual void	validate_data () const
	Throws gko::InvalidData exception if we found the data inside the object does not fulfill certain property up to our knowledge.

PolymorphicObject &	operator= (const PolymorphicObject &)

std::shared_ptr< const Executor >	get_executor () const noexcept
	Returns the Executor of the object. More...

Public Member Functions inherited from gko::log::EnableLogging< PolymorphicObject >
void	add_logger (std::shared_ptr< const Logger > logger) override

void	remove_logger (const Logger *logger) override

void	remove_logger (ptr_param< const Logger > logger)

const std::vector< std::shared_ptr< const Logger > > &	get_loggers () const override

void	clear_loggers () override

Public Member Functions inherited from gko::log::Loggable
void	remove_logger (ptr_param< const Logger > logger)

Public Member Functions inherited from gko::EnableCloneable< Nullspace< ValueType > >
std::unique_ptr< Nullspace< ValueType > >	clone (std::shared_ptr< const Executor > exec) const
	Creates a clone of the object. More...

std::unique_ptr< Nullspace< ValueType > >	clone () const
	Creates a clone of the object. More...

void	convert_to (result_type *result) const override
	Converts the implementer to an object of type result_type. More...

void	move_to (result_type *result) override
	Converts the implementer to an object of type result_type by moving data from this object. More...

std::unique_ptr< Nullspace< ValueType > >	create_default () const

std::unique_ptr< Nullspace< ValueType > >	create_default (std::shared_ptr< const Executor > exec) const

Public Member Functions inherited from gko::ConvertibleTo< ResultType >
void	convert_to (ptr_param< result_type > result) const

void	move_to (ptr_param< result_type > result)

Public Member Functions inherited from gko::Cloneable
std::unique_ptr< Cloneable >	clone (std::shared_ptr< const Executor > exec) const

std::unique_ptr< Cloneable >	clone () const

Cloneable *	copy_from (ptr_param< const Cloneable > other)

Cloneable *	move_from (ptr_param< Cloneable > other)

std::unique_ptr< Cloneable >	create_default (std::shared_ptr< const Executor > exec) const

std::unique_ptr< Cloneable >	create_default () const

Static Public Member Functions
static std::unique_ptr< Nullspace >	create (std::shared_ptr< const Executor > exec, std::vector< std::shared_ptr< const LinOp >> basis, bool contains_constant=false)
	Creates a Nullspace from an explicit basis. More...

static std::unique_ptr< Nullspace >	create_from_constant (std::shared_ptr< const Executor > exec, dim< 2 > size={})
	Creates a Nullspace consisting only of the constant vector (e.g. More...

Friends
class	EnableCloneable< Nullspace >

Detailed Description

template<typename ValueType = default_precision>
class gko::solver::Nullspace< ValueType >

Nullspace represents the (right or left) nullspace of an operator and is the orthogonal projector \( P = I - V V^H \) onto its complement, where \( V \) is an orthonormal basis of the nullspace.

The constant vector is handled implicitly by subtracting the mean, so a constant-only nullspace works with any vector layout (matrix::Dense or experimental::distributed::Vector with any partition).
An explicit basis is copied and orthonormalized once at creation time (twice-iterated Gram-Schmidt, also against the constant if it is part of the nullspace). Columns that are numerically linearly dependent (relative norm below \( \sqrt{\epsilon} \) after orthogonalization) are dropped; get_dimension() reports the remaining dimension.
project() removes the nullspace components of all columns of its input \( X \) at once: the coefficients \( C = V^H X \) and the column means are computed in a single pass (and, for distributed vectors, a single all-reduce), followed by \( X \leftarrow X - V C \).

The typical use is as the nullspace / left_nullspace parameter of an iterative solver, see enable_preconditioned_iterative_solver_factory_parameters.

The object is immutable after creation apart from internal scratch buffers. Solvers and preconditioner::NullspaceProjection work on their own copy, which shares the basis, so the same object can be passed to any number of factories. Like other Ginkgo LinOps with internal caches, a single instance must not be applied concurrently from multiple threads.

Template Parameters

ValueType the value type of the vectors it projects.

Member Function Documentation

◆ contains_constant()

template<typename ValueType = default_precision>

bool gko::solver::Nullspace< ValueType >::contains_constant ( ) const

noexcept

Returns: whether the constant vector is part of the nullspace.

◆ create()

template<typename ValueType = default_precision>

static std::unique_ptr<Nullspace> gko::solver::Nullspace< ValueType >::create	(	std::shared_ptr< const Executor >	exec,
		std::vector< std::shared_ptr< const LinOp >>	basis,
		bool	contains_constant = `false`
	)

static

Creates a Nullspace from an explicit basis.

Parameters

exec	the executor the projector (and its basis) lives on
basis	the nullspace basis vectors. Each entry is an `n x k_i` matrix::Dense<ValueType> or experimental::distributed::Vector<ValueType> (all entries of the same kind and, if distributed, the same partition); their columns together span the nullspace. They do not need to be orthonormal: they are copied and orthonormalized, dropping numerically dependent columns.
contains_constant	whether the constant vector is also part of the nullspace.

◆ create_from_constant()

template<typename ValueType = default_precision>

static std::unique_ptr<Nullspace> gko::solver::Nullspace< ValueType >::create_from_constant	(	std::shared_ptr< const Executor >	exec,
		dim< 2 >	size = `{}`
	)

static

Creates a Nullspace consisting only of the constant vector (e.g.

a pure-Neumann Poisson problem). The constant is never materialized, so the result can project vectors of any type and distribution.

Solvers adapt a constant-only nullspace to the size and value type of their system matrix, so the same object can be used in solver factories that are generated for matrices of different sizes (e.g. on the levels of a multigrid hierarchy) or precisions. Without a size, project() accepts vectors of any size; the size is only needed to use the Nullspace as a LinOp.

Parameters

exec	the executor
size	the (square, global) size `n x n` of the operator.

◆ get_basis()

template<typename ValueType = default_precision>

std::shared_ptr<const LinOp> gko::solver::Nullspace< ValueType >::get_basis ( ) const

noexcept

Returns: the orthonormalized explicit basis as a single n x k vector of the same kind as the input basis (orthogonal to the constant if contains_constant()), or nullptr if there is none.

◆ get_dimension()

template<typename ValueType = default_precision>

size_type gko::solver::Nullspace< ValueType >::get_dimension ( ) const

noexcept

Returns: the dimension of the nullspace: the number of orthonormal explicit basis vectors, plus one if the constant is included.

◆ project()

template<typename ValueType = default_precision>

void gko::solver::Nullspace< ValueType >::project ( ptr_param< LinOp > v ) const

Applies the projector in place: \( v \leftarrow (I - V V^H) v \), for each column of v independently.

Parameters

v a matrix::Dense or experimental::distributed::Vector with as many rows as this operator (any number of rows for a constant-only nullspace created without a size). Other precisions are converted like in apply(). If the Nullspace has an explicit basis, v must be of the same kind (and distribution) as that basis.

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

ginkgo/core/solver/nullspace.hpp

Public Types

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

template<typename ValueType = default_precision> class gko::solver::Nullspace< ValueType >

Member Function Documentation

◆ contains_constant()

◆ create()

◆ create_from_constant()

◆ get_basis()

◆ get_dimension()

◆ project()

template<typename ValueType = default_precision>
class gko::solver::Nullspace< ValueType >