Element pitfalls ================ Every element kernel has failure modes that are documented in the FE literature but often forgotten by users picking an element by catalogue number. This page is the diagnostic matrix: rows are elements femorph-solver ships, columns are the failure modes that bite users in practice. Each cell links to the element's reference page (for the formulation-level fix) and to a verification example (for a runnable demonstration). The flow is symptom → element class → failure mode → fix. If you already know which element you're using and what symptom you see, jump straight to the element's section below. Quick-look matrix ----------------- The first row of every cell names the failure mode; the second row gives the recommended fix. .. list-table:: :header-rows: 1 :widths: 14 14 14 14 14 14 14 * - Element - :term:`shear locking` - :term:`volumetric locking` - :term:`hourglass` - distortion - aspect-ratio - through-thickness * - HEX8 (plain Gauss) - **severe** on bending; switch to EAS / B-bar - severe as ν→0.5; B-bar / EAS - none (full integration) - moderate; degrades as J → 0 - keep < 5:1 in bending - 1 element per thickness is too few * - HEX8 (EAS) - cured on regular meshes; partial cure on distorted - cured - none - mild; better than plain - tolerates 8-10:1 - 2 elements / thickness for plates * - HEX20 - none (cubic in each direction) - mild; B-bar still helpful at ν > 0.49 - none - strong against distortion - tolerates 15-20:1 - 1 element / thickness adequate * - TET10 - none (quadratic) - mild; rises near ν = 0.5 - none - excellent - tolerates 20:1 - 1 element / thickness fine * - WEDGE15 - none (degenerate HEX20) - mild - none - good - 10-15:1 - 1 / thickness * - PYR13 - none (degenerate HEX20) - mild - none - good - 10:1 - 1 / thickness * - QUAD4 (plain) - **severe** on plane-strain bending - severe as ν→0.5 - none (full integration) - moderate - keep < 5:1 - n/a (2D) * - QUAD4 (Wilson-Q6) - cured on regular meshes - cured - none - mild; better than plain - 8-10:1 - n/a * - QUAD4_SHELL (DKT) - cured (Mindlin transverse-shear stabilisation) - n/a (membrane / bending split) - none - moderate - 8-10:1 - 1-2 / thickness for thin shells * - BEAM2 (Euler-Bernoulli) - none (Hermite cubics absorb shear analytically) - n/a (1D line) - none - n/a (1D) - L/h > 10 for slender-beam regime - n/a * - TRUSS2 / SPRING - n/a (axial only) - n/a - none - n/a - n/a - n/a Cells marked **severe** mean the failure produces *non-trivial quantitative error* on engineering quantities of interest, not just slow convergence — replacing the element with the recommended fix is mandatory, not optional. Per-element notes ----------------- HEX8 ~~~~ The 8-node trilinear hex is the workhorse of 3D structural FEA. Plain-Gauss integration is the default but suffers two classical failure modes — both are addressed by the :term:`enhanced strain` (EAS) variant, which is what femorph-solver uses by default when ``integration="enhanced_strain"`` is requested on :meth:`Model.assign `. * **Shear locking** — On bending-dominated meshes plain HEX8 develops :math:`O(1)` error that the user reads as "the bracket is way stiffer than the analytical formula predicts". Demonstrated in :ref:`sphx_glr_gallery_verification_example_verify_shear_locking_demo.py` — a slender-cantilever sweep that walks the error all the way to convergence with EAS but stalls at 30-50 % over-stiffness with plain Gauss. * **Volumetric locking** — As :math:`\nu \to 0.5` (rubber, near-incompressible plastic) the dilatational mode loses its representation in the trilinear basis; plain HEX8 stiffens by orders of magnitude. EAS or :term:`B-bar` cures it; for truly incompressible problems, use HEX20. * **Distortion** — Even EAS struggles when the element Jacobian goes near-zero. Trim aspect-ratio outliers (Section :doc:`mesh-quality`) before suspecting a kernel bug. Reference: :doc:`/reference/elements/hex8`. HEX20 ~~~~~ The 20-node serendipity hex is the natural choice when bending matters and you can afford the 2.5× DOF cost. Cubic in each direction so it neither shear-locks nor volumetric-locks significantly under any standard load case. Distortion robustness is excellent; aspect-ratio limit is generous (15-20:1). The one footnote: for fully incompressible materials (:math:`\nu = 0.5`) the constant-pressure mode still has no basis representation, so use the B-bar variant or switch to a mixed u-p formulation (not yet shipped — see :doc:`/getting-started/known-limitations`). Reference: :doc:`/reference/elements/hex20`. TET10 ~~~~~ The 10-node quadratic tet is the workhorse of automatic-meshed 3D analysis (CAD-driven, complex geometries) where structured hex meshing isn't practical. No locking, excellent distortion robustness, and modern mesh generators (Gmsh, Tetgen) produce clean TET10 meshes from STEP files. Two notes: * TET10 needs ~3× the DOFs of HEX8 for similar accuracy on bending-rich problems; HEX-meshing pays off for slender bracket geometries. * On problems with sharp re-entrant corners, the TET10 stress recovery near the singularity converges to the "right infinity" (the singular solution) more cleanly than HEX8 — the higher-order basis matters where the field is rough. Reference: :doc:`/reference/elements/tet10`. WEDGE15 / PYR13 ~~~~~~~~~~~~~~~ Degenerate HEX20 elements at the topology boundary between HEX20 and TET10 — wedges along a hex-tet transition layer, pyramids at the apex of a hex sub-domain meeting a tet sub-domain. Properties inherited from HEX20 with the degeneracy-induced stiffness reduction; mainly used to make hybrid hex-tet meshing tractable. Reference: :doc:`/reference/elements/wedge15_pyr13`. QUAD4 (plane and shell) ~~~~~~~~~~~~~~~~~~~~~~~ The 2D / shell counterpart of HEX8. Plain-Gauss QUAD4 has the same failure modes — shear locking on plane-strain bending, volumetric locking near :math:`\nu = 0.5`. Use the Wilson-Q6 (incompatible-modes) variant for plane elements; DKT (Discrete Kirchhoff Triangle, the non-Mindlin plate that's used inside QUAD4_SHELL on the bending side) inherently fixes the shell-bending case. A specific QUAD4_SHELL note: the kernel ships **5 DOFs per node** (3 translations + 2 rotations). Coupling a shell to a solid mesh that carries the third rotation (drilling DOF) requires an explicit constraint. See :doc:`/getting-started/known-limitations`. Reference: :doc:`/reference/elements/quad4_plane`, :doc:`/reference/elements/quad4_shell`. BEAM2 ~~~~~ The 2-node Hermite-cubic beam is the only line element where shear locking is *structurally absent* — the cubic Hermite shape functions absorb the linear-shear constraint analytically (Cook 2002, Table 16.3-1). Distortion isn't a concept (1D line elements have no Jacobian to distort). The slenderness rule of thumb: BEAM2 is a faithful Euler-Bernoulli element for :math:`L/h > 10`. Below that the shear-deformation correction matters and a Timoshenko upgrade is needed (planned, see roadmap). For very long beams (:math:`L/h > 1000`) numerical conditioning of the bending- stiffness term degrades; subdivide into more elements rather than push the slenderness limit. Reference: :doc:`/reference/elements/beam2`. TRUSS2 and SPRING ~~~~~~~~~~~~~~~~~ Pure-axial elements with no transverse stiffness. The transverse-DOF rows of the element K matrix are identically zero; the assembled global K has zero diagonals on those DOFs unless another element contributes. ``solve_static`` detects zero-diagonal rows via the threshold ``|K_ii| <= 1e-12 * max(|K_ii|)`` and folds them into the Dirichlet set automatically — see :doc:`/user-guide/solving/static`. No user action required; this is *not* a bug to chase. Reference: :doc:`/reference/elements/truss2`, :doc:`/reference/elements/spring`. Symptom-driven cross-reference ------------------------------ If you opened this page because of a specific symptom, the fastest path to a fix is the troubleshooting flowchart in :doc:`troubleshooting` — it asks five questions and lands you on the right element / mesh / BC / solver page. This pitfalls matrix is the *companion* table the flowchart points back to when "which element variant?" is the answer. See also -------- * :doc:`mesh-quality` — element-aspect-ratio and Jacobian thresholds. * :doc:`troubleshooting` — symptom-driven decision tree. * :doc:`/reference/elements/index` — per-element formulation references. * :doc:`/getting-started/known-limitations` — capabilities the library does *not* have today (incompressible u-p mixed, drilling-DOF shell, Timoshenko beam).