Extended documentation for solid materials

doc/documentation/CMakeLists.txt

@@ -56,6 +56,25 @@ if(FOUR_C_ENABLE_DOCUMENTATION)
       ${PROJECT_SOURCE_DIR}/tests/input_files/constr2D_MPC_angle.4C.yaml
       ${PROJECT_SOURCE_DIR}/tests/input_files/elch_gaussian_hill_pbc_genalpha.4C.yaml
       ${PROJECT_SOURCE_DIR}/tests/input_files/rve3d_periodic_bcs.4C.yaml
+      ${PROJECT_SOURCE_DIR}/tests/input_files/plastic_pressurisedcylinder.4C.yaml
+      ${PROJECT_SOURCE_DIR}/tests/input_files/tsi_plastic_heating_monolithic.4C.yaml
+      ${PROJECT_SOURCE_DIR}/tests/input_files/mat_druckerprager_RetToCone.4C.yaml
+      ${PROJECT_SOURCE_DIR}/tests/input_files/mat_gtn_patch_test.4C.yaml
+      ${PROJECT_SOURCE_DIR}/tests/input_files/plastic_necking_damage.4C.yaml
+      ${PROJECT_SOURCE_DIR}/tests/input_files/tsi_pressurisedcylinder_robinson.4C.yaml
+      ${PROJECT_SOURCE_DIR}/tests/input_files/plastic_necking_fbar_thrplast.4C.yaml
+      ${PROJECT_SOURCE_DIR}/tests/input_files/plastic_necking_fbar_vcu.4C.yaml
+      ${PROJECT_SOURCE_DIR}/tests/input_files/mat_viscoplastic_no_yield_surface_1hex8.4C.yaml
+      ${PROJECT_SOURCE_DIR}/tests/input_files/mat_iso_viscoplast_refJC_log_timint.4C.yaml
+      ${PROJECT_SOURCE_DIR}/tests/input_files/structure_bidomain_material_problem_torsion.4C.yaml
+      ${PROJECT_SOURCE_DIR}/tests/input_files/tsi_lindilatation_geolin.4C.yaml
+      ${PROJECT_SOURCE_DIR}/tests/input_files/f3_womersley.4C.yaml
+      ${PROJECT_SOURCE_DIR}/tests/input_files/elasthyper_coupanisoexpo.4C.yaml
+      ${PROJECT_SOURCE_DIR}/tests/input_files/elasthyper_isoogden.4C.yaml
+      ${PROJECT_SOURCE_DIR}/tests/input_files/elasthyper_isoanisoexpo_DispersedTransverselyIsotropic_ost_h8.4C.yaml
+      ${PROJECT_SOURCE_DIR}/tests/input_files/viscoAnisotropic_creep.4C.yaml
+      ${PROJECT_SOURCE_DIR}/tests/input_files/viscoelasthyper.4C.yaml
+      ${PROJECT_SOURCE_DIR}/tests/input_files/mat_ogden_tca_hex.4C.yaml
       )
 
   set(_sphinx_FILES_FROM_TESTS_DIR "${_sphinx_OUT_DIR}/testfiles")

doc/documentation/src/analysis_guide_templates/elastic_materials.rst.j2

