Constitution

This module provides constitutive material formulations.

Linear-Elasticity

LinearElastic([E, nu])	Isotropic linear-elastic material formulation.
LinearElasticPlaneStrain(E, nu)	Plane-strain isotropic linear-elastic material formulation.
LinearElasticPlaneStress(E, nu)	Plane-stress isotropic linear-elastic material formulation.
constitution.LinearElasticTensorNotation([...])	Isotropic linear-elastic material formulation.
LinearElasticLargeStrain([E, nu, parallel])	Linear-elastic material formulation suitable for large-rotation analyses based on the nearly-incompressible Neo-Hookean material formulation.

Plasticity

LinearElasticPlasticIsotropicHardening(E, ...)

Linear-elastic-plastic material formulation with linear isotropic hardening (return mapping algorithm).

Hyperelasticity

NeoHooke([mu, bulk, parallel])	Nearly-incompressible isotropic hyperelastic Neo-Hooke material formulation.
ThreeFieldVariation(material[, parallel])	Hu-Washizu hydrostatic-volumetric selective \((\boldsymbol{u},p,J)\) - three-field variation for nearly- incompressible material formulations.

Pseudo-Elasticity (Isotropic Damage)

OgdenRoxburgh(material, r, m, beta)

A Pseudo-Elastic material formulation for an isotropic treatment of the load-history dependent Mullins-softening of rubber-like materials.

Hyperelastic User-Materials with Automatic Differentation

Hyperelastic(fun[, nstatevars, parallel])	A user-defined hyperelastic material definition with a given function for the strain energy function with Automatic Differentiation provided by tensortrax.
constitution.saint_venant_kirchhoff(C, mu, lmbda)	Strain energy function of the Saint Venant-Kirchhoff material formulation.
constitution.neo_hooke(C, mu)	Strain energy function of the Neo-Hookean material formulation.
constitution.mooney_rivlin(C, C10, C01)	Strain energy function of the Mooney-Rivlin material formulation.
constitution.yeoh(C, C10, C20, C30)
constitution.third_order_deformation(C, C10, ...)	Strain energy function of the Third-Order-Deformation material formulation.
constitution.ogden(C, mu, alpha)	Strain energy function of the Ogden material formulation.
constitution.arruda_boyce(C, C1, limit)	Strain energy function of the Arruda-Boyce material formulation.
constitution.extended_tube(C, Gc, delta, Ge, ...)	Strain energy function of the Extended-Tube material formulation.
constitution.van_der_waals(C, mu, limit, a, beta)	Strain energy function of the Van der Waals material formulation.

(Small) Strain-based User Materials

MaterialStrain(material[, dim, statevars])	A strain-based user-defined material definition with a given function for the stress tensor and the (fourth-order) elasticity tensor.
constitution.linear_elastic(dε, εn, σn, ζn, ...)	3D linear-elastic material formulation.
constitution.linear_elastic_plastic_isotropic_hardening(dε, ...)	Linear-elastic-plastic material formulation with linear isotropic hardening (return mapping algorithm).

Deformation-Gradient-based User Materials

Material(stress, elasticity[, nstatevars])

A user-defined material definition with given functions for the (first Piola-Kirchhoff) stress tensor and the according fourth-order elasticity tensor.

Kinematics

LineChange([parallel])	Line Change.
AreaChange([parallel])	Area Change.
VolumeChange([parallel])	Volume Change.

Detailed API Reference

class felupe.NeoHooke(mu=None, bulk=None, parallel=False)

Nearly-incompressible isotropic hyperelastic Neo-Hooke material formulation. The strain energy density function of the Neo-Hookean material formulation is a linear function of the trace of the isochoric part of the right Cauchy-Green deformation tensor.

In a nearly-incompressible constitutive framework the strain energy density is an additive composition of an isochoric and a volumetric part. While the isochoric part is defined on the distortional part of the deformation gradient, the volumetric part of the strain energy function is defined on the determinant of the deformation gradient.

\[ \begin{align}\begin{aligned}\psi &= \hat{\psi}(\hat{\boldsymbol{C}}) + U(J)\\\hat\psi(\hat{\boldsymbol{C}}) &= \frac{\mu}{2} (\text{tr}(\hat{\boldsymbol{C}}) - 3)\end{aligned}\end{align} \]

with

\[ \begin{align}\begin{aligned}J &= \text{det}(\boldsymbol{F})\\\hat{\boldsymbol{F}} &= J^{-1/3} \boldsymbol{F}\\\hat{\boldsymbol{C}} &= \hat{\boldsymbol{F}}^T \hat{\boldsymbol{F}}\end{aligned}\end{align} \]

The volumetric part of the strain energy density function is a function the volume ratio.

\[U(J) = \frac{K}{2} (J - 1)^2\]

The first Piola-Kirchhoff stress tensor is evaluated as the gradient of the strain energy density function. The hessian of the strain energy density function enables the corresponding elasticity tensor.

\[ \begin{align}\begin{aligned}\boldsymbol{P} &= \frac{\partial \psi}{\partial \boldsymbol{F}}\\\mathbb{A} &= \frac{\partial^2 \psi}{\partial \boldsymbol{F}\ \partial \boldsymbol{F}}\end{aligned}\end{align} \]

A chain rule application leads to the following expression for the stress tensor. It is formulated as a sum of the physical-deviatoric (not the mathematical deviator!) and the physical-hydrostatic stress tensors.

