The DoFManager is responsible for allocating global dofs, constructing sparsity patterns, and generally simplifying the interaction between PhysicsSolvers and linear algebra operations. More...

#include <DofManager.hpp>

Classes
struct	SubComponent
	Describes a selection of components from a DoF field. More...

Public Types
enum	Location { Location::Elem, Location::Face, Location::Edge, Location::Node }
	Enumeration of geometric objects for support location. Note that this enum is nearly identical to Connectivity, but we keep both for code readability in function calls. More...

enum	Connector { Connector::Elem, Connector::Face, Connector::Edge, Connector::Node, Connector::None, Connector::Stencil }
	Enumeration of geometric objects for connectivity type. Note that this enum is nearly identical to Location, but we keep both for code readability in function calls. More...

using	CompMask = ComponentMask< MAX_COMP >
	Type of component mask used by DofManager.

Public Member Functions
	DofManager (string name)
	Constructor. More...

	DofManager (DofManager const &)=delete
	Deleted copy constructor.

	DofManager (DofManager &&)=default
	Move constructor.

DofManager &	operator= (DofManager const &)=delete
	Deleted copy assignment. More...

DofManager &	operator= (DofManager &&)=default
	Defaulted move assignment. More...

	~DofManager ()=default
	Destructor.

void	clear ()
	Remove all fields and couplings and re-enable addition of new fields.

void	setMesh (MeshLevel &mesh)
	Assign a mesh. More...

void	addField (string const &fieldName, Location location, integer components, std::vector< string > const &regions={})
	Add a new field and enumerate its degrees-of-freedom. More...

void	addField (string const &fieldName, Location location, integer components, arrayView1d< string const > const &regions)
	Add a new field and enumerate its degrees-of-freedom. More...

void	addCoupling (string const &rowFieldName, string const &colFieldName, Connector connectivity, std::vector< string > const &regions={}, bool symmetric=true)
	Add coupling between two fields. More...

void	addCoupling (string const &rowFieldName, string const &colFieldName, Connector connectivity, arrayView1d< string const > const &regions, bool symmetric=true)
	Add coupling between two fields. More...

void	addCoupling (string const &fieldName, FluxApproximationBase const &stencils)
	Special interface for self-connectivity through a stencil. More...

void	reorderByRank ()
	Finish populating fields and apply appropriate dof renumbering. More...

bool	fieldExists (string const &name) const
	Check if string key is already being used. More...

string const &	getKey (string const &fieldName) const
	Return the key used to record the field in the DofManager. More...

globalIndex	numGlobalDofs (string const &fieldName) const

globalIndex	numGlobalDofs () const

localIndex	numLocalDofs (string const &fieldName) const

localIndex	numLocalDofs () const

globalIndex	rankOffset (string const &fieldName) const

globalIndex	rankOffset () const

integer	numComponents (string const &fieldName="") const

integer	numComponents () const

Location	location (string const &fieldName) const
	Get the support location type of the field. More...

std::vector< string > const &	regions (string const &fieldName) const

globalIndex	globalOffset (string const &fieldName) const

array1d< integer >	numComponentsPerField () const
	Return an array of number of components per field, sorted by field registration order. More...

template<typename CONTAINER >
void	getLocalDofComponentLabels (CONTAINER &labels) const
	Fill a container with unique dof labels for each local dof. More...

void	setSparsityPattern (SparsityPattern< globalIndex > &pattern) const
	Populate sparsity pattern of the entire system matrix. More...

template<typename VECTOR >
void	copyVectorToField (VECTOR const &vector, string const &srcFieldName, string const &dstFieldName, real64 scalingFactor, CompMask mask=CompMask(MAX_COMP, true)) const
	Copy values from LA vectors to simulation data arrays. More...

void	copyVectorToField (arrayView1d< real64 const > const &localVector, string const &srcFieldName, string const &dstFieldName, real64 scalingFactor, CompMask mask=CompMask(MAX_COMP, true)) const
	Copy values from LA vectors to simulation data arrays. More...

template<typename VECTOR >
void	addVectorToField (VECTOR const &vector, string const &srcFieldName, string const &dstFieldName, real64 scalingFactor, CompMask mask=CompMask(MAX_COMP, true)) const
	Add values from LA vectors to simulation data arrays. More...

