Coefficients¶

Introduction¶

Coefficients represent fields defined on the mesh. These can be scalar, vector, or matrix-valued. mufem uses them in several components, including reports, boundary conditions, and models.

Models register coefficients to the Coefficient Manager automatically, or you register them manually.

Coefficient Manager¶

The mufem.CoefficientFunctionManager manages all scalar, vector, and matrix coefficient functions used in the simulation. After you register a coefficient, you can use it in reports or export it with the Field Exporter.

coefficient_manager = sim.get_coefficient_manager()

A set of built-in coefficients is always available (see Built-in Coefficients below). You get additional coefficients in two ways:

1. Via a model:

   Models automatically register their own coefficients when you add them to the simulation. For example, the Refinement Model adds Refinement Level:

   model = mufem.RefinementModel()
   sim.get_model_manager().add_model(model)
   
   print(sim.get_coefficient_manager().list_functions())
   

   [..., 'Refinement Level']
   

2. Manually by user:

   Users can define and register their own coefficients (see User Coefficients):

   cff = mufem.CffConstantScalar(1.23)
   sim.get_coefficient_manager().register_user("MyScalar", cff)
   
   print(sim.get_coefficient_manager().list_functions())
   

   ['MyScalar', ...]
   

User Coefficients¶

Several types of coefficients are available in mufem.

Constant Scalar Coefficient¶

mufem.CffConstantScalar defines a scalar field with a constant value:

cff_constant_scalar = mufem.CffConstantScalar(value=1.23)

Sinusoidal Coefficient¶

mufem.CffSinusoidal defines a time-varying sinusoidal scalar field \(f(t) = A \sin(2\pi f t + \phi)\). frequency defaults to 50.0 Hz and phase defaults to 0.0; phase is given in degrees.

cff_sin = mufem.CffSinusoidal(amplitude=2.0, frequency=50.0, phase=30.0)

Gaussian Pulse Coefficient¶

mufem.CffGaussianPulse defines a Gaussian-windowed cosine pulse \(f(t) = A \exp(-(t - t_d)^2 / \tau^2) \cos(2\pi f (t - t_d) + \phi)\). delay defaults to \(4 \tau\) so the pulse is essentially zero at \(t = 0\); phase defaults to 0.0 degrees.

cff_pulse = mufem.CffGaussianPulse(amplitude=1.0, frequency=1.5e9, pulse_width=1.0e-9)

Time Table Coefficient¶

mufem.CffTimeTable defines a piecewise scalar function over time:

cff_time_table = mufem.CffTimeTable(time=[0.1, 0.2, 0.3], value=[1.0, 2.0, 3.0])

Expression-Based Scalar Coefficient¶

mufem.CffExpressionScalar defines a scalar field with a mathematical expression. References to other registered coefficients use brace syntax {Name}. You can access vector components with .X / .Y / .Z. Pure constants such as pi are bare identifiers.

cff_expression = mufem.CffExpressionScalar("sqrt({Position}.X^2 + {Position}.Y^2)")

Expression-Based Vector Coefficient¶

mufem.CffExpressionVector defines a 3-component vector field from a single expression. It supports inline vector literals [a, b, c], vector arithmetic, and the cross product cross(A, B). The same {Name} and .X/.Y/.Z syntax applies.

cff_expr_vec = mufem.CffExpressionVector(
    "cross({Electric Current Density}, {Magnetic Flux Density})"
)

Constant Vector Coefficient¶

mufem.CffConstantVector defines a constant 3D vector field. Components can be passed individually or as a length-3 sequence:

cff_vector = mufem.CffConstantVector(1.0, 2.0, 3.0)
cff_vector = mufem.CffConstantVector((1.0, 2.0, 3.0))

Convenience factories are also available:

mufem.CffConstantVector.Zero()  # [0, 0, 0]
mufem.CffConstantVector.X()     # [1, 0, 0]
mufem.CffConstantVector.Y()     # [0, 1, 0]
mufem.CffConstantVector.Z()     # [0, 0, 1]

Composite Vector Coefficient¶

mufem.CffVectorComponent builds a vector field from three scalar coefficients:

x = mufem.CffConstantScalar(1.0)
y = mufem.CffConstantScalar(2.0)
z = mufem.CffConstantScalar(3.0)

cff_composite = mufem.CffVectorComponent(cff_x=x, cff_y=y, cff_z=z)

Cylindrical Coordinate Coefficient¶

mufem.CffCylindricalCoordinate interprets a child vector coefficient as \((v_r, v_\phi, v_z)\) in a local cylindrical basis and returns the corresponding Cartesian world vector. You can offset and rotate the local frame with translation and rotation.

m_cyl = mufem.CffExpressionVector(
    "var phi := atan2({Position}.Y, {Position}.X);"
    "[ sin(2*phi), 0, cos(2*phi) ]"
)
M = mufem.CffCylindricalCoordinate(vec=m_cyl)

Constant Matrix Coefficient¶

mufem.CffConstantMatrix defines a constant 3×3 symmetric matrix field:

cff_matrix = mufem.CffConstantMatrix(xx=1.0, yy=2.0, zz=3.0, xy=0.1, xz=0.2, yz=0.3)

Convenience factories build common shapes:

mufem.CffConstantMatrix.Isotropic(value=2.0)
mufem.CffConstantMatrix.Diagonal(xx=1.0, yy=2.0, zz=3.0)

Built-in Coefficients¶

The CoefficientFunctionManager registers the following coefficients automatically in every simulation:

Example¶

import mufem

sim = mufem.Simulation.New("My Case", "data/geometry.mesh", print_only_warnings=True)
cff_manager = sim.get_coefficient_manager()

# Scalar coefficients
cff_manager.register_user("MyCffConstantScalar", mufem.CffConstantScalar(1.23))
cff_manager.register_user("MyCffSinusoidal", mufem.CffSinusoidal(amplitude=2., frequency=50., phase=30.))
cff_manager.register_user("MyCffGaussianPulse", mufem.CffGaussianPulse(amplitude=1.0, frequency=1.5e9, pulse_width=1.0e-9))
cff_manager.register_user("MyCffTimeTable", mufem.CffTimeTable(time=[0.1, 0.2, 0.3], value=[1.0, 2.0, 3.0]))
cff_manager.register_user("MyCffExpression", mufem.CffExpressionScalar("sqrt({Position}.X^2 + {Position}.Y^2)"))

# Vector coefficients
cff_manager.register_user("MyCffConstantVector", mufem.CffConstantVector(1.0, 2.0, 3.0))

x = mufem.CffConstantScalar(1.0)
y = mufem.CffConstantScalar(2.0)
z = mufem.CffConstantScalar(3.0)
composite = mufem.CffVectorComponent(cff_x=x, cff_y=y, cff_z=z)
cff_manager.register_user("MyCffCompositeVector", composite)

cff_manager.register_user("MyCffExpressionVector", mufem.CffExpressionVector("[ {Position}.X, {Position}.Y, 0 ]"))

# Matrix coefficient
cff_manager.register_user("MyCffConstantMatrix", mufem.CffConstantMatrix.Isotropic(2.0))

# List all available coefficient names
print(cff_manager.list_functions())