@@ -0,0 +1,170 @@
+{% set stvenant_file = "structure_bidomain_material_problem_torsion.4C.yaml" %}
+{% set stvenant = load_input_file(stvenant_file) %}
+{% set thermo_stvenant_file = "tsi_lindilatation_geolin.4C.yaml" %}
+{% set thermo_stvenant = load_input_file(thermo_stvenant_file) %}
+{% set aaa_file = "f3_womersley.4C.yaml" %}
+{% set aaa = load_input_file(aaa_file) %}
+{% set elasthyper_file = "elasthyper_coupanisoexpo.4C.yaml" %}
+{% set elasthyper = load_input_file(elasthyper_file) %}
+{% set ogden_tca_file = "mat_ogden_tca_hex.4C.yaml" %}
+{% set ogden_tca = load_input_file(ogden_tca_file) %}
+
+.. _elastic-materials:
+
+Elastic materials
+=================
+
+This page summarizes the elastic materials that are assigned directly to 2D and 3D solid
+elements. Materials that are composed of hyperelastic energy summands are documented
+separately in :doc:`hyperelastic_framework`.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 18 42
+
+   * - Material
+     - Kinematics
+     - Application
+   * - :ref:`MAT_Struct_StVenantKirchhoff <elastic-stvenant>`
+     - Linear or nonlinear
+     - Isotropic St. Venant--Kirchhoff elasticity.
+   * - :ref:`MAT_Struct_StVenantKirchhoffOrthotropic <elastic-orthotropic-stvenant>`
+     - Linear or nonlinear
+     - Orthotropic St. Venant--Kirchhoff elasticity.
+   * - :ref:`MAT_Struct_ThermoStVenantK <elastic-thermo-stvenant>`
+     - Linear or nonlinear
+     - Temperature-dependent St. Venant--Kirchhoff elasticity.
+   * - :ref:`MAT_Struct_AAANeoHooke <elastic-aaa-neohooke>`
+     - Nonlinear
+     - Nonlinear arterial-wall elasticity.
+   * - :ref:`MAT_Ogden_TCA <elastic-ogden-tca>`
+     - Nonlinear
+     - Ogden hyperelasticity with independently controlled tension--compression asymmetry.
+   * - :ref:`MAT_ElastHyper <elastic-elasthyper>`
+     - Nonlinear
+     - General composition of hyperelastic energy summands.
+
+.. _elastic-stvenant:
+
+``MAT_Struct_StVenantKirchhoff``
+--------------------------------
+
+This isotropic material is linear in Green--Lagrange strain and second Piola--Kirchhoff stress.
+With ``KINEM: linear`` it represents standard small-strain elasticity. With
+``KINEM: nonlinear`` it retains the same constitutive law but includes geometric nonlinearity;
+the model is not suitable for arbitrary large strains because its energy loses physical
+realism under strong compression.
+
+``YOUNG``, ``NUE``, and ``DENS`` define the material. See
+:ref:`MAT_Struct_StVenantKirchhoff in the Input Parameter Reference
+<MATERIALS_MAT_Struct_StVenantKirchhoff>`. The following material section is taken from
+``{{ stvenant_file }}``:
+
+{{ section_dump(stvenant, "MATERIALS") }}
+
+The material does not register model-specific Gauss-point output.
+
+.. _elastic-orthotropic-stvenant:
+
+``MAT_Struct_StVenantKirchhoffOrthotropic``
+-------------------------------------------
+
+This is the orthotropic counterpart of the St. Venant--Kirchhoff material. Three Young's moduli,
+three shear moduli, and three Poisson ratios define the material axes. It accepts both linear and
+nonlinear total-Lagrangian kinematics. The principal material directions are fixed to the
+Cartesian axes of the reference configuration; the material provides no input for rotating this
+orthotropic coordinate system. A different orientation therefore requires a correspondingly
+oriented reference mesh or an extension of the material model.
+
+The vectors ``YOUNG``, ``SHEAR``, and ``NUE`` contain the directional elastic constants;
+``DENS`` sets density. See
+:ref:`MAT_Struct_StVenantKirchhoffOrthotropic in the Input Parameter Reference
+<MATERIALS_MAT_Struct_StVenantKirchhoffOrthotropic>`. Its definition is included in
+``{{ stvenant_file }}`` above.
+
+The material does not register model-specific Gauss-point output.
+
+.. _elastic-thermo-stvenant:
+
+``MAT_Struct_ThermoStVenantK``
+------------------------------
+
+This thermoelastic St. Venant--Kirchhoff model adds isotropic thermal strain and allows a list of
+Young's moduli for temperature-dependent applications. It accepts linear and nonlinear
+total-Lagrangian kinematics.
+
+``YOUNGNUM`` and ``YOUNG`` define the elastic-modulus data. ``NUE``, ``DENS``, ``THEXPANS``, and
+``INITTEMP`` specify Poisson's ratio, density, thermal expansion, and reference temperature. See
+:ref:`MAT_Struct_ThermoStVenantK in the Input Parameter Reference
+<MATERIALS_MAT_Struct_ThermoStVenantK>`. The following material section is taken from
+``{{ thermo_stvenant_file }}``:
+
+{{ section_dump(thermo_stvenant, "MATERIALS") }}
+
+.. _elastic-aaa-neohooke:
+
+``MAT_Struct_AAANeoHooke``
+--------------------------
+
+This nonlinear isotropic material implements the arterial-wall model of Raghavan and Vorp. It
+requires ``KINEM: nonlinear`` and is intended for nearly incompressible soft-tissue response.
+
+``YOUNG`` and ``BETA`` are its constitutive parameters; ``NUE`` and ``DENS`` define Poisson's
+ratio and density. See :ref:`MAT_Struct_AAANeoHooke in the Input Parameter Reference
+<MATERIALS_MAT_Struct_AAANeoHooke>`. The following material section is taken from
+``{{ aaa_file }}``:
+
+{{ section_dump(aaa, "MATERIALS") }}
+
+.. _elastic-ogden-tca:
+
+``MAT_Ogden_TCA``
+-----------------
+
+``MAT_Ogden_TCA`` is a nonlinear isotropic hyperelastic solid material representing the
+tension--compression asymmetric Ogden model of
+`Moerman et al. (2016) <https://doi.org/10.1016/j.jmbbm.2015.11.027>`_:
+
+.. math::
+
+   \Psi ={}& \frac{c}{m^2}\sum_{i=1}^{3}
+      \left[q\left(\lambda_i^m-1\right)
+      +(1-q)\left(\lambda_i^{-m}-1\right)\right] \\
+      &+\frac{c}{m}(1-2q)\ln J+\frac{\kappa}{2}(J-1)^2 ,
+
+where :math:`\lambda_i` are the principal stretches and :math:`J=\det\boldsymbol F`.
+``C`` (:math:`c>0`) scales the material stiffness and ``M`` (:math:`m>0`) controls its
+nonlinearity. ``Q`` (:math:`q\in[0,1]`) independently controls tension--compression asymmetry:
+
+- :math:`q=0.5` gives a tension--compression symmetric response,
+- :math:`q>0.5` makes the material stiffer in tension than in compression, and
+- :math:`q<0.5` makes the material stiffer in compression than in tension.
+
+``KAPPA`` (:math:`\kappa>0`) is the volumetric penalty parameter. Larger values produce a more
+nearly incompressible response but do not enforce exact incompressibility and may cause poor
+conditioning or volumetric locking. ``DENS`` specifies the non-negative density. The material
+requires nonlinear total-Lagrangian kinematics.
+
+See :ref:`MAT_Ogden_TCA in the Input Parameter Reference <MATERIALS_MAT_Ogden_TCA>`. The two
+materials in the following excerpt from ``{{ ogden_tca_file }}`` differ only in ``Q`` and
+therefore demonstrate opposite asymmetry:
+
+{{ section_dump(ogden_tca, "MATERIALS") }}
+
+.. _elastic-elasthyper:
+
+``MAT_ElastHyper``
+------------------
+
+``MAT_ElastHyper`` is the general finite-strain elastic framework. It sums separately defined
+``ELAST_*`` energy contributions and requires ``KINEM: nonlinear``. ``NUMMAT`` and ``MATIDS``
+select the summands, ``DENS`` defines density, and ``POLYCONVEX`` optionally requests a
+polyconvexity check.
+
+See :ref:`MAT_ElastHyper in the Input Parameter Reference <MATERIALS_MAT_ElastHyper>` and
+:doc:`hyperelastic_framework` for composition rules and the summand catalog. The following
+material section is taken from ``{{ elasthyper_file }}``:
+
+{{ section_dump(elasthyper, "MATERIALS") }}
+
+Anisotropic combinations can provide fiber directions and summand-specific visualization data.