void	addVectorToField (arrayView1d< real64 const > const &localVector, string const &srcFieldName, string const &dstFieldName, real64 scalingFactor, CompMask mask=CompMask(MAX_COMP, true)) const
	Add values from LA vectors to simulation data arrays. More...

template<typename VECTOR >
void	copyFieldToVector (VECTOR &vector, string const &srcFieldName, string const &dstFieldName, real64 scalingFactor, CompMask mask=CompMask(MAX_COMP, true)) const
	Copy values from nodes to DOFs. More...

void	copyFieldToVector (arrayView1d< real64 > const &localVector, string const &srcFieldName, string const &dstFieldName, real64 scalingFactor, CompMask mask=CompMask(MAX_COMP, true)) const
	Copy values from simulation data arrays to vectors. More...

template<typename VECTOR >
void	addFieldToVector (VECTOR &vector, string const &srcFieldName, string const &dstFieldName, real64 scalingFactor, CompMask mask=CompMask(MAX_COMP, true)) const
	Add values from a simulation data array to a DOF vector. More...

void	addFieldToVector (arrayView1d< real64 > const &localVector, string const &srcFieldName, string const &dstFieldName, real64 scalingFactor, CompMask mask=CompMask(MAX_COMP, true)) const
	Add values from a simulation data array to a DOF vector. More...

std::vector< SubComponent >	filterDofs (std::vector< SubComponent > const &excluded) const
	Create a dof selection by filtering out excluded components. More...

void	setupFrom (DofManager const &source, std::vector< SubComponent > const &selection)
	Populate this manager from another using a sub-selection of fields/components. More...

template<typename MATRIX >
void	makeRestrictor (std::vector< SubComponent > const &selection, MPI_Comm const &comm, bool transpose, MATRIX &restrictor) const
	Create a matrix that restricts vectors and matrices to a subset of DOFs. More...

void	printFieldInfo (std::ostream &os=std::cout) const
	Print the summary of declared fields and coupling. More...

Static Public Attributes
static int constexpr	MAX_COMP = 32
	Maximum number of components in a field.

Detailed Description

The DoFManager is responsible for allocating global dofs, constructing sparsity patterns, and generally simplifying the interaction between PhysicsSolvers and linear algebra operations.

Definition at line 41 of file DofManager.hpp.

Member Enumeration Documentation

◆ Connector

enum geosx::DofManager::Connector

strong

Enumeration of geometric objects for connectivity type. Note that this enum is nearly identical to Location, but we keep both for code readability in function calls.

Enumerator
Elem	connectivity is element (like in finite elements)
Face	connectivity is face (like in finite volumes TPFA)
Edge	connectivity is edge (like fracture element connectors)
Node	connectivity is node (like in finite volumes MPFA)
None	there is no connectivity (self connected field, like a lumped mass matrix)
Stencil	connectivity is through a (set of) user-provided stencil(s)

Definition at line 80 of file DofManager.hpp.

◆ Location

enum geosx::DofManager::Location

strong

Enumeration of geometric objects for support location. Note that this enum is nearly identical to Connectivity, but we keep both for code readability in function calls.

Enumerator
Elem	location is element (like pressure in finite volumes)
Face	location is face (like flux in mixed finite elements)
Edge	location is edge (like flux between fracture elements)
Node	location is node (like displacements in finite elements)

Definition at line 67 of file DofManager.hpp.

Constructor & Destructor Documentation

◆ DofManager()

geosx::DofManager::DofManager ( string name )

explicit

Constructor.

Parameters

[in] name a unique name for this DoF manager

Member Function Documentation

◆ addCoupling() [1/3]

void geosx::DofManager::addCoupling	(	string const &	rowFieldName,
		string const &	colFieldName,
		Connector	connectivity,
		std::vector< string > const &	regions = `{}`,
		bool	symmetric = `true`
	)

Add coupling between two fields.

The connectivity argument defines how the two fields couple. If the first field has support location A, the second field has support location B, and the connecting object is C, the sparsity pattern will be defined as (AC)(CB). The final argument indicates if the coupling is symmetric, in the sense that there is a two-way coupling between the fields. Without this argument, a nonzero block will be added to the system matrix for block AB, but block BA will remain zero (one-way coupling).

