====== Hyperelastic materials ======

===== NeoHookeanHyperMaterial =====

=== Description ===

Neo-Hookean hyperelastic law, using a ''Cauchy'' stress tensor $\boldsymbol{\sigma}$, stress in the current configuration.

(Quasi-)incompressibility is treated by a volumetric/deviatoric multiplicative split of the deformation gradient, i.e.  $\bar{\mathbf{F}} = J^{-1/3}\mathbf{F}$. Hence the deviatoric potential is based on reduced invariants of $\bar{\mathbf{b}} =\bar{\mathbf{F}}\bar{\mathbf{F}}^T $.

$$
 W\left(I_1,I_2,J\right)  =  \bar{W}\left(\bar{I_1},\bar{I_2}\right) + K f\left(J\right) = C_1\left(\bar{I_1} - 3\right) + \frac{k_0}{2}\left[ \left(J-1\right)^2 + \ln^2 J\right]
$$

=== Parameters ===
^   Name                                                  ^  Metafor Code  ^ Dependency ^
| Density                                                 |  ''MASS_DENSITY''  |  ''TO/TM''  |
| NeoHookean coefficient ($C_1$)                          |  ''RUBBER_C1''  |  ''TO/TM''  |
| Initial bulk modulus ($k_0$)                            |  ''RUBBER_PENAL''  |  ''TO/TM''  |
| Material temperature evolution law                      |  ''TEMP''  |    ''TM''   |
| Thermal expansion coefficient ($\alpha$)                |  ''THERM_EXPANSION''  |  ''TO/TM''  |

===== TmNeoHookeanHyperMaterial =====
<note important> **Metafor version $\geq$ 3554** </note>
=== Description ===
Neo-Hookean hyperelastic law, using a ''Cauchy'' stress tensor $\boldsymbol{\sigma}$, stress in the current configuration.

Here, the ''TEMP'' parameter is not relevant anymore.

=== Parameters ===
^   Name                                                  ^  Metafor Code  ^ Dependency ^
| Density                                                 |  ''MASS_DENSITY''  |  ''TO/TM''  |
| NeoHookean coefficient ($C_1$)                          |  ''RUBBER_C1''  |  ''TO/TM''  |
| Initial bulk modulus ($k_0$)                            |  ''RUBBER_PENAL''  |  ''TO/TM''  |
| Thermal expansion coefficient ($\alpha$)                |  ''THERM_EXPANSION''  |  ''TO/TM''  |
| Conductivity                                            |    ''CONDUCTIVITY''   |  ''TO/TM''  |
| Heat capacity                                           |   ''HEAT_CAPACITY''   |  ''TO/TM''  |
| Dissipated thermoelastic power fraction                 |     ''DISSIP_TE''     |      -      |
| Dissipated (visco)plastic power fraction (Taylor-Quinney factor)  |     ''DISSIP_TQ''     |      -      |
===== MooneyRivlinHyperMaterial =====

=== Description ===

Mooney-Rivlin hyperelastic law, using a ''Cauchy'' stress tensor $\boldsymbol{\sigma}$, stress in the current configuration.

(Quasi-)incompressibility is treated by a volumetric/deviatoric multiplicative split of the deformation gradient, i.e.  $\bar{\mathbf{F}} = J^{-1/3}\mathbf{F}$. Hence the deviatoric potential is based on reduced invariants of $\bar{\mathbf{b}} =\bar{\mathbf{F}}\bar{\mathbf{F}}^T $.

$$
 W\left(I_1,I_2,J\right)  =  \bar{W}\left(\bar{I_1},\bar{I_2}\right) + K f\left(J\right) = C_1\left(\bar{I_1} - 3\right) + C_2\left(\bar{I_2} - 3\right)+ \frac{k_0}{2}\left[ \left(J-1\right)^2 + \ln^2 J\right]
$$


=== Parameters ===
^   Name                             ^  Metafor Code           ^  Dependency ^
| Density                            |  ''MASS_DENSITY''         |  ''TO/TM''  |
| Mooney-Rivlin coefficient ($C_1$)  |   ''RUBBER_C1''           |  ''TO/TM''  |
| Mooney-Rivlin coefficient ($C_2$)  |   ''RUBBER_C2''           |  ''TO/TM''  |
| Initial bulk modulus ($k_0$)       |  ''RUBBER_PENAL''         |  ''TO/TM''  |
| Material temperature evolution law                      |  ''TEMP''  |    ''TM''   |
| Thermal expansion coefficient ($\alpha$)                |  ''THERM_EXPANSION''  |  ''TO/TM''  |


