Coefficients¶

Introduction¶

Coefficients represent fields defined on the mesh. These can be scalar, vector, or matrix-valued. They are used in various components of μfem, including reports, boundary conditions, and models.

Coefficients are registered to the Coefficient Manager either automatically by models or manually by users.

Coefficient Manager¶

The mufem.CoefficientFunctionManager manages all scalar, vector, and matrix coefficient functions used in the simulation. Once registered, coefficients can be used in reports or exported using the Field Exporter.

coefficient_manager = sim.get_coefficient_manager()

A set of built-in coefficients is always available (see Built-in Coefficients below). Additional coefficients are registered in two ways:

1. Via a model:

   Models automatically register their own coefficients when added 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 μfem.

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 via a mathematical expression. References to other registered coefficients use brace syntax {Name}; vector coefficients can be component-accessed 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. The local frame can be offset and rotated via 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 following coefficients are registered automatically by the CoefficientFunctionManager 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())