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)
This commit is contained in:
2026-11-09 14:09:44 -05:00
parent d9c4919477
commit 6b57738330
32596 changed files with 4155414 additions and 0 deletions

View File

@@ -0,0 +1,339 @@
.TH "serif::discretization::backend::mfem::BasisEvaluation" 3 "Version v0.0.1a" "SERiF" \" -*- nroff -*-
.ad l
.nh
.SH NAME
serif::discretization::backend::mfem::BasisEvaluation \- Represents an element-local basis evaluation operator, supporting dense or tensor contractions, pointwise mappings, and transpose application\&.
.SH SYNOPSIS
.br
.PP
.PP
\fR#include <basis_evaluation\&.hpp>\fP
.SS "Public Member Functions"
.in +1c
.ti -1c
.RI "void \fBsample\fP (const ::mfem::FiniteElement &element, const ::mfem::IntegrationRule &rule, \fBReferenceOperation\fP operation, int copies, \fBTensorBasisCache\fP &cache, \fBContractionMode\fP mode, const \fBElementReconstruction\fP *reconstruction=nullptr)"
.br
.RI "Prepare basis values or derivatives at quadrature points using a dense matrix or tensor-product representation\&. "
.ti -1c
.RI "void \fBset_constant\fP (int points)"
.br
.RI "Set the basis evaluation to a constant basis with the given number of points\&. "
.ti -1c
.RI "void \fBreset_from\fP (const \fBBasisEvaluation\fP &reference, int components)"
.br
.RI "Allocate storage for a mapped basis using the reference's coefficient ordering and quadrature points\&. "
.ti -1c
.RI "template<typename MapT> void \fBmap_point\fP (int point, const \fBBasisEvaluation\fP &reference, MapT &&map, \fBBasisWorkspace\fP &workspace)"
.br
.RI "Apply a pointwise linear map to the reference basis or its geometry variation\&. "
.ti -1c
.RI "void \fBevaluate\fP (const ::mfem::Vector &coefficients, ::mfem::Vector &values, \fBBasisWorkspace\fP &workspace) const"
.br
.RI "Apply the basis to native coefficients; no integration weight is introduced\&. "
.ti -1c
.RI "void \fBevaluate_many\fP (const ::mfem::Vector &coefficients, ::mfem::Vector &values, int lanes, \fBBasisWorkspace\fP &workspace) const"
.br
.RI "\fBevaluate()\fP for several coefficient vectors stored lane-interleaved (entry i of lane j at i * lanes + j)\&. "
.ti -1c
.RI "void \fBintegrate\fP (const ::mfem::Vector &values, ::mfem::Vector &coefficients, \fBBasisWorkspace\fP &workspace) const"
.br
.RI "Apply the coordinate transpose to already weighted quadrature duals\&. "
.ti -1c
.RI "int \fBheight\fP () const noexcept"
.br
.RI "Number of flattened quadrature samples\&. "
.ti -1c
.RI "int \fBwidth\fP () const noexcept"
.br
.RI "Number of native element coefficients\&. "
.ti -1c
.RI "bool \fBuses_tensor\fP () const noexcept"
.br
.RI "Report whether contractions use verified Cartesian factors\&. "
.in -1c
.SS "Private Attributes"
.in +1c
.ti -1c
.RI "int \fBm_points\fP {0}"
.br
.RI "Number of quadrature points in the rule\&. "
.ti -1c
.RI "int \fBm_components\fP {0}"
.br
.RI "Number of output components per point\&. "
.ti -1c
.RI "int \fBm_width\fP {0}"
.br
.RI "Number of native element coefficients\&. "
.ti -1c
.RI "bool \fBm_identity_mapping\fP {false}"
.br
.RI "Canonical tensor samples need no pointwise mapping\&. "
.ti -1c
.RI "std::shared_ptr< const \fBTensorBasis\fP > \fBm_tensor\fP"
.br
.RI "Canonical tensor representation, when the tensor path is selected\&. "
.ti -1c
.RI "::mfem::DenseMatrix \fBm_dense\fP"
.br
.RI "Full evaluation matrix, including applied mappings, when the dense path is selected\&. "
.ti -1c
.RI "::mfem::DenseMatrix \fBm_mapping\fP"
.br
.RI "Stacked pointwise maps; canonical identity maps require no storage\&. "
.in -1c
.SH "Detailed Description"
.PP
Represents an element-local basis evaluation operator, supporting dense or tensor contractions, pointwise mappings, and transpose application\&.
Consider a scalar field represented on one finite element:
.PP
\[\rho_h(\xi) = \sum_{j=1}^{n} c_j \phi_j(\xi).
\]
.PP
Here, $c_{j}$ is a scalar coefficient, $\phi_{j}$ is its associated basis function, and $\xi$ is the canonical reference coordinate\&. The field is expressed in these coordinates through the element mapping\&.
.PP
For a quadrature rule with $N_{q}$ points, define the evaluation matrix $\mathbf{E}$ by
.PP
\[E_{qj} = \phi_j(\xi_q).
\]
.PP
$\mathbf{E}$ therefore has $N_{q}$ rows and $n$ columns\&. The field value at one point is
.PP
\[\rho_h(\xi_q) = \sum_{j=1}^{n} E_{qj} c_j.
\]
.PP
Collecting the samples into a vector gives
.PP
\[\boldsymbol{\rho}_h = \mathbf{E}\mathbf{c}.
\]
.PP
This class represents that linear operation without necessarily storing the full matrix $\mathbf{E}$: it can instead apply equivalent tensor contractions\&.
.PP
\fBExample\fP
.RS 4
Evaluate a constant scalar field on the reference cube, then compute its integral against each basis function\&.
.RE
.PP
.PP
.nf
namespace backend = serif::discretization::backend::mfem;
// First\-order nodal H1 basis on the reference cube\&.
::mfem::H1_HexahedronElement element(1);
const ::mfem::IntegrationRule& rule =
::mfem::IntRules\&.Get(::mfem::Geometry::CUBE, 2);
backend::TensorBasisCache cache;
backend::BasisWorkspace workspace;
backend::BasisEvaluation basis;
// Prepare E: one scalar basis value per quadrature point and DOF\&.
basis\&.sample(
element,
rule,
backend::ReferenceOperation::value,
1, // One copy of the scalar basis\&.
cache,
backend::ContractionMode::automatic
);
// For this nodal basis, equal coefficients represent a constant field\&.
::mfem::Vector coefficients(element\&.GetDof());
coefficients = 2\&.0;
// Compute values = E * coefficients\&.
// Every quadrature\-point value is approximately 2\&.0\&.
::mfem::Vector values;
basis\&.evaluate(coefficients, values, workspace);
// Supply quadrature weights explicitly: integrate does not add them\&.
::mfem::Vector weighted_values(rule\&.GetNPoints());
for (int q = 0; q < rule\&.GetNPoints(); ++q) {
weighted_values[q] = rule\&.IntPoint(q)\&.weight * values[q];
}
// Compute element_integrals = E^T * weighted_values\&.
::mfem::Vector element_integrals;
basis\&.integrate(weighted_values, element_integrals, workspace);
.fi
.PP
.PP
Each output entry approximates \[ \int_{\hat K} \phi_j(\xi)\rho_h(\xi)\,d\xi.
\] These are element-DOF integral contributions, not reconstructed field coefficients\&. Integration over a physical element additionally requires the appropriate volume Jacobian in the quadrature weights\&.
.SH "Member Function Documentation"
.PP
.SS "void serif::discretization::backend::mfem::BasisEvaluation::evaluate (const ::mfem::Vector & coefficients, ::mfem::Vector & values, \fBBasisWorkspace\fP & workspace) const"
.PP
Apply the basis to native coefficients; no integration weight is introduced\&.
.PP
\fBParameters\fP
.RS 4
\fIcoefficients\fP Input coefficients to apply the basis to\&.
.br
\fIvalues\fP Output values after applying the basis\&.
.br
\fIworkspace\fP Workspace to use for intermediate computations\&.
.RE
.PP
.SS "void serif::discretization::backend::mfem::BasisEvaluation::evaluate_many (const ::mfem::Vector & coefficients, ::mfem::Vector & values, int lanes, \fBBasisWorkspace\fP & workspace) const"
.PP
\fBevaluate()\fP for several coefficient vectors stored lane-interleaved (entry i of lane j at i * lanes + j)\&.
.PP
\fBNote\fP
.RS 4
Each lane's values equal \fBevaluate()\fP on that lane alone; the output is interleaved the same way\&.
.RE
.PP
.SS "int serif::discretization::backend::mfem::BasisEvaluation::height () const\fR [nodiscard]\fP, \fR [noexcept]\fP"
.PP
Number of flattened quadrature samples\&.
.SS "void serif::discretization::backend::mfem::BasisEvaluation::integrate (const ::mfem::Vector & values, ::mfem::Vector & coefficients, \fBBasisWorkspace\fP & workspace) const"
.PP
Apply the coordinate transpose to already weighted quadrature duals\&.
.PP
\fBParameters\fP
.RS 4
\fIvalues\fP Quadrature data with any required integration weights already applied\&.
.br
\fIcoefficients\fP Element-DOF contributions computed as E^T times values\&.
.br
\fIworkspace\fP Workspace to use for intermediate computations\&.
.RE
.PP
.SS "template<typename MapT> void serif::discretization::backend::mfem::BasisEvaluation::map_point (int point, const \fBBasisEvaluation\fP & reference, MapT && map, \fBBasisWorkspace\fP & workspace)"
.PP
Apply a pointwise linear map to the reference basis or its geometry variation\&.
.PP
\fBTemplate Parameters\fP
.RS 4
\fIMapT\fP Type of the mapping function to apply\&.
.RE
.PP
\fBParameters\fP
.RS 4
\fIpoint\fP Quadrature point index to apply the mapping at\&.
.br
\fIreference\fP Reference basis evaluation to map from\&.
.br
\fImap\fP Mapping function to apply\&.
.br
\fIworkspace\fP Reusable pointwise input and output buffers\&.
.RE
.PP
\fBPrecondition\fP
.RS 4
The mapping callback must be linear in its input and fill every output component\&.
.RE
.PP
.SS "void serif::discretization::backend::mfem::BasisEvaluation::reset_from (const \fBBasisEvaluation\fP & reference, int components)"
.PP
Allocate storage for a mapped basis using the reference's coefficient ordering and quadrature points\&.
.PP
\fBParameters\fP
.RS 4
\fIreference\fP Basis evaluation supplying the dimensions and any shared tensor representation\&.
.br
\fIcomponents\fP Number of output components per quadrature point\&.
.RE
.PP
\fBNote\fP
.RS 4
Populate the destination at every quadrature point using map_point before evaluation or transpose application\&.
.RE
.PP
.SS "void serif::discretization::backend::mfem::BasisEvaluation::sample (const ::mfem::FiniteElement & element, const ::mfem::IntegrationRule & rule, \fBReferenceOperation\fP operation, int copies, \fBTensorBasisCache\fP & cache, \fBContractionMode\fP mode, const \fBElementReconstruction\fP * reconstruction = \fRnullptr\fP)"
.PP
Prepare basis values or derivatives at quadrature points using a dense matrix or tensor-product representation\&.
.PP
\fBParameters\fP
.RS 4
\fIelement\fP Finite element to sample\&.
.br
\fIrule\fP Integration rule to use for sampling\&.
.br
\fIoperation\fP Reference operation to perform\&.
.br
\fIcopies\fP Number of independent copies of the finite-element basis; for example, three scalar basis copies for a vector H1 field\&.
.br
\fIcache\fP Tensor basis cache to use\&.
.br
\fImode\fP Contraction mode to use\&.
.RE
.PP
.SS "void serif::discretization::backend::mfem::BasisEvaluation::set_constant (int points)"
.PP
Set the basis evaluation to a constant basis with the given number of points\&.
.PP
\fBParameters\fP
.RS 4
\fIpoints\fP Number of quadrature points to use for the constant basis\&.
.RE
.PP
.SS "bool serif::discretization::backend::mfem::BasisEvaluation::uses_tensor () const\fR [nodiscard]\fP, \fR [noexcept]\fP"
.PP
Report whether contractions use verified Cartesian factors\&.
.SS "int serif::discretization::backend::mfem::BasisEvaluation::width () const\fR [nodiscard]\fP, \fR [noexcept]\fP"
.PP
Number of native element coefficients\&.
.SH "Member Data Documentation"
.PP
.SS "int serif::discretization::backend::mfem::BasisEvaluation::m_components {0}\fR [private]\fP"
.PP
Number of output components per point\&.
.SS "::mfem::DenseMatrix serif::discretization::backend::mfem::BasisEvaluation::m_dense\fR [private]\fP"
.PP
Full evaluation matrix, including applied mappings, when the dense path is selected\&.
.SS "bool serif::discretization::backend::mfem::BasisEvaluation::m_identity_mapping {false}\fR [private]\fP"
.PP
Canonical tensor samples need no pointwise mapping\&.
.SS "::mfem::DenseMatrix serif::discretization::backend::mfem::BasisEvaluation::m_mapping\fR [private]\fP"
.PP
Stacked pointwise maps; canonical identity maps require no storage\&.
.SS "int serif::discretization::backend::mfem::BasisEvaluation::m_points {0}\fR [private]\fP"
.PP
Number of quadrature points in the rule\&.
.SS "std::shared_ptr<const \fBTensorBasis\fP> serif::discretization::backend::mfem::BasisEvaluation::m_tensor\fR [private]\fP"
.PP
Canonical tensor representation, when the tensor path is selected\&.
.SS "int serif::discretization::backend::mfem::BasisEvaluation::m_width {0}\fR [private]\fP"
.PP
Number of native element coefficients\&.
.SH "Author"
.PP
Generated automatically by Doxygen for SERiF from the source code\&.