<WRAP center round important 60%>
**Version < 3554**\\
This material has no analytical material tangent stiffness. The latter should be computed by pertubation (global or material). \\
See ''STIFFMETHOD'' in the element properties of [[doc:user:elements:volumes:volumeelement|Volume elements]].
</WRAP>

===== TmMooneyRivlinHyperMaterial =====
<note important> **Metafor version $\geq$ 3554** </note>
=== Description ===

Mooney-Rivlin hyperelastic law, using a ''Cauchy'' stress tensor $\boldsymbol{\sigma}$, stress in the current configuration.

Here, the ''TEMP'' parameter is not relevant anymore.

=== Parameters ===
^   Name                                                  ^  Metafor Code  ^ Dependency ^
| Density                                                 |  ''MASS_DENSITY''  |  ''TO/TM''  |
| Mooney-Rivlin coefficient ($C_1$)                          |  ''RUBBER_C1''  |  ''TO/TM''  |
| Mooney-Rivlin coefficient ($C_2$)  |   ''RUBBER_C2''           |  ''TO/TM''  |
| Initial bulk modulus ($k_0$)                            |  ''RUBBER_PENAL''  |  ''TO/TM''  |
| Thermal expansion coefficient ($\alpha$)                |  ''THERM_EXPANSION''  |  ''TO/TM''  |
| Conductivity                                            |    ''CONDUCTIVITY''   |  ''TO/TM''  |
| Heat capacity                                           |   ''HEAT_CAPACITY''   |  ''TO/TM''  |
| Dissipated thermoelastic power fraction                 |     ''DISSIP_TE''     |      -      |
| Dissipated (visco)plastic power fraction (Taylor-Quinney factor)  |     ''DISSIP_TQ''     |      -      |

===== HolzapfelGasserOgdenHyperMaterial =====

=== Description ===
Holzapfel-Gasser-Ogden (invariant-based) anisotropic hyperelastic law, using a ''Cauchy'' stress tensor $\boldsymbol{\sigma}$, stress in the current configuration. This model is particularly suited to predict the response of **biological tissues**.

(Quasi-)incompressibility is treated by a volumetric/deviatoric multiplicative split of the deformation gradient, i.e.  $\bar{\mathbf{F}} = J^{-1/3}\mathbf{F}$. Hence the deviatoric potential is based on reduced invariants of $\bar{\mathbf{b}} =\bar{\mathbf{F}}\bar{\mathbf{F}}^T $.

The strain-energy density function $W$ is expressed as the sum of an **isotropic** (=**matrix**) and **anisotropic** (=**fibers**) contribution:
$$
W\left(\bar{I}_1,\bar{I}_4,J \right) = W_{iso}\left(\bar{I}_1,J \right) + W_{ani}\left(\bar{I}_1,\bar{I}_4\right)
$$

The **isotropic** contribution takes the form of a **generalized Neo-Hookean** model:
$$
W_{iso}\left(\bar{I}_1,J \right) = C_1\left(\bar{I}_1 -3\right) +K f\left(J\right) = C_1\left(\bar{I}_1 -3\right) +\frac{k_0}{2}\text{ln}^2 J
$$

The **anisotropic** contribution to the strain energy density function writes:
$$
W_{ani}\left(\bar{I}_1,\bar{I}_4\right) = \frac{k_1}{2k_2} \sum_{\alpha=1}^n \left[ e^{k_2\left<E_\alpha \right>^2} - 1 \right] = \frac{k_1}{2k_2} \sum_{\alpha=1}^n \left[ e^{k_2\left<d(\bar{I}_1-3)+(1-3d)(\bar{I}_4^\alpha - 1)\right>^2} - 1 \right],
$$
where $k_1$[MPa] and $k_2$[-] are material parameters characterizing all fiber families in the material. $d\in[0,~\frac{1}{3}]$ is a parameter accounting for **fiber dispersion**, with $d=0$ corresponding to **perfectly aligned** fibers whilst $d=\frac{1}{3}$ corresponds to **randomly oriented** fibers (isotropic response). The model adds up to three different families of fibers ($\alpha \leq 3$), with their initial orientation given by $\mathbf{a}^\alpha = \left[a_{\alpha x},~a_{\alpha y},~a_{\alpha z} \right]$. Fiber directions do not have to be orthogonal.

More information and mathematical derivations, such as the analytical tangent stiffness matrix, can be found in {{ :doc:user:elements:volumes:metafor_hgo.pdf |}}.