Example 1 = ("node_field","elem_field", ELEM, {}, true) couples all dofs sharing a common element (two-way coupling)
Example 2 = ("node_field","node_field", NODE, {}, true) couples all dofs sharing a common node (two-way coupling)
Example 3 = ("node_field","face_field", NODE, {}, false) couples nodal dofs to adjacent faces (one-way coupling)

When the number of components is greater than one, we always assume they are tightly coupled to one another and form a dense block. The sparsity pattern LC*CL is then interpreted as the super-node pattern, containing dense sub-blocks.

Parameters

[in]	rowFieldName	string the name of the row field.
[in]	colFieldName	string the name of the col field.
[in]	connectivity	Connectivity through what they are connected.
[in]	regions	names of regions where this coupling is defined.
[in]	symmetric	bool is it symmetric, i.e., both row-col and col-row?

◆ addCoupling() [2/3]

void geosx::DofManager::addCoupling	(	string const &	rowFieldName,
		string const &	colFieldName,
		Connector	connectivity,
		arrayView1d< string const > const &	regions,
		bool	symmetric = `true`
	)

Add coupling between two fields.

The connectivity argument defines how the two fields couple. If the first field has support location A, the second field has support location B, and the connecting object is C, the sparsity pattern will be defined as (AC)(CB). The final argument indicates if the coupling is symmetric, in the sense that there is a two-way coupling between the fields. Without this argument, a nonzero block will be added to the system matrix for block AB, but block BA will remain zero (one-way coupling).

Example 1 = ("node_field","elem_field", ELEM, {}, true) couples all dofs sharing a common element (two-way coupling)
Example 2 = ("node_field","node_field", NODE, {}, true) couples all dofs sharing a common node (two-way coupling)
Example 3 = ("node_field","face_field", NODE, {}, false) couples nodal dofs to adjacent faces (one-way coupling)

When the number of components is greater than one, we always assume they are tightly coupled to one another and form a dense block. The sparsity pattern LC*CL is then interpreted as the super-node pattern, containing dense sub-blocks.

Parameters

[in]	rowFieldName	string the name of the row field.
[in]	colFieldName	string the name of the col field.
[in]	connectivity	Connectivity through what they are connected.
[in]	regions	names of regions where this coupling is defined.
[in]	symmetric	bool is it symmetric, i.e., both row-col and col-row?

Overload for arrayView1d<string> input used by physics solvers.

◆ addCoupling() [3/3]

void geosx::DofManager::addCoupling	(	string const &	fieldName,
		FluxApproximationBase const &	stencils
	)

Special interface for self-connectivity through a stencil.

Parameters

[in]	fieldName	name of the field (this is only for diagonal blocks)
[in]	stencils	a pointer to FluxApproximation storing the stencils

The field must be defined on element support. The set of regions is taken automatically from the field definition.

◆ addField() [1/2]

void geosx::DofManager::addField	(	string const &	fieldName,
		Location	location,
		integer	components,
		std::vector< string > const &	regions = `{}`
	)

Add a new field and enumerate its degrees-of-freedom.

Parameters

[in]	fieldName	the name of the field
[in]	location	type of mesh objects the field is defined on
[in]	components	number of components
[in]	regions	list of region names the field is defined on (if empty, selects all regions)

◆ addField() [2/2]

void geosx::DofManager::addField	(	string const &	fieldName,
		Location	location,
		integer	components,
		arrayView1d< string const > const &	regions
	)

Add a new field and enumerate its degrees-of-freedom.

Parameters

[in]	fieldName	the name of the field
[in]	location	type of mesh objects the field is defined on
[in]	components	number of components
[in]	regions	list of region names the field is defined on (if empty, selects all regions)

Overload for arrayView1d<string> input used by physics solvers.

◆ addFieldToVector() [1/2]

template<typename VECTOR >

void geosx::DofManager::addFieldToVector	(	VECTOR &	vector,
		string const &	srcFieldName,
		string const &	dstFieldName,
		real64	scalingFactor,
		CompMask	mask = `CompMask(MAX_COMP, true)`
	)		const

