MoReFEM: MoReFEM::GlobalMatrix Class Reference

Class which encapsulates both the Petsc matrix and the numbering subsets used to described its rows and columns. More...

#include <GlobalMatrix.hpp>

Inheritance diagram for MoReFEM::GlobalMatrix:

Collaboration diagram for MoReFEM::GlobalMatrix:

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

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

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

using	petsc_parent = Wrappers::Petsc::Matrix
	Alias to parent.

using	numbering_subset_parent = Crtp::NumberingSubsetForMatrix<GlobalMatrix>
	Alias to other parent.

using	self = Matrix
	Alias to self.

using	parent = Advanced::Wrappers::Petsc::AbstractMatrix
	Alias to parent.

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

Public Member Functions
void	InitMinimalCase (const Mpi &mpi, MatType petsc_matrix_type, const std::source_location location=std::source_location::current())
	A method which provides a very bare initialization: only the type of the matrix is set.

void	InitSequentialMatrix (std::size_t Nrow, std::size_t Ncolumn, const MatrixPattern &matrix_pattern, const Mpi &mpi, const std::source_location location=std::source_location::current())
	Create a sequential sparse matrix.

void	InitParallelMatrix (std::size_t Nlocal_row, std::size_t Nlocal_column, std::size_t Nglobal_row, std::size_t Nglobal_column, const MatrixPattern &matrix_pattern, const Mpi &mpi, const std::source_location location=std::source_location::current())
	Create a parallel sparse matrix.

void	InitSequentialDenseMatrix (std::size_t Nrow, std::size_t Ncolumn, const Mpi &mpi, const std::source_location location=std::source_location::current())
	Create a sequential dense matrix.

void	InitParallelDenseMatrix (std::size_t Nlocal_row, std::size_t Nlocal_column, std::size_t Nglobal_row, std::size_t Nglobal_column, const Mpi &mpi, const std::source_location location=std::source_location::current())
	Create a parallel dense matrix.

void	DuplicateLayout (const Matrix &original, MatDuplicateOption option, const std::source_location location=std::source_location::current())
	Duplicate the layout of the matrix.

void	Copy (const Matrix &source, const MatStructure &structure=SAME_NONZERO_PATTERN, const std::source_location location=std::source_location::current())
	A wrapper over MatCopy, which assumed target already gets the right layout.

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

void	Assembly (const std::source_location location=std::source_location::current())
	Petsc Assembling of the matrix.

bool	IsAssembled (const std::source_location location=std::source_location::current()) const
	Indicates if a matrix has been assembled and is ready for use; for example, in matrix-vector product.

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

void	SetValuesRow (PetscInt row_index, const PetscScalar *values, const std::source_location location=std::source_location::current())
	Set the values of a row.

void	SetValue (PetscInt row_index, PetscInt column_index, PetscScalar value, InsertMode insertOrAppend, const std::source_location location=std::source_location::current())
	Set a single entry into a Petsc matrix.

void	LoadBinary (const Mpi &mpi, const FilesystemNS::File &input_file, const std::source_location location=std::source_location::current())
	Wrapper over MatLoad in the case the viewer is a file.

void	SetFromPetscMat (Mat petsc_matrix, const std::source_location location=std::source_location::current())
	Init a Matrix from a Petsc Mat object.

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

Mat	Internal (std::source_location location)
	Handle over the internal Mat object.

Mat	InternalForReadOnly (std::source_location location) const
	Handle over the internal Mat object - when you can guarantee the call is only to read the value, not act upon it.

std::pair< PetscInt, PetscInt >	GetProcessorWiseSize (const std::source_location location=std::source_location::current()) const
	Get the number of elements in the local matrix.

std::pair< PetscInt, PetscInt >	GetProgramWiseSize (const std::source_location location=std::source_location::current()) const
	Get the number of elements in the global matrix (first is number of rows, second number of columns).

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

void	ZeroRows (const std::vector< PetscInt > &row_indexes, PetscScalar diagonal_value, const std::source_location location=std::source_location::current())
	Zeros all entries (except possibly the main diagonal) of a set of rows of a matrix.

void	ZeroRowsColumns (const std::vector< PetscInt > &row_indexes, PetscScalar diagonal_value, const std::source_location location=std::source_location::current())
	Zeros all entries (except possibly the main diagonal) of a set of rows and columns of a matrix.

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

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

void	GetInfo (MatInfo *infos, const std::source_location location=std::source_location::current())
	Wrapper over MatGetInfo()

