# LinearOperator

A linear operator allows to add vectors to the right-hand side of the system that usually refer to right-hand side data or linearisations of PDE operators (see remark in NonlinearOperator example). If the linear operator lives on face entities, also jumps of operators can be involved, if they are naturally continuous for the finite element space in operation (also jumps for broken spaces) and only involve degrees of freedom on the face, e.g. normal jumps for Hdiv spaces or jumps for H1-conforming spaces or tangential jumps of Hcurl spaces. For all other discontinuous operator evaluations (that needs to evaluate more than the degrees of freedom on the face) there is the possibility to use LinearOperatorDG. It is also possible to assign a vector assembled by the user as a LinearOperator.

## Constructors

`ExtendableFEM.LinearOperator`

— Method```
function LinearOperator(
A,
u_test,
u_args;
kwargs...)
```

Generates a linear form from a user-provided matrix A, which can be an AbstractMatrix or a FEMatrix with multiple blocks. The arguments u*args specify which coefficients of the current solution should be multiplied with the matrix and u*test specifies where to put the (blocks of the) resulting vector in the system right-hand side.

`ExtendableFEM.LinearOperator`

— Method```
function LinearOperator(
b,
u_test;
kwargs...)
```

Generates a linear form from a user-provided vector b, which can be an AbstractVector or a FEVector with multiple blocks. The argument u_test specifies where to put the (blocks of the) vector in the system right-hand side.

`ExtendableFEM.LinearOperator`

— Method```
function LinearOperator(
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 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:

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

verbosity: verbosity level. Default: 0

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

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

entities: assemble operator on these grid entities (default = ON

*CELLS). Default: ON*CELLSquadorder: quadrature order. Default: ''auto''

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

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

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

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

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

`ExtendableFEM.LinearOperator`

— Method```
function LinearOperator(
[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 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.

Operator evaluations are tuples that pair an unknown identifier or integer with a Function operator.

Example: LinearOperator(kernel!, [id(1)]; kwargs...) generates the right-hand side for a Poisson problem, where kernel! evaluates the right-hand side.

Keyword arguments:

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

verbosity: verbosity level. Default: 0

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

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

entities: assemble operator on these grid entities (default = ON

*CELLS). Default: ON*CELLSquadorder: quadrature order. Default: ''auto''

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

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

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

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

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

## Example - right-hand side

For a right-hand side operator of a Poisson problem with some given function `f(x)`

a kernel could look like

```
function kernel!(result, qpinfo)
result[1] = f(qpinfo.x)
end
```

and the coressponding LinearOperator constructor call reads

```
u = Unknown("u")
NonlinearOperator(kernel!, [id(u)])
```

The second argument triggers that the `result`

vector of the kernel is multiplied with the Identity evaluation of the test function.

## LinearOperatorDG

LinearOperatorDG is intended for linear forms that involves jumps of discontinuous quantities on faces whose assembly requires evaluation of all degrees of freedom on the neighbouring cells, e.g. gradient jumps for H1 conforming functions. In this case the assembly loop triggers integration along the boundary of the 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 (discontinous) 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:

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

verbosity: verbosity level. Default: 0

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

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

entities: assemble operator on these grid entities (default = ON

*FACES). Default: ON*FACESquadorder: quadrature order. Default: ''auto''

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

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

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

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

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

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

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

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

verbosity: verbosity level. Default: 0

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

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

entities: assemble operator on these grid entities (default = ON

*FACES). Default: ON*FACESquadorder: quadrature order. Default: ''auto''

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

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

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

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

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