serif::operators::backend::mfem::BasisEvaluation Class Reference

Represents an element-local basis evaluation operator, supporting dense or tensor contractions, pointwise mappings, and transpose application. More...

#include <basis_evaluation.hpp>

Collaboration diagram for serif::operators::backend::mfem::BasisEvaluation:

Public Member Functions
void	sample (const ::mfem::FiniteElement &element, const ::mfem::IntegrationRule &rule, ReferenceOperation operation, int copies, TensorBasisCache &cache, ContractionMode mode, const ElementReconstruction *reconstruction=nullptr)
	Prepare basis values or derivatives at quadrature points using a dense matrix or tensor-product representation.
void	set_constant (int points)
	Set the basis evaluation to a constant basis with the given number of points.
void	reset_from (const BasisEvaluation &reference, int components)
	Allocate storage for a mapped basis using the reference's coefficient ordering and quadrature points.
template<typename MapT>
void	map_point (int point, const BasisEvaluation &reference, MapT &&map, BasisWorkspace &workspace)
	Apply a pointwise linear map to the reference basis or its geometry variation.
void	evaluate (const ::mfem::Vector &coefficients, ::mfem::Vector &values, BasisWorkspace &workspace) const
	Apply the basis to native coefficients; no integration weight is introduced.
void	evaluate_many (const ::mfem::Vector &coefficients, ::mfem::Vector &values, int lanes, BasisWorkspace &workspace) const
	evaluate() for several coefficient vectors stored lane-interleaved (entry i of lane j at i * lanes + j).
void	integrate (const ::mfem::Vector &values, ::mfem::Vector &coefficients, BasisWorkspace &workspace) const
	Apply the coordinate transpose to already weighted quadrature duals.
int	height () const noexcept
	Number of flattened quadrature samples.
int	width () const noexcept
	Number of native element coefficients.
bool	uses_tensor () const noexcept
	Report whether contractions use verified Cartesian factors.

Private Attributes
int	m_points {0}
	Number of quadrature points in the rule.
int	m_components {0}
	Number of output components per point.
int	m_width {0}
	Number of native element coefficients.
bool	m_identity_mapping {false}
	Canonical tensor samples need no pointwise mapping.
std::shared_ptr< const TensorBasis >	m_tensor
	Canonical tensor representation, when the tensor path is selected.
::mfem::DenseMatrix	m_dense
	Full evaluation matrix, including applied mappings, when the dense path is selected.
::mfem::DenseMatrix	m_mapping
	Stacked pointwise maps; canonical identity maps require no storage.

Detailed Description

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:

\[\rho_h(\xi) = \sum_{j=1}^{n} c_j \phi_j(\xi). \]

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.

For a quadrature rule with \(N_{q}\) points, define the evaluation matrix \(\mathbf{E}\) by

\[E_{qj} = \phi_j(\xi_q). \]

\(\mathbf{E}\) therefore has \(N_{q}\) rows and \(n\) columns. The field value at one point is

\[\rho_h(\xi_q) = \sum_{j=1}^{n} E_{qj} c_j. \]

Collecting the samples into a vector gives

\[\boldsymbol{\rho}_h = \mathbf{E}\mathbf{c}. \]

This class represents that linear operation without necessarily storing the full matrix \(\mathbf{E}\): it can instead apply equivalent tensor contractions.

Example

Evaluate a constant scalar field on the reference cube, then compute its integral against each basis function.

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);

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.

Member Function Documentation

evaluate()

void serif::discretization::backend::mfem::BasisEvaluation::evaluate	(	const ::mfem::Vector &	coefficients,
		::mfem::Vector &	values,
		BasisWorkspace &	workspace ) const

Apply the basis to native coefficients; no integration weight is introduced.

Parameters

coefficients	Input coefficients to apply the basis to.
values	Output values after applying the basis.
workspace	Workspace to use for intermediate computations.

evaluate_many()

void serif::discretization::backend::mfem::BasisEvaluation::evaluate_many	(	const ::mfem::Vector &	coefficients,
		::mfem::Vector &	values,
		int	lanes,
		BasisWorkspace &	workspace ) const

evaluate() for several coefficient vectors stored lane-interleaved (entry i of lane j at i * lanes + j).

Note

Each lane's values equal evaluate() on that lane alone; the output is interleaved the same way.

