# Coefficients

Coefficient objects serve many purposes within MFEM. As the name suggests they often represent the material coefficients appearing in partial differential equations. However, Coefficients can also be used to specify initial conditions, boundary conditions, exact solutions, etc..

Coefficients come in three varieties; scalar-valued, vector-valued,
and matrix-valued. The primary purpose of any Coefficient class is to
define an `Eval`

method which returns a scalar, vector, or matrix
given an element and a location within that element expressed as a
point in reference space i.e. an `IntegrationPoint`

. Coefficients can
also be time dependent. Time is treated as a parameter which changes
infrequently by passing the current time though a `SetTime(t)`

method.

A Coefficient's `Eval`

method depends on not only the position within
an element but also on the element attribute number which allows the
Coefficient to return different results from different regions of the
domain or boundary. This can be a powerful feature but it can lead to
unexpected results. As a rule domain integrals will have access to
element attributes and boundary integrals will access the boundary
attributes. This seems obvious but there may be cases where the
outcome is not so clear cut and careful thought is required.

It is important to know when a Coefficient will be accessed,
particularly in the case of time-dependent or field-dependent
coefficients. When used with `GridFunction::Project`

,
`GridFunction::ComputeL2Error`

, and other `GridFunction`

methods the
`Coefficient`

is used immediately. When used in `BilinearForm`

and
`LinearForm`

objects the coefficients are only accessed during calls
to the `Assemble`

methods. An important side note is that
`GridFunction`

and `LinearForm`

objects will overwrite their values
during such calls but a `BilinearForm`

will not. Consequently, when
using a time-dependent coefficient with a `BilinearForm`

object it is
crucial that the user calls `BilinearForm::Update`

to reset the
internally stored matrix to zero before calling
`BilinearForm::Assemble`

. Otherwise the new matrix entries will be
added to the previous values leading to odd behavior.

## Scalar Coefficients

### Basic Scalar Coefficients

Class Name | Description |
---|---|

ConstantCoefficient | Returns a constant value: $\alpha$ |

FunctionCoefficient | Computes a value from a standard function, $f(\vec{x},t)$, or a lambda expression |

PWConstCoefficient | Returns different constants based e.g. on element attribute |

GridFunctionCoefficient | Returns values interpolated from a scalar-valued `GridFunction` : $u(\vec{x})$ |

DivergenceGridFunctionCoefficient | Returns the divergence of a vector-valued `GridFunction` : $\nabla\cdot\vec{u}$ |

DeltaCoefficient | A weighted Dirac delta function: $s\,w(\vec{x},t)\,T(t)\,\delta(\vec{x}-\vec{x}_c)$ |

### Derived Scalar Coefficients

These classes provide a means of creating functions of existing
coefficients. In performance critical situations it would clearly be
preferable to write specialized `Coefficient`

classes but these offer
a quick and, hopefully, easy to use alternative.

Class Name | Formula |
---|---|

TransformedCoefficient | $T(Q_1(\vec{x},t))\mbox{ or }T(Q_1(\vec{x},t),Q_2(\vec{x},t))$ |

RestrictedCoefficient | $Q(\vec{x})\,\forall a\in A, 0\mbox{ otherwise}$ |

SumCoefficient | $\alpha\,Q_1(\vec{x}) + \beta\,Q_2(\vec{x})$ |

ProductCoefficient | $Q_1(\vec{x})\,Q_2(\vec{x})$ |

PowerCoefficient | $Q(\vec{x})^p$ |

InnerProductCoefficient | $\vec{Q}_1\cdot\vec{Q}_2$ |

VectorRotProductCoefficient | $\vec{Q}_1\times\vec{Q}_2\mbox{ in }\mathbb{R}^2$ |

DeterminantCoefficient | $|\overleftrightarrow{Q}|$ |

## Vector Coefficients

### Basic Vector Coefficients

Class Name | Description |
---|---|

VectorConstantCoefficient | Returns a constant vector value: $\vec{\alpha}$ |

VectorFunctionCoefficient | Computes a value from a standard function, $\vec{f}(\vec{x})$, or a lambda expression |

VectorGridFunctionCoefficient | Returns values interpolated from a vector-valued `GridFunction` : $\vec{u}(\vec{x})$ |

GradientGridFunctionCoefficient | Returns the gradient of a scalar-valued `GridFunction` : $\nabla u(\vec{x})$ |

CurlGridFunctionCoefficient | Returns the curl of a vector-valued `GridFunction` : $\nabla\times\vec{u}(\vec{x})$ |

VectorDeltaCoefficient | $s\,\vec{\alpha}\,\delta(\vec{x}-\vec{x}_c)$ |

### Derived Vector Coefficients

Again these classes provide a means of creating functions of existing coefficients.

Class Name | Formula |
---|---|

VectorArrayCoefficient | Construct a vector value from an array of scalar coefficients: $\vec{Q}_a$ |

VectorRestrictedCoefficient | $\vec{Q}(\vec{x})\,\forall a\in A, 0\mbox{ otherwise}$ |

VectorSumCoefficient | $\alpha\,\vec{Q}_1(\vec{x}) + \beta\,\vec{Q}_2(\vec{x})$ |

ScalarVectorProductCoefficient | $Q_1\,\vec{Q}_2$ |

VectorCrossProductCoefficient | $\vec{Q}_1\times\vec{Q}_2$ |

MatVecCoefficient | $\overleftrightarrow{Q}_1\cdot\vec{Q}_2$ |

## Matrix Coefficients

### Basic Matrix Coefficients

Class Name | Description |
---|---|

MatrixConstantCoefficient | Returns a constant matrix value: $\overleftrightarrow{\alpha}$ |

MatrixFunctionCoefficient | Computes a value from a standard function, $\overleftrightarrow{f}$, or a lambda expression |

IdentityMatrixCoefficient | Returns the identity matrix of the appropriate dimension: $\overleftrightarrow{I}$ |

### Derived Matrix Coefficients

Again these classes provide a means of creating functions of existing coefficients.

Class Name | Formula |
---|---|

MatrixArrayCoefficient | Construct a matrix value from an array of scalar coefficients: $\overleftrightarrow{Q}_a$ |

MatrixRestrictedCoefficient | $\overleftrightarrow{Q}(\vec{x})\,\forall a\in A, 0\mbox{ otherwise}$ |

MatrixSumCoefficient | $\alpha\,\overleftrightarrow{Q}_1(\vec{x}) + \beta\,\overleftrightarrow{Q}_2(\vec{x})$ |

ScalarMatrixProductCoefficient | $Q_1\,\overleftrightarrow{Q}_2$ |

TransposeMatrixCoefficient | $\overleftrightarrow{Q}^T$ |

InverseMatrixCoefficient | $\overleftrightarrow{Q}^{-1}$ |

OuterProductCoefficient | $\vec{Q}_1\otimes\vec{Q}_2$ |