Add values from a simulation data array to a DOF vector.

Template Parameters

VECTOR type of LA vector

Parameters

vector	target LA vector
srcFieldName	name of the source field (view wrapper key on the manager)
dstFieldName	name of the destination field (as defined in DofManager)
scalingFactor	a factor to scale vector values by
mask	component selection mask

◆ addFieldToVector() [2/2]

void geosx::DofManager::addFieldToVector	(	arrayView1d< real64 > const &	localVector,
		string const &	srcFieldName,
		string const &	dstFieldName,
		real64	scalingFactor,
		CompMask	mask = `CompMask(MAX_COMP, true)`
	)		const

Add values from a simulation data array to a DOF vector.

Parameters

localVector	target vector
srcFieldName	name of the source field (view wrapper key on the manager)
dstFieldName	name of the destination field (as defined in DofManager)
scalingFactor	a factor to scale vector values by
mask	component selection mask

◆ addVectorToField() [1/2]

template<typename VECTOR >

void geosx::DofManager::addVectorToField	(	VECTOR const &	vector,
		string const &	srcFieldName,
		string const &	dstFieldName,
		real64	scalingFactor,
		CompMask	mask = `CompMask(MAX_COMP, true)`
	)		const

Add values from LA vectors to simulation data arrays.

Template Parameters

VECTOR type of LA vector

Parameters

vector	source LA vector
srcFieldName	name of the source field (as defined in DofManager)
dstFieldName	name of the destination field (view wrapper key on the manager)
scalingFactor	a factor to scale vector values by
mask	component selection mask

◆ addVectorToField() [2/2]

void geosx::DofManager::addVectorToField	(	arrayView1d< real64 const > const &	localVector,
		string const &	srcFieldName,
		string const &	dstFieldName,
		real64	scalingFactor,
		CompMask	mask = `CompMask(MAX_COMP, true)`
	)		const

Add values from LA vectors to simulation data arrays.

Parameters

localVector	source local vector
srcFieldName	name of the source field (as defined in DofManager)
dstFieldName	name of the destination field (view wrapper key on the manager)
scalingFactor	a factor to scale vector values by
mask	component selection mask

◆ copyFieldToVector() [1/2]

template<typename VECTOR >

void geosx::DofManager::copyFieldToVector	(	VECTOR &	vector,
		string const &	srcFieldName,
		string const &	dstFieldName,
		real64	scalingFactor,
		CompMask	mask = `CompMask(MAX_COMP, true)`
	)		const

Copy values from nodes to DOFs.

Template Parameters

VECTOR type of LA vector

Parameters

vector	target LA vector
srcFieldName	name of the source field (view wrapper key on the manager)
dstFieldName	name of the destination field (as defined in DofManager)
scalingFactor	a factor to scale vector values by
mask	component selection mask

◆ copyFieldToVector() [2/2]

void geosx::DofManager::copyFieldToVector	(	arrayView1d< real64 > const &	localVector,
		string const &	srcFieldName,
		string const &	dstFieldName,
		real64	scalingFactor,
		CompMask	mask = `CompMask(MAX_COMP, true)`
	)		const

Copy values from simulation data arrays to vectors.

Parameters

localVector	target LA vector
srcFieldName	name of the source field (view wrapper key on the manager)
dstFieldName	name of the destination field (as defined in DofManager)
scalingFactor	a factor to scale vector values by
mask	component selection mask

◆ copyVectorToField() [1/2]

template<typename VECTOR >

void geosx::DofManager::copyVectorToField	(	VECTOR const &	vector,
		string const &	srcFieldName,
		string const &	dstFieldName,
		real64	scalingFactor,
		CompMask	mask = `CompMask(MAX_COMP, true)`
	)		const

Copy values from LA vectors to simulation data arrays.

Template Parameters

VECTOR type of LA vector

Parameters

vector	source LA vector
srcFieldName	name of the source field (as defined in DofManager)
dstFieldName	name of the destination field (view wrapper key on the manager)
scalingFactor	a factor to scale vector values by
mask	component selection mask

◆ copyVectorToField() [2/2]

