MoReFEM: MoReFEM::GlobalVector Class Reference

Class which encapsulates both the Petsc vector and the numbering subset used to described it. More...

#include <GlobalVector.hpp>

Inheritance diagram for MoReFEM::GlobalVector:

Collaboration diagram for MoReFEM::GlobalVector:

Public Types
using	unique_ptr = std::unique_ptr<GlobalVector>
	Alias to unique pointer.

using	vector_unique_ptr = std::vector<unique_ptr>
	Alias to vector of unique pointers.

template<std::size_t N>
using	array_unique_ptr = std::array<unique_ptr, N>
	Alias to array of unique pointers.

using	parent = Wrappers::Petsc::Vector
	Alias to parent.

using	self = GlobalVector
	Alias to the type of the class.

enum class	check_non_null_ptr { no , yes }
	Convenient enum class for Internal() and InternalForReadOnly() template argument.

using	call_petsc_destroy = Advanced::Wrappers::Petsc::call_petsc_destroy
	Convenient alias.

Public Member Functions
const NumberingSubset &	GetNumberingSubset () const
	Numbering subset used to describe vector.

void	InitSequentialVector (const Mpi &mpi, std::size_t size, const std::source_location location=std::source_location::current())
	Set the vector as sequential.

void	InitMpiVector (const Mpi &mpi, std::size_t processor_wise_size, std::size_t program_wise_size, const std::source_location location=std::source_location::current())
	Set the vector as sequential.

void	InitMpiVectorWithGhost (const Mpi &mpi, std::size_t processor_wise_size, std::size_t program_wise_size, const std::vector< PetscInt > &ghost_padding, const std::source_location location=std::source_location::current())
	Create a parallel vector with ghost padding.

void	InitSequentialFromAsciiFile (const Mpi &mpi, const FilesystemNS::File &file, const std::source_location location=std::source_location::current())
	Init a sequential vector with the data read in the file.

void	InitParallelFromProcessorWiseAsciiFile (const Mpi &mpi, std::size_t processor_wise_size, std::size_t program_wise_size, const std::vector< PetscInt > &ghost_padding, const FilesystemNS::File &ascii_file, const std::source_location location=std::source_location::current())
	Init a vector from the data read in the file.

void	InitParallelFromProcessorWiseBinaryFile (const Mpi &mpi, std::size_t processor_wise_size, std::size_t program_wise_size, const std::vector< PetscInt > &ghost_padding, const FilesystemNS::File &binary_file, const std::source_location location=std::source_location::current())
	Init a vector from the data read in the file.

void	InitFromProgramWiseBinaryFile (const Mpi &mpi, std::size_t processor_wise_size, std::size_t program_wise_size, const std::vector< PetscInt > &ghost_padding, const FilesystemNS::File &binary_file, const std::source_location location=std::source_location::current())
	Init from a program-wise binary file: load a vector dumped with View() method.

template<check_non_null_ptr do_check_non_null_ptr = check_non_null_ptr::yes>
Vec	Internal (std::source_location location)
	Handle over the internal Vec object.

template<check_non_null_ptr do_check_non_null_ptr = check_non_null_ptr::yes>
Vec	InternalForReadOnly (std::source_location location) const
	Handle over the internal Vec object - when you can guarantee the call is only to read the value, not act upon it.

void	DuplicateLayout (const Vector &original, const std::source_location location=std::source_location::current())
	Duplicate layout (in memory, processor repartition, etc...)

PetscInt	GetProcessorWiseSize (const std::source_location location=std::source_location::current()) const
	Get the number of elements in the local vector.

PetscInt	GetProgramWiseSize (const std::source_location location=std::source_location::current()) const
	Get the number of elements in the global vector.

void	ZeroEntries (const std::source_location location=std::source_location::current(), update_ghost do_update_ghost=update_ghost::yes)
	Set all the entries to zero.

void	Assembly (const std::source_location location=std::source_location::current(), update_ghost do_update_ghost=update_ghost::yes)
	Petsc Assembling of the vector.

void	SetValues (const std::vector< PetscInt > &indexing, const PetscScalar *values, InsertMode insertOrAppend, const std::source_location location=std::source_location::current())
	Add or modify values inside a Petsc vector.

template<Utilities::Access AccessT>
void	SetValues (const std::vector< PetscInt > &indexing, const AccessVectorContent< AccessT > &local_vec, InsertMode insertOrAppend, const std::source_location location=std::source_location::current())
	Add or modify values inside a Petsc vector.

void	SetFromPetscVec (const Vec &petsc_vector, const std::source_location location=std::source_location::current())
	Set the values of a vector from a Petsc Vec object.

std::vector< PetscScalar >	GetValues (const std::vector< PetscInt > &indexing, const std::source_location location=std::source_location::current()) const
	Get the values of a vector on a current process.

void	GetValues (const std::vector< PetscInt > &indexing, std::vector< PetscScalar > &values, const std::source_location location=std::source_location::current()) const
	Get the values of a vector on a current process.

PetscScalar	GetValue (PetscInt index, const std::source_location location=std::source_location::current()) const
	Same as GetValues() for a unique index.

void	SetValue (PetscInt index, PetscScalar value, InsertMode insertOrAppend, const std::source_location location=std::source_location::current(), update_ghost do_update_ghost=update_ghost::yes)
	Add or modify one value inside a Petsc vector.

void	SetUniformValue (PetscScalar value, const std::source_location location=std::source_location::current(), update_ghost do_update_ghost=update_ghost::yes)
	Set the same value to all entries of the vector.

