Skip to content
← Notes

MFEM 02

17 min read

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\Omega_0 in its undeformed (reference) configuration, and X\bm X labels its material points. A displacement u(X)\bm u(\bm X) carries each point to x=X+u\bm x = \bm X + \bm u. Deformation is finite, loads are applied slowly enough that inertia is negligible (quasi-static), and every quantity is written on Ω0\Omega_0.

Here the body is a beam, Ω0=[0,1]×[0,0.1]×[0,0.1]\Omega_0 = [0, 1] \times [0, 0.1] \times [0, 0.1]. The left end X=0X = 0 is clamped, the right end X=1X = 1 is moved vertically by a prescribed uy=uˉu_y = \bar u, and the four lateral faces are traction-free. The reference case raises uˉ\bar u from 0 to 0.5 in 25 load steps; the driver below solves the first one, uˉ=0.02\bar u = 0.02.

The deformation is measured by

F=I+Grad⁡u,J=det⁡F,C=FTF,E=12(C−I), \bm F = \bm I + \operatorname{Grad}\bm u, \qquad J = \det \bm F, \qquad \bm C = \bm F^{\mathrm{T}} \bm F, \qquad \bm E = \tfrac12 (\bm C - \bm I),

where Grad⁡\operatorname{Grad} is the gradient with respect to X\bm X. Capitalized operators, Grad⁡\operatorname{Grad} and Div⁡\operatorname{Div}, always act on the reference coordinates X\bm X.

Balance of linear momentum without inertia, written on Ω0\Omega_0, is Div⁡P+B=0\operatorname{Div}\bm P + \bm B = \bm 0, with B\bm B the body force per reference volume. Body force is neglected here (B=0\bm B = \bm 0), as in the code. The strong form is then

  Div⁡P=0   in Ω0,u=uˉ   on ΓD⏟essential,P N=Tˉ   on ΓN⏟natural  (1) \boxed{\; \operatorname{Div} \bm P = \bm 0 \;\text{ in } \Omega_0, \qquad \underbrace{\bm u = \bar{\bm u} \;\text{ on } \Gamma_D}_{\text{essential}}, \qquad \underbrace{\bm P\,\bm N = \bar{\bm T} \;\text{ on } \Gamma_N}_{\text{natural}} \;} \tag{1}
  • N\bm N the reference outward normal, Tˉ\bar{\bm T} the traction per reference area, and ∂Ω0=ΓD∪ΓN\partial\Omega_0 = \Gamma_D \cup \Gamma_N. For the beam, Tˉ=0\bar{\bm T} = \bm 0.
  • P\bm P is not symmetric. The symmetric stress work-conjugate to E\bm E is the second Piola–Kirchhoff stress S\bm S, related by P=FS\bm P = \bm F\bm S.

1. Mesh

const char *mesh_file = ".../Beam_coarse-hex.mesh";
mfem::Mesh mesh(mesh_file, 1, 1);

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\bm u^h, Fh\bm F^h and Ph\bm P^h. They are written in bold italic, F\bm F, and their components carry tensor indices, FkJF_{kJ}.
  • 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\mathsf d, and their entries are counted by mesh indices.

Mesh. The body is divided into elements, Ω0≈⋃eΩe\Omega_0 \approx \bigcup_\mathbf{e} \Omega^\mathbf{e}. Mesh indices are written in bold upright letters, to keep them apart from the tensor indices i,j,k,li,j,k,l and I,J,K,LI,J,K,L:

  • e\mathbf{e} numbers the elements;
  • a,b\mathbf{a}, \mathbf{b} number the nodes of one element, from 11 to nn;
  • A\mathbf{A} numbers the nodes of the whole mesh.

As for the bar, a connectivity table A=ℓ(e,a)\mathbf{A} = \ell(\mathbf{e}, \mathbf{a}) gives the global number of local node a\mathbf{a} of element e\mathbf{e}.

  • The mesh is the reference configuration, and it never moves. In the Total Lagrangian form the node coordinates stay at X\bm X; the deformation lives only in the displacement.
  • The coarse beam has 80 hexahedra (20×2×220 \times 2 \times 2) and 189 vertices. The mesh file labels its boundary faces with attributes:
Boundary faces Location Attribute
left end X=0X = 0 1
right end X=1X = 1 2
lateral faces Y,Z∈{0,0.1}Y, Z \in \{0, 0.1\} 3 to 6

2. Finite element space and interpolation

const int dim = mesh.Dimension();
const int order = 1;
mfem::H1_FECollection fec(order, dim);
mfem::FiniteElementSpace fespace(&mesh, &fec, dim,
                                mfem::Ordering::byVDIM);
mfem::GridFunction disp(&fespace);
disp = 0.0;

fec is the trilinear hexahedron, with n=8n = 8 nodes and shape functions NaN^\mathbf{a}. fespace puts three components on each node, vdim = dim = 3, so the beam has 3×189=5673 \times 189 = 567 displacement unknowns, and disp holds their values.

Interpolation on one element. Node a\mathbf{a} sits at the reference position Xa\bm X^\mathbf{a} and carries three numbers dkad^\mathbf{a}_k, k=1,2,3k = 1,2,3, its displacement in the three coordinate directions. Inside Ωe\Omega^\mathbf{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)N^\mathbf{a}(\bm X):

ukh(X)=∑a=1nNa(X) dka,wkh(X)=∑a=1nNa(X) wka,X∈Ωe.(2) \tag{2} u^h_k(\bm X) = \sum_{\mathbf{a}=1}^{n} N^\mathbf{a}(\bm X)\, d^\mathbf{a}_k, \qquad w^h_k(\bm X) = \sum_{\mathbf{a}=1}^{n} N^\mathbf{a}(\bm X)\, w^\mathbf{a}_k, \qquad \bm X \in \Omega^\mathbf{e} .