void geosx::DofManager::copyVectorToField	(	arrayView1d< real64 const > const &	localVector,
		string const &	srcFieldName,
		string const &	dstFieldName,
		real64	scalingFactor,
		CompMask	mask = `CompMask(MAX_COMP, true)`
	)		const

Copy values from LA vectors to simulation data arrays.

Parameters

localVector	source local vector
srcFieldName	name of the source field (as defined in DofManager)
dstFieldName	name of the destination field (view wrapper key on the manager)
scalingFactor	a factor to scale vector values by
mask	component selection mask

◆ fieldExists()

bool geosx::DofManager::fieldExists ( string const & name ) const

Check if string key is already being used.

Parameters

name	field key to check

Returns: flag true if exists

◆ filterDofs()

std::vector< SubComponent > geosx::DofManager::filterDofs ( std::vector< SubComponent > const & excluded ) const

Create a dof selection by filtering out excluded components.

Parameters

excluded a list of dof components to exclude

Returns: a vector of remaining dof components

Note: Removed components must not have repeats, and each entry must either have loComp = 0 or hiComp = numComponents(fieldName) (or both). In other words, filtered out components must not leave "holes" in DOFs.

◆ getKey()

string const& geosx::DofManager::getKey ( string const & fieldName ) const

Return the key used to record the field in the DofManager.

Parameters

[in] fieldName string the name of the field.

Returns: string indicating name of the field.

◆ getLocalDofComponentLabels()

template<typename CONTAINER >

void geosx::DofManager::getLocalDofComponentLabels ( CONTAINER & labels ) const

inline

Fill a container with unique dof labels for each local dof.

Template Parameters

CONTAINER type of container to fill

Parameters

labels the container to fill

The labels are assigned starting from zero in increasing order of field registration. Labels are repeated for each support point of a field.

Definition at line 322 of file DofManager.hpp.

◆ globalOffset()

globalIndex geosx::DofManager::globalOffset ( string const & fieldName ) const

Returns: global offset of field's block on current processor in the system matrix.

Parameters

[in] fieldName name of the field.

◆ location()

Location geosx::DofManager::location ( string const & fieldName ) const

Get the support location type of the field.

Parameters

[in] fieldName name of the field

Returns: support location type

◆ makeRestrictor()

template<typename MATRIX >

void geosx::DofManager::makeRestrictor	(	std::vector< SubComponent > const &	selection,
		MPI_Comm const &	comm,
		bool	transpose,
		MATRIX &	restrictor
	)		const

Create a matrix that restricts vectors and matrices to a subset of DOFs.

Template Parameters

MATRIX type of matrix used for restrictor

Parameters

selection	a list of fields to select; each entry is a struct containing the name of the field and low and high selected component indices
comm	the MPI communicator to use in the operator
transpose	if `true`, the transpose (prolongation) operator will be created
restrictor	resulting operator

Note: Can only be called after reorderByRank(), since global DOF indexing is required for the restrictor to make sense.

◆ numComponents() [1/2]

integer geosx::DofManager::numComponents ( string const & fieldName = "" ) const

Returns: number of components in a given field.

Parameters

fieldName name of the field

◆ numComponents() [2/2]

integer geosx::DofManager::numComponents ( ) const

Returns: number of dof components across all fields.

◆ numComponentsPerField()

array1d< integer > geosx::DofManager::numComponentsPerField ( ) const

Return an array of number of components per field, sorted by field registration order.

Returns: array of number of components

◆ numGlobalDofs() [1/2]

globalIndex geosx::DofManager::numGlobalDofs ( string const & fieldName ) const

Returns: number of global dofs of a given field.

Parameters

fieldName the name of the field

◆ numGlobalDofs() [2/2]

globalIndex geosx::DofManager::numGlobalDofs ( ) const

Returns: total number of dofs across all fields and processors.

◆ numLocalDofs() [1/2]

localIndex geosx::DofManager::numLocalDofs ( string const & fieldName ) const

Returns: number of local dofs of a given field.

Parameters

fieldName name of the field

◆ numLocalDofs() [2/2]

localIndex geosx::DofManager::numLocalDofs ( ) const

Returns: total number of dofs across all fields on current processor.