void	Copy (const Vector &source, const std::source_location location=std::source_location::current(), update_ghost do_update_ghost=update_ghost::yes)
	A wrapper over VecCopy, which assumed target already gets the right layout.

void	CompleteCopy (const Vector &source, const std::source_location location=std::source_location::current(), update_ghost do_update_ghost=update_ghost::yes)
	A complete copy: layout is copied first and then the values.

void	Scale (PetscScalar a, const std::source_location location=std::source_location::current(), update_ghost do_update_ghost=update_ghost::yes)
	Wrapper over VecScale, that performs Y = a * Y.

void	Shift (PetscScalar a, const std::source_location location=std::source_location::current(), update_ghost do_update_ghost=update_ghost::yes)
	Wrapper over VecShift, that performs Y = Y + a * 1.

void	View (const Mpi &mpi, const std::source_location location=std::source_location::current()) const
	Wrapper over VecView.

void	View (const Mpi &mpi, const FilesystemNS::File &output_file, const std::source_location location=std::source_location::current(), PetscViewerFormat format=PETSC_VIEWER_DEFAULT) const
	Wrapper over VecView in the case the viewer is a file.

void	ViewBinary (const Mpi &mpi, const FilesystemNS::File &output_file, const std::source_location location=std::source_location::current()) const
	Wrapper over MatView in the case the viewer is a binary file.

template<MpiScale MpiScaleT>
void	Print (const Mpi &mpi, const FilesystemNS::File &output_file, binary_or_ascii binary_or_ascii_choice=binary_or_ascii::from_input_data, const std::source_location location=std::source_location::current()) const
	Print the content of a vector in a file.

std::pair< PetscInt, PetscReal >	Min (const std::source_location location=std::source_location::current()) const
	Get the minimum.

std::pair< PetscInt, PetscReal >	Max (const std::source_location location=std::source_location::current()) const
	Get the maximum.

double	Norm (NormType type, const std::source_location location=std::source_location::current()) const
	Wrapper over VecNorm.

void	UpdateGhosts (const std::source_location location=std::source_location::current())
	Update the ghost values.

void	UpdateGhosts (const std::source_location location, update_ghost do_update_ghost)
	Update the ghost values if do_update_ghost is set to yes.

bool	IsParallel (const std::source_location location) const
	Tells whether a vector is sequential or parallel.

bool	IsGhosted (const std::source_location location) const
	Tells whether a vector is ghosted or not.

const std::vector< PetscInt > &	GetGhostPadding () const noexcept
	Accessor to the list of program-wise index of values that are ghost.

void	SetDoNotDestroyPetscVector ()
	Tells the class not to destroy the underlying vector through a call to VecDestroy().

const std::string &	GetName () const noexcept
	Get the name given to the vector at construction.

Static Public Attributes
static constexpr bool	ConceptIsGlobalLinearAlgebra = true
	Keyword to indicate that this class qualify for the Concept::GlobalLinearAlgebra.

Protected Member Functions
void	ChangeInternal (Vec new_petsc_vector)
	Change the underlying PETSc pointer .

VecType	GetType (const std::source_location location) const
	Tells the type of the current vector.

Private Attributes
const NumberingSubset &	numbering_subset_
	Numbering subset used to describe vector.

Vec	petsc_vector_
	Underlying Petsc vector.

std::vector< PetscInt >	ghost_padding_
	List of program-wise index of values that are ghost (i.e. required processor-wise but owned by another processor).

call_petsc_destroy	do_call_petsc_destroy_ = call_petsc_destroy::yes
	Whether the underlying Petsc vector will be destroyed upon destruction of the object.

std::string	name_

Advanced::Wrappers::Petsc::print_linalg_destruction	do_print_linalg_destruction_
	Whether there is a print on standard output to inform of the deletion of the Matrix.

Friends
template<class VariationalFormulationT >
struct	Internal::SolverNS::SnesInterface
	Friendship (to enable ChangeInternal usage).

Special members.
	GlobalVector (const NumberingSubset &numbering_subset, std::optional< std::string > name=std::nullopt)
	Constructor.

virtual	~GlobalVector () override
	Destructor.

	GlobalVector (const GlobalVector &rhs, std::optional< std::string > name=std::nullopt)
	The copy constructor.

	GlobalVector (GlobalVector &&rhs)=default
	The move constructor.

GlobalVector &	operator= (const GlobalVector &rhs)=delete
	The (copy) operator=.

GlobalVector &	operator= (GlobalVector &&rhs)=delete
	The (move) operator=.

	GlobalVector (const NumberingSubset &numbering_subset, Internal::WrapPetscVec wrap_petsc_vector)
	Constructor to provide a thin-wrapper over a Vec object.

Detailed Description

Class which encapsulates both the Petsc vector and the numbering subset used to described it.

Member Typedef Documentation

◆ self

using MoReFEM::GlobalVector::self = GlobalVector

Alias to the type of the class.

Constructor & Destructor Documentation

◆ GlobalVector() [1/4]

MoReFEM::GlobalVector::GlobalVector	(	const NumberingSubset &	numbering_subset,
		std::optional< std::string >	name = std::nullopt )

explicit

Constructor.

Parameters

[in]	numbering_subset	NumberingSubset to use to define the numbering of the vector.
[in]	name	A name that may optionally be given to the vector.