The superscript hh marks discrete fields. The left-hand sides are components of the tensor fields uh\bm u^h and wh\bm w^h; the right-hand sides mix the two kinds of objects: all the dependence on position is carried by Na(X)N^\mathbf{a}(\bm X), and the nodal values dkad^\mathbf{a}_k, wkaw^\mathbf{a}_k are just numbers. Since Na(Xb)=δabN^\mathbf{a}(\bm X^\mathbf{b}) = \delta_{\mathbf{a}\mathbf{b}}, evaluating ukhu^h_k at node b\mathbf{b} returns dkbd^\mathbf{b}_k, so dkad^\mathbf{a}_k is exactly the displacement of node a\mathbf{a} in direction kk.

Deformation gradient. Since FkJh=δkJ+∂ukh/∂XJF^h_{kJ} = \delta_{kJ} + \partial u^h_k / \partial X_J and the nodal values do not depend on X\bm X, only the shape functions are differentiated:

FkJh=δkJ+∑a=1ndka N,Ja.(3) F^h_{kJ} = \delta_{kJ} + \sum_{\mathbf{a}=1}^{n} d^\mathbf{a}_k\, N^\mathbf{a}_{,J} . \tag{3}

So the tensor Fh\bm F^h, and through the material law also Ch\bm C^h, Sh\bm S^h and Ph\bm P^h, is known once the nodal displacements dkad^\mathbf{a}_k and the shape function gradients N,JaN^\mathbf{a}_{,J} are known.

Collected over the nodes a\mathbf{a} and directions kk 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. \big(\mathsf d^\mathbf{e}\big)_P = d^\mathbf{a}_k, \qquad P = \mathbf{a} + (k-1)\,n, \qquad \mathsf d^\mathbf{e} \in \mathbb R^{3n} .
  • byVDIM only orders the global vector, node by node: x1,y1,z1,x2,…x_1, y_1, z_1, x_2, \dots 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 dkAd^\mathbf{A}_k, and fespace supplies the shape functions.

3. Boundary conditions

mfem::Array<int> ess_bdr_x(mesh.bdr_attributes.Max());
mfem::Array<int> ess_bdr_y(mesh.bdr_attributes.Max());
mfem::Array<int> ess_bdr_z(mesh.bdr_attributes.Max());
ess_bdr_x = 0;
ess_bdr_y = 0;
ess_bdr_z = 0;
ess_bdr_x[0] = 1;
ess_bdr_y[0] = 1;
ess_bdr_y[1] = 1;
ess_bdr_z[0] = 1;

mfem::Array<int> ess_tdof_x, ess_tdof_y, ess_tdof_z, ess_tdof_list;
fespace.GetEssentialTrueDofs(ess_bdr_x, ess_tdof_x, 0);
fespace.GetEssentialTrueDofs(ess_bdr_y, ess_tdof_y, 1);
fespace.GetEssentialTrueDofs(ess_bdr_z, ess_tdof_z, 2);
ess_tdof_list.Append(ess_tdof_x);
ess_tdof_list.Append(ess_tdof_y);
ess_tdof_list.Append(ess_tdof_z);
Direction Attribute 1 (left end) Attribute 2 (right end)
xx fixed, ux=0u_x = 0 free
yy fixed, uy=0u_y = 0 prescribed, uy=uˉu_y = \bar u
zz fixed, uz=0u_z = 0 free
  • 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 uyu_y is prescribed; uxu_x and uzu_z remain unknown there.
const double prescribed_uy = 0.02;
mfem::ConstantCoefficient right_uy(prescribed_uy);
mfem::Coefficient *right_disp[3] = {nullptr, &right_uy, nullptr};
mfem::Array<int> right_bdr(mesh.bdr_attributes.Max());
right_bdr = 0;
right_bdr[1] = 1;
disp.ProjectBdrCoefficient(right_disp, right_bdr);
Uh={ uh:dkA=uˉkA for every constrained (A,k) },Vh={ wh:wkA=0 for every constrained (A,k) } \mathcal U^h = \{\, \bm u^h : d^\mathbf{A}_k = \bar u^\mathbf{A}_k \text{ for every constrained } (\mathbf{A}, k) \,\}, \qquad \mathcal V^h = \{\, \bm w^h : w^\mathbf{A}_k = 0 \text{ for every constrained } (\mathbf{A}, k) \,\}
  • ProjectBdrCoefficient writes uˉ=0.02\bar u = 0.02 into the yy-components of disp on attribute 2. The nullptr entries leave xx and zz 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

const double young = 540.0e3;
const double poisson = 0.324;
const double mu = young / (2.0 * (1.0 + poisson));
const double kappa = young / (3.0 * (1.0 - 2.0 * poisson));
const CompressibleNeoHookean material(kappa, mu);
Symbol Variable Value
EE young 540 kPa
ν\nu poisson 0.324
μ=E/2(1+ν)\mu = E / 2(1+\nu) mu 203.9 kPa
κ=E/3(1−2ν)\kappa = E / 3(1-2\nu) kappa 511.4 kPa

The compressible Neo-Hookean model splits the strain energy into an isochoric and a volumetric part,

Ψ=μ2(J−2/3tr⁡C−3)+κ2(J−1)2, \Psi = \frac{\mu}{2}\big( J^{-2/3} \operatorname{tr}\bm C - 3 \big) + \frac{\kappa}{2} (J - 1)^2 ,

and CompressibleNeoHookean returns its first two derivatives with respect to C\bm C:

Tensor2_3D get_2nd_PK_stress(const Tensor2_3D &F) const override
{
   ...
   return mu * J_m23 * Tensor2_3D::identity()
          + (kappa * det_F * (det_F - 1.0) - 1.0/3.0 * mu * J_m23 * tr_C )* C_inv;
}

