Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Field gradients

Figures use PyVista; verbose plotting boilerplate is omitted.

A transfer copies a field from one mesh onto another; a gradient differentiates it. mf.Gradient reconstructs the gradient of a scalar field with a moving least-squares (MLS) fit over the k nearest source cell centres, using the same prepare / apply split as the field transfers: the geometric operator is built once and can then be applied to any number of scalar fields.

Unlike a transfer, whose per-target weights are scalar, the gradient carries d weights per neighbour — one per space direction — so the result is a vector field with d trailing components. This page covers the three evaluation targets (the source cells, a target mesh, an arbitrary point cloud), validates them against analytic gradients, and compares the distance kernels.

import numpy as np

import mefikit as mf

# A smooth, non-affine scalar field on the unit square grid:
#     f(x, y) = sin(pi x) sin(pi y)
n = 41
src = mf.build_cmesh(np.linspace(0.0, 1.0, n), np.linspace(0.0, 1.0, n))
src.fields["f"] = (mf.X * np.pi).sin() * (mf.Y * np.pi).sin()

The gradient operator

mf.Gradient(src, tgt=None, k=10, weighting=..., def_val=0.0) builds the MLS operator. The evaluation points depend on how it is built:

ConstructorEvaluated at
mf.Gradient(src)the source mesh’s own cell centroids
mf.Gradient(src, tgt)the target mesh’s cell centroids
mf.Gradient.at_points(src, points)an explicit (n, d) point array

k is the number of nearest source cells used in each local fit and weighting is one of the mf.DistanceWeighting kernels — Constant, InverseDistance(exponent), CompactSupport(exponent) or Gaussian — shared with the transfer operators. A degree-1 fit reproduces affine fields exactly, which is the validation used below.

Gradient at the source cells

With no target mesh the gradient is evaluated at the source cell centroids. grad("f") is a lazy vector Field; grad.eval("f") materialises it as {etype: array} of shape (n_cells, d).

grad = mf.Gradient(src, k=12)
grad_f = np.asarray(grad.eval("f")["QUAD4"])
grad_f.shape
(1600, 2)

The analytic gradient of f is grad f = (pi cos(pi x) sin(pi y), pi sin(pi x) cos(pi y)). Sampling it at the cell centroids gives a reference to compare against:

cx = np.asarray(src.eval(mf.X)["QUAD4"]).ravel()
cy = np.asarray(src.eval(mf.Y)["QUAD4"]).ravel()
exact = np.c_[
    np.pi * np.cos(np.pi * cx) * np.sin(np.pi * cy),
    np.pi * np.sin(np.pi * cx) * np.cos(np.pi * cy),
]

err = np.linalg.norm(grad_f - exact, axis=1)
h = 1.0 / (n - 1)
interior = (cx > 2 * h) & (cx < 1 - 2 * h) & (cy > 2 * h) & (cy < 1 - 2 * h)
print(f"max |grad f - exact| : {err.max():.3e}")
print(f"interior max error   : {err[interior].max():.3e}")
max |grad f - exact| : 2.844e-01
interior max error   : 5.152e-02

The reconstruction is accurate in the interior; accuracy drops near the boundary, where all k neighbours lie on one side of the cell.

Gradient on a target mesh

Passing a second mesh moves the evaluation to its cell centroids — useful to compute a gradient on a coarser or differently-shaped mesh, or on the boundary of the source.

tgt = mf.build_cmesh(np.linspace(0.05, 0.95, 15), np.linspace(0.05, 0.95, 15))
grad_tgt = mf.Gradient(src, tgt, k=12)
grad_tgt.eval("f")["QUAD4"].shape
(196, 2)

Gradient at arbitrary points

mf.Gradient.at_points takes the evaluation points explicitly as an (n, d) array; grad.eval_points("f") then returns the (n, d) gradient directly. This is convenient to sample the gradient along a curve or at sparse probes.

t = np.linspace(0.0, 1.0, 120)
curve = np.c_[t, 0.5 + 0.3 * np.sin(2 * np.pi * t)]
grad_pts = mf.Gradient.at_points(src, curve, k=12)
grad_curve = grad_pts.eval_points("f")
grad_curve.shape
(120, 2)

Lazy fields, components and in-place results

