Models

This page contains the core (hard-coded) constitutive material model formulations (not using automatic differentiation) for linear-elasticitiy, small-strain plasticity, hyperelasticity and pseudo-elasticity.

Poisson Equation

Laplace([multiplier])

Laplace equation as hessian of one half of the second main invariant of the field gradient.

Linear-Elasticity

LinearElastic(E, nu)	Isotropic linear-elastic material formulation.
LinearElasticPlaneStress(E, nu)	Plane-stress isotropic linear-elastic material formulation.
constitution.LinearElasticPlaneStrain(E, nu)	Plane-strain isotropic linear-elastic material formulation.
constitution.LinearElasticTensorNotation(E, nu)	Isotropic linear-elastic material formulation.
LinearElasticLargeStrain(E, nu[, parallel])	Linear-elastic material formulation suitable for large-strain analyses based on the compressible Neo-Hookean material formulation.
LinearElasticOrthotropic(E, nu, G)	Orthotropic linear-elastic 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-Hookean material formulation.
NeoHookeCompressible([mu, lmbda, parallel])	Compressible isotropic hyperelastic Neo-Hookean material formulation.
OgdenRoxburgh(material, r, m, beta)	Ogden-Roxburgh Pseudo-Elastic material formulation for an isotropic treatment of the load-history dependent Mullins-softening of rubber-like materials.

Mixed-Field Formulations \((\boldsymbol{u}, p, \bar{J})\)

ThreeFieldVariation(material[, parallel])	Hu-Washizu hydrostatic-volumetric selective \((\boldsymbol{u},p,J)\) - three-field variation for nearly- incompressible material formulations.
NearlyIncompressible(material, bulk[, ...])	A nearly-incompressible material formulation to augment the distortional part of the strain energy function by a volumetric part and a constraint equation.

Small Strain-based 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.
linear_elastic(dε, εn, σn, ζn, λ, μ, **kwargs)	3D linear-elastic material formulation to be used in MaterialStrain.
linear_elastic_plastic_isotropic_hardening(dε, ...)	Linear-elastic-plastic material formulation with linear isotropic hardening (return mapping algorithm) to be used in MaterialStrain.

Detailed API Reference

class felupe.Laplace(multiplier=1.0)

Laplace equation as hessian of one half of the second main invariant of the field gradient.

Parameters:

multiplier (float, optional) – A multiplier which scales the potential (default is 1.0).

Notes

The potential is given by the second main invariant of the field gradient w.r.t. the undeformed coordinates.

\[\psi = \frac{1}{2} \left( \boldsymbol{H} : \boldsymbol{H} \right)\]

with the field gradient w.r.t. the undeformed coordinates.

\[\boldsymbol{H} = \frac{\partial \boldsymbol{u}}{\partial \boldsymbol{X}}\]

Examples

>>> import felupe as fem
>>>
>>> umat = fem.Laplace()
>>> ax = umat.plot()

copy()

Return a deep-copy of the constitutive material.

function(x)

Evaluate the potential per unit undeformed volume.

Parameters:

x (list of ndarray) – List with Deformation gradient \(\boldsymbol{F}\) as first item.

Returns:

potential

Return type:

ndarray of shape (…)

gradient(x)

Evaluate the stress tensor.

Parameters:

x (list of ndarray) – List with Deformation gradient \(\boldsymbol{F}\) as first item.

Returns:

gradient of the potential w.r.t. the undeformed coordinates

Return type:

ndarray of shape (n, m, …)

hessian(x)

Evaluate the elasticity tensor.

Parameters:

x (list of ndarray) – List with Deformation gradient \(\boldsymbol{F}\) as first item.

Returns:

hessian of the potential w.r.t. the undeformed coordinates

Return type:

ndarray of shape (n, m, n, m, …)

optimize(ux=None, ps=None, bx=None, incompressible=False, relative=False, **kwargs)

Optimize the material parameters by a least-squares fit on experimental stretch-stress data.

Parameters:

• ux (array of shape (2, ...) or None, optional) – Experimental uniaxial stretch and force-per-undeformed-area data (default is None).

• ps (array of shape (2, ...) or None, optional) – Experimental planar-shear stretch and force-per-undeformed-area data (default is None).

• bx (array of shape (2, ...) or None, optional) – Experimental biaxial stretch and force-per-undeformed-area data (default is None).

• incompressible (bool, optional) – A flag to enforce incompressible deformations (default is False).

• relative (bool, optional) – A flag to optimize relative instead of absolute residuals, i.e. (predicted - observed) / observed instead of predicted - observed (default is False).

• **kwargs (dict, optional) – Optional keyword arguments are passed to scipy.optimize.least_squares().

Returns:

• ConstitutiveMaterial – A copy of the constitutive material with the optimized material parameters.

• scipy.optimize.OptimizeResult – Represents the optimization result.

Notes

Warning

At least one load case, i.e. one of the arguments ux, ps or bx must not be None.

The vector of residuals is given in Eq. (3) in case of absolute residuals

(1)\[ \begin{align}\begin{aligned}\begin{split}\boldsymbol{r} &= \begin{bmatrix} \boldsymbol{r}_\text{ux} \\ \boldsymbol{r}_\text{ps} \\ \boldsymbol{r}_\text{bx} \end{bmatrix}\end{split}\\r_\text{ux}(\lambda_i) &= P_\text{ux}(\lambda_i) - P_\text{ux, observed}(\lambda_i)\\r_\text{ps}(\lambda_i) &= P_\text{ps}(\lambda_i) - P_\text{ps, observed}(\lambda_i)\\r_\text{bx}(\lambda_i) &= P_\text{bx}(\lambda_i) - P_\text{bx, observed}(\lambda_i)\end{aligned}\end{align} \]

and in Eq. (4) in case of relative residuals.

(2)\[ \begin{align}\begin{aligned}\begin{split}\boldsymbol{r} &= \begin{bmatrix} \boldsymbol{r}_\text{ux} \\ \boldsymbol{r}_\text{ps} \\ \boldsymbol{r}_\text{bx} \end{bmatrix}\end{split}\\r_\text{ux}(\lambda_i) &= \frac{ P_\text{ux}(\lambda_i) - P_\text{ux, observed}(\lambda_i)}{ P_\text{ux, observed}(\lambda_i) }\\r_\text{ps}(\lambda_i) &= \frac{ P_\text{ps}(\lambda_i) - P_\text{ps, observed}(\lambda_i)}{ P_\text{ps, observed}(\lambda_i) }\\r_\text{bx}(\lambda_i) &= \frac{ P_\text{bx}(\lambda_i) - P_\text{bx, observed}(\lambda_i)}{ P_\text{bx, observed}(\lambda_i) }\end{aligned}\end{align} \]

Examples

The Anssari-Benam Bucchi material model formulation is best-fitted on Treloar’s uniaxial and biaxial tension data [1]_.

>>> import numpy as np
>>> import felupe as fem
>>>
>>> λ, P = np.array(
...     [
...         [1.000, 0.00],
...         [1.240, 2.30],
...         [1.585, 4.16],
...         [2.180, 6.00],
...         [3.020, 8.80],
...         [4.030, 12.5],
...         [4.760, 16.2],
...         [5.750, 23.6],
...         [6.850, 38.5],
...         [7.250, 49.6],
...         [7.600, 64.4],
...     ]
... ).T * np.array([[1.0], [0.0980665]])
>>>
>>> umat = fem.Hyperelastic(fem.anssari_benam_bucchi)
>>> umat_new, res = umat.optimize(
...     ux=[λ, P], incompressible=True, relative=True
... )
>>>
>>> ux = np.linspace(λ.min(), λ.max(), num=50)
>>> ax = umat_new.plot(incompressible=True, ux=ux, bx=None, ps=None)

>>> ax.plot(λ, P, "C0x")

See also

scipy.optimize.least_squares

Solve a nonlinear least-squares problem with bounds on the variables.

References

[1]

L. R. G. Treloar, “Stress-strain data for vulcanised rubber under various types of deformation”, Transactions of the Faraday Society, vol. 40. Royal Society of Chemistry (RSC), p. 59, 1944. doi: 10.1039/tf9444000059. Data available at https://www.uni-due.de/mathematik/ag_neff/neff_hencky.

plot(incompressible=False, **kwargs)

Return a plot with normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

matplotlib.axes.Axes

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

screenshot(filename='umat.png', incompressible=False, **kwargs)

Save a screenshot with normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• filename (str, optional) – The filename of the screenshot (default is “umat.png”).

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

matplotlib.axes.Axes

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

view(incompressible=False, **kwargs)

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

felupe.ViewMaterial or felupe.ViewMaterialIncompressible

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

class felupe.LinearElastic(E, nu)

Isotropic linear-elastic material formulation.

Parameters:

• E (float) – Young’s modulus.

• nu (float) – Poisson ratio.

Notes

The stress-strain relation of the linear-elastic material formulation is given in Eq. (3)

