PyMFEM Python Bindings for MFEM

To use a Python function as a coefficient in MFEM, you must inherit from the appropriate PyMFEM coefficient classes and implement the EvalValue(self, x) method.

Available Classes:

• mfem.PyCoefficient: For scalar coefficients.
• mfem.PyCoefficientT: Time-dependent scalar coefficients.
• mfem.VectorPyCoefficient: For vector coefficients.
• mfem.VectorPyCoefficientT: Time-dependent vector coefficients.

Implementation Pattern:

class MyCoefficient(mfem.PyCoefficient):
    def EvalValue(self, x):
        return 0.01  # Must return a float

class MyVectorCoefficient(mfem.VectorPyCoefficient):
    def EvalValue(self, x):
        return [0., 0., np.cos(x[2])] # Must return a list/array

Constant Coefficients: MatrixConstantCoefficient and VectorConstantCoefficient support natural Python objects (lists/nested lists) as input. The input is converted via np.array(x, dtype=float) internally.

class Jt(mfem.VectorPyCoefficient):
    def EvalValue(self, x):
        return [0.,0., np.cos(np.abs(x[2]-0.03)/0.03*np.pi/2)]

class Sigma(mfem.PyCoefficient):
    def EvalValue(self, x):
        return 0.01

Cof_Jt = Jt(3)
dd = mfem.VectorFEBoundaryTangentLFIntegrator(Cof_Jt)

When developing (e.g., editing *.i files), you can avoid full rebuilds by using specific flags to build components incrementally.

Workflow:

1. Clean the environment:

   python setup.py clean --all

2. Build external libraries only:

   pip install . -C"ext-only=Yes" --verbose

3. Generate SWIG wrappers (skipping externals):

   pip install . -C"skip-ext=Yes" -C"swig=Yes" --verbose

4. Final build (after editing wrappers): Once you are satisfied with the *.cxx and *.py files, build the final package skipping both externals and SWIG:

   pip install . -C"skip-ext=Yes" -C"skip-swig=Yes" --verbose

Development Flags:

• --swig: Run SWIG only.
• --skip-swig: Build without running SWIG.
• --skip-ext: Skip building external libraries.
• --ext-only: Build external libraries and exit.

Function coefficients written in Python can be Just-In-Time (JIT) compiled using Numba for performance. You can use mfem.jit decorators or the NumbaFunction class.

Using @mfem.jit decorators

Decorators can be applied to functions to create scalar, vector, or matrix coefficients.

• @mfem.jit.scalar(td=False, ...)
• @mfem.jit.vector(vdim=None, shape=None, ...)
• @mfem.jit.matrix(height=None, width=None, ...)

Decorator Arguments:

• td: Time-dependence (False for stationary, True for time-dependent).
• complex: If True, returns a complex coefficient (internally creates real and imaginary parts).
• interface: 'simple' (returns by value, Pythonic) or 'c++' (returns by parameter, like C++).
• shape: The shape of the return value (e.g., shape=(3,)).
• vdim: Length of vector coefficient.
• dependency: A tuple of other coefficients that this function depends on.

Example: JIT Vector Coefficient

@mfem.jit.vector(shape=(3,))
def f_exact(x):
    return np.array([(1 + kappa**2)*sin(kappa * x[1]),
                     (1 + kappa**2)*sin(kappa * x[2]),
                     (1 + kappa**2)*sin(kappa * x[0])])

x.ProjectCoefficient(f_exact)

Example: Complex Coefficient

@mfem.jit.scalar(complex=True)
def c12(ptx):
    return ptx[0] + 1j*ptx[1]

x.ProjectCoefficient(c12.real)
x.ProjectCoefficient(c12.imag)

>>> @mfem.jit.scalar()
>>> def c12(ptx):
>>>     return s_func0(ptx[0], ptx[1], ptx[2])

>>> @mfem.jit.vector(shape=(3,))
>>> def f_exact(x):
>>>     return np.array((1 + kappa**2)*sin(kappa * x[1]),
>>>                     (1 + kappa**2)*sin(kappa * x[2]),
>>>                     (1 + kappa**2)*sin(kappa * x[0]))

>>> x.ProjectCoefficient(f_exact)