fenics-constitutive

This project provides a framework for using nonlinear constitutive material models in dolfinx with the goal of making it easy to implement new models and to use these models interchangeably in a simulation. This is made possible by prescribing a simple interface for the constitutive models and by providing a simple wrapper around the dolfinx NonlinearProblem that uses the constitutive model to compute the residual and the stiffness matrix. The project is currently focussed on small strain models with the goal of supporting large deformations through the use of objective stress rates and, therefore, also supporting a subset of the functionality provided by Abaqus UMATs or Ansys material models.

Although the project contains some constitutive models -- and will contain more in the foreseeable future -- we are currently not focussed on creating a comprehensive library of models. Instead, through the simplicity of the provided interface which only uses numpy.ndarray as a complex datatype, we want to enable users to write their own models in any language that can be linked to Python, while still being able to use their models in simulation scripts that other users have written using our interface.

Documentation

https://fenics-constitutive.readthedocs.io/en/latest/

Installation using conda/mamba

Clone the repository and create a new environment from the environment.yml file:

bash git clone https://github.com/BAMresearch/fenics-constitutive.git cd fenics-constitutive mamba env create -f environment.yml This automatically installs the required dependencies and the package itself.

Alternatively, if you have all dependencies listed in the environment.yml file installed, you can install the package using pip after cloning:

bash git clone https://github.com/BAMresearch/fenics-constitutive.git cd fenics-constitutive pip install -e .

Usage

Since this project is based on FEniCSx, a basic knowledge of using FEniCSx is required. Similarly to any other FEniCSx project, you need to create a mesh, function spaces and boundary conditions. Defining the weak form is handled by the IncrSmallStrainProblem class. However, you may write your own Newton solver.

```python import dolfinx as df from dolfinx.nls.petsc import NewtonSolver from fenicsconstitutive import ( IncrSmallStrainProblem, IncrSmallStrainModel, StressStrainConstraint, ) from fenicsconstitutive.models import LinearElasticityModel

youngsmodulus = 42.0 poissonsratio = 0.3

mesh = df.mesh.createunitcube(MPI.COMMWORLD, 2, 2, 2) V = df.fem.functionspace(mesh, ("CG", 2, (2,))) u = df.fem.Function(V) law = LinearElasticityModel( {"E": youngsmodulus, "nu": poissons_ratio}, StressStrainConstraint.FULL, )

def left_boundary(x): return np.isclose(x[0], 0.0)

def right_boundary(x): return np.isclose(x[0], 1.0)

dofsleft = df.fem.locatedofsgeometrical(V, leftboundary) dofsright = df.fem.locatedofsgeometrical(V, rightboundary) bcleft = df.fem.dirichletbc(np.array([0.0, 0.0, 0.0]), dofsleft, V) bcright = df.fem.dirichletbc(np.array([0.01, 0.0, 0.0]), dofsright, V)

problem = IncrSmallStrainProblem( law, u, [bcleft, bcright], 1, )

solver = NewtonSolver(MPI.COMM_WORLD, problem) n, converged = solver.solve(u) problem.update()

```

Currently the Python package contains the following models:

1. Linear elasticity for uniaxial stress, uniaxial strain, plane stress, plane strain, and full 3D stress and strain states.
2. Mises plasticity with isotropic nonlinear hardening.
3. Two viscoelasticity models: Standard linear solid model in both Maxwell representation and Kelvin-Voigt representation.

Citing

If you use this package in your research, please cite it using the following bibtex entry for our paper in Advances in Engineering Software:

bibtex @Article{Rosenbusch2025AiES, author = {Sjard Mathis Rosenbusch and Philipp Diercks and Vitaliy Kindrachuk and Jörg F. Unger}, journal = {Advances in Engineering Software}, title = {Integrating custom constitutive models into FEniCSx: A versatile approach and case studies}, year = {2025}, issn = {0965-9978}, pages = {103922}, volume = {206}, doi = {https://doi.org/10.1016/j.advengsoft.2025.103922}, keywords = {Finite element method, Constitutive models, FEniCSx, UMAT, Rust, Python, C++}, url = {https://www.sciencedirect.com/science/article/pii/S0965997825000602}, }

Additionally, if you want to cite a specific version of the software, you can use the published records on Zenodo.