(3)\[\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 small-strain tensor from Eq. (4).

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

Warning

This material formulation must not be used in analyses where large rotations, large displacements or large strains occur. In this case, consider using a Hyperelastic material formulation instead. LinearElasticLargeStrain is based on a compressible version of the Neo-Hookean material formulation and is safe to use for large rotations, large displacements and large strains.

Examples

>>> import felupe as fem
>>>
>>> umat = fem.LinearElastic(E=1, nu=0.3)
>>> ax = umat.plot()

See also

felupe.LinearElasticLargeStrain

Linear-elastic material formulation suitable for large-strain analyses based on the compressible Neo-Hookean material formulation.

felupe.Hyperelastic

A hyperelastic material definition with a given function for the strain energy density function per unit undeformed volume with automatic differentiation.

copy()

Return a deep-copy of the constitutive material.

gradient(x)

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

Parameters:

x (list of ndarray) – List with Deformation gradient \(\boldsymbol{F}\) (3x3) as first item.

Returns:

Stress tensor (3x3)

Return type:

ndarray

hessian(x=None, shape=(1, 1), dtype=None)

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 \(\boldsymbol{F}\) (3x3) as first item (default is None).

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

Returns:

elasticity tensor (3x3x3x3)

Return type:

ndarray

optimize(ux=None, ps=None, bx=None, incompressible=False, relative=False, **kwargs)

Optimize the material parameters by a least-squares fit on experimental stretch-stress data.

Parameters:

• ux (array of shape (2, ...) or None, optional) – Experimental uniaxial stretch and force-per-undeformed-area data (default is None).

• ps (array of shape (2, ...) or None, optional) – Experimental planar-shear stretch and force-per-undeformed-area data (default is None).

• bx (array of shape (2, ...) or None, optional) – Experimental biaxial stretch and force-per-undeformed-area data (default is None).

• incompressible (bool, optional) – A flag to enforce incompressible deformations (default is False).

• relative (bool, optional) – A flag to optimize relative instead of absolute residuals, i.e. (predicted - observed) / observed instead of predicted - observed (default is False).

• **kwargs (dict, optional) – Optional keyword arguments are passed to scipy.optimize.least_squares().

Returns:

• ConstitutiveMaterial – A copy of the constitutive material with the optimized material parameters.

• scipy.optimize.OptimizeResult – Represents the optimization result.

Notes

Warning

At least one load case, i.e. one of the arguments ux, ps or bx must not be None.

The vector of residuals is given in Eq. (3) in case of absolute residuals

(5)\[ \begin{align}\begin{aligned}\begin{split}\boldsymbol{r} &= \begin{bmatrix} \boldsymbol{r}_\text{ux} \\ \boldsymbol{r}_\text{ps} \\ \boldsymbol{r}_\text{bx} \end{bmatrix}\end{split}\\r_\text{ux}(\lambda_i) &= P_\text{ux}(\lambda_i) - P_\text{ux, observed}(\lambda_i)\\r_\text{ps}(\lambda_i) &= P_\text{ps}(\lambda_i) - P_\text{ps, observed}(\lambda_i)\\r_\text{bx}(\lambda_i) &= P_\text{bx}(\lambda_i) - P_\text{bx, observed}(\lambda_i)\end{aligned}\end{align} \]

and in Eq. (4) in case of relative residuals.

(6)\[ \begin{align}\begin{aligned}\begin{split}\boldsymbol{r} &= \begin{bmatrix} \boldsymbol{r}_\text{ux} \\ \boldsymbol{r}_\text{ps} \\ \boldsymbol{r}_\text{bx} \end{bmatrix}\end{split}\\r_\text{ux}(\lambda_i) &= \frac{ P_\text{ux}(\lambda_i) - P_\text{ux, observed}(\lambda_i)}{ P_\text{ux, observed}(\lambda_i) }\\r_\text{ps}(\lambda_i) &= \frac{ P_\text{ps}(\lambda_i) - P_\text{ps, observed}(\lambda_i)}{ P_\text{ps, observed}(\lambda_i) }\\r_\text{bx}(\lambda_i) &= \frac{ P_\text{bx}(\lambda_i) - P_\text{bx, observed}(\lambda_i)}{ P_\text{bx, observed}(\lambda_i) }\end{aligned}\end{align} \]

Examples

The Anssari-Benam Bucchi material model formulation is best-fitted on Treloar’s uniaxial and biaxial tension data [1]_.

>>> import numpy as np
>>> import felupe as fem
>>>
>>> λ, P = np.array(
...     [
...         [1.000, 0.00],
...         [1.240, 2.30],
...         [1.585, 4.16],
...         [2.180, 6.00],
...         [3.020, 8.80],
...         [4.030, 12.5],
...         [4.760, 16.2],
...         [5.750, 23.6],
...         [6.850, 38.5],
...         [7.250, 49.6],
...         [7.600, 64.4],
...     ]
... ).T * np.array([[1.0], [0.0980665]])
>>>
>>> umat = fem.Hyperelastic(fem.anssari_benam_bucchi)
>>> umat_new, res = umat.optimize(
...     ux=[λ, P], incompressible=True, relative=True
... )
>>>
>>> ux = np.linspace(λ.min(), λ.max(), num=50)
>>> ax = umat_new.plot(incompressible=True, ux=ux, bx=None, ps=None)

>>> ax.plot(λ, P, "C0x")

See also

scipy.optimize.least_squares

Solve a nonlinear least-squares problem with bounds on the variables.

References

[1]

L. R. G. Treloar, “Stress-strain data for vulcanised rubber under various types of deformation”, Transactions of the Faraday Society, vol. 40. Royal Society of Chemistry (RSC), p. 59, 1944. doi: 10.1039/tf9444000059. Data available at https://www.uni-due.de/mathematik/ag_neff/neff_hencky.

plot(incompressible=False, **kwargs)

Return a plot with normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

matplotlib.axes.Axes

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

screenshot(filename='umat.png', incompressible=False, **kwargs)

Save a screenshot with normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• filename (str, optional) – The filename of the screenshot (default is “umat.png”).

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

matplotlib.axes.Axes

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

view(incompressible=False, **kwargs)

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

felupe.ViewMaterial or felupe.ViewMaterialIncompressible

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

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

3D linear-elastic material formulation to be used in MaterialStrain.

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} \]

Examples

>>> import felupe as fem
>>>
>>> umat = fem.MaterialStrain(material=fem.linear_elastic, λ=2.0, μ=1.0)
>>> ax = umat.plot()

See also

MaterialStrain

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

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

Linear-elastic material formulation suitable for large-strain analyses based on the compressible Neo-Hookean material formulation.

Parameters:

• E (float) – Young’s modulus.

• nu (float) – Poisson ratio.

See also

felupe.NeoHookeCompressible

Compressible isotropic hyperelastic Neo-Hooke material formulation.

Examples

>>> import felupe as fem
>>>
>>> umat = fem.LinearElasticLargeStrain(E=1.0, nu=0.3)
>>> ax = umat.plot()

copy()

Return a deep-copy of the constitutive material.

function(x)

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

Returns:

Stress tensor (3x3)

Return type:

ndarray

gradient(x)

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

Returns:

Stress tensor (3x3)

Return type:

ndarray

hessian(x)

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.

Returns:

elasticity tensor (3x3x3x3)

Return type:

ndarray

optimize(ux=None, ps=None, bx=None, incompressible=False, relative=False, **kwargs)

Optimize the material parameters by a least-squares fit on experimental stretch-stress data.

Parameters:

• ux (array of shape (2, ...) or None, optional) – Experimental uniaxial stretch and force-per-undeformed-area data (default is None).

• ps (array of shape (2, ...) or None, optional) – Experimental planar-shear stretch and force-per-undeformed-area data (default is None).

• bx (array of shape (2, ...) or None, optional) – Experimental biaxial stretch and force-per-undeformed-area data (default is None).

• incompressible (bool, optional) – A flag to enforce incompressible deformations (default is False).

• relative (bool, optional) – A flag to optimize relative instead of absolute residuals, i.e. (predicted - observed) / observed instead of predicted - observed (default is False).

• **kwargs (dict, optional) – Optional keyword arguments are passed to scipy.optimize.least_squares().

Returns:

• ConstitutiveMaterial – A copy of the constitutive material with the optimized material parameters.

• scipy.optimize.OptimizeResult – Represents the optimization result.

Notes

Warning

At least one load case, i.e. one of the arguments ux, ps or bx must not be None.

The vector of residuals is given in Eq. (3) in case of absolute residuals

(7)\[ \begin{align}\begin{aligned}\begin{split}\boldsymbol{r} &= \begin{bmatrix} \boldsymbol{r}_\text{ux} \\ \boldsymbol{r}_\text{ps} \\ \boldsymbol{r}_\text{bx} \end{bmatrix}\end{split}\\r_\text{ux}(\lambda_i) &= P_\text{ux}(\lambda_i) - P_\text{ux, observed}(\lambda_i)\\r_\text{ps}(\lambda_i) &= P_\text{ps}(\lambda_i) - P_\text{ps, observed}(\lambda_i)\\r_\text{bx}(\lambda_i) &= P_\text{bx}(\lambda_i) - P_\text{bx, observed}(\lambda_i)\end{aligned}\end{align} \]

and in Eq. (4) in case of relative residuals.

(8)\[ \begin{align}\begin{aligned}\begin{split}\boldsymbol{r} &= \begin{bmatrix} \boldsymbol{r}_\text{ux} \\ \boldsymbol{r}_\text{ps} \\ \boldsymbol{r}_\text{bx} \end{bmatrix}\end{split}\\r_\text{ux}(\lambda_i) &= \frac{ P_\text{ux}(\lambda_i) - P_\text{ux, observed}(\lambda_i)}{ P_\text{ux, observed}(\lambda_i) }\\r_\text{ps}(\lambda_i) &= \frac{ P_\text{ps}(\lambda_i) - P_\text{ps, observed}(\lambda_i)}{ P_\text{ps, observed}(\lambda_i) }\\r_\text{bx}(\lambda_i) &= \frac{ P_\text{bx}(\lambda_i) - P_\text{bx, observed}(\lambda_i)}{ P_\text{bx, observed}(\lambda_i) }\end{aligned}\end{align} \]

Examples

The Anssari-Benam Bucchi material model formulation is best-fitted on Treloar’s uniaxial and biaxial tension data [1]_.

>>> import numpy as np
>>> import felupe as fem
>>>
>>> λ, P = np.array(
...     [
...         [1.000, 0.00],
...         [1.240, 2.30],
...         [1.585, 4.16],
...         [2.180, 6.00],
...         [3.020, 8.80],
...         [4.030, 12.5],
...         [4.760, 16.2],
...         [5.750, 23.6],
...         [6.850, 38.5],
...         [7.250, 49.6],
...         [7.600, 64.4],
...     ]
... ).T * np.array([[1.0], [0.0980665]])
>>>
>>> umat = fem.Hyperelastic(fem.anssari_benam_bucchi)
>>> umat_new, res = umat.optimize(
...     ux=[λ, P], incompressible=True, relative=True
... )
>>>
>>> ux = np.linspace(λ.min(), λ.max(), num=50)
>>> ax = umat_new.plot(incompressible=True, ux=ux, bx=None, ps=None)

>>> ax.plot(λ, P, "C0x")

See also

scipy.optimize.least_squares

Solve a nonlinear least-squares problem with bounds on the variables.

References

[1]