void	GetOption (MatOption op, PetscBool *flg, const std::source_location location=std::source_location::current())
	Wrapper over MatGetOption()

void	SetOption (MatOption op, PetscBool flg, const std::source_location location=std::source_location::current())
	Wrapper over MatSetOption()

MatType	GetType (const std::source_location location=std::source_location::current()) const
	Return the type of the matrix.

PetscScalar	GetValue (PetscInt row_index, PetscInt column_index, const std::source_location location=std::source_location::current()) const
	Get the value of an element of the matrix.

void	GetRow (PetscInt row_index, std::vector< PetscInt > &row_content_position_list, std::vector< PetscScalar > &row_content_value_list, const std::source_location location=std::source_location::current()) const
	Get a row for the matrix.

void	GetRow (PetscInt row_index, std::vector< std::pair< PetscInt, PetscScalar > > &row_content, const std::source_location location=std::source_location::current()) const
	Get a row for the matrix.

void	GetColumnVector (PetscInt column_index, ::MoReFEM::Wrappers::Petsc::Vector &column, const std::source_location location=std::source_location::current()) const
	Get the column of the matrix.

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

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

void	ViewBinary (const ::MoReFEM::Wrappers::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.

const NumberingSubset &	GetRowNumberingSubset () const
	Numbering subset used to describe rows.

const NumberingSubset &	GetColNumberingSubset () const
	Numbering subset used to describe columns.

Special members.
	GlobalMatrix (const NumberingSubset &row_numbering_subset, const NumberingSubset &col_numbering_subset, std::optional< std::string > name=std::nullopt)
	Constructor.

	~GlobalMatrix () override
	Destructor.

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

	GlobalMatrix (GlobalMatrix &&rhs)=delete
	The move constructor.

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

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

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

static constexpr bool	ConceptIsPetscMatrix = true
	Keyword to indicate that this class qualify for the Concept::PetscStrictlyMatrix.

Protected Member Functions
Mat &	InternalNoCheck ()
	Handle over the internal Mat object, with no check whether it is initialized or not.

const Mat &	InternalNoCheckForReadOnly () const
	Same as `InternalNoCheck` with `const` qualifier.

void	ChangeInternal (const ::MoReFEM::Wrappers::Mpi &mpi, Mat new_petsc_matrix)
	Change the underlying Mat object pointed by the class.

void	SetDoNotDestroyPetscMatrix ()
	Tells the class not to destroy the underlying vector through a call to MatDestroy().

call_petsc_destroy	DoCallPetscDestroy () const noexcept
	Get the value of do_call_petsc_destroy_.

void	SetDoCallPetscDestroy (call_petsc_destroy value)
	Set the value of do_call_petsc_destroy_.

Special members.
virtual void	Unused () const

Private Member Functions
	GlobalMatrix (const Wrappers::Mpi &mpi, const NumberingSubset &row_numbering_subset, const NumberingSubset &col_numbering_subset, Internal::WrapPetscMat wrap_petsc_matrix)
	Constructor to provide a thin-wrapper over a Mat object.

void	InitMatrixHelper (const Mpi &mpi, MatType petsc_matrix_type, std::size_t Nlocal_row, std::size_t Nlocal_column, std::size_t Nglobal_row, std::size_t Nglobal_column, const std::source_location location=std::source_location::current())
	Helper to init a matrix.

Private Attributes
Mat	petsc_matrix_
	Underlying Petsc matrix.

call_petsc_destroy	do_call_petsc_destroy_ { call_petsc_destroy::yes }
	Whether the underlying Petsc matrix 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.

const NumberingSubset &	row_numbering_subset_
	Numbering subset used to describe rows.

const NumberingSubset &	col_numbering_subset_
	Numbering subset used to describe columns.

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

Detailed Description

Class which encapsulates both the Petsc matrix and the numbering subsets used to described its rows and columns.

Constructor & Destructor Documentation

◆ GlobalMatrix() [1/4]

MoReFEM::GlobalMatrix::GlobalMatrix	(	const NumberingSubset &	row_numbering_subset,
		const NumberingSubset &	col_numbering_subset,
		std::optional< std::string >	name = std::nullopt )

explicit

Constructor.

Parameters

[in]	row_numbering_subset	NumberingSubset to use to define the numbering of rows.
[in]	col_numbering_subset	NumberingSubset to use to define the numbering of columns.
[in]	name	A name that may optionally be given to the matrix.

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 MatDestroy() call fails doesn't tell for which matrix it happens. If name is not provided, a default name featuring the numbering subset number is used.

◆ GlobalMatrix() [2/4]

MoReFEM::GlobalMatrix::GlobalMatrix	(	const GlobalMatrix &	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 matrix.

◆ GlobalMatrix() [3/4]

MoReFEM::GlobalMatrix::GlobalMatrix ( GlobalMatrix && rhs )

delete

The move constructor.

Parameters

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

◆ GlobalMatrix() [4/4]

MoReFEM::GlobalMatrix::GlobalMatrix	(	const Wrappers::Mpi &	mpi,
		const NumberingSubset &	row_numbering_subset,
		const NumberingSubset &	col_numbering_subset,
		Internal::WrapPetscMat	wrap_petsc_matrix )

explicitprivate

Constructor to provide a thin-wrapper over a Mat 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 Mat 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 MatDestroy at destruction.

Parameters

[in]	mpi	Mpi object which knows the rank of the processor, the total number of processors, etc...
[in]	row_numbering_subset	NumberingSubset to use to define the numbering of rows.
[in]	col_numbering_subset	NumberingSubset to use to define the numbering of columns.
[in]	wrap_petsc_matrix	A very thin wrapper object over a `Mat`. 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.

Member Function Documentation

◆ operator=() [1/2]

GlobalMatrix & MoReFEM::GlobalMatrix::operator= ( const GlobalMatrix & 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]

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

delete

The (move) operator=.

Parameters

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

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

◆ InitMinimalCase()

void MoReFEM::Wrappers::Petsc::Matrix::InitMinimalCase	(	const Mpi &	mpi,
		MatType	petsc_matrix_type,
		const std::source_location	location = std::source_location::current() )

inherited

A method which provides a very bare initialization: only the type of the matrix is set.

Most of the time, you should use another method such as InitSequentialMatrix() or InitParallelDenseMatrix(); however when you just want to load a matrix from a file you may not know the informations related to sizes. In this case, this method will provide the minimum set up required to properly init your matrix. Beware though: if you're reloading a matrix in parallel (typically with petsc_matrix_type = MATMPIAIJ) you get no guarantee whatsoever of the repartition that will be done among the ranks. To control this, you should use instead another of the InitXXX() methods for which you are able to set the dimensions yourself (you may have a look at TestPetscMatrixIO where both versions are checked).

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]	petsc_matrix_type	The PETSc identifier for the requested matrix (see https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatType.html#MatType)

◆ InitSequentialMatrix()

void MoReFEM::Wrappers::Petsc::Matrix::InitSequentialMatrix	(	std::size_t	Nrow,
		std::size_t	Ncolumn,
		const MatrixPattern &	matrix_pattern,
		const Mpi &	mpi,
		const std::source_location	location = std::source_location::current() )

inherited

Create a sequential sparse matrix.

Parameters

[in]	Nrow	Number of rows.
[in]	Ncolumn	Number of columns.
[in]	matrix_pattern	Pattern of the matrix (number of elements expected on each row_).
[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.

The matrix hence created will keep the non-zero structure: even if a value becomes 0 it will go on being held as a non-zero emplacement.

◆ InitParallelMatrix()

void MoReFEM::Wrappers::Petsc::Matrix::InitParallelMatrix	(	std::size_t	Nlocal_row,
		std::size_t	Nlocal_column,
		std::size_t	Nglobal_row,
		std::size_t	Nglobal_column,
		const MatrixPattern &	matrix_pattern,
		const Mpi &	mpi,
		const std::source_location	location = std::source_location::current() )

inherited

Create a parallel sparse matrix.

Parameters

[in]	Nlocal_row	Number of rows on the local processor.
[in]	Nlocal_column	Number of columns on the local processor.
[in]	Nglobal_row	Number of rows on the global processor.
[in]	Nglobal_column	Number of columns on the global processor.
[in]	matrix_pattern	Pattern of the matrix (number of elements expected on each row_).
[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.

◆ InitSequentialDenseMatrix()

void MoReFEM::Wrappers::Petsc::Matrix::InitSequentialDenseMatrix	(	std::size_t	Nrow,
		std::size_t	Ncolumn,
		const Mpi &	mpi,
		const std::source_location	location = std::source_location::current() )

inherited

Create a sequential dense matrix.

Parameters

[in]	Nrow	Number of rows.
[in]	Ncolumn	Number of columns.
[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.

◆ InitParallelDenseMatrix()

void MoReFEM::Wrappers::Petsc::Matrix::InitParallelDenseMatrix	(	std::size_t	Nlocal_row,
		std::size_t	Nlocal_column,
		std::size_t	Nglobal_row,
		std::size_t	Nglobal_column,
		const Mpi &	mpi,
		const std::source_location	location = std::source_location::current() )

inherited

Create a parallel dense matrix.

Parameters

[in]	Nlocal_row	Number of rows on the local processor.
[in]	Nlocal_column	Number of columns on the local processor.
[in]	Nglobal_row	Number of rows on the global processor.
[in]	Nglobal_column	Number of columns on the global processor.
[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.

◆ DuplicateLayout()

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

inherited

Duplicate the layout of the matrix.

Parameters

[in]	original	Original matrix, which layout is to be duplicated.
[in]	option	Fine tune the behaviour of the duplication. Three values are possible: MAT_DO_NOT_COPY_VALUES MAT_COPY_VALUES MAT_SHARE_NONZERO_PATTERN (share the nonzero patterns with the previous matrix but do not copy them.)
[in]	location	STL object with relevant information about the calling site (usually to help when an exception is thrown.

To make the third option work, the original matrix must have been assembled (i.e. where are the non-zero values must already be determined accurately, not just how many of them there are on each line - which is the information we get when a matrix is created). So technically it means you can't just duplicate the layout of a matrix you've just initialized but in which you haven't put any value yet.

◆ Copy()

void MoReFEM::Wrappers::Petsc::Matrix::Copy	(	const Matrix &	source,
		const MatStructure &	structure = SAME_NONZERO_PATTERN,
		const std::source_location	location = std::source_location::current() )

inherited

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

Parameters

[in]	source	Original matrix which content is copied. It is assumed the object that called the method already gets the same layout as source.
[in]	structure	SAME_NONZERO_PATTERN or DIFFERENT_NONZERO_PATTERN. SAME_NONZERO_PATTERN should apply for almost all cases in MoReFEM; however if you're using raw Petsc library you'll see there are more prerequisite to this choice (the pattern must be fully built). Within the frame of this wrapper there shouldn't be any problem provided one of the InitXXX() method has been called.

Parameters

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

◆ CompleteCopy()

void MoReFEM::Wrappers::Petsc::Matrix::CompleteCopy	(	const Matrix &	source,
		const std::source_location	location = std::source_location::current() )

inherited

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

Parameters

[in] source Original matrix which layout AND content is copied. Beware: this method requires that source has already been deeply initialized (SetValues() and Assembly() should already have been called). See DuplicateLayout() for a lenghtier explanation.

Parameters

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

◆ Assembly()

void MoReFEM::Wrappers::Petsc::Matrix::Assembly ( const std::source_location location = std::source_location::current() )

inherited

Petsc Assembling of the matrix.

Parameters

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

◆ IsAssembled()

bool MoReFEM::Wrappers::Petsc::Matrix::IsAssembled ( const std::source_location location = std::source_location::current() ) const

inherited

Indicates if a matrix has been assembled and is ready for use; for example, in matrix-vector product.

Note: This is a direct wrapper upon Petsc MatAssembled() function.

Parameters

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

Returns: True if the matrix has been assembled.

◆ SetValues()

void MoReFEM::Wrappers::Petsc::Matrix::SetValues	(	const std::vector< PetscInt > &	row_indexing,
		const std::vector< PetscInt > &	column_indexing,
		const PetscScalar *	values,
		InsertMode	insertOrAppend,
		const std::source_location	location = std::source_location::current(),
		ignore_zero_entries	do_ignore_zero_entries = ignore_zero_entries::no )

inherited

Add or modify values inside a Petsc matrix.

Note: Petsc documentation says you should use this over MatSetValue, but usage is actually not that wide: you actually define here a block of values. So for instance you choose row_indexing = { 1, 2 } and col_indexing = { 3, 5 }, you modify the four values (1, 3), (1, 5), (2, 3), (2, 5)... (which might fail if some of it are actually not non zero values! See however ignore_zero_entries for a possible workaround here). To my knowledge there are no way to modify just (1, 3) and (2, 5) in one call! I skimmed a bit through petsc-user help list, and they seem to suggest MatSetValues should be called for one row at a time.

Warning: Assembly() must be called afterwards!

Parameters

[in]	row_indexing	Program-wise index of the rows which values will be set.
[in]	column_indexing	Program-wise index of the columns which values will be set.
[in]	values	Values to put in the matrix. This array should be the same size as row_indexing x column_indexing: it is a block of values that is actually introduced!
[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.
[in]	do_ignore_zero_entries	If yes, you might specify a block which encompass locations that are not within the pattern. For instance in our case above, you may specify row_indexing = { 1, 2 } and col_indexing = { 3, 5 } even if pattern says there are no value at (1, 5). In this case, the associated value in values MUST be 0.; any other value will rightfully trigger a Petsc error.

◆ SetValuesRow()

void MoReFEM::Wrappers::Petsc::Matrix::SetValuesRow	(	PetscInt	row_index,
		const PetscScalar *	values,
		const std::source_location	location = std::source_location::current() )

inherited

Set the values of a row.

Warning: Pattern must have been set beforehand!; Assembly() must be called afterwards!

Parameters

[in]	row_index	Program-wise index of the row which values will be set.
[in]	values	Non-zero values to report in the matrix.

Parameters

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

◆ SetValue()

void MoReFEM::Wrappers::Petsc::Matrix::SetValue	(	PetscInt	row_index,
		PetscInt	column_index,
		PetscScalar	value,
		InsertMode	insertOrAppend,
		const std::source_location	location = std::source_location::current() )

inherited

Set a single entry into a Petsc matrix.

Warning: Assembly() must be called afterwards!

As noted in Petsc manual pages, if several values the SetValues() method should be preferred; however see SetValues() documentation that specify the cases in which it can be applied.

Parameters

[in]	row_index	Program-wise index of the row which value will be set.
[in]	column_index	Program-wise index of the column which value will be set.
[in]	value	Value to put in the matrix.
[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.

◆ LoadBinary()

void MoReFEM::Wrappers::Petsc::Matrix::LoadBinary	(	const Mpi &	mpi,
		const FilesystemNS::File &	input_file,
		const std::source_location	location = std::source_location::current() )

inherited

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

Parameters

[in]	mpi	Mpi object which knows the rank of the processor, the total number of processors, etc...
[in]	input_file	File from which matrix is to be loaded ON THE ROOT PROCESSOR.

Parameters

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

Attention

Thie methods should be called after at least a minimal initialization of the matrix has been done (type of PETSc matrix should be set, and under the hood MatCreate should have been invoked. Concretely in MoReFEM wrapper, this means you should have called beforehand a InitXXX() method - InitMinimalCase() for instance. Of course you may also have

So far (June 2020), the underlying MatLoad function works with two formats:

Binary
HDF5 (see https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatLoad.html) HDF5 is not currently used within MoReFEM, but PETSc comes with strong guarantees upon the portability of binary files (see https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscBinaryRead.html)

◆ InitMatrixHelper()

void MoReFEM::Wrappers::Petsc::Matrix::InitMatrixHelper	(	const Mpi &	mpi,
		MatType	petsc_matrix_type,
		std::size_t	Nlocal_row,
		std::size_t	Nlocal_column,
		std::size_t	Nglobal_row,
		std::size_t	Nglobal_column,
		const std::source_location	location = std::source_location::current() )

privateinherited

Helper to init a matrix.

Parameters

[in]	Nlocal_row	Number of rows on the local processor.
[in]	Nlocal_column	Number of columns on the local processor.
[in]	Nglobal_row	Number of rows on the global processor.
[in]	Nglobal_column	Number of columns on the global processor.
[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]	petsc_matrix_type	The PETSc identifier for the requested matrix (see https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatType.html#MatType)

◆ Unused()

virtual void MoReFEM::Advanced::Wrappers::Petsc::AbstractMatrix::Unused ( ) const

protectedvirtualinherited

Unused method that should never been called to satisfy the condition of at least one out of line virtual method definition.

◆ SetFromPetscMat()

void MoReFEM::Advanced::Wrappers::Petsc::AbstractMatrix::SetFromPetscMat	(	Mat	petsc_matrix,
		const std::source_location	location = std::source_location::current() )

inherited

Init a Matrix from a Petsc Mat object.

Ideally it shouldn't be used at all except in the implementation of few of the associated function such as MatMatMult.

Parameters

[in] petsc_matrix Native Petsc matrix which should be put inside current object.

Parameters

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

◆ GetName()

const std::string & MoReFEM::Advanced::Wrappers::Petsc::AbstractMatrix::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.

◆ Internal()

Mat MoReFEM::Advanced::Wrappers::Petsc::AbstractMatrix::Internal ( std::source_location location )

inherited

Handle over the internal Mat object.

Parameters

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

Returns: Internal Mat 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 Mat internal object.

◆ InternalForReadOnly()

Mat MoReFEM::Advanced::Wrappers::Petsc::AbstractMatrix::InternalForReadOnly ( std::source_location location ) const

inherited

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

Parameters

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

Returns: Internal Mat 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 Mat internal object.

◆ InternalNoCheck()

Mat & MoReFEM::Advanced::Wrappers::Petsc::AbstractMatrix::InternalNoCheck ( )

protectedinherited

Handle over the internal Mat object, with no check whether it is initialized or not.

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

◆ InternalNoCheckForReadOnly()

const Mat & MoReFEM::Advanced::Wrappers::Petsc::AbstractMatrix::InternalNoCheckForReadOnly ( ) const

protectedinherited

Same as InternalNoCheck with const qualifier.

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

◆ GetProcessorWiseSize()

std::pair< PetscInt, PetscInt > MoReFEM::Advanced::Wrappers::Petsc::AbstractMatrix::GetProcessorWiseSize ( const std::source_location location = std::source_location::current() ) const

inherited

Get the number of elements in the local matrix.

Parameters

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

Returns: First index is number of rows, second one the number of columns.

◆ GetProgramWiseSize()

std::pair< PetscInt, PetscInt > MoReFEM::Advanced::Wrappers::Petsc::AbstractMatrix::GetProgramWiseSize ( const std::source_location location = std::source_location::current() ) const

inherited

Get the number of elements in the global matrix (first is number of rows, second number of columns).

Parameters

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

Returns: First index is number of rows, second one the number of columns.

◆ ZeroEntries()

void MoReFEM::Advanced::Wrappers::Petsc::AbstractMatrix::ZeroEntries ( const std::source_location location = std::source_location::current() )

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.

◆ ZeroRows()

void MoReFEM::Advanced::Wrappers::Petsc::AbstractMatrix::ZeroRows	(	const std::vector< PetscInt > &	row_indexes,
		PetscScalar	diagonal_value,
		const std::source_location	location = std::source_location::current() )

inherited

Zeros all entries (except possibly the main diagonal) of a set of rows of a matrix.

Parameters

[in]	row_indexes	Indexes of the row considered (C - numbering).
[in]	diagonal_value	Value for the diagonal term. Put 0. if you want it zeroed too.

Parameters

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

◆ ZeroRowsColumns()

void MoReFEM::Advanced::Wrappers::Petsc::AbstractMatrix::ZeroRowsColumns	(	const std::vector< PetscInt > &	row_indexes,
		PetscScalar	diagonal_value,
		const std::source_location	location = std::source_location::current() )

inherited

Zeros all entries (except possibly the main diagonal) of a set of rows and columns of a matrix.

Parameters

[in]	row_indexes	Indexes of the row considered (C - numbering). All values on this row (except the diagonal value) AND all values on the columns will be zeroed.
[in]	diagonal_value	Value for the diagonal term. Put 0. if you want it zeroed too.

Parameters

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

◆ Scale()

void MoReFEM::Advanced::Wrappers::Petsc::AbstractMatrix::Scale	(	PetscScalar	a,
		const std::source_location	location = std::source_location::current() )

inherited

Wrapper over MatScale, 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.

◆ Norm()

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

inherited

Wrapper over MatNorm.

Parameters

[in] type Type of norm. Available norms are NORM_1, NORM_FROBENIUS and NORM_INFINITY.

Parameters

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

Returns: Norm of the vector of the chose type.

◆ GetInfo()

void MoReFEM::Advanced::Wrappers::Petsc::AbstractMatrix::GetInfo	(	MatInfo *	infos,
		const std::source_location	location = std::source_location::current() )

inherited

Wrapper over MatGetInfo()

Parameters

[in]	location	STL object with relevant information about the calling site (usually to help when an exception is thrown.
[in]	infos	Matrix information context (see Petsc documentation for more details).

◆ GetOption()

void MoReFEM::Advanced::Wrappers::Petsc::AbstractMatrix::GetOption	(	MatOption	op,
		PetscBool *	flg,
		const std::source_location	location = std::source_location::current() )

inherited

Wrapper over MatGetOption()

Parameters

[in]	location	STL object with relevant information about the calling site (usually to help when an exception is thrown.
[in]	op	The Petsc MatOption which status is sought.
[out]	flg	True if the option is set, false otherwise.

◆ SetOption()

void MoReFEM::Advanced::Wrappers::Petsc::AbstractMatrix::SetOption	(	MatOption	op,
		PetscBool	flg,
		const std::source_location	location = std::source_location::current() )

inherited

Wrapper over MatSetOption()

Parameters

[in]	location	STL object with relevant information about the calling site (usually to help when an exception is thrown.
[in]	op	The Petsc MatOption which status is to be modified.
[in]	flg	Whether the option is activated or not.

◆ GetType()

MatType MoReFEM::Advanced::Wrappers::Petsc::AbstractMatrix::GetType ( const std::source_location location = std::source_location::current() ) const

inherited

Return the type of the matrix.

Thin wrapper over https://petsc.org/release/docs/manualpages/Mat/MatGetType

Parameters

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

Returns: The MatType of the matrix,

◆ GetValue()

PetscScalar MoReFEM::Advanced::Wrappers::Petsc::AbstractMatrix::GetValue	(	PetscInt	row_index,
		PetscInt	column_index,
		const std::source_location	location = std::source_location::current() ) const

inherited

Get the value of an element of the matrix.

The underlying Petsc function requires that the row belong to the current processor; however for the column it is much more liberal: if there is an attempt to get a value that doesn't belong to the CSR pattern, the function simply returns 0.

Parameters

[in]	row_index	Program-wise index of the row. The row MUST be one of the row handled by the current processor.
[in]	column_index	Program-wise index of the column.

Parameters

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

Returns: Value of the chosen element in the matrix.

◆ GetRow() [1/2]

void MoReFEM::Advanced::Wrappers::Petsc::AbstractMatrix::GetRow	(	PetscInt	row_index,
		std::vector< PetscInt > &	row_content_position_list,
		std::vector< PetscScalar > &	row_content_value_list,
		const std::source_location	location = std::source_location::current() ) const

inherited

Get a row for the matrix.

This is a wrapper over MatGetRow; it should be noticed that Petsc people hope this function is actually not used...

Parameters

[in] row_index Program-wise index of the row. The row MUST be one of the row handled by the current processor.

Parameters

[in]	location	STL object with relevant information about the calling site (usually to help when an exception is thrown.
[out]	row_content_position_list	Position of the non-zero values in the row.
[out]	row_content_value_list	Values of non-zero values in the row. This container is the same size as row_content_position

Todo: At the moment row_content is allocated each time; it might be useful not to do this... But this means structure has to be kept for each line of the matrix considered.

◆ GetRow() [2/2]

void MoReFEM::Advanced::Wrappers::Petsc::AbstractMatrix::GetRow	(	PetscInt	row_index,
		std::vector< std::pair< PetscInt, PetscScalar > > &	row_content,
		const std::source_location	location = std::source_location::current() ) const

inherited

Get a row for the matrix.

This is a wrapper over MatGetRow; it should be noticed that Petsc people hope this function is actually not used...

Parameters

[in] row_index Program-wise index of the row. The row MUST be one of the row handled by the current processor.

Parameters

[in]	location	STL object with relevant information about the calling site (usually to help when an exception is thrown.
[out]	row_content	Key is position of the non-zero values, value the actual value.

Todo: At the moment row_content is allocated each time; it might be useful not to do this... But this means structure has to be kept for each line of the matrix considered.

◆ GetColumnVector()

void MoReFEM::Advanced::Wrappers::Petsc::AbstractMatrix::GetColumnVector	(	PetscInt	column_index,
		::MoReFEM::Wrappers::Petsc::Vector &	column,
		const std::source_location	location = std::source_location::current() ) const

inherited

Get the column of the matrix.

This is a wrapper over MatGetColumnVector; it should be noticed that Petsc people hope this function is actually not used...

Parameters

[in]	column_index	Program-wise index of the column.
[out]	column	Vector containing the column.

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::Advanced::Wrappers::Petsc::AbstractMatrix::View	(	const ::MoReFEM::Wrappers::Mpi &	mpi,
		const std::source_location	location = std::source_location::current() ) const

inherited

Wrapper over MatView.

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.

◆ View() [2/2]

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

inherited

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

MatView write the content of the matrix only on the root processor; if you need it on several you need to copy the file afterwards (for instance in the case of prepartitioned data).

Parameters

[in]	mpi	Mpi object which knows the rank of the processor, the total number of processors, etc...
[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.
[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.

Parameters

[in]

file_mode

Same modes as in Petsc documentation , i.e.:

FILE_MODE_WRITE - create new file for binary output.
FILE_MODE_READ - open existing file for binary input.
FILE_MODE_APPEND - open existing file for binary output. Note: this field is actually not used if the format is an ascii one.

◆ ViewBinary()

void MoReFEM::Advanced::Wrappers::Petsc::AbstractMatrix::ViewBinary	(	const ::MoReFEM::Wrappers::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. This file will be written only on the root processor; for other ranks nothing is written at all.

Parameters

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

Parameters

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

◆ ChangeInternal()

void MoReFEM::Advanced::Wrappers::Petsc::AbstractMatrix::ChangeInternal	(	const ::MoReFEM::Wrappers::Mpi &	mpi,
		Mat	new_petsc_matrix )

protectedinherited

Change the underlying Mat object pointed by the class.

Attention: This should not be encouraged and is provided only t comply with PETSc non linear solve interface.

Parameters

[in]	mpi	Mpi object. It is provided so that Barrier() may be called: we do not want the ranks oto be inconsistent...
[in]	new_petsc_matrix	The Mat object that should now be used internally (for thecurrent mpi rank).

◆ SetDoNotDestroyPetscMatrix()

void MoReFEM::Advanced::Wrappers::Petsc::AbstractMatrix::SetDoNotDestroyPetscMatrix ( )

protectedinherited

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

Attention: This method should be avoided most of the time; it is there only for an edge case related to PETSc Snes interface!

◆ SetDoCallPetscDestroy()

void MoReFEM::Advanced::Wrappers::Petsc::AbstractMatrix::SetDoCallPetscDestroy ( call_petsc_destroy value )

protectedinherited

Set the value of do_call_petsc_destroy_.

You should rather use SetDoNotDestroyPetscMatrix(); this one is just helpful to define recopy in derived classes.

Parameters

[in] value The value to set.

Field Documentation

◆ ConceptIsGlobalLinearAlgebra

constexpr bool MoReFEM::GlobalMatrix::ConceptIsGlobalLinearAlgebra = true

inlinestaticconstexpr

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

◆ ConceptIsPetscMatrix

constexpr bool MoReFEM::Wrappers::Petsc::Matrix::ConceptIsPetscMatrix = true

inlinestaticconstexprinherited

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

◆ do_call_petsc_destroy_

call_petsc_destroy MoReFEM::Advanced::Wrappers::Petsc::AbstractMatrix::do_call_petsc_destroy_ { call_petsc_destroy::yes }

privateinherited

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

Default behaviour is to do so, but in some cases it is wiser not to.

◆ name_

std::string MoReFEM::Advanced::Wrappers::Petsc::AbstractMatrix::name_

privateinherited

◆ do_print_linalg_destruction_

Advanced::Wrappers::Petsc::print_linalg_destruction MoReFEM::Advanced::Wrappers::Petsc::AbstractMatrix::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/GlobalMatrix.hpp

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Private Member Functions

Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ GlobalMatrix() [1/4]

◆ GlobalMatrix() [2/4]

◆ GlobalMatrix() [3/4]

◆ GlobalMatrix() [4/4]

Member Function Documentation

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ InitMinimalCase()

◆ InitSequentialMatrix()

◆ InitParallelMatrix()

◆ InitSequentialDenseMatrix()

◆ InitParallelDenseMatrix()

◆ DuplicateLayout()

◆ Copy()

◆ CompleteCopy()

◆ Assembly()

◆ IsAssembled()

◆ SetValues()

◆ SetValuesRow()

◆ SetValue()

◆ LoadBinary()

◆ InitMatrixHelper()

◆ Unused()

◆ SetFromPetscMat()

◆ GetName()

◆ Internal()

◆ InternalForReadOnly()

◆ InternalNoCheck()

◆ InternalNoCheckForReadOnly()

◆ GetProcessorWiseSize()

◆ GetProgramWiseSize()

◆ ZeroEntries()

◆ ZeroRows()

◆ ZeroRowsColumns()

◆ Scale()

◆ Norm()

◆ GetInfo()

◆ GetOption()

◆ SetOption()

◆ GetType()

◆ GetValue()

◆ GetRow() [1/2]

◆ GetRow() [2/2]

◆ GetColumnVector()

◆ View() [1/2]

◆ View() [2/2]

◆ ViewBinary()

◆ ChangeInternal()

◆ SetDoNotDestroyPetscMatrix()

◆ SetDoCallPetscDestroy()

Field Documentation

◆ ConceptIsGlobalLinearAlgebra

◆ ConceptIsPetscMatrix

◆ do_call_petsc_destroy_

◆ name_

◆ do_print_linalg_destruction_