Tensor4_3D get_2nd_elasticity_tensor(const Tensor2_3D &F) const override
{
   ...
   return -2.0 / 3.0 * mu * J_m23 * (otimes(Id, C_inv) + otimes(C_inv, Id))
         + (kappa * det_F * (2.0 * det_F - 1.0) + 2.0 * mu / 9.0 * J_m23 * tr_C) * otimes(C_inv, C_inv)
         - 2.0 * (kappa * det_F * (det_F - 1.0) - 1.0/3.0 * mu * J_m23 * tr_C) * odot(C_inv, C_inv);
}
S=2∂Ψ∂C=μJ−2/3 I+(κJ(J−1)−μ3J−2/3tr⁡C) C−1, \bm S = 2\frac{\partial\Psi}{\partial\bm C} = \mu J^{-2/3}\, \bm I + \Big( \kappa J (J - 1) - \frac{\mu}{3} J^{-2/3} \operatorname{tr}\bm C \Big)\, \bm C^{-1},
C=2∂S∂C=−2μ3J−2/3(I⊗C−1+C−1⊗I)+(κJ(2J−1)+2μ9J−2/3tr⁡C) C−1⊗C−1−2(κJ(J−1)−μ3J−2/3tr⁡C) C−1⊙C−1, \begin{aligned} \mathbb C = 2\frac{\partial\bm S}{\partial\bm C} ={}& -\frac{2\mu}{3} J^{-2/3} \big( \bm I \otimes \bm C^{-1} + \bm C^{-1} \otimes \bm I \big) + \Big( \kappa J (2J - 1) + \frac{2\mu}{9} J^{-2/3} \operatorname{tr}\bm C \Big)\, \bm C^{-1} \otimes \bm C^{-1} \\ &- 2 \Big( \kappa J (J - 1) - \frac{\mu}{3} J^{-2/3} \operatorname{tr}\bm C \Big)\, \bm C^{-1} \odot \bm C^{-1}, \end{aligned}

with (A⊗B)IJKL=AIJBKL(\bm A \otimes \bm B)_{IJKL} = A_{IJ} B_{KL} and (A⊙B)IJKL=12(AIKBJL+AILBJK)(\bm A \odot \bm B)_{IJKL} = \tfrac12 (A_{IK} B_{JL} + A_{IL} B_{JK}). From these two, the base class HyperelasticMaterialModel builds the two-point quantities that the integrator needs:

Tensor2_3D get_1st_PK_stress(const Tensor2_3D &F) const
{
   return F * get_2nd_PK_stress(F);
}

// AA_iJkL = F_iM CC_MJNL F_kN + delta_ik S_JL.
Tensor4_3D get_1st_elasticity_tensor(const Tensor2_3D &F) const;
P=FS,AkJlL=∂PkJ∂FlL=∑I,KFkI CIJKL FlK+δkl SJL. \bm P = \bm F \bm S, \qquad \mathbb A_{kJlL} = \frac{\partial P_{kJ}}{\partial F_{lL}} = \sum_{I,K} F_{kI}\, \mathbb C_{IJKL}\, F_{lK} + \delta_{kl}\, S_{JL} .
  • The material only sees F\bm F. It knows nothing about elements, nodes or quadrature, so the same integrator works for any model derived from HyperelasticMaterialModel.
  • P\bm P enters the residual (step 6) and A\mathbb A the tangent (step 7); step 7 shows where the formula for A\mathbb A comes from.

5. Weak form and the nonlinear form

mfem::NonlinearForm nonlinear_form(&fespace);
nonlinear_form.AddDomainIntegrator(
   new CompressibleHyperelasticIntegrator(material));
nonlinear_form.SetEssentialTrueDofs(ess_tdof_list);

Take a test function w\bm w that vanishes where the displacement is prescribed, w=0\bm w = \bm 0 on ΓD\Gamma_D. Multiply Eq. (1) by it and integrate over the body,

∫Ω0w⋅Div⁡P  dV=0.(4) \tag{4} \int_{\Omega_0} \bm w \cdot \operatorname{Div} \bm P \; dV = 0 .

The integrand contains a derivative of P\bm P, which is what the weak form moves onto w\bm w. The product rule for a divergence, written with indices (PkJ,J=∂PkJ/∂XJP_{kJ,J} = \partial P_{kJ}/\partial X_J), is

∑J(∑kwkPkJ),J=∑k,Jwk PkJ,J+∑k,Jwk,J PkJ⟺Div⁡(PTw)=w⋅Div⁡P+P:Grad⁡w, \sum_{J} \Big( \sum_{k} w_k P_{kJ} \Big)_{,J} = \sum_{k,J} w_k\, P_{kJ,J} + \sum_{k,J} w_{k,J}\, P_{kJ} \quad\Longleftrightarrow\quad \operatorname{Div}\big(\bm P^{\mathrm{T}} \bm w\big) = \bm w \cdot \operatorname{Div}\bm P + \bm P : \operatorname{Grad}\bm w ,

We use lowercase indices such as i,j,k,li,j,k,l to denote the basis components associated with the current configuration, and uppercase indices such as I,J,K,LI,J,K,L to denote those associated with the reference configuration. The first Piola–Kirchhoff stress P\bm 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 PkJP_{kJ}. The test function wkw_k is defined over the reference configuration. Note that all these indices refer to three-dimensional space and therefore take values 1,2,31,2,3.

so the integral in Eq. (4) splits into a divergence and a term with Grad⁡w\operatorname{Grad}\bm w,

∫Ω0w⋅Div⁡P  dV=∫Ω0Div⁡(PTw)  dV−∫Ω0P:Grad⁡w  dV=0. \int_{\Omega_0} \bm w \cdot \operatorname{Div} \bm P \; dV = \int_{\Omega_0} \operatorname{Div}\big(\bm P^{\mathrm{T}} \bm w\big) \; dV - \int_{\Omega_0} \bm P : \operatorname{Grad}\bm w \; dV = 0 .