L. R. G. Treloar, “Stress-strain data for vulcanised rubber under various types of deformation”, Transactions of the Faraday Society, vol. 40. Royal Society of Chemistry (RSC), p. 59, 1944. doi: 10.1039/tf9444000059. Data available at https://www.uni-due.de/mathematik/ag_neff/neff_hencky.

plot(incompressible=False, **kwargs)

Return a plot with normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

matplotlib.axes.Axes

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

screenshot(filename='umat.png', incompressible=False, **kwargs)

Save a screenshot with normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• filename (str, optional) – The filename of the screenshot (default is “umat.png”).

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

matplotlib.axes.Axes

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

view(incompressible=False, **kwargs)

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

felupe.ViewMaterial or felupe.ViewMaterialIncompressible

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

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

Isotropic linear-elastic material formulation.

Parameters:

• E (float) – Young’s modulus.

• nu (float) – Poisson ratio.

Notes

\[ \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)\]

Examples

>>> import felupe as fem
>>>
>>> umat = fem.constitution.LinearElasticTensorNotation(E=1, nu=0.3)
>>> ax = umat.plot()

copy()

Return a deep-copy of the constitutive material.

gradient(x)

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

Parameters:

x (list of ndarray) – List with Deformation gradient \(\boldsymbol{F}\) (3x3) as first item.

Returns:

Stress tensor (3x3)

Return type:

ndarray

hessian(x=None, shape=(1, 1), dtype=None)

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

Parameters:

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

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

• dtype (data-type or None, optional) – Data-type of the returned array (default is None).

Returns:

elasticity tensor (3x3x3x3)

Return type:

ndarray

optimize(ux=None, ps=None, bx=None, incompressible=False, relative=False, **kwargs)

Optimize the material parameters by a least-squares fit on experimental stretch-stress data.

Parameters:

• ux (array of shape (2, ...) or None, optional) – Experimental uniaxial stretch and force-per-undeformed-area data (default is None).

• ps (array of shape (2, ...) or None, optional) – Experimental planar-shear stretch and force-per-undeformed-area data (default is None).

• bx (array of shape (2, ...) or None, optional) – Experimental biaxial stretch and force-per-undeformed-area data (default is None).

• incompressible (bool, optional) – A flag to enforce incompressible deformations (default is False).

• relative (bool, optional) – A flag to optimize relative instead of absolute residuals, i.e. (predicted - observed) / observed instead of predicted - observed (default is False).

• **kwargs (dict, optional) – Optional keyword arguments are passed to scipy.optimize.least_squares().

Returns:

• ConstitutiveMaterial – A copy of the constitutive material with the optimized material parameters.

• scipy.optimize.OptimizeResult – Represents the optimization result.

Notes

Warning

At least one load case, i.e. one of the arguments ux, ps or bx must not be None.

The vector of residuals is given in Eq. (3) in case of absolute residuals

(9)\[ \begin{align}\begin{aligned}\begin{split}\boldsymbol{r} &= \begin{bmatrix} \boldsymbol{r}_\text{ux} \\ \boldsymbol{r}_\text{ps} \\ \boldsymbol{r}_\text{bx} \end{bmatrix}\end{split}\\r_\text{ux}(\lambda_i) &= P_\text{ux}(\lambda_i) - P_\text{ux, observed}(\lambda_i)\\r_\text{ps}(\lambda_i) &= P_\text{ps}(\lambda_i) - P_\text{ps, observed}(\lambda_i)\\r_\text{bx}(\lambda_i) &= P_\text{bx}(\lambda_i) - P_\text{bx, observed}(\lambda_i)\end{aligned}\end{align} \]

and in Eq. (4) in case of relative residuals.

(10)\[ \begin{align}\begin{aligned}\begin{split}\boldsymbol{r} &= \begin{bmatrix} \boldsymbol{r}_\text{ux} \\ \boldsymbol{r}_\text{ps} \\ \boldsymbol{r}_\text{bx} \end{bmatrix}\end{split}\\r_\text{ux}(\lambda_i) &= \frac{ P_\text{ux}(\lambda_i) - P_\text{ux, observed}(\lambda_i)}{ P_\text{ux, observed}(\lambda_i) }\\r_\text{ps}(\lambda_i) &= \frac{ P_\text{ps}(\lambda_i) - P_\text{ps, observed}(\lambda_i)}{ P_\text{ps, observed}(\lambda_i) }\\r_\text{bx}(\lambda_i) &= \frac{ P_\text{bx}(\lambda_i) - P_\text{bx, observed}(\lambda_i)}{ P_\text{bx, observed}(\lambda_i) }\end{aligned}\end{align} \]

Examples

The Anssari-Benam Bucchi material model formulation is best-fitted on Treloar’s uniaxial and biaxial tension data [1]_.

>>> import numpy as np
>>> import felupe as fem
>>>
>>> λ, P = np.array(
...     [
...         [1.000, 0.00],
...         [1.240, 2.30],
...         [1.585, 4.16],
...         [2.180, 6.00],
...         [3.020, 8.80],
...         [4.030, 12.5],
...         [4.760, 16.2],
...         [5.750, 23.6],
...         [6.850, 38.5],
...         [7.250, 49.6],
...         [7.600, 64.4],
...     ]
... ).T * np.array([[1.0], [0.0980665]])
>>>
>>> umat = fem.Hyperelastic(fem.anssari_benam_bucchi)
>>> umat_new, res = umat.optimize(
...     ux=[λ, P], incompressible=True, relative=True
... )
>>>
>>> ux = np.linspace(λ.min(), λ.max(), num=50)
>>> ax = umat_new.plot(incompressible=True, ux=ux, bx=None, ps=None)

>>> ax.plot(λ, P, "C0x")

See also

scipy.optimize.least_squares

Solve a nonlinear least-squares problem with bounds on the variables.

References

[1]

L. R. G. Treloar, “Stress-strain data for vulcanised rubber under various types of deformation”, Transactions of the Faraday Society, vol. 40. Royal Society of Chemistry (RSC), p. 59, 1944. doi: 10.1039/tf9444000059. Data available at https://www.uni-due.de/mathematik/ag_neff/neff_hencky.

plot(incompressible=False, **kwargs)

Return a plot with normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

matplotlib.axes.Axes

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

screenshot(filename='umat.png', incompressible=False, **kwargs)

Save a screenshot with normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• filename (str, optional) – The filename of the screenshot (default is “umat.png”).

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

matplotlib.axes.Axes

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

view(incompressible=False, **kwargs)

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

felupe.ViewMaterial or felupe.ViewMaterialIncompressible

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

class felupe.constitution.LinearElasticPlaneStrain(E, nu)

Plane-strain isotropic linear-elastic material formulation.

Parameters:

• E (float) – Young’s modulus.

• nu (float) – Poisson ratio.

Notes

Warning

This class must not be used with FieldPlaneStrain but with Field instead!

gradient(x)

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

Parameters:

x (list of ndarray) – List with In-plane components (2x2) of the Deformation gradient \(\boldsymbol{F}\) as first item.

Returns:

In-plane components of stress tensor (2x2)

Return type:

ndarray

hessian(x)

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

Parameters:

x (list of ndarray) – List with In-plane components (2x2) of the Deformation gradient \(\boldsymbol{F}\) as first item.

Returns:

In-plane components of elasticity tensor (2x2x2x2)

Return type:

ndarray

strain(x)

Evaluate the strain tensor from the deformation gradient.

Parameters:

x (list of ndarray) – List with In-plane components (2x2) of the Deformation gradient \(\boldsymbol{F}\) as first item.

Returns:

e – Strain tensor (3x3)

Return type:

ndarray

stress(x)

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

Parameters:

x (list of ndarray) – List with In-plane components (2x2) of the Deformation gradient \(\boldsymbol{F}\) as first item.

Returns:

Stress tensor (3x3)

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)

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

Parameters:

x (list of ndarray) – List with In-plane components (2x2) of the Deformation gradient \(\boldsymbol{F}\) as first item.

Returns:

In-plane components of stress tensor (2x2)

Return type:

ndarray

hessian(x=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 \(\boldsymbol{F}\) as first item (default is None)-

• shape (tuple of 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)

Evaluate the strain tensor from the deformation gradient.

Parameters:

x (list of ndarray) – List with In-plane components (2x2) of the Deformation gradient \(\boldsymbol{F}\) as first item.

Returns:

e – Strain tensor (3x3)

Return type:

ndarray

stress(x)

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

Parameters:

x (list of ndarray) – List with In-plane components (2x2) of the Deformation gradient \(\boldsymbol{F}\) as first item.

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).

Parameters:

• E (float) – Young’s modulus.

• nu (float) – Poisson ratio.

• sy (float) – Initial yield stress.

• K (float) – Isotropic hardening modulus.

See also

MaterialStrain

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

linear_elastic_plastic_isotropic_hardening

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

copy()

Return a deep-copy of the constitutive material.

extract(x)

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

gradient(x)

hessian(x)

optimize(ux=None, ps=None, bx=None, incompressible=False, relative=False, **kwargs)

Optimize the material parameters by a least-squares fit on experimental stretch-stress data.

Parameters:

• ux (array of shape (2, ...) or None, optional) – Experimental uniaxial stretch and force-per-undeformed-area data (default is None).

• ps (array of shape (2, ...) or None, optional) – Experimental planar-shear stretch and force-per-undeformed-area data (default is None).

• bx (array of shape (2, ...) or None, optional) – Experimental biaxial stretch and force-per-undeformed-area data (default is None).

• incompressible (bool, optional) – A flag to enforce incompressible deformations (default is False).

• relative (bool, optional) – A flag to optimize relative instead of absolute residuals, i.e. (predicted - observed) / observed instead of predicted - observed (default is False).

• **kwargs (dict, optional) – Optional keyword arguments are passed to scipy.optimize.least_squares().

Returns:

• ConstitutiveMaterial – A copy of the constitutive material with the optimized material parameters.

• scipy.optimize.OptimizeResult – Represents the optimization result.

Notes

Warning

At least one load case, i.e. one of the arguments ux, ps or bx must not be None.

The vector of residuals is given in Eq. (3) in case of absolute residuals