=== Parameters ===
^   Name                             ^  Metafor Code           ^ 
| Density                            |''MASS_DENSITY''         |  
| Mooney-Rivlin coefficient ($C_1$)  | ''RUBBER_C1''           |  
| Initial bulk modulus ($k_0$)       |''RUBBER_PENAL''         |  
| HGO parameter $k_1$   |''HGO_K1''  |
| HGO parameter $k_2$   |''HGO_K2''  |
| Fiber dissipation $d$ (optional, default=0)  |''HGO_DISP''  |
| Direction of $1^{st}$ fiber family $\mathbf{a}^1$  | ''HGO_FIB1_X'', ''HGO_FIB1_Y'', ''HGO_FIB1_Z''  |
| Direction of $2^{nd}$ fiber family $\mathbf{a}^2$  | ''HGO_FIB2_X'', ''HGO_FIB2_Y'', ''HGO_FIB2_Z''  |
| Direction of $3^{rd}$ fiber family $\mathbf{a}^3$  | ''HGO_FIB3_X'', ''HGO_FIB3_Y'', ''HGO_FIB3_Z''  |

===== NeoHookeanHyperPk2Material =====

=== Description ===

Neo-Hookean hyperelastic law, using a ''PK2'' tensor.

The potential per unit volume is computed based on the average compressibility over the element, ($\theta$): 

$$
U^{vol}=\dfrac{k_0}{2} \left[\ln\right(\theta\left)\right]^2
$$

The deviatoric potential is computed based on a Cauchy tensor with a unit determinant:

$$
U^{dev}=\dfrac{g_0}{2} \left[\text{tr}\right(\hat{\mathbf{C}}\left)-3\right]
$$

=== Parameters ===

^   Name                                                  ^     Metafor Code   ^ Dependency ^
| Density                                                 |  ''MASS_DENSITY''  |  ''TO/TM''  |
| Initial bulk modulus ($k_0$)                            |    ''HYPER_K0''    |  ''TO/TM''  |
| Initial shear modulus ($g_0$)                           |    ''HYPER_G0''    |  ''TO/TM''  |
| Material temperature evolution law                      |  ''TEMP''  |    ''TM''   |
| Thermal expansion coefficient ($\alpha$)                |  ''THERM_EXPANSION''  |  ''TO/TM''  |

===== LogarihtmicHyperPk2Material =====

=== Description ===

Logarithmic hyperelastic law, using a ''PK2'' tensor.

The potential per unit volume is computed based on the average compressibility of the element, ($\theta$): 

$$
U^{vol}=\dfrac{k_0}{2} \left[\ln\right(\theta\left)\right]^2
$$

The deviatoric potential is computed based on a Cauchy tensor with a unit determinant:

$$
U^{dev}= \dfrac{g_0}{4} \ln \left(\hat{\mathbf{C}}\right):\ln \left(\hat{\mathbf{C}}\right)
$$

=== Parameters ===

^   Name                                             ^     Metafor Code     ^ Dependency ^
| Density                                                 |  ''MASS_DENSITY''  |  ''TO/TM''  |
| Initial bulk modulus ($k_0$)  |    ''HYPER_K0''    |  ''TO/TM''  |
| Initial shear modulus ($g_0$)     |    ''HYPER_G0''    |  ''TO/TM''  |
| Material temperature evolution law                      |  ''TEMP''  |    ''TM''   |
| Thermal expansion coefficient ($\alpha$)                |  ''THERM_EXPANSION''  |  ''TO/TM''  |


===== EvpIsoHLogarithmicHyperPk2Material =====

=== Description ===
Logarithmic hyperelastic law, using a ''PK2'' tensor.

The potential per unit volume is computed based on the average compressibility of the element, ($\theta$): 

$$
U^{vol}=\dfrac{k_0}{2} \left[\ln\right(\theta\left)\right]^2
$$

The deviatoric potential is computed based on a Cauchy tensor with a unit determinant:

$$
U^{dev}= \dfrac{g_0}{4} \ln \left(\hat{\mathbf{C}}^{el}\right):\ln \left(\hat{\mathbf{C}}^{el}\right)
$$

=== Parameters ===

