Emily Boudreaux
6b57738330
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)
250 lines
12 KiB
Groff
250 lines
12 KiB
Groff
.TH "serif::discretization::backend::mfem" 3 "Version v0.0.1a" "SERiF" \" -*- nroff -*-
|
|
.ad l
|
|
.nh
|
|
.SH NAME
|
|
serif::discretization::backend::mfem
|
|
.SH SYNOPSIS
|
|
.br
|
|
.PP
|
|
.SS "Namespaces"
|
|
|
|
.in +1c
|
|
.ti -1c
|
|
.RI "namespace \fBdetail\fP"
|
|
.br
|
|
.in -1c
|
|
.SS "Classes"
|
|
|
|
.in +1c
|
|
.ti -1c
|
|
.RI "class \fBBasisEvaluation\fP"
|
|
.br
|
|
.RI "Represents an element-local basis evaluation operator, supporting dense or tensor contractions, pointwise mappings, and transpose application\&. "
|
|
.ti -1c
|
|
.RI "struct \fBBasisWorkspace\fP"
|
|
.br
|
|
.RI "Reusable scratch storage for basis contractions, reducing repeated allocations\&. "
|
|
.ti -1c
|
|
.RI "struct \fBCoefficientTracking\fP"
|
|
.br
|
|
.RI "Track coefficient values using an owned snapshot and the identity of their binding\&. "
|
|
.ti -1c
|
|
.RI "class \fBDofMap\fP"
|
|
.br
|
|
.RI "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]\&. "
|
|
.ti -1c
|
|
.RI "class \fBDofSelection\fP"
|
|
.br
|
|
.RI "A selection of supported DOFs from a term binding, with boundary attribute information\&. The purpose here is to allow for the selection of a subset of DOFs from a term binding, such as those associated with a particular boundary, while still retaining the ability to validate the selection against the underlying mesh and term binding\&. "
|
|
.ti -1c
|
|
.RI "class \fBElementCoordinates\fP"
|
|
.br
|
|
.RI "One element's native orientation and its supported full/reduced coefficient coordinates\&. "
|
|
.ti -1c
|
|
.RI "struct \fBElementReconstruction\fP"
|
|
.br
|
|
.RI "An element's radial reconstruction; the enclosing plan owns its profile\&. "
|
|
.ti -1c
|
|
.RI "class \fBFieldValues\fP"
|
|
.br
|
|
.RI "Read a field using the same representation and mappings as its equation operators\&. "
|
|
.ti -1c
|
|
.RI "struct \fBOwnedBindings\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "struct \fBOwnedBindings< Context, utils::dependencies::KeyList< Keys\&.\&.\&. > >\fP"
|
|
.br
|
|
.RI "Keep typed bindings alive beside the resources they borrow; neither copying a configuration nor restoring it copies these resources\&. "
|
|
.ti -1c
|
|
.RI "class \fBReconstructionPlan\fP"
|
|
.br
|
|
.RI "Immutable reconstruction selected on material-side surface elements and validated against their interfaces\&. "
|
|
.ti -1c
|
|
.RI "struct \fBResources\fP"
|
|
.br
|
|
.RI "Own meshes and finite-element resources in reverse dependency order, for creation and archive restoration\&. "
|
|
.ti -1c
|
|
.RI "class \fBScalarBoundaryTrace\fP"
|
|
.br
|
|
.RI "An immutable scalar interpolation operator from supported coefficients to selected residual nodes\&. "
|
|
.ti -1c
|
|
.RI "class \fBTensorBasis\fP"
|
|
.br
|
|
.RI "A class that represents a tensor basis for a finite element\&. This class is used to evaluate the basis functions and their derivatives at a set of reference points\&. "
|
|
.ti -1c
|
|
.RI "class \fBTensorBasisCache\fP"
|
|
.br
|
|
.RI "Share immutable tensor plans within one operator; copied rules are keyed by their contents\&. "
|
|
.ti -1c
|
|
.RI "struct \fBTensorWorkspace\fP"
|
|
.br
|
|
.RI "A workspace for tensor contractions to avoid repeated allocations and pack memory (TODO: does this actual pack memory in a useful manner when using mfem vectors? Probably something to look into)\&. "
|
|
.ti -1c
|
|
.RI "class \fBTermBinding\fP"
|
|
.br
|
|
.RI "A runtime binding between a term descriptor and its MFEM finite-element space\&. This is used to project down the compile time term descriptors into runtime reinterpretations which can then be used to extract things like the list of dofs, the element support, and the mesh\&. Note that this is a child of \fBDofMap\fP, therefor all term bindings are also dof maps\&. "
|
|
.in -1c
|
|
.SS "Concepts"
|
|
|
|
.in +1c
|
|
.ti -1c
|
|
.RI "concept \fBBoundaryTraceTerm\fP"
|
|
.br
|
|
.RI "Concept Limiting the input term to either a global scalar term or a spatial term of rank 0 in the H1 family\&. Outside of H1, the trace is a vector (e\&.g\&. the normal trace for a H(div) field or the tangential trace for a H(curl) field)\&. Further, for higher rank H1 fields the trace is a tensor\&. "
|
|
.in -1c
|
|
.SS "Enumerations"
|
|
|
|
.in +1c
|
|
.ti -1c
|
|
.RI "enum class \fBReferenceOperation\fP { \fBvalue\fP, \fBgradient\fP, \fBvalue_and_gradient\fP }"
|
|
.br
|
|
.RI "Options enum to control what is actually evaluated at the reference points\&. "
|
|
.ti -1c
|
|
.RI "enum class \fBContractionMode\fP { \fBautomatic\fP, \fBdense\fP }"
|
|
.br
|
|
.RI "Options enum to control how the tensor contractions are performed\&. "
|
|
.in -1c
|
|
.SS "Functions"
|
|
|
|
.in +1c
|
|
.ti -1c
|
|
.RI "std::vector< int > \fBboundary_leaf_faces\fP (::mfem::Mesh &mesh, const int attribute)"
|
|
.br
|
|
.RI "Expand a selected coarse interface label onto its physical leaf faces, integrating each leaf once\&. "
|
|
.ti -1c
|
|
.RI "template<BoundaryTraceTerm TermT, domain::schema::IsSchema SchemaT> \fBScalarBoundaryTrace\fP \fBmake_boundary_trace\fP (std::shared_ptr< const \fBDofSelection\fP > rows, const \fBTermBinding\fP< TermT, SchemaT > &input)"
|
|
.br
|
|
.RI "Sample a continuous scalar field at the selected nodal H1 residual points\&. "
|
|
.ti -1c
|
|
.RI "template<BoundaryTraceTerm TermT, domain::schema::IsSchema SchemaT> \fBScalarBoundaryTrace\fP \fBmake_boundary_trace\fP (std::shared_ptr< const \fBDofSelection\fP >, \fBTermBinding\fP< TermT, SchemaT > &&)=delete"
|
|
.br
|
|
.RI "A trace borrows its input binding, so temporaries cannot supply its coefficient ordering\&. "
|
|
.ti -1c
|
|
.RI "template<BoundaryTraceTerm TermT, domain::schema::IsSchema SchemaT> \fBScalarBoundaryTrace\fP \fBmake_boundary_trace\fP (std::shared_ptr< const \fBDofSelection\fP >, const \fBTermBinding\fP< TermT, SchemaT > &&)=delete"
|
|
.br
|
|
.RI "Const temporary bindings have the same lifetime restriction\&. "
|
|
.ti -1c
|
|
.RI "template<domain::IsBoundary BoundaryT, blocks::SpatialTerm TermT, domain::schema::IsSchema SchemaT> \fBDofSelection\fP \fBselect_boundary_dofs\fP (const \fBTermBinding\fP< TermT, SchemaT > &binding)"
|
|
.br
|
|
.RI "Select DOFs associated with a particular boundary from a term binding\&. "
|
|
.ti -1c
|
|
.RI "template<blocks::SpatialTerm Term, domain::schema::IsSchema Schema> std::expected< std::vector< double >, std::string > \fBreference_mass_diagonal\fP (const \fBTermBinding\fP< Term, Schema > &binding)"
|
|
.br
|
|
.RI "Measure the supported coefficients in their reference finite-element geometry\&. "
|
|
.ti -1c
|
|
.RI "template<typename Term, typename Binding> std::shared_ptr< const \fBReconstructionPlan\fP > \fBmake_reconstruction\fP (const \fBreconstruction::SurfacePower\fP< Term > &specification, const Binding &binding)"
|
|
.br
|
|
.RI "Resolve a surface-power request against a typed binding before publishing the discretization\&. "
|
|
.in -1c
|
|
.SH "Enumeration Type Documentation"
|
|
.PP
|
|
.SS "enum class \fBserif::discretization::backend::mfem::ContractionMode\fP\fR [strong]\fP"
|
|
|
|
.PP
|
|
Options enum to control how the tensor contractions are performed\&.
|
|
.PP
|
|
\fBEnumerator\fP
|
|
.in +1c
|
|
.TP
|
|
\f(BIautomatic \fP
|
|
Automatically choose the contraction mode based on the number of points and dofs\&.
|
|
.TP
|
|
\f(BIdense \fP
|
|
Use a dense contraction mode\&.
|
|
.SS "enum class \fBserif::discretization::backend::mfem::ReferenceOperation\fP\fR [strong]\fP"
|
|
|
|
.PP
|
|
Options enum to control what is actually evaluated at the reference points\&.
|
|
.PP
|
|
\fBEnumerator\fP
|
|
.in +1c
|
|
.TP
|
|
\f(BIvalue \fP
|
|
Evaluate the basis functions at the reference points\&.
|
|
.TP
|
|
\f(BIgradient \fP
|
|
Evaluate the gradients of the basis functions at the reference points\&.
|
|
.TP
|
|
\f(BIvalue_and_gradient \fP
|
|
Evaluate both the basis functions and their gradients at the reference points\&.
|
|
.SH "Function Documentation"
|
|
.PP
|
|
.SS "std::vector< int > serif::discretization::backend::mfem::boundary_leaf_faces (::mfem::Mesh & mesh, const int attribute)\fR [inline]\fP, \fR [nodiscard]\fP"
|
|
|
|
.PP
|
|
Expand a selected coarse interface label onto its physical leaf faces, integrating each leaf once\&.
|
|
.SS "template<BoundaryTraceTerm TermT, domain::schema::IsSchema SchemaT> \fBScalarBoundaryTrace\fP serif::discretization::backend::mfem::make_boundary_trace (std::shared_ptr< const \fBDofSelection\fP > rows, const \fBTermBinding\fP< TermT, SchemaT > & input)\fR [nodiscard]\fP"
|
|
|
|
.PP
|
|
Sample a continuous scalar field at the selected nodal H1 residual points\&.
|
|
.PP
|
|
\fBNote\fP
|
|
.RS 4
|
|
Input and residual spaces may have different orders and numbering but must share a mesh\&. Discontinuous fields require an explicit physical trace convention and are intentionally excluded\&.
|
|
.RE
|
|
.PP
|
|
|
|
.SS "template<BoundaryTraceTerm TermT, domain::schema::IsSchema SchemaT> \fBScalarBoundaryTrace\fP serif::discretization::backend::mfem::make_boundary_trace (std::shared_ptr< const \fBDofSelection\fP > , const \fBTermBinding\fP< TermT, SchemaT > && )\fR [delete]\fP"
|
|
|
|
.PP
|
|
Const temporary bindings have the same lifetime restriction\&.
|
|
.SS "template<BoundaryTraceTerm TermT, domain::schema::IsSchema SchemaT> \fBScalarBoundaryTrace\fP serif::discretization::backend::mfem::make_boundary_trace (std::shared_ptr< const \fBDofSelection\fP > , \fBTermBinding\fP< TermT, SchemaT > && )\fR [delete]\fP"
|
|
|
|
.PP
|
|
A trace borrows its input binding, so temporaries cannot supply its coefficient ordering\&.
|
|
.SS "template<typename Term, typename Binding> std::shared_ptr< const \fBReconstructionPlan\fP > serif::discretization::backend::mfem::make_reconstruction (const \fBreconstruction::SurfacePower\fP< Term > & specification, const Binding & binding)\fR [nodiscard]\fP"
|
|
|
|
.PP
|
|
Resolve a surface-power request against a typed binding before publishing the discretization\&.
|
|
.PP
|
|
\fBNote\fP
|
|
.RS 4
|
|
Other forms add an ADL-visible make_reconstruction(specification, binding) overload returning an immutable \fBReconstructionPlan\fP\&. Unsupported fields must report a SERiF error in that overload\&.
|
|
.RE
|
|
.PP
|
|
|
|
.SS "template<blocks::SpatialTerm Term, domain::schema::IsSchema Schema> std::expected< std::vector< double >, std::string > serif::discretization::backend::mfem::reference_mass_diagonal (const \fBTermBinding\fP< Term, Schema > & binding)\fR [nodiscard]\fP"
|
|
|
|
.PP
|
|
Measure the supported coefficients in their reference finite-element geometry\&.
|
|
.PP
|
|
\fBReturns\fP
|
|
.RS 4
|
|
The exact mass-matrix diagonal in the binding's reduced ordering, or an invalid-metric diagnostic\&.
|
|
.RE
|
|
.PP
|
|
\fBNote\fP
|
|
.RS 4
|
|
The binding must remain current\&. Coordinates belong to the reference mesh, not a trial deformation\&.
|
|
.RE
|
|
.PP
|
|
|
|
.SS "template<domain::IsBoundary BoundaryT, blocks::SpatialTerm TermT, domain::schema::IsSchema SchemaT> \fBDofSelection\fP serif::discretization::backend::mfem::select_boundary_dofs (const \fBTermBinding\fP< TermT, SchemaT > & binding)\fR [nodiscard]\fP"
|
|
|
|
.PP
|
|
Select DOFs associated with a particular boundary from a term binding\&.
|
|
.PP
|
|
\fBTemplate Parameters\fP
|
|
.RS 4
|
|
\fIBoundaryT\fP The boundary type to select\&. This must be a valid boundary in the domain schema of the term binding\&.
|
|
.br
|
|
\fITermT\fP The term type of the term binding\&. This must be a valid term type in the domain schema of the term binding\&. (e\&.g\&. something like Density)
|
|
.br
|
|
\fISchemaT\fP The domain schema type of the term binding\&. This must be a valid domain schema type that contains the specified boundary\&.
|
|
.RE
|
|
.PP
|
|
\fBParameters\fP
|
|
.RS 4
|
|
\fIbinding\fP The term binding from which to select DOFs\&. This must outlive the returned DOF selection\&.
|
|
.RE
|
|
.PP
|
|
\fBReturns\fP
|
|
.RS 4
|
|
A \fBDofSelection\fP object representing the selected DOFs associated with the specified boundary\&.
|
|
.RE
|
|
.PP
|
|
|
|
.SH "Author"
|
|
.PP
|
|
Generated automatically by Doxygen for SERiF from the source code\&.
|