GitHub

LinearOperator

LinearOperator provides a flexible interface for defining linear forms (right-hand side vectors) in finite element problems. These operators typically represent source terms, boundary data, or linearizations of nonlinear operators. The interface supports both standard and discontinuous Galerkin (DG) forms, and allows for custom assembly on cells, faces, or other grid entities. It is also possible to assign a pre-computed vector as a LinearOperator.

Constructors

ExtendableFEM.LinearOperator — Method
LinearOperator(
    A::AbstractMatrix,
    u_test::Vector{<:Union{Int64, Unknown}},
    u_args::Vector{<:Union{Int64, Unknown}};
    kwargs...
) -> Union{ExtendableFEM.LinearOperatorFromMatrix{_A, <:AbstractMatrix{T}} where T, ExtendableFEM.LinearOperatorFromMatrix{_A, MT} where {T, MT<:AbstractMatrix{T}}} where _A<:Union{Integer, Unknown}

Construct a linear form (right-hand side operator) from a user-provided matrix.

This wraps an explicit matrix A (which can be an AbstractMatrix or a block-structured FEMatrix) as a linear operator for finite element assembly. The arguments u_args specify which coefficients of the current solution should be multiplied with the matrix, and u_test specifies where to place the (blocks of the) resulting vector in the system right-hand side.

Arguments

  • A: The matrix to use (can be an AbstractMatrix or a FEMatrix with multiple blocks).
  • u_test: Array specifying which unknowns or blocks the result should be assigned to.
  • u_args: Array specifying which unknowns or blocks are used as arguments (i.e., which solution coefficients are multiplied by A).
source
ExtendableFEM.LinearOperator — Method
LinearOperator(
    b,
    u_test;
    kwargs...
) -> LinearOperator{Float64, _A, typeof(ExtendableFEMBase.standard_kernel)} where _A<:Union{Integer, Unknown}

Construct a linear form (right-hand side operator) from a user-provided vector.

This wraps an explicit vector b (which can be an AbstractVector or a block-structured FEVector) as a linear operator for finite element assembly. The argument u_test specifies where to place the (blocks of the) vector in the system right-hand side.

Arguments

  • b: The vector to use as the right-hand side. Can be an AbstractVector or an FEVector with multiple blocks.
  • u_test: Array specifying which unknowns or blocks the vector should be assigned to.
source
ExtendableFEM.LinearOperator — Method
LinearOperator(
    kernel,
    oa_test::Vector{<:Tuple{Union{Int64, Unknown}, DataType}},
    oa_args::Vector{<:Tuple{Union{Int64, Unknown}, DataType}};
    kwargs...
) -> LinearOperator{Float64}

Construct a nonlinear linear form (right-hand side operator) for finite element assembly, suitable for linearizations or forms depending on the current solution.

This operator evaluates, at each quadrature point, the provided kernel! function, which depends on the operator evaluations of the current solution (the "argument" unknowns). The result of the kernel is then used in a vector product with the operator evaluation(s) of the test function(s).

The kernel function should have the signature:

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 information about the current quadrature point (e.g., qpinfo.x for global coordinates).

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!: Function to evaluate at each quadrature point, depending on the current solution.
  • oa_test: Array of tuples (unknown, operator) specifying test function operator evaluations.
  • oa_args: Array of tuples (unknown, operator) specifying argument operator evaluations (from the current solution).

Keyword Arguments

  • bonus_quadorder: additional quadrature order added to quadorder. Default: 0

  • entities: assemble operator on these grid entities (default = ONCELLS). Default: ONCELLS

  • factor: factor that should be multiplied during assembly. Default: 1

  • name: name for operator used in printouts. Default: ''LinearOperator''

  • parallel: assemble operator in parallel using colors/partitions information. Default: false

  • parallel_groups: assemble operator in parallel using CellAssemblyGroups. Default: false

  • params: array of parameters that should be made available in qpinfo argument of kernel function. Default: nothing

  • quadorder: quadrature order. Default: ''auto''

  • regions: subset of regions where operator should be assembly only. Default: Any[]

  • store: store matrix separately (and copy from there when reassembly is triggered). Default: false

  • time_dependent: operator is time-dependent ?. Default: false

  • verbosity: verbosity level. Default: 0

source
ExtendableFEM.LinearOperator — Method
function LinearOperator(
	[kernel!::Function],
	oa_test::Array{<:Tuple{Union{Unknown,Int}, DataType},1};
	kwargs...)

Construct a linear form (right-hand side operator) for finite element assembly.

This operator evaluates, at each quadrature point, the provided kernel! function (or a constant function if none is given) and computes the vector product with the operator evaluation(s) of the test function(s). The kernel function should have the signature:

kernel!(result, qpinfo)

where result is the output array and qpinfo provides information about the current quadrature point (e.g., qpinfo.x for global coordinates).

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): Function to evaluate at each quadrature point. If omitted, a constant kernel is used.
  • oa_test: Array of tuples (unknown, operator) specifying test function operator evaluations.

