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

enumerator HOLZA: Gasser-Ogden-Holzapfel, props [C10, k1, k2, kappa_d, n_fam, (a0x, a0y, a0z) x n_fam, kappa].

enum class VolumetricPotential

Volumetric part \( U(J) \) of a hyperelastic potential.

Both share the ground-state bulk modulus \( U''(1) = \kappa \).

Values:

enumerator LOG_J: \( U = \kappa (J \ln J - J + 1) \) (default)

enumerator QUADRATIC: \( U = \frac{\kappa}{2} (J - 1)^2 \)

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, const arma::vec &lambda_bar, const 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}} = \left( \frac{\partial U}{\partial J} + J \, \frac{\partial^2 U}{\partial J^2} \right) \left( \mathbf{I} \otimes \mathbf{I} \right) - 2 \frac{\partial U}{\partial 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);

Note

This is the SPATIAL ELASTICITY \( \boldsymbol{\mathsf{c}} = J^{-1} \partial (\mathcal{L}_v \boldsymbol{\tau}) / \partial \mathbf{D} \), not \( \partial (\mathcal{L}_v \boldsymbol{\sigma}) / \partial \mathbf{D} \): the two differ by exactly \( \boldsymbol{\sigma} \otimes \mathbf{I} \), which here is \( U'(J) \, \mathbf{I} \otimes \mathbf{I} \). A caller wanting the Kirchhoff-Lie tangent multiplies by \( J \) once. Beware that the sibling L_iso_hyper_invariants reaches the same convention through an EXPLICIT \( 1/J \) while this one is \( J \)-free by cancellation – scale the two as a sum, never one at a time.

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.

VolumetricPotential volumetric_potential_of(const arma::vec &props, const arma::uword n_used)

The volumetric potential selected by an optional trailing prop.

Parameters:

props – the props of the law
n_used – how many of them the isochoric potential consumed; props(n_used), when present, selects the VolumetricPotential (0 or 1)

void volumetric_derivatives(const VolumetricPotential &vol, const double &kappa, const double &J, double &dUdJ, double &dU2dJ2): First and second derivatives of \( U(J) \).

hyper_anisotropy hyper_potential_anisotropy(const HyperPotential &potential, const arma::vec &props)

The fibre directions and dispersion an anisotropic potential declares in its props.

Isotropic potentials return an empty a0 and \( \kappa_d = 0 \). This is the single place that knows where the directions sit in a potential’s props, so neither the standalone UMAT nor the modular block duplicates the layout.

The reference directions are read as three direction cosines per family and normalised defensively: the Python API expresses them as a simcoon.Rotation applied to \( \mathbf{e}_1 \), so no Euler triplet (and hence no gimbal lock) sits anywhere on the path from the user to the kernel. They are expressed in the LOCAL material frame; the solver’s material orientation places them globally, exactly as for ELIST/ELORT.

Parameters:

potential – the potential (see HyperPotential for its props)
props – the potential’s own parameters, starting at index 0

Throws:

std::invalid_argument – if \( \kappa_d \notin [0, 1/3] \), if the family count is not strictly positive, or if a direction has zero norm

Returns:

the reference fibre directions and the dispersion

std::vector<arma::mat> structure_tensors_push_forward(const arma::mat &F, const arma::mat &a0, const double &kappa_d, const double &mJ = 0.)

The pushed-forward isochoric structure tensors of a dispersed fibre family.

With \( \bar{\mathbf{a}}_i = J^{-1/3} \mathbf{F} \mathbf{a}_{0,i} \) the isochoric push-forward of the i-th reference direction, the Gasser-Ogden-Holzapfel generalised structure tensor becomes, in the spatial configuration,

\[ \mathbf{A}_i = \kappa_d \, \bar{\mathbf{b}} + (1 - 3 \kappa_d) \, \bar{\mathbf{a}}_i \otimes \bar{\mathbf{a}}_i \]

whose trace is the fibre pseudo-invariant the potential is written in:

\[ \bar{I}^{*}_{4,i} = \textrm{tr} \, \mathbf{A}_i = \kappa_d \, \bar{I}_1 + (1 - 3 \kappa_d) \, \bar{I}_{4,i}, \qquad \bar{I}_{4,i} = \mathbf{a}_{0,i} \cdot \bar{\mathbf{C}} \, \mathbf{a}_{0,i} \]

\( \kappa_d = 0 \) gives perfectly aligned fibres (the Holzapfel-Gasser-Ogden 2000 model), \( \kappa_d = 1/3 \) an isotropic distribution, for which \( \mathbf{A}_i = \bar{\mathbf{b}}/3 \) and the fibre term degenerates to a function of \( \bar{I}_1 \) alone.

Returning \( \mathbf{A}_i \) rather than the bare \( \bar{\mathbf{a}}_i \) is what makes the anisotropic stress and tangent reuse the isotropic \( \bar{I}_1 \) machinery: \( \bar{\mathbf{b}} \) and \( \bar{\mathbf{a}}_i \otimes \bar{\mathbf{a}}_i \) share the convected rate form \( \mathbf{l}\mathbf{A} + \mathbf{A}\mathbf{l}^T - \frac{2}{3} \textrm{tr}(\mathbf{d}) \mathbf{A} \), hence so does their combination, hence \( \dot{\bar{I}}^{*}_{4,i} = 2 \, \textrm{dev} \mathbf{A}_i : \mathbf{d} \) — the very relation \( \bar{I}_1 \) satisfies with \( \bar{\mathbf{b}} \).

Example:

mat F = randu(3,3);
mat a0 = {{1.},{0.},{0.}};
std::vector<mat> A = structure_tensors_push_forward(F, a0, 0.1, det(F));
double I4_star = trace(A[0]);

Note

When F is \( \mathbf{V}^{el} \) (the modular block), the push-forward is the exact corotated one, \( \mathbf{U}\mathbf{a}_0 = \mathbf{R}^T\mathbf{F}\mathbf{a}_0 \), ONLY because MODUL under finite strain rejects any corate other than 3 (log_R) – see select_umat_M_finite in umat_smart.cpp. Under another corate the same code would silently convect the fibres with a different spin, which is still objective but is a different model. That guard and this function must stay in step.

Warning

The directions are carried from the REFERENCE configuration and pushed forward by F. When F is an elastic stretch that differs from the total one – a modular composition whose mechanism subtracts an inelastic strain (plasticity, viscoelasticity) – the fibres should first be convected into the intermediate configuration, and are not: the inelastic strain does not reorient them. The composition remains well posed and converges, and the approximation is exact while the inelastic strain is small or leaves the fibre directions fixed; its error grows with how much that strain reorients them. Representing it exactly would need the convected directions as state, which the additive corotational kinematics of the modular UMAT cannot express (there is no plastic deformation gradient to convect with). Damage is unaffected: it contributes no inelastic strain, so the elastic stretch is the total one and the push-forward is exact.

Parameters:

F – deformation gradient \( \mathbf{F} \) (or \( \mathbf{V}^{el} \) for an elastic state, as in hyper_invariants_response)
a0 – 3 x n_fam matrix of unit reference directions, one per column (empty gives an empty result)
kappa_d – the dispersion \( \kappa_d \)
mJ – the determinant of \( \mathbf{F} \) (optional)

Returns:

one 3x3 symmetric \( \mathbf{A}_i \) per fibre family

hyper_invariants_dW hyper_potential_derivatives(const HyperPotential &potential, const arma::vec &props, const arma::vec &I_bar, const double &J, const std::vector<arma::mat> &A = {})

Derivatives of an isochoric-invariant potential.

Note

The framework assumes the potential is ADDITIVELY SEPARABLE in \( \bar{I}_1 \), \( \bar{I}_2 \) and each \( \bar{I}^{*}_{4,i} \): hyper_invariants_dW carries no \( \partial^2 W / \partial \bar{I}_1 \partial \bar{I}^{*}_4 \) slot, and hyper_invariants_response builds no cross term. A future coupled potential (the Holzapfel-Ogden myocardium model, for instance) needs that slot added, not just a new case here.

Parameters:

potential – the potential (see HyperPotential for its props)
props – the potential’s own parameters, starting at index 0
I_bar – the isochoric invariants \( (\bar{I}_1, \bar{I}_2, \bar{I}_3) \), as isochoric_invariants returns them
J – determinant of the deformation gradient
A – the pushed-forward structure tensors (structure_tensors_push_forward), one per fibre family. An anisotropic potential reads its pseudo-invariants off them as \( \bar{I}^{*}_{4,i} = \textrm{tr}\,\mathbf{A}_i \), so the invariant and the tensor the tangent is built from can never come from different code. Empty for an isotropic potential, which is the default.

Returns:

the derivatives of the potential

void hyper_invariants_response(const hyper_invariants_dW &dW, const arma::mat &b, const double &J, const arma::mat &F, const int &corate_type, arma::vec &tau, arma::mat &Lt_box, const std::vector<arma::mat> &A = {})

Kirchhoff stress and canonical box tangent of an invariant potential.

Assembles \( \boldsymbol{\tau} \) and \( \partial \hat{\boldsymbol{\tau}} / \partial \mathbf{D}_e \) (Kirchhoff, no J, in the requested corate — the same object the small-strain boxes return) from the potential derivatives and the left Cauchy-Green tensor. The closed form is the spatial (Lie/Oldroyd) tangent; it is converted once, by Dtau_LieDD_2_DtauDe_corate, to the box of corate_type.

Kirchhoff on both outputs, deliberately: in the logarithmic framework an isotropic potential differentiates to \( \boldsymbol{\tau} = \partial W / \partial \ln \mathbf{V} \) per REFERENCE volume, so \( \boldsymbol{\tau} \) is what the whole finite route carries and what the tangent is conjugate to. Cauchy is the derived output \( \boldsymbol{\sigma} = \boldsymbol{\tau}/J \) and is formed only at the boundaries (the solver’s sinks, the python wrapper), never on the route.

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 — with corate_type = 3 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)
corate_type – [in] the objective rate Lt_box is expressed in (see corate_kinematics)
tau – [out] Kirchhoff stress, 6-Voigt
Lt_box – [out] box tangent in corate_type, 6x6
A – [in] the pushed-forward structure tensors of an anisotropic potential (structure_tensors_push_forward), one per fibre family and in the same order as dW.dWdI_a_bar. Empty for an isotropic potential, which is the default.

struct hyper_invariants_dW

#include <hyperelastic.hpp>

Derivatives of an isochoric-invariant hyperelastic potential.

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

An anisotropic potential additionally writes the two vector members, one entry per fibre family, holding the derivatives with respect to the fibre pseudo-invariant \( \bar{I}^{*}_{4,i} \) (see structure_tensors_push_forward). They stay empty for an isotropic potential, which is how the builders tell the two cases apart.

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

arma::vec dWdI_a_bar: \( \partial W / \partial \bar{I}^{*}_{4,i} \), one per fibre family

arma::vec dW2dI_aa_bar: \( \partial^2 W / \partial \bar{I}^{*\,2}_{4,i} \), one per fibre family

struct hyper_anisotropy

#include <hyperelastic.hpp>

The fibre anisotropy carried by a hyperelastic potential’s props.

hyperelastic.hpp

Overview

API Reference

Overview 

API Reference 