# 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$