(11)\[ \begin{align}\begin{aligned}\begin{split}\boldsymbol{r} &= \begin{bmatrix} \boldsymbol{r}_\text{ux} \\ \boldsymbol{r}_\text{ps} \\ \boldsymbol{r}_\text{bx} \end{bmatrix}\end{split}\\r_\text{ux}(\lambda_i) &= P_\text{ux}(\lambda_i) - P_\text{ux, observed}(\lambda_i)\\r_\text{ps}(\lambda_i) &= P_\text{ps}(\lambda_i) - P_\text{ps, observed}(\lambda_i)\\r_\text{bx}(\lambda_i) &= P_\text{bx}(\lambda_i) - P_\text{bx, observed}(\lambda_i)\end{aligned}\end{align} \]

and in Eq. (4) in case of relative residuals.

(12)\[ \begin{align}\begin{aligned}\begin{split}\boldsymbol{r} &= \begin{bmatrix} \boldsymbol{r}_\text{ux} \\ \boldsymbol{r}_\text{ps} \\ \boldsymbol{r}_\text{bx} \end{bmatrix}\end{split}\\r_\text{ux}(\lambda_i) &= \frac{ P_\text{ux}(\lambda_i) - P_\text{ux, observed}(\lambda_i)}{ P_\text{ux, observed}(\lambda_i) }\\r_\text{ps}(\lambda_i) &= \frac{ P_\text{ps}(\lambda_i) - P_\text{ps, observed}(\lambda_i)}{ P_\text{ps, observed}(\lambda_i) }\\r_\text{bx}(\lambda_i) &= \frac{ P_\text{bx}(\lambda_i) - P_\text{bx, observed}(\lambda_i)}{ P_\text{bx, observed}(\lambda_i) }\end{aligned}\end{align} \]

Examples

The Anssari-Benam Bucchi material model formulation is best-fitted on Treloar’s uniaxial and biaxial tension data [1]_.

>>> import numpy as np
>>> import felupe as fem
>>>
>>> λ, P = np.array(
...     [
...         [1.000, 0.00],
...         [1.240, 2.30],
...         [1.585, 4.16],
...         [2.180, 6.00],
...         [3.020, 8.80],
...         [4.030, 12.5],
...         [4.760, 16.2],
...         [5.750, 23.6],
...         [6.850, 38.5],
...         [7.250, 49.6],
...         [7.600, 64.4],
...     ]
... ).T * np.array([[1.0], [0.0980665]])
>>>
>>> umat = fem.Hyperelastic(fem.anssari_benam_bucchi)
>>> umat_new, res = umat.optimize(
...     ux=[λ, P], incompressible=True, relative=True
... )
>>>
>>> ux = np.linspace(λ.min(), λ.max(), num=50)
>>> ax = umat_new.plot(incompressible=True, ux=ux, bx=None, ps=None)

>>> ax.plot(λ, P, "C0x")

See also

scipy.optimize.least_squares

Solve a nonlinear least-squares problem with bounds on the variables.

References

[1]

L. R. G. Treloar, “Stress-strain data for vulcanised rubber under various types of deformation”, Transactions of the Faraday Society, vol. 40. Royal Society of Chemistry (RSC), p. 59, 1944. doi: 10.1039/tf9444000059. Data available at https://www.uni-due.de/mathematik/ag_neff/neff_hencky.

plot(incompressible=False, **kwargs)

Return a plot with normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

matplotlib.axes.Axes

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

screenshot(filename='umat.png', incompressible=False, **kwargs)

Save a screenshot with normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• filename (str, optional) – The filename of the screenshot (default is “umat.png”).

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

matplotlib.axes.Axes

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

view(incompressible=False, **kwargs)

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

felupe.ViewMaterial or felupe.ViewMaterialIncompressible

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

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

Linear-elastic-plastic material formulation with linear isotropic hardening (return mapping algorithm) to be used in MaterialStrain.

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]\]

Examples

>>> import felupe as fem
>>>
>>> umat = fem.MaterialStrain(
...     material=fem.linear_elastic_plastic_isotropic_hardening,
...     λ=2.0,
...     μ=1.0,
...     σy=0.05,
...     K=0.1,
...     dim=3,
...     statevars=(1, (3, 3)),
... )
>>> ux = fem.math.linsteps([1, 1.05, 0.95, 1.05], num=[10, 20, 20])
>>> ax = umat.plot(ux=ux, bx=None, ps=None)

See also

MaterialStrain

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

class felupe.LinearElasticOrthotropic(E, nu, G)

Orthotropic linear-elastic material formulation.

Parameters:

• E (float) – Young’s modulus (E1, E2, E3).

• nu (float) – Poisson ratio (nu12, nu23, n31).

• G (float) – Shear modulus (G12, G23, G31).

Examples

>>> import felupe as fem
>>>
>>> umat = fem.LinearElasticOrthotropic(
...     E=[1, 1, 1], nu=[0.3, 0.3, 0.3], G=[0.4, 0.4, 0.4]
... )
>>> ax = umat.plot()

copy()

Return a deep-copy of the constitutive material.

gradient(x)

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

Parameters:

x (list of ndarray) – List with Deformation gradient \(\boldsymbol{F}\) (3x3) as first item.

Returns:

Stress tensor

Return type:

ndarray of shape (3, 3, …)

hessian(x=None, shape=(1, 1), dtype=None)

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 \(\boldsymbol{F}\) (3x3) as first item (default is None).

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

Returns:

elasticity tensor

Return type:

ndarray of shape (3, 3, 3, 3, …)

optimize(ux=None, ps=None, bx=None, incompressible=False, relative=False, **kwargs)

Optimize the material parameters by a least-squares fit on experimental stretch-stress data.

Parameters:

• ux (array of shape (2, ...) or None, optional) – Experimental uniaxial stretch and force-per-undeformed-area data (default is None).

• ps (array of shape (2, ...) or None, optional) – Experimental planar-shear stretch and force-per-undeformed-area data (default is None).

• bx (array of shape (2, ...) or None, optional) – Experimental biaxial stretch and force-per-undeformed-area data (default is None).

• incompressible (bool, optional) – A flag to enforce incompressible deformations (default is False).

• relative (bool, optional) – A flag to optimize relative instead of absolute residuals, i.e. (predicted - observed) / observed instead of predicted - observed (default is False).

• **kwargs (dict, optional) – Optional keyword arguments are passed to scipy.optimize.least_squares().

Returns:

• ConstitutiveMaterial – A copy of the constitutive material with the optimized material parameters.

• scipy.optimize.OptimizeResult – Represents the optimization result.

Notes

Warning

At least one load case, i.e. one of the arguments ux, ps or bx must not be None.

The vector of residuals is given in Eq. (3) in case of absolute residuals

(13)\[ \begin{align}\begin{aligned}\begin{split}\boldsymbol{r} &= \begin{bmatrix} \boldsymbol{r}_\text{ux} \\ \boldsymbol{r}_\text{ps} \\ \boldsymbol{r}_\text{bx} \end{bmatrix}\end{split}\\r_\text{ux}(\lambda_i) &= P_\text{ux}(\lambda_i) - P_\text{ux, observed}(\lambda_i)\\r_\text{ps}(\lambda_i) &= P_\text{ps}(\lambda_i) - P_\text{ps, observed}(\lambda_i)\\r_\text{bx}(\lambda_i) &= P_\text{bx}(\lambda_i) - P_\text{bx, observed}(\lambda_i)\end{aligned}\end{align} \]

and in Eq. (4) in case of relative residuals.

(14)\[ \begin{align}\begin{aligned}\begin{split}\boldsymbol{r} &= \begin{bmatrix} \boldsymbol{r}_\text{ux} \\ \boldsymbol{r}_\text{ps} \\ \boldsymbol{r}_\text{bx} \end{bmatrix}\end{split}\\r_\text{ux}(\lambda_i) &= \frac{ P_\text{ux}(\lambda_i) - P_\text{ux, observed}(\lambda_i)}{ P_\text{ux, observed}(\lambda_i) }\\r_\text{ps}(\lambda_i) &= \frac{ P_\text{ps}(\lambda_i) - P_\text{ps, observed}(\lambda_i)}{ P_\text{ps, observed}(\lambda_i) }\\r_\text{bx}(\lambda_i) &= \frac{ P_\text{bx}(\lambda_i) - P_\text{bx, observed}(\lambda_i)}{ P_\text{bx, observed}(\lambda_i) }\end{aligned}\end{align} \]

Examples

The Anssari-Benam Bucchi material model formulation is best-fitted on Treloar’s uniaxial and biaxial tension data [1]_.

>>> import numpy as np
>>> import felupe as fem
>>>
>>> λ, P = np.array(
...     [
...         [1.000, 0.00],
...         [1.240, 2.30],
...         [1.585, 4.16],
...         [2.180, 6.00],
...         [3.020, 8.80],
...         [4.030, 12.5],
...         [4.760, 16.2],
...         [5.750, 23.6],
...         [6.850, 38.5],
...         [7.250, 49.6],
...         [7.600, 64.4],
...     ]
... ).T * np.array([[1.0], [0.0980665]])
>>>
>>> umat = fem.Hyperelastic(fem.anssari_benam_bucchi)
>>> umat_new, res = umat.optimize(
...     ux=[λ, P], incompressible=True, relative=True
... )
>>>
>>> ux = np.linspace(λ.min(), λ.max(), num=50)
>>> ax = umat_new.plot(incompressible=True, ux=ux, bx=None, ps=None)

>>> ax.plot(λ, P, "C0x")

See also

scipy.optimize.least_squares

Solve a nonlinear least-squares problem with bounds on the variables.

References

[1]

L. R. G. Treloar, “Stress-strain data for vulcanised rubber under various types of deformation”, Transactions of the Faraday Society, vol. 40. Royal Society of Chemistry (RSC), p. 59, 1944. doi: 10.1039/tf9444000059. Data available at https://www.uni-due.de/mathematik/ag_neff/neff_hencky.

plot(incompressible=False, **kwargs)

Return a plot with normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

matplotlib.axes.Axes

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

screenshot(filename='umat.png', incompressible=False, **kwargs)

Save a screenshot with normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• filename (str, optional) – The filename of the screenshot (default is “umat.png”).

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

matplotlib.axes.Axes

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

view(incompressible=False, **kwargs)

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

felupe.ViewMaterial or felupe.ViewMaterialIncompressible

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

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)

