Constitution

This module provides constitutive material formulations. In FElupe, a constitutive material definition, or so-called umat (user material), is a class with methods for evaluating gradients and hessians of the strain energy density function with respect to the defined fields in the field container, where the gradient of the first (displacement) field is passed as the deformation gradient. For all following fields, the field values (no gradients) are provided. An attribute x=[np.zeros(statevars_shape)] has to be added to the class to define the shape of optional state variables. For reasons of performance, FElupe passes the field gradients and values all at once, e.g. the deformation gradient is of shape (3, 3, q, c), where q refers to the number of quadrature points per cell and c to the number of cells. These last two axes are the so-called trailing axes. Math-functions from felupe.math all support the operation on trailing axes. The constitutive material definition class should be inherited from ConstitutiveMaterial in order to provide force-stretch curves for elementary deformations. Take this code-block as a template for a two-field \((\boldsymbol{u}, p)\) formulation with the old displacement gradient as a state variable:

import numpy as np
import felupe as fem

# math-functions which support trailing axes
from felupe.math import det, dya, identity, transpose, inv

class MyMaterialFormulation(fem.ConstitutiveMaterial):

    def __init__(self):
        # provide the shape of state variables without trailing axes
        # values are ignored - state variables are always initiated with zeros
        self.x = [np.zeros((3, 3))]

    def gradient(self, x):
        "Gradients of the strain energy density function."

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

        # user code
        dWdF = None  # first Piola-Kirchhoff stress tensor
        dWdp = None

        # update state variables
        # example: the displacement gradient
        statevars_new = F - identity(F)

        return [dWdF, dWdp, statevars_new]

    def hessian(self, x, **kwargs):
        "Hessians of the strain energy density function."

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

        # user code
        d2WdFdF = None  # fourth-order elasticity tensor
        d2WdFdp = None
        d2Wdpdp = None

        # upper-triangle items of the hessian
        return [d2WdFdF, d2WdFdp, d2Wdpdp]

umat = MyMaterialFormulation()

There are many different pre-defined constitutive material formulations available, including definitions for linear-elasticity, small-strain plasticity, hyperelasticity or pseudo-elasticity. The generation of user materials may be simplified when using frameworks for user-defined functions, like hyperelasticity (with automatic differentiation) or a small-strain based framework with state variables. The most general case is given by a framework with functions for the evaluation of stress and elasticity tensors in terms of the deformation gradient.

View Force-Stretch Curves on Elementary Deformations

ConstitutiveMaterial()	Base class for constitutive materials.
ViewMaterial(umat[, ux, ps, bx, statevars])	Create views on normal force per undeformed area vs.
ViewMaterialIncompressible(umat[, ux, ps, ...])	Create views on normal force per undeformed area vs.

Merge Constitutive Materials

CompositeMaterial(material, other_material)

A composite material with two constitutive materials merged.

Linear-Elasticity

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

Plasticity

LinearElasticPlasticIsotropicHardening(E, ...)

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

Hyperelasticity

NeoHooke([mu, bulk, parallel])	Nearly-incompressible isotropic hyperelastic Neo-Hookean material formulation.
NeoHookeCompressible([mu, lmbda, parallel])	Compressible isotropic hyperelastic Neo-Hookean material formulation.
Volumetric(bulk[, parallel])	Neo-Hookean material formulation with deactivated shear modulus.

Hyperelastic Three-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.

Pseudo-Elasticity (Isotropic Damage)

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.

Hyperelastic User-Materials with Automatic Differentation

Hyperelastic(fun[, nstatevars, parallel])	A hyperelastic material definition with a given function for the strain energy density function per unit undeformed volume with Automatic Differentiation provided by tensortrax.
MaterialAD(fun[, nstatevars, parallel])	A user-defined material definition with a given function for the partial derivative of the strain energy function w.r.t.

Material Model Formulations (Strain Energy Functions) for Hyperelastic

saint_venant_kirchhoff(C, mu, lmbda)	Strain energy function of the isotropic hyperelastic Saint-Venant Kirchhoff material formulation.
neo_hooke(C, mu)	Strain energy function of the isotropic hyperelastic Neo-Hookean material formulation.
mooney_rivlin(C, C10, C01)	Strain energy function of the isotropic hyperelastic Mooney-Rivlin material formulation.
yeoh(C, C10, C20, C30)	Strain energy function of the isotropic hyperelastic Yeoh material formulation.
third_order_deformation(C, C10, C01, C11, ...)	Strain energy function of the isotropic hyperelastic Third-Order-Deformation material formulation.
ogden(C, mu, alpha)	Strain energy function of the isotropic hyperelastic Ogden material formulation.
arruda_boyce(C, C1, limit)	Strain energy function of the isotropic hyperelastic Arruda-Boyce material formulation.
extended_tube(C, Gc, delta, Ge, beta)	Strain energy function of the isotropic hyperelastic Extended Tube [1]_ material formulation.
van_der_waals(C, mu, limit, a, beta)	Strain energy function of the Van der Waals [1]_ material formulation.,
finite_strain_viscoelastic(C, Cin, mu, eta, ...)	Multiplicative finite strain viscoelastic [1]_ material formulation.

(Small) Strain-based User Materials

MaterialStrain(material[, dim, statevars])	A strain-based user-defined material definition with a given function for the stress tensor and the (fourth-order) elasticity tensor.
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.

Deformation-Gradient-based User Materials

Material(stress, elasticity[, nstatevars])

A user-defined material definition with given functions for the (first Piola-Kirchhoff) stress tensor \(\boldsymbol{P}\), optional constraints on additional fields (e.g. \(p\) and \(J\)), updated state variables \(\boldsymbol{\zeta}\) as well as the according fourth-order elasticity tensor \(\mathbb{A}\) and the linearizations of the constraint equations.

Kinematics

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

Detailed API Reference

class felupe.ConstitutiveMaterial

Base class for constitutive materials.

optimize(ux=None, ps=None, bx=None, incompressible=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).

• **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.

Examples

The Ogden material model formulation is fitted on Treloar’s uniaxial tension data [1]_.

>>> import numpy as np
>>> import felupe as fem
>>>
>>> stretches, stresses = np.array(
...     [
...         [1.000, 0.00],
...         [1.020, 0.26],
...         [1.125, 1.37],
...         [1.240, 2.30],
...         [1.390, 3.23],
...         [1.585, 4.16],
...         [1.900, 5.10],
...         [2.180, 6.00],
...         [2.420, 6.90],
...         [3.020, 8.80],
...         [3.570, 10.7],
...         [4.030, 12.5],
...         [4.760, 16.2],
...         [5.360, 19.9],
...         [5.750, 23.6],
...         [6.150, 27.4],
...         [6.400, 31.0],
...         [6.600, 34.8],
...         [6.850, 38.5],
...         [7.050, 42.1],
...         [7.150, 45.8],
...         [7.250, 49.6],
...         [7.400, 53.3],
...         [7.500, 57.0],
...         [7.600, 64.4],
...     ]
... ).T * np.array([[1.0], [0.0980665]])
>>>
>>> umat = fem.Hyperelastic(fem.ogden)
>>> umat_new, res = umat.optimize(ux=[stretches, stresses], incompressible=True)
>>>
>>> ux = np.linspace(stretches.min(), stretches.max(), num=200)
>>> ax = umat_new.plot(incompressible=True, ux=ux, bx=None, ps=None)