^   Name                                                                     ^     Metafor Code     ^  Dependency ^
| Density                                                                    |  ''MASS_DENSITY''  |  ''TO/TM''  |
| Initial bulk modulus ($k_0$)                                               |    ''HYPER_K0''    |  ''TO/TM''  |
| Initial shear modulus ($g_0$)                                              |    ''HYPER_G0''    |  ''TO/TM''  |
| Number of the material law which defines the yield stress $\sigma_{yield}$ |    ''YIELD_NUM''   |    -     |
| Material temperature evolution law                      |  ''TEMP''  |    ''TM''   |
| Thermal expansion coefficient ($\alpha$)                |  ''THERM_EXPANSION''  |  ''TO/TM''  |

===== FunctionBasedHyperPk2Material =====

=== Description ===

Hyperelastic law, using a ''PK2'' tensor. Its function applied on the strain spectral decomposition is a user law.

The potential per unit volume is computed based on the average compressibility of the element, ($\theta$): 

$$
U^{vol}=\dfrac{k_0}{2} \left[\ln\right(\theta\left)\right]^2
$$

The deviatoric potential is computed based on a hyperelastic user function defined in [[doc:user:elements:volumes:hyper_viscoelastic]].

=== Parameters ===

^   Name                                                  ^     Metafor Code     ^  Dependency ^
| Density                                                 |  ''MASS_DENSITY''           |  ''TO/TM''  |
| Initial bulk modulus ($k_0$)                            |    ''HYPER_K0''             |  ''TO/TM''  |
| Number of the hyperelastic law                          |    ''HYPER_FUNCTION_NO''    |    -     |
| Material temperature evolution law                      |  ''TEMP''  |    ''TM''   |
| Thermal expansion coefficient ($\alpha$)                |  ''THERM_EXPANSION''  |  ''TO/TM''  |


===== VeIsoHyperPk2Material =====

=== Description ===

Viscoelastic hyperelastic law, using a ''PK2'' tensor. The law includes a main branch (spring and dashpot in parallel) and one or several Maxwell branches (spring and dashpot in series).

Each branch has its behavior corresponding to a viscoelastic law, supplied by the user.

The potential per unit volume is computed based on the average compressibility of the element, ($\theta$): 

$$
U^{vol}=\dfrac{k_0}{2} \left[\ln\right(\theta\left)\right]^2
$$

The deviatoric potential is computed based on the viscoelastic laws :

$$
U^{dev}= U^{dev}_{\text{main,elastic}}\left(\hat{C}\right) + \sum_{Maxwell} U^{dev}_{\text{Maxwell,elastic}}\left(\hat{C}^{\text{el}}\right)
$$

The dissipation potential is written as:

$$
\Delta t \phi^{dev}= \Delta t \phi^{dev}_{\text{main,viscous}}\left( \exp{\frac{\ln{\Delta\hat{C}}}{\Delta t}}   \right) + \sum_{Maxwell} \Delta t \phi^{dev}_{\text{Maxwell,viscous}}\left(\exp{\frac{\ln{\Delta C^{\text{vis}}}}{\Delta t}}   \right)
$$

where
$$
\Delta\hat{C} = {\hat{F}^n}^{-T} \hat{C}^{n+1} {\hat{F}^n}^{-1}
$$

$$
\Delta C^{\text{vis}} = {{F^{\text{vis}}}^n}^{-T} {C^{\text{vis}}}^{n+1} {{F^{\text{vis}}}^n}^{-1}
$$

The potentials $ U^{dev}_{\text{main,elastic}},~~U^{dev}_{\text{Maxwell,elastic}},~~\phi^{dev}_{\text{main,viscous}},~~\phi^{dev}_{\text{Maxwell,viscous}} $ are hyperelastic functions defined in [[doc:user:elements:volumes:hyper_viscoelastic]].

=== Parameters ===

^   Name                                             ^     Metafor Code     ^  Dependency ^
| Density                                                 |    ''MASS_DENSITY''         |  ''TO/TM''  |
| Initial bulk modulus ($k_0$)  |    ''HYPER_K0''             |  ''TO/TM''  |
| Number of the main viscoelastic law              |    ''MAIN_FUNCTION_NO''     |    -     | 
| Number of the first Maxwell viscoelastic law      |    ''MAXWELL_FUNCTION_NO1'' |    -     |
| Number of the second Maxwell viscoelastic law (optional)    |    ''MAXWELL_FUNCTION_NO2'' |    -     |
| Number of the third Maxwell viscoelastic law (optional)    |    ''MAXWELL_FUNCTION_NOI'' |    -     |
| Material temperature evolution law                      |  ''TEMP''  |    ''TM''   |
| Thermal expansion coefficient ($\alpha$)                |  ''THERM_EXPANSION''  |  ''TO/TM''  |