The divergence theorem turns the first integral into a boundary integral, and (PTw)⋅N=w⋅PN(\bm P^{\mathrm{T}}\bm w)\cdot\bm N = \bm w \cdot \bm P\bm N,

∫Ω0Div⁡(PTw)  dV=∫∂Ω0w⋅P N  dA=∫ΓDw⋅P N  dA⏟= 0,    w = 0+∫ΓNw⋅P N  dA⏟PN = Tˉ. \int_{\Omega_0} \operatorname{Div}\big(\bm P^{\mathrm{T}} \bm w\big) \; dV = \int_{\partial\Omega_0} \bm w \cdot \bm P\,\bm N \; dA = \underbrace{\int_{\Gamma_D} \bm w \cdot \bm P\,\bm N \; dA}_{=\,0,\;\; \bm w \,=\, \bm 0} + \underbrace{\int_{\Gamma_N} \bm w \cdot \bm P\,\bm N \; dA}_{\bm P\bm N \,=\, \bar{\bm T}} .

Putting the pieces together:

∫Ω0P:Grad⁡w  dV=∫ΓNTˉ⋅w  dA∀ w,    w=0 on ΓD.(5) \int_{\Omega_0} \bm P : \operatorname{Grad}\bm w \; dV = \int_{\Gamma_N} \bar{\bm T} \cdot \bm w \; dA \qquad \forall\, \bm w,\;\; \bm w = \bm 0 \text{ on } \Gamma_D. \tag{5}

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\bm w. Its integrals, however, are additive over non-overlapping pieces. The elements cover Ω0\Omega_0, and their faces on ΓN\Gamma_N cover ΓN\Gamma_N, so moving everything to one side, Eq. (5) becomes a sum of element contributions,

∑e[  ∫ΩeP:Grad⁡w  dV−∫∂Ωe∩ΓNTˉ⋅w  dA  ]=0. \sum_\mathbf{e} \left[\; \int_{\Omega^\mathbf{e}} \bm P : \operatorname{Grad}\bm w \; dV - \int_{\partial\Omega^\mathbf{e} \cap \Gamma_N} \bar{\bm T} \cdot \bm w \; dA \;\right] = 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\bar{\bm T} = \bm 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\mathbf{e}. With the same shape functions for u\bm u and w\bm w (Galerkin), P\bm P becomes Ph=P(Fh)\bm P^h = \bm P(\bm F^h). Writing P:Grad⁡w=∑k,JPkJ wk,J\bm P : \operatorname{Grad}\bm w = \sum_{k,J} P_{kJ}\, w_{k,J} and Tˉ⋅w=∑kTˉk wk\bar{\bm T} \cdot \bm w = \sum_k \bar T_k\, w_k, the bracket reads

∫Ωe∑k,JPkJh wk,Jh  dV−∫∂Ωe∩ΓN∑kTˉk wkh  dA. \int_{\Omega^\mathbf{e}} \sum_{k,J} P^h_{kJ}\, w^h_{k,J} \; dV - \int_{\partial\Omega^\mathbf{e} \cap \Gamma_N} \sum_{k} \bar T_k\, w^h_k \; dA .

