Skip to content

About

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

Resources

Contributing

Stars

4 stars

Watchers

0 watching

Forks

Repository files navigation

FerriteSolidMechanics.jl

CI Documentation

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. One generic material model assembler takes care of (sub-)DOF handling, sparse assembly, threading, MPI reduction, and trial/commit state bookkeeping; a separate LoadHandler integrates the external loads. Use a bundled model or implement your own constitutive law and reuse the same assembly path.

Installation

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

Minimal example

using Ferrite
using FerriteSolidMechanics

grid = generate_grid(Quadrilateral, (2, 2))     # Ferrite grid
dh = DofHandler(grid)                           # Ferrite DofHandler
add!(dh, :u, Lagrange{RefQuadrilateral, 1}()^2) # 2D displacement field, linear interpolation
close!(dh)

ch = ConstraintHandler(dh)                      # Ferrite ConstraintHandler
add!(ch, Dirichlet(:u, getfacetset(grid, "left"), (x, t) -> [0.0, 0.0], [1, 2])) # Clamp left boundary
close!(ch)

material = PlaneStress(J2Plasticity(200e3, 0.3, 100.0, 1e3)) # assign a material (plane stress conditions)
assembler = create_assembler(material, dh, ch)  # build the assembler

lh = LoadHandler(assembler)                     # external loads, same pattern as `ch`
add!(lh, Traction("right", (x, t) -> Vec(0.0, -150.0 * t))) # define loading and direction (downward traction)
close!(lh)

u = zeros(ndofs(dh))                            # initial displacement
nsteps, max_newton, tol = 4, 20, 1e-8           # solution control

for step in 1:nsteps                            # loop over load steps
    t = step / nsteps                           # load factor, ramps from 0 to 1
    update!(ch, t)                              # update Dirichlet BCs
    f_ext = external_forces!(lh, t)             # update Neumann BCs
    for _ in 1:max_newton                       # Newton loop
        K, r = stiffness_matrix(assembler, u; dt=1.0 / nsteps) # tangent and internal residual
        residual = r .- f_ext                   # external loads enter residual
        apply_zero!(K, residual, ch)            # zero constrained rows/columns in K & residual
        norm(residual) < tol && break           # stop if residual is small enough
        u .-= K \ residual                      # linear solve & Newton update
    end
    update_states!(assembler)                   # commit updated material state
end

stresses = compute_stresses(assembler, u)       # compute stresses (postprocessing)

See examples/plate_with_hole_planestress.jl for a runnable script incorporating a quarter-plate-with-hole mesh, displacement-controlled loading, and a printed result summary.

Features

  • Material model catalogue: linear elastic, hyperelastic, plastic, and viscoelastic-viscoplastic models. Among those are Ogden, ArrudaBoyce, J2Plasticity, and complex literature-specific polymer models such as VEPD_Detrez2010, which adds damage.
  • Material model interface: implement the quadrature point hook material_response (UMAT-like), or, for a hyperelastic model, only the strain energy density Ψ(C).
  • Element-level override: optionally implement _assemble_element! (UEL-like), e.g., when the element structure itself is material-specific (hand-assembled tangent blocks, mixed or nonlocal formulations).
  • Generic material assembler: 2D and 3D, mixed-element grids, linear preassembly, thread parallelism, and MPI-parallel assembly.
  • External loads: LoadHandler collects BodyForce, Traction, Pressure, and NodalForce entries and assembles the external force vector.
  • 2D wrappers: PlaneStrain and PlaneStress embed a 3D material model into a 2D analysis.
  • Distributed linear solve: distributed_solve splits one factorization across MPI ranks using MUMPS, instead of every rank factorizing the whole system.
  • Adaptive time stepping: TimeStepController retries a failed material update with a smaller step size, using the recoverable failures reported by try_stiffness_matrix.
  • MaterialModelsBase.jl bridge: wrap any MaterialModelsBase.jl / MechanicalMaterialModels.jl model with FromMaterialModelsBase and use it like a bundled model.

Documentation

  • Material models: catalogue of bundled models.
  • Tutorials: 2D plate with a hole, DMA cantilever beam, adaptive time stepping, and MPI four-point bending.
  • Concepts: the assembler, the element loop, and trial/commit state management.
  • External loads: LoadHandler, the four load types, and their placement in the Newton loop.
  • Performance and parallel execution: choosing the linear solver, the rank and thread layout, BLAS threads, and memory per rank.
  • In-plane wrappers: PlaneStrain and PlaneStress usage.
  • Developer guide: how to implement your own material model.
  • FAQ: possible uncertainties and troubleshooting.
API reference
  • General API: the assembler, loads, time stepping, and material interface API.
  • Material model API: constructors of the bundled material models and the in-plane wrappers.

Related packages and acknowledgements

FerriteSolidMechanics.jl follows conventions established by earlier Julia packages. The material_response interface, the AbstractMaterial / AbstractMaterialState pair, and the PlaneStrain / PlaneStress wrapper names originate from MaterialModels.jl (K. Auth and contributors), from which MaterialModelsBase.jl (K. A. Meyer) was developed as an implementation-independent interface package; materials written for MaterialModelsBase can be used here through the FromMaterialModelsBase wrapper. FerriteAssembly.jl (K. A. Meyer) covers similar ground to the assembler and the LoadHandler in this package, and FerriteDistributed.jl is a partitioned alternative to the replicated MPI assembly used here. The assembler entry points, the _assemble_element! and alpha_value hooks, and that replicated MPI assembly originate from CAPRICCIO (J. Roksvaag), a concurrent FE–MD coupling tool. The Ψ(C) / constitutive_driver convention and the element integration loops originate from Ferrite.jl's tutorials; per-model provenance is on the material documentation pages.

The documentation compares these packages in more detail.

License

FerriteSolidMechanics.jl is distributed under the MIT license; see LICENSE. See the individual material documentation pages for scientific references, implementation provenance, and acknowledgements.

About

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

Resources

Contributing

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages