Finite element implementation notes for a hyperelastostatic problem
Overview
Recently, I was asked to verify the implementation of a compressible Neo-Hookean model, so I chose a finite-deformation static problem as my second target task.
In MFEM 01, a linear elastic bar was solved entirely with MFEM's built-in integrators. Here the material is hyperelastic and the deformation is finite, so I write the two things MFEM cannot provide for me: the material model, and the element residual and tangent that go with it. Everything else, from the mesh to Newton's method, is still MFEM.
As in MFEM 01, I walk through the code in the order in which it is executed, placing each part alongside the corresponding formula it implements. The driver is 3d-elastostatics.cpp; the material model and the integrator are header files in include/. The full code is available at Chongran-Zhao/mfem-solids.
Problem setting
A body occupies Ω0 in its undeformed (reference) configuration, and X labels its material points. A displacement u(X) carries each point to x=X+u. Deformation is finite, loads are applied slowly enough that inertia is negligible (quasi-static), and every quantity is written on Ω0.
Here the body is a beam, Ω0=[0,1]×[0,0.1]×[0,0.1]. The left end X=0 is clamped, the right end X=1 is moved vertically by a prescribed uy=uˉ, and the four lateral faces are traction-free. The reference case raises uˉ from 0 to 0.5 in 25 load steps; the driver below solves the first one, uˉ=0.02.
The deformation is measured by
F=I+Gradu,J=detF,C=FTF,E=21(C−I),
where Grad is the gradient with respect to X. Capitalized operators, Grad and Div, always act on the reference coordinates X.
Balance of linear momentum without inertia, written on Ω0, is DivP+B=0, with B the body force per reference volume. Body force is neglected here (B=0), as in the code. The strong form is then
DivP=0 in Ω0,essentialu=uˉ on ΓD,naturalPN=Tˉ on ΓN(1)
N the reference outward normal, Tˉ the traction per reference area, and ∂Ω0=ΓD∪ΓN. For the beam, Tˉ=0.
P is not symmetric. The symmetric stress work-conjugate to E is the second Piola–Kirchhoff stress S, related by P=FS.
Notation. From here on two kinds of objects appear side by side, and they are written differently:
Tensors are continuous fields with a direct physical meaning, such as uh, Fh and Ph. They are written in bold italic, F, and their components carry tensor indices, FkJ.
Discrete finite element quantities are arrays of numbers built from nodal values, such as the element displacement vector or the element stiffness matrix. They are written in sans-serif, d, and their entries are counted by mesh indices.
Mesh. The body is divided into elements, Ω0≈⋃eΩe. Mesh indices are written in bold upright letters, to keep them apart from the tensor indices i,j,k,l and I,J,K,L:
e numbers the elements;
a,b number the nodes of one element, from 1 to n;
A numbers the nodes of the whole mesh.
As for the bar, a connectivity table A=ℓ(e,a) gives the global number of local node a of element e.
The mesh is the reference configuration, and it never moves. In the Total Lagrangian form the node coordinates stay at X; the deformation lives only in the displacement.
The coarse beam has 80 hexahedra (20×2×2) and 189 vertices. The mesh file labels its boundary faces with attributes:
fec is the trilinear hexahedron, with n=8 nodes and shape functions Na. fespace puts three components on each node, vdim = dim = 3, so the beam has 3×189=567 displacement unknowns, and disp holds their values.
Interpolation on one element. Node a sits at the reference position Xa and carries three numbers dka, k=1,2,3, its displacement in the three coordinate directions. Inside Ωe, the displacement field and the test function are interpolated from these nodal values with the shape functions of the element, the scalar functions Na(X):
The superscript h marks discrete fields. The left-hand sides are components of the tensor fields uh and wh; the right-hand sides mix the two kinds of objects: all the dependence on position is carried by Na(X), and the nodal values dka, wka are just numbers. Since Na(Xb)=δab, evaluating ukh at node b returns dkb, so dka is exactly the displacement of node a in direction k.
Deformation gradient. Since FkJh=δkJ+∂ukh/∂XJ and the nodal values do not depend on X, only the shape functions are differentiated:
FkJh=δkJ+a=1∑ndkaN,Ja.(3)
So the tensor Fh, and through the material law also Ch, Sh and Ph, is known once the nodal displacements dka and the shape function gradients N,Ja are known.
Collected over the nodes a and directions k of the element, the nodal displacements form the element displacement vector, numbered direction by direction as in the code (disp(aa + k*num_nodes), step 6):
(de)P=dka,P=a+(k−1)n,de∈R3n.
byVDIM only orders the global vector, node by node: x1,y1,z1,x2,… The element vectors that the integrator receives are always ordered direction by direction (step 7), whatever the global ordering.
disp is a function, not just a vector: its values are the nodal displacements dkA, and fespace supplies the shape functions.
Unlike the bar, each direction has its own list of constrained boundaries, and the last argument of GetEssentialTrueDofs picks the component. The three lists are merged into ess_tdof_list, 36 unknowns in total.
On the right end only uy is prescribed; ux and uz remain unknown there.
Uh={uh:dkA=uˉkA for every constrained (A,k)},Vh={wh:wkA=0 for every constrained (A,k)}
ProjectBdrCoefficient writes uˉ=0.02 into the y-components of disp on attribute 2. The nullptr entries leave x and z untouched, and the left end keeps the zeros of step 2.
This step only collects indices and values. They are imposed in step 9, where Newton's method starts from disp and never changes the constrained entries.
4. Material model
constdouble young = 540.0e3;
constdouble poisson = 0.324;
constdouble mu = young / (2.0 * (1.0 + poisson));
constdouble kappa = young / (3.0 * (1.0 - 2.0 * poisson));
const CompressibleNeoHookean material(kappa, mu);
Symbol
Variable
Value
E
young
540 kPa
ν
poisson
0.324
μ=E/2(1+ν)
mu
203.9 kPa
κ=E/3(1−2ν)
kappa
511.4 kPa
The compressible Neo-Hookean model splits the strain energy into an isochoric and a volumetric part,
Ψ=2μ(J−2/3trC−3)+2κ(J−1)2,
and CompressibleNeoHookean returns its first two derivatives with respect to C:
with (A⊗B)IJKL=AIJBKL and (A⊙B)IJKL=21(AIKBJL+AILBJK). From these two, the base class HyperelasticMaterialModel builds the two-point quantities that the integrator needs:
The material only sees F. It knows nothing about elements, nodes or quadrature, so the same integrator works for any model derived from HyperelasticMaterialModel.
P enters the residual (step 6) and A the tangent (step 7); step 7 shows where the formula for A comes from.
Take a test function w that vanishes where the displacement is prescribed, w=0 on ΓD. Multiply Eq. (1) by it and integrate over the body,
∫Ω0w⋅DivPdV=0.(4)
The integrand contains a derivative of P, which is what the weak form moves onto w. The product rule for a divergence, written with indices (PkJ,J=∂PkJ/∂XJ), is
We use lowercase indices such as i,j,k,l to denote the basis components associated with the current configuration, and uppercase indices such as I,J,K,L to denote those associated with the reference configuration. The first Piola–Kirchhoff stress P is a two-point tensor, with one index referring to the current configuration and the other to the reference configuration, so its components are written as PkJ. The test function wk is defined over the reference configuration. Note that all these indices refer to three-dimensional space and therefore take values 1,2,3.
so the integral in Eq. (4) splits into a divergence and a term with Gradw,
∫Ω0w⋅DivPdV=∫Ω0Div(PTw)dV−∫Ω0P:GradwdV=0.
The divergence theorem turns the first integral into a boundary integral, and (PTw)⋅N=w⋅PN,
From the body to one element. The weak form, Eq. (5), is a single statement about the whole body: the balance of momentum, tested against every admissible w. Its integrals, however, are additive over non-overlapping pieces. The elements cover Ω0, and their faces on ΓN cover ΓN, so moving everything to one side, Eq. (5) becomes a sum of element contributions,
e∑[∫ΩeP:GradwdV−∫∂Ωe∩ΓNTˉ⋅wdA]=0.
Each bracket only involves the fields inside one element, and those are described by the nodal values of that element through the interpolation of step 2.
NonlinearForm is the sum over elements; the integrator is one bracket. MFEM loops over the elements and adds up their contributions (step 9); the integrator only has to evaluate the bracket of one element, which is what steps 6 and 7 derive.
AddDomainIntegrator only stores a pointer: nonlinear_form owns the integrator and deletes it, while the integrator keeps a reference to material, which must therefore outlive nonlinear_form.
There is no traction integrator: Tˉ=0 on the free faces, so the boundary integral vanishes.
6. Element residual
Insert the interpolation of step 2 into the bracket of element e. With the same shape functions for u and w (Galerkin), P becomes Ph=P(Fh). Writing P:Gradw=∑k,JPkJwk,J and Tˉ⋅w=∑kTˉkwk, the bracket reads
∫Ωek,J∑PkJhwk,JhdV−∫∂Ωe∩ΓNk∑TˉkwkhdA.
A note on sums. The summation convention is not used in this note: every sum is written out with an explicit ∑. This matters because two kinds of indices appear side by side, tensor indices (i,j,k,l and I,J,K,L) and mesh indices (a, b, e), and the derivation below moves sums of both kinds in and out of integrals. With every sum visible, it is always clear which indices are summed and which are free.
Take the bracket of one element and follow it through four steps.
Step 1: substitute the interpolation. Inside Ωe the test function and its gradient are
wkh=a∑Nawka,wk,Jh=a∑N,Jawka,
where only Na is differentiated, since the nodal values wka are constants. The bracket becomes
Step 2: put all the sums in front. The first integrand now contains three sums, over k, J and a; the second contains two, over k and a. Moving the inner sum over a out of the parentheses,
Step 3: reorder the sums and take them out of the integrals. Finite sums can be taken in any order, so put a and k outermost and leave J inside. Integration is linear and wka does not depend on X, so both the sums over a,k and the factor wka come out of the integrals:
Collected over the nodes a and directions k of the element, these components form the element residual vector. As in the code, the entries are numbered direction by direction, first the x-components of the n nodes, then y, then z:
(Re)P=Rka,P=a+(k−1)n,Re∈R3n.
The code.AssembleElementVector evaluates Eq. (6) without the traction term:
The function name is fixed.AssembleElementVector overrides a virtual function of NonlinearFormIntegrator, and NonlinearForm calls it through a base-class pointer. Only the parameter names are ours.
The element vectors are ordered direction by direction: first the x-components of the n nodes, then y, then z. GetElementVDofs always returns them in this order, independently of the byVDIM global ordering of step 2.
elem is the reference element, shared by all hexahedra, and only knows N^a(ξ); elem_map knows the node coordinates of this element and supplies (∂X/∂ξ)−1 and its determinant.
In the driver, one call evaluates the global residual at the displacement of step 3:
Mult calls AssembleElementVector once per element and adds the results into residual (step 9). Only the right-end nodes have moved, so the elements next to them are strained and the residual is far from zero; Newton's method will remove it.
7. Element stiffness
From the field uh to the nodal values de. Eq. (6) writes the residual in terms of the field uh, but a field cannot be the unknown of a program; the unknowns are the nodal values. On Ωe the two carry the same information: by Eq. (2) the field is fixed by the element's nodal displacements,
ukh(X)=b=1∑nNb(X)dkb,
so, with the nodal values collected in de, the residual is a function of de alone, Rka(de):=Rka(uh[de]). The map from de to uh is linear, and its derivatives are just the shape functions,
∂dlb∂ukh=δklNb,∂dlb∂FkJh=δklN,Jb.
Differentiating with respect to one nodal value dlb therefore means: move node b in direction l; the field uh changes by Nb in that direction, and Fh by N,Jb in row l.
Re is nonlinear in de, so the equations it leads to are solved by Newton's method (step 9), and Newton's method needs the derivative of the residual. That derivative is computed element by element. Perturb the element displacements by Δde and expand the element residual to first order:
Re(de+Δde)≈Re(de)+KeΔde,Ke=∂de∂Re.
Ke is the element stiffness matrix. Written entry by entry, with Ke=[Kklab], the same expansion reads
Kklab says how much the residual at node a, direction k, changes when node b moves in direction l. The rest of this step computes it from this component definition.
Step 1: start from the definition. Insert the element residual, Eq. (6), into Eq. (7). The shape functions and the element domain do not depend on de, and neither does the traction term (a dead load), so the derivative passes through the integral and acts only on Ph:
Step 3: the two derivatives. The first was found at the start of this step. The second goes through the strain, with the material elasticity tensor Ch=∂Sh/∂Eh, which is symmetric in IJ and in KL:
since ∂EKLh/∂dlb=21(N,KbFlLh+FlKhN,Lb) and the minor symmetry of Ch merges the two halves. Renaming I→L in the first term (and using SLJh=SJLh), both terms end in N,Lb:
The bracket is the first elasticity tensor Ah=∂Ph/∂Fh of step 4: the residual needs Ph, and the tangent needs Ah, with one shape function gradient on each side.
From Kklab to Ke. The element stiffness matrix of Eq. (7) stores these components. Each pair (node, direction) is one element unknown, and the unknowns are numbered direction by direction, as in MFEM: first the x-components of nodes 1,…,n, then the y-components, then the z-components. The pair (a,k) is therefore unknown number a+(k−1)n, and
(Ke)PQ=Kklab,P=a+(k−1)n,Q=b+(l−1)n,Ke∈R3n×3n.
The row P comes from the residual, node a in direction k; the column Q from the displacement, node b in direction l. Grouping the rows and columns by direction, Ke is a 3×3 array of n×n blocks, one block for each pair of directions (k,l), and inside a block the nodes (a,b) pick the entry:
and Rka in the same way. At each point ξq the integrand is evaluated from the current de: Fh, then Sh and Ch from the material law, then Ah. quad_pt.weight is ωq and elem_map.Weight() is det(∂X/∂ξ); their product is dV.
How many points. The code uses linear hexahedra (H1_FECollection of order 1), and get_quad_rule asks MFEM for a Gauss rule exact up to degree 2× (degree of GradNa):
The factor 2. The integrand of Kklab contains two shape function gradients, N,Ja and N,Lb. In linear elasticity Ah is constant and the integrand is then a polynomial of degree 4, so the rule is exact in the small-strain limit.
Three points per direction. A 1D Gauss rule with m points is exact up to degree 2m−1, so degree 4 needs m=3, and the hexahedron uses the tensor product, 33=27 points.
Not exact, but consistent. The Neo-Hookean Ah is not a polynomial in ξ, so the rule is accurate rather than exact. What matters more is that the residual and the tangent use the same rule (both call get_quad_rule): only then is Ke the exact derivative of the discrete Re, and Newton's method converges quadratically.
Everything above happens inside one element, and it is all the integrator has to provide: AssembleElementVector returns Re and AssembleElementGrad returns Ke. The rest is done by MFEM.
Assembly.NonlinearForm loops over the elements, calls the integrator, and adds Re and Ke into the global R and K at the global numbers returned by GetElementVDofs, the local unknown (a,k) going to the global unknown (ℓ(e,a),k). A node shared by several elements receives the sum of their contributions, RkA=∑e∋ARka(e), and K is assembled the same way.
Newton's method. The discrete problem is RkA(d)=0 for every free unknown. NewtonSolver repeats: assemble R and K at the current d, solve KΔd=−R, update d←d+Δd, until R≈0. Since Ke is the exact derivative of Re, the convergence is quadratic.
∥R(d)∥≤10−8∥R(d0)∥
zero_rhs is empty, which tells NewtonSolver to solve R(d)=0.
iterative_mode = true is essential. It makes Newton start from disp_true, which carries the prescribed uˉ of step 3; with the default false, Newton would first set the initial guess to zero and wipe out the boundary values.
CG applies because K is symmetric: AkJlLh=AlLkJh, and replacing constrained rows and columns by the identity keeps the symmetry. Each linear solve only needs to be accurate to 10−6, since Newton corrects it in the next iteration.
SetPrintLevel(1) prints the residual norm of every iteration, and quadratic convergence, the norm roughly squaring from one iteration to the next, is the most direct check of the integrator.
SetFromTrueDofs copies the solution back into disp, the finite element function.
First edited on Sep. 26, 2026.
Writing this post was truly exhausting. I read a lot of code and textbooks, and revised the content again and again until it reflected what I was actually thinking. Of course, I used AI agents to help me organize the whole article.
I do find MFEM useful. It focuses on solving differential equations, so you have to derive the weak form yourself. Once that first step is done, however, the structure extends naturally to more specific problems, such as hyperelastodynamics, and it stays really clear.