This name may be used to provide hints in error messages - especially when the error occurs in PetscFinalize() call where all the information we get is given by PETSc error message and is frankly not that useful: knowing a VecDestroy() call fails doesn't tell for which vector it happens. If name is not provided, a default name featuring the numbering subset number is used.

◆ GlobalVector() [2/4]

MoReFEM::GlobalVector::GlobalVector	(	const GlobalVector &	rhs,
		std::optional< std::string >	name = std::nullopt )

The copy constructor.

Parameters

[in]	rhs	The object from which the construction occurs.
[in]	name	A name that may optionally be given to the vector.

◆ GlobalVector() [3/4]

MoReFEM::GlobalVector::GlobalVector	(	const NumberingSubset &	numbering_subset,
		Internal::WrapPetscVec	wrap_petsc_vector )

explicitprivate

Constructor to provide a thin-wrapper over a Vec object.

This constructor is not meant to be used widely - hence its private status - : it is used only when defining a Snes interface for a non-linear solver in PETSc. In this case, PETSc provides a Vec object to compute quantities such as residual or evaluation_state; we want to be able to manipulate them with high-level PETSc wrapper defined in MoReFEM. PETSc owns these linear algebra quantities, so we do not call VecDestroy at destruction.

Parameters

[in]	numbering_subset	NumberingSubset to use to define the numbering of the vector.
[in]	wrap_petsc_vector	A very thin wrapper object over a `Vec`. The sole purpose of the class used here is to make apparent at call site that it is really a very special constructor that is used.

◆ GlobalVector() [4/4]

MoReFEM::GlobalVector::GlobalVector ( GlobalVector && rhs )

default

The move constructor.

Parameters

[in] rhs The object from which the construction occurs.

Member Function Documentation

◆ operator=() [1/2]

GlobalVector & MoReFEM::GlobalVector::operator= ( const GlobalVector & rhs )

delete

The (copy) operator=.

Parameters

[in] rhs The object from which the affectation occurs.

Returns: Reference to the object (to enable chained affectation).

◆ operator=() [2/2]

GlobalVector & MoReFEM::GlobalVector::operator= ( GlobalVector && rhs )

delete

The (move) operator=.

Parameters

[in] rhs The object from which the affectation occurs.

Returns: Reference to the object (to enable chained affectation).

◆ InitSequentialVector()

void MoReFEM::Wrappers::Petsc::Vector::InitSequentialVector	(	const Mpi &	mpi,
		std::size_t	size,
		const std::source_location	location = std::source_location::current() )

inherited

Set the vector as sequential.

Attention: This method is to be called just after creation of the object, which should still be a blank state.

Parameters

[in] size Number of elements in the vector.

Parameters

