Math on Meshes

November 18, 2026
VTK Logo

In my very first numpy blog back in 2014, I closed with a teaser: the gradient of a field on an unstructured grid, “a concept that does not exist in numpy”. A few blogs ago, I also said there was a lot more to say about vtkmodules.util.functions. Let’s say it.

By now, VTK arrays do everything numpy does on values and tuples. What numpy doesn’t have is the mesh: which points are neighbors, how big a cell is, what a derivative means on a tetrahedron. That’s what functions is for.

A vortex

Let’s make a velocity field we know the answers for: solid-body rotation about the z axis, u = (-y, x, 0). Its vorticity is (0, 0, 2) everywhere, and its divergence is zero.

>>> import numpy as np
>>> from vtkmodules import vtkImagingCore as imaging_core
>>> from vtkmodules.util import functions
>>> w = imaging_core.vtkRTAnalyticSource()()
>>> pts = w.points.data
>>> x, y = pts[:, 0], pts[:, 1]
>>> w.point_data['velocity'] = functions.make_vector(-y, x)
>>> u = w.point_data['velocity']
>>> omega = functions.vorticity(u)
>>> omega.min(axis=0), omega.max(axis=0)
(array([0., 0., 2.]), array([0., 0., 2.]))
>>> abs(functions.divergence(u)).max()
np.float64(0.0)

A few things to note:

  • We never told vorticity() about the mesh. u came from point_data, so it knows its dataset, and functions finds the mesh through the array.
  • x and y are columns of the image’s implicit point array (see my last blog), and make_vector() builds a 3-component array out of them, with z set to zero.
  • The answers are exact. The field is linear, so cell derivatives get it right to the last bit.

The result is an ordinary VTK array with a name (omega.name is 'vorticity') and the same dataset, so w.point_data['vorticity'] = omega puts it right back.

Tensors

The gradient of a vector field is a tensor. Let’s switch to a simple shear flow, u = (y, 0, 0), whose strain rate has principal values of plus and minus one half:

>>> w.point_data['shear'] = functions.make_vector(y, np.zeros(w.number_of_points))
>>> shear = w.point_data['shear']
>>> functions.vorticity(shear)[0]
array([ 0.,  0., -1.])
>>> s = functions.strain(shear)
>>> s.shape, s[0]
((9261, 9), array([0. , 0.5, 0. , 0.5, 0. , 0. , 0. , 0. , 0. ]))
>>> functions.eigenvalue(s)[0]
array([ 0.5,  0. , -0.5])

VTK stores a tensor as 9 components per tuple, row by row, so strain() and gradient() return (n, 9) arrays, and the per-tuple matrix functions (det(), trace(), inverse(), eigenvalue(), eigenvector()) take them as they are. One thing to know: eigenvalue() and eigenvector() only handle symmetric tensors, like strain. Hand them a non-symmetric one, such as the velocity gradient itself, and you get zeros back.

Same code, any mesh

None of this cares what kind of mesh it runs on. Let’s cut the image into tetrahedra and do it again:

>>> from vtkmodules import vtkFiltersGeneral as filters_general
>>> tets = filters_general.vtkDataSetTriangleFilter()(w)
>>> tets.GetClassName(), tets.number_of_cells
('vtkUnstructuredGrid', 40000)
>>> omega = functions.vorticity(tets.point_data['velocity'])
>>> omega.min(axis=0), omega.max(axis=0)
(array([0., 0., 2.]), array([0., 0., 2.]))

Same answer on 40000 tetrahedra. And now that we have cells worth asking about, functions has the cell quality measures too (area, volume, aspect, jacobian, skew etc.). These take the dataset and return cell data:

>>> vol = functions.volume(tets)
>>> vol.sum()
np.float64(8000.0)
>>> vol.min(), vol.max()
(np.float64(0.16666666666666666), np.float64(0.3333333333333333))
>>> ar = functions.aspect(tets)
>>> ar.min(), ar.max()
(np.float64(0.9999999999999999), np.float64(1.3660254037844386))
>>> tets.cell_data['volume'] = vol

The wavelet’s box is 20 on a side, and its 40000 tetrahedra add up to 8000. Good.

Under the covers

The mesh-aware functions and the matrix functions each run a VTK filter: vtkCellDerivatives for the derivatives, vtkCellQuality for the quality measures, vtkMatrixMathFilter for the per-tuple matrix math. So they are only as good as those filters, and one thing is worth knowing. For point data, derivatives are computed per cell and then averaged to the points. That’s exact for a linear field, like the ones above, and an approximation otherwise. The curl of a gradient should be zero:

>>> grad = functions.gradient(w.point_data['RTData'])
>>> abs(functions.curl(grad)).max(), abs(grad).max()
(np.float64(0.4411312937736511), np.float64(34.781060218811035))

Small, but not zero.

If you are coming from my 2014 blogs, note that the old numpy_interface.algorithms module (algs.gradient() and friends) only works with dataset_adapter, which is deprecated. On the new arrays it fails with an AttributeError. functions is where those algorithms live now.

In my next blog, I will step back from arrays to the datasets they live in, and build points and cells straight from numpy.

Tags:
VTK

Leave a comment