See also

linear_elastic

3D linear-elastic material formulation

linear_elastic_plastic_isotropic_hardening

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

LinearElasticPlasticIsotropicHardening

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

copy()

Return a deep-copy of the constitutive material.

extract(x)

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

gradient(x)

hessian(x)

optimize(ux=None, ps=None, bx=None, incompressible=False, relative=False, **kwargs)

Optimize the material parameters by a least-squares fit on experimental stretch-stress data.

Parameters:

• ux (array of shape (2, ...) or None, optional) – Experimental uniaxial stretch and force-per-undeformed-area data (default is None).

• ps (array of shape (2, ...) or None, optional) – Experimental planar-shear stretch and force-per-undeformed-area data (default is None).

• bx (array of shape (2, ...) or None, optional) – Experimental biaxial stretch and force-per-undeformed-area data (default is None).

• incompressible (bool, optional) – A flag to enforce incompressible deformations (default is False).

• relative (bool, optional) – A flag to optimize relative instead of absolute residuals, i.e. (predicted - observed) / observed instead of predicted - observed (default is False).

• **kwargs (dict, optional) – Optional keyword arguments are passed to scipy.optimize.least_squares().

Returns:

• ConstitutiveMaterial – A copy of the constitutive material with the optimized material parameters.

• scipy.optimize.OptimizeResult – Represents the optimization result.

Notes

Warning

At least one load case, i.e. one of the arguments ux, ps or bx must not be None.

The vector of residuals is given in Eq. (3) in case of absolute residuals

(15)\[ \begin{align}\begin{aligned}\begin{split}\boldsymbol{r} &= \begin{bmatrix} \boldsymbol{r}_\text{ux} \\ \boldsymbol{r}_\text{ps} \\ \boldsymbol{r}_\text{bx} \end{bmatrix}\end{split}\\r_\text{ux}(\lambda_i) &= P_\text{ux}(\lambda_i) - P_\text{ux, observed}(\lambda_i)\\r_\text{ps}(\lambda_i) &= P_\text{ps}(\lambda_i) - P_\text{ps, observed}(\lambda_i)\\r_\text{bx}(\lambda_i) &= P_\text{bx}(\lambda_i) - P_\text{bx, observed}(\lambda_i)\end{aligned}\end{align} \]

and in Eq. (4) in case of relative residuals.

(16)\[ \begin{align}\begin{aligned}\begin{split}\boldsymbol{r} &= \begin{bmatrix} \boldsymbol{r}_\text{ux} \\ \boldsymbol{r}_\text{ps} \\ \boldsymbol{r}_\text{bx} \end{bmatrix}\end{split}\\r_\text{ux}(\lambda_i) &= \frac{ P_\text{ux}(\lambda_i) - P_\text{ux, observed}(\lambda_i)}{ P_\text{ux, observed}(\lambda_i) }\\r_\text{ps}(\lambda_i) &= \frac{ P_\text{ps}(\lambda_i) - P_\text{ps, observed}(\lambda_i)}{ P_\text{ps, observed}(\lambda_i) }\\r_\text{bx}(\lambda_i) &= \frac{ P_\text{bx}(\lambda_i) - P_\text{bx, observed}(\lambda_i)}{ P_\text{bx, observed}(\lambda_i) }\end{aligned}\end{align} \]

Examples

The Anssari-Benam Bucchi material model formulation is best-fitted on Treloar’s uniaxial and biaxial tension data [1]_.

>>> import numpy as np
>>> import felupe as fem
>>>
>>> λ, P = np.array(
...     [
...         [1.000, 0.00],
...         [1.240, 2.30],
...         [1.585, 4.16],
...         [2.180, 6.00],
...         [3.020, 8.80],
...         [4.030, 12.5],
...         [4.760, 16.2],
...         [5.750, 23.6],
...         [6.850, 38.5],
...         [7.250, 49.6],
...         [7.600, 64.4],
...     ]
... ).T * np.array([[1.0], [0.0980665]])
>>>
>>> umat = fem.Hyperelastic(fem.anssari_benam_bucchi)
>>> umat_new, res = umat.optimize(
...     ux=[λ, P], incompressible=True, relative=True
... )
>>>
>>> ux = np.linspace(λ.min(), λ.max(), num=50)
>>> ax = umat_new.plot(incompressible=True, ux=ux, bx=None, ps=None)

>>> ax.plot(λ, P, "C0x")

See also

scipy.optimize.least_squares

Solve a nonlinear least-squares problem with bounds on the variables.

References

[1]

L. R. G. Treloar, “Stress-strain data for vulcanised rubber under various types of deformation”, Transactions of the Faraday Society, vol. 40. Royal Society of Chemistry (RSC), p. 59, 1944. doi: 10.1039/tf9444000059. Data available at https://www.uni-due.de/mathematik/ag_neff/neff_hencky.

plot(incompressible=False, **kwargs)

Return a plot with normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

matplotlib.axes.Axes

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

screenshot(filename='umat.png', incompressible=False, **kwargs)

Save a screenshot with normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• filename (str, optional) – The filename of the screenshot (default is “umat.png”).

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

matplotlib.axes.Axes

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

view(incompressible=False, **kwargs)

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

felupe.ViewMaterial or felupe.ViewMaterialIncompressible

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

class felupe.NearlyIncompressible(material, bulk, parallel=False, dUdJ=<function NearlyIncompressible.<lambda>>, d2UdJdJ=<function NearlyIncompressible.<lambda>>)

A nearly-incompressible material formulation to augment the distortional part of the strain energy function by a volumetric part and a constraint equation.

Notes

The total potential energy of internal forces is given in Eq. (5).

(17)\[\Pi_{int}(\boldsymbol{F}, p, \bar{J}) = \int_V \hat{\psi}(\boldsymbol{F})\ dV + \int_V U(\bar{J})\ dV + \int_V p (J - \bar{J})\ dV\]

The volumetric part of the strain energy density function is denoted in Eq. (9) along with its first and second derivatives.