doc/documentation/src/analysis_guide_templates/hyperelastic_anisotropic.rst.j2

@@ -0,0 +1,94 @@
+{% set anisotropic_file = "elasthyper_isoanisoexpo_DispersedTransverselyIsotropic_ost_h8.4C.yaml" %}
+{% set anisotropic = load_input_file(anisotropic_file) %}
+
+.. _hyperelastic-anisotropic:
+
+Anisotropic, fiber, and active hyperelastic summands
+====================================================
+
+Anisotropic summands are normally combined with an isotropic matrix. Depending on the model,
+fiber information comes from element fibers, explicit fiber IDs, or an
+``ELAST_StructuralTensor`` helper.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 65
+
+   * - Summand or helper
+     - Model
+   * - :ref:`ELAST_CoupAnisoExpo <MATERIALS_ELAST_CoupAnisoExpo>`
+     - Exponential reinforcement for one fiber.
+
+       :math:`\Psi=\frac{k_1}{2k_2}\{\exp[k_2(I_4-1)^2]-1\}`.
+       ``K1COMP`` and ``K2COMP`` apply in compression.
+   * - :ref:`ELAST_CoupAnisoExpoShear <MATERIALS_ELAST_CoupAnisoExpoShear>`
+     - Exponential shear coupling between two fibers.
+
+       :math:`\Psi=\frac{k_1}{2k_2}\{\exp[k_2(I_8-
+       \boldsymbol a_1\mathbin{\cdot}\boldsymbol a_2)^2]-1\}`.
+   * - :ref:`ELAST_CoupAnisoExpoTwoCoup <MATERIALS_ELAST_CoupAnisoExpoTwoCoup>`
+     - Exponential coupling of two fiber families.
+
+       :math:`\Psi=\sum_{\alpha=4,6,8}\frac{a_\alpha}{2b_\alpha}
+       [\exp(b_\alpha x_\alpha^2)-1]`, with :math:`x_4=I_4-1`,
+       :math:`x_6=I_6-1`, and
+       :math:`x_8=I_8-\boldsymbol a_1\mathbin{\cdot}\boldsymbol a_2`.
+   * - :ref:`ELAST_CoupAnisoNeoHooke <MATERIALS_ELAST_CoupAnisoNeoHooke>`
+     - Neo-Hookean reinforcement for one fiber.
+
+       :math:`\Psi=c(I_4-1)`.
+   * - :ref:`ELAST_CoupAnisoNeoHooke_VarProp <MATERIALS_ELAST_CoupAnisoNeoHooke_VarProp>`
+     - Neo-Hookean response for one fiber with variable properties.
+
+       :math:`\Psi=c(\boldsymbol x,t)(I_4-1)`, with ``SOURCE_ACTIVATION`` defining
+       :math:`c(\boldsymbol x,t)`.
+   * - :ref:`ELAST_CoupAnisoPow <MATERIALS_ELAST_CoupAnisoPow>`
+     - Power-law energy for one fiber.
+
+       :math:`\Psi=k(I_4^{d_1}-1)^{d_2}` where active; ``ACTIVETHRES`` disables
+       its stress contribution below the selected fiber stretch.
+   * - :ref:`ELAST_CoupAnisoExpoActive <MATERIALS_ELAST_CoupAnisoExpoActive>`
+     - Exponential law for one fiber with active response.
+
+       Passive exponential potential as for ``ELAST_CoupAnisoExpo``, plus
+       :math:`\Psi_\mathrm{act}=\frac{s}{\rho}\left[\lambda_\mathrm{act}+
+       \frac{(\lambda_\mathrm{max}-\lambda_\mathrm{act})^3}
+       {3(\lambda_\mathrm{max}-\lambda_0)^2}\right]`.
+   * - :ref:`ELAST_AnisoActiveStress_Evolution
+       <MATERIALS_ELAST_AnisoActiveStress_Evolution>`
+     - Active-stress evolution law for one fiber.
+
+       No stored-energy potential; it supplies the evolving active stress
+       :math:`\boldsymbol S_\mathrm{act}=\tau(t)\boldsymbol A`.
+   * - :ref:`ELAST_IsoAnisoExpo <MATERIALS_ELAST_IsoAnisoExpo>`
+     - Combined isotropic-anisotropic exponential response for one fiber.
+
+       :math:`\Psi=\frac{k_1}{2k_2}\{\exp[k_2(\bar I_4-1)^2]-1\}`, with
+       :math:`\bar I_4=J^{-2/3}I_4`.
+   * - :ref:`ELAST_CoupTransverselyIsotropic
+       <MATERIALS_ELAST_CoupTransverselyIsotropic>`
+     - General transversely isotropic coupling for one fiber.
+
+       :math:`\Psi=[\alpha+\frac{\beta}{2}\ln I_3+\gamma(I_4-1)](I_4-1)
+       -\frac{\alpha}{2}(I_5-1)`.
+   * - :ref:`ELAST_RemodelFiber <MATERIALS_ELAST_RemodelFiber>`
+     - Remodeling contribution for a variable number of fibers.
+
+       No single fixed potential; it combines the referenced exponential fiber potentials with
+       evolving remodeling and growth histories.
+   * - :ref:`ELAST_StructuralTensor <MATERIALS_ELAST_StructuralTensor>`
+     - Structural-tensor strategy for one fiber, referenced by anisotropic summands.
+
+       No potential; it supplies :math:`\boldsymbol A`, for example
+       :math:`\boldsymbol A=\boldsymbol a\otimes\boldsymbol a` for ``Standard``.
+
+The active-stress and structural-tensor entries are state/helper models rather than independent
+strain-energy terms. Follow the linked parameter reference for required IDs and fiber strategies.
+
+Example
+-------
+
+The following dispersed transversely isotropic composition is taken from
+``{{ anisotropic_file }}``:
+
+{{ section_dump(anisotropic, "MATERIALS") }}