Keyword Arguments

  • bonus_quadorder: additional quadrature order added to quadorder. Default: 0

  • entities: assemble operator on these grid entities (default = ONCELLS). Default: ONCELLS

  • factor: factor that should be multiplied during assembly. Default: 1

  • name: name for operator used in printouts. Default: ''LinearOperator''

  • parallel: assemble operator in parallel using colors/partitions information. Default: false

  • parallel_groups: assemble operator in parallel using CellAssemblyGroups. Default: false

  • params: array of parameters that should be made available in qpinfo argument of kernel function. Default: nothing

  • quadorder: quadrature order. Default: ''auto''

  • regions: subset of regions where operator should be assembly only. Default: Any[]

  • store: store matrix separately (and copy from there when reassembly is triggered). Default: false

  • time_dependent: operator is time-dependent ?. Default: false

  • verbosity: verbosity level. Default: 0

Example

# Standard load vector with right-hand side f(x)
kernel!(result, qpinfo) = (result[1] = f(qpinfo.x))
O = LinearOperator(kernel!, [id(u)]; entities=ON_CELLS)
source
ExtendableFEM.assemble! — Method
assemble!(
    b::FEVector,
    O::LinearOperator{Tv, UT};
    ...
) -> Any
assemble!(
    b::FEVector,
    O::LinearOperator{Tv, UT},
    sol;
    assemble_rhs,
    kwargs...
) -> Any

Assembles the right-hand side vector for a linear form (i.e., applies the LinearOperator to the current solution and accumulates the result in b). If the operator depends on the current solution (i.e., has argument unknowns), the solution vector(s) sol must be provided.

Arguments

  • b::FEVector: The right-hand side vector to assemble into (can be block-structured).
  • O::LinearOperator: The linear operator to assemble.
  • sol: (Optional) Solution vector(s) for argument unknowns, required if the operator depends on the current solution.
  • assemble_rhs: (Keyword, default = true) If false, assembly is skipped.
  • kwargs...: Additional keyword arguments passed to the assembler (e.g., time, custom parameters).

Returns

  • The assembled right-hand side vector b (modified in-place).
source

Example: Right-hand Side Operator

For a right-hand side operator of a Poisson problem with a given function f(x), the kernel could look like:

function kernel!(result, qpinfo)
    result[1] = f(qpinfo.x)
end
u = Unknown("u")
LinearOperator(kernel!, [id(u)])

The argument [id(u)] specifies that the result of the kernel is multiplied with the identity evaluation of the test function.

LinearOperatorDG

LinearOperatorDG is intended for linear forms that involve jumps or averages of discontinuous quantities on faces, requiring access to all degrees of freedom on neighboring cells.

ExtendableFEM.LinearOperatorDG — Method
function LinearOperatorDG(
	kernel::Function,
	oa_test::Array{<:Tuple{Union{Unknown,Int}, DataType},1},
	oa_args::Array{<:Tuple{Union{Unknown,Int}, DataType},1};
	kwargs...)

Generates a nonlinear linear form that evaluates a kernel function that depends on the (discontinuous) operator evaluations of the current solution. The result of the kernel function is used in a vector product with the operator evaluation(s) of the test function(s). Hence, this can be used as a linearization of a nonlinear operator. The header of the kernel functions needs to be conform to the interface

kernel!(result, eval_args, qpinfo)

where qpinfo allows to access information at the current quadrature point.

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: 0

  • entities: assemble operator on these grid entities (default = ONFACES). Default: ONFACES

  • entry_tolerance: threshold to add entry to sparse matrix. Default: 0

  • factor: factor that should be multiplied during assembly. Default: 1

  • name: name for operator used in printouts. Default: ''LinearOperatorDG''

  • parallel: assemble operator in parallel using colors/partitions information. Default: false

  • parallel_groups: assemble operator in parallel using FaceAssemblyGroups. Default: false

  • params: array of parameters that should be made available in qpinfo argument of kernel function. Default: nothing

  • quadorder: quadrature order. Default: ''auto''

  • regions: subset of regions where operator should be assembly only. Default: Any[]

  • store: store matrix separately (and copy from there when reassembly is triggered). Default: false

  • time_dependent: operator is time-dependent ?. Default: false

  • verbosity: verbosity level. Default: 0

source
ExtendableFEM.LinearOperatorDG — Method
function LinearOperatorDG(
	[kernel!::Function],
	oa_test::Array{<:Tuple{Union{Unknown,Int}, DataType},1};
	kwargs...)

Generates a linear form that evaluates, in each quadrature point, the kernel function (if non is provided, a constant function one is used) and computes the vector product of the result with with the (discontinuous) operator evaluation(s) of the test function(s). The header of the kernel functions needs to be conform to the interface

kernel!(result, qpinfo)

where qpinfo allows to access information at the current quadrature point, e.g. qpinfo.x are the global coordinates of the quadrature point.

Keyword arguments:

  • bonus_quadorder: additional quadrature order added to quadorder. Default: 0

  • entities: assemble operator on these grid entities (default = ONFACES). Default: ONFACES

  • entry_tolerance: threshold to add entry to sparse matrix. Default: 0

  • factor: factor that should be multiplied during assembly. Default: 1

  • name: name for operator used in printouts. Default: ''LinearOperatorDG''

  • parallel: assemble operator in parallel using colors/partitions information. Default: false

  • parallel_groups: assemble operator in parallel using FaceAssemblyGroups. Default: false

  • params: array of parameters that should be made available in qpinfo argument of kernel function. Default: nothing

  • quadorder: quadrature order. Default: ''auto''

  • regions: subset of regions where operator should be assembly only. Default: Any[]

  • store: store matrix separately (and copy from there when reassembly is triggered). Default: false

  • time_dependent: operator is time-dependent ?. Default: false

  • verbosity: verbosity level. Default: 0

source