[in]	location	STL object with relevant information about the calling site (usually to help when an exception is thrown.
[in]	mpi	Mpi object which knows the rank of the processor, the total number of processors, etc...

◆ InitMpiVector()

void MoReFEM::Wrappers::Petsc::Vector::InitMpiVector	(	const Mpi &	mpi,
		std::size_t	processor_wise_size,
		std::size_t	program_wise_size,
		const std::source_location	location = std::source_location::current() )

inherited

Set the vector as sequential.

Attention: This method is to be called just after creation of the object, which should still be a blank state.

Parameters

[in]	processor_wise_size	Number of elements processor-wise (ghosts excluded).
[in]	program_wise_size	Number of elements program-wise.

Parameters

[in]	location	STL object with relevant information about the calling site (usually to help when an exception is thrown.
[in]	mpi	Mpi object which knows the rank of the processor, the total number of processors, etc...

◆ InitMpiVectorWithGhost()

void MoReFEM::Wrappers::Petsc::Vector::InitMpiVectorWithGhost	(	const Mpi &	mpi,
		std::size_t	processor_wise_size,
		std::size_t	program_wise_size,
		const std::vector< PetscInt > &	ghost_padding,
		const std::source_location	location = std::source_location::current() )

inherited

Create a parallel vector with ghost padding.

Parameters

[in]	processor_wise_size	Number of elements processor-wise (ghosts excluded).
[in]	program_wise_size	Number of elements program-wise.
[in]	ghost_padding	List of program-wise index of values that are ghost (i.e. required processor-wise but owned by another processor).

Parameters

[in]	location	STL object with relevant information about the calling site (usually to help when an exception is thrown.
[in]	mpi	Mpi object which knows the rank of the processor, the total number of processors, etc...

◆ InitSequentialFromAsciiFile()

void MoReFEM::Wrappers::Petsc::Vector::InitSequentialFromAsciiFile	(	const Mpi &	mpi,
		const FilesystemNS::File &	file,
		const std::source_location	location = std::source_location::current() )

inherited

Init a sequential vector with the data read in the file.

This file is assumed to have been created with Print() method for a sequential vector.

Parameters

[in] file File from which vector content is read.

Parameters

[in]	location	STL object with relevant information about the calling site (usually to help when an exception is thrown.
[in]	mpi	Mpi object which knows the rank of the processor, the total number of processors, etc...

◆ InitParallelFromProcessorWiseAsciiFile()

void MoReFEM::Wrappers::Petsc::Vector::InitParallelFromProcessorWiseAsciiFile	(	const Mpi &	mpi,
		std::size_t	processor_wise_size,
		std::size_t	program_wise_size,
		const std::vector< PetscInt > &	ghost_padding,
		const FilesystemNS::File &	ascii_file,
		const std::source_location	location = std::source_location::current() )

inherited

Init a vector from the data read in the file.

This file is assumed to have been created with Print() method.

Current method is in fact able to create a sequential vector as well, but use rather InitSequentialFromAsciiFile() with its more friendly API if you need only the sequential case.

Parameters

[in]	ascii_file	File from which vector content is read.
[in]	processor_wise_size	Number of elements processor-wise (ghosts excluded).
[in]	program_wise_size	Number of elements program-wise.
[in]	ghost_padding	List of program-wise index of values that are ghost (i.e. required processor-wise but owned by another processor).

Parameters

[in]	location	STL object with relevant information about the calling site (usually to help when an exception is thrown.
[in]	mpi	Mpi object which knows the rank of the processor, the total number of processors, etc...

◆ InitParallelFromProcessorWiseBinaryFile()

void MoReFEM::Wrappers::Petsc::Vector::InitParallelFromProcessorWiseBinaryFile	(	const Mpi &	mpi,
		std::size_t	processor_wise_size,
		std::size_t	program_wise_size,
		const std::vector< PetscInt > &	ghost_padding,
		const FilesystemNS::File &	binary_file,
		const std::source_location	location = std::source_location::current() )

inherited

Init a vector from the data read in the file.

This file is assumed to have been created with Print() method.

Parameters

[in]	binary_file	File from which vector content is read.
[in]	processor_wise_size	Number of elements processor-wise (ghosts excluded).
[in]	program_wise_size	Number of elements program-wise.
[in]	ghost_padding	List of program-wise index of values that are ghost (i.e. required processor-wise but owned by another processor).

Parameters

[in]	location	STL object with relevant information about the calling site (usually to help when an exception is thrown.
[in]	mpi	Mpi object which knows the rank of the processor, the total number of processors, etc...

◆ InitFromProgramWiseBinaryFile()

void MoReFEM::Wrappers::Petsc::Vector::InitFromProgramWiseBinaryFile	(	const Mpi &	mpi,
		std::size_t	processor_wise_size,
		std::size_t	program_wise_size,
		const std::vector< PetscInt > &	ghost_padding,
		const FilesystemNS::File &	binary_file,
		const std::source_location	location = std::source_location::current() )

inherited

Init from a program-wise binary file: load a vector dumped with View() method.

Parameters

[in]	binary_file	File from which the vector must be loaded. This file must be in binary format.
[in]	processor_wise_size	Number of elements processor-wise (ghosts excluded).
[in]	program_wise_size	Number of elements program-wise.
[in]	ghost_padding	List of program-wise index of values that are ghost (i.e. required processor-wise but owned by another processor).

Parameters

[in]	location	STL object with relevant information about the calling site (usually to help when an exception is thrown.
[in]	mpi	Mpi object which knows the rank of the processor, the total number of processors, etc...

◆ Internal()

template<check_non_null_ptr do_check_non_null_ptr = check_non_null_ptr::yes>

Vec MoReFEM::Wrappers::Petsc::Vector::Internal ( std::source_location location )

inherited

Handle over the internal Vec object.

Template Parameters

do_check_non_null_ptr If 'yes', check with an assert in debug mode whether the underlying pointer has been defined or not. 'yes' is really the go to value; 'no' is used only in some low level functions.

Parameters

[in] location STL object with relevant information about the calling site (usually to help when an exception is thrown.

Returns: Internal Vec object, which is indeed a pointer in Petsc.

Ideally it shouldn't be used at all except in the implementation of the Petsc Wrapper: a wrapper method should be implemented over the function that might need access to the Vec internal object.

◆ InternalForReadOnly()

template<check_non_null_ptr do_check_non_null_ptr = check_non_null_ptr::yes>

Vec MoReFEM::Wrappers::Petsc::Vector::InternalForReadOnly ( std::source_location location ) const

inherited

Handle over the internal Vec object - when you can guarantee the call is only to read the value, not act upon it.

Template Parameters

Parameters

[in] location STL object with relevant information about the calling site (usually to help when an exception is thrown.

Returns: Internal Vec object, which is indeed a pointer in Petsc.

Ideally it shouldn't be used at all except in the implementation of the Petsc Wrapper: a wrapper method should be implemented over the function that might need access to the Vec internal object.

◆ DuplicateLayout()

void MoReFEM::Wrappers::Petsc::Vector::DuplicateLayout	(	const Vector &	original,
		const std::source_location	location = std::source_location::current() )

inherited

Duplicate layout (in memory, processor repartition, etc...)

Parameters

[in] original Vector which layout is copied.

Parameters

[in] location STL object with relevant information about the calling site (usually to help when an exception is thrown.

◆ GetProcessorWiseSize()

PetscInt MoReFEM::Wrappers::Petsc::Vector::GetProcessorWiseSize ( const std::source_location location = std::source_location::current() ) const

inherited

Get the number of elements in the local vector.

Parameters

[in] location STL object with relevant information about the calling site (usually to help when an exception is thrown.

Returns: Number of processor-wise elements of the vector (ghost excluded).

◆ GetProgramWiseSize()

PetscInt MoReFEM::Wrappers::Petsc::Vector::GetProgramWiseSize ( const std::source_location location = std::source_location::current() ) const

inherited

Get the number of elements in the global vector.

Parameters

[in] location STL object with relevant information about the calling site (usually to help when an exception is thrown.

Returns: Number of program-wise elements of the vector.

◆ ZeroEntries()

void MoReFEM::Wrappers::Petsc::Vector::ZeroEntries	(	const std::source_location	location = std::source_location::current(),
		update_ghost	do_update_ghost = update_ghost::yes )

inherited

Set all the entries to zero.

Parameters

[in] location STL object with relevant information about the calling site (usually to help when an exception is thrown.

Parameters

[in] do_update_ghost Whether the target gets its ghost automatically updated or not. Default is yes.

◆ Assembly()

void MoReFEM::Wrappers::Petsc::Vector::Assembly	(	const std::source_location	location = std::source_location::current(),
		update_ghost	do_update_ghost = update_ghost::yes )

inherited

Petsc Assembling of the vector.

You have to call Assembly() method after you're done with all your SetXXX() calls; otherwise you will in all likelihood get error message in parallel about wrong state of the vector (but nothing in sequential run). It has not been put directly inside these SetXXX() methods as usually several of them are called in a row. For more details, see original explanation in Petsc page about vecSetValues: http://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Vec/VecSetValues.html#VecSetValues

Parameters

[in] location STL object with relevant information about the calling site (usually to help when an exception is thrown.

Parameters

[in] do_update_ghost Whether the target gets its ghost automatically updated or not. Default is yes. This argument must be set to update_ghost::no if you're considering a parallel vector without ghost.

There is a hidden call to it in boundary condition appliance; so maybe you

◆ SetValues() [1/2]

void MoReFEM::Wrappers::Petsc::Vector::SetValues	(	const std::vector< PetscInt > &	indexing,
		const PetscScalar *	values,
		InsertMode	insertOrAppend,
		const std::source_location	location = std::source_location::current() )

inherited

Add or modify values inside a Petsc vector.

Parameters

[in]	indexing	All indexes (program-wise) that have to be modified in the vector are stored here.
[in]	values	Values to put in the vector. This array should be the same size as indexing (unfortunately we can't check that here as it is a C array)
[in]	insertOrAppend	Petsc ADD_VALUES or INSERT_VALUES (see Petsc documentation).

Parameters

[in] location STL object with relevant information about the calling site (usually to help when an exception is thrown.

◆ SetValues() [2/2]

template<Utilities::Access AccessT>

void MoReFEM::Wrappers::Petsc::Vector::SetValues	(	const std::vector< PetscInt > &	indexing,
		const AccessVectorContent< AccessT > &	local_vec,
		InsertMode	insertOrAppend,
		const std::source_location	location = std::source_location::current() )

inherited

Add or modify values inside a Petsc vector.

Parameters

[in]	indexing	All indexes (program-wise) (program-wise) that have to be modified in the vector are stored here.
[in]	local_vec	Local vector which values will be put inside vector.
[in]	insertOrAppend	Petsc ADD_VALUES or INSERT_VALUES (see Petsc documentation).

Parameters

[in] location STL object with relevant information about the calling site (usually to help when an exception is thrown.

◆ SetFromPetscVec()

void MoReFEM::Wrappers::Petsc::Vector::SetFromPetscVec	(	const Vec &	petsc_vector,
		const std::source_location	location = std::source_location::current() )

inherited

Set the values of a vector from a Petsc Vec object.

Attention: This method should be used as little as possible: the purpose of current class is to avoid interacting at all with native Petsc objects. However, in some cases we do not have the choice: for instance in the definition of a Snes function (for Newton method) we get a Vec argument.

Parameters

[in] petsc_vector Petsc Vec object.

Parameters

[in] location STL object with relevant information about the calling site (usually to help when an exception is thrown.

◆ GetValues() [1/2]

std::vector< PetscScalar > MoReFEM::Wrappers::Petsc::Vector::GetValues	(	const std::vector< PetscInt > &	indexing,
		const std::source_location	location = std::source_location::current() ) const

inherited

Get the values of a vector on a current process.

This method allocates a vector at each call, another method with the same name does the same thing without the allocation at each time and should be used if the calls happen several times for the same underlying data.

Used to get the values of a sequential vector (see AccessVectorContent for mpi vectors).

Parameters

[in] indexing All program-wise indexes which are required from the vector.

Parameters

[in] location STL object with relevant information about the calling site (usually to help when an exception is thrown.

Returns: The values for all the indexes given in input.

◆ GetValues() [2/2]

void MoReFEM::Wrappers::Petsc::Vector::GetValues	(	const std::vector< PetscInt > &	indexing,
		std::vector< PetscScalar > &	values,
		const std::source_location	location = std::source_location::current() ) const

inherited

Get the values of a vector on a current process.

Same as the other method with the same name but the vector to contain the values is not allocated at each call. This method should be called if you need to get the values of a vector with the same size a lot of time.

Used to get the values of a sequential vector (see AccessVectorContent for mpi vectors).

Parameters

[in] indexing All program-wise indexes which are required from the vector.

Parameters

[in]	location	STL object with relevant information about the calling site (usually to help when an exception is thrown.
[in]	values	Vector used to contain the values. Should have been allocated before the call.

◆ GetValue()

PetscScalar MoReFEM::Wrappers::Petsc::Vector::GetValue	(	PetscInt	index,
		const std::source_location	location = std::source_location::current() ) const

inherited

Same as GetValues() for a unique index.

Parameters

[in] index Program-wise index which associated value is sought.

Parameters

[in] location STL object with relevant information about the calling site (usually to help when an exception is thrown.

Returns: Associated value.

◆ SetValue()

void MoReFEM::Wrappers::Petsc::Vector::SetValue	(	PetscInt	index,
		PetscScalar	value,
		InsertMode	insertOrAppend,
		const std::source_location	location = std::source_location::current(),
		update_ghost	do_update_ghost = update_ghost::yes )

inherited

Add or modify one value inside a Petsc vector.

Parameters

[in]	index	Index (program-wise) to be modified.
[in]	value	Value to set.
[in]	insertOrAppend	Petsc ADD_VALUES or INSERT_VALUES (see Petsc documentation).

Parameters

[in] location STL object with relevant information about the calling site (usually to help when an exception is thrown.

Parameters

[in] do_update_ghost Whether the target gets its ghost automatically updated or not. Default is yes.

◆ SetUniformValue()

void MoReFEM::Wrappers::Petsc::Vector::SetUniformValue	(	PetscScalar	value,
		const std::source_location	location = std::source_location::current(),
		update_ghost	do_update_ghost = update_ghost::yes )

inherited

Set the same value to all entries of the vector.

Parameters

[in] value Value to set.

Parameters

[in] location STL object with relevant information about the calling site (usually to help when an exception is thrown.

Parameters

[in] do_update_ghost Whether the target gets its ghost automatically updated or not. Default is yes.

◆ Copy()

void MoReFEM::Wrappers::Petsc::Vector::Copy	(	const Vector &	source,
		const std::source_location	location = std::source_location::current(),
		update_ghost	do_update_ghost = update_ghost::yes )

inherited

A wrapper over VecCopy, which assumed target already gets the right layout.

Doesn't do much except check the return value.

Parameters

[in] source Original vector which content is copied. Layout is assumed to be already the same between object for which the method is called and source.

Parameters

[in] location STL object with relevant information about the calling site (usually to help when an exception is thrown.

Parameters

[in] do_update_ghost Whether the target gets its ghost automatically updated or not. Default is yes.

◆ CompleteCopy()

void MoReFEM::Wrappers::Petsc::Vector::CompleteCopy	(	const Vector &	source,
		const std::source_location	location = std::source_location::current(),
		update_ghost	do_update_ghost = update_ghost::yes )

inherited

A complete copy: layout is copied first and then the values.

Parameters

[in] source Original vector which layout AND content is copied.

Parameters

[in] location STL object with relevant information about the calling site (usually to help when an exception is thrown.

Parameters

[in] do_update_ghost Whether the target gets its ghost automatically updated or not. Default is yes.

◆ Scale()

void MoReFEM::Wrappers::Petsc::Vector::Scale	(	PetscScalar	a,
		const std::source_location	location = std::source_location::current(),
		update_ghost	do_update_ghost = update_ghost::yes )

inherited

Wrapper over VecScale, that performs Y = a * Y.

Parameters

[in] a Factor by which the vector is scaled.

Parameters

[in] location STL object with relevant information about the calling site (usually to help when an exception is thrown.

Parameters

[in] do_update_ghost Whether the target gets its ghost automatically updated or not. Default is yes.

◆ Shift()

void MoReFEM::Wrappers::Petsc::Vector::Shift	(	PetscScalar	a,
		const std::source_location	location = std::source_location::current(),
		update_ghost	do_update_ghost = update_ghost::yes )

inherited

Wrapper over VecShift, that performs Y = Y + a * 1.

Parameters

[in] a Factor by which the vector is shifted.

Parameters

[in] do_update_ghost Whether the target gets its ghost automatically updated or not. Default is yes.

Parameters

[in] location STL object with relevant information about the calling site (usually to help when an exception is thrown.

◆ View() [1/2]

void MoReFEM::Wrappers::Petsc::Vector::View	(	const Mpi &	mpi,
		const std::source_location	location = std::source_location::current() ) const

inherited

Wrapper over VecView.

Parameters

[in]	location	STL object with relevant information about the calling site (usually to help when an exception is thrown.
[in]	mpi	Mpi object which knows the rank of the processor, the total number of processors, etc...

◆ View() [2/2]

void MoReFEM::Wrappers::Petsc::Vector::View	(	const Mpi &	mpi,
		const FilesystemNS::File &	output_file,
		const std::source_location	location = std::source_location::current(),
		PetscViewerFormat	format = PETSC_VIEWER_DEFAULT ) const

inherited

Wrapper over VecView in the case the viewer is a file.

Parameters

[in] format Format in which the matrix is written. See Petsc manual pages to get all the formats available; relevant ones so far are PETSC_VIEWER_DEFAULT and PETSC_VIEWER_ASCII_MATLAB.

Parameters

[in]	location	STL object with relevant information about the calling site (usually to help when an exception is thrown.
[in]	mpi	Mpi object which knows the rank of the processor, the total number of processors, etc...
[in]	output_file	File into which the vector content will be written.

Attention: To my knowledge there are no way to reload a PETSc vector from the file; if you need to do so rather use binary format.

◆ ViewBinary()

void MoReFEM::Wrappers::Petsc::Vector::ViewBinary	(	const Mpi &	mpi,
		const FilesystemNS::File &	output_file,
		const std::source_location	location = std::source_location::current() ) const

inherited

Wrapper over MatView in the case the viewer is a binary file.

Parameters

[in] output_file File into which the vector content will be written.

Parameters

[in]	location	STL object with relevant information about the calling site (usually to help when an exception is thrown.
[in]	mpi	Mpi object which knows the rank of the processor, the total number of processors, etc...

Attention: If you want to be able to reload the vector later with the exact same structure, you have to also store its local and global sizes (called processor- and program-wise sizes within MoReFEM) and the ghost padding.

◆ Print()

template<MpiScale MpiScaleT>

void MoReFEM::Wrappers::Petsc::Vector::Print	(	const Mpi &	mpi,
		const FilesystemNS::File &	output_file,
		binary_or_ascii	binary_or_ascii_choice = binary_or_ascii::from_input_data,
		const std::source_location	location = std::source_location::current() ) const

inherited

Print the content of a vector in a file.

Template Parameters

MpiScaleT Whether we want to print program-wise (in which case View function above is called) or processor-wise data. If processor-wise is chosen, this function does not rely on VecView: what I want to achieve is write to a different file for each processor and VecView doesn't seem to be able to do so.

Parameters

[in] mpi Mpi object which knows the rank of the processor, the total number of processors, etc...

Parameters

[in]	location	STL object with relevant information about the calling site (usually to help when an exception is thrown.
[in]	output_file	File into which the vector content will be written.
[in]	binary_or_ascii_choice	Whether the vector should be printed as binary or ascii. Default value takes its cue from the choice written in the input data file.

Attention

If the purpose is to be able to reload the file from disk later on, format MUST be binary (PETSc VecLoad works only with binary or HDF5). The file is not enough to rebuild the vector: you will also need to know:

The number of elements processor-wise.
The number of elements program-wise.
The program-wise indexes on the ghost elements.

◆ Min()

std::pair< PetscInt, PetscReal > MoReFEM::Wrappers::Petsc::Vector::Min ( const std::source_location location = std::source_location::current() ) const

inherited

Get the minimum.

Parameters

[in] location STL object with relevant information about the calling site (usually to help when an exception is thrown.

Returns: First element is the position of the minimum found, second is its value.

◆ Max()

std::pair< PetscInt, PetscReal > MoReFEM::Wrappers::Petsc::Vector::Max ( const std::source_location location = std::source_location::current() ) const

inherited

Get the maximum.

Parameters

[in] location STL object with relevant information about the calling site (usually to help when an exception is thrown.

Returns: First element is the position of the maximum found, second is its value.

◆ Norm()

double MoReFEM::Wrappers::Petsc::Vector::Norm	(	NormType	type,
		const std::source_location	location = std::source_location::current() ) const

inherited

Wrapper over VecNorm.

Available norms are NORM_1, NORM_2 and NORM_INFINITY.

Parameters

[in] type NORM_1, NORM_2 or NORM_INFINITY.

Parameters

[in] location STL object with relevant information about the calling site (usually to help when an exception is thrown.

Returns: Value of the norm.

◆ UpdateGhosts() [1/2]

void MoReFEM::Wrappers::Petsc::Vector::UpdateGhosts ( const std::source_location location = std::source_location::current() )

inherited

Update the ghost values.

Parameters

[in] location STL object with relevant information about the calling site (usually to help when an exception is thrown.

Prior to 2024, behaviour when applied upon a vector without ghost was left to PETSc. I have now changed that: when it is unduly called (i.e. when IsGhosted() returns false) it just does nothing.

Beware: all processor must make the call to this method! If for instance you're in a loop and one processor leaves it before the other, the code will be deadlocked...

◆ UpdateGhosts() [2/2]

void MoReFEM::Wrappers::Petsc::Vector::UpdateGhosts	(	const std::source_location	location,
		update_ghost	do_update_ghost )

inherited

Update the ghost values if do_update_ghost is set to yes.

This convenient method should be used only in Vector or Matrix related functions that provides the possibility to automatically update ghosts through an ad hoc argument (see for instance Copy() method).

Parameters

[in] location STL object with relevant information about the calling site (usually to help when an exception is thrown.

Prior to 2024, behaviour when applied upon a vector without ghost was left to PETSc. I have now changed that: when it is unduly called (i.e. when IsGhosted() returns false) it just does nothing.

Beware: all processor must make the call to this method! If for instance you're in a loop and one processor leaves it before the other, the code will be deadlocked...

Parameters

[in] do_update_ghost Whether the target gets its ghost automatically updated or not. Default is yes.

◆ IsParallel()

bool MoReFEM::Wrappers::Petsc::Vector::IsParallel ( const std::source_location location ) const

inherited

Tells whether a vector is sequential or parallel.

Parameters

[in] location STL object with relevant information about the calling site (usually to help when an exception is thrown.

Returns: True if the vector is parallel, false if it is sequential.

◆ IsGhosted()

bool MoReFEM::Wrappers::Petsc::Vector::IsGhosted ( const std::source_location location ) const

inherited

Tells whether a vector is ghosted or not.

PETSc does not provide a direct function to do so by choice (see this discussion).

However they provide nonetheless a way: VecGhostGetLocalForm provides a null pointer if invoked on ghost element.

Parameters

[in] location STL object with relevant information about the calling site (usually to help when an exception is thrown.

Returns: True if the vector gets some ghost (in general, not specifically on current rank).

◆ GetGhostPadding()

const std::vector< PetscInt > & MoReFEM::Wrappers::Petsc::Vector::GetGhostPadding ( ) const

noexceptinherited

Accessor to the list of program-wise index of values that are ghost.

(i.e. required processor-wise but owned by another processor).

Shouldn't be called if not a vector with ghost (an assert checks that).

◆ SetDoNotDestroyPetscVector()

void MoReFEM::Wrappers::Petsc::Vector::SetDoNotDestroyPetscVector ( )

inherited

Tells the class not to destroy the underlying vector through a call to VecDestroy().

Attention

This method should be avoided most of the time; the only cases in which it's relevant are:

the one exposed in the documentation of member function Swap.
when wrapping a Vec that is owned by PETSc (typically in non linear interface - Snes - where PETSc provides so-called evaluation_state and residual objects for each iteration).
temporarily, in FiberList to avoid crash at deallocation. This is however temporary and should be fixed (see #1895).

◆ GetName()

const std::string & MoReFEM::Wrappers::Petsc::Vector::GetName ( ) const

noexceptinherited

Get the name given to the vector at construction.

This is intended as a developer tool for debug, especially when something goes awry with PetscFinalize().

Returns: Name given as construction.

It should be noticed that inherited class GlobalVector may provide a default name if none was given; no default name however is foreseen in current base class.

◆ ChangeInternal()

void MoReFEM::Wrappers::Petsc::Vector::ChangeInternal ( Vec new_petsc_vector )

protectedinherited

Change the underlying PETSc pointer .

Parameters

[in] new_petsc_vector The new underlying PETSc Vec (which is a typedef to a pointer).

This functionality was introduced after version 3.12 of PETSc: I realized after the non linear code failed that I didn't set it up properly. The functions given to SNESSetFunction and SNESSetJacobian must work on Vec and Mat objects handled completely by PETSc; it just happened in prior versions of the library it used up the system matrices and vectors given to SolveNonLinear. So these functions now start by creating on the stack respectively a GlobalVector and a GlobalMatrix; ChangeInternal is then called so that these temporary objects handle internally the objects provided by PETSc API.

◆ GetType()

VecType MoReFEM::Wrappers::Petsc::Vector::GetType ( const std::source_location location ) const

protectedinherited

Tells the type of the current vector.

Parameters

[in] location STL object with relevant information about the calling site (usually to help when an exception is thrown.

This is a thin wrapper over VecGetType.

Returns: A PETSc [VecType](https://petsc.org/release/manualpages/Vec/VecType/) object which tells which type of vector it is.

As the API is not great (returns VecType that is a pointer so comparison to a VecType such as VECSEQ could yield unexpected result) I make it provate. More sugary methods such as IsSequential or IsParallel will be introduced instead.

Field Documentation

◆ ConceptIsGlobalLinearAlgebra

constexpr bool MoReFEM::GlobalVector::ConceptIsGlobalLinearAlgebra = true

inlinestaticconstexpr

Keyword to indicate that this class qualify for the Concept::GlobalLinearAlgebra.

◆ ghost_padding_

std::vector<PetscInt> MoReFEM::Wrappers::Petsc::Vector::ghost_padding_

privateinherited

List of program-wise index of values that are ghost (i.e. required processor-wise but owned by another processor).

Left empty if sequential or mpi without ghost.

◆ do_call_petsc_destroy_

call_petsc_destroy MoReFEM::Wrappers::Petsc::Vector::do_call_petsc_destroy_ = call_petsc_destroy::yes

privateinherited

Whether the underlying Petsc vector will be destroyed upon destruction of the object.

Default behaviour is to do so, but in some cases (for instance when vector has been built from an existing Petsc Vec) it is wiser not to.

◆ name_

std::string MoReFEM::Wrappers::Petsc::Vector::name_

privateinherited

◆ do_print_linalg_destruction_

Advanced::Wrappers::Petsc::print_linalg_destruction MoReFEM::Wrappers::Petsc::Vector::do_print_linalg_destruction_

privateinherited

Initial value:

{
            Advanced::Wrappers::Petsc::print_linalg_destruction::no
        }

Whether there is a print on standard output to inform of the deletion of the Matrix.

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

/builds/2mk6rsew/0/MoReFEM/CoreLibrary/MoReFEM/Sources/Core/LinearAlgebra/GlobalVector.hpp

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Private Attributes

Friends

Special members.

Detailed Description

Member Typedef Documentation

◆ self

Constructor & Destructor Documentation

◆ GlobalVector() [1/4]

◆ GlobalVector() [2/4]

◆ GlobalVector() [3/4]

◆ GlobalVector() [4/4]

Member Function Documentation

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ InitSequentialVector()

◆ InitMpiVector()

◆ InitMpiVectorWithGhost()

◆ InitSequentialFromAsciiFile()

◆ InitParallelFromProcessorWiseAsciiFile()

◆ InitParallelFromProcessorWiseBinaryFile()

◆ InitFromProgramWiseBinaryFile()

◆ Internal()

◆ InternalForReadOnly()

◆ DuplicateLayout()

◆ GetProcessorWiseSize()

◆ GetProgramWiseSize()

◆ ZeroEntries()

◆ Assembly()

◆ SetValues() [1/2]

◆ SetValues() [2/2]

◆ SetFromPetscVec()

◆ GetValues() [1/2]

◆ GetValues() [2/2]

◆ GetValue()

◆ SetValue()

◆ SetUniformValue()

◆ Copy()

◆ CompleteCopy()

◆ Scale()

◆ Shift()

◆ View() [1/2]

◆ View() [2/2]

◆ ViewBinary()

◆ Print()

◆ Min()

◆ Max()

◆ Norm()

◆ UpdateGhosts() [1/2]

◆ UpdateGhosts() [2/2]

◆ IsParallel()

◆ IsGhosted()

◆ GetGhostPadding()

◆ SetDoNotDestroyPetscVector()

◆ GetName()

◆ ChangeInternal()

◆ GetType()

Field Documentation

◆ ConceptIsGlobalLinearAlgebra

◆ ghost_padding_

◆ do_call_petsc_destroy_

◆ name_

◆ do_print_linalg_destruction_