(18)\[ \begin{align}\begin{aligned}\bar{U} &= \frac{K}{2} \left( \bar{J} - 1 \right)^2\\\bar{U}' &= K \left( \bar{J} - 1 \right)\\\bar{U}'' &= K\end{aligned}\end{align} \]

Parameters:

• material (ConstitutiveMaterial) – A hyperelastic material definition for the distortional part of the strain energy density function \(\hat{\psi}(\boldsymbol{F})\) with methods for the gradient \(\partial_\boldsymbol{F}(\hat{\psi})\) and the hessian \(\partial_\boldsymbol{F}[\partial_\boldsymbol{F}(\hat{\psi})]\) w.r.t the deformation gradient tensor \(\boldsymbol{F}\).

• bulk (float) – The bulk modulus \(K\) for the volumetric part of the strain energy function.

• parallel (bool, optional) – A flag to invoke parallel (threaded) math operations (default is False).

• dUdJ (callable, optional) – A function which evaluates the derivative of the volumetric part of the strain energy function \(\bar{U}'\) w.r.t. the volume ratio \(\bar{J}\). Function signature must be lambda J, bulk: dUdJ. Default is \(\bar{U}' = K (\bar{J} - 1)\) or lambda J, bulk: bulk * (J - 1).

• d2UdJdJ (callable, optional) – A function which evaluates the second derivative of the volumetric part of the strain energy function \(\bar{U}''\) w.r.t. the volume ratio \(\bar{J}\). Function signature must be lambda J, bulk: d2UdJdJ. Default is \(\bar{U}'' = K\) or lambda J, bulk: bulk.

Examples

>>> import felupe as fem
>>>
>>> field = fem.FieldsMixed(fem.RegionHexahedron(fem.Cube(n=6)), n=3)
>>> boundaries, loadcase = fem.dof.uniaxial(field, clamped=True)
>>> umat = fem.NearlyIncompressible(fem.NeoHooke(mu=1), bulk=5000)
>>> solid = fem.SolidBody(umat, field)
>>> job = fem.Job(steps=[fem.Step(items=[solid], boundaries=boundaries)]).evaluate()

See also

ThreeFieldVariation

Hu-Washizu hydrostatic-volumetric selective three-field variation for nearly-incompressible material formulations.

copy()

Return a deep-copy of the constitutive material.

gradient(x, out=None)

Return a list with the gradient of the strain energy density function w.r.t. the fields displacements, pressure and volume ratio.

Parameters:

• x (list of ndarray) – List of extracted field values with the deformation gradient tensor \(\boldsymbol{F}\) as first, the pressure \(p\) as second and the volume ratio \(\bar{J}\) as third list item. Initial state variables are stored in the last (fourth) list item.

• out (ndarray or None, optional) – A location into which the result is stored (default is None).

Returns:

List of gradients w.r.t. the input variables \(\boldsymbol{F}\), \(p\) and \(\bar{J}\). The last item of the list contains the updated state variables.

Return type:

list of ndarrays

Notes

\[ \begin{align}\begin{aligned}\delta_\boldsymbol{u}(\Pi_{int}) &= \int_V \left( \frac{\partial \hat{\psi}}{\partial \boldsymbol{F}} + p\ J \boldsymbol{F}^{-T} \right) : \delta\boldsymbol{F}\ dV\\\delta_p(\Pi_{int}) &= \int_V \left( J - \bar{J} \right)\ \delta p\ dV\\\delta_\bar{J}(\Pi_{int}) &= \int_V \left( \bar{U}' - p \right)\ \delta \bar{J}\ dV\end{aligned}\end{align} \]

hessian(x, out=None)

Return a list with the hessian of the strain energy density function w.r.t. the fields displacements, pressure and volume ratio.

Parameters:

• x (list of ndarray) – List of extracted field values with the deformation gradient tensor \(\boldsymbol{F}\) as first, the pressure \(p\) as second and the volume ratio \(\bar{J}\) as third list item. Initial state variables are stored in the last (fourth) list item.

• out (ndarray or None, optional) – A location into which the result is stored (default is None).

Returns:

List of the hessian w.r.t. the input variables \(\boldsymbol{F}\), \(p\) and \(\bar{J}\). The upper-triangle items of the hessian are returned as the items of the list.

Return type:

list of ndarrays

Notes

\[ \begin{align}\begin{aligned}\Delta_\boldsymbol{u}\delta_\boldsymbol{u}(\Pi_{int}) &= \int_V \delta\boldsymbol{F} : \left[ \frac{\partial^2 \hat{\psi}} {\partial\boldsymbol{F}\ \partial\boldsymbol{F}} + p\ J \left( \boldsymbol{F}^{-T} \otimes \boldsymbol{F}^{-T} - \boldsymbol{F}^{-T} \overset{il}{\odot} \boldsymbol{F}^{-T} \right) \right] : \Delta\boldsymbol{F}\ dV\\\Delta_p\delta_\boldsymbol{u}(\Pi_{int}) &= \int_V \delta\boldsymbol{F} : J \boldsymbol{F}^{-T}\ \Delta p\ dV\\\Delta_\bar{J}\delta_\boldsymbol{u}(\Pi_{int}) &= \int_V \delta\boldsymbol{F} : \boldsymbol{0}\ \Delta \bar{J}\ dV\\\Delta_p\delta_p(\Pi_{int}) &= \int_V \delta p\ (0)\ \Delta p\ dV\\\Delta_p\delta_\bar{J}(\Pi_{int}) &= \int_V \delta \bar{J}\ (-1)\ \Delta p\ dV\\\Delta_\bar{J}\delta_\bar{J}(\Pi_{int}) &= \int_V \delta \bar{J}\ \bar{U}''\ \Delta \bar{J}\ dV\end{aligned}\end{align} \]

optimize(ux=None, ps=None, bx=None, incompressible=False, relative=False, **kwargs)

Optimize the material parameters by a least-squares fit on experimental stretch-stress data.

Parameters:

• ux (array of shape (2, ...) or None, optional) – Experimental uniaxial stretch and force-per-undeformed-area data (default is None).

• ps (array of shape (2, ...) or None, optional) – Experimental planar-shear stretch and force-per-undeformed-area data (default is None).

• bx (array of shape (2, ...) or None, optional) – Experimental biaxial stretch and force-per-undeformed-area data (default is None).

• incompressible (bool, optional) – A flag to enforce incompressible deformations (default is False).

• relative (bool, optional) – A flag to optimize relative instead of absolute residuals, i.e. (predicted - observed) / observed instead of predicted - observed (default is False).

• **kwargs (dict, optional) – Optional keyword arguments are passed to scipy.optimize.least_squares().

Returns:

• ConstitutiveMaterial – A copy of the constitutive material with the optimized material parameters.

• scipy.optimize.OptimizeResult – Represents the optimization result.

Notes

Warning

At least one load case, i.e. one of the arguments ux, ps or bx must not be None.

The vector of residuals is given in Eq. (3) in case of absolute residuals

(19)\[ \begin{align}\begin{aligned}\begin{split}\boldsymbol{r} &= \begin{bmatrix} \boldsymbol{r}_\text{ux} \\ \boldsymbol{r}_\text{ps} \\ \boldsymbol{r}_\text{bx} \end{bmatrix}\end{split}\\r_\text{ux}(\lambda_i) &= P_\text{ux}(\lambda_i) - P_\text{ux, observed}(\lambda_i)\\r_\text{ps}(\lambda_i) &= P_\text{ps}(\lambda_i) - P_\text{ps, observed}(\lambda_i)\\r_\text{bx}(\lambda_i) &= P_\text{bx}(\lambda_i) - P_\text{bx, observed}(\lambda_i)\end{aligned}\end{align} \]

and in Eq. (4) in case of relative residuals.

(20)\[ \begin{align}\begin{aligned}\begin{split}\boldsymbol{r} &= \begin{bmatrix} \boldsymbol{r}_\text{ux} \\ \boldsymbol{r}_\text{ps} \\ \boldsymbol{r}_\text{bx} \end{bmatrix}\end{split}\\r_\text{ux}(\lambda_i) &= \frac{ P_\text{ux}(\lambda_i) - P_\text{ux, observed}(\lambda_i)}{ P_\text{ux, observed}(\lambda_i) }\\r_\text{ps}(\lambda_i) &= \frac{ P_\text{ps}(\lambda_i) - P_\text{ps, observed}(\lambda_i)}{ P_\text{ps, observed}(\lambda_i) }\\r_\text{bx}(\lambda_i) &= \frac{ P_\text{bx}(\lambda_i) - P_\text{bx, observed}(\lambda_i)}{ P_\text{bx, observed}(\lambda_i) }\end{aligned}\end{align} \]

Examples

The Anssari-Benam Bucchi material model formulation is best-fitted on Treloar’s uniaxial and biaxial tension data [1]_.

>>> import numpy as np
>>> import felupe as fem
>>>
>>> λ, P = np.array(
...     [
...         [1.000, 0.00],
...         [1.240, 2.30],
...         [1.585, 4.16],
...         [2.180, 6.00],
...         [3.020, 8.80],
...         [4.030, 12.5],
...         [4.760, 16.2],
...         [5.750, 23.6],
...         [6.850, 38.5],
...         [7.250, 49.6],
...         [7.600, 64.4],
...     ]
... ).T * np.array([[1.0], [0.0980665]])
>>>
>>> umat = fem.Hyperelastic(fem.anssari_benam_bucchi)
>>> umat_new, res = umat.optimize(
...     ux=[λ, P], incompressible=True, relative=True
... )
>>>
>>> ux = np.linspace(λ.min(), λ.max(), num=50)
>>> ax = umat_new.plot(incompressible=True, ux=ux, bx=None, ps=None)

>>> ax.plot(λ, P, "C0x")

See also

scipy.optimize.least_squares

Solve a nonlinear least-squares problem with bounds on the variables.

References

[1]

L. R. G. Treloar, “Stress-strain data for vulcanised rubber under various types of deformation”, Transactions of the Faraday Society, vol. 40. Royal Society of Chemistry (RSC), p. 59, 1944. doi: 10.1039/tf9444000059. Data available at https://www.uni-due.de/mathematik/ag_neff/neff_hencky.

plot(incompressible=False, **kwargs)

Return a plot with normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

matplotlib.axes.Axes

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

screenshot(filename='umat.png', incompressible=False, **kwargs)

Save a screenshot with normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• filename (str, optional) – The filename of the screenshot (default is “umat.png”).

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

matplotlib.axes.Axes

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

view(incompressible=False, **kwargs)

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

felupe.ViewMaterial or felupe.ViewMaterialIncompressible

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

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

Nearly-incompressible isotropic hyperelastic Neo-Hookean 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.

Parameters:

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

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

Notes

Note

At least one of the two material parameters must not be None.

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} \]

Examples

>>> import felupe as fem
>>>
>>> umat = fem.NeoHooke(mu=1.0, bulk=2.0)
>>> ax = umat.plot()

copy()

Return a deep-copy of the constitutive material.

function(x)

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

gradient(x, out=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

• out (ndarray or None, optional) – A location into which the result is stored (default is None).

hessian(x, out=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

• out (ndarray or None, optional) – A location into which the result is stored (default is None).

optimize(ux=None, ps=None, bx=None, incompressible=False, relative=False, **kwargs)

Optimize the material parameters by a least-squares fit on experimental stretch-stress data.

Parameters:

• ux (array of shape (2, ...) or None, optional) – Experimental uniaxial stretch and force-per-undeformed-area data (default is None).

• ps (array of shape (2, ...) or None, optional) – Experimental planar-shear stretch and force-per-undeformed-area data (default is None).

• bx (array of shape (2, ...) or None, optional) – Experimental biaxial stretch and force-per-undeformed-area data (default is None).

• incompressible (bool, optional) – A flag to enforce incompressible deformations (default is False).

• relative (bool, optional) – A flag to optimize relative instead of absolute residuals, i.e. (predicted - observed) / observed instead of predicted - observed (default is False).

• **kwargs (dict, optional) – Optional keyword arguments are passed to scipy.optimize.least_squares().

Returns:

• ConstitutiveMaterial – A copy of the constitutive material with the optimized material parameters.

• scipy.optimize.OptimizeResult – Represents the optimization result.

Notes

Warning

At least one load case, i.e. one of the arguments ux, ps or bx must not be None.

The vector of residuals is given in Eq. (3) in case of absolute residuals

(21)\[ \begin{align}\begin{aligned}\begin{split}\boldsymbol{r} &= \begin{bmatrix} \boldsymbol{r}_\text{ux} \\ \boldsymbol{r}_\text{ps} \\ \boldsymbol{r}_\text{bx} \end{bmatrix}\end{split}\\r_\text{ux}(\lambda_i) &= P_\text{ux}(\lambda_i) - P_\text{ux, observed}(\lambda_i)\\r_\text{ps}(\lambda_i) &= P_\text{ps}(\lambda_i) - P_\text{ps, observed}(\lambda_i)\\r_\text{bx}(\lambda_i) &= P_\text{bx}(\lambda_i) - P_\text{bx, observed}(\lambda_i)\end{aligned}\end{align} \]

and in Eq. (4) in case of relative residuals.

(22)\[ \begin{align}\begin{aligned}\begin{split}\boldsymbol{r} &= \begin{bmatrix} \boldsymbol{r}_\text{ux} \\ \boldsymbol{r}_\text{ps} \\ \boldsymbol{r}_\text{bx} \end{bmatrix}\end{split}\\r_\text{ux}(\lambda_i) &= \frac{ P_\text{ux}(\lambda_i) - P_\text{ux, observed}(\lambda_i)}{ P_\text{ux, observed}(\lambda_i) }\\r_\text{ps}(\lambda_i) &= \frac{ P_\text{ps}(\lambda_i) - P_\text{ps, observed}(\lambda_i)}{ P_\text{ps, observed}(\lambda_i) }\\r_\text{bx}(\lambda_i) &= \frac{ P_\text{bx}(\lambda_i) - P_\text{bx, observed}(\lambda_i)}{ P_\text{bx, observed}(\lambda_i) }\end{aligned}\end{align} \]

Examples

The Anssari-Benam Bucchi material model formulation is best-fitted on Treloar’s uniaxial and biaxial tension data [1]_.

>>> import numpy as np
>>> import felupe as fem
>>>
>>> λ, P = np.array(
...     [
...         [1.000, 0.00],
...         [1.240, 2.30],
...         [1.585, 4.16],
...         [2.180, 6.00],
...         [3.020, 8.80],
...         [4.030, 12.5],
...         [4.760, 16.2],
...         [5.750, 23.6],
...         [6.850, 38.5],
...         [7.250, 49.6],
...         [7.600, 64.4],
...     ]
... ).T * np.array([[1.0], [0.0980665]])
>>>
>>> umat = fem.Hyperelastic(fem.anssari_benam_bucchi)
>>> umat_new, res = umat.optimize(
...     ux=[λ, P], incompressible=True, relative=True
... )
>>>
>>> ux = np.linspace(λ.min(), λ.max(), num=50)
>>> ax = umat_new.plot(incompressible=True, ux=ux, bx=None, ps=None)

>>> ax.plot(λ, P, "C0x")

See also

scipy.optimize.least_squares

Solve a nonlinear least-squares problem with bounds on the variables.

References

[1]

L. R. G. Treloar, “Stress-strain data for vulcanised rubber under various types of deformation”, Transactions of the Faraday Society, vol. 40. Royal Society of Chemistry (RSC), p. 59, 1944. doi: 10.1039/tf9444000059. Data available at https://www.uni-due.de/mathematik/ag_neff/neff_hencky.

plot(incompressible=False, **kwargs)

Return a plot with normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

matplotlib.axes.Axes

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

screenshot(filename='umat.png', incompressible=False, **kwargs)

Save a screenshot with normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• filename (str, optional) – The filename of the screenshot (default is “umat.png”).

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

matplotlib.axes.Axes

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

view(incompressible=False, **kwargs)

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

felupe.ViewMaterial or felupe.ViewMaterialIncompressible

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

class felupe.NeoHookeCompressible(mu=None, lmbda=None, parallel=False)

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

Parameters:

• mu (float or None, optional) – Shear modulus (second Lamé constant). Default is None.

• lmbda (float or None, optional) – First Lamé constant (default is None)

Notes

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

with

\[J = \text{det}(\boldsymbol{F})\]

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

\[ \begin{align}\begin{aligned}\boldsymbol{P} &= \frac{\partial \psi}{\partial \boldsymbol{F}}\\\boldsymbol{P} &= \mu \left( \boldsymbol{F} - \boldsymbol{F}^{-T} \right) + \lambda \ln(J) \boldsymbol{F}^{-T}\end{aligned}\end{align} \]

The hessian of the strain energy density function enables the corresponding elasticity tensor.

\[ \begin{align}\begin{aligned}\mathbb{A} &= \frac{\partial^2 \psi}{\partial \boldsymbol{F}\ \partial \boldsymbol{F}}\\\mathbb{A} &= \mu \boldsymbol{I} \overset{ik}{\otimes} \boldsymbol{I} + \left(\mu - \lambda \ln(J) \right) \boldsymbol{F}^{-T} \overset{il}{\otimes} \boldsymbol{F}^{-T} + \lambda \boldsymbol{F}^{-T} {\otimes} \boldsymbol{F}^{-T}\end{aligned}\end{align} \]

Examples

>>> import felupe as fem
>>>
>>> umat = fem.NeoHookeCompressible(mu=1.0, lmbda=2.0)
>>> ax = umat.plot()

copy()

Return a deep-copy of the constitutive material.

function(x)

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

gradient(x, out=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

• out (ndarray or None, optional) – A location into which the result is stored (default is None).

hessian(x, out=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

• out (ndarray or None, optional) – A location into which the result is stored (default is None).

optimize(ux=None, ps=None, bx=None, incompressible=False, relative=False, **kwargs)

Optimize the material parameters by a least-squares fit on experimental stretch-stress data.

Parameters:

• ux (array of shape (2, ...) or None, optional) – Experimental uniaxial stretch and force-per-undeformed-area data (default is None).

• ps (array of shape (2, ...) or None, optional) – Experimental planar-shear stretch and force-per-undeformed-area data (default is None).

• bx (array of shape (2, ...) or None, optional) – Experimental biaxial stretch and force-per-undeformed-area data (default is None).

• incompressible (bool, optional) – A flag to enforce incompressible deformations (default is False).

• relative (bool, optional) – A flag to optimize relative instead of absolute residuals, i.e. (predicted - observed) / observed instead of predicted - observed (default is False).

• **kwargs (dict, optional) – Optional keyword arguments are passed to scipy.optimize.least_squares().

Returns:

• ConstitutiveMaterial – A copy of the constitutive material with the optimized material parameters.

• scipy.optimize.OptimizeResult – Represents the optimization result.

Notes

Warning

At least one load case, i.e. one of the arguments ux, ps or bx must not be None.

The vector of residuals is given in Eq. (3) in case of absolute residuals

(23)\[ \begin{align}\begin{aligned}\begin{split}\boldsymbol{r} &= \begin{bmatrix} \boldsymbol{r}_\text{ux} \\ \boldsymbol{r}_\text{ps} \\ \boldsymbol{r}_\text{bx} \end{bmatrix}\end{split}\\r_\text{ux}(\lambda_i) &= P_\text{ux}(\lambda_i) - P_\text{ux, observed}(\lambda_i)\\r_\text{ps}(\lambda_i) &= P_\text{ps}(\lambda_i) - P_\text{ps, observed}(\lambda_i)\\r_\text{bx}(\lambda_i) &= P_\text{bx}(\lambda_i) - P_\text{bx, observed}(\lambda_i)\end{aligned}\end{align} \]

and in Eq. (4) in case of relative residuals.

(24)\[ \begin{align}\begin{aligned}\begin{split}\boldsymbol{r} &= \begin{bmatrix} \boldsymbol{r}_\text{ux} \\ \boldsymbol{r}_\text{ps} \\ \boldsymbol{r}_\text{bx} \end{bmatrix}\end{split}\\r_\text{ux}(\lambda_i) &= \frac{ P_\text{ux}(\lambda_i) - P_\text{ux, observed}(\lambda_i)}{ P_\text{ux, observed}(\lambda_i) }\\r_\text{ps}(\lambda_i) &= \frac{ P_\text{ps}(\lambda_i) - P_\text{ps, observed}(\lambda_i)}{ P_\text{ps, observed}(\lambda_i) }\\r_\text{bx}(\lambda_i) &= \frac{ P_\text{bx}(\lambda_i) - P_\text{bx, observed}(\lambda_i)}{ P_\text{bx, observed}(\lambda_i) }\end{aligned}\end{align} \]

Examples

The Anssari-Benam Bucchi material model formulation is best-fitted on Treloar’s uniaxial and biaxial tension data [1]_.

>>> import numpy as np
>>> import felupe as fem
>>>
>>> λ, P = np.array(
...     [
...         [1.000, 0.00],
...         [1.240, 2.30],
...         [1.585, 4.16],
...         [2.180, 6.00],
...         [3.020, 8.80],
...         [4.030, 12.5],
...         [4.760, 16.2],
...         [5.750, 23.6],
...         [6.850, 38.5],
...         [7.250, 49.6],
...         [7.600, 64.4],
...     ]
... ).T * np.array([[1.0], [0.0980665]])
>>>
>>> umat = fem.Hyperelastic(fem.anssari_benam_bucchi)
>>> umat_new, res = umat.optimize(
...     ux=[λ, P], incompressible=True, relative=True
... )
>>>
>>> ux = np.linspace(λ.min(), λ.max(), num=50)
>>> ax = umat_new.plot(incompressible=True, ux=ux, bx=None, ps=None)

>>> ax.plot(λ, P, "C0x")

See also

scipy.optimize.least_squares

Solve a nonlinear least-squares problem with bounds on the variables.

References

[1]

L. R. G. Treloar, “Stress-strain data for vulcanised rubber under various types of deformation”, Transactions of the Faraday Society, vol. 40. Royal Society of Chemistry (RSC), p. 59, 1944. doi: 10.1039/tf9444000059. Data available at https://www.uni-due.de/mathematik/ag_neff/neff_hencky.

plot(incompressible=False, **kwargs)

Return a plot with normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

matplotlib.axes.Axes

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

screenshot(filename='umat.png', incompressible=False, **kwargs)

Save a screenshot with normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• filename (str, optional) – The filename of the screenshot (default is “umat.png”).

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

matplotlib.axes.Axes

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

view(incompressible=False, **kwargs)

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

felupe.ViewMaterial or felupe.ViewMaterialIncompressible

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

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

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

Parameters:

• material (NeoHooke, Hyperelastic, Material or MaterialAD) – An isotropic hyperelastic (user) material definition.

• r (float) – Reciprocal value of the maximum relative amount of softening. i.e. r=3 means the shear modulus of the base material scales down from \(1\) (no softening) to \(1 - 1/3 = 2/3\) (maximum softening).

• m (float) – The initial Mullins softening modulus.

• beta (float) – Maximum deformation-dependent part of the Mullins softening modulus.

Notes

\[ \begin{align}\begin{aligned}\eta(\psi, \psi_\text{max}) &= 1 - \frac{1}{r} \text{erf} \left( \frac{\psi_\text{max} - \psi}{m + \beta~\psi_\text{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} \]

Examples

>>> import felupe as fem
>>>
>>> neo_hooke = fem.NeoHooke(mu=1.0)
>>> umat = fem.OgdenRoxburgh(material=neo_hooke, r=3.0, m=1.0, beta=0.0)
>>>
>>> ax = umat.plot(
...     ux=fem.math.linsteps([1, 1.5, 1, 2, 1, 2.5, 1], num=15),
...     ps=None,
...     bx=None,
...     incompressible=True,
... )

copy()

Return a deep-copy of the constitutive material.

gradient(x)

hessian(x)

optimize(ux=None, ps=None, bx=None, incompressible=False, relative=False, **kwargs)

Optimize the material parameters by a least-squares fit on experimental stretch-stress data.

Parameters:

• ux (array of shape (2, ...) or None, optional) – Experimental uniaxial stretch and force-per-undeformed-area data (default is None).

• ps (array of shape (2, ...) or None, optional) – Experimental planar-shear stretch and force-per-undeformed-area data (default is None).

• bx (array of shape (2, ...) or None, optional) – Experimental biaxial stretch and force-per-undeformed-area data (default is None).

• incompressible (bool, optional) – A flag to enforce incompressible deformations (default is False).

• relative (bool, optional) – A flag to optimize relative instead of absolute residuals, i.e. (predicted - observed) / observed instead of predicted - observed (default is False).

• **kwargs (dict, optional) – Optional keyword arguments are passed to scipy.optimize.least_squares().

Returns:

• ConstitutiveMaterial – A copy of the constitutive material with the optimized material parameters.

• scipy.optimize.OptimizeResult – Represents the optimization result.

Notes

Warning

At least one load case, i.e. one of the arguments ux, ps or bx must not be None.

The vector of residuals is given in Eq. (3) in case of absolute residuals

(25)\[ \begin{align}\begin{aligned}\begin{split}\boldsymbol{r} &= \begin{bmatrix} \boldsymbol{r}_\text{ux} \\ \boldsymbol{r}_\text{ps} \\ \boldsymbol{r}_\text{bx} \end{bmatrix}\end{split}\\r_\text{ux}(\lambda_i) &= P_\text{ux}(\lambda_i) - P_\text{ux, observed}(\lambda_i)\\r_\text{ps}(\lambda_i) &= P_\text{ps}(\lambda_i) - P_\text{ps, observed}(\lambda_i)\\r_\text{bx}(\lambda_i) &= P_\text{bx}(\lambda_i) - P_\text{bx, observed}(\lambda_i)\end{aligned}\end{align} \]

and in Eq. (4) in case of relative residuals.

(26)\[ \begin{align}\begin{aligned}\begin{split}\boldsymbol{r} &= \begin{bmatrix} \boldsymbol{r}_\text{ux} \\ \boldsymbol{r}_\text{ps} \\ \boldsymbol{r}_\text{bx} \end{bmatrix}\end{split}\\r_\text{ux}(\lambda_i) &= \frac{ P_\text{ux}(\lambda_i) - P_\text{ux, observed}(\lambda_i)}{ P_\text{ux, observed}(\lambda_i) }\\r_\text{ps}(\lambda_i) &= \frac{ P_\text{ps}(\lambda_i) - P_\text{ps, observed}(\lambda_i)}{ P_\text{ps, observed}(\lambda_i) }\\r_\text{bx}(\lambda_i) &= \frac{ P_\text{bx}(\lambda_i) - P_\text{bx, observed}(\lambda_i)}{ P_\text{bx, observed}(\lambda_i) }\end{aligned}\end{align} \]

Examples

The Anssari-Benam Bucchi material model formulation is best-fitted on Treloar’s uniaxial and biaxial tension data [1]_.

>>> import numpy as np
>>> import felupe as fem
>>>
>>> λ, P = np.array(
...     [
...         [1.000, 0.00],
...         [1.240, 2.30],
...         [1.585, 4.16],
...         [2.180, 6.00],
...         [3.020, 8.80],
...         [4.030, 12.5],
...         [4.760, 16.2],
...         [5.750, 23.6],
...         [6.850, 38.5],
...         [7.250, 49.6],
...         [7.600, 64.4],
...     ]
... ).T * np.array([[1.0], [0.0980665]])
>>>
>>> umat = fem.Hyperelastic(fem.anssari_benam_bucchi)
>>> umat_new, res = umat.optimize(
...     ux=[λ, P], incompressible=True, relative=True
... )
>>>
>>> ux = np.linspace(λ.min(), λ.max(), num=50)
>>> ax = umat_new.plot(incompressible=True, ux=ux, bx=None, ps=None)

>>> ax.plot(λ, P, "C0x")

See also

scipy.optimize.least_squares

Solve a nonlinear least-squares problem with bounds on the variables.

References

[1]

L. R. G. Treloar, “Stress-strain data for vulcanised rubber under various types of deformation”, Transactions of the Faraday Society, vol. 40. Royal Society of Chemistry (RSC), p. 59, 1944. doi: 10.1039/tf9444000059. Data available at https://www.uni-due.de/mathematik/ag_neff/neff_hencky.

plot(incompressible=False, **kwargs)

Return a plot with normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

matplotlib.axes.Axes

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

screenshot(filename='umat.png', incompressible=False, **kwargs)

Save a screenshot with normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• filename (str, optional) – The filename of the screenshot (default is “umat.png”).

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

matplotlib.axes.Axes

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

view(incompressible=False, **kwargs)

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

felupe.ViewMaterial or felupe.ViewMaterialIncompressible

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

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{P} : \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{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 (ConstitutiveMaterial) – A hyperelastic material definition for the strain energy density function with methods for the gradient and the hessian w.r.t the deformation gradient tensor.

• parallel (bool, optional) – A flag to invoke parallel (threaded) math operations (default is False).

copy()

Return a deep-copy of the constitutive material.

gradient(x)

Return a list of variations of the total potential energy w.r.t. the fields displacements, pressure and volume ratio.

Parameters:

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

Returns:

List of gradients w.r.t. the input variables \(\boldsymbol{F}\), \(p\) and \(\bar{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

optimize(ux=None, ps=None, bx=None, incompressible=False, relative=False, **kwargs)

Optimize the material parameters by a least-squares fit on experimental stretch-stress data.

Parameters:

• ux (array of shape (2, ...) or None, optional) – Experimental uniaxial stretch and force-per-undeformed-area data (default is None).

• ps (array of shape (2, ...) or None, optional) – Experimental planar-shear stretch and force-per-undeformed-area data (default is None).

• bx (array of shape (2, ...) or None, optional) – Experimental biaxial stretch and force-per-undeformed-area data (default is None).

• incompressible (bool, optional) – A flag to enforce incompressible deformations (default is False).

• relative (bool, optional) – A flag to optimize relative instead of absolute residuals, i.e. (predicted - observed) / observed instead of predicted - observed (default is False).

• **kwargs (dict, optional) – Optional keyword arguments are passed to scipy.optimize.least_squares().

Returns:

• ConstitutiveMaterial – A copy of the constitutive material with the optimized material parameters.

• scipy.optimize.OptimizeResult – Represents the optimization result.

Notes

Warning

At least one load case, i.e. one of the arguments ux, ps or bx must not be None.

The vector of residuals is given in Eq. (3) in case of absolute residuals

(27)\[ \begin{align}\begin{aligned}\begin{split}\boldsymbol{r} &= \begin{bmatrix} \boldsymbol{r}_\text{ux} \\ \boldsymbol{r}_\text{ps} \\ \boldsymbol{r}_\text{bx} \end{bmatrix}\end{split}\\r_\text{ux}(\lambda_i) &= P_\text{ux}(\lambda_i) - P_\text{ux, observed}(\lambda_i)\\r_\text{ps}(\lambda_i) &= P_\text{ps}(\lambda_i) - P_\text{ps, observed}(\lambda_i)\\r_\text{bx}(\lambda_i) &= P_\text{bx}(\lambda_i) - P_\text{bx, observed}(\lambda_i)\end{aligned}\end{align} \]

and in Eq. (4) in case of relative residuals.

(28)\[ \begin{align}\begin{aligned}\begin{split}\boldsymbol{r} &= \begin{bmatrix} \boldsymbol{r}_\text{ux} \\ \boldsymbol{r}_\text{ps} \\ \boldsymbol{r}_\text{bx} \end{bmatrix}\end{split}\\r_\text{ux}(\lambda_i) &= \frac{ P_\text{ux}(\lambda_i) - P_\text{ux, observed}(\lambda_i)}{ P_\text{ux, observed}(\lambda_i) }\\r_\text{ps}(\lambda_i) &= \frac{ P_\text{ps}(\lambda_i) - P_\text{ps, observed}(\lambda_i)}{ P_\text{ps, observed}(\lambda_i) }\\r_\text{bx}(\lambda_i) &= \frac{ P_\text{bx}(\lambda_i) - P_\text{bx, observed}(\lambda_i)}{ P_\text{bx, observed}(\lambda_i) }\end{aligned}\end{align} \]

Examples

The Anssari-Benam Bucchi material model formulation is best-fitted on Treloar’s uniaxial and biaxial tension data [1]_.

>>> import numpy as np
>>> import felupe as fem
>>>
>>> λ, P = np.array(
...     [
...         [1.000, 0.00],
...         [1.240, 2.30],
...         [1.585, 4.16],
...         [2.180, 6.00],
...         [3.020, 8.80],
...         [4.030, 12.5],
...         [4.760, 16.2],
...         [5.750, 23.6],
...         [6.850, 38.5],
...         [7.250, 49.6],
...         [7.600, 64.4],
...     ]
... ).T * np.array([[1.0], [0.0980665]])
>>>
>>> umat = fem.Hyperelastic(fem.anssari_benam_bucchi)
>>> umat_new, res = umat.optimize(
...     ux=[λ, P], incompressible=True, relative=True
... )
>>>
>>> ux = np.linspace(λ.min(), λ.max(), num=50)
>>> ax = umat_new.plot(incompressible=True, ux=ux, bx=None, ps=None)

>>> ax.plot(λ, P, "C0x")

See also

scipy.optimize.least_squares

Solve a nonlinear least-squares problem with bounds on the variables.

References

[1]

L. R. G. Treloar, “Stress-strain data for vulcanised rubber under various types of deformation”, Transactions of the Faraday Society, vol. 40. Royal Society of Chemistry (RSC), p. 59, 1944. doi: 10.1039/tf9444000059. Data available at https://www.uni-due.de/mathematik/ag_neff/neff_hencky.

plot(incompressible=False, **kwargs)

Return a plot with normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

matplotlib.axes.Axes

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

screenshot(filename='umat.png', incompressible=False, **kwargs)

Save a screenshot with normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• filename (str, optional) – The filename of the screenshot (default is “umat.png”).

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

matplotlib.axes.Axes

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

view(incompressible=False, **kwargs)

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

Parameters:

• incompressible (bool, optional) – A flag to enforce views on incompressible deformations (default is False).

• **kwargs (dict, optional) – Optional keyword-arguments for ViewMaterial or ViewMaterialIncompressible.

Return type:

felupe.ViewMaterial or felupe.ViewMaterialIncompressible

See also

felupe.ViewMaterial

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.

felupe.ViewMaterialIncompressible

Create views on normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension of a given isotropic material formulation.