Field kernels

The derived values that Construct computes from the fields of a solve

A field kernel is a derived value that Construct computes from the fields of an item, at each node or at each element. The von Mises stress, the factor of safety and the length of a displacement are kernels. A solve stores the primary fields: the displacement, the stress and the strain. A kernel turns them into the value you read.

Each kernel is one short function in GLSL, the shading language of the GPU. Construct runs the same text on the CPU, for a value, a minimum or an export, and on the GPU, to color the surface. So the value you read at a point is the value that colors that point.

On the GPU, the viewport sends the kernel's input fields to the vertex shader of the item, and the shader runs the kernel at each node. A change to another kernel over the same fields, for example from von Mises to Tresca, sends no new data. A change of a kernel parameter shows in the next frame. The range of the legend follows when Construct has computed the values on the CPU. A stored vector, such as displacement, shows its length through the magnitude kernel in the same way.

What a solve stores

A solve stores these fields in the volume's file. Each field carries a description: its name, what it measures, its unit and where it sits.

Field	Sits at	What it holds
`displacement`	Each node	How far the node moves, in world axes, in mm
`stress`	Each element	The stress tensor at the element's center, in MPa
`stress_nodal`	Each node	The stress tensor averaged over the elements around the node, in MPa
`strain`	Each element	The strain tensor at the element's center
`yield`	Each element	The yield strength of the element's material, in MPa. Only when the material has one

A tensor holds six values per node or element: xx, yy, zz, yz, xz and xy. A VTK viewer reads the file, and shows each tensor.

The kernels

Kernel	Takes	Gives	Unit
`magnitude`	A vector	Its length	The vector's
`component`	A vector or a tensor, and an axis	One component	The input's
`von_mises`	A stress tensor	The von Mises stress	The stress's
`signed_von_mises`	A stress tensor, and a sign rule	The von Mises stress with the sign of the mean stress, or of the largest principal stress	The stress's
`tresca`	A stress tensor	The largest principal stress minus the smallest	The stress's
`principal`	A stress or strain tensor, and 1, 2 or 3	One principal value, 1 the largest	The input's
`max_shear`	A stress tensor	Half the Tresca stress	The stress's
`hydrostatic`	A stress tensor	The mean normal stress, positive in tension	The stress's
`pressure`	A stress tensor	The mean normal stress, positive in compression	The stress's
`percent_of_limit`	A stress tensor, a limit, and a criterion	The equivalent stress as a percent of the limit	%
`tension_compression`	A stress tensor	+1 in tension, −1 in compression	None
`factor_of_safety`	A stress tensor, a limit, and a criterion	The limit over the equivalent stress	None
`threshold`	A value, a low end and a high end	How far the value is inside the band	The value's
`difference`	Two values or two vectors	The first minus the second	The first's
`deformed_offset`	A displacement, a scale and a rotation	How far a node moves on the deformed shape	The displacement's

The criterion of the factor of safety and of the percent of the limit is one of three:

von_mises: the von Mises stress against the yield strength. The default, for a ductile material such as steel.
max_principal: the largest principal stress against the ultimate strength, for a brittle material.
tresca: the Tresca stress against the yield strength.

Where the stress is zero, the factor of safety has no upper limit. A probe and OPAL report it as infinite.

How a kernel finds its inputs

A kernel takes its inputs by what they measure, not by their names. The von_mises kernel takes any stress tensor. When an item has one field that fits each input, the kernel uses it. When two fit, for example stress and stress_nodal, you choose one. So a kernel works for every solver that writes a stress tensor.

The OPAL task construct.field.kernels lists every kernel. With item, it also lists the ways each kernel fits the item's fields:

{"task": "construct.field.kernels", "args": {"item": "Bar"}}

The fields that Construct shows

Tet ▸ Field lists these fields of a solved volume. Each one is a kernel over the stored fields:

Field shown	Kernel
`von_mises_stress`	`von_mises` over `stress_nodal`
`von_mises_stress_element`	`von_mises` over `stress`
`factor_of_safety`	`factor_of_safety` over `stress` and `yield`, at each element

A file that a solve wrote before 2026-10-15 holds these fields as stored values, and shows them as they are.

After these fields, the menu lists each other kernel that fits the stored fields, by its label and its inputs, for example "Tresca stress (stress)". The color presenter takes the default range mode of the kernel: robust for a stress, targets for the factor of safety, full for the others. See Fields.

Add a kernel

A kernel is a file and an entry. The files are in src/libs/libfield/field/kernels/:

Write <id>.glsl with one function, kernel_<id>. The function reads only its arguments. A tensor argument is two vec3: the diagonal and the shear.
Add an entry for <id> to catalog.yaml: its inputs, parameters, unit and sign.
Build. testFieldKernels compiles every kernel, and testFieldKernelsGpu compares every kernel on the GPU with the CPU. testFieldSplice compiles every kernel into the vertex shaders of the tet volume and the mesh items.

No C++ changes.