Item Integrators
ItemIntegrator
provides a flexible interface for computing derived quantities from finite element solutions. These include a posteriori error estimators, norms, physical quantities (e.g., drag/lift coefficients), and other statistics that are computed by integrating over mesh entities (cells, faces, etc.).
API Reference
ExtendableFEM.ItemIntegrator
— Methodfunction ItemIntegrator(
[kernel!::Function],
oa_args::Array{<:Tuple{Union{Unknown,Int}, DataType},1};
kwargs...)
Construct an operator that integrates user-specified operator evaluations (e.g., gradients, values) over mesh entities, optionally applying a custom kernel function at each quadrature point.
This is a flexible tool for assembling quantities such as integrals, norms, or custom functionals over cells, faces, or other mesh entities. If no kernel is provided, the arguments are integrated directly. If a kernel is provided, it must have the interface:
kernel!(result, eval_args, qpinfo)
where result
is the output array, eval_args
contains the evaluated operator arguments at the quadrature point, and qpinfo
provides quadrature point information (e.g., coordinates, region, etc.).
Operator evaluations are specified as tuples pairing an unknown identifier (or integer) with a function operator (such as those generated by grad(u)
, id(u)
, etc).
Arguments
kernel!
(optional): A function to combine the evaluated operator arguments at each quadrature point.oa_args
: Array of tuples(unknown, operator)
specifying which operator evaluations to perform.
Keyword Arguments
bonus_quadorder
: additional quadrature order added to quadorder. Default: 0entities
: assemble operator on these grid entities (default = ONCELLS). Default: ONCELLSfactor
: factor that should be multiplied during assembly. Default: 1name
: name for operator used in printouts. Default: ''ItemIntegrator''parallel
: assemble operator in parallel using partitions information. Default: falseparams
: array of parameters that should be made available in qpinfo argument of kernel function. Default: nothingpiecewise
: returns piecewise integrations, otherwise a global integration. Default: truequadorder
: quadrature order. Default: ''auto''regions
: subset of regions where the item integrator should be evaluated. Default: Any[]resultdim
: dimension of result field (default = length of arguments). Default: 0verbosity
: verbosity level. Default: 0
ExtendableFEM.L2NormIntegrator
— Methodfunction L2NormIntegrator(
oa_args::Array{<:Tuple{Union{Unknown,Int}, DataType},1};
kwargs...)
ItemIntegrator with a fixed kernel that computes the (componentwise) L2Norm of the arguments.
Keyword arguments:
bonus_quadorder
: additional quadrature order added to quadorder. Default: 0entities
: assemble operator on these grid entities (default = ONCELLS). Default: ONCELLSfactor
: factor that should be multiplied during assembly. Default: 1name
: name for operator used in printouts. Default: ''ItemIntegrator''parallel
: assemble operator in parallel using partitions information. Default: falseparams
: array of parameters that should be made available in qpinfo argument of kernel function. Default: nothingpiecewise
: returns piecewise integrations, otherwise a global integration. Default: truequadorder
: quadrature order. Default: ''auto''regions
: subset of regions where the item integrator should be evaluated. Default: Any[]resultdim
: dimension of result field (default = length of arguments). Default: 0verbosity
: verbosity level. Default: 0
ExtendableFEM.evaluate
— Methodfunction evaluate(
O::ItemIntegrator,
sol;
time = 0,
kwargs...)
Evaluates the ItemIntegrator for the specified solution and returns an matrix of size resultdim x num_items.
ExtendableFEMBase.evaluate!
— Methodevaluate!(b, O::ItemIntegrator, sol; kwargs...)
Evaluate the ItemIntegrator
operator O
for the given solution sol
and store the result in the matrix b
.
This function assembles the integral or functional defined by O
using the current values in sol
, writing the result into the provided matrix b
. The result can be a global or piecewise (per-entity) quantity, depending on the operator's settings.
Arguments
b
: Output matrix to store the result (size and shape depend onO
and itspiecewise
/resultdim
settings).O
: TheItemIntegrator
operator to evaluate.sol
: The solution vector (FEVector
) or array of solution blocks (Array{<:FEVectorBlock,1}
) providing the field values.
Keyword Arguments
time
: Time parameter for time-dependent problems (default:0
).- Additional keyword arguments are passed to the assembler.
Notes
- The shape of
b
should match the expected output of the integrator (e.g.,resultdim × nitems
for piecewise results).
ItemIntegratorDG
ItemIntegratorDG
is intended for quantities that involve jumps or averages of discontinuous quantities on faces, requiring access to all degrees of freedom on neighboring cells. This is essential for DG methods and certain error estimators.
ExtendableFEM.ItemIntegratorDG
— Methodfunction ItemIntegratorDG(
kernel::Function,
oa_args::Array{<:Tuple{Union{Unknown,Int}, DataType},1};
kwargs...)
Generates an ItemIntegrator that evaluates the specified (discontinuous) operator evaluations, puts it into the kernel function and integrates the results over the entities (see kwargs) along cell boundaries. If no kernel is given, the arguments are integrated directly. If a kernel is provided it has be conform to the interface
kernel!(result, eval_args, qpinfo)
where qpinfo allows to access information at the current quadrature point. Additionally the length of the result needs to be specified via the kwargs.
Evaluation can be triggered via the evaluate function.
Operator evaluations are tuples that pair an unknown identifier or integer with a Function operator.
Keyword arguments:
bonus_quadorder
: additional quadrature order added to quadorder. Default: 0entities
: assemble operator on these grid entities (default = ONCELLS). Default: ONFACESfactor
: factor that should be multiplied during assembly. Default: 1name
: name for operator used in printouts. Default: ''ItemIntegratorDG''params
: array of parameters that should be made available in qpinfo argument of kernel function. Default: nothingpiecewise
: returns piecewise integrations, otherwise a global integration. Default: truequadorder
: quadrature order. Default: ''auto''regions
: subset of regions where the item integrator should be evaluated. Default: Any[]resultdim
: dimension of result field (default = length of arguments). Default: 0verbosity
: verbosity level. Default: 0
ExtendableFEM.evaluate
— Methodfunction evaluate(
O::ItemIntegratorDG,
sol;
time = 0,
kwargs...)
Evaluates the ItemIntegratorDG for the specified solution and returns an matrix of size resultdim x num_items.
ExtendableFEMBase.evaluate!
— Methodfunction evaluate(
b::AbstractMatrix,
O::ItemIntegratorDG,
sol::FEVector;
time = 0,
kwargs...)
Evaluates the ItemIntegratorDG for the specified solution into the matrix b.
ExtendableFEMBase.evaluate!
— Methodfunction evaluate(
b::AbstractMatrix,
O::ItemIntegratorDG,
sol::Array{FEVEctorBlock};
time = 0,
kwargs...)
Evaluates the ItemIntegratorDG for the specified solution into the matrix b.
See, e.g., Example207, Example210 or Example245 for some practical use cases.