A note on sums. The summation convention is not used in this note: every sum is written out with an explicit ∑\sum. This matters because two kinds of indices appear side by side, tensor indices (i,j,k,li,j,k,l and I,J,K,LI,J,K,L) and mesh indices (a\mathbf{a}, b\mathbf{b}, e\mathbf{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\Omega^\mathbf{e} the test function and its gradient are

wkh=∑aNa wka,wk,Jh=∑aN,Ja wka, w^h_k = \sum_{\mathbf{a}} N^\mathbf{a}\, w^\mathbf{a}_k, \qquad w^h_{k,J} = \sum_{\mathbf{a}} N^\mathbf{a}_{,J}\, w^\mathbf{a}_k ,

where only NaN^\mathbf{a} is differentiated, since the nodal values wkaw^\mathbf{a}_k are constants. The bracket becomes

∫Ωe∑k,JPkJh(∑aN,Ja wka)dV−∫∂Ωe∩ΓN∑kTˉk(∑aNa wka)dA. \int_{\Omega^\mathbf{e}} \sum_{k,J} P^h_{kJ} \Big( \sum_{\mathbf{a}} N^\mathbf{a}_{,J}\, w^\mathbf{a}_k \Big) dV - \int_{\partial\Omega^\mathbf{e} \cap \Gamma_N} \sum_{k} \bar T_k \Big( \sum_{\mathbf{a}} N^\mathbf{a}\, w^\mathbf{a}_k \Big) dA .

Step 2: put all the sums in front. The first integrand now contains three sums, over kk, JJ and a\mathbf{a}; the second contains two, over kk and a\mathbf{a}. Moving the inner sum over a\mathbf{a} out of the parentheses,

∫Ωe∑k∑J∑aPkJh N,Ja wka  dV−∫∂Ωe∩ΓN∑k∑aTˉk Na wka  dA. \int_{\Omega^\mathbf{e}} \sum_{k}\sum_{J}\sum_{\mathbf{a}} P^h_{kJ}\, N^\mathbf{a}_{,J}\, w^\mathbf{a}_k \; dV - \int_{\partial\Omega^\mathbf{e} \cap \Gamma_N} \sum_{k}\sum_{\mathbf{a}} \bar T_k\, N^\mathbf{a}\, w^\mathbf{a}_k \; dA .

Step 3: reorder the sums and take them out of the integrals. Finite sums can be taken in any order, so put a\mathbf{a} and kk outermost and leave JJ inside. Integration is linear and wkaw^\mathbf{a}_k does not depend on X\bm X, so both the sums over a,k\mathbf{a}, k and the factor wkaw^\mathbf{a}_k come out of the integrals:

∑a∑kwka∫Ωe∑JN,Ja PkJh  dV−∑a∑kwka∫∂Ωe∩ΓNNa Tˉk  dA. \sum_{\mathbf{a}}\sum_{k} w^\mathbf{a}_k \int_{\Omega^\mathbf{e}} \sum_{J} N^\mathbf{a}_{,J}\, P^h_{kJ} \; dV - \sum_{\mathbf{a}}\sum_{k} w^\mathbf{a}_k \int_{\partial\Omega^\mathbf{e} \cap \Gamma_N} N^\mathbf{a}\, \bar T_k \; dA .

JJ stays inside because it only connects Ph\bm P^h with Grad⁡Na\operatorname{Grad} N^\mathbf{a}; kk comes out because it belongs to wkaw^\mathbf{a}_k.

Step 4: collect the coefficient of each wkaw^\mathbf{a}_k. Both terms carry the same wkaw^\mathbf{a}_k:

∑a,kwka[  ∫Ωe∑JN,Ja PkJh  dV−∫∂Ωe∩ΓNNa Tˉk  dA  ]=∑a,kwka Rka. \sum_{\mathbf{a},k} w^\mathbf{a}_k \left[\; \int_{\Omega^\mathbf{e}} \sum_{J} N^\mathbf{a}_{,J}\, P^h_{kJ} \; dV - \int_{\partial\Omega^\mathbf{e} \cap \Gamma_N} N^\mathbf{a}\, \bar T_k \; dA \;\right] = \sum_{\mathbf{a},k} w^\mathbf{a}_k\, R^\mathbf{a}_k .

The element residual is

  Rka(uh)=∫Ωe∑JN,Ja  PkJh(Fh(uh))  dV  −  ∫∂Ωe∩ΓNNa Tˉk  dA  (6) \boxed{\; R^\mathbf{a}_k(\bm u^h) = \int_{\Omega^\mathbf{e}} \sum_{J} N^\mathbf{a}_{,J}\; P^h_{kJ}\big(\bm F^h(\bm u^h)\big) \; dV \;-\; \int_{\partial\Omega^\mathbf{e} \cap \Gamma_N} N^\mathbf{a}\, \bar T_k \; dA \;} \tag{6}

Collected over the nodes a\mathbf{a} and directions kk of the element, these components form the element residual vector. As in the code, the entries are numbered direction by direction, first the xx-components of the nn nodes, then yy, then zz:

(Re)P=Rka,P=a+(k−1) n,Re∈R3n. \big(\mathsf R^\mathbf{e}\big)_P = R^\mathbf{a}_k, \qquad P = \mathbf{a} + (k-1)\,n, \qquad \mathsf R^\mathbf{e} \in \mathbb R^{3n} .

The code. AssembleElementVector evaluates Eq. (6) without the traction term:

void AssembleElementVector(const mfem::FiniteElement &elem,
                           mfem::ElementTransformation &elem_map,
                           const mfem::Vector &disp,
                           mfem::Vector &residual) override
{
   const int num_nodes = elem.GetDof();
   mfem::DenseMatrix dN_dxi(num_nodes, 3), dN_dX(num_nodes, 3);

   residual.SetSize(3 * num_nodes);
   residual = 0.0;

   const mfem::IntegrationRule &quad_rule = get_quad_rule(elem, elem_map);

   for (int qq = 0; qq < quad_rule.GetNPoints(); qq++)
   {
      const mfem::IntegrationPoint &quad_pt = quad_rule.IntPoint(qq);
      elem_map.SetIntPoint(&quad_pt);

      // dN/dxi
      elem.CalcDShape(quad_pt, dN_dxi);
      // N_a,J = dN/dX = dN/dxi (dX/dxi)^-1.
      mfem::Mult(dN_dxi, elem_map.InverseJacobian(), dN_dX);

      const Tensor2_3D F = get_deformation_gradient(disp, dN_dX);

      const Tensor2_3D PK1 = material.get_1st_PK_stress(F);

      // dV = w_q * det( dX/dxi )
      const double dV = quad_pt.weight * elem_map.Weight();

      for (int aa = 0; aa < num_nodes; aa++)
      {
         // x-component
         residual(aa)             += dV * (PK1(0, 0) * dN_dX(aa, 0)
                                         + PK1(0, 1) * dN_dX(aa, 1)
                                         + PK1(0, 2) * dN_dX(aa, 2));
         // y- and z-components: rows 1 and 2 of PK1
         ...
      }
   }
}
Symbol Code
nn num_nodes
dkad^\mathbf{a}_k disp(aa + k*num_nodes), kk counted from 0
N,JaN^\mathbf{a}_{,J} dN_dX(aa, J)
Fh\bm F^h, Eq. (3) get_deformation_gradient(disp, dN_dX)
Ph\bm P^h PK1
ωqdet⁡(∂X/∂ξ)\omega_q \det(\partial\bm X/\partial\bm\xi) dV (step 8)
RkaR^\mathbf{a}_k residual(aa + k*num_nodes)
  • 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 xx-components of the nn nodes, then yy, then zz. 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(ξ)\hat N^\mathbf{a}(\bm\xi); elem_map knows the node coordinates of this element and supplies (∂X/∂ξ)−1(\partial\bm X/\partial\bm\xi)^{-1} and its determinant.

In the driver, one call evaluates the global residual at the displacement of step 3:

mfem::Vector disp_true;
disp.GetTrueDofs(disp_true);

mfem::Vector residual(fespace.GetTrueVSize());
nonlinear_form.Mult(disp_true, residual);

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\bm u^h to the nodal values de\mathsf d^\mathbf{e}. Eq. (6) writes the residual in terms of the field uh\bm u^h, but a field cannot be the unknown of a program; the unknowns are the nodal values. On Ωe\Omega^\mathbf{e} the two carry the same information: by Eq. (2) the field is fixed by the element's nodal displacements,

ukh(X)=∑b=1nNb(X) dkb, u^h_k(\bm X) = \sum_{\mathbf{b}=1}^{n} N^\mathbf{b}(\bm X)\, d^\mathbf{b}_k ,

so, with the nodal values collected in de\mathsf d^\mathbf{e}, the residual is a function of de\mathsf d^\mathbf{e} alone, Rka(de):=Rka(uh[de])R^\mathbf{a}_k(\mathsf d^\mathbf{e}) := R^\mathbf{a}_k\big(\bm u^h[\mathsf d^\mathbf{e}]\big). The map from de\mathsf d^\mathbf{e} to uh\bm u^h is linear, and its derivatives are just the shape functions,

∂ukh∂dlb=δkl Nb,∂FkJh∂dlb=δkl N,Jb. \frac{\partial u^h_k}{\partial d^\mathbf{b}_l} = \delta_{kl}\, N^\mathbf{b}, \qquad \frac{\partial F^h_{kJ}}{\partial d^\mathbf{b}_l} = \delta_{kl}\, N^\mathbf{b}_{,J} .

Differentiating with respect to one nodal value dlbd^\mathbf{b}_l therefore means: move node b\mathbf{b} in direction ll; the field uh\bm u^h changes by NbN^\mathbf{b} in that direction, and Fh\bm F^h by N,JbN^\mathbf{b}_{,J} in row ll.

Re\mathsf R^\mathbf{e} is nonlinear in de\mathsf d^\mathbf{e}, 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\Delta\mathsf d^\mathbf{e} and expand the element residual to first order:

Re(de+Δde)≈Re(de)+Ke Δde,Ke=∂Re∂de. \mathsf R^\mathbf{e}(\mathsf d^\mathbf{e} + \Delta\mathsf d^\mathbf{e}) \approx \mathsf R^\mathbf{e}(\mathsf d^\mathbf{e}) + \mathsf K^\mathbf{e}\, \Delta\mathsf d^\mathbf{e}, \qquad \mathsf K^\mathbf{e} = \frac{\partial \mathsf R^\mathbf{e}}{\partial \mathsf d^\mathbf{e}} .

Ke\mathsf K^\mathbf{e} is the element stiffness matrix. Written entry by entry, with Ke=[ Kklab ]\mathsf K^\mathbf{e} = \big[\, K^{\mathbf{a}\mathbf{b}}_{kl} \,\big], the same expansion reads

Rka(de+Δde)≈Rka(de)+∑b,lKklab Δdlb,  Kklab=∂Rka∂dlb  (7) R^\mathbf{a}_k(\mathsf d^\mathbf{e} + \Delta\mathsf d^\mathbf{e}) \approx R^\mathbf{a}_k(\mathsf d^\mathbf{e}) + \sum_{\mathbf{b},l} K^{\mathbf{a}\mathbf{b}}_{kl}\, \Delta d^\mathbf{b}_l, \qquad \boxed{\; K^{\mathbf{a}\mathbf{b}}_{kl} = \frac{\partial R^\mathbf{a}_k}{\partial d^\mathbf{b}_l} \;} \tag{7}

KklabK^{\mathbf{a}\mathbf{b}}_{kl} says how much the residual at node a\mathbf{a}, direction kk, changes when node b\mathbf{b} moves in direction ll. 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\mathsf d^\mathbf{e}, and neither does the traction term (a dead load), so the derivative passes through the integral and acts only on Ph\bm P^h:

Kklab=∂∂dlb[ ∫Ωe∑JN,Ja PkJh  dV−∫∂Ωe∩ΓNNa Tˉk  dA ]=∫Ωe∑JN,Ja ∂PkJh∂dlb  dV. K^{\mathbf{a}\mathbf{b}}_{kl} = \frac{\partial}{\partial d^\mathbf{b}_l} \left[\, \int_{\Omega^\mathbf{e}} \sum_{J} N^\mathbf{a}_{,J}\, P^h_{kJ} \; dV - \int_{\partial\Omega^\mathbf{e} \cap \Gamma_N} N^\mathbf{a}\, \bar T_k \; dA \,\right] = \int_{\Omega^\mathbf{e}} \sum_{J} N^\mathbf{a}_{,J}\, \frac{\partial P^h_{kJ}}{\partial d^\mathbf{b}_l} \; dV .

Step 2: differentiate Ph=FhSh\bm P^h = \bm F^h\bm S^h. By the product rule,

∂PkJh∂dlb=∑I∂FkIh∂dlb SIJh+∑IFkIh ∂SIJh∂dlb. \frac{\partial P^h_{kJ}}{\partial d^\mathbf{b}_l} = \sum_{I} \frac{\partial F^h_{kI}}{\partial d^\mathbf{b}_l}\, S^h_{IJ} + \sum_{I} F^h_{kI}\, \frac{\partial S^h_{IJ}}{\partial d^\mathbf{b}_l} .

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\mathbb C^h = \partial\bm S^h/\partial\bm E^h, which is symmetric in IJIJ and in KLKL:

∂FkIh∂dlb=δkl N,Ib,∂SIJh∂dlb=∑K,LCIJKLh ∂EKLh∂dlb=∑K,LCIJKLh FlKh N,Lb, \frac{\partial F^h_{kI}}{\partial d^\mathbf{b}_l} = \delta_{kl}\, N^\mathbf{b}_{,I}, \qquad \frac{\partial S^h_{IJ}}{\partial d^\mathbf{b}_l} = \sum_{K,L} \mathbb C^h_{IJKL}\, \frac{\partial E^h_{KL}}{\partial d^\mathbf{b}_l} = \sum_{K,L} \mathbb C^h_{IJKL}\, F^h_{lK}\, N^\mathbf{b}_{,L} ,

since ∂EKLh/∂dlb=12(N,KbFlLh+FlKhN,Lb)\partial E^h_{KL}/\partial d^\mathbf{b}_l = \tfrac12 ( N^\mathbf{b}_{,K} F^h_{lL} + F^h_{lK} N^\mathbf{b}_{,L} ) and the minor symmetry of Ch\mathbb C^h merges the two halves. Renaming I→LI \to L in the first term (and using SLJh=SJLhS^h_{LJ} = S^h_{JL}), both terms end in N,LbN^\mathbf{b}_{,L}:

∂PkJh∂dlb=∑L(∑I,KFkIh CIJKLh FlKh+δkl SJLh) N,Lb.(8) \frac{\partial P^h_{kJ}}{\partial d^\mathbf{b}_l} = \sum_{L} \Big( \sum_{I,K} F^h_{kI}\, \mathbb C^h_{IJKL}\, F^h_{lK} + \delta_{kl}\, S^h_{JL} \Big)\, N^\mathbf{b}_{,L} . \tag{8}

Step 4: back into KklabK^{\mathbf{a}\mathbf{b}}_{kl}. Substituting Eq. (8) into Step 1 gives the element stiffness tensor:

  Kklab=∫Ωe∑J,LN,Ja  AkJlLh  N,Lb  dV,AkJlLh=∑I,KFkIh  CIJKLh  FlKh⏟material  +  δkl  SJLh⏟geometric  (9) \boxed{\; K^{\mathbf{a}\mathbf{b}}_{kl} = \int_{\Omega^\mathbf{e}} \sum_{J,L} N^\mathbf{a}_{,J}\; \mathbb A^h_{kJlL}\; N^\mathbf{b}_{,L} \; dV, \qquad \mathbb A^h_{kJlL} = \underbrace{\sum_{I,K} F^h_{kI}\; \mathbb C^h_{IJKL}\; F^h_{lK}}_{\text{material}} \;+\; \underbrace{\delta_{kl}\; S^h_{JL}}_{\text{geometric}} \;} \tag{9}

The bracket is the first elasticity tensor Ah=∂Ph/∂Fh\mathbb A^h = \partial\bm P^h/\partial\bm F^h of step 4: the residual needs Ph\bm P^h, and the tangent needs Ah\mathbb A^h, with one shape function gradient on each side.

From KklabK^{\mathbf{a}\mathbf{b}}_{kl} to Ke\mathsf K^\mathbf{e}. 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 xx-components of nodes 1,…,n1, \dots, n, then the yy-components, then the zz-components. The pair (a,k)(\mathbf{a}, k) is therefore unknown number a+(k−1) n\mathbf{a} + (k-1)\,n, and

(Ke)PQ=Kklab,P=a+(k−1) n,Q=b+(l−1) n,Ke∈R3n×3n. \big(\mathsf K^\mathbf{e}\big)_{PQ} = K^{\mathbf{a}\mathbf{b}}_{kl}, \qquad P = \mathbf{a} + (k-1)\,n, \quad Q = \mathbf{b} + (l-1)\,n, \qquad \mathsf K^\mathbf{e} \in \mathbb R^{3n \times 3n} .

The row PP comes from the residual, node a\mathbf{a} in direction kk; the column QQ from the displacement, node b\mathbf{b} in direction ll. Grouping the rows and columns by direction, Ke\mathsf K^\mathbf{e} is a 3×33 \times 3 array of n×nn \times n blocks, one block for each pair of directions (k,l)(k, l), and inside a block the nodes (a,b)(\mathbf{a}, \mathbf{b}) pick the entry:

Ke=[K11K12K13K21K22K23K31K32K33],(Kkl)ab=Kklab. \mathsf K^\mathbf{e} = \begin{bmatrix} \mathsf K_{11} & \mathsf K_{12} & \mathsf K_{13} \\ \mathsf K_{21} & \mathsf K_{22} & \mathsf K_{23} \\ \mathsf K_{31} & \mathsf K_{32} & \mathsf K_{33} \end{bmatrix}, \qquad \big(\mathsf K_{kl}\big)_{\mathbf{a}\mathbf{b}} = K^{\mathbf{a}\mathbf{b}}_{kl} .

The code. AssembleElementGrad evaluates Eq. (9) at the same quadrature points as the residual:

void AssembleElementGrad(const mfem::FiniteElement &elem,
                         mfem::ElementTransformation &elem_map,
                         const mfem::Vector &disp,
                         mfem::DenseMatrix &tangent) override
{
   ...
   for (int qq = 0; qq < quad_rule.GetNPoints(); qq++)
   {
      ...
      const Tensor2_3D F = get_deformation_gradient(disp, dN_dX);

      const Tensor4_3D AA = material.get_1st_elasticity_tensor(F);

      // dV = w_q * det( dX/dxi )
      const double dV = quad_pt.weight * elem_map.Weight();

      for (int aa = 0; aa < num_nodes; aa++)
      {
         const Vector_3D dNa_dX(dN_dX(aa, 0), dN_dX(aa, 1), dN_dX(aa, 2));

         for (int bb = 0; bb < num_nodes; bb++)
         {
            const Vector_3D dNb_dX(dN_dX(bb, 0), dN_dX(bb, 1), dN_dX(bb, 2));

            // N_a,J AA_kJlL N_b,L
            for (int kk = 0; kk < 3; kk++)
               for (int ll = 0; ll < 3; ll++)
                  tangent(aa+kk*num_nodes, bb+ll*num_nodes) += dV *
                     ( dNa_dX(0) * (AA(kk, 0, ll, 0) * dNb_dX(0)
                                 +  AA(kk, 0, ll, 1) * dNb_dX(1)
                                 +  AA(kk, 0, ll, 2) * dNb_dX(2))
                     + dNa_dX(1) * (...)
                     + dNa_dX(2) * (...));
         }
      }
   }
}
Symbol Code
AkJlLh\mathbb A^h_{kJlL} AA(kk, J, ll, L)
N,JaN^\mathbf{a}_{,J}, N,LbN^\mathbf{b}_{,L} dNa_dX(J), dNb_dX(L)
(Ke)PQ(\mathsf K^\mathbf{e})_{PQ} tangent(aa+kk*num_nodes, bb+ll*num_nodes), all indices counted from 0
  • The loop is Eq. (9) written out: two loops over the nodes, two over the directions, and the sums over JJ and LL spelled out.
  • AssembleElementGrad is the second fixed name, called by NonlinearForm::GetGradient. Both functions compute Fh\bm F^h with the same get_deformation_gradient.

8. Quadrature

static const mfem::IntegrationRule &get_quad_rule(
   const mfem::FiniteElement &elem, mfem::ElementTransformation &elem_map)
{
   return mfem::IntRules.Get(elem.GetGeomType(), 2 * elem_map.OrderGrad(&elem));
}

The element integrals are evaluated with Gauss–Legendre quadrature on the reference element Ω^\hat\Omega. With the mapping ξ↦Xe(ξ)\bm\xi \mapsto \bm X^\mathbf{e}(\bm\xi),

Kklab≈∑qωqdet⁡ ⁣(∂X∂ξ)∑J,LN,Ja AkJlLh N,Lb ∣ξq, K^{\mathbf{a}\mathbf{b}}_{kl} \approx \sum_{q} \omega_q \det\!\left(\frac{\partial\bm X}{\partial\bm\xi}\right) \sum_{J,L} N^{\mathbf{a}}_{,J}\, \mathbb A^h_{kJlL}\, N^{\mathbf{b}}_{,L}\,\bigg|_{\bm\xi_q},

and RkaR^\mathbf{a}_k in the same way. At each point ξq\bm\xi_q the integrand is evaluated from the current de\mathsf d^\mathbf{e}: Fh\bm F^h, then Sh\bm S^h and Ch\mathbb C^h from the material law, then Ah\mathbb A^h. quad_pt.weight is ωq\omega_q and elem_map.Weight() is det⁡(∂X/∂ξ)\det(\partial\bm X/\partial\bm\xi); 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×2 \times (degree of Grad⁡Na\operatorname{Grad} N^\mathbf{a}):

  • The factor 2. The integrand of KklabK^{\mathbf{a}\mathbf{b}}_{kl} contains two shape function gradients, N,JaN^\mathbf{a}_{,J} and N,LbN^\mathbf{b}_{,L}. In linear elasticity Ah\mathbb A^h 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 mm points is exact up to degree 2m−12m - 1, so degree 4 needs m=3m = 3, and the hexahedron uses the tensor product, 33=273^3 = 27 points.
  • Not exact, but consistent. The Neo-Hookean Ah\mathbb A^h is not a polynomial in ξ\bm\xi, 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\mathsf K^\mathbf{e} the exact derivative of the discrete Re\mathsf R^\mathbf{e}, and Newton's method converges quadratically.

9. Newton's method

mfem::GSSmoother preconditioner;
mfem::CGSolver linear_solver;
linear_solver.SetRelTol(1.0e-6);
linear_solver.SetAbsTol(0.0);
linear_solver.SetMaxIter(500);
linear_solver.SetPrintLevel(0);
linear_solver.SetPreconditioner(preconditioner);

mfem::NewtonSolver newton_solver;
newton_solver.SetOperator(nonlinear_form);
newton_solver.SetSolver(linear_solver);
newton_solver.SetRelTol(1.0e-8);
newton_solver.SetAbsTol(0.0);
newton_solver.SetMaxIter(20);
newton_solver.SetPrintLevel(1);
newton_solver.iterative_mode = true;

const mfem::Vector zero_rhs;
newton_solver.Mult(zero_rhs, disp_true);
MFEM_VERIFY(newton_solver.GetConverged(), "Newton did not converge.");

disp.SetFromTrueDofs(disp_true);

Everything above happens inside one element, and it is all the integrator has to provide: AssembleElementVector returns Re\mathsf R^\mathbf{e} and AssembleElementGrad returns Ke\mathsf K^\mathbf{e}. The rest is done by MFEM.

  • Assembly. NonlinearForm loops over the elements, calls the integrator, and adds Re\mathsf R^\mathbf{e} and Ke\mathsf K^\mathbf{e} into the global R\mathsf R and K\mathsf K at the global numbers returned by GetElementVDofs, the local unknown (a,k)(\mathbf{a}, k) going to the global unknown (ℓ(e,a),k)(\ell(\mathbf{e},\mathbf{a}), k). A node shared by several elements receives the sum of their contributions, RkA=∑e∋ARka(e)R^\mathbf{A}_k = \sum_{\mathbf{e} \ni \mathbf{A}} R^\mathbf{a}_k(\mathbf{e}), and K\mathsf K is assembled the same way.
  • Newton's method. The discrete problem is RkA(d)=0R^\mathbf{A}_k(\mathsf d) = 0 for every free unknown. NewtonSolver repeats: assemble R\mathsf R and K\mathsf K at the current d\mathsf d, solve K Δd=−R\mathsf K\, \Delta\mathsf d = -\mathsf R, update d←d+Δd\mathsf d \leftarrow \mathsf d + \Delta\mathsf d, until R≈0\mathsf R \approx \mathsf 0. Since Ke\mathsf K^\mathbf{e} is the exact derivative of Re\mathsf R^\mathbf{e}, the convergence is quadratic.
∥R(d)∥  ≤  10−8 ∥R(d0)∥ \|\mathsf R(\mathsf d)\| \;\le\; 10^{-8}\, \|\mathsf R(\mathsf d_0)\|
  • zero_rhs is empty, which tells NewtonSolver to solve R(d)=0\mathsf R(\mathsf d) = \mathsf 0.
  • iterative_mode = true is essential. It makes Newton start from disp_true, which carries the prescribed uˉ\bar 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\mathsf K is symmetric: AkJlLh=AlLkJh\mathbb A^h_{kJlL} = \mathbb A^h_{lLkJ}, and replacing constrained rows and columns by the identity keeps the symmetry. Each linear solve only needs to be accurate to 10−610^{-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.