\[ \begin{align}\begin{aligned}\boldsymbol{P} &= \boldsymbol{P}' + \boldsymbol{P}_U\\\boldsymbol{P}' &= \frac{\partial \hat{\psi}}{\partial \hat{\boldsymbol{F}}} : \frac{\partial \hat{\boldsymbol{F}}}{\partial \boldsymbol{F}} = \bar{\boldsymbol{P}} - \frac{1}{3} (\bar{\boldsymbol{P}} : \boldsymbol{F}) \boldsymbol{F}^{-T}\\\boldsymbol{P}_U &= \frac{\partial U(J)}{\partial J} \frac{\partial J}{\partial \boldsymbol{F}} = U'(J) J \boldsymbol{F}^{-T}\end{aligned}\end{align} \]

with

\[ \begin{align}\begin{aligned}\frac{\partial \hat{\boldsymbol{F}}}{\partial \boldsymbol{F}} &= J^{-1/3} \left( \boldsymbol{I} \overset{ik}{\otimes} \boldsymbol{I} - \frac{1}{3} \boldsymbol{F} \otimes \boldsymbol{F}^{-T} \right)\\\frac{\partial J}{\partial \boldsymbol{F}} &= J \boldsymbol{F}^{-T}\\\bar{\boldsymbol{P}} &= J^{-1/3} \frac{\partial \hat{\psi}}{\partial \hat{\boldsymbol{F}}}\end{aligned}\end{align} \]

With the above partial derivatives the first Piola-Kirchhoff stress tensor of the Neo-Hookean material model takes the following form.

\[\boldsymbol{P} = \mu J^{-2/3} \left( \boldsymbol{F} - \frac{1}{3} ( \boldsymbol{F} : \boldsymbol{F}) \boldsymbol{F}^{-T} \right) + K (J - 1) J \boldsymbol{F}^{-T}\]

Again, a chain rule application leads to an expression for the elasticity tensor.

\[ \begin{align}\begin{aligned}\mathbb{A} &= \mathbb{A}' + \mathbb{A}_{U}\\\mathbb{A}' &= \bar{\mathbb{A}} - \frac{1}{3} \left( (\bar{\mathbb{A}} : \boldsymbol{F}) \otimes \boldsymbol{F}^{-T} + \boldsymbol{F}^{-T} \otimes (\boldsymbol{F} : \bar{\mathbb{A}}) \right ) + \frac{1}{9} (\boldsymbol{F} : \bar{\mathbb{A}} : \boldsymbol{F}) \boldsymbol{F}^{-T} \otimes \boldsymbol{F}^{-T}\\\mathbb{A}_{U} &= (U''(J) J + U'(J)) J \boldsymbol{F}^{-T} \otimes \boldsymbol{F}^{-T} - U'(J) J \boldsymbol{F}^{-T} \overset{il}{\otimes} \boldsymbol{F}^{-T}\end{aligned}\end{align} \]

with

\[\bar{\mathbb{A}} = J^{-1/3} \frac{\partial^2 \hat\psi}{\partial \hat{\boldsymbol{F}}\ \partial \hat{\boldsymbol{F}}} J^{-1/3}\]

With the above partial derivatives the (physical-deviatoric and -hydrostatic) parts of the elasticity tensor associated to the first Piola-Kirchhoff stress tensor of the Neo-Hookean material model takes the following form.

\[ \begin{align}\begin{aligned}\mathbb{A} &= \mathbb{A}' + \mathbb{A}_{U}\\\mathbb{A}' &= J^{-2/3} \left(\boldsymbol{I} \overset{ik}{\otimes} \boldsymbol{I} - \frac{1}{3} \left( \boldsymbol{F} \otimes \boldsymbol{F}^{-T} + \boldsymbol{F}^{-T} \otimes \boldsymbol{F} \right ) + \frac{1}{9} (\boldsymbol{F} : \boldsymbol{F}) \boldsymbol{F}^{-T} \otimes \boldsymbol{F}^{-T} \right)\\\mathbb{A}_{U} &= K J \left( (2J - 1) \boldsymbol{F}^{-T} \otimes \boldsymbol{F}^{-T} - (J - 1) \boldsymbol{F}^{-T} \overset{il}{\otimes} \boldsymbol{F}^{-T} \right)\end{aligned}\end{align} \]

Parameters:

• mu (float) – Shear modulus

• bulk (float) – Bulk modulus

function(x, mu=None, bulk=None)

Strain energy density function per unit undeformed volume of the Neo-Hookean material formulation.

Parameters:

• x (list of ndarray) – List with the Deformation gradient F (3x3) as first item

• mu (float, optional) – Shear modulus (default is None)

• bulk (float, optional) – Bulk modulus (default is None)

gradient(x, mu=None, bulk=None)

Gradient of the strain energy density function per unit undeformed volume of the Neo-Hookean material formulation.

Parameters:

• x (list of ndarray) – List with the Deformation gradient F (3x3) as first item

• mu (float, optional) – Shear modulus (default is None)

• bulk (float, optional) – Bulk modulus (default is None)

hessian(x, mu=None, bulk=None)

Hessian of the strain energy density function per unit undeformed volume of the Neo-Hookean material formulation.

Parameters:

• x (list of ndarray) – List with the Deformation gradient F (3x3) as first item

• mu (float, optional) – Shear modulus (default is None)

• bulk (float, optional) – Bulk modulus (default is None)

class felupe.OgdenRoxburgh(material, r, m, beta)

A Pseudo-Elastic material formulation for an isotropic treatment of the load-history dependent Mullins-softening of rubber-like materials.

\[ \begin{align}\begin{aligned}\eta(W, W_{max}) &= 1 - \frac{1}{r} erf\left( \frac{W_{max} - W} {m + \beta~W_{max}} \right)\\\boldsymbol{P} &= \eta \frac{\partial \psi}{\partial \boldsymbol{F}}\\\mathbb{A} &= \frac{\partial^2 \psi}{\partial \boldsymbol{F} \partial \boldsymbol{F}} + \frac{\partial \eta}{\partial \psi} \frac{\partial \psi} {\partial \boldsymbol{F}} \otimes \frac{\partial \psi}{\partial \boldsymbol{F}}\end{aligned}\end{align} \]

gradient(x)

hessian(x)

class felupe.LinearElastic(E=None, nu=None)

Isotropic linear-elastic material formulation.

\[\begin{split}\begin{bmatrix} \sigma_{11} \\ \sigma_{22} \\ \sigma_{33} \\ \sigma_{12} \\ \sigma_{23} \\ \sigma_{31} \end{bmatrix} = \frac{E}{(1+\nu)(1-2\nu)}\begin{bmatrix} 1-\nu & \nu & \nu & 0 & 0 & 0\\ \nu & 1-\nu & \nu & 0 & 0 & 0\\ \nu & \nu & 1-\nu & 0 & 0 & 0\\ 0 & 0 & 0 & \frac{1-2\nu}{2} & 0 & 0 \\ 0 & 0 & 0 & 0 & \frac{1-2\nu}{2} & 0 \\ 0 & 0 & 0 & 0 & 0 & \frac{1-2\nu}{2} \end{bmatrix} \cdot \begin{bmatrix} \varepsilon_{11} \\ \varepsilon_{22} \\ \varepsilon_{33} \\ 2 \varepsilon_{12} \\ 2 \varepsilon_{23} \\ 2 \varepsilon_{31} \end{bmatrix}\end{split}\]

with the strain tensor

\[\boldsymbol{\varepsilon} = \frac{1}{2} \left( \frac{\partial \boldsymbol{u}} {\partial \boldsymbol{X}} + \left( \frac{\partial \boldsymbol{u}} {\partial \boldsymbol{X}} \right)^T \right)\]

Parameters:

• E (float) – Young’s modulus.

• nu (float) – Poisson ratio.

gradient(x, E=None, nu=None)

Evaluate the stress tensor (as a function of the deformation gradient).

Parameters:

• x (list of ndarray) – List with Deformation gradient F (3x3) as first item

• E (float, optional) – Young’s modulus (default is None)

• nu (float, optional) – Poisson ratio (default is None)

Returns:

Stress tensor (3x3)

Return type:

ndarray

hessian(x=None, E=None, nu=None, shape=(1, 1))

Evaluate the elasticity tensor. The Deformation gradient is only used for the shape of the trailing axes.

Parameters:

• x (list of ndarray, optional) – List with Deformation gradient F (3x3) as first item (default is None)

• E (float, optional) – Young’s modulus (default is None)

• nu (float, optional) – Poisson ratio (default is None)

• shape ((int, ...), optional) – Tuple with shape of the trailing axes (default is (1, 1))

Returns:

elasticity tensor (3x3x3x3)

Return type:

ndarray

class felupe.LinearElasticLargeStrain(E=None, nu=None, parallel=False)

Linear-elastic material formulation suitable for large-rotation analyses based on the nearly-incompressible Neo-Hookean material formulation.

Parameters:

• E (float) – Young’s modulus.

• nu (float) – Poisson ratio.

See also

NeoHooke

Nearly-incompressible isotropic hyperelastic Neo-Hooke material formulation.

function(x, E=None, nu=None)

Evaluate the strain energy (as a function of the deformation gradient).

Parameters:

• x (list of ndarray) – List with Deformation gradient F (3x3) as first item

• E (float, optional) – Young’s modulus (default is None)

• nu (float, optional) – Poisson ratio (default is None)

Returns:

Stress tensor (3x3)

Return type:

ndarray

gradient(x, E=None, nu=None)

Evaluate the stress tensor (as a function of the deformation gradient).

Parameters:

• x (list of ndarray) – List with Deformation gradient F (3x3) as first item

• E (float, optional) – Young’s modulus (default is None)

• nu (float, optional) – Poisson ratio (default is None)

Returns:

Stress tensor (3x3)

Return type:

ndarray

hessian(x, E=None, nu=None)

Evaluate the elasticity tensor (as a function of the deformation gradient).

Parameters:

• x (list of ndarray) – List with Deformation gradient F (3x3) as first item.

• E (float, optional) – Young’s modulus (default is None)

• nu (float, optional) – Poisson ratio (default is None)

Returns:

elasticity tensor (3x3x3x3)

Return type:

ndarray

class felupe.constitution.LinearElasticTensorNotation(E=None, nu=None, parallel=False)

Isotropic linear-elastic material formulation.

\[ \begin{align}\begin{aligned}\boldsymbol{\sigma} &= 2 \mu \ \boldsymbol{\varepsilon} + \gamma \ \text{tr}(\boldsymbol{\varepsilon}) \ \boldsymbol{I}\\\frac{\boldsymbol{\partial \sigma}}{\partial \boldsymbol{\varepsilon}} &= 2 \mu \ \boldsymbol{I} \odot \boldsymbol{I} + \gamma \ \boldsymbol{I} \otimes \boldsymbol{I}\end{aligned}\end{align} \]

with the strain tensor

\[\boldsymbol{\varepsilon} = \frac{1}{2} \left( \frac{\partial \boldsymbol{u}} {\partial \boldsymbol{X}} + \left( \frac{\partial \boldsymbol{u}} {\partial \boldsymbol{X}} \right)^T \right)\]

Parameters:

• E (float) – Young’s modulus.

• nu (float) – Poisson ratio.

gradient(x=None, E=None, nu=None)

Evaluate the stress tensor (as a function of the deformation gradient).

Parameters:

• x (list of ndarray) – List with Deformation gradient F (3x3) as first item

• E (float, optional) – Young’s modulus (default is None)

• nu (float, optional) – Poisson ratio (default is None)

Returns:

Stress tensor (3x3)

Return type:

ndarray

hessian(x=None, E=None, nu=None, shape=(1, 1))

Evaluate the elasticity tensor. The Deformation gradient is only used for the shape of the trailing axes.

Parameters:

• x (list of ndarray. optional) – List with Deformation gradient F (3x3) as first item (default is None)

• E (float, optional) – Young’s modulus (default is None)

• nu (float, optional) – Poisson ratio (default is None)

• shape ((int, ...), optional) – Tuple with shape of the trailing axes (default is (1, 1))

Returns:

elasticity tensor (3x3x3x3)

Return type:

ndarray

class felupe.LinearElasticPlaneStress(E, nu)

Plane-stress isotropic linear-elastic material formulation.

Parameters:

• E (float) – Young’s modulus.

• nu (float) – Poisson ratio.

gradient(x, E=None, nu=None)

Evaluate the 2d-stress tensor from the deformation gradient.

Parameters:

• x (list of ndarray) – List with In-plane components (2x2) of the Deformation gradient F as first item

• E (float, optional) – Young’s modulus (default is None)

• nu (float, optional) – Poisson ratio (default is None)

Returns:

In-plane components of stress tensor (2x2)

Return type:

ndarray

hessian(x=None, E=None, nu=None, shape=(1, 1))

Evaluate the elasticity tensor from the deformation gradient.

Parameters:

• x (list of ndarray, optional) – List with In-plane components (2x2) of the Deformation gradient F as first item (default is None)

• E (float, optional) – Young’s modulus (default is None)

• nu (float, optional) – Poisson ratio (default is None)

• shape ((int, ...), optional) – Tuple with shape of the trailing axes (default is (1, 1))

Returns:

In-plane components of elasticity tensor (2x2x2x2)

Return type:

ndarray

strain(x, E=None, nu=None)

Evaluate the strain tensor from the deformation gradient.

Parameters:

• x (list of ndarray) – List with In-plane components (2x2) of the Deformation gradient F as first item

• E (float, optional) – Young’s modulus (default is None)

• nu (float, optional) – Poisson ratio (default is None)

Returns:

e – Strain tensor (3x3)

Return type:

ndarray

stress(x, E=None, nu=None)

“Evaluate the 3d-stress tensor from the deformation gradient.

Parameters:

• x (list of ndarray) – List with In-plane components (2x2) of the Deformation gradient F as first item

• E (float, optional) – Young’s modulus (default is None)

• nu (float, optional) – Poisson ratio (default is None)

Returns:

Stress tensor (3x3)

Return type:

ndarray

class felupe.LinearElasticPlaneStrain(E, nu)

Plane-strain isotropic linear-elastic material formulation.

Parameters:

• E (float) – Young’s modulus.

• nu (float) – Poisson ratio.

gradient(x, E=None, nu=None)

Evaluate the 2d-stress tensor from the deformation gradient.

Parameters:

• x (list of ndarray) – List with In-plane components (2x2) of the Deformation gradient F as first item

• E (float, optional) – Young’s modulus (default is None)

• nu (float, optional) – Poisson ratio (default is None)

Returns:

In-plane components of stress tensor (2x2)

Return type:

ndarray

hessian(x, E=None, nu=None)

Evaluate the 2d-elasticity tensor from the deformation gradient.

Parameters:

• x (list of ndarray) – List with In-plane components (2x2) of the Deformation gradient F as first item

• E (float, optional) – Young’s modulus (default is None)

• nu (float, optional) – Poisson ratio (default is None)

Returns:

In-plane components of elasticity tensor (2x2x2x2)

Return type:

ndarray

strain(x, E=None, nu=None)

Evaluate the strain tensor from the deformation gradient.

Parameters:

• x (list of ndarray) – List with In-plane components (2x2) of the Deformation gradient F as first item

• E (float, optional) – Young’s modulus (default is None)

• nu (float, optional) – Poisson ratio (default is None)

Returns:

e – Strain tensor (3x3)

Return type:

ndarray

stress(x, E=None, nu=None)

“Evaluate the 3d-stress tensor from the deformation gradient.

Parameters:

• x (list of ndarray) – List with In-plane components (2x2) of the Deformation gradient F as first item

• E (float, optional) – Young’s modulus (default is None)

• nu (float, optional) – Poisson ratio (default is None)

Returns:

Stress tensor (3x3)

Return type:

ndarray

class felupe.LinearElasticPlasticIsotropicHardening(E, nu, sy, K)

Linear-elastic-plastic material formulation with linear isotropic hardening (return mapping algorithm).

extract(x)

Extract the input and evaluate strains, stresses and state variables.

gradient(x)

hessian(x)

class felupe.ThreeFieldVariation(material, parallel=False)

Hu-Washizu hydrostatic-volumetric selective \((\boldsymbol{u},p,J)\) - three-field variation for nearly- incompressible material formulations. The total potential energy for nearly-incompressible hyperelasticity is formulated with a determinant-modified deformation gradient. Pressure and volume ratio fields should be kept one order lower than the interpolation order of the displacement field, e.g. linear displacement fields should be paired with element-constant (mean) values of pressure and volume ratio.

The total potential energy of internal forces is defined with a strain energy density function in terms of a determinant-modified deformation gradient and an additional control equation.

\[ \begin{align}\begin{aligned}\Pi &= \Pi_{int} + \Pi_{ext}\\\Pi_{int} &= \int_V \psi(\boldsymbol{F}) \ dV \qquad \rightarrow \qquad \Pi_{int}(\boldsymbol{u},p,J) = \int_V \psi(\overline{\boldsymbol{F}}) \ dV + \int_V p (J-\overline{J}) \ dV\\\overline{\boldsymbol{F}} &= \left(\frac{\overline{J}}{J}\right)^{1/3} \boldsymbol{F}\end{aligned}\end{align} \]

The variations of the total potential energy w.r.t. \((\boldsymbol{u},p,J)\) lead to the following expressions. We denote first partial derivatives as \(\boldsymbol{f}_{(\bullet)}\) and second partial derivatives as \(\boldsymbol{A}_{(\bullet,\bullet)}\).

\[ \begin{align}\begin{aligned}\delta_{\boldsymbol{u}} \Pi_{int} &= \int_V \boldsymbol{f}_{\boldsymbol{u}} : \delta \boldsymbol{F} \ dV = \int_V \left( \frac{\partial \psi} {\partial \overline{\boldsymbol{F}}} : \frac{\partial \overline{\boldsymbol{F}}} {\partial \boldsymbol{F}} + p J \boldsymbol{F}^{-T} \right) : \delta \boldsymbol{F} \ dV\\\delta_{p} \Pi_{int} &= \int_V f_{p} \ \delta p \ dV = \int_V (J - \overline{J}) \ \delta p \ dV\\\delta_{\overline{J}} \Pi_{int} &= \int_V f_{\overline{J}} \ \delta \overline{J} \ dV = \int_V \left( \frac{\partial \psi}{\partial \overline{\boldsymbol{F}}} : \frac{\partial \overline{\boldsymbol{F}}}{\partial \overline{J}} - p \right) : \delta \overline{J} \ dV\end{aligned}\end{align} \]

The projection tensors from the variations lead the following results.

\[ \begin{align}\begin{aligned}\frac{\partial \overline{\boldsymbol{F}}}{\partial \boldsymbol{F}} &= \left(\frac{\overline{J}}{J}\right)^{1/3} \left( \boldsymbol{I} \overset{ik}{\odot} \boldsymbol{I} - \frac{1}{3} \boldsymbol{F} \otimes \boldsymbol{F}^{-T} \right)\\\frac{\partial \overline{\boldsymbol{F}}}{\partial \overline{J}} &= \frac{1}{3 \overline{J}} \overline{\boldsymbol{F}}\end{aligned}\end{align} \]

The double-dot products from the variations are now evaluated.

\[ \begin{align}\begin{aligned}\overline{\boldsymbol{P}} &= \frac{\partial \psi}{\partial \overline{\boldsymbol{F}}} = \overline{\overline{\boldsymbol{P}}} - \frac{1}{3} \left( \overline{\overline{\boldsymbol{P}}} : \boldsymbol{F} \right) \boldsymbol{F}^{-T} \qquad \text{with} \qquad \overline{\overline{\boldsymbol{P}}} = \left(\frac{\overline{J}}{J}\right)^{1/3} \frac{\partial \psi}{\partial \overline{\boldsymbol{F}}}\\\frac{\partial \psi}{\partial \overline{\boldsymbol{F}}} : \frac{1}{3 \overline{J}} \overline{\boldsymbol{F}} &= \frac{1}{3 \overline{J}} \overline{\overline{\boldsymbol{P}}} : \boldsymbol{F}\end{aligned}\end{align} \]

We now have three formulas; one for the first Piola Kirchhoff stress and two additional control equations.

\[ \begin{align}\begin{aligned}\boldsymbol{f}_{\boldsymbol{u}} (= \boldsymbol{P}) &= \overline{\overline{\boldsymbol{P}}} - \frac{1}{3} \left( \overline{\overline{\boldsymbol{P}}} : \boldsymbol{F} \right) \boldsymbol{F}^{-T}\\f_p &= J - \overline{J}\\f_{\overline{J}} &= \frac{1}{3 \overline{J}} \left( \overline{\overline{\boldsymbol{P}}} : \boldsymbol{F} \right) - p\end{aligned}\end{align} \]

A linearization of the above formulas gives six equations (only results are given here).

\[ \begin{align}\begin{aligned}\mathbb{A}_{\boldsymbol{u},\boldsymbol{u}} &= \overline{\overline{\mathbb{A}}} + \frac{1}{9} \left( \boldsymbol{F} : \overline{\overline{\mathbb{A}}} : \boldsymbol{F} \right) \boldsymbol{F}^{-T} \otimes \boldsymbol{F}^{-T} - \frac{1}{3} \left( \boldsymbol{F}^{-T} \otimes \left( \overline{\overline{\boldsymbol{P}}} + \boldsymbol{F} : \overline{\overline{\mathbb{A}}} \right) + \left( \overline{\overline{\boldsymbol{P}}} + \overline{\overline{\mathbb{A}}} : \boldsymbol{F} \right) \otimes \boldsymbol{F}^{-T} \right)\\&+\left( p J + \frac{1}{9} \overline{\overline{\boldsymbol{P}}} : \boldsymbol{F} \right) \boldsymbol{F}^{-T} \otimes \boldsymbol{F}^{-T} - \left( p J - \frac{1}{3} \overline{\overline{\boldsymbol{P}}} : \boldsymbol{F} \right) \boldsymbol{F}^{-T} \overset{il}{\odot} \boldsymbol{F}^{-T}\\A_{p,p} &= 0\\A_{\overline{J},\overline{J}} &= \frac{1}{9 \overline{J}^2} \left( \boldsymbol{F} : \overline{\overline{\mathbb{A}}} : \boldsymbol{F} \right) - 2 \left( \overline{\overline{\boldsymbol{P}}} : \boldsymbol{F} \right)\\\boldsymbol{A}_{\boldsymbol{u},p} &= \boldsymbol{A}_{p, \boldsymbol{u}} = J \boldsymbol{F}^{-T}\\\boldsymbol{A}_{\boldsymbol{u},\overline{J}} &= \boldsymbol{A}_{\overline{J}, \boldsymbol{u}} = \frac{1}{3 \overline{J}} \left( \boldsymbol{P}' + \boldsymbol{F} : \overline{\overline{\mathbb{A}}} - \frac{1}{3} \left( \boldsymbol{F} : \overline{\overline{\mathbb{A}}} : \boldsymbol{F} \right) \boldsymbol{F}^{-T} \right)\\A_{p,\overline{J}} &= A_{\overline{J}, p} = -1\end{aligned}\end{align} \]

with

\[\overline{\overline{\mathbb{A}}} = \left(\frac{\overline{J}}{J}\right)^{1/3} \frac{\partial^2 \psi}{\partial \overline{\boldsymbol{F}} \partial \overline{\boldsymbol{F}}} \left(\frac{\overline{J}}{J}\right)^{1/3}\]

as well as

\[\boldsymbol{P}' = \boldsymbol{P} - p J \boldsymbol{F}^{-T}\]

Parameters:

material (Material) – A material definition with gradient and hessian methods.

fun_P

Method for gradient evaluation

Type:

function

fun_A

Method for hessian evaluation

Type:

function

detF

Determinant of deformation gradient

Type:

ndarray

iFT

Transpose of inverse of the deformation gradient

Type:

ndarray

Fb

Determinant-modified deformation gradient

Type:

ndarray

Pb

First Piola-Kirchhoff stress tensor (in determinant-modified framework)

Type:

ndarray

Pbb

Determinant-modification multiplied by Pb

Type:

ndarray

PbbF

Double-dot product of Pb and the deformation gradient

Type:

ndarray

class Material(stress, elasticity, nstatevars=0, **kwargs)

A user-defined material definition with given functions for the (first Piola-Kirchhoff) stress tensor and the according fourth-order elasticity tensor. Both functions take a list of the deformation gradient and optional state variables as the first input argument. The stress-function also returns the updated state variables.

Take this code-block as template:

def stress(x, **kwargs):
    "First Piola-Kirchhoff stress tensor."

    # extract variables
    F, statevars = x[0], x[-1]

    # user code for (first Piola-Kirchhoff) stress tensor
    P = None

    # update state variables
    statevars_new = None

    return [P, statevars_new]

def elasticity(x, **kwargs):
    "Fourth-order elasticity tensor."

    # extract variables
    F, statevars = x[0], x[-1]

    # user code for fourth-order elasticity tensor
    # according to the (first Piola-Kirchhoff) stress tensor
    dPdF = None

    return [dPdF]

umat = Material(stress, elasticity, **kwargs)

Members:

Undoc-members:

Inherited-members:

gradient(x)

List of variations of total potential energy w.r.t displacements, pressure and volume ratio.

δ_u(Π_int) = ∫_V (∂ψ/∂F + p cof(F)) : δF dV
δ_p(Π_int) = ∫_V (det(F) - J) δp dV
δ_J(Π_int) = ∫_V (∂U/∂J - p) δJ dV

Parameters:

x (list of ndarray) – List of extracted field values with Deformation gradient F as first, the hydrostatic pressure p as second and the volume ratio J as third item.

Returns:

List of gradients w.r.t. the input variables F, p and J

Return type:

list of ndarrays

hessian(x)

List of linearized variations of total potential energy w.r.t displacements, pressure and volume ratio (these expressions are symmetric; A_up = A_pu if derived from a total potential energy formulation). List entries have to be arranged as a flattened list from the upper triangle blocks:

Δ_u(δ_u(Π_int)) = ∫_V δF : (∂²ψ/(∂F∂F) + p ∂cof(F)/∂F) : ΔF dV
Δ_p(δ_u(Π_int)) = ∫_V δF : J cof(F) Δp dV
Δ_J(δ_u(Π_int)) = ∫_V δF :  ∂²ψ/(∂F∂J) ΔJ dV
Δ_p(δ_p(Π_int)) = ∫_V δp 0 Δp dV
Δ_J(δ_p(Π_int)) = ∫_V δp (-1) ΔJ dV
Δ_J(δ_J(Π_int)) = ∫_V δJ ∂²ψ/(∂J∂J) ΔJ dV

[[0 1 2],
 [  3 4],
 [    5]] --> [0 1 2 3 4 5]

Parameters:

extract (list of ndarray) – List of extracted field values with Deformation gradient F as first, the hydrostatic pressure p as second and the volume ratio J as third item.

Returns:

List of hessians in upper triangle order

Return type:

list of ndarrays

class felupe.MaterialStrain(material, dim=3, statevars=(0,), **kwargs)

A strain-based user-defined material definition with a given function for the stress tensor and the (fourth-order) elasticity tensor.

Take this code-block from the linear-elastic material formulation

from felupe.math import identity, cdya, dya, trace

def linear_elastic(dε, εn, σn, ζn, λ, μ, **kwargs):
    '''3D linear-elastic material formulation.

    Arguments
    ---------
    dε : ndarray
        Incremental strain tensor.
    εn : ndarray
        Old strain tensor.
    σn : ndarray
        Old stress tensor.
    ζn : ndarray
        Old state variables.
    λ : float
        First Lamé-constant.
    μ : float
        Second Lamé-constant (shear modulus).
    '''

    # change of stress due to change of strain
    I = identity(dε)
    dσ = 2 * μ * dε + λ * trace(dε) * I

    # update stress and evaluate elasticity tensor
    σ = σn + dσ
    dσdε = 2 * μ * cdya(I, I) + λ * dya(I, I)

    # update state variables (not used here)
    ζ = ζn

    return dσdε, σ, ζ

umat = MaterialStrain(material=linear_elastic, μ=1, λ=2)

or this minimal header as template:

def fun(dε, εn, σn, ζn, **kwargs):
    return dσdε, σ, ζ

umat = MaterialStrain(material=fun, **kwargs)

extract(x)

Extract the input and evaluate strains, stresses and state variables.

gradient(x)

hessian(x)

felupe.constitution.linear_elastic(dε, εn, σn, ζn, λ, μ, **kwargs)

3D linear-elastic material formulation.

Parameters:

• dε (ndarray) – Strain increment.

• εn (ndarray) – Old strain tensor.

• σn (ndarray) – Old stress tensor.

• ζn (list) – List of old state variables.

• λ (float) – First Lamé-constant.

• μ (float) – Second Lamé-constant (shear modulus).

Returns:

• dσdε (ndarray) – Elasticity tensor.

• σ (ndarray) – (New) stress tensor.

• ζ (list) – List of new state variables.

Notes

1. Given state in point \(\boldsymbol{x} (\boldsymbol{\sigma}_n)\) (valid).

2. Given strain increment \(\Delta\boldsymbol{\varepsilon}\), so that \(\boldsymbol{\varepsilon} = \boldsymbol{\varepsilon}_n + \Delta\boldsymbol{\varepsilon}\).

3. Evaluation of the stress \(\boldsymbol{\sigma}\) and the algorithmic consistent tangent modulus \(\mathbb{C}\) (=``dσdε``).

   \[ \begin{align}\begin{aligned}\mathbb{C} &= \lambda \ \boldsymbol{1} \otimes \boldsymbol{1} + 2 \mu \ \boldsymbol{1} \odot \boldsymbol{1}\\\boldsymbol{\sigma} &= \boldsymbol{\sigma}_n + \mathbb{C} : \Delta\boldsymbol{\varepsilon}\end{aligned}\end{align} \]

felupe.constitution.linear_elastic_plastic_isotropic_hardening(dε, εn, σn, ζn, λ, μ, σy, K, **kwargs)

Linear-elastic-plastic material formulation with linear isotropic hardening (return mapping algorithm).

Parameters:

• dε (ndarray) – Strain increment.

• εn (ndarray) – Old strain tensor.

• σn (ndarray) – Old stress tensor.

• ζn (list) – List of old state variables.

• λ (float) – First Lamé-constant.

• μ (float) – Second Lamé-constant (shear modulus).

• σy (float) – Initial yield stress.

• K (float) – Isotropic hardening modulus.

Returns:

• dσdε (ndarray) – Algorithmic consistent elasticity tensor.

• σ (ndarray) – (New) stress tensor.

• ζ (list) – List of new state variables.

Notes

1. Given state in point \(x (\sigma_n, \zeta_n=[\varepsilon^p_n, \alpha_n])\) (valid).

2. Given strain increment \(\Delta\varepsilon\), so that \(\varepsilon = \varepsilon_n + \Delta\varepsilon\).

3. Evaluation of the hypothetic trial state:

   \[ \begin{align}\begin{aligned}\mathbb{C} &= \lambda\ \boldsymbol{1} \otimes \boldsymbol{1} + 2 \mu\ \boldsymbol{1} \odot \boldsymbol{1}\\\sigma &= \sigma_n + \mathbb{C} : \Delta\varepsilon\\s &= \text{dev}(\sigma)\\\varepsilon^p &= \varepsilon^p_n\\\alpha &= \alpha_n\\f &= ||s|| - \sqrt{\frac{2}{3}}\ (\sigma_y + K \alpha)\end{aligned}\end{align} \]

4. If \(f \le 0\), then elastic step:

   Set \(y = y_n + \Delta y, y=(\sigma, \zeta=[\varepsilon^p, \alpha])\),

   algorithmic consistent tangent modulus \(d\sigma d\varepsilon\).

   \[d\sigma d\varepsilon = \mathbb{C}\]

   Else:

   \[ \begin{align}\begin{aligned}d\gamma &= \frac{f}{2\mu + \frac{2}{3} K}\\n &= \frac{s}{||s||}\\\sigma &= \sigma - 2\mu \Delta\gamma n\\\varepsilon^p &= \varepsilon^p_n + \Delta\gamma n\\\alpha &= \alpha_n + \sqrt{\frac{2}{3}}\ \Delta\gamma\end{aligned}\end{align} \]

   Algorithmic consistent tangent modulus:

   \[d\sigma d\varepsilon = \mathbb{C} - \frac{2 \mu}{1 + \frac{K}{3 \mu}} n \otimes n - \frac{2 \mu \Delta\gamma}{||s||} \left[ 2 \mu \left( \boldsymbol{1} \odot \boldsymbol{1} - \frac{1}{3} \boldsymbol{1} \otimes \boldsymbol{1} - n \otimes n \right) \right]\]

class felupe.Hyperelastic(fun, nstatevars=0, parallel=False, **kwargs)

A user-defined hyperelastic material definition with a given function for the strain energy function with Automatic Differentiation provided by tensortrax.

Take this code-block as template

import tensortrax.math as tm

def neo_hooke(C, mu):
    "Strain energy function of the Neo-Hookean material formulation."
    return mu / 2 * (tm.linalg.det(C) ** (-1/3) * tm.trace(C) - 3)

umat = fem.Hyperelastic(neo_hooke, mu=1)

and this code-block for material formulations with state variables:

import tensortrax.math as tm

def viscoelastic(C, Cin, mu, eta, dtime):
    "Finite strain viscoelastic material formulation."

    # unimodular part of the right Cauchy-Green deformation tensor
    Cu = det(C) ** (-1 / 3) * C

    # update of state variables by evolution equation
    Ci = tm.special.from_triu_1d(Cin, like=C) + mu / eta * dtime * Cu
    Ci = det(Ci) ** (-1 / 3) * Ci

    # first invariant of elastic part of right Cauchy-Green deformation tensor
    I1 = tm.trace(Cu @ inv(Ci))

    # strain energy function and state variable
    return mu / 2 * (I1 - 3), tm.special.triu_1d(Ci)

umat = fem.Hyperelastic(
    viscoelastic, mu=1, eta=1, dtime=1, nstatevars=6
)

See the documentation of tensortrax for further details.

gradient(x)

hessian(x)

felupe.constitution.saint_venant_kirchhoff(C, mu, lmbda)

Strain energy function of the Saint Venant-Kirchhoff material formulation. Here, I1 and I2 are strain invariants of the Green-Lagrange strain tensor.

felupe.constitution.neo_hooke(C, mu)

Strain energy function of the Neo-Hookean material formulation.

felupe.constitution.mooney_rivlin(C, C10, C01)

Strain energy function of the Mooney-Rivlin material formulation.

felupe.constitution.yeoh(C, C10, C20, C30)

felupe.constitution.third_order_deformation(C, C10, C01, C11, C20, C30)

Strain energy function of the Third-Order-Deformation material formulation.

felupe.constitution.ogden(C, mu, alpha)

Strain energy function of the Ogden material formulation.

felupe.constitution.arruda_boyce(C, C1, limit)

Strain energy function of the Arruda-Boyce material formulation.

felupe.constitution.extended_tube(C, Gc, delta, Ge, beta)

Strain energy function of the Extended-Tube material formulation.

felupe.constitution.van_der_waals(C, mu, limit, a, beta)

Strain energy function of the Van der Waals material formulation.

class felupe.LineChange(parallel=False)

Line Change.

\[d\boldsymbol{x} = \boldsymbol{F} d\boldsymbol{X}\]

Gradient:

\[\frac{\partial \boldsymbol{F}}{\partial \boldsymbol{F}} = \boldsymbol{I} \overset{ik}{\otimes} \boldsymbol{I}\]

function(extract)

Line change.

Parameters:

extract (list of ndarray) – List of extracted field values with Deformation gradient as first item.

Returns:

F – Deformation gradient

Return type:

ndarray

gradient(extract, parallel=None)

Gradient of line change.

Parameters:

extract (list of ndarray) – List of extracted field values with Deformation gradient as first item.

Returns:

Gradient of line change

Return type:

ndarray

class felupe.AreaChange(parallel=False)

Area Change.

\[d\boldsymbol{a} = J \boldsymbol{F}^{-T} d\boldsymbol{A}\]

Gradient:

\[\frac{\partial J \boldsymbol{F}^{-T}}{\partial \boldsymbol{F}} = J \left( \boldsymbol{F}^{-T} \otimes \boldsymbol{F}^{-T} - \boldsymbol{F}^{-T} \overset{il}{\otimes} \boldsymbol{F}^{-T} \right)\]

function(extract, N=None, parallel=None)

Area change.

Parameters:

• extract (list of ndarray) – List of extracted field values with Deformation gradient as first item.

• N (ndarray or None, optional) – Area normal vector (default is None)

Returns:

Cofactor matrix of the deformation gradient

Return type:

ndarray

gradient(extract, N=None, parallel=None)

Gradient of area change.

Parameters:

• extract (list of ndarray) – List of extracted field values with Deformation gradient as first item.

• N (ndarray or None, optional) – Area normal vector (default is None)

Returns:

Gradient of cofactor matrix of the deformation gradient

Return type:

ndarray

class felupe.VolumeChange(parallel=False)

Volume Change.

\[d\boldsymbol{v} = \text{det}(\boldsymbol{F}) d\boldsymbol{V}\]

Gradient and hessian (equivalent to gradient of area change):

\[ \begin{align}\begin{aligned}\frac{\partial J}{\partial \boldsymbol{F}} &= J \boldsymbol{F}^{-T}\\\frac{\partial^2 J}{\partial \boldsymbol{F}\ \partial \boldsymbol{F}} &= J \left( \boldsymbol{F}^{-T} \otimes \boldsymbol{F}^{-T} - \boldsymbol{F}^{-T} \overset{il}{\otimes} \boldsymbol{F}^{-T} \right)\end{aligned}\end{align} \]

function(extract)

Gradient of volume change.

Parameters:

extract (list of ndarray) – List of extracted field values with Deformation gradient as first item.

Returns:

J – Determinant of the deformation gradient

Return type:

ndarray

gradient(extract)

Gradient of volume change.

Parameters:

F (ndarray) – Deformation gradient

Returns:

Gradient of the determinant of the deformation gradient

Return type:

ndarray

hessian(extract, parallel=None)

Hessian of volume change.

Parameters:

extract (list of ndarray) – List of extracted field values with Deformation gradient as first item.

Returns:

Hessian of the determinant of the deformation gradient

Return type:

ndarray