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