hyperelastic.hpp

Overview 

Functions for hyperelastic material models, including strain energy derivatives, stress computations, and tangent moduli for various hyperelastic models (Neo-Hookean, Mooney-Rivlin, Ogden, etc.). Supports both invariant-based and principal stretch-based formulations.

API Reference 

enum class HyperPotential

Isochoric-invariant potentials of hyper_potential_derivatives.

Shared by the standalone UMAT (umat_generic_hyper_invariants, which maps its 5-letter names onto these values) and by the modular composition, which stores the value in its props: adding a potential here serves both.

Values:

enumerator NEOHC: compressible neo-Hookean, props [mu, kappa]

enumerator MOORI: Mooney-Rivlin, props [C10, C01, kappa].

enumerator YEOHH: Yeoh, props [C10, C20, C30, kappa].

enumerator ISHAH: Isihara, props [C10, C20, C01, kappa].

enumerator GETHH: Gent-Thomas, props [c1, c2, kappa].

enumerator SWANH: Swanson, props [N, kappa, (A, B, alpha, beta) x N].

arma::vec isochoric_invariants(const arma::mat &b, const double &mJ = 0.)

Provides the isochoric strain invariants, from the left Cauchy-Green deformation tensor \(\mathbf{b}\) .

\[\begin{split} \begin{align} \bar{I}_1 = \textrm{tr} \bar{\mathbf{b}} \\ \bar{I}_2 = \frac{1}{2} \left( \left(\textrm{tr} \bar{\mathbf{b}} \right)^2 - \textrm{tr} \bar{\mathbf{b}}^2 \right) \\ \bar{I}_3 = \textrm{det} \bar{\mathbf{b}} = 1 \end{align} \end{split}\]

Example:

mat F = randu(3,3);
mat b = L_Cauchy_Green(F); 
double J = det(F);
vec I_bar = isochoric_invariants(b,J);

Parameters:

b – 3x3 matrix representing the left Cauchy-Green deformation tensor \(\mathbf{b}\)
mJ – the determinant of the transformation gradient \(\mathbf{F}\) (optional)

Returns:

a column vector of dimension 3 that contains the three isochoric invariants

arma::vec isochoric_invariants(const arma::vec &lambda, const double &mJ = 0.)

Provides the isochoric strain invariants, from the left Cauchy-Green principal stretches \( \lambda^2_1, \lambda^2_2 and \lambda^2_3\) Note that principal stretches \( \lambda_1, \lambda_2 and \lambda_3\) are the ones of the Eulerian stretch tensor \( \mathbf{v} \).

\[\begin{split} \begin{align} \bar{I}_1 = \bar{\lambda}_1^2 + \bar{\lambda}_2^2 + \bar{\lambda}_3^2 \\ \bar{I}_2 = \bar{\lambda}_1^{-2} + \bar{\lambda}_2^{-2} + \bar{\lambda}_3^{-2} \\ \bar{I}_3 = \bar{\lambda}_1^2 \bar{\lambda}_2^2 \bar{\lambda}_3^2 = 1 \end{align} \end{split}\]

where \( \bar{\lambda}_i = J^{-1/3} \lambda_i \) is the i-th isochoric principal stretch from a principal decomposition of the isochoric part of \(\mathbf{b}\).

Example:

mat F = randu(3,3);
mat b = L_Cauchy_Green(F); 
double J = det(F);
vec lambdas = eigen_sym(sqrtmat(b));
vec I_bar = isochoric_invariants(lambdas,J);

Parameters:

lambda – a column vector of dimension 3 that contains the three principal stretches \( \lambda_1 \), \( \lambda_2 \) and \( \lambda_3 \) of the Eulerian stretch tensor \( \mathbf{v} \).
mJ – the determinant of the transformation gradient \(\mathbf{F}\) (optional)

Returns:

a column vector of dimension 3 that contains the three isochoric invariants

arma::vec isochoric_pstretch_from_V(const arma::mat &V, const double &mJ = 0.)

Provides the isochoric principal stretches \( \bar{\lambda}^2_1, \bar{\lambda}^2_2 and \bar{\lambda}^2_3\) , from the eulerian stretch tensor \( \mathbf{v} \).

\( \lambda_1, \lambda_2 \) and \( \lambda_3 \) are the principal stretches of the Eulerian stretch tensor \( \mathbf{v} \) and:

\[ \bar{\lambda}_i = J^{-1/3} \lambda_i \]

Example:

mat F = randu(3,3);
mat V = zeros(3,3);
mat R = zeros(3,3); 
VR_decomposition(V, R, F);
double J = det(F);
vec lambdas_bar = isochoric_pstretch_from_V(V,J);

Parameters:

V – 3x3 matrix representing the Eulerian stretch tensor \( \mathbf{v} \).
mJ – the determinant of the transformation gradient \(\mathbf{F}\) (optional)

Returns:

a column vector of dimension 3 that contains the three isochoric principal stretches

arma::vec isochoric_pstretch_from_b(const arma::mat &b, const double &mJ = 0.)

Provides the isochoric principal stretches \( \bar{\lambda}^2_1, \bar{\lambda}^2_2 and \bar{\lambda}^2_3\) , from the from the left Cauchy-Green tensor \( \mathbf{b} \).

\( \lambda^2_1, \lambda^2_2 \) and \( \lambda^2_3 \) are the principal components of the left Cauchy-Green tensor \( \mathbf{b} \) and:

\[ \bar{\lambda}_i = J^{-1/3} \lambda_i \]

Example:

mat F = randu(3,3);
mat b = L_Cauchy_Green(F); 
double J = det(F);
vec lambdas_bar = isochoric_pstretch_from_b(b,J);

Parameters:

