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.
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.
Convert the pair of given material parameters Young's modulus \(E\) and Poisson ratio \(\nu\) to first and second Lamé - constants \(\lambda\) and \(\mu\).
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). The (absolute) times are required as second
row for a time-dependent material, e.g. [stretches,times].
ps (ndarray, optional) – Array with stretches for planar shear. Default is
linsteps([1.0,2.5],num=30). The (absolute) times are required as second
row for a time-dependent material, e.g. [stretches,times].
bx (ndarray, optional) – Array with stretches for equi-biaxial tension. Default is
linsteps([1.0,1.75],num=15)`. The (absolute) times are required as second
row for a time-dependent material, e.g. [stretches,times].
statevars (ndarray or None, optional) – Array with state variables (default is None). If None, the state variables are
assumed to be initially zero.
Notes
The load cases of a time-dependent material, i.e. a material with an attribute
time_dependent which is True, include the (absolute) times of the stretches,
e.g. ux=[stretches,times]. The time increments are the differences of the
times, with the initial time zero (like a TimeStep), and they are
passed to the material for each increment of a load case. Each load case starts at
the initial time with the initial state variables. Holding times are given by
repeated stretches.
The load case of a time-dependent material includes the times, e.g. a loading with
a holding time at the maximum stretch and an unloading with a lower stretch rate.
Normal force per undeformed area vs stretch curve for a equi-biaxial
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.
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.
Normal force per undeformed area vs stretch curve for a planar shear
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.
Plot normal force per undeformed area vs stretch curves for the elementary
homogeneous incompressible deformations uniaxial tension/compression, planar
shear and biaxial tension.
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.
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). The (absolute) times are required as second
row for a time-dependent material, e.g. [stretches,times].
ps (ndarray, optional) – Array with stretches for incompressible planar shear. Default is
linsteps([1,2.5],num=30). The (absolute) times are required as second
row for a time-dependent material, e.g. [stretches,times].
bx (ndarray, optional) – Array with stretches for incompressible equi-biaxial tension. Default is
linsteps([1,1.75],num=15). The (absolute) times are required as second
row for a time-dependent material, e.g. [stretches,times].
statevars (ndarray or None, optional) – Array with state variables (default is None). If None, the state variables are
assumed to be initially zero.
Notes
The load cases of a time-dependent material, i.e. a material with an attribute
time_dependent which is True, include the (absolute) times of the stretches,
e.g. ux=[stretches,times]. The time increments are the differences of the
times, with the initial time zero (like a TimeStep), and they are
passed to the material for each increment of a load case. Each load case starts at
the initial time with the initial state variables. Holding times are given by
repeated stretches.
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.
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.
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.
Plot normal force per undeformed area vs stretch curves for the elementary
homogeneous incompressible deformations uniaxial tension/compression, planar
shear and biaxial tension.
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.
The state variables of the composite material are the flattened state variables of
the first material, followed by the flattened state variables of the second
material, i.e. the size of the state variables is the sum of the sizes of the state
variables of both materials. The state variables are split for the evaluation of the
materials and the updated state variables of both materials are concatenated again.
Hence, the order of the materials doesn’t matter, e.g. nh&viscoelastic and
viscoelastic&nh are equal, and several materials with state variables are
supported, also nested composite materials like a&b&c. If the state
variables are not given (None) or if the input list contains only one array, the
input list is passed to both materials and the state variables of the first
material are returned.
The gradients and the hessians are evaluated in chunks of cells, by a pool of
threads if any of the materials is parallel.
The composite material is time-dependent if any of the materials is time-dependent
(attribute time_dependent). The time increment dtime is only passed to the
time-dependent materials, e.g. viscoelastic&fem.Volumetric(bulk=5000).
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.
Return the evaluated gradient(s) of the strain energy density function,
evaluated by _gradient(x,*args,**kwargs) in chunks of cells.
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].
*args (tuple, optional) – Optional arguments for _gradient().
out (ndarray or None, optional) – A location into which the first gradient is stored (default is None).
**kwargs (dict, optional) – Optional keyword-arguments for _gradient(), e.g. the time increment
dtime of a time-dependent material.
Returns:
A list with the evaluated gradient(s) of the strain energy density function
and the updated vector of state variables.
Return the evaluated upper-triangle components of the hessian(s) of the
strain energy density function, evaluated by _hessian(x,*args,**kwargs)
in chunks of cells.
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].
*args (tuple, optional) – Optional arguments for _hessian().
out (ndarray or None, optional) – A location into which the first hessian is stored (default is None).
**kwargs (dict, optional) – Optional keyword-arguments for _hessian(), e.g. the time increment
dtime of a time-dependent material.
Returns:
A list with the evaluated upper-triangle components of the hessian(s) of the
strain energy density function.
Return a boolean mask for stability of isotropic material model formulations.
At a given deformation gradient, a normal force is applied on each principal
stretch direction. If the resulting incremental stretches are positive, the
material model formulation is considered to be stable at the given deformation
gradient.
Parameters:
x (list of ndarray) – The list with input arguments. These contain the extracted fields of a
FieldContainer.
hessian (ndarray or None, optional) – Second partial derivative of the strain energy density function w.r.t. the
deformation gradient. Default is None.
Returns:
Boolean mask of stability.
Return type:
ndarray
Notes
Warning
This stability check will lead to a singular matrix for isotropic
(hyperelastic) material model formulations without a volumetric part.
Examples
First, let’s check the stability of the Neo-Hookean material model formulation.
The stability is evaluated on (valid) principal stretches of a biaxial
deformation. All deformations are stable.
Now, let’s check the stability of the Mooney-Rivlin material model formulation.
The stability is evaluated on (valid) principal stretches of a biaxial
deformation. Biaxial deformations are only stable up to a longitudinal stretch
of 1.35.
Optimize the material parameters by a least-squares fit on experimental
stretch-stress data.
Parameters:
ux (array of shape (2, ...) or (3, ...) or None, optional) – Experimental uniaxial stretch and force-per-undeformed-area data (default is
None). The (absolute) times are required as third row for a time-dependent
material.
ps (array of shape (2, ...) or (3, ...) or None, optional) – Experimental planar-shear stretch and force-per-undeformed-area data
(default is None). The (absolute) times are required as third row for a
time-dependent material.
bx (array of shape (2, ...) or (3, ...) or None, optional) – Experimental biaxial stretch and force-per-undeformed-area data (default is
None). The (absolute) times are required as third row for a time-dependent
material.
incompressible (bool, optional) – A flag to enforce incompressible deformations (default is False).
relative (bool, optional) – A flag to optimize relative instead of absolute residuals, i.e.
(predicted-observed)/observed instead of predicted-observed
(default is False).
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.
Note
For JAX-based materials, double-precision is required to optimize material
parameters.
The material parameters are the keyword-arguments of the material. They are
set on a copy of the material, i.e. its keyword-arguments and its attributes
with the same names, as well as the material parameters of its materials, e.g.
of a composite material. The time increment is not a material parameter, i.e. a
constant time increment dtime of the keyword-arguments is not optimized. The
experimental data of a time-dependent material includes the (absolute) times
of the data points, e.g. ux=[stretches,forces,times], which are taken for
the time increments of the load case, see ViewMaterial.
importjaxjax.config.update("jax_enable_x64",True)
The vector of residuals is given in Eq. (3) in
case of absolute residuals
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).
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.
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.
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).
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.
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.
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, e.g. the load cases. The load
cases of a time-dependent material include the (absolute) times, e.g.
ux=[stretches,times].
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.
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.
Neo-Hookean material formulation with deactivated shear modulus, i.e. the
volumetric part of the strain energy density function \(U(J)\) only.
Parameters:
bulk (float or None, optional) – Bulk modulus of the volumetric part of the strain energy density function. It is
required if volumetric is a kind and it must be None if volumetric is an
instance, which holds its own parameters (default is None).
parallel (bool, optional) – A flag to evaluate the gradient and the hessian in chunks of cells by a pool of
threads (default is False).
volumetric (str or VolumetricStrainEnergy, optional) – The volumetric part of the strain energy density function \(U(J)\), given by
a kind with the bulk modulus, "volume-ratio", "stretch" or "log", or
by an instance of VolumetricStrainEnergy, e.g. of a custom
subclass. Default is "volume-ratio".
Examples
The volumetric part is combined with a material formulation for the distortional
part of the strain energy density function.
Return the evaluated gradient(s) of the strain energy density function,
evaluated by _gradient(x,*args,**kwargs) in chunks of cells.
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].
*args (tuple, optional) – Optional arguments for _gradient().
out (ndarray or None, optional) – A location into which the first gradient is stored (default is None).
**kwargs (dict, optional) – Optional keyword-arguments for _gradient(), e.g. the time increment
dtime of a time-dependent material.
Returns:
A list with the evaluated gradient(s) of the strain energy density function
and the updated vector of state variables.
Return the evaluated upper-triangle components of the hessian(s) of the
strain energy density function, evaluated by _hessian(x,*args,**kwargs)
in chunks of cells.
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].
*args (tuple, optional) – Optional arguments for _hessian().
out (ndarray or None, optional) – A location into which the first hessian is stored (default is None).
**kwargs (dict, optional) – Optional keyword-arguments for _hessian(), e.g. the time increment
dtime of a time-dependent material.
Returns:
A list with the evaluated upper-triangle components of the hessian(s) of the
strain energy density function.
Return a boolean mask for stability of isotropic material model formulations.
At a given deformation gradient, a normal force is applied on each principal
stretch direction. If the resulting incremental stretches are positive, the
material model formulation is considered to be stable at the given deformation
gradient.
Parameters:
x (list of ndarray) – The list with input arguments. These contain the extracted fields of a
FieldContainer.
hessian (ndarray or None, optional) – Second partial derivative of the strain energy density function w.r.t. the
deformation gradient. Default is None.
Returns:
Boolean mask of stability.
Return type:
ndarray
Notes
Warning
This stability check will lead to a singular matrix for isotropic
(hyperelastic) material model formulations without a volumetric part.
Examples
First, let’s check the stability of the Neo-Hookean material model formulation.
The stability is evaluated on (valid) principal stretches of a biaxial
deformation. All deformations are stable.
Now, let’s check the stability of the Mooney-Rivlin material model formulation.
The stability is evaluated on (valid) principal stretches of a biaxial
deformation. Biaxial deformations are only stable up to a longitudinal stretch
of 1.35.
Optimize the material parameters by a least-squares fit on experimental
stretch-stress data.
Parameters:
ux (array of shape (2, ...) or (3, ...) or None, optional) – Experimental uniaxial stretch and force-per-undeformed-area data (default is
None). The (absolute) times are required as third row for a time-dependent
material.
ps (array of shape (2, ...) or (3, ...) or None, optional) – Experimental planar-shear stretch and force-per-undeformed-area data
(default is None). The (absolute) times are required as third row for a
time-dependent material.
bx (array of shape (2, ...) or (3, ...) or None, optional) – Experimental biaxial stretch and force-per-undeformed-area data (default is
None). The (absolute) times are required as third row for a time-dependent
material.
incompressible (bool, optional) – A flag to enforce incompressible deformations (default is False).
relative (bool, optional) – A flag to optimize relative instead of absolute residuals, i.e.
(predicted-observed)/observed instead of predicted-observed
(default is False).
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.
Note
For JAX-based materials, double-precision is required to optimize material
parameters.
The material parameters are the keyword-arguments of the material. They are
set on a copy of the material, i.e. its keyword-arguments and its attributes
with the same names, as well as the material parameters of its materials, e.g.
of a composite material. The time increment is not a material parameter, i.e. a
constant time increment dtime of the keyword-arguments is not optimized. The
experimental data of a time-dependent material includes the (absolute) times
of the data points, e.g. ux=[stretches,forces,times], which are taken for
the time increments of the load case, see ViewMaterial.
importjaxjax.config.update("jax_enable_x64",True)
The vector of residuals is given in Eq. (3) in
case of absolute residuals
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).
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.
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.
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).
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.
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.
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, e.g. the load cases. The load
cases of a time-dependent material include the (absolute) times, e.g.
ux=[stretches,times].
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.
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.
The volumetric part of the strain energy density function, see
VolumetricStrainEnergy. For a kind, it is created with the
current bulk modulus and it is None without a bulk modulus.
The volumetric part of the strain energy density function as a function of the
volume ratio, \(U(J)\), with its first and second derivatives w.r.t. the volume
ratio.
kind (str, optional) – The kind of the volumetric part of the strain energy density function:
"volume-ratio" for \(U(J)=K(J-1)^2/2\), "stretch" for
\(U(J)=9K(J^{1/3}-1)^2/2\) or "log" for \(U(J)=K\ln(J)^2/2\), see
Eq. (5). Default is "volume-ratio".
Notes
Unlike a ConstitutiveMaterial, which is evaluated by the
deformation gradient, it is evaluated by the volume ratio
\(J=\det(\boldsymbol{F})\). An instance U is callable, i.e. U(J)
returns \(U(J)\), U.dUdJ(J) returns \(U'(J)\) and U.d2UdJdJ(J)
returns \(U''(J)\). The
derivatives w.r.t. the deformation gradient are obtained by the chain rule with the
derivatives of the volume ratio, see VolumeChange.
The kinds are quadratic in the Seth-Hill strain \(E_m = (\lambda^m - 1) / m\)
of order \(m\) of the volumetric stretch \(\lambda = J^{1/3}\), see Eq.
(5), with \(m=3\) for "volume-ratio",
\(m=1\) for "stretch" and the limit \(m \rightarrow 0\) for "log".
For all kinds, the second derivative at the undeformed configuration is the bulk
modulus, \(U''(1)=K\). The volumetric part and its first and second derivatives
are given in Eq. (6) for
kind="volume-ratio" (default),
The kinds are evaluated by these expressions of the volume ratio, i.e. not by the
general form, which is singular for \(m=0\). The cubic root of the kind
"stretch" is evaluated by numpy.cbrt(), which is real-valued also for
negative (linearized) volume ratios. The smaller the order \(m\), the stiffer is
the volumetric response in compression and the softer in tension. The first
derivative \(U'(J)\), i.e. the hydrostatic part of the Cauchy stress, is
unbounded for \(J \rightarrow 0\) for the kinds "stretch" and "log". In
tension, it is bounded by \(3K/4\) at \(J=8\) and by \(K/e\) at
\(J=e\) for these kinds, where their second derivatives change their sign.
A custom volumetric part of the strain energy density function is a subclass which
implements the methods __call__(J), dUdJ(J) and d2UdJdJ(J). The
undeformed configuration is free of stress only if \(U'(1)=0\), and a positive
second derivative \(U''(J)>0\) is required for a stable volumetric response.
The volumetric part of the strain energy density function is passed by the argument
volumetric to NeoHooke, Volumetric,
NearlyIncompressible and
SolidBodyNearlyIncompressible, either as a kind together with the
bulk modulus or as an instance (then, without the bulk modulus).
A nearly-incompressible material formulation to augment the distortional part of the strain energy function by a volumetric part and a constraint equation.
Convert the pair of given material parameters Young’s modulus \(E\) and
Poisson ratio \(\nu\) to first and second Lamé - constants \(\lambda\) and
\(\mu\).
Convert elastic orthotropic material parameters to Lamé constants.
Parameters:
E (list of float) – List of the three elastic moduli \(E_1, E_2, E_3\).
nu (list of float) – List of three poisson ratios \(\nu_{12}, \nu_{23}, \nu_{31}\).
G (list of float) – List of three shear moduli \(G_{12}, G_{23}, G_{31}\).
Returns:
lmbda (list of float) – List of six (upper triangle) first Lamé parameters \(\lambda_{11},
\lambda_{12}, \lambda_{13}, \lambda_{22}, \lambda_{23}, \lambda_{33}\).
mu (list of float) – List of the three second Lamé parameters \(\mu_1,\mu_2, \mu_3\).
Notes
The orthotropic material parameters are converted to orthotropic Lamé
constants.
The compliance matrix as the inverse of the stiffness matrix with the
parameters \(E_i\), \(\nu_{ij}\) and \(G_{ij}\) is given in
Eq. (10).