Because grad("f") returns a lazy Field, it composes with the rest of the expression system: index the components with [0] / [1], combine them into derived quantities, and assign them to named target fields.

tgt.fields["dfdx"] = grad_tgt("f")[0]
tgt.fields["dfdy"] = grad_tgt("f")[1]
tgt.fields["grad_mag"] = (grad_tgt("f")[0].square() + grad_tgt("f")[1].square()).sqrt()

tgt.fields["grad_f"] = grad_tgt("f")
tgt.fields["grad_f"].numpy().shape
(196, 2)

Kernels and neighbour count

The kernel only changes how the local least-squares weights decay with distance:

  • Constant — an unweighted affine fit;
  • InverseDistance(exponent) — weight (h / r)**exponent;
  • CompactSupport(exponent) — a compactly-supported power kernel;
  • Gaussian — a bell-shaped kernel.

On a smooth field the kernel choice mostly changes the boundary. k balances locality against smoothness: a small k follows the field tightly and is the most accurate on smooth data, but is more sensitive to noise, while a large k averages over a wider stencil and smooths the reconstruction, at the cost of a larger error near the boundary.

for name, weighting in {
    "Constant": mf.DistanceWeighting.Constant(),
    "InverseDistance(2)": mf.DistanceWeighting.InverseDistance(2.0),
    "CompactSupport(2)": mf.DistanceWeighting.CompactSupport(2.0),
    "Gaussian": mf.DistanceWeighting.Gaussian(),
}.items():
    vals = np.asarray(mf.Gradient(src, k=12, weighting=weighting).eval("f")["QUAD4"])
    print(f"{name:18s} max |grad f - exact| = {np.abs(vals - exact).max():.3e}")
Constant           max |grad f - exact| = 2.407e-01
InverseDistance(2) max |grad f - exact| = 1.599e-01
CompactSupport(2)  max |grad f - exact| = 1.424e-01
Gaussian           max |grad f - exact| = 2.028e-01
for k in (4, 8, 16, 32):
    vals = np.asarray(mf.Gradient(src, k=k).eval("f")["QUAD4"])
    print(f"k = {k:2d}  max |grad f - exact| = {np.abs(vals - exact).max():.3e}")
k =  4  max |grad f - exact| = 1.222e-01
k =  8  max |grad f - exact| = 1.700e-01
k = 16  max |grad f - exact| = 3.360e-01
k = 32  max |grad f - exact| = 4.692e-01

3D gradients

The tool works in 3D space too; the gradient then has three components. On the linear field f = 1 + 2x - 3y + 4z the reconstruction is exact.

mesh3d = mf.build_cmesh(
    np.linspace(0.0, 1.0, 6), np.linspace(0.0, 1.0, 6), np.linspace(0.0, 1.0, 6)
)
mesh3d.fields["f"] = 1.0 + 2.0 * mf.X - 3.0 * mf.Y + 4.0 * mf.Z

grad3d = mf.Gradient(mesh3d, k=8)
vals3d = np.asarray(grad3d.eval("f")["HEX8"])
print(vals3d.shape, np.abs(vals3d - np.array([2.0, -3.0, 4.0])).max())
(125, 3) 4.973799150320701e-14

Scope and caveats

The MLS fit needs a full-dimensional neighbourhood: a 2D region for a 2D space, a 3D volume for a 3D space. A lower-dimensional mesh embedded in a higher-dimensional space — a surface in 3D, a line in 2D — has a rank-deficient local geometry, so the operator returns a zero gradient there instead of failing:

# A planar quad mesh living in 3D: locally rank-deficient, gradient is zero.
flat = mf.build_cmesh(np.linspace(0.0, 1.0, 6), np.linspace(0.0, 1.0, 6))
planar = mf.UMesh(np.c_[flat.coords(), np.zeros(len(flat.coords()))])
planar.add_regular_block("QUAD4", flat.blocks()["QUAD4"])
planar.fields["f"] = 2.0 * mf.X - 3.0 * mf.Y

vals = np.asarray(mf.Gradient(planar, k=8).eval("f")["QUAD4"])
print(vals.shape, np.abs(vals).max())
(25, 3) 0.0

Treat mf.Gradient as a meshless differential operator built on the same machinery as the field transfers: build it once, then reuse it for every scalar field and every time step.