◆ operator=() [1/2]

DofManager& geosx::DofManager::operator= ( DofManager const & )

delete

Deleted copy assignment.

Returns

◆ operator=() [2/2]

DofManager& geosx::DofManager::operator= ( DofManager && )

default

Defaulted move assignment.

Returns

◆ printFieldInfo()

void geosx::DofManager::printFieldInfo ( std::ostream & os = std::cout ) const

Print the summary of declared fields and coupling.

Parameters

os	output stream

◆ rankOffset() [1/2]

globalIndex geosx::DofManager::rankOffset ( string const & fieldName ) const

Returns: rank offset of given field, i.e. total number of dofs of this field on previous processors.

Parameters

fieldName name of the field

◆ rankOffset() [2/2]

globalIndex geosx::DofManager::rankOffset ( ) const

Returns: rank offset of current processor, i.e. total number of dofs on previous processors.

◆ regions()

std::vector< string > const& geosx::DofManager::regions ( string const & fieldName ) const

Returns: The list of region names in field's domain.

Parameters

fieldName name of the field

◆ reorderByRank()

void geosx::DofManager::reorderByRank ( )

Finish populating fields and apply appropriate dof renumbering.

This function must be called after all field and coupling information has been added. It adjusts DoF index arrays to account for presence of other fields (in a global monolithic fashion).

Note: After DofManager has been closed, new fields and coupling cannot be added, until clear or setMesh is called.; After reorderByRank() is called, the meaning of FieldDescription::globalOffset changes from "global offset of field's block in a global field-wise ordered (block) system" to "global offset of field's block on current processor in a rank-wise ordered system". This meaning is consistent with its use throughout. For example, this is the row/col global offset used to insert the field's sparsity block into a global coupled system.

◆ setMesh()

void geosx::DofManager::setMesh ( MeshLevel & mesh )

Assign a mesh.

Parameters

mesh	the target mesh (non-const access required for allocating index arrays)

Note: Calling this function unconditionally removes all previously defined fields and couplings. The user should only call this when they actually want to replace the mesh with a new one, or they think the mesh topology might have changed and so the DOFs need to be re-numbered. They must then re-add all fields and couplings, and call reorderByRank() again.

◆ setSparsityPattern()

void geosx::DofManager::setSparsityPattern ( SparsityPattern< globalIndex > & pattern ) const

Populate sparsity pattern of the entire system matrix.

Parameters

[out] pattern the target sparsity pattern

◆ setupFrom()

void geosx::DofManager::setupFrom	(	DofManager const &	source,
		std::vector< SubComponent > const &	selection
	)

Populate this manager from another using a sub-selection of fields/components.

Parameters

source	source dof manager
selection	selection of fields/components

Note: this will also allocate new dof

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

coreComponents/linearAlgebra/DofManager.hpp

Classes

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Member Enumeration Documentation

◆ Connector

◆ Location

Constructor & Destructor Documentation

◆ DofManager()

Member Function Documentation

◆ addCoupling() [1/3]

◆ addCoupling() [2/3]

◆ addCoupling() [3/3]

◆ addField() [1/2]

◆ addField() [2/2]

◆ addFieldToVector() [1/2]

◆ addFieldToVector() [2/2]

◆ addVectorToField() [1/2]

◆ addVectorToField() [2/2]

◆ copyFieldToVector() [1/2]

◆ copyFieldToVector() [2/2]

◆ copyVectorToField() [1/2]

◆ copyVectorToField() [2/2]

◆ fieldExists()

◆ filterDofs()

◆ getKey()

◆ getLocalDofComponentLabels()

◆ globalOffset()

◆ location()

◆ makeRestrictor()

◆ numComponents() [1/2]

◆ numComponents() [2/2]

◆ numComponentsPerField()

◆ numGlobalDofs() [1/2]

◆ numGlobalDofs() [2/2]

◆ numLocalDofs() [1/2]

◆ numLocalDofs() [2/2]

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ printFieldInfo()

◆ rankOffset() [1/2]

◆ rankOffset() [2/2]

◆ regions()

◆ reorderByRank()

◆ setMesh()

◆ setSparsityPattern()

◆ setupFrom()