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	FieldSupport
	Describes field support on a single mesh body/level. More...

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

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

enum class	LocalReorderingType { None , ReverseCutHillMcKee }
	Indicates the type of (local to a rank) reordering applied to a given field. 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...

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

void	setDomain (DomainPartition &domain)
	Assign a domain. More...

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

void	addField (string const &fieldName, FieldLocation location, integer components, map< std::pair< string, string >, array1d< string > > const &regions)
	Add a new field and enumerate its degrees-of-freedom. More...

void	setLocalReorderingType (string const &fieldName, LocalReorderingType const reorderingType)
	Set the local reodering of the dof numbers. More...

void	disableGlobalCouplingForEquation (string const &fieldName, integer const c)
	Disable the global coupling for a given equation. More...

void	disableGlobalCouplingForEquations (string const &fieldName, arrayView1d< integer const > const components)
	Disable the global coupling for a set of equations. More...

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

void	addCoupling (string const &rowFieldName, string const &colFieldName, Connector connectivity, map< std::pair< string, string >, array1d< string > > 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

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

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...

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 SCALING_FACTOR_TYPE >
void	addVectorToField (arrayView1d< real64 const > const &localVector, string const &srcFieldName, string const &dstFieldName, SCALING_FACTOR_TYPE const &scalingFactor, CompMask mask=CompMask(MAX_COMP, true)) const
	Add values from LA vectors to simulation data arrays. 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...

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 constexpr int	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 43 of file DofManager.hpp.

Member Enumeration Documentation

◆ Connector

enum geos::DofManager::Connector

strong

Enumeration of geometric objects for connectivity type. Note that this enum is nearly identical to FieldLocation, 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 103 of file DofManager.hpp.

◆ LocalReorderingType

enum geos::DofManager::LocalReorderingType

strong

Indicates the type of (local to a rank) reordering applied to a given field.

Enumerator
None	Do not reorder the variables.
ReverseCutHillMcKee	Use reverve CutHill-McKee reordering algorithm.

Definition at line 116 of file DofManager.hpp.

Constructor & Destructor Documentation

◆ DofManager()

geos::DofManager::DofManager ( string name )

explicit

Constructor.

Parameters

[in] name a unique name for this DoF manager

Member Function Documentation

◆ addCoupling() [1/3]

void geos::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.

◆ addCoupling() [2/3]

void geos::DofManager::addCoupling	(	string const &	rowFieldName,
		string const &	colFieldName,
		Connector	connectivity,
		map< std::pair< string, string >, array1d< 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() [3/3]

void geos::DofManager::addCoupling	(	string const &	rowFieldName,
		string const &	colFieldName,
		Connector	connectivity,
		std::vector< FieldSupport > 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?

◆ addField() [1/2]

void geos::DofManager::addField	(	string const &	fieldName,
		FieldLocation	location,
		integer	components,
		map< std::pair< string, string >, array1d< 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)

Overload for map< string, array1d< string > > bodyFieldSupport used by physics solvers.

◆ addField() [2/2]

void geos::DofManager::addField	(	string const &	fieldName,
		FieldLocation	location,
		integer	components,
		std::vector< FieldSupport > 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)

◆ addFieldToVector()

void geos::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()

template<typename SCALING_FACTOR_TYPE >

void geos::DofManager::addVectorToField	(	arrayView1d< real64 const > const &	localVector,
		string const &	srcFieldName,
		string const &	dstFieldName,
		SCALING_FACTOR_TYPE const &	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()

void geos::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()

void geos::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

◆ disableGlobalCouplingForEquation()

void geos::DofManager::disableGlobalCouplingForEquation	(	string const &	fieldName,
		integer const	c
	)

Disable the global coupling for a given equation.

Parameters

[in]	fieldName	the name of the field
[in]	c	the index of the equation

◆ disableGlobalCouplingForEquations()

void geos::DofManager::disableGlobalCouplingForEquations	(	string const &	fieldName,
		arrayView1d< integer const > const	components
	)

Disable the global coupling for a set of equations.

Parameters

[in]	fieldName	the name of the field
[in]	components	the indices of the equations

◆ fieldExists()

bool geos::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 > geos::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& geos::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 geos::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 364 of file DofManager.hpp.

◆ globalOffset()

globalIndex geos::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()

FieldLocation geos::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 geos::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 geos::DofManager::numComponents ( ) const

Returns: number of dof components across all fields.

◆ numComponents() [2/2]

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

Returns: number of components in a given field.

Parameters

fieldName name of the field

◆ numComponentsPerField()

array1d< integer > geos::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 geos::DofManager::numGlobalDofs ( ) const

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

◆ numGlobalDofs() [2/2]

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

Returns: number of global dofs of a given field.

Parameters

fieldName the name of the field

◆ numLocalDofs() [1/2]

localIndex geos::DofManager::numLocalDofs ( ) const

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

◆ numLocalDofs() [2/2]

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

Returns: number of local dofs of a given field.

Parameters

fieldName name of the field

◆ operator=() [1/2]

DofManager& geos::DofManager::operator= ( DofManager && )

default

Defaulted move assignment.

Returns

◆ operator=() [2/2]

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

delete

Deleted copy assignment.

Returns

◆ printFieldInfo()

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

Print the summary of declared fields and coupling.

Parameters

os	output stream

◆ rankOffset() [1/2]

globalIndex geos::DofManager::rankOffset ( ) const

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

◆ rankOffset() [2/2]

globalIndex geos::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

◆ reorderByRank()

void geos::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 setDomain 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.

◆ setDomain()

void geos::DofManager::setDomain ( DomainPartition & domain )

Assign a domain.

Parameters

domain the target domain (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 domain 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.

◆ setLocalReorderingType()

void geos::DofManager::setLocalReorderingType	(	string const &	fieldName,
		LocalReorderingType const	reorderingType
	)

Set the local reodering of the dof numbers.

Parameters

[in]	fieldName	the name of the field
[in]	reorderingType	the reordering type

◆ setSparsityPattern()

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

Populate sparsity pattern of the entire system matrix.

Parameters

[out] pattern the target sparsity pattern

◆ setupFrom()

void geos::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

◆ LocalReorderingType

Constructor & Destructor Documentation

◆ DofManager()

Member Function Documentation

◆ addCoupling() [1/3]

◆ addCoupling() [2/3]

◆ addCoupling() [3/3]

◆ addField() [1/2]

◆ addField() [2/2]

◆ addFieldToVector()

◆ addVectorToField()

◆ copyFieldToVector()

◆ copyVectorToField()

◆ disableGlobalCouplingForEquation()

◆ disableGlobalCouplingForEquations()

◆ 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]

◆ reorderByRank()

◆ setDomain()

◆ setLocalReorderingType()

◆ setSparsityPattern()

◆ setupFrom()