# Working with CoefficientFunctions¶

A CoefficientFunction is a function which can be evaluated on a mesh, and may be used to provide the coefficient or a right-hand-side to the variational formulation. Because typical finite element procedures iterate over elements, and map integration points from a reference element to a physical element, the evaluation of a CoefficientFunction requires a mapped integration point. The mapped integration point contains the coordinate, as well as the Jacobian, but also element number and region index. This allows the efficient evaluation of a wide class of functions needed for finite element computations.

class ngsolve.CoefficientFunction

A CoefficientFunction (CF) is some function defined on a mesh. Examples are coordinates x, y, z, domain-wise constants, solution-fields, ... CFs can be combined by mathematical operations (+,-,sin(), ...) to form new CFs Parameters:

val : can be one of the following:

scalar (float or complex):

Creates a constant CoefficientFunction with value val

tuple of scalars or CoefficientFunctions:

Creates a vector or matrix valued CoefficientFunction, use dims=(h,w) for matrix valued CF

list of scalars or CoefficientFunctions:

Creates a domain-wise CF, use with generator expressions and mesh.GetMaterials() and mesh.GetBoundaries()

## Basic Coefficient Functions¶

Python objects implicitly convertible to float or Complex are implicitly converted to CoefficientFunction if needed. The Cartesian coordinates x, y, and z are pre-defined coordinate coefficient functions:

f = LinearForm(V)
f += SymbolicLFI( x * V.TestFunction())


A CoefficientFunction initialized with a list stores one value per region, depending where the CoefficientFunction is used this is a domain or boundary region. Here one usually uses generator expressions in combination with mesh.GetMaterials() and mesh.GetBoundaries():

alpha_d = {"air" : 1, "box" : 100}
alpha = CoefficientFunction([alpha_d[mat] for mat in mesh.GetMaterials()])


A CoefficientFunction initialized with a tuple gives a vector coefficient function. Components of the coefficient function can be accessed by the bracket operator:

vec_cf = CoefficientFunction( (fx,fy) )  # Creates a vector CF
fx_again = vec_cf[0]                     # Creates a scalar CF from the first component


A matrix valued CF can be created with the additional dims argument:

mat_cf = CoefficientFunction((f11,f12,f21,f22),dims=(2,2))


## ProxyFunctions¶

The finite element spaces provide proxy placeholder functions for Symbolic Integrators when assembling the system matrices the proxy functions are replaced with the FEM basis functions.

FESpace.TrialFunction(self: ngsolve.comp.FESpace) → object

Return a proxy to be used as a trialfunction in Symbolic Integrators

FESpace.TestFunction(self: ngsolve.comp.FESpace) → object

Return a proxy to be used as a testfunction for Symbolic Integrators

## Operations on CoefficientFunctions¶

CoefficientFunctions can be combined with algebraic operations (+,-,*,/,**). Math functions are available as well for CoefficientFunctions: sin, cos, tan, exp, log, atan, sqrt, Conj.

## Special CoefficientFunctions¶

NGSolve provides special coefficient functions needed for finite element computations. Special coefficient functions are mesh dependent.

You can get the normal vector on an interface with

specialcf.normal = <bound method PyCapsule.normal of <ngsolve.fem.SpecialCFCreator object>>

this can be used in discontinuous Galerkin methods.

The tangential vector can be obtained in the same way:

specialcf.tangential = <bound method PyCapsule.tangential of <ngsolve.fem.SpecialCFCreator object>>

The local mesh size can be obtained by a coefficient function as well:

specialcf.mesh_size = <ngsolve.fem.CoefficientFunction object>

This has application i.e. in hybrid DG methods.

### IfPos¶

The function IfPos provides CoefficientFunctions depending on some condition:

ngsolve.IfPos(c1: ngfem::CoefficientFunction, then_obj: object, else_obj: object) → ngfem::CoefficientFunction

Returns new CoefficientFunction with values then_obj if c1 is positive and else_obj else.

Parameters:

c1ngsolve.CoefficientFunction

Indicator function

then_objobject

Values of new CF if c1 is positive, object must be implicitly convertible to ngsolve.CoefficientFunction. See help(CoefficientFunction ) for information.

else_objobject

Values of new CF if c1 is not positive, object must be implicitly convertible to ngsolve.CoefficientFunction. See help(CoefficientFunction ) for information.

### Parameter CoefficientFunction¶

If you want a CoefficientFunction with a variable parameter, instead of using a new BilinearForm every time you can use a Parameter CF. The parameter can be modified with the Set method and when assembling the BilinearForm again, the updated parameter is used.

class ngsolve.Parameter

CoefficientFunction with a modifiable value

Parameters:

valuefloat

Parameter value

Get(self: ngsolve.fem.Parameter) → float

return parameter value

Set(self: ngsolve.fem.Parameter, value: float) → None

Modify parameter value.

Parameters:

valuedouble

input scalar

### BSpline CoefficientFunction¶

You can create a BSpline as a CoefficientFunction as well. BSplines are differentiable and integrable:

class ngsolve.BSpline

BSpline of arbitrary order

Parameters:

orderint

order of the BSpline

knotslist

list of float

valslist

list of float

Differentiate(self: ngsolve.fem.BSpline) → ngsolve.fem.BSpline

Differentiate the BSpline

Integrate(self: ngsolve.fem.BSpline) → ngsolve.fem.BSpline

Integrate the BSpline

## Compiling a CoefficientFunctions¶

CoefficientFunction.Compile(self: ngsolve.fem.CoefficientFunction, realcompile: bool = False, maxderiv: int = 2, wait: bool = False) → ngsolve.fem.CoefficientFunction

Compile list of individual steps, experimental improvement for deep trees

Parameters:

realcompilebool

True -> Compile to C++ code

maxderivint

input maximal derivative

waitbool

True -> Waits until the previous Compile call is finished before start compiling

## Evaluating CoefficientFunctions¶

Sometimes it can be useful to evaluate a CoefficientFunction. Since some CoefficientFunctions are only defined on the mesh (like a GridFunction) this can only be done with information from the mesh. For this we request a mapped integration point from the mesh and plug it into the CoefficientFunction:

>>> mip = mesh(0.2,0.4)
>>> cf = x*x*y
>>> cf(mip)
0.016000000000000004