height()

int serif::discretization::backend::mfem::BasisEvaluation::height ( ) const

nodiscardnoexcept

Number of flattened quadrature samples.

integrate()

void serif::discretization::backend::mfem::BasisEvaluation::integrate	(	const ::mfem::Vector &	values,
		::mfem::Vector &	coefficients,
		BasisWorkspace &	workspace ) const

Apply the coordinate transpose to already weighted quadrature duals.

Parameters

[in]	values	Quadrature data with any required integration weights already applied.
[out]	coefficients	Element-DOF contributions computed as E^T times values.
	workspace	Workspace to use for intermediate computations.

map_point()

template<typename MapT>

void serif::discretization::backend::mfem::BasisEvaluation::map_point	(	int	point,
		const BasisEvaluation &	reference,
		MapT &&	map,
		BasisWorkspace &	workspace )

Apply a pointwise linear map to the reference basis or its geometry variation.

Template Parameters

MapT	Type of the mapping function to apply.

Parameters

point	Quadrature point index to apply the mapping at.
reference	Reference basis evaluation to map from.
map	Mapping function to apply.
workspace	Reusable pointwise input and output buffers.

Precondition

The mapping callback must be linear in its input and fill every output component.

reset_from()

void serif::discretization::backend::mfem::BasisEvaluation::reset_from	(	const BasisEvaluation &	reference,
		int	components )

Allocate storage for a mapped basis using the reference's coefficient ordering and quadrature points.

Parameters

reference	Basis evaluation supplying the dimensions and any shared tensor representation.
components	Number of output components per quadrature point.

Note

Populate the destination at every quadrature point using map_point before evaluation or transpose application.

sample()

void serif::discretization::backend::mfem::BasisEvaluation::sample	(	const ::mfem::FiniteElement &	element,
		const ::mfem::IntegrationRule &	rule,
		ReferenceOperation	operation,
		int	copies,
		TensorBasisCache &	cache,
		ContractionMode	mode,
		const ElementReconstruction *	reconstruction = nullptr )

Prepare basis values or derivatives at quadrature points using a dense matrix or tensor-product representation.

Parameters

element	Finite element to sample.
rule	Integration rule to use for sampling.
operation	Reference operation to perform.
copies	Number of independent copies of the finite-element basis; for example, three scalar basis copies for a vector H1 field.
cache	Tensor basis cache to use.
mode	Contraction mode to use.

set_constant()

void serif::discretization::backend::mfem::BasisEvaluation::set_constant

(

int

points

)

Set the basis evaluation to a constant basis with the given number of points.

Parameters

points

Number of quadrature points to use for the constant basis.

uses_tensor()

bool serif::discretization::backend::mfem::BasisEvaluation::uses_tensor ( ) const

nodiscardnoexcept

Report whether contractions use verified Cartesian factors.

width()

int serif::discretization::backend::mfem::BasisEvaluation::width ( ) const

nodiscardnoexcept

Number of native element coefficients.

Member Data Documentation

m_components

int serif::discretization::backend::mfem::BasisEvaluation::m_components {0}

private

Number of output components per point.

m_dense

::mfem::DenseMatrix serif::discretization::backend::mfem::BasisEvaluation::m_dense

private

Full evaluation matrix, including applied mappings, when the dense path is selected.

m_identity_mapping

bool serif::discretization::backend::mfem::BasisEvaluation::m_identity_mapping {false}

private

Canonical tensor samples need no pointwise mapping.

m_mapping

::mfem::DenseMatrix serif::discretization::backend::mfem::BasisEvaluation::m_mapping

private

Stacked pointwise maps; canonical identity maps require no storage.

m_points

int serif::discretization::backend::mfem::BasisEvaluation::m_points {0}

private

Number of quadrature points in the rule.

m_tensor

std::shared_ptr<const TensorBasis> serif::discretization::backend::mfem::BasisEvaluation::m_tensor

private

Canonical tensor representation, when the tensor path is selected.

m_width

int serif::discretization::backend::mfem::BasisEvaluation::m_width {0}

private

Number of native element coefficients.

---

The documentation for this class was generated from the following files:

• src/include/serif/backend/mfem/discretization/basis_evaluation.hpp
• src/lib/serif/backend/mfem/discretization/basis_evaluation.cpp