>>> ax.plot(stretches, stresses, "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.ViewMaterial(umat, ux=array([0.7, 0.75, 0.8, 0.85, 0.9, 0.95, 1., 1.05, 1.1, 1.15, 1.2, 1.25, 1.3, 1.35, 1.4, 1.45, 1.5, 1.55, 1.6, 1.65, 1.7, 1.75, 1.8, 1.85, 1.9, 1.95, 2., 2.05, 2.1, 2.15, 2.2, 2.25, 2.3, 2.35, 2.4, 2.45, 2.5]), ps=array([1., 1.05, 1.1, 1.15, 1.2, 1.25, 1.3, 1.35, 1.4, 1.45, 1.5, 1.55, 1.6, 1.65, 1.7, 1.75, 1.8, 1.85, 1.9, 1.95, 2., 2.05, 2.1, 2.15, 2.2, 2.25, 2.3, 2.35, 2.4, 2.45, 2.5]), bx=array([1., 1.05, 1.1, 1.15, 1.2, 1.25, 1.3, 1.35, 1.4, 1.45, 1.5, 1.55, 1.6, 1.65, 1.7, 1.75]), statevars=None)

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:

• umat (class) – A class with methods for the gradient and hessian of the strain energy density function w.r.t. the deformation gradient. See Material for further details.

• ux (ndarray, optional) – Array with stretches for uniaxial tension/compression. Default is linsteps([0.7, 2.5], num=36).

• ps (ndarray, optional) – Array with stretches for planar shear. Default is linsteps([1.0, 2.5], num=30).

• bx (ndarray, optional) – Array with stretches for equi-biaxial tension. Default is linsteps([1.0, 1.75], num=15)`.

• statevars (ndarray or None, optional) – Array with state variables (default is None). If None, the state variables are assumed to be initially zero.

Examples

>>> import felupe as fem
>>>
>>> umat = fem.OgdenRoxburgh(fem.NeoHooke(mu=1, bulk=2), r=3, m=1, beta=0)
>>> view = fem.ViewMaterial(
...     umat,
...     ux=fem.math.linsteps([1, 1.5, 1, 2, 1, 2.5, 1], num=15),
...     ps=None,
...     bx=None,
... )
>>> ax = view.plot(show_title=True, show_kwargs=True)

biaxial(stretches=None)

Normal force per undeformed area vs. stretch curve for a equi-biaxial incompressible deformation.

Parameters:

stretches (ndarray or None, optional) – Array with stretches at which the forces are evaluated (default is None). If None, the stretches from initialization are used.

Returns:

3-tuple with array of stretches and array of forces and the label.

Return type:

tuple of ndarray

evaluate()

Evaluate normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension. A load case is not included if its array of stretches (attribute ux, ps or bx) is None.

Returns:

List with 3-tuple of stretch and force arrays and the label string for each load case.

Return type:

list of 3-tuple

planar(stretches=None)

Normal force per undeformed area vs. stretch curve for a planar shear incompressible deformation.

Parameters:

stretches (ndarray or None, optional) – Array with stretches at which the forces are evaluated (default is None). If None, the stretches from initialization are used.

Returns:

3-tuple with array of stretches and array of forces and the label.

Return type:

tuple of ndarray

plot(ax=None, show_title=True, show_kwargs=True, **kwargs)

Plot normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension.

uniaxial(stretches=None)

Normal force per undeformed area vs. stretch curve for a uniaxial deformation.

Parameters:

stretches (ndarray or None, optional) – Array with stretches at which the forces are evaluated (default is None). If None, the stretches from initialization are used.

Returns:

3-tuple with array of stretches and array of forces and the label.

Return type:

tuple of ndarray

class felupe.ViewMaterialIncompressible(umat, ux=array([0.7, 0.75, 0.8, 0.85, 0.9, 0.95, 1., 1.05, 1.1, 1.15, 1.2, 1.25, 1.3, 1.35, 1.4, 1.45, 1.5, 1.55, 1.6, 1.65, 1.7, 1.75, 1.8, 1.85, 1.9, 1.95, 2., 2.05, 2.1, 2.15, 2.2, 2.25, 2.3, 2.35, 2.4, 2.45, 2.5]), ps=array([1., 1.05, 1.1, 1.15, 1.2, 1.25, 1.3, 1.35, 1.4, 1.45, 1.5, 1.55, 1.6, 1.65, 1.7, 1.75, 1.8, 1.85, 1.9, 1.95, 2., 2.05, 2.1, 2.15, 2.2, 2.25, 2.3, 2.35, 2.4, 2.45, 2.5]), bx=array([1., 1.05, 1.1, 1.15, 1.2, 1.25, 1.3, 1.35, 1.4, 1.45, 1.5, 1.55, 1.6, 1.65, 1.7, 1.75]), statevars=None)

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.

Parameters:

• umat (class) – A class with methods for the gradient and hessian of the strain energy density function w.r.t. the deformation gradient. See Material for further details.

• ux (ndarray, optional) – Array with stretches for incompressible uniaxial tension/compression. Default is linsteps([0.7, 2.5], num=36).

• ps (ndarray, optional) – Array with stretches for incompressible planar shear. Default is linsteps([1, 2.5], num=30).

• bx (ndarray, optional) – Array with stretches for incompressible equi-biaxial tension. Default is linsteps([1, 1.75], num=15).

• statevars (ndarray or None, optional) – Array with state variables (default is None). If None, the state variables are assumed to be initially zero.

Examples

>>> import felupe as fem
>>>
>>> umat = fem.Hyperelastic(fem.extended_tube, Gc=0.2, Ge=0.2, beta=0.2, delta=0.1)
>>> preview = fem.ViewMaterialIncompressible(umat)
>>> ax = preview.plot(show_title=True, show_kwargs=True)

>>> umat = fem.OgdenRoxburgh(fem.NeoHooke(mu=1), r=3, m=1, beta=0)
>>> view = fem.ViewMaterialIncompressible(
...     umat,
...     ux=fem.math.linsteps([1, 1.5, 1, 2, 1, 2.5, 1], num=15),
...     ps=None,
...     bx=None,
... )
>>> ax = view.plot(show_title=True, show_kwargs=True)

biaxial(stretches=None)

Normal force per undeformed area vs. stretch curve for a equi-biaxial incompressible deformation.

Parameters:

stretches (ndarray or None, optional) – Array with stretches at which the forces are evaluated (default is None). If None, the stretches from initialization are used.

Returns:

3-tuple with array of stretches and array of forces and the label.

Return type:

tuple of ndarray

evaluate()

Evaluate normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension. A load case is not included if its array of stretches (attribute ux, ps or bx) is None.

Returns:

List with 3-tuple of stretch and force arrays and the label string for each load case.

Return type:

list of 3-tuple

planar(stretches=None)

Normal force per undeformed area vs. stretch curve for a planar shear incompressible deformation.

Parameters:

stretches (ndarray or None, optional) – Array with stretches at which the forces are evaluated (default is None). If None, the stretches from initialization are used.

Returns:

3-tuple with array of stretches and array of forces and the label.

Return type:

tuple of ndarray

plot(ax=None, show_title=True, show_kwargs=True, **kwargs)

Plot normal force per undeformed area vs. stretch curves for the elementary homogeneous incompressible deformations uniaxial tension/compression, planar shear and biaxial tension.

uniaxial(stretches=None)

Normal force per undeformed area vs. stretch curve for a uniaxial incompressible deformation.

Parameters:

stretches (ndarray or None, optional) – Array with stretches at which the forces are evaluated (default is None). If None, the stretches from initialization are used.

Returns:

3-tuple with array of stretches and array of forces and the label.

Return type:

tuple of ndarray

class felupe.CompositeMaterial(material, other_material)

A composite material with two constitutive materials merged. State variables are only considered for the first material.

Parameters:

• material (ConstitutiveMaterial) – First constitutive material.

• other_material (ConstitutiveMaterial) – Second constitutive material.

Notes

Warning

Do not merge two constitutive materials with the same keys of material parameters. In this case, the values of these material parameters are taken from the first constitutive material.

Examples

>>> import felupe as fem
>>>
>>> nh = fem.NeoHooke(mu=1.0)
>>> vol = fem.Volumetric(bulk=2.0)
>>> umat = nh & vol
>>> ax = umat.plot()

gradient(x, **kwargs)

hessian(x, **kwargs)

optimize(ux=None, ps=None, bx=None, incompressible=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).

• **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.

Examples

The Ogden material model formulation is fitted on Treloar’s uniaxial tension data [1]_.

>>> import numpy as np
>>> import felupe as fem
>>>
>>> stretches, stresses = np.array(
...     [
...         [1.000, 0.00],
...         [1.020, 0.26],
...         [1.125, 1.37],
...         [1.240, 2.30],
...         [1.390, 3.23],
...         [1.585, 4.16],
...         [1.900, 5.10],
...         [2.180, 6.00],
...         [2.420, 6.90],
...         [3.020, 8.80],
...         [3.570, 10.7],
...         [4.030, 12.5],
...         [4.760, 16.2],
...         [5.360, 19.9],
...         [5.750, 23.6],
...         [6.150, 27.4],
...         [6.400, 31.0],
...         [6.600, 34.8],
...         [6.850, 38.5],
...         [7.050, 42.1],
...         [7.150, 45.8],
...         [7.250, 49.6],
...         [7.400, 53.3],
...         [7.500, 57.0],
...         [7.600, 64.4],
...     ]
... ).T * np.array([[1.0], [0.0980665]])
>>>
>>> umat = fem.Hyperelastic(fem.ogden)
>>> umat_new, res = umat.optimize(ux=[stretches, stresses], incompressible=True)
>>>
>>> ux = np.linspace(stretches.min(), stretches.max(), num=200)
>>> ax = umat_new.plot(incompressible=True, ux=ux, bx=None, ps=None)

>>> ax.plot(stretches, stresses, "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

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

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

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

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

Parameters:

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

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

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

gradient(x, mu=None, bulk=None, 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

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

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

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

hessian(x, mu=None, bulk=None, 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

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

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

• 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, **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).

• **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.

Examples

The Ogden material model formulation is fitted on Treloar’s uniaxial tension data [1]_.

>>> import numpy as np
>>> import felupe as fem
>>>
>>> stretches, stresses = np.array(
...     [
...         [1.000, 0.00],
...         [1.020, 0.26],
...         [1.125, 1.37],
...         [1.240, 2.30],
...         [1.390, 3.23],
...         [1.585, 4.16],
...         [1.900, 5.10],
...         [2.180, 6.00],
...         [2.420, 6.90],
...         [3.020, 8.80],
...         [3.570, 10.7],
...         [4.030, 12.5],
...         [4.760, 16.2],
...         [5.360, 19.9],
...         [5.750, 23.6],
...         [6.150, 27.4],
...         [6.400, 31.0],
...         [6.600, 34.8],
...         [6.850, 38.5],
...         [7.050, 42.1],
...         [7.150, 45.8],
...         [7.250, 49.6],
...         [7.400, 53.3],
...         [7.500, 57.0],
...         [7.600, 64.4],
...     ]
... ).T * np.array([[1.0], [0.0980665]])
>>>
>>> umat = fem.Hyperelastic(fem.ogden)
>>> umat_new, res = umat.optimize(ux=[stretches, stresses], incompressible=True)
>>>
>>> ux = np.linspace(stretches.min(), stretches.max(), num=200)
>>> ax = umat_new.plot(incompressible=True, ux=ux, bx=None, ps=None)

>>> ax.plot(stretches, stresses, "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) – Shear modulus (second Lamé constant)

• lmbda (float) – First Lamé constant

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

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

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

Parameters:

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

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

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

gradient(x, mu=None, lmbda=None, 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

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

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

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

hessian(x, mu=None, lmbda=None, 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

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

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

• 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, **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).

• **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.

Examples

The Ogden material model formulation is fitted on Treloar’s uniaxial tension data [1]_.

>>> import numpy as np
>>> import felupe as fem
>>>
>>> stretches, stresses = np.array(
...     [
...         [1.000, 0.00],
...         [1.020, 0.26],
...         [1.125, 1.37],
...         [1.240, 2.30],
...         [1.390, 3.23],
...         [1.585, 4.16],
...         [1.900, 5.10],
...         [2.180, 6.00],
...         [2.420, 6.90],
...         [3.020, 8.80],
...         [3.570, 10.7],
...         [4.030, 12.5],
...         [4.760, 16.2],
...         [5.360, 19.9],
...         [5.750, 23.6],
...         [6.150, 27.4],
...         [6.400, 31.0],
...         [6.600, 34.8],
...         [6.850, 38.5],
...         [7.050, 42.1],
...         [7.150, 45.8],
...         [7.250, 49.6],
...         [7.400, 53.3],
...         [7.500, 57.0],
...         [7.600, 64.4],
...     ]
... ).T * np.array([[1.0], [0.0980665]])
>>>
>>> umat = fem.Hyperelastic(fem.ogden)
>>> umat_new, res = umat.optimize(ux=[stretches, stresses], incompressible=True)
>>>
>>> ux = np.linspace(stretches.min(), stretches.max(), num=200)
>>> ax = umat_new.plot(incompressible=True, ux=ux, bx=None, ps=None)

>>> ax.plot(stretches, stresses, "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.Volumetric(bulk, parallel=False)

Neo-Hookean material formulation with deactivated shear modulus.

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

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

Parameters:

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

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

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

gradient(x, mu=None, bulk=None, 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

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

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

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

hessian(x, mu=None, bulk=None, 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

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

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

• 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, **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).

• **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.

Examples

The Ogden material model formulation is fitted on Treloar’s uniaxial tension data [1]_.

>>> import numpy as np
>>> import felupe as fem
>>>
>>> stretches, stresses = np.array(
...     [
...         [1.000, 0.00],
...         [1.020, 0.26],
...         [1.125, 1.37],
...         [1.240, 2.30],
...         [1.390, 3.23],
...         [1.585, 4.16],
...         [1.900, 5.10],
...         [2.180, 6.00],
...         [2.420, 6.90],
...         [3.020, 8.80],
...         [3.570, 10.7],
...         [4.030, 12.5],
...         [4.760, 16.2],
...         [5.360, 19.9],
...         [5.750, 23.6],
...         [6.150, 27.4],
...         [6.400, 31.0],
...         [6.600, 34.8],
...         [6.850, 38.5],
...         [7.050, 42.1],
...         [7.150, 45.8],
...         [7.250, 49.6],
...         [7.400, 53.3],
...         [7.500, 57.0],
...         [7.600, 64.4],
...     ]
... ).T * np.array([[1.0], [0.0980665]])
>>>
>>> umat = fem.Hyperelastic(fem.ogden)
>>> umat_new, res = umat.optimize(ux=[stretches, stresses], incompressible=True)
>>>
>>> ux = np.linspace(stretches.min(), stretches.max(), num=200)
>>> ax = umat_new.plot(incompressible=True, ux=ux, bx=None, ps=None)

>>> ax.plot(stretches, stresses, "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_{max}) &= 1 - \frac{1}{r} erf\left( \frac{\psi_{max} - \psi} {m + \beta~\psi_{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,
... )

gradient(x)

hessian(x)

optimize(ux=None, ps=None, bx=None, incompressible=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).

• **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.

Examples

The Ogden material model formulation is fitted on Treloar’s uniaxial tension data [1]_.

>>> import numpy as np
>>> import felupe as fem
>>>
>>> stretches, stresses = np.array(
...     [
...         [1.000, 0.00],
...         [1.020, 0.26],
...         [1.125, 1.37],
...         [1.240, 2.30],
...         [1.390, 3.23],
...         [1.585, 4.16],
...         [1.900, 5.10],
...         [2.180, 6.00],
...         [2.420, 6.90],
...         [3.020, 8.80],
...         [3.570, 10.7],
...         [4.030, 12.5],
...         [4.760, 16.2],
...         [5.360, 19.9],
...         [5.750, 23.6],
...         [6.150, 27.4],
...         [6.400, 31.0],
...         [6.600, 34.8],
...         [6.850, 38.5],
...         [7.050, 42.1],
...         [7.150, 45.8],
...         [7.250, 49.6],
...         [7.400, 53.3],
...         [7.500, 57.0],
...         [7.600, 64.4],
...     ]
... ).T * np.array([[1.0], [0.0980665]])
>>>
>>> umat = fem.Hyperelastic(fem.ogden)
>>> umat_new, res = umat.optimize(ux=[stretches, stresses], incompressible=True)
>>>
>>> ux = np.linspace(stretches.min(), stretches.max(), num=200)
>>> ax = umat_new.plot(incompressible=True, ux=ux, bx=None, ps=None)

>>> ax.plot(stretches, stresses, "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=None, nu=None)

Isotropic linear-elastic material formulation.

Parameters:

• E (float) – Young’s modulus.

• nu (float) – Poisson ratio.

Notes

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

with the strain tensor

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

Examples

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

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

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

Parameters:

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

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

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

Returns:

Stress tensor (3x3)

Return type:

ndarray

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

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

Parameters:

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

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

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

• shape (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, **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).

• **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.

Examples

The Ogden material model formulation is fitted on Treloar’s uniaxial tension data [1]_.

>>> import numpy as np
>>> import felupe as fem
>>>
>>> stretches, stresses = np.array(
...     [
...         [1.000, 0.00],
...         [1.020, 0.26],
...         [1.125, 1.37],
...         [1.240, 2.30],
...         [1.390, 3.23],
...         [1.585, 4.16],
...         [1.900, 5.10],
...         [2.180, 6.00],
...         [2.420, 6.90],
...         [3.020, 8.80],
...         [3.570, 10.7],
...         [4.030, 12.5],
...         [4.760, 16.2],
...         [5.360, 19.9],
...         [5.750, 23.6],
...         [6.150, 27.4],
...         [6.400, 31.0],
...         [6.600, 34.8],
...         [6.850, 38.5],
...         [7.050, 42.1],
...         [7.150, 45.8],
...         [7.250, 49.6],
...         [7.400, 53.3],
...         [7.500, 57.0],
...         [7.600, 64.4],
...     ]
... ).T * np.array([[1.0], [0.0980665]])
>>>
>>> umat = fem.Hyperelastic(fem.ogden)
>>> umat_new, res = umat.optimize(ux=[stretches, stresses], incompressible=True)
>>>
>>> ux = np.linspace(stretches.min(), stretches.max(), num=200)
>>> ax = umat_new.plot(incompressible=True, ux=ux, bx=None, ps=None)

>>> ax.plot(stretches, stresses, "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.LinearElasticLargeStrain(E=None, nu=None, parallel=False)

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

Parameters:

• E (float) – Young’s modulus.

• nu (float) – Poisson ratio.

See also

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

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

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

Parameters:

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

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

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

Returns:

Stress tensor (3x3)

Return type:

ndarray

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

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

Parameters:

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

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

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

Returns:

Stress tensor (3x3)

Return type:

ndarray

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

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

Parameters:

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

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

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

Returns:

elasticity tensor (3x3x3x3)

Return type:

ndarray

optimize(ux=None, ps=None, bx=None, incompressible=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).

• **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.

Examples

The Ogden material model formulation is fitted on Treloar’s uniaxial tension data [1]_.

>>> import numpy as np
>>> import felupe as fem
>>>
>>> stretches, stresses = np.array(
...     [
...         [1.000, 0.00],
...         [1.020, 0.26],
...         [1.125, 1.37],
...         [1.240, 2.30],
...         [1.390, 3.23],
...         [1.585, 4.16],
...         [1.900, 5.10],
...         [2.180, 6.00],
...         [2.420, 6.90],
...         [3.020, 8.80],
...         [3.570, 10.7],
...         [4.030, 12.5],
...         [4.760, 16.2],
...         [5.360, 19.9],
...         [5.750, 23.6],
...         [6.150, 27.4],
...         [6.400, 31.0],
...         [6.600, 34.8],
...         [6.850, 38.5],
...         [7.050, 42.1],
...         [7.150, 45.8],
...         [7.250, 49.6],
...         [7.400, 53.3],
...         [7.500, 57.0],
...         [7.600, 64.4],
...     ]
... ).T * np.array([[1.0], [0.0980665]])
>>>
>>> umat = fem.Hyperelastic(fem.ogden)
>>> umat_new, res = umat.optimize(ux=[stretches, stresses], incompressible=True)
>>>
>>> ux = np.linspace(stretches.min(), stretches.max(), num=200)
>>> ax = umat_new.plot(incompressible=True, ux=ux, bx=None, ps=None)

>>> ax.plot(stretches, stresses, "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=None, nu=None, 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()

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

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

Parameters:

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

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

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

Returns:

Stress tensor (3x3)

Return type:

ndarray

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

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

Parameters:

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

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

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

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

Returns:

elasticity tensor (3x3x3x3)

Return type:

ndarray

optimize(ux=None, ps=None, bx=None, incompressible=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).

• **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.

Examples

The Ogden material model formulation is fitted on Treloar’s uniaxial tension data [1]_.

>>> import numpy as np
>>> import felupe as fem
>>>
>>> stretches, stresses = np.array(
...     [
...         [1.000, 0.00],
...         [1.020, 0.26],
...         [1.125, 1.37],
...         [1.240, 2.30],
...         [1.390, 3.23],
...         [1.585, 4.16],
...         [1.900, 5.10],
...         [2.180, 6.00],
...         [2.420, 6.90],
...         [3.020, 8.80],
...         [3.570, 10.7],
...         [4.030, 12.5],
...         [4.760, 16.2],
...         [5.360, 19.9],
...         [5.750, 23.6],
...         [6.150, 27.4],
...         [6.400, 31.0],
...         [6.600, 34.8],
...         [6.850, 38.5],
...         [7.050, 42.1],
...         [7.150, 45.8],
...         [7.250, 49.6],
...         [7.400, 53.3],
...         [7.500, 57.0],
...         [7.600, 64.4],
...     ]
... ).T * np.array([[1.0], [0.0980665]])
>>>
>>> umat = fem.Hyperelastic(fem.ogden)
>>> umat_new, res = umat.optimize(ux=[stretches, stresses], incompressible=True)
>>>
>>> ux = np.linspace(stretches.min(), stretches.max(), num=200)
>>> ax = umat_new.plot(incompressible=True, ux=ux, bx=None, ps=None)

>>> ax.plot(stretches, stresses, "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.LinearElasticPlaneStress(E, nu)

Plane-stress isotropic linear-elastic material formulation.

Parameters:

• E (float) – Young’s modulus.

• nu (float) – Poisson ratio.

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

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

Parameters:

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

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

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

Returns:

In-plane components of stress tensor (2x2)

Return type:

ndarray

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

Evaluate the elasticity tensor from the deformation gradient.

Parameters:

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

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

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

• shape (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, E=None, nu=None)

Evaluate the strain tensor from the deformation gradient.

Parameters:

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

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

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

Returns:

e – Strain tensor (3x3)

Return type:

ndarray

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

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

Parameters:

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

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

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

Returns:

Stress tensor (3x3)

Return type:

ndarray

class felupe.LinearElasticPlaneStrain(E, nu)

Plane-strain isotropic linear-elastic material formulation.

Parameters:

• E (float) – Young’s modulus.

• nu (float) – Poisson ratio.

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

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

Parameters:

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

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

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

Returns:

In-plane components of stress tensor (2x2)

Return type:

ndarray

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

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

Parameters:

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

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

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

Returns:

In-plane components of elasticity tensor (2x2x2x2)

Return type:

ndarray

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

Evaluate the strain tensor from the deformation gradient.

Parameters:

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

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

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

Returns:

e – Strain tensor (3x3)

Return type:

ndarray

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

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

Parameters:

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

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

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

Returns:

Stress tensor (3x3)

Return type:

ndarray

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

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

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

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

• **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.

Examples

The Ogden material model formulation is fitted on Treloar’s uniaxial tension data [1]_.

>>> import numpy as np
>>> import felupe as fem
>>>
>>> stretches, stresses = np.array(
...     [
...         [1.000, 0.00],
...         [1.020, 0.26],
...         [1.125, 1.37],
...         [1.240, 2.30],
...         [1.390, 3.23],
...         [1.585, 4.16],
...         [1.900, 5.10],
...         [2.180, 6.00],
...         [2.420, 6.90],
...         [3.020, 8.80],
...         [3.570, 10.7],
...         [4.030, 12.5],
...         [4.760, 16.2],
...         [5.360, 19.9],
...         [5.750, 23.6],
...         [6.150, 27.4],
...         [6.400, 31.0],
...         [6.600, 34.8],
...         [6.850, 38.5],
...         [7.050, 42.1],
...         [7.150, 45.8],
...         [7.250, 49.6],
...         [7.400, 53.3],
...         [7.500, 57.0],
...         [7.600, 64.4],
...     ]
... ).T * np.array([[1.0], [0.0980665]])
>>>
>>> umat = fem.Hyperelastic(fem.ogden)
>>> umat_new, res = umat.optimize(ux=[stretches, stresses], incompressible=True)
>>>
>>> ux = np.linspace(stretches.min(), stretches.max(), num=200)
>>> ax = umat_new.plot(incompressible=True, ux=ux, bx=None, ps=None)

>>> ax.plot(stretches, stresses, "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).

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

• **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.

Examples

The Ogden material model formulation is fitted on Treloar’s uniaxial tension data [1]_.

>>> import numpy as np
>>> import felupe as fem
>>>
>>> stretches, stresses = np.array(
...     [
...         [1.000, 0.00],
...         [1.020, 0.26],
...         [1.125, 1.37],
...         [1.240, 2.30],
...         [1.390, 3.23],
...         [1.585, 4.16],
...         [1.900, 5.10],
...         [2.180, 6.00],
...         [2.420, 6.90],
...         [3.020, 8.80],
...         [3.570, 10.7],
...         [4.030, 12.5],
...         [4.760, 16.2],
...         [5.360, 19.9],
...         [5.750, 23.6],
...         [6.150, 27.4],
...         [6.400, 31.0],
...         [6.600, 34.8],
...         [6.850, 38.5],
...         [7.050, 42.1],
...         [7.150, 45.8],
...         [7.250, 49.6],
...         [7.400, 53.3],
...         [7.500, 57.0],
...         [7.600, 64.4],
...     ]
... ).T * np.array([[1.0], [0.0980665]])
>>>
>>> umat = fem.Hyperelastic(fem.ogden)
>>> umat_new, res = umat.optimize(ux=[stretches, stresses], incompressible=True)
>>>
>>> ux = np.linspace(stretches.min(), stretches.max(), num=200)
>>> ax = umat_new.plot(incompressible=True, ux=ux, bx=None, ps=None)

>>> ax.plot(stretches, stresses, "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).

(1)\[\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.

(2)\[ \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.

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

• **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.

Examples

The Ogden material model formulation is fitted on Treloar’s uniaxial tension data [1]_.

>>> import numpy as np
>>> import felupe as fem
>>>
>>> stretches, stresses = np.array(
...     [
...         [1.000, 0.00],
...         [1.020, 0.26],
...         [1.125, 1.37],
...         [1.240, 2.30],
...         [1.390, 3.23],
...         [1.585, 4.16],
...         [1.900, 5.10],
...         [2.180, 6.00],
...         [2.420, 6.90],
...         [3.020, 8.80],
...         [3.570, 10.7],
...         [4.030, 12.5],
...         [4.760, 16.2],
...         [5.360, 19.9],
...         [5.750, 23.6],
...         [6.150, 27.4],
...         [6.400, 31.0],
...         [6.600, 34.8],
...         [6.850, 38.5],
...         [7.050, 42.1],
...         [7.150, 45.8],
...         [7.250, 49.6],
...         [7.400, 53.3],
...         [7.500, 57.0],
...         [7.600, 64.4],
...     ]
... ).T * np.array([[1.0], [0.0980665]])
>>>
>>> umat = fem.Hyperelastic(fem.ogden)
>>> umat_new, res = umat.optimize(ux=[stretches, stresses], incompressible=True)
>>>
>>> ux = np.linspace(stretches.min(), stretches.max(), num=200)
>>> ax = umat_new.plot(incompressible=True, ux=ux, bx=None, ps=None)

>>> ax.plot(stretches, stresses, "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.Material(stress, elasticity, nstatevars=0, **kwargs)

A user-defined material definition with given functions for the (first Piola-Kirchhoff) stress tensor \(\boldsymbol{P}\), optional constraints on additional fields (e.g. \(p\) and \(J\)), updated state variables \(\boldsymbol{\zeta}\) as well as the according fourth-order elasticity tensor \(\mathbb{A}\) and the linearizations of the constraint equations. Both functions take a list of the 3x3 deformation gradient \(\boldsymbol{F}\) and optional vector of state variables \(\boldsymbol{\zeta}_n\) as the first input argument. The stress-function must return the updated state variables \(\boldsymbol{\zeta}\).

Parameters:

• stress (callable) – A constitutive material definition which returns a list containting the (first Piola-Kirchhoff) stress tensor, optional additional constraints as well as the state variables. The state variables must always be included even if they are None. See template code-blocks for the required function signature.

• elasticity (callable) – A constitutive material definition which returns a list containing the fourth- order elasticity tensor as the jacobian of the (first Piola-Kirchhoff) stress tensor w.r.t. the deformation gradient, optional linearizations of the additional constraints. The state variables must not be returned. See template code-blocks for the required function signature.

• nstatevars (int, optional) – Number of internal state variable components (default is 0). State variable components must always be concatenated into a 1d-array.

Notes

Note

The first item in the list of the input arguments always contains the gradient of the (displacement) field \(\boldsymbol{u}\) w.r.t. the undeformed coordinates \(\boldsymbol{X}\). The identity matrix \(\boldsymbol{1}\) is added to this gradient, i.e. the first item of the list x contains the deformation gradient \(\boldsymbol{F} = \boldsymbol{1} + \frac{\partial \boldsymbol{u}}{\partial \boldsymbol{X}}\). All other fields are provided as interpolated values (no gradients evaluated).

For \((\boldsymbol{u})\) single-field formulations, the callables for stress and elasticity must return the gradient and hessian of the strain energy density function \(\psi(\boldsymbol{F})\) w.r.t. the deformation gradient tensor \(\boldsymbol{F}\).

\[\begin{split}\text{stress}(\boldsymbol{F}, \boldsymbol{\zeta}_n) = \begin{bmatrix} \frac{\partial \psi}{\partial \boldsymbol{F}} \\ \boldsymbol{\zeta} \end{bmatrix}\end{split}\]

The callable for elasticity (hessian) must not return the updated state variables.

\[\text{elasticity}(\boldsymbol{F}, \boldsymbol{\zeta}_n) = \begin{bmatrix} \frac{\partial^2 \psi}{\partial \boldsymbol{F}\ \partial \boldsymbol{F}} \end{bmatrix}\]

Take this code-block as template:

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

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

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

    # update state variables
    statevars_new = None

    return [P, statevars_new]

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

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

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

    return [dPdF]

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

For \((\boldsymbol{u}, p, J)\) mixed-field formulations, the callables for stress and elasticity must return the gradients and hessians of the (augmented) strain energy density function w.r.t. the deformation gradient and the other fields.

\[\begin{split}\text{stress}(\boldsymbol{F}, p, J, \boldsymbol{\zeta}_n) = \begin{bmatrix} \frac{\partial \psi}{\partial \boldsymbol{F}} \\ \frac{\partial \psi}{\partial p} \\ \frac{\partial \psi}{\partial J} \\ \boldsymbol{\zeta} \end{bmatrix}\end{split}\]

For the hessians, the upper-triangle blocks have to be provided.

\[\begin{split}\text{elasticity}(\boldsymbol{F}, p, J, \boldsymbol{\zeta}_n) = \begin{bmatrix} \frac{\partial^2 \psi}{\partial \boldsymbol{F}\ \partial \boldsymbol{F}} \\ \frac{\partial^2 \psi}{\partial \boldsymbol{F}\ \partial p} \\ \frac{\partial^2 \psi}{\partial \boldsymbol{F}\ \partial J} \\ \frac{\partial^2 \psi}{\partial p\ \partial p} \\ \frac{\partial^2 \psi}{\partial p\ \partial J} \\ \frac{\partial^2 \psi}{\partial J\ \partial J} \end{bmatrix}\end{split}\]

For \((\boldsymbol{u}, p, J)\) mixed-field formulations, take this code-block as template:

def gradient(x, **kwargs):
    "Gradients of the strain energy density function."

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

    # user code
    dWdF = None  # first Piola-Kirchhoff stress tensor
    dWdp = None
    dWdJ = None

    # update state variables
    statevars_new = None

    return [dWdF, dWdp, dWdJ, statevars_new]

def hessian(x, **kwargs):
    "Hessians of the strain energy density function."

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

    # user code
    d2WdFdF = None  # fourth-order elasticity tensor
    d2WdFdp = None
    d2WdFdJ = None
    d2Wdpdp = None
    d2WdpdJ = None
    d2WdJdJ = None

    # upper-triangle items of the hessian
    return [d2WdFdF, d2WdFdp, d2WdFdJ, d2Wdpdp, d2WdpdJ, d2WdJdJ]

umat = Material(gradient, hessian, **kwargs)

Examples

The compressible isotropic hyperelastic Neo-Hookean material formulation is given by the strain energy density function.

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

>>> import numpy as np
>>> import felupe as fem
>>> from felupe.math import (
...     cdya_ik,
...     cdya_il,
...     det,
...     dya,
...     identity,
...     inv,
...     transpose
... )

>>> def stress(x, mu, lmbda):
...     F, statevars = x[0], x[-1]
...     J = det(F)
...     lnJ = np.log(J)
...     iFT = transpose(inv(F, J))
...     dWdF = mu * (F - iFT) + lmbda * lnJ * iFT
...     return [dWdF, statevars]

>>> def elasticity(x, mu, lmbda):
...     F = x[0]
...     J = det(F)
...     iFT = transpose(inv(F, J))
...     eye = identity(F)
...     return [
...         mu * cdya_ik(eye, eye) + lmbda * dya(iFT, iFT) +
...         (mu - lmbda * np.log(J)) * cdya_il(iFT, iFT)
...     ]

>>> umat = fem.Material(stress, elasticity, mu=1.0, lmbda=2.0)

The material formulation is tested in a minimal example of non-homogeneous uniaxial tension.

>>> mesh = fem.Cube(n=6)
>>> region = fem.RegionHexahedron(mesh)
>>> field = fem.FieldContainer([fem.Field(region, dim=3)])
>>> boundaries, loadcase = fem.dof.uniaxial(field, clamped=True, move=0.5)
>>> solid = fem.SolidBodyNearlyIncompressible(umat, field, bulk=5000)
>>> step = fem.Step(items=[solid], boundaries=boundaries)
>>> job = fem.Job(steps=[step]).evaluate()

See also

felupe.NeoHookeCompressible

Nearly-incompressible isotropic hyperelastic Neo-Hookean material formulation.

gradient(x)

Return the evaluated gradient of the strain energy density function.

Parameters:

x (list of ndarray) – The list with input arguments. These contain the extracted fields of a FieldContainer along with the old vector of state variables, [*field.extract(), statevars_old].

Returns:

A list with the evaluated gradient(s) of the strain energy density function and the updated vector of state variables.

Return type:

list of ndarray

hessian(x)

Return the evaluated upper-triangle components of the hessian(s) of the strain energy density function.

Parameters:

x (list of ndarray) – The list with input arguments. These contain the extracted fields of a FieldContainer along with the old vector of state variables, [*field.extract(), statevars_old].

Returns:

A list with the evaluated upper-triangle components of the hessian(s) of the strain energy density function.

Return type:

list of ndarray

optimize(ux=None, ps=None, bx=None, incompressible=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).

• **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.

Examples

The Ogden material model formulation is fitted on Treloar’s uniaxial tension data [1]_.

>>> import numpy as np
>>> import felupe as fem
>>>
>>> stretches, stresses = np.array(
...     [
...         [1.000, 0.00],
...         [1.020, 0.26],
...         [1.125, 1.37],
...         [1.240, 2.30],
...         [1.390, 3.23],
...         [1.585, 4.16],
...         [1.900, 5.10],
...         [2.180, 6.00],
...         [2.420, 6.90],
...         [3.020, 8.80],
...         [3.570, 10.7],
...         [4.030, 12.5],
...         [4.760, 16.2],
...         [5.360, 19.9],
...         [5.750, 23.6],
...         [6.150, 27.4],
...         [6.400, 31.0],
...         [6.600, 34.8],
...         [6.850, 38.5],
...         [7.050, 42.1],
...         [7.150, 45.8],
...         [7.250, 49.6],
...         [7.400, 53.3],
...         [7.500, 57.0],
...         [7.600, 64.4],
...     ]
... ).T * np.array([[1.0], [0.0980665]])
>>>
>>> umat = fem.Hyperelastic(fem.ogden)
>>> umat_new, res = umat.optimize(ux=[stretches, stresses], incompressible=True)
>>>
>>> ux = np.linspace(stretches.min(), stretches.max(), num=200)
>>> ax = umat_new.plot(incompressible=True, ux=ux, bx=None, ps=None)

>>> ax.plot(stretches, stresses, "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).

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

• **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.

Examples

The Ogden material model formulation is fitted on Treloar’s uniaxial tension data [1]_.

>>> import numpy as np
>>> import felupe as fem
>>>
>>> stretches, stresses = np.array(
...     [
...         [1.000, 0.00],
...         [1.020, 0.26],
...         [1.125, 1.37],
...         [1.240, 2.30],
...         [1.390, 3.23],
...         [1.585, 4.16],
...         [1.900, 5.10],
...         [2.180, 6.00],
...         [2.420, 6.90],
...         [3.020, 8.80],
...         [3.570, 10.7],
...         [4.030, 12.5],
...         [4.760, 16.2],
...         [5.360, 19.9],
...         [5.750, 23.6],
...         [6.150, 27.4],
...         [6.400, 31.0],
...         [6.600, 34.8],
...         [6.850, 38.5],
...         [7.050, 42.1],
...         [7.150, 45.8],
...         [7.250, 49.6],
...         [7.400, 53.3],
...         [7.500, 57.0],
...         [7.600, 64.4],
...     ]
... ).T * np.array([[1.0], [0.0980665]])
>>>
>>> umat = fem.Hyperelastic(fem.ogden)
>>> umat_new, res = umat.optimize(ux=[stretches, stresses], incompressible=True)
>>>
>>> ux = np.linspace(stretches.min(), stretches.max(), num=200)
>>> ax = umat_new.plot(incompressible=True, ux=ux, bx=None, ps=None)

>>> ax.plot(stretches, stresses, "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.

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=1.0,
...     K=0.1,
...     dim=3,
...     statevars=(1, (3, 3)),
... )

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.MaterialAD(fun, nstatevars=0, parallel=False, **kwargs)

A user-defined material definition with a given function for the partial derivative of the strain energy function w.r.t. the deformation gradient tensor with Automatic Differentiation provided by tensortrax.

Parameters:

• fun (callable) – A gradient of the strain energy density function w.r.t. the deformation gradient tensor \(\boldsymbol{F}\). Function signature must be fun = lambda F, **kwargs: P for functions without state variables and fun = lambda F, statevars, **kwargs: [P, statevars_new] for functions with state variables. The deformation gradient tensor will be a tensortrax.Tensor when the function is evaluated. It is important to only use differentiable math-functions from tensortrax.math!

• nstatevars (int, optional) – Number of state variables (default is 0).

• parallel (bool, optional) – A flag to invoke threaded gradient of strain energy density function evaluations (default is False). May introduce additional overhead for small-sized problems.

• **kwargs (dict, optional) – Optional keyword-arguments for the gradient of the strain energy density function.

Notes

The gradient of the strain energy density function \(\frac{\partial \psi}{\partial \boldsymbol{F}}\) must be given in terms of the deformation gradient tensor \(\boldsymbol{F}\).

Warning

It is important to only use differentiable math-functions from tensortrax.math!

\[\boldsymbol{P} = \frac{\partial \psi(\boldsymbol{F}, \boldsymbol{\zeta})}{ \partial \boldsymbol{F}}\]

Take this code-block as template

import tensortrax.math as tm

def neo_hooke(F, mu):
    "First Piola-Kirchhoff stress of the Neo-Hookean material formulation."

    C = tm.dot(tm.transpose(F), F)
    Cu = tm.linalg.det(C) ** (-1/3) * C

    return mu * F @ tm.special.dev(Cu) @ tm.linalg.inv(C)

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

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

import tensortrax.math as tm

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

    # unimodular part of the right Cauchy-Green deformation tensor
    C = tm.dot(tm.transpose(F), F)
    Cu = tm.linalg.det(C) ** (-1 / 3) * C

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

    # second Piola-Kirchhoff stress tensor
    S = mu * tm.special.dev(Cu @ tm.linalg.inv(Ci)) @ tm.linalg.inv(C)

    # first Piola-Kirchhoff stress tensor and state variable
    return F @ S, tm.special.triu_1d(Ci)

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

Note

See the documentation of tensortrax for further details.

Examples

>>> import felupe as fem
>>> import tensortrax.math as tm
>>>
>>> def neo_hooke(F, mu):
...     C = tm.dot(tm.transpose(F), F)
...     S = mu * tm.special.dev(tm.linalg.det(C)**(-1/3) * C) @ tm.linalg.inv(C)
...     return F @ S
>>>
>>> umat = fem.MaterialAD(neo_hooke, mu=1)
>>> ax = umat.plot(incompressible=True)

gradient(x)

Return the evaluated gradient of the strain energy density function.

Parameters:

x (list of ndarray) – The list with input arguments. These contain the extracted fields of a FieldContainer along with the old vector of state variables, [*field.extract(), statevars_old].

Returns:

A list with the evaluated gradient(s) of the strain energy density function and the updated vector of state variables.

Return type:

list of ndarray

hessian(x)

Return the evaluated upper-triangle components of the hessian(s) of the strain energy density function.

Parameters:

x (list of ndarray) – The list with input arguments. These contain the extracted fields of a FieldContainer along with the old vector of state variables, [*field.extract(), statevars_old].

Returns:

A list with the evaluated upper-triangle components of the hessian(s) of the strain energy density function.

Return type:

list of ndarray

optimize(ux=None, ps=None, bx=None, incompressible=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).

• **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.

Examples

The Ogden material model formulation is fitted on Treloar’s uniaxial tension data [1]_.

>>> import numpy as np
>>> import felupe as fem
>>>
>>> stretches, stresses = np.array(
...     [
...         [1.000, 0.00],
...         [1.020, 0.26],
...         [1.125, 1.37],
...         [1.240, 2.30],
...         [1.390, 3.23],
...         [1.585, 4.16],
...         [1.900, 5.10],
...         [2.180, 6.00],
...         [2.420, 6.90],
...         [3.020, 8.80],
...         [3.570, 10.7],
...         [4.030, 12.5],
...         [4.760, 16.2],
...         [5.360, 19.9],
...         [5.750, 23.6],
...         [6.150, 27.4],
...         [6.400, 31.0],
...         [6.600, 34.8],
...         [6.850, 38.5],
...         [7.050, 42.1],
...         [7.150, 45.8],
...         [7.250, 49.6],
...         [7.400, 53.3],
...         [7.500, 57.0],
...         [7.600, 64.4],
...     ]
... ).T * np.array([[1.0], [0.0980665]])
>>>
>>> umat = fem.Hyperelastic(fem.ogden)
>>> umat_new, res = umat.optimize(ux=[stretches, stresses], incompressible=True)
>>>
>>> ux = np.linspace(stretches.min(), stretches.max(), num=200)
>>> ax = umat_new.plot(incompressible=True, ux=ux, bx=None, ps=None)

>>> ax.plot(stretches, stresses, "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.Hyperelastic(fun, nstatevars=0, parallel=False, **kwargs)

A hyperelastic material definition with a given function for the strain energy density function per unit undeformed volume with Automatic Differentiation provided by tensortrax.

Parameters:

• fun (callable) – A strain energy density function in terms of the right Cauchy-Green deformation tensor \(\boldsymbol{C}\). Function signature must be fun = lambda C, **kwargs: psi for functions without state variables and fun = lambda C, statevars, **kwargs: [psi, statevars_new] for functions with state variables. The right Cauchy-Green deformation tensor will be a tensortrax.Tensor when the function is evaluated. It is important to only use differentiable math-functions from tensortrax.math!

• nstatevars (int, optional) – Number of state variables (default is 0).

• parallel (bool, optional) – A flag to invoke threaded strain energy density function evaluations (default is False). May introduce additional overhead for small-sized problems.

• **kwargs (dict, optional) – Optional keyword-arguments for the strain energy density function.

Notes

The strain energy density function \(\psi\) must be given in terms of the right Cauchy-Green deformation tensor \(\boldsymbol{C} = \boldsymbol{F}^T \boldsymbol{F}\).

Warning

It is important to only use differentiable math-functions from tensortrax.math!

Take this minimal code-block as template

\[\psi = \psi(\boldsymbol{C})\]

import tensortrax.math as tm

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

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

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

\[\psi = \psi(\boldsymbol{C}, \boldsymbol{\zeta})\]

import tensortrax.math as tm

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

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

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

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

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

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

Note

See the documentation of tensortrax for further details.

Examples

View force-stretch curves on elementary incompressible deformations.

>>> import felupe as fem
>>> import tensortrax.math as tm
>>>
>>> def neo_hooke(C, mu):
...     "Strain energy function of the Neo-Hookean material formulation."
...     return mu / 2 * (tm.linalg.det(C) ** (-1/3) * tm.trace(C) - 3)
>>>
>>> umat = fem.Hyperelastic(neo_hooke, mu=1)
>>> ax = umat.plot(incompressible=True)

See also

saint_venant_kirchhoff

Strain energy function of the Saint Venant-Kirchhoff material formulation.

neo_hooke

Strain energy function of the Neo-Hookean material formulation.

mooney_rivlin

Strain energy function of the Mooney-Rivlin material formulation.

yeoh

“Strain energy function of the Yeoh material formulation.

third_order_deformation

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

ogden

Strain energy function of the Ogden material formulation.

arruda_boyce

Strain energy function of the Arruda-Boyce material formulation.

extended_tube

Strain energy function of the Extended-Tube material formulation.

van_der_waals

Strain energy function of the Van der Waals material formulation.

finite_strain_viscoelastic

Finite strain viscoelastic material formulation.

gradient(x)

Return the evaluated gradient of the strain energy density function.

Parameters:

x (list of ndarray) – The list with input arguments. These contain the extracted fields of a FieldContainer along with the old vector of state variables, [*field.extract(), statevars_old].

Returns:

A list with the evaluated gradient(s) of the strain energy density function and the updated vector of state variables.

Return type:

list of ndarray

hessian(x)

Return the evaluated upper-triangle components of the hessian(s) of the strain energy density function.

Parameters:

x (list of ndarray) – The list with input arguments. These contain the extracted fields of a FieldContainer along with the old vector of state variables, [*field.extract(), statevars_old].

Returns:

A list with the evaluated upper-triangle components of the hessian(s) of the strain energy density function.

Return type:

list of ndarray

optimize(ux=None, ps=None, bx=None, incompressible=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).

• **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.

Examples

The Ogden material model formulation is fitted on Treloar’s uniaxial tension data [1]_.

>>> import numpy as np
>>> import felupe as fem
>>>
>>> stretches, stresses = np.array(
...     [
...         [1.000, 0.00],
...         [1.020, 0.26],
...         [1.125, 1.37],
...         [1.240, 2.30],
...         [1.390, 3.23],
...         [1.585, 4.16],
...         [1.900, 5.10],
...         [2.180, 6.00],
...         [2.420, 6.90],
...         [3.020, 8.80],
...         [3.570, 10.7],
...         [4.030, 12.5],
...         [4.760, 16.2],
...         [5.360, 19.9],
...         [5.750, 23.6],
...         [6.150, 27.4],
...         [6.400, 31.0],
...         [6.600, 34.8],
...         [6.850, 38.5],
...         [7.050, 42.1],
...         [7.150, 45.8],
...         [7.250, 49.6],
...         [7.400, 53.3],
...         [7.500, 57.0],
...         [7.600, 64.4],
...     ]
... ).T * np.array([[1.0], [0.0980665]])
>>>
>>> umat = fem.Hyperelastic(fem.ogden)
>>> umat_new, res = umat.optimize(ux=[stretches, stresses], incompressible=True)
>>>
>>> ux = np.linspace(stretches.min(), stretches.max(), num=200)
>>> ax = umat_new.plot(incompressible=True, ux=ux, bx=None, ps=None)

>>> ax.plot(stretches, stresses, "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.saint_venant_kirchhoff(C, mu, lmbda)

Strain energy function of the isotropic hyperelastic Saint-Venant Kirchhoff material formulation.

Parameters:

• C (tensortrax.Tensor) – Right Cauchy-Green deformation tensor.

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

• lmbda (float) – First Lamé constant (shear modulus).

Notes

\[\psi = \mu I_2 + \lambda \frac{I_1^2}{2}\]

With the first and second invariant of the Green-Lagrange strain tensor \(\boldsymbol{E} = \frac{1}{2} (\boldsymbol{C} - \boldsymbol{1})\).

\[ \begin{align}\begin{aligned}I_1 &= \text{tr}\left( \boldsymbol{E} \right)\\I_2 &= \boldsymbol{E} : \boldsymbol{E}\end{aligned}\end{align} \]

Examples

Warning

The Saint-Venant Kirchhoff material formulation is unstable for large strains.

>>> import felupe as fem
>>>
>>> umat = fem.Hyperelastic(fem.saint_venant_kirchhoff, mu=1.0, lmbda=20.0)
>>> ax = umat.plot(incompressible=False)

felupe.neo_hooke(C, mu)

Strain energy function of the isotropic hyperelastic Neo-Hookean material formulation.

Parameters:

• C (tensortrax.Tensor) – Right Cauchy-Green deformation tensor.

• mu (float) – Shear modulus.

Notes

\[\psi = \frac{\mu}{2} \left(\text{tr}\left(\hat{\boldsymbol{C}}\right) - 3\right)\]

Examples

>>> import felupe as fem
>>>
>>> umat = fem.Hyperelastic(fem.neo_hooke, mu=1.0)
>>> ax = umat.plot(incompressible=True)

felupe.mooney_rivlin(C, C10, C01)

Strain energy function of the isotropic hyperelastic Mooney-Rivlin material formulation.

Parameters:

• C (tensortrax.Tensor) – Right Cauchy-Green deformation tensor.

• C10 (float) – First material parameter associated to the first invariant.

• C01 (float) – Second material parameter associated to the second invariant.

Notes

\[\psi = C_{10} \left(\hat{I}_1 - 3 \right) + C_{01} \left(\hat{I}_2 - 3 \right)\]

With the first and second main invariant of the distortional part of the right Cauchy-Green deformation tensor.

\[ \begin{align}\begin{aligned}\hat{I}_1 &= J^{-2/3} \text{tr}\left( \boldsymbol{C} \right)\\\hat{I}_2 &= J^{-4/3} \frac{1}{2} \left( \text{tr}\left(\boldsymbol{C}\right)^2 - \text{tr}\left(\boldsymbol{C}^2\right) \right)\end{aligned}\end{align} \]

The doubled sum of both material parameters is equal to the shear modulus \(\mu\).

\[\mu = 2 \left( C_{10} + C_{01} \right)\]

Examples

>>> import felupe as fem
>>>
>>> umat = fem.Hyperelastic(fem.mooney_rivlin, C10=0.3, C01=0.8)
>>> ax = umat.plot(incompressible=True)

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

Strain energy function of the isotropic hyperelastic Yeoh material formulation.

Parameters:

• C (tensortrax.Tensor) – Right Cauchy-Green deformation tensor.

• C10 (float) – Material parameter associated to the linear term of the first invariant.

• C20 (float) – Material parameter associated to the quadratic term of the first invariant.

• C30 (float) – Material parameter associated to the cubic term of the first invariant.

Notes

\[\psi = C_{10} \left(\hat{I}_1 - 3 \right) + C_{20} \left(\hat{I}_1 - 3 \right)^2 + C_{30} \left(\hat{I}_1 - 3 \right)^3\]

With the first main invariant of the distortional part of the right Cauchy-Green deformation tensor.

\[\hat{I}_1 = J^{-2/3} \text{tr}\left( \boldsymbol{C} \right)\]

The \(C_{10}\) material parameter is equal to half the initial shear modulus \(\mu\).

\[\mu = 2 C_{10}\]

Examples

>>> import felupe as fem
>>>
>>> umat = fem.Hyperelastic(fem.yeoh, C10=0.5, C20=-0.1, C30=0.02)
>>> ax = umat.plot(incompressible=True)

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

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

Parameters:

• C (tensortrax.Tensor) – Right Cauchy-Green deformation tensor.

• C10 (float) – Material parameter associated to the linear term of the first invariant.

• C01 (float) – Material parameter associated to the linear term of the second invariant.

• C11 (float) – Material parameter associated to the mixed term of the first and second invariant.

• C20 (float) – Material parameter associated to the quadratic term of the first invariant.

• C30 (float) – Material parameter associated to the cubic term of the first invariant.

Notes

\[ \begin{align}\begin{aligned}\psi &= C_{10} \left(\hat{I}_1 - 3 \right) + C_{01} \left(\hat{I}_2 - 3 \right) + C_{11} \left(\hat{I}_1 - 3 \right) \left(\hat{I}_2 - 3 \right)\\ &+ C_{20} \left(\hat{I}_1 - 3 \right)^2 + C_{30} \left(\hat{I}_1 - 3 \right)^3\end{aligned}\end{align} \]

With the first and second main invariant of the distortional part of the right Cauchy-Green deformation tensor.

\[ \begin{align}\begin{aligned}\hat{I}_1 &= J^{-2/3} \text{tr}\left( \boldsymbol{C} \right)\\\hat{I}_2 &= J^{-4/3} \frac{1}{2} \left( \text{tr}\left(\boldsymbol{C}\right)^2 - \text{tr}\left(\boldsymbol{C}^2\right) \right)\end{aligned}\end{align} \]

The doubled sum of the material parameters \(C_{10}\) and \(C_{01}\) is equal to the initial shear modulus \(\mu\).

\[\mu = 2 \left( C_{10} + C_{01} \right)\]

Examples

>>> import felupe as fem
>>>
>>> umat = fem.Hyperelastic(
...     fem.third_order_deformation, C10=0.5, C01=0.1, C11=0.01, C20=-0.1, C30=0.02
... )
>>> ax = umat.plot(incompressible=True)

felupe.ogden(C, mu, alpha)

Strain energy function of the isotropic hyperelastic Ogden material formulation.

Parameters:

• C (tensortrax.Tensor) – Right Cauchy-Green deformation tensor.

• mu (list of float) – List of moduli.

• alpha (list of float) – List of stretch exponents.

Notes

\[\psi = \sum_i \frac{2 \mu_i}{\alpha^2_i} \left( \lambda_1^{\alpha_i} + \lambda_2^{\alpha_i} + \lambda_3^{\alpha_i} - 3 \right)\]

The sum of the moduli \(\mu_i\) is equal to the initial shear modulus \(\mu\).

\[\mu = \sum_i \mu_i\]

Examples

>>> import felupe as fem
>>>
>>> umat = fem.Hyperelastic(fem.ogden, mu=[1, 0.2], alpha=[1.7, -1.5])
>>> ax = umat.plot(incompressible=True)

felupe.arruda_boyce(C, C1, limit)

Strain energy function of the isotropic hyperelastic Arruda-Boyce material formulation.

Parameters:

• C (tensortrax.Tensor) – Right Cauchy-Green deformation tensor.

• C1 (float) – Initial shear modulus.

• limit (float) – Limiting stretch \(\lambda_m\) at which the polymer chain network becomes locked.

Notes

\[\psi = C_1 \sum_{i=1}^5 \alpha_i \beta^{i-1} \left( \hat{I}_1^i - 3^i \right)\]

With the first main invariant of the distortional part of the right Cauchy-Green deformation tensor

\[\hat{I}_1 = J^{-2/3} \text{tr}\left( \boldsymbol{C} \right)\]

and \(\alpha_i\) and \(\beta\).

\[ \begin{align}\begin{aligned}\begin{split}\boldsymbol{\alpha} &= \begin{bmatrix} \frac{1}{2} \\ \frac{1}{20} \\ \frac{11}{1050} \\ \frac{19}{7000} \\ \frac{519}{673750} \end{bmatrix}\end{split}\\\beta &= \frac{1}{\lambda_m^2}\end{aligned}\end{align} \]

The initial shear modulus is a function of both material parameters.

\[\mu = C_1 \left( 1 + \frac{3}{5 \lambda_m^2} + \frac{99}{175 \lambda_m^4} + \frac{513}{875 \lambda_m^6} + \frac{42039}{67375 \lambda_m^8} \right)\]

Examples

>>> import felupe as fem
>>>
>>> umat = fem.Hyperelastic(fem.arruda_boyce, C1=1.0, limit=3.2)
>>> ax = umat.plot(incompressible=True)

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

Strain energy function of the isotropic hyperelastic Extended Tube [1]_ material formulation.

Parameters:

• C (tensortrax.Tensor) – Right Cauchy-Green deformation tensor.

• Gc (float) – Cross-link contribution to the initial shear modulus.

• delta (float) – Finite extension parameter of the polymer strands.

• Ge (float) – Constraint contribution to the initial shear modulus.

• beta (float) – Global rearrangements of cross-links upon deformation (release of topological constraints).

Notes

\[\psi = \frac{G_c}{2} \left[ \frac{\left( 1 - \delta^2 \right) \left( \hat{I}_1 - 3 \right)}{1 - \delta^2 \left( \hat{I}_1 - 3 \right)} + \ln \left( 1 - \delta^2 \left( \hat{I}_1 - 3 \right) \right) \right] + \frac{2 G_e}{\beta^2} \left( \hat{\lambda}_1^{-\beta} + \hat{\lambda}_2^{-\beta} + \hat{\lambda}_3^{-\beta} - 3 \right)\]

With the first main invariant of the distortional part of the right Cauchy-Green deformation tensor

\[\hat{I}_1 = J^{-2/3} \text{tr}\left( \boldsymbol{C} \right)\]

and the principal stretches, obtained from the distortional part of the right Cauchy-Green deformation tensor

\[\hat{\lambda}_\alpha = J^{-1/3} \lambda_\alpha\]

The initial shear modulus results from the sum of the cross-link and the constraint contributions to the total initial shear modulus.

\[\mu = G_e + G_c\]

Examples

>>> import felupe as fem
>>>
>>> umat = fem.Hyperelastic(
...     fem.extended_tube, Gc=0.1867, Ge=0.2169, beta=0.2, delta=0.09693
... )
>>> ax = umat.plot(incompressible=True)

References

[1]

M. Kaliske and G. Heinrich, “An Extended Tube-Model for Rubber Elasticity: Statistical-Mechanical Theory and Finite Element Implementation”, Rubber Chemistry and Technology, vol. 72, no. 4. Rubber Division, ACS, pp. 602–632, Sep. 01, 1999. doi: 10.5254/1.3538822.

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

Strain energy function of the Van der Waals [1]_ material formulation.,

Parameters:

• C (tensortrax.Tensor) – Right Cauchy-Green deformation tensor.

• mu (float) – Initial shear modulus.

• limit (float) – Limiting stretch \(\lambda_m\) at which the polymer chain network becomes locked.

• a (float) – Attractive interactions between the quasi-particles.

• beta (float) – Mixed-Invariant factor: 0 for pure I1- and 1 for pure I2-contribution.

Examples

>>> import felupe as fem
>>>
>>> umat = fem.Hyperelastic(fem.van_der_waals, mu=1.0, beta=0.1, a=0.5, limit=5.0)
>>> ax = umat.plot(incompressible=True)

References

[1]

H.-G. Kilian, “Equation of state of real networks”, Polymer, vol. 22, no. 2. Elsevier BV, pp. 209–217, Feb. 1981. doi: 10.1016/0032-3861(81)90200-7.

felupe.finite_strain_viscoelastic(C, Cin, mu, eta, dtime)

Multiplicative finite strain viscoelastic [1]_ material formulation.

Examples

>>> import felupe as fem
>>>
>>> umat = fem.Hyperelastic(
...     fem.finite_strain_viscoelastic, mu=1.0, eta=1.0, dtime=1.0, nstatevars=6
... )
>>> ax = umat.plot(
...    incompressible=True,
...    ux=fem.math.linsteps([1, 1.5, 1, 2, 1, 2.5, 1], num=15),
...    ps=None,
...    bx=None,
... )

References

[1]

A. V. Shutov, R. Landgraf, and J. Ihlemann, “An explicit solution for implicit time stepping in multiplicative finite strain viscoelasticity”, Computer Methods in Applied Mechanics and Engineering, vol. 265. Elsevier BV, pp. 213–225, Oct. 2013. doi: 10.1016/j.cma.2013.07.004.

class felupe.LineChange(parallel=False)

Line Change.

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

Gradient:

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

function(extract)

Line change.

Parameters:

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

Returns:

F – Deformation gradient

Return type:

ndarray

gradient(extract, parallel=None)

Gradient of line change.

Parameters:

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

Returns:

Gradient of line change

Return type:

ndarray

class felupe.AreaChange(parallel=False)

Area Change.

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

Gradient:

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

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

Area change.

Parameters:

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

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

Returns:

Cofactor matrix of the deformation gradient

Return type:

ndarray

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

Gradient of area change.

Parameters:

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

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

Returns:

Gradient of cofactor matrix of the deformation gradient

Return type:

ndarray

class felupe.VolumeChange(parallel=False)

Volume Change.

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

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

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

function(extract)

Gradient of volume change.

Parameters:

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

Returns:

J – Determinant of the deformation gradient

Return type:

ndarray

gradient(extract)

Gradient of volume change.

Parameters:

F (ndarray) – Deformation gradient

Returns:

Gradient of the determinant of the deformation gradient

Return type:

ndarray

hessian(extract, parallel=None)

Hessian of volume change.

Parameters:

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

Returns:

Hessian of the determinant of the deformation gradient

Return type:

ndarray

felupe.constitution.lame_converter(E, nu)

Convert the pair of given material parameters Young’s modulus \(E\) and Poisson ratio \(\nu\) to first and second Lamé - constants \(\lambda\) and \(\mu\).

Notes

\[ \begin{align}\begin{aligned}\lambda &= \frac{E \nu}{(1 + \nu) (1 - 2 \nu)}\\\mu &= \frac{E}{2 (1 + \nu)}\end{aligned}\end{align} \]

Parameters:

• E (float) – Young’s modulus.

• nu (float) – Poisson ratio.

Returns:

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

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