Files
MeanField_SERiF/docs/man/man3/serif_discretization_backend_mfem_DofMap.3

523 lines
20 KiB
Groff
Raw Normal View History

.TH "serif::discretization::backend::mfem::DofMap" 3 "Version v0.0.1a" "SERiF" \" -*- nroff -*-
.ad l
.nh
.SH NAME
serif::discretization::backend::mfem::DofMap \- A mapping from a full MFEM finite-element space to a reduced set of DOFs that are supporter by the given element support\&. That is to say that if one has some set of dofs D (perhaps it looks like [0, 1, 2, 3, 4] as a hypothetical) and dofs 0, 2, and 4 are associated to domain A while 1 and 3 are associated to domain B\&. Then if one were to construct a \fBDofMap\fP with element support [1, 0, 1, 0, 1] (where 1 indicates that the element is supported and 0 indicates that it is not) then the reduced dof map would be [0, 2, 4] and the full to reduced map would be [-1, -1, 0, -1, 1]\&.
.SH SYNOPSIS
.br
.PP
.PP
\fR#include <dof_map\&.hpp>\fP
.PP
Inherited by \fBserif::discretization::backend::mfem::TermBinding< Closure::Test, Schema >\fP, \fBserif::discretization::backend::mfem::TermBinding< TestT, SchemaT >\fP, \fBserif::discretization::backend::mfem::TermBinding< discretization::blocks::displacement::vector, SchemaT >\fP, and \fBserif::discretization::backend::mfem::TermBinding< TermT, SchemaT >\fP\&.
.SS "Classes"
.in +1c
.ti -1c
.RI "class \fBElements\fP"
.br
.RI "Borrow element access for one traversal after checking the complete binding\&. "
.in -1c
.SS "Public Member Functions"
.in +1c
.ti -1c
.RI "\fBElements\fP \fBvalidated_elements\fP () const"
.br
.RI "Validate once before traversing elements without repeated mesh-wide scans\&. "
.ti -1c
.RI "const std::shared_ptr< const \fBReconstructionPlan\fP > & \fBreconstruction\fP () const noexcept"
.br
.RI "Read the immutable physical-field representation retained by this binding\&. "
.ti -1c
.RI "const \fBElementReconstruction\fP * \fBreconstruction_element\fP (int element) const"
.br
.RI "Select the reference adapter without adding work to ordinary elements\&. "
.ti -1c
.RI "\fBDofMap\fP (const \fBDofMap\fP &)=delete"
.br
.ti -1c
.RI "\fBDofMap\fP & \fBoperator=\fP (const \fBDofMap\fP &)=delete"
.br
.ti -1c
.RI "\fBDofMap\fP (\fBDofMap\fP &&)=delete"
.br
.ti -1c
.RI "\fBDofMap\fP & \fBoperator=\fP (\fBDofMap\fP &&)=delete"
.br
.ti -1c
.RI "::mfem::FiniteElementSpace & \fBspace\fP () const"
.br
.RI "Return the borrowed finite-element space associated with this DOF map\&. "
.ti -1c
.RI "::mfem::Mesh & \fBmesh\fP () const noexcept"
.br
.RI "Return the borrowed mesh associated with this DOF map\&. "
.ti -1c
.RI "int \fBfull_size\fP () const noexcept"
.br
.RI "Return the number of full-space DOFs, including those not supported by the element support\&. "
.ti -1c
.RI "int \fBsize\fP () const noexcept"
.br
.RI "Return the number of supported DOFs, which is the size of the reduced coefficient vector\&. "
.ti -1c
.RI "std::optional< int > \fBreduced_dof\fP (const int \fBfull_dof\fP) const"
.br
.RI "Locate a local coefficient represented by exactly one supported independent coordinate\&. "
.ti -1c
.RI "int \fBfull_dof\fP (const int reduced) const"
.br
.RI "Return the representative local coefficient selected for one supported independent coordinate\&. "
.ti -1c
.RI "bool \fBconstrained\fP () const noexcept"
.br
.RI "Report whether local coefficients require hanging-node interpolation\&. "
.ti -1c
.RI "int \fBtrue_size\fP () const noexcept"
.br
.RI "Return the full independent coordinate count before selecting material support\&. "
.ti -1c
.RI "template<typename Visitor> void \fBfor_each_coefficient\fP (const int local_dof, Visitor &&visit) const"
.br
.RI "Visit the supported independent coefficients contributing to one unsigned local DOF\&. "
.ti -1c
.RI "::mfem::Vector \fBgather_true\fP (const ::mfem::Vector &values) const"
.br
.RI "Select supported coefficients from a full independent vector, without interpolation\&. "
.ti -1c
.RI "::mfem::Vector \fBscatter_true\fP (const ::mfem::Vector &values) const"
.br
.RI "Expand supported coefficients into a full independent vector, without interpolation\&. "
.ti -1c
.RI "::mfem::Vector \fBaccumulate_dual\fP (const ::mfem::Vector &full) const"
.br
.RI "Accumulate local dual contributions with the transpose of coefficient expansion\&. "
.ti -1c
.RI "void \fBaccumulate_dual\fP (const ::mfem::Vector &full, ::mfem::Vector &result) const"
.br
.RI "Accumulate local dual contributions while reusing caller storage\&. "
.ti -1c
.RI "bool \fBsupports\fP (const int element) const"
.br
.RI "Check whether an element is supported by this dof map\&. "
.ti -1c
.RI "void \fBvalidate\fP () const"
.br
.RI "Validate the dof map\&. "
.ti -1c
.RI "void \fBvalidate_values\fP (const ::mfem::Vector &values) const"
.br
.RI "Check supported coefficient count and finiteness\&. "
.ti -1c
.RI "::mfem::Vector \fBgather\fP (const ::mfem::Vector &full) const"
.br
.RI "Restrict a full coefficient vector to supported DOFs\&. "
.ti -1c
.RI "void \fBgather\fP (const ::mfem::Vector &full, ::mfem::Vector &result) const"
.br
.RI "Restrict supported coefficients while reusing the destination allocation\&. "
.ti -1c
.RI "::mfem::Vector \fBscatter\fP (const ::mfem::Vector &reduced) const"
.br
.RI "Expand supported independent coefficients into the constrained local field\&. Unsupported independent coordinates are zero\&. Interpolation can populate local coordinates outside the supported elements; element support still controls physical integration\&. "
.ti -1c
.RI "void \fBelement_values\fP (int element, const ::mfem::Vector &reduced, ::mfem::Vector &values) const"
.br
.RI "Extract element coefficients, including primal orientation transforms\&. "
.ti -1c
.RI "void \fBadd_element\fP (int element, ::mfem::Vector &values, ::mfem::Vector &full) const"
.br
.RI "Apply dual orientation transforms and add an element residual\&. "
.in -1c
.SS "Protected Member Functions"
.in +1c
.ti -1c
.RI "\fBDofMap\fP (::mfem::FiniteElementSpace &\fBspace\fP, const ::mfem::Array< int > &element_support, std::shared_ptr< const \fBReconstructionPlan\fP > \fBreconstruction\fP={})"
.br
.ti -1c
.RI "\fBDofMap\fP (::mfem::Mesh &\fBmesh\fP, const ::mfem::Array< int > &element_support)"
.br
.ti -1c
.RI "\fB~DofMap\fP ()=default"
.br
.in -1c
.SS "Private Member Functions"
.in +1c
.ti -1c
.RI "void \fBbuild_constrained_map\fP ()"
.br
.RI "Close material support over hanging-node dependencies and retain independent coordinates\&. "
.ti -1c
.RI "void \fBvalidate_structure\fP () const"
.br
.RI "Check borrowed resource revisions in constant time before accessing their arrays\&. "
.in -1c
.SS "Private Attributes"
.in +1c
.ti -1c
.RI "::mfem::FiniteElementSpace * \fBm_space\fP"
.br
.RI "Borrowed pointer to the finite-element space associated with this dof map, or nullptr for a global scalar\&. This must outlive this class\&. "
.ti -1c
.RI "::mfem::Mesh & \fBm_mesh\fP"
.br
.RI "Borrowed reference to the mesh associated with this dof map\&. This must outlive this class\&. "
.ti -1c
.RI "long \fBm_space_sequence\fP"
.br
.RI "Sequence number of the finite-element space at construction, or -1 for a global scalar\&. "
.ti -1c
.RI "long \fBm_mesh_sequence\fP"
.br
.RI "Sequence number of the mesh at construction\&. "
.ti -1c
.RI "::mfem::Array< int > \fBm_attributes\fP"
.br
.RI "Array of attribute indices associated with this dof map\&. "
.ti -1c
.RI "::mfem::Array< int > \fBm_element_support\fP"
.br
.RI "Array of 0/1 values indicating whether each element is supported by this dof map\&. "
.ti -1c
.RI "const ::mfem::SparseMatrix * \fBm_prolongation\fP {nullptr}"
.br
.RI "Borrowed constraint matrix, guarded by the space revision\&. "
.ti -1c
.RI "::mfem::Array< int > \fBm_true_to_reduced\fP"
.br
.RI "Independent coordinate to supported coordinate\&. "
.ti -1c
.RI "::mfem::Array< int > \fBm_reduced_to_true\fP"
.br
.RI "Supported coordinate to independent coordinate\&. "
.ti -1c
.RI "::mfem::Array< int > \fBm_reduced_to_full\fP"
.br
.RI "Mapping from reduced to full degrees of freedom\&. "
.ti -1c
.RI "::mfem::Array< int > \fBm_full_to_reduced\fP"
.br
.RI "Mapping from full to reduced degrees of freedom\&. "
.ti -1c
.RI "std::optional<::mfem::Array< int > > \fBm_boundary_attributes\fP"
.br
.RI "Reconstructed bindings depend on boundary labels\&. "
.ti -1c
.RI "std::shared_ptr< const \fBReconstructionPlan\fP > \fBm_reconstruction\fP"
.br
.RI "Immutable; a different representation requires a new binding\&. "
.in -1c
.SS "Friends"
.in +1c
.ti -1c
.RI "class \fBElementCoordinates\fP"
.br
.in -1c
.SH "Detailed Description"
.PP
A mapping from a full MFEM finite-element space to a reduced set of DOFs that are supporter by the given element support\&. That is to say that if one has some set of dofs D (perhaps it looks like [0, 1, 2, 3, 4] as a hypothetical) and dofs 0, 2, and 4 are associated to domain A while 1 and 3 are associated to domain B\&. Then if one were to construct a \fBDofMap\fP with element support [1, 0, 1, 0, 1] (where 1 indicates that the element is supported and 0 indicates that it is not) then the reduced dof map would be [0, 2, 4] and the full to reduced map would be [-1, -1, 0, -1, 1]\&.
.PP
\fBNote\fP
.RS 4
Solver coordinates are supported independent (true) DOFs\&. Element coefficients include hanging-node interpolation\&. Coefficient restriction and dual accumulation are separate operations\&. Distributed spaces are not supported\&.
.RE
.PP
.SH "Constructor & Destructor Documentation"
.PP
.SS "serif::discretization::backend::mfem::DofMap::DofMap (::mfem::FiniteElementSpace & space, const ::mfem::Array< int > & element_support, std::shared_ptr< const \fBReconstructionPlan\fP > reconstruction = \fR{}\fP)\fR [inline]\fP, \fR [protected]\fP"
.SS "serif::discretization::backend::mfem::DofMap::DofMap (::mfem::Mesh & mesh, const ::mfem::Array< int > & element_support)\fR [inline]\fP, \fR [protected]\fP"
.SS "serif::discretization::backend::mfem::DofMap::~DofMap ()\fR [protected]\fP, \fR [default]\fP"
.SS "serif::discretization::backend::mfem::DofMap::DofMap (const \fBDofMap\fP & )\fR [delete]\fP"
.SS "serif::discretization::backend::mfem::DofMap::DofMap (\fBDofMap\fP && )\fR [delete]\fP"
.SH "Member Function Documentation"
.PP
.SS "::mfem::Vector serif::discretization::backend::mfem::DofMap::accumulate_dual (const ::mfem::Vector & full) const\fR [inline]\fP, \fR [nodiscard]\fP"
.PP
Accumulate local dual contributions with the transpose of coefficient expansion\&.
.SS "void serif::discretization::backend::mfem::DofMap::accumulate_dual (const ::mfem::Vector & full, ::mfem::Vector & result) const\fR [inline]\fP"
.PP
Accumulate local dual contributions while reusing caller storage\&.
.SS "void serif::discretization::backend::mfem::DofMap::add_element (int element, ::mfem::Vector & values, ::mfem::Vector & full) const"
.PP
Apply dual orientation transforms and add an element residual\&.
.PP
\fBParameters\fP
.RS 4
\fIelement\fP element index
.br
\fIvalues\fP vector of element coefficients
.br
\fIfull\fP full coefficient vector to which the element residual will be added
.RE
.PP
.SS "void serif::discretization::backend::mfem::DofMap::build_constrained_map ()\fR [inline]\fP, \fR [private]\fP"
.PP
Close material support over hanging-node dependencies and retain independent coordinates\&.
.SS "bool serif::discretization::backend::mfem::DofMap::constrained () const\fR [inline]\fP, \fR [nodiscard]\fP, \fR [noexcept]\fP"
.PP
Report whether local coefficients require hanging-node interpolation\&.
.SS "void serif::discretization::backend::mfem::DofMap::element_values (int element, const ::mfem::Vector & reduced, ::mfem::Vector & values) const"
.PP
Extract element coefficients, including primal orientation transforms\&.
.PP
\fBParameters\fP
.RS 4
\fIelement\fP element index
.br
\fIreduced\fP vector of supported coefficients
.br
\fIvalues\fP vector to store extracted element coefficients
.RE
.PP
.SS "template<typename Visitor> void serif::discretization::backend::mfem::DofMap::for_each_coefficient (const int local_dof, Visitor && visit) const\fR [inline]\fP"
.PP
Visit the supported independent coefficients contributing to one unsigned local DOF\&.
.SS "int serif::discretization::backend::mfem::DofMap::full_dof (const int reduced) const\fR [inline]\fP, \fR [nodiscard]\fP"
.PP
Return the representative local coefficient selected for one supported independent coordinate\&.
.SS "int serif::discretization::backend::mfem::DofMap::full_size () const\fR [inline]\fP, \fR [nodiscard]\fP, \fR [noexcept]\fP"
.PP
Return the number of full-space DOFs, including those not supported by the element support\&.
.PP
\fBReturns\fP
.RS 4
The number of full-space DOFs (not reduced by element support)
.RE
.PP
.SS "::mfem::Vector serif::discretization::backend::mfem::DofMap::gather (const ::mfem::Vector & full) const\fR [inline]\fP, \fR [nodiscard]\fP"
.PP
Restrict a full coefficient vector to supported DOFs\&.
.PP
\fBParameters\fP
.RS 4
\fIfull\fP full coefficient vector
.RE
.PP
\fBReturns\fP
.RS 4
vector of supported coefficients
.RE
.PP
.SS "void serif::discretization::backend::mfem::DofMap::gather (const ::mfem::Vector & full, ::mfem::Vector & result) const\fR [inline]\fP"
.PP
Restrict supported coefficients while reusing the destination allocation\&.
.SS "::mfem::Vector serif::discretization::backend::mfem::DofMap::gather_true (const ::mfem::Vector & values) const\fR [inline]\fP, \fR [nodiscard]\fP"
.PP
Select supported coefficients from a full independent vector, without interpolation\&.
.SS "::mfem::Mesh & serif::discretization::backend::mfem::DofMap::mesh () const\fR [inline]\fP, \fR [nodiscard]\fP, \fR [noexcept]\fP"
.PP
Return the borrowed mesh associated with this DOF map\&.
.PP
\fBReturns\fP
.RS 4
A reference to the mesh in m_mesh
.RE
.PP
.SS "\fBDofMap\fP & serif::discretization::backend::mfem::DofMap::operator= (const \fBDofMap\fP & )\fR [delete]\fP"
.SS "\fBDofMap\fP & serif::discretization::backend::mfem::DofMap::operator= (\fBDofMap\fP && )\fR [delete]\fP"
.SS "const std::shared_ptr< const \fBReconstructionPlan\fP > & serif::discretization::backend::mfem::DofMap::reconstruction () const\fR [inline]\fP, \fR [nodiscard]\fP, \fR [noexcept]\fP"
.PP
Read the immutable physical-field representation retained by this binding\&.
.SS "const \fBElementReconstruction\fP * serif::discretization::backend::mfem::DofMap::reconstruction_element (int element) const\fR [inline]\fP, \fR [nodiscard]\fP"
.PP
Select the reference adapter without adding work to ordinary elements\&.
.SS "std::optional< int > serif::discretization::backend::mfem::DofMap::reduced_dof (const int full_dof) const\fR [inline]\fP, \fR [nodiscard]\fP"
.PP
Locate a local coefficient represented by exactly one supported independent coordinate\&.
.PP
\fBParameters\fP
.RS 4
\fIfull_dof\fP index of the dof in the full space
.RE
.PP
\fBReturns\fP
.RS 4
An optional index of the dof in the reduced space, or std::nullopt for an unsupported or weighted hanging coefficient\&.
.RE
.PP
.SS "::mfem::Vector serif::discretization::backend::mfem::DofMap::scatter (const ::mfem::Vector & reduced) const\fR [inline]\fP, \fR [nodiscard]\fP"
.PP
Expand supported independent coefficients into the constrained local field\&. Unsupported independent coordinates are zero\&. Interpolation can populate local coordinates outside the supported elements; element support still controls physical integration\&.
.PP
\fBParameters\fP
.RS 4
\fIreduced\fP vector of supported coefficients
.RE
.PP
\fBReturns\fP
.RS 4
full local coefficient vector satisfying hanging-node interpolation
.RE
.PP
.SS "::mfem::Vector serif::discretization::backend::mfem::DofMap::scatter_true (const ::mfem::Vector & values) const\fR [inline]\fP, \fR [nodiscard]\fP"
.PP
Expand supported coefficients into a full independent vector, without interpolation\&.
.SS "int serif::discretization::backend::mfem::DofMap::size () const\fR [inline]\fP, \fR [nodiscard]\fP, \fR [noexcept]\fP"
.PP
Return the number of supported DOFs, which is the size of the reduced coefficient vector\&.
.PP
\fBReturns\fP
.RS 4
The number of supported DOFs (reduced by element support)
.RE
.PP
.SS "::mfem::FiniteElementSpace & serif::discretization::backend::mfem::DofMap::space () const\fR [inline]\fP, \fR [nodiscard]\fP"
.PP
Return the borrowed finite-element space associated with this DOF map\&.
.PP
\fBReturns\fP
.RS 4
A reference to the finite-element space in m_space
.RE
.PP
.SS "bool serif::discretization::backend::mfem::DofMap::supports (const int element) const\fR [inline]\fP, \fR [nodiscard]\fP"
.PP
Check whether an element is supported by this dof map\&.
.PP
\fBParameters\fP
.RS 4
\fIelement\fP element index
.RE
.PP
\fBReturns\fP
.RS 4
true if element is supported by this dof map, false otherwise
.RE
.PP
.SS "int serif::discretization::backend::mfem::DofMap::true_size () const\fR [inline]\fP, \fR [nodiscard]\fP, \fR [noexcept]\fP"
.PP
Return the full independent coordinate count before selecting material support\&.
.SS "void serif::discretization::backend::mfem::DofMap::validate () const\fR [inline]\fP"
.PP
Validate the dof map\&.
.SS "void serif::discretization::backend::mfem::DofMap::validate_structure () const\fR [inline]\fP, \fR [private]\fP"
.PP
Check borrowed resource revisions in constant time before accessing their arrays\&.
.SS "void serif::discretization::backend::mfem::DofMap::validate_values (const ::mfem::Vector & values) const\fR [inline]\fP"
.PP
Check supported coefficient count and finiteness\&.
.PP
\fBParameters\fP
.RS 4
\fIvalues\fP vector of coefficients to validate
.RE
.PP
.SS "\fBElements\fP serif::discretization::backend::mfem::DofMap::validated_elements () const\fR [inline]\fP, \fR [nodiscard]\fP"
.PP
Validate once before traversing elements without repeated mesh-wide scans\&.
.SH "Friends And Related Symbol Documentation"
.PP
.SS "friend class \fBElementCoordinates\fP\fR [friend]\fP"
.SH "Member Data Documentation"
.PP
.SS "::mfem::Array<int> serif::discretization::backend::mfem::DofMap::m_attributes\fR [private]\fP"
.PP
Array of attribute indices associated with this dof map\&.
.SS "std::optional<::mfem::Array<int> > serif::discretization::backend::mfem::DofMap::m_boundary_attributes\fR [private]\fP"
.PP
Reconstructed bindings depend on boundary labels\&.
.SS "::mfem::Array<int> serif::discretization::backend::mfem::DofMap::m_element_support\fR [private]\fP"
.PP
Array of 0/1 values indicating whether each element is supported by this dof map\&.
.SS "::mfem::Array<int> serif::discretization::backend::mfem::DofMap::m_full_to_reduced\fR [private]\fP"
.PP
Mapping from full to reduced degrees of freedom\&.
.SS "::mfem::Mesh& serif::discretization::backend::mfem::DofMap::m_mesh\fR [private]\fP"
.PP
Borrowed reference to the mesh associated with this dof map\&. This must outlive this class\&.
.SS "long serif::discretization::backend::mfem::DofMap::m_mesh_sequence\fR [private]\fP"
.PP
Sequence number of the mesh at construction\&.
.SS "const ::mfem::SparseMatrix* serif::discretization::backend::mfem::DofMap::m_prolongation {nullptr}\fR [private]\fP"
.PP
Borrowed constraint matrix, guarded by the space revision\&.
.SS "std::shared_ptr<const \fBReconstructionPlan\fP> serif::discretization::backend::mfem::DofMap::m_reconstruction\fR [private]\fP"
.PP
Immutable; a different representation requires a new binding\&.
.SS "::mfem::Array<int> serif::discretization::backend::mfem::DofMap::m_reduced_to_full\fR [private]\fP"
.PP
Mapping from reduced to full degrees of freedom\&.
.SS "::mfem::Array<int> serif::discretization::backend::mfem::DofMap::m_reduced_to_true\fR [private]\fP"
.PP
Supported coordinate to independent coordinate\&.
.SS "::mfem::FiniteElementSpace* serif::discretization::backend::mfem::DofMap::m_space\fR [private]\fP"
.PP
Borrowed pointer to the finite-element space associated with this dof map, or nullptr for a global scalar\&. This must outlive this class\&.
.SS "long serif::discretization::backend::mfem::DofMap::m_space_sequence\fR [private]\fP"
.PP
Sequence number of the finite-element space at construction, or -1 for a global scalar\&.
.SS "::mfem::Array<int> serif::discretization::backend::mfem::DofMap::m_true_to_reduced\fR [private]\fP"
.PP
Independent coordinate to supported coordinate\&.
.SH "Author"
.PP
Generated automatically by Doxygen for SERiF from the source code\&.