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.

Additional CoefficientFunctions¶

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