b – 3x3 matrix representing the left Cauchy-Green tensor \( \mathbf{b} \).
mJ – the determinant of the transformation gradient \(\mathbf{F}\) (optional)

Returns:

a column vector of dimension 3 that contains the three isochoric principal stretches

arma::vec isochoric_pstretch(const arma::mat &input, const std::string &input_tensor, const double &mJ = 0.)

Provides the isochoric principal stretches \( \bar{\lambda}^2_1, \bar{\lambda}^2_2 and \bar{\lambda}^2_3\) , from either the left Cauchy-Green tensor \( \mathbf{b} \) or the the eulerian stretch tensor \( \mathbf{v} \).

Example:

mat F = randu(3,3);
mat b = L_Cauchy_Green(F); 
double J = det(F);
vec lambdas_bar = isochoric_pstretch(b, "b", J);

Parameters:

input – 3x3 matrix representing the left Cauchy-Green tensor \( \mathbf{b} \) or the eulerian stretch tensor \( \mathbf{v} \).
input_tensor – a string (“b” for the left Cauchy-Green tensor or “V” for the eulerian stretch tensor ) representing the selected input
mJ – the determinant of the transformation gradient \(\mathbf{F}\) (optional)

Returns:

a column vector of dimension 3 that contains the three isochoric principal stretches

void pstretch(arma::vec &lambda, arma::mat &n_pvector, const arma::mat &input, const std::string &input_tensor, const double &mJ = 0.)

Principal stretches \( \lambda^2_1, \lambda^2_2 \) and \( \lambda^2_3\) and principal directions, from either the left Cauchy-Green tensor \( \mathbf{b} \) or the the eulerian stretch tensor \( \mathbf{v} \).

Example:

mat F = randu(3,3);
mat b = L_Cauchy_Green(F); 
double J = det(F);
vec lambdas;
mat n;
pstretch(lambdas, n, b, "b", J);

Parameters:

lambda – a column vector of dimension 3 that will contain the three principal stretches
n_pvector – a 3x3 matrix, where each column is a principal direction vector.
input – 3x3 matrix representing the left Cauchy-Green tensor \( \mathbf{b} \) or the eulerian stretch tensor \( \mathbf{v} \).
input_tensor – a string (“b” for the left Cauchy-Green tensor or “V” for the eulerian stretch tensor ) representing the selected input
mJ – the determinant of the transformation gradient \(\mathbf{F}\) (optional)

void pstretch(arma::vec &lambda, arma::mat &n_pvector, std::vector<arma::mat> &N_projectors, const arma::mat &input, const std::string &input_tensor, const double &mJ = 0.)

Principal stretches \( \lambda^2_1, \lambda^2_2 \) and \( \lambda^2_3\) and principal directions, from either the left Cauchy-Green tensor \( \mathbf{b} \) or the the eulerian stretch tensor \( \mathbf{v} \).

Example:

mat F = randu(3,3);
mat b = L_Cauchy_Green(F); 
double J = det(F);
vec lambdas;
mat n;
std::vector<mat> N;
pstretch(lambdas, n, N, b, "b", J);

Parameters:

lambda – a column vector of dimension 3 that will contain the three principal stretches
n_pvector – a 3x3 matrix, where each column is a principal direction vector.
N_projectors – a std::vector of 3x3 matrices, each one being an orthogonal projector corresponding to a principal vector
input – 3x3 matrix representing the left Cauchy-Green tensor \( \mathbf{b} \) or the eulerian stretch tensor \( \mathbf{v} \).
input_tensor – a string (“b” for the left Cauchy-Green tensor or “V” for the eulerian stretch tensor ) representing the selected input
mJ – the determinant of the transformation gradient \(\mathbf{F}\) (optional)

void isochoric_pstretch(arma::vec &lambda_bar, arma::mat &n_pvector, const arma::mat &input, const std::string &input_tensor, const double &mJ = 0.)

isochoric principal stretches \( \bar{\lambda}^2_1, \bar{\lambda}^2_2 and \bar{\lambda}^2_3\) and principal directions, from either the left Cauchy-Green tensor \( \mathbf{b} \) or the the eulerian stretch tensor \( \mathbf{v} \).

Example:

mat F = randu(3,3);
mat b = L_Cauchy_Green(F); 
double J = det(F);
vec lambdas_bar;
mat n;
isochoric_pstretch(lambdas_bar, n, "b", J);

Parameters:

lambda_bar – a column vector of dimension 3 that will contain the three isochoric principal stretches
n_pvector – a 3x3 matrix, where each column is a principal direction vector.
input – 3x3 matrix representing the left Cauchy-Green tensor \( \mathbf{b} \) or the eulerian stretch tensor \( \mathbf{v} \).
input_tensor – a string (“b” for the left Cauchy-Green tensor or “V” for the eulerian stretch tensor ) representing the selected input
mJ – the determinant of the transformation gradient \(\mathbf{F}\) (optional)

void isochoric_pstretch(arma::vec &lambda_bar, arma::mat &n_pvector, std::vector<arma::mat> &N_projectors, const arma::mat &input, const std::string &input_tensor, const double &mJ = 0.)

isochoric principal stretches, principal directions \( \bar{\lambda}^2_1, \bar{\lambda}^2_2 \) and \( \bar{\lambda}^2_3\), principal directions and principal orthogonal projectors, from either the left Cauchy-Green tensor \( \mathbf{b} \) or the the eulerian stretch tensor \( \mathbf{v} \).

Example:

mat F = randu(3,3);
mat b = L_Cauchy_Green(F); 
double J = det(F);
vec lambdas_bar;
mat n;
std::vector<mat> N(3);
isochoric_pstretch(lambdas_bar, n, N, b, "b", J);

Parameters:

lambda_bar – a column vector of dimension 3 that will contain the three isochoric principal stretches
n_pvector – a 3x3 matrix, where each column is a principal direction vector.
N_projectors – a std::vector of 3x3 matrices, each one being an orthogonal projector corresponding to a principal vector
input – 3x3 matrix representing the left Cauchy-Green tensor \( \mathbf{b} \) or the eulerian stretch tensor \( \mathbf{v} \).
input_tensor – a string (“b” for the left Cauchy-Green tensor or “V” for the eulerian stretch tensor ) representing the selected input
mJ – the determinant of the transformation gradient \(\mathbf{F}\) (optional)

arma::vec beta_coefs(const arma::vec &dWdlambda_bar, const arma::vec &lambda_bar)

Provides the coeficients \( beta_i \) for the computation of Kirchoff stress using isochoric principal stretch models see (Connolly et al. Computational Mechanics (2019) 64:1273–1288 : https://doi.org/10.1007/s00466-019-01707-1) for more details.

Example:

mat F = randu(3,3);
mat b = L_Cauchy_Green(F); 
double J = det(F);
double dWdlambda_bar_1;
double dWdlambda_bar_2;
double dWdlambda_bar_3; 
vec dWdlambda_bar = {dWdlambda_bar_1, dWdlambda_bar_2, dWdlambda_bar_3};
lambda_bar = isochoric_pstretch_from_b(b, J);
vec beta_coefs = beta_coefs(dWdlambda_bar, lambda_bar);

Parameters:

dWdlambda_bar – a column vector of dimension 3 that contains the three derivatives of the strain energy with respect to the isochoric principal stretches
lambda_bar – a column vector of dimension 3 that contains the isochoric principal stretches \( \bar{lambda}_i \)

Returns:

a column vector of dimension 3 that contains the three coefficients \( \beta_1, \beta_2, \beta_3 \)

arma::mat gamma_coefs(const arma::vec &dWdlambda_bar, const arma::mat &dW2dlambda_bar2, const arma::vec &lambda_bar)

Provides the coeficients \( gamma_{ij} \) for the computation of Kirchoff stress using isochoric principal stretch models see (Connolly et al. Computational Mechanics (2019) 64:1273–1288 : https://doi.org/10.1007/s00466-019-01707-1) for more details and the Ph.D Thesis of V. Le Sault https://theses.hal.science/file/index/docid/542506/filename/Manuscrit_final.pdf.

Example:

mat F = randu(3,3);
mat b = L_Cauchy_Green(F); 
double J = det(F);
vec dWdlambda_bar = {dWdlambda_bar_1, dWdlambda_bar_2, dWdlambda_bar_3};
mat dW2dlambda_bar2 = ...
lambda_bar = isochoric_pstretch_from_b(b, J);
mat gamma_coefs = gamma_coefs(dWdlambda_bar, dW2dlambda_bar2, lambda_bar);

Parameters:

dWdlambda_bar – a column vector of dimension 3 that contains the three derivatives of the strain energy with respect to the isochoric principal stretches
dW2dlambda_bar2 – a matrix of dimension 3 that contains the nine (6 independant) second derivatives of the strain energy with respect to the isochoric principal stretches
lambda_bar – a column vector of dimension 3 that contains the isochoric principal stretches \( \bar{lambda}_i \)

Returns:

a 3x3 matrix that contains the nine coefficients \( \gamma_{ij} \)

arma::vec a_coefs(const double &dWdI_1_bar, const double &dWdI_2_bar, const arma::vec &I_bar)

Provides the coeficients \( a_i \) for the computation of invariants-based Kirchoff stress tensor see (Connolly et al. Computational Mechanics (2019) 64:1273–1288 : https://doi.org/10.1007/s00466-019-01707-1) for more details.

Example:

double dWdI_1_bar;
double dWdI_2_bar; 
mat F = randu(3,3);
mat b = L_Cauchy_Green(F); 
double J = det(F);
vec I_bar = isochoric_invariants(b,J);
vec a_coefs = a_coefs(dWdI_1_bar, dWdI_2_bar, I_bar);

Parameters:

dWdI_1_bar – The derivative of the isochoric strain energy with respect to the first isochoric invariant.
dWdI_2_bar – The derivative of the isochoric strain energy with respect to the second isochoric invariant.
I_bar – a column vector of dimension 3 that contains the three isochoric invariants

Returns:

a column vector of dimension 2 that contains the two coefficients \( a_1 and a_2 \)

arma::vec b_coefs(const double &dWdI_2_bar, const double &dW2dI_11_bar, const double &dW2dI_12_bar, const double &dW2dI_22_bar, const arma::vec &I_bar)

Provides the coeficients \( b_i \) for the computation of hyperlastic tangent modulus see (Connolly et al. Computational Mechanics (2019) 64:1273–1288 : https://doi.org/10.1007/s00466-019-01707-1) for more details.

Example:

double dWdI_2_bar, dW2dI_11_bar, dW2dI_12_bar, dW2dI_22_bar; 
mat F = randu(3,3);
mat b = L_Cauchy_Green(F); 
double J = det(F);
vec I_bar = isochoric_invariants(b,J);
vec b_coefs = b_coefs(dWdI_2_bar, dW2dI_11_bar, dW2dI_12_bar, dW2dI_22_bar, I_bar);

Parameters:

dWdI_2_bar – The derivative of the isochoric strain energy with respect to the first isochoric invariant.
dW2dI_11_bar – The second derivative of the isochoric strain energy with respect to the first isochoric invariant.
dW2dI_12_bar – The second derivative of the isochoric strain energy with respect to the first and second isochoric invariant.
dW2dI_22_bar – The second derivative of the isochoric strain energy with respect to the second isochoric invariant.
I_bar – a column vector of dimension 3 that contains the three isochoric invariants

Returns:

a column vector of dimension 4 that contains the four coefficients \( b_1, b_2, b_3 and b_4 \).

arma::vec delta_coefs(const arma::vec &a_coefs, const arma::vec &b_coefs, const arma::mat &b)

Provides the coeficients \( delta_i \) for the computation of hyperlastic tangent modulus see (Connolly et al. Computational Mechanics (2019) 64:1273–1288 : https://doi.org/10.1007/s00466-019-01707-1) for more details.

Example:

mat F = randu(3,3);
mat b = L_Cauchy_Green(F); 
double J = det(F);
...
vec a_coefs = a_coefs(dWdI_1_bar, dWdI_2_bar, I_bar);
vec b_coefs = b_coefs(dWdI_2_bar, dW2dI_11_bar, dW2dI_12_bar, dW2dI_22_bar, I_bar); 
vec delta_coefs = delta_coefs(a_coefs, b_coefs, b);

Parameters:

a_coefs – a column vector of dimension 2 that contains the two coefficients \( a_1 and a_2 \)
b_coefs – column vector of dimension 4 that contains the four coefficients \( b_1, b_2, b_3 and b_4 \)
b – 3x3 matrix representing the left Cauchy-Green deformation tensor \(\mathbf{b}\)

Returns:

a column vector of dimension 8 that contains the eight coefficients \( \delta_1, \dots, \delta_8 \)

arma::mat tau_iso_hyper_pstretch(const arma::vec &dWdlambda_bar, const arma::mat &b, const double &mJ = 0.)

Provides the isochoric part of the Kirchoff stress tensor.

The isochoric part of the Kirchoff stress tensor is defined as:

\[\begin{split} \begin{align} \mathbf{\tau}_{\textrm{iso}} = \sum_{i=1}^3 \beta_i \left(\underline{n}_i \otimes \underline{n}_i \right) \\ \beta_i = \bar{\lambda}_i \frac{\partial W}{\partial \bar{\lambda}_i} - \frac{1}{3} \sum_{j=1}^3 \bar{\lambda}_j \frac{\partial W}{\partial \bar{\lambda}_j} \end{align} \end{split}\]

where \( \frac{\partial \bar{W} }{\partial \bar{\lambda}_i} \) is the derivative of the isochoric strain energy with respect to the i-th isochoric principal stretch \( \bar{\lambda}_i \).

Example:

mat F = randu(3,3);
mat b = L_Cauchy_Green(F); 
double J = det(F);
double dWdlambda_bar_1;
double dWdlambda_bar_2;
double dWdlambda_bar_3; 
vec dWdlambda_bar = {dWdlambda_bar_1, dWdlambda_bar_2, dWdlambda_bar_3};
lambda_bar = isochoric_pstretch_from_b(b, J);
mat m_tau_iso = tau_iso_hyper_pstretch(dWdlambda_bar, b, J);

Parameters:

dWdlambda_bar – A column vector of dimension 3 that contains the derivatives of the isochoric strain energy with respect to the isochoric principal stretches
b – 3x3 matrix representing the left Cauchy-Green deformation tensor \(\mathbf{b}\)
mJ – the determinant of the transformation gradient \(\mathbf{F}\) (optional)

Returns:

3x3 matrix representing the isochoric part of the Kirchoff stress tensor.

arma::mat tau_iso_hyper_pstretch(const arma::vec &dWdlambda_bar, arma::vec &lambda_bar, std::vector<arma::mat> &N_projectors)

Provides the isochoric part of the Kirchoff stress tensor.

The isochoric part of the Kirchoff stress tensor is defined as:

\[\begin{split} \begin{align} \mathbf{\tau}_{\textrm{iso}} = \sum_{i=1}^3 \beta_i \left(\underline{n}_i \otimes \underline{n}_i \right) \\ \beta_i = \bar{\lambda}_i \frac{\partial W}{\partial \bar{\lambda}_i} - \frac{1}{3} \sum_{j=1}^3 \bar{\lambda}_j \frac{\partial W}{\partial \bar{\lambda}_j} \end{align} \end{split}\]

where \( \frac{\partial \bar{W} }{\partial \bar{\lambda}_i} \) is the derivative of the isochoric strain energy with respect to the i-th isochoric principal stretch \( \bar{\lambda}_i \).

Example:

mat F = randu(3,3);
mat b = L_Cauchy_Green(F); 
double J = det(F);
double dWdlambda_bar_1;
double dWdlambda_bar_2;
double dWdlambda_bar_3; 
vec dWdlambda_bar = {dWdlambda_bar_1, dWdlambda_bar_2, dWdlambda_bar_3};
vec lambdas_bar;
mat n;
std::vector<double> N(3);
isochoric_pstretch(lambdas_bar, n, N, "b", J);
mat m_tau_iso = tau_iso_hyper_pstretch(dWdlambda_bar, lambda_bar, N_projectors);

Parameters:

dWdlambda_bar – A column vector of dimension 3 that contains the derivatives of the isochoric strain energy with respect to the isochoric principal stretches
lambda_bar – a column vector of dimension 3 that will contain the three isochoric principal stretches
N_projectors – a std::vector of 3x3 matrices, each one being an orthogonal projector corresponding to a principal vector

Returns:

3x3 matrix representing the isochoric part of the Kirchoff stress tensor.

arma::mat tau_iso_hyper_invariants(const double &dWdI_1_bar, const double &dWdI_2_bar, const arma::mat &b, const double &mJ = 0.)

Provides the isochoric part of the Kirchoff stress tensor.

The isochoric part of the Kirchoff stress tensor is defined as:

\[ \mathbf{\tau}_{\textrm{iso}} = 2. \frac{\partial \bar{W} }{\partial \bar{I}_1 } \textrm{dev} \bar{\mathbf{b}} + 2 \frac{\partial \bar{W} }{\partial \bar{I}_2 } \left( \textrm{tr} \bar{\mathbf{b}} \textrm{dev} \bar{\mathbf{b}} - \textrm{dev} \bar{\mathbf{b}}^2 \right) \]

where \( \frac{\partial \bar{W} }{\partial \bar{I}_1 } \) and \( \frac{\partial \bar{W} }{\partial \bar{I}_2 } \) are the derivatives of the isochoric strain energy, \(\mathbf{b}\) is the left Cauchy-Green deformation tensor and \(\mathbf{I}\) is the 3x3 identity matrix.

Example:

double dWdI_1_bar;
double dWdI_2_bar; 
mat F = randu(3,3);
mat b = L_Cauchy_Green(F); 
double J = det(F);
mat m_tau_iso = tau_iso_hyper_invariants(dWdI_1_bar, dWdI_2_bar, b, J);

Parameters:

dWdI_1_bar – The derivative of the isochoric strain energy with respect to the first isochoric invariant.
dWdI_2_bar – The derivative of the isochoric strain energy with respect to the second isochoric invariant.
b – 3x3 matrix representing the left Cauchy-Green deformation tensor \(\mathbf{b}\)
mJ – the determinant of the transformation gradient \(\mathbf{F}\) (optional)

Returns:

3x3 matrix representing the isochoric part of the Kirchoff stress tensor.

arma::mat tau_vol_hyper(const double &dUdJ, const arma::mat &b, const double &mJ = 0.)

Provides the volumetric part of the Kirchoff stress tensor.

The volumetric part of the Kirchoff stress tensor is related to the derivative of the volumetric strain energy \( U \):

\[ \mathbf{\tau}_{\textrm{vol}} = J \frac{\partial U}{\partial J} \, \mathbf{I} \]

Example:

double dUdJ;
mat F = randu(3,3);
mat b = L_Cauchy_Green(F); 
double J = det(F);
mat m_tau_vol = tau_vol(dUdJ, J);

Parameters:

dUdJ – the derivative of the volumetric strain energy with respect to \( J \)
b – 3x3 matrix representing the left Cauchy-Green deformation tensor \(\mathbf{b}\)
mJ – the determinant of the transformation gradient \(\mathbf{F}\) (optional)

Returns:

3x3 matrix representing the isochoric part of the Kirchoff stress tensor.

arma::mat sigma_iso_hyper_pstretch(const arma::vec &dWdlambda_bar, const arma::mat &b, const double &mJ = 0.)

Provides the isochoric part of the Cauchy stress tensor.

The isochoric part of the Cauchy stress tensor is defined as:

\[\begin{split} \begin{align} \mathbf{\sigma}_{\textrm{iso}} = \frac{1}{J} \sum_{i=1}^3 \beta_i \left(\underline{n}_i \otimes \underline{n}_i \right) \\ \beta_i = \bar{\lambda}_i \frac{\partial W}{\partial \bar{\lambda}_i} - \frac{1}{3} \sum_{j=1}^3 \bar{\lambda}_j \frac{\partial W}{\partial \bar{\lambda}_j} \end{align} \end{split}\]

where \( \frac{\partial \bar{W} }{\partial \bar{\lambda}_i} \) is the derivative of the isochoric strain energy with respect to the i-th isochoric principal stretch \( \bar{\lambda}_i \).

Example:

mat F = randu(3,3);
mat b = L_Cauchy_Green(F); 
double J = det(F);
double dWdlambda_bar_1;
double dWdlambda_bar_2;
double dWdlambda_bar_3; 
vec dWdlambda_bar = {dWdlambda_bar_1, dWdlambda_bar_2, dWdlambda_bar_3};
lambda_bar = isochoric_pstretch_from_b(b, J);
mat m_sigma_iso = sigma_iso_hyper_pstretch(dWdlambda_bar, b, J);

Parameters:

dWdlambda_bar – A column vector of dimension 3 that contains the derivatives of the isochoric strain energy with respect to the isochoric principal stretches
b – 3x3 matrix representing the left Cauchy-Green deformation tensor \(\mathbf{b}\)
mJ – the determinant of the transformation gradient \(\mathbf{F}\) (optional)

Returns:

3x3 matrix representing the isochoric part of the Cauchy stress tensor.

arma::mat sigma_iso_hyper_pstretch(const arma::vec &dWdlambda_bar, const arma::vec &lambda_bar, const std::vector<arma::mat> &N_projectors, const double &J)

Provides the isochoric part of the Cauchy stress tensor.

The isochoric part of the Cauchy stress tensor is defined as:

\[\begin{split} \begin{align} \mathbf{\sigma}_{\textrm{iso}} = \frac{1}{J} \sum_{i=1}^3 \beta_i \left(\underline{n}_i \otimes \underline{n}_i \right) \\ \beta_i = \bar{\lambda}_i \frac{\partial W}{\partial \bar{\lambda}_i} - \frac{1}{3} \sum_{j=1}^3 \bar{\lambda}_j \frac{\partial W}{\partial \bar{\lambda}_j} \end{align} \end{split}\]

where \( \frac{\partial \bar{W} }{\partial \bar{\lambda}_i} \) is the derivative of the isochoric strain energy with respect to the i-th isochoric principal stretch \( \bar{\lambda}_i \).

Example:

mat F = randu(3,3);
mat b = L_Cauchy_Green(F); 
double J = det(F);
double dWdlambda_bar_1;
double dWdlambda_bar_2;
double dWdlambda_bar_3; 
vec dWdlambda_bar = {dWdlambda_bar_1, dWdlambda_bar_2, dWdlambda_bar_3};
vec lambdas_bar = isochoric_pstretch_from_b(b, J);
mat n;
std::vector<double> N(3);
isochoric_pstretch(lambdas_bar, n, N, "b", J);
mat m_tau_iso = sigma_iso_hyper_pstretch(dWdlambda_bar, lambda_bar, N_projectors, J);

Parameters:

dWdlambda_bar – A column vector of dimension 3 that contains the derivatives of the isochoric strain energy with respect to the isochoric principal stretches
lambda_bar – a column vector of dimension 3 that will contain the three isochoric principal stretches
N_projectors – a std::vector of 3x3 matrices, each one being an orthogonal projector corresponding to a principal vector
J – the determinant of the transformation gradient \(\mathbf{F}\) (mandatory since left Cauchy-Green deformation tensor \(\mathbf{b}\) is not provided)

Returns:

3x3 matrix representing the isochoric part of the Cauchy stress tensor.

arma::mat sigma_iso_hyper_invariants(const double &dWdI_1_bar, const double &dWdI_2_bar, const arma::mat &b, const double &mJ = 0.)

Provides the isochoric part of the Cauchy stress tensor.

The isochoric part of the Kirchoff stress tensor is defined as:

\[ \mathbf{\tau}_{\textrm{iso}} = \frac{1}{J} \left[ 2. \frac{\partial \bar{W} }{\partial \bar{I}_1 } \textrm{dev} \bar{\mathbf{b}} + 2 \frac{\partial \bar{W} }{\partial \bar{I}_2 } \left( \textrm{tr} \bar{\mathbf{b}} \textrm{dev} \bar{\mathbf{b}} - \textrm{dev} \bar{\mathbf{b}}^2 \right) \right] \]

where \( \frac{\partial \bar{W} }{\partial \bar{I}_1 } \) and \( \frac{\partial \bar{W} }{\partial \bar{I}_2 } \) are the derivatives of the isochoric strain energy, \(\mathbf{b}\) is the left Cauchy-Green deformation tensor and \(\mathbf{I}\) is the 3x3 identity matrix.

Example:

double dWdI_1_bar;
double dWdI_2_bar; 
mat F = randu(3,3);
mat b = L_Cauchy_Green(F); 
double J = det(F);
mat m_sigma_iso = sigma_iso(dWdI_1_bar, dWdI_2_bar, b, J);

Parameters:

dWdI_1_bar – The derivative of the isochoric strain energy with respect to the first isochoric invariant.
dWdI_2_bar – The derivative of the isochoric strain energy with respect to the second isochoric invariant.
b – 3x3 matrix representing the left Cauchy-Green deformation tensor \(\mathbf{b}\)
mJ – the determinant of the transformation gradient \(\mathbf{F}\) (optional)

Returns:

3x3 matrix representing the isochoric part of the Kirchoff stress tensor.

arma::mat sigma_vol_hyper(const double &dUdJ, const arma::mat &b, const double &mJ = 0.)

Provides the volumetric part of the Kirchoff stress tensor.

The volumetric part of the Cauchy stress tensor is related to the derivative of the volumetric strain energy \( U \):

\[ \mathbf{\sigma}_{\textrm{vol}} = \frac{\partial U}{\partial J} \, \mathbf{I} \]

Example:

double dUdJ;
mat F = randu(3,3);
mat b = L_Cauchy_Green(F); 
double J = det(F);
mat m_sigma_vol = sigma_vol(dUdJ, J);

Parameters:

dUdJ – the derivative of the volumetric strain energy with respect to \( J \)
b – 3x3 matrix representing the left Cauchy-Green deformation tensor \(\mathbf{b}\)
mJ – the determinant of the transformation gradient \(\mathbf{F}\) (optional)

Returns:

3x3 matrix representing the isochoric part of the Kirchoff stress tensor.

arma::mat L_iso_hyper_pstretch(const arma::vec &dWdlambda_bar, const arma::mat &dW2dlambda_bar2, const arma::vec &lambda_bar, const arma::mat &n_pvectors, const double &J)

Provides the isochoric part of the hyperelastic tangent modulus, considering principal stretches.

The isochoric part of the hyperelastic tangent modulus is defined as:

\[\begin{split} \begin{align} \mathbf{L}^t_{\textrm{iso}} &= \displaystyle \sum_{a,b = 1}^3 \left( \gamma_{ab} - \delta_{ab} \beta_a \right) \left( \mathbf{n}_a \otimes \mathbf{n}_a \otimes \mathbf{n}_b \otimes \mathbf{n}_b \right) \\ & + \displaystyle \sum_{a,b=1, \, a \neq b } \frac{\beta_b \lambda_a^2 - \beta_a \lambda_b^2}{\lambda_a^2 - \lambda_b^2} \left(\mathbf{n}_a \otimes \mathbf{n}_b \otimes \mathbf{n}_a \otimes \mathbf{n}_b + \mathbf{n}_a \otimes \mathbf{n}_b \otimes \mathbf{n}_b \otimes \mathbf{n}_a \right) \end{align} \end{split}\]

where \( \beta_{ij} \) and \( \gamma_{ij} \) depend on the derivatives of the isochoric strain energy with respect to principal stretches and \( \mathbf{n}_a \) is the a-th principal vector.

Example:

mat F = randu(3,3);
mat b = L_Cauchy_Green(F); 
double J = det(F);
double dWdlambda_bar_1;
double dWdlambda_bar_2;
double dWdlambda_bar_3; 
vec dWdlambda_bar = {dWdlambda_bar_1, dWdlambda_bar_2, dWdlambda_bar_3};
mat dW2dlambda_bar = {{ dW2dlambda_bar2_11, dW2dlambda_bar2_21, dW2dlambda_bar2_31}, { dW2dlambda_bar2_12, dW2dlambda_bar2_22, dW2dlambda_bar2_32}, { dW2dlambda_bar2_13, dW2dlambda_bar2_23, dW2dlambda_bar2_33}}; 
vec lambdas_bar = isochoric_pstretch_from_b(b, J);
mat n;
std::vector<double> N(3);
isochoric_pstretch(lambdas_bar, n_pvectors, N, "b", J);
mat L_iso = L_iso_hyper_pstretch(dWdlambda_bar, dW2dlambda_bar2, n_pvectors, J);

Parameters:

dWdlambda_bar – The derivative of the isochoric strain energy with respect to the isochoric principal stretches.
dW2dlambda_bar2 – The second derivative of the isochoric strain energy with respect to the isochoric principal stretches.
lambda_bar – The isochoric principal stretches.
n_pvectors – The principal vectors, stacked as columns of a 3x3 matrix.
J – the determinant of the transformation gradient \(\mathbf{F}\)

Returns:

6x6 matrix representing the isochoric part of the hyperelastic tangent modulus.

arma::mat L_iso_hyper_pstretch(const arma::vec &dWdlambda_bar, const arma::mat &dW2dlambda_bar2, const arma::mat &b, const double &mJ)

Provides the isochoric part of the hyperelastic tangent modulus, considering principal stretches.

The isochoric part of the hyperelastic tangent modulus is defined as:

\[\begin{split} \begin{align} \mathbf{L}^t_{\textrm{iso}} &= \displaystyle \sum_{a,b = 1}^3 \left( \gamma_{ab} - \delta_{ab} \beta_a \right) \left( \mathbf{n}_a \otimes \mathbf{n}_a \otimes \mathbf{n}_b \otimes \mathbf{n}_b \right) \\ & + \displaystyle \sum_{a,b=1, \, a \neq b } \frac{\beta_b \lambda_a^2 - \beta_a \lambda_b^2}{\lambda_a^2 - \lambda_b^2} \left(\mathbf{n}_a \otimes \mathbf{n}_b \otimes \mathbf{n}_a \otimes \mathbf{n}_b + \mathbf{n}_a \otimes \mathbf{n}_b \otimes \mathbf{n}_b \otimes \mathbf{n}_a \right) \end{align} \end{split}\]

where \( \beta_{ij} \) and \( \gamma_{ij} \) depend on the derivatives of the isochoric strain energy with respect to principal stretches and \( \mathbf{n}_a \) is the a-th principal vector.

Example:

mat F = randu(3,3);
mat b = L_Cauchy_Green(F); 
double J = det(F);
double dWdlambda_bar_1;
double dWdlambda_bar_2;
double dWdlambda_bar_3; 
vec dWdlambda_bar = {dWdlambda_bar_1, dWdlambda_bar_2, dWdlambda_bar_3};
mat dW2dlambda_bar = {{ dW2dlambda_bar2_11, dW2dlambda_bar2_21, dW2dlambda_bar2_31}, { dW2dlambda_bar2_12, dW2dlambda_bar2_22, dW2dlambda_bar2_32}, { dW2dlambda_bar2_13, dW2dlambda_bar2_23, dW2dlambda_bar2_33}}; 
mat L_iso = L_iso_hyper_pstretch(dWdlambda_bar, dW2dlambda_bar2, b, J);

Parameters:

dWdlambda_bar – The derivative of the isochoric strain energy with respect to the isochoric principal stretches.
dW2dlambda_bar2 – The second derivative of the isochoric strain energy with respect to the isochoric principal stretches.
b – 3x3 matrix representing the left Cauchy-Green deformation tensor \(\mathbf{b}\)
mJ – the determinant of the transformation gradient \(\mathbf{F}\) (optional)

Returns:

6x6 matrix representing the isochoric part of the hyperelastic tangent modulus.

arma::mat L_iso_hyper_invariants(const double &dWdI_1_bar, const double &dWdI_2_bar, const double &dW2dI_11_bar, const double &dW2dI_12_bar, const double &dW2dI_22_bar, const arma::mat &b, const double &mJ = 0.)

Provides the isochoric part of the hyperelastic tangent modulus, considering Invariants.

The isochoric part of the hyperelastic tangent modulus is defined as:

\[\begin{split} \begin{align} \mathbf{L}^t_{\textrm{iso}} &= \delta_1 \left( \bar{\mathbf{b}} \otimes \bar{\mathbf{b}} \right) + \delta_2 \left[ \left( \bar{\mathbf{b}} \otimes \bar{\mathbf{b}}^2 \right) + \left( \bar{\mathbf{b}}^2 \otimes \bar{\mathbf{b}} \right) \right] \\ &+ \delta_3 \left[ \left( \bar{\mathbf{b}} \otimes \mathbf{I} \right) + \left(\mathbf{I} \otimes \bar{\mathbf{b}} \right) \right] + \delta_4 \left( \bar{\mathbf{b}}^2 \times \bar{\mathbf{b}}^2 \right) \\ &+ \delta_5 \left[ \left( \bar{\mathbf{b}}^2 \otimes \mathbf{I} \right) + \left(\mathbf{I} \otimes \bar{\mathbf{b}}^2 \right) \right] + \delta_6 \left( \mathbf{I} \otimes \mathbf{I} \right) \\ &+ \delta_7 \left( \mathbf{I} \odot \mathbf{I} \right) + \delta_8 \left( \bar{\mathbf{b}} \odot \bar{\mathbf{b}} \right) \\ \end{align} \end{split}\]

where \( delta_i \) depends on the derivatives of the isochoric strain energy, \(\mathbf{b}\) is the left Cauchy-Green deformation tensor and \( J \) is the determinant of the transformation gradient

Example:

mat F = randu(3,3);
mat b = L_Cauchy_Green(F); 
double J = det(F);
double dWdI_1_bar, dWdI_2_bar, dW2dI_11_bar, dW2dI_12_bar, dW2dI_22_bar;
mat L_iso = L_iso_hyper_invariants(delta_coefs, b, J);

Parameters:

dWdI_1_bar – The derivative of the isochoric strain energy with respect to the first isochoric invariant.
dWdI_2_bar – The derivative of the isochoric strain energy with respect to the second isochoric invariant.
dW2dI_11_bar – The second derivative of the isochoric strain energy with respect to the first isochoric invariant.
dW2dI_12_bar – The second derivative of the isochoric strain energy with respect to the first and second isochoric invariant.
dW2dI_22_bar – The second derivative of the isochoric strain energy with respect to the second isochoric invariant.
b – 3x3 matrix representing the left Cauchy-Green deformation tensor \(\mathbf{b}\)
mJ – the determinant of the transformation gradient \(\mathbf{F}\) (optional)

Returns:

6x6 matrix representing the isochoric part of the hyperelastic tangent modulus.

arma::mat L_vol_hyper(const double &dUdJ, const double &dU2dJ2, const arma::mat &b, const double &mJ = 0.)

Provides the volumetric part of the hyperelastic tangent modulus.

The volumetric part of the hyperelastic tangent modulus is defined as:

\[ \mathbf{L}^t_{\textrm{vol}} = J \left( \frac{\partial U}{\partial J} + \frac{\partial^2 U}{\partial J^2 \, J} \right) \left( \mathbf{I} \otimes \mathbf{I} \right) - 2 \frac{\partial U}{\partial J} \, J \left( \mathbf{I} \odot \mathbf{I} \right) \]

where U is the volumetric strain energy and \( J \) is the determinant of the transformation gradient

Example:

mat F = randu(3,3);
mat b = L_Cauchy_Green(F); 
double J = det(F);
double dUdJ, dU2dJ2;
mat L_vol = L_vol_hyper_invariants(dUdJ, dU2dJ2, J);

Parameters:

dUdJ – the derivative of the volumetric strain energy with respect to \( J \)
dU2dJ2 – the second derivative of the volumetric strain energy with respect to \( J \)
b – 3x3 matrix representing the left Cauchy-Green deformation tensor \(\mathbf{b}\)
mJ – the determinant of the transformation gradient \(\mathbf{F}\) (optional)

Returns:

6x6 matrix representing the volumetric part of the hyperelastic tangent modulus.

hyper_invariants_dW hyper_potential_derivatives(const HyperPotential &potential, const arma::vec &props, const arma::vec &I_bar, const double &J)

Derivatives of an isochoric-invariant potential.

Parameters:

potential – the potential (see HyperPotential for its props)
props – the potential’s own parameters, starting at index 0
I_bar – isochoric invariants \( (\bar{I}_1, \bar{I}_2) \)
J – determinant of the deformation gradient

Returns:

the seven derivatives

void hyper_invariants_response(const hyper_invariants_dW &dW, const arma::mat &b, const double &J, const arma::mat &F, arma::vec &sigma, arma::mat &Lt_box)

Cauchy stress and canonical box tangent of an invariant potential.

Assembles \( \boldsymbol{\sigma} \) and \( \partial \hat{\boldsymbol{\tau}} / \partial \mathbf{D}_e \) (Kirchhoff, no J, XBM rate — the same object the small-strain boxes return) from the potential derivatives and the left Cauchy-Green tensor.

F is only used to move the tangent into the box convention. The standalone UMAT passes the deformation gradient; a caller that has an ELASTIC state rather than a total one passes \( \mathbf{V}^{el} = \exp(\boldsymbol{ \varepsilon}^{el}) \), whose square is b — the tangent is then \( \partial \boldsymbol{\tau} / \partial \boldsymbol{\varepsilon}^{el} \).

Parameters:

dW – [in] potential derivatives at (b, J)
b – [in] left Cauchy-Green tensor \( \mathbf{b} = \mathbf{F}\mathbf{F}^T \)
J – [in] \( \det \mathbf{F} \)
F – [in] deformation gradient (or V for an elastic state, see above)
sigma – [out] Cauchy stress, 6-Voigt. Cauchy and not Kirchhoff because that is what the builders produce: a caller wanting \( \boldsymbol{\tau} \) multiplies by J once, rather than this function multiplying and the caller dividing back (which is not exact in floating point).
Lt_box – [out] canonical box tangent, 6x6

struct hyper_invariants_dW

#include <hyperelastic.hpp>

Derivatives of an isochoric-invariant hyperelastic potential.

The seven scalars every potential of the form \( W(\bar{I}_1, \bar{I}_2) + U(J) \) hands to the stress and tangent builders. Zero-initialised, so a potential only writes the terms it has.

Public Members

double dWdI_1_bar = 0.: \( \partial W / \partial \bar{I}_1 \)

double dWdI_2_bar = 0.: \( \partial W / \partial \bar{I}_2 \)

double dW2dI_11_bar = 0.: \( \partial^2 W / \partial \bar{I}_1^2 \)

double dW2dI_12_bar = 0.: \( \partial^2 W / \partial \bar{I}_1 \partial \bar{I}_2 \)

double dW2dI_22_bar = 0.: \( \partial^2 W / \partial \bar{I}_2^2 \)

double dUdJ = 0.: \( \partial U / \partial J \)

double dU2dJ2 = 0.: \( \partial^2 U / \partial J^2 \)

hyperelastic.hpp

Overview

API Reference

Overview 

API Reference 