FerriteSolidMechanics.jl

A solid mechanics assembly framework and material model library for Ferrite.jl.

FerriteSolidMechanics.jl provides finite element assembly infrastructure for solid mechanics in Ferrite.jl alongside a library of ready-to-use constitutive models and a quadrature point interface for implementing new ones. The package handles element-level assembly, external load integration, state bookkeeping, thread and MPI parallelism, and provides MPI-distributed solving through MUMPS. Dimensionality wrappers adapt 3D models to 2D plane strain and plane stress analyses; an adaptive time step controller allows step size adjustment after failed material updates.

In a nutshell, FerriteSolidMechanics.jl works as follows:

using Ferrite
using FerriteSolidMechanics

# After setting up a grid and initializing Ferrite's DofHandler `dh`,
# ConstraintHandler `ch`, LoadHandler `lh`, and displacement vector `u`:
material = J2Plasticity(100.0, 0.3, 1.0, 10.0)  # assign material model
assembler = create_assembler(material, dh, ch)  # create material assembler

K, r = stiffness_matrix(assembler, u; dt=0.5)   # get stiffness tangent and internal residual
# ... solve the global Newton step and update u ...
update_states!(assembler)                       # commit material state
stresses = compute_stresses(assembler, u)       # postprocessing

Why this package

Running solid mechanics simulations in Ferrite.jl requires cell iteration, per-sub-dof-handler cell values and quadrature rules, and – depending on the problem – state management, external load integration, and thread/MPI parallelism. FerriteSolidMechanics.jl provides this infrastructure generically for small- and finite-strain models, alongside an extendable catalog of models built on it. The package includes:

• a quadrature point constitutive interface (material_response, kinematics, plus the state lifecycle create_state, update_state!, revert_state!): a material author writes only the constitutive update – parameters, state, stress, and tangent – comparable to an Abaqus UMAT. A generic element routine owns the quadrature loop, integration weights, weak form, and trial-state bookkeeping; stateless hyperelastic models can even be defined by a single strain energy function via AbstractHyperelastic. For formulations whose element structure is material-specific, the element-level hooks (_assemble_element!, _compute_stress_qp) remain stable extension points,
• dimensionality wrappers (PlaneStrain, PlaneStress) that use compatible 3D materials in 2D analyses: PlaneStrain uses 2D-to-3D embedding, while PlaneStress solves the out-of-plane stretch with a local Newton iteration and condenses the tangent,
• a generic material assembler that handles 2D / 3D, mixed-element grids, sub-dof-handlers, linear preassembly, thread parallelism (OhMyThreads.@tasks), and MPI-parallel constitutive evaluation and element assembly,
• external load assembly (LoadHandler) for Neumann boundary conditions: BodyForce, Traction, Pressure and NodalForce are collected with add! and integrated into the external force vector by external_forces!, using the assembler's quadrature order and thickness so that external and internal forces match,
• adaptive time stepping (TimeStepController) that retries a failed material update with a smaller step size, using the recoverable failures reported by try_stiffness_matrix,
• a distributed linear solve (distributed_solve) that splits one MUMPS factorization across MPI ranks, instead of every rank factorizing the whole system,
• bundled material models ranging from linear elasticity to finite-strain hyperelastic and viscoelastic-viscoplastic laws (including MooneyRivlin, Ogden, ArrudaBoyce, VEPD_Detrez2010, VEVP_Zhao2021_AD, VEVP_MOAMMM),
• a MaterialModelsBase.jl bridge (FromMaterialModelsBase) that runs a material written for MaterialModelsBase.jl or MechanicalMaterialModels.jl through the same assembly path as a bundled model.

To add a new material, implement material_response and kinematics for it. The Developer guide walks through the full interface using the bundled J2Plasticity model, and through the one-function hyperelastic path that needs only a strain energy density Ψ(C).

Where to start

Installation

using Pkg
Pkg.add(url="https://github.com/LukasLaubert/FerriteSolidMechanics.jl")

For local development:

using Pkg
Pkg.develop(path=".")
Pkg.test("FerriteSolidMechanics")

Status

FerriteSolidMechanics.jl requires Julia 1.10 or newer; CI tests Julia 1.10 and the latest stable Julia 1.x. The implementation is tested with Julia 1.11.6 and Ferrite 1.4.1. It is licensed under the MIT license (see LICENSE in the repository root); material model provenance and acknowledgements are documented on the material pages.

Related packages and acknowledgements

FerriteSolidMechanics.jl sits alongside several Julia packages for constitutive modelling and finite element assembly, and follows some conventions established by them.

• MaterialModels.jl (K. Auth and contributors) is a material model library without an assembly layer. Its material_response convention returning (stress, tangent, new_state), the AbstractMaterial/AbstractMaterialState pair, and PlaneStrain/PlaneStress as dimensional wrappers are used here under the same names.
• MaterialModelsBase.jl (K. A. Meyer) is an implementation-independent interface package developed from MaterialModels.jl, with MechanicalMaterialModels.jl as the model library built on it. The constitutive interface in FerriteSolidMechanics.jl follows the MaterialModelsBase conventions, and models written for MaterialModelsBase can be used through the FromMaterialModelsBase wrapper.
• FerriteAssembly.jl (K. A. Meyer) covers similar ground to the assembler here: a generic Ferrite assembly path over pluggable materials, with an element-level hook, update_states! for committing converged state, and per-task scratch buffers. Its LoadHandler, a container populated with add! and applied at a given time, is followed here under the same name. FerriteAssembly also assembles general facet contributions to the tangent and threads load assembly, neither of which FerriteSolidMechanics.jl currently does; assembly of the tangent and internal force in FerriteSolidMechanics.jl is instead MPI-parallel, with the external force vector replicated on every rank.
• Ferrite.jl's hyperelasticity and von Mises plasticity tutorials are the source of the Ψ(C)/constitutive_driver convention and of the element integration loops.
• FerriteDistributed.jl runs MPI by partitioning the grid and the DofHandler. FerriteSolidMechanics.jl replicates the global system on every rank and reduces it instead, which leaves the Ferrite DofHandler unchanged at the cost of per-rank memory; see Performance and parallel execution.
• CAPRICCIO - Tool to run concurrent Finite Element-Molecular Dynamics Simulations (Version 3.0.0) (J. Roksvaag, Apache-2.0) couples finite elements to molecular dynamics and is the origin of the assembler interface used here. The entry points create_assembler, stiffness_matrix, compute_forces and compute_stresses, the _assemble_element! element hook, the alpha_value quadrature point scaling hook with its AlphaValues companion, and the replicated MPI assembly keep their names and design from it.

Scientific references and provenance for the bundled constitutive models are on the individual material pages.