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

340 lines
12 KiB
Groff
Raw Permalink Normal View History

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