Files
MeanField_SERiF/docs/man/man3/serif_discretization_backend_mfem_DofMap.3
Emily Boudreaux 6b57738330 docs(docs): built docs
Note for now much of the docs is LLM written. This was done to save time and focus on code development. The docs have been LOOSLEY reviewed. However, the code itself has been either fully written by hand or fully reviewed. Therefore, the docs should at the moment be seen as a loose resource rather than authoratiative (and this is on top of the general ability for docs to drift)
2026-11-09 14:09:44 -05:00

523 lines
20 KiB
Groff

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