diff --git a/doc/documentation/CMakeLists.txt b/doc/documentation/CMakeLists.txt index 40a7387272b..69ec97b0ed3 100644 --- a/doc/documentation/CMakeLists.txt +++ b/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_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/visco_generalized_maxwell_etd_h8.4C.yaml + ${PROJECT_SOURCE_DIR}/tests/input_files/mat_ogden_tca_hex.4C.yaml + ${PROJECT_SOURCE_DIR}/tests/input_files/cardiovascular0d_arterialproxdist_structure_direct_genalpha.4C.yaml ) set(_sphinx_FILES_FROM_TESTS_DIR "${_sphinx_OUT_DIR}/testfiles") diff --git a/doc/documentation/src/analysis_guide_templates/coupling_materials.rst.j2 b/doc/documentation/src/analysis_guide_templates/coupling_materials.rst.j2 new file mode 100644 index 00000000000..b2df2aae383 --- /dev/null +++ b/doc/documentation/src/analysis_guide_templates/coupling_materials.rst.j2 @@ -0,0 +1,21 @@ +{% set input_file = "tsi_lincompression_iterstaggtemp.4C.yaml" %} +{% set input_file_content = load_input_file(input_file) %} + +.. _coupling-materials: + +Material coupling +================== + +One may use a single multiphysics element type for a multiphysics simulation with matching +discretizations. However, since each discretization belongs to a single physics representation +and can therefore be connected to only one material, the other material must be connected to the +same discretization by cloning the discretization to the other physics. + +In |FOURC|, a material mapping section connects two material models to a single representation. +The following example is taken from {{ input_file }}: + +{{ section_dump(input_file_content, ["MATERIALS", "CLONING MATERIAL MAP", "STRUCTURE ELEMENTS"]) }} + +.. todo:: + + Add a list of the discretizations that can be coupled. diff --git a/doc/documentation/src/analysis_guide_templates/elastic_materials.rst.j2 b/doc/documentation/src/analysis_guide_templates/elastic_materials.rst.j2 new file mode 100644 index 00000000000..dbb457773b6 --- /dev/null +++ b/doc/documentation/src/analysis_guide_templates/elastic_materials.rst.j2 @@ -0,0 +1,150 @@ +{% set iso_stvenant_file = "solid_runtime_hex8.4C.yaml" %} +{% set iso_stvenant = load_input_file(iso_stvenant_file) %} +{% set ortho_stvenant_file = "structure_bidomain_material_problem_torsion.4C.yaml" %} +{% set ortho_stvenant = load_input_file(ortho_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 = "cardiovascular0d_arterialproxdist_structure_direct_genalpha.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 can be used for 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 ` + - Linear or nonlinear + - Isotropic St. Venant--Kirchhoff elasticity. + * - :ref:`MAT_Struct_StVenantKirchhoffOrthotropic ` + - Linear or nonlinear + - Orthotropic St. Venant--Kirchhoff elasticity. + * - :ref:`MAT_Struct_ThermoStVenantK ` + - Linear or nonlinear + - Temperature-dependent St. Venant--Kirchhoff elasticity. + * - :ref:`MAT_Struct_AAANeoHooke ` + - Nonlinear + - Nonlinear arterial-wall elasticity. + * - :ref:`MAT_Ogden_TCA ` + - Nonlinear + - Ogden hyperelasticity with independently controlled tension--compression asymmetry. + * - :ref:`MAT_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. + +The following material section is taken from ``{{ iso_stvenant_file }}``. +See details about the parameters in :ref:`MAT_Struct_StVenantKirchhoff +in the Input Parameter Reference `. + +{{ section_dump(iso_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 following material section is taken from ``{{ ortho_stvenant_file }}``. +See details about the parameters in +:ref:`MAT_Struct_StVenantKirchhoffOrthotropic in the Input Parameter Reference +`. + +`. + +{{ section_dump(ortho_stvenant, "MATERIALS") }} + +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. + +The following material section is taken from +``{{ thermo_stvenant_file }}``. See details about the parameters in +:ref:`MAT_Struct_ThermoStVenantK in the Input Parameter Reference `. + +{{ 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. + +The following material section is taken from ``{{ aaa_file }}``. +See details about the parameters in +:ref:`MAT_Struct_AAANeoHooke in the Input Parameter Reference +`. + +{{ 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) `_, +where the tension-compression asymmetry is controlled by the ``Q`` parameter. + +The two materials in the following excerpt from ``{{ ogden_tca_file }}`` differ only in ``Q`` and +therefore demonstrate opposite tension-compression asymmetry. See more details of the parameters +in the :ref:`Input Parameter Reference for MAT_Ogden_TCA `: + +{{ 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``; +see :ref:`MAT_ElastHyper in the Input Parameter Reference ` and +:doc:`hyperelastic_framework` for further parameters, 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. diff --git a/doc/documentation/src/analysis_guide_templates/fluid_materials.rst.j2 b/doc/documentation/src/analysis_guide_templates/fluid_materials.rst.j2 new file mode 100644 index 00000000000..132ddbf29e9 --- /dev/null +++ b/doc/documentation/src/analysis_guide_templates/fluid_materials.rst.j2 @@ -0,0 +1,7 @@ +.. _fluid-materials: + +Fluid materials +=============== + +Fluid material models define the constitutive behavior of fluids. Their available parameters are +documented in the :doc:`../reference_guide/materials_reference` \ No newline at end of file diff --git a/doc/documentation/src/analysis_guide_templates/hyperelastic_anisotropic.rst.j2 b/doc/documentation/src/analysis_guide_templates/hyperelastic_anisotropic.rst.j2 new file mode 100644 index 00000000000..aa07c315f83 --- /dev/null +++ b/doc/documentation/src/analysis_guide_templates/hyperelastic_anisotropic.rst.j2 @@ -0,0 +1,63 @@ +{% 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 or nodal fibers. The distribution of fibers can be +controlled by the structural tensor, which is supplied by the ``ELAST_StructuralTensor`` helper, +its evolution can be controlled by the ``ELAST_AnisoActiveStress_Evolution`` helper. +The strain-energy formulation of each summand is documented in the Input Parameter Reference. +Follow the linked parameter reference for the exact formulation, required IDs, and fiber strategies. + +.. list-table:: + :header-rows: 1 + :widths: 40 60 + + * - Summand or helper + - Model + * - :ref:`ELAST_CoupAnisoExpo ` + - Exponential reinforcement for one fiber. + * - :ref:`ELAST_CoupAnisoExpoShear ` + - Exponential shear coupling between two fibers. + * - :ref:`ELAST_CoupAnisoExpoTwoCoup ` + - Exponential coupling of two fiber families. + * - :ref:`ELAST_CoupAnisoNeoHooke ` + - Neo-Hookean reinforcement for one fiber. + * - :ref:`ELAST_CoupAnisoNeoHooke_VarProp ` + - Neo-Hookean response for one fiber with variable properties. + * - :ref:`ELAST_CoupAnisoPow ` + - Power-law energy for one fiber. + * - :ref:`ELAST_CoupAnisoExpoActive ` + - Exponential law for one fiber with active response. + * - :ref:`ELAST_IsoAnisoExpo ` + - Combined isotropic-anisotropic exponential response for one fiber. + * - :ref:`ELAST_CoupTransverselyIsotropic + ` + - General transversely isotropic coupling for one fiber. + * - :ref:`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_AnisoActiveStress_Evolution + ` + - Active-stress evolution law for one fiber. + + No stored-energy potential; it supplies the evolving active stress. + * - :ref:`ELAST_StructuralTensor ` + - Structural-tensor strategy for one fiber, that is, the distribution of the fiber in a specific direction; + referenced by anisotropic summands. + + This is not a potential; it supplies the structural tensor used by the anisotropic summands above. + +Example +------- + +The following dispersed transversely isotropic composition is taken from +``{{ anisotropic_file }}``: + +{{ section_dump(anisotropic, "MATERIALS") }} diff --git a/doc/documentation/src/analysis_guide_templates/hyperelastic_framework.rst.j2 b/doc/documentation/src/analysis_guide_templates/hyperelastic_framework.rst.j2 new file mode 100644 index 00000000000..50fec56e495 --- /dev/null +++ b/doc/documentation/src/analysis_guide_templates/hyperelastic_framework.rst.j2 @@ -0,0 +1,145 @@ +{% set framework_file = "cardiovascular0d_arterialproxdist_structure_direct_genalpha.4C.yaml" %} +{% set framework = load_input_file(framework_file) %} + +.. _hyperelastic-framework: + +Hyperelastic framework +====================== + +``MAT_ElastHyper`` constructs a strain-energy function by summing separately registered +``ELAST_*`` contributions: + +.. math:: + + \Psi = \sum_{a=1}^{n_\mathrm{mat}} \Psi_a. + +One material is the *parent material*, which is assigned to the element. +This material entry does not define its properties (except the density of the material), but contains +pointers to the energy summands. +Its children, denoted by the parameter ``MATIDS``, refer to the material IDs of these summands (see example below). + +Notation for the potentials +--------------------------- + +The summands :math:`\Psi_a` state the strain-energy density implemented by each contribution, +based on the deformation gradient :math:`\boldsymbol F` and the right Cauchy-Green deformation tensor +:math:`\boldsymbol C` or the Green-Lagrange strain tensor :math:`\boldsymbol E`: + +.. math:: + + \boldsymbol C = \boldsymbol F^\mathrm{T}\boldsymbol F \quad , \quad + \boldsymbol E = \tfrac12(\boldsymbol C-\boldsymbol I)\quad , \quad + J = \det\boldsymbol F, + +They are either based on strain invariants + +.. math:: + + I_1 = \operatorname{tr}\boldsymbol C \quad , \quad + I_2 = \tfrac12\left[(\operatorname{tr}\boldsymbol C)^2 + -\operatorname{tr}(\boldsymbol C^2)\right] \quad , \quad + I_3 = \det\boldsymbol C=J^2, + +or on principal stretches :math:`\lambda_i`, which are the positive square roots of the eigenvalues of +:math:`\boldsymbol C`. + +We can define distortional quantities, that don't account for volume changes and carry an overbar, +often colled *modified deformation gradient* and *modified Cauchy-Green deformation tensor*: + +.. math:: + + \bar{\boldsymbol C}=J^{-2/3}\boldsymbol C,\qquad + \bar I_1=J^{-2/3}I_1,\qquad + \bar I_2=J^{-4/3}I_2,\qquad + \bar\lambda_i=J^{-1/3}\lambda_i. + +For a reference fiber direction :math:`\boldsymbol a` and two-family directions +:math:`\boldsymbol a_1,\boldsymbol a_2`, the anisotropic invariants are + +.. math:: + + I_4 &= \boldsymbol a\mathbin{\cdot}\boldsymbol C\boldsymbol a \quad, \quad + &I_5 &= \boldsymbol a\mathbin{\cdot}\boldsymbol C^2\boldsymbol a,\\ + I_6 &= \boldsymbol a_2\mathbin{\cdot}\boldsymbol C\boldsymbol a_2 \quad, \quad + &I_8 &= \tfrac12(\boldsymbol a_1\otimes\boldsymbol a_2+ + \boldsymbol a_2\otimes\boldsymbol a_1):\boldsymbol C . + +Choosing summands +----------------- + +There are two common ways to define the full hyperelastic response: + +- A **coupled** contribution depends on the full deformation and already contains distortional + and volumetric response. +- A **split** formulation usually combines any number of isochoric ``ELAST_Iso*`` contributions + with any number of ``ELAST_Vol*`` contributions. It is also possible (but less common) to add + coupled laws (``ELAST_Coup*``) as well. + +Composition rules and limiting cases +------------------------------------ + +The framework adds all referenced potentials and does not require a particular number of +isochoric, volumetric, or coupled summands. Consequently, the following combinations are +technically possible: + +- Any number of isochoric, volumetric and combined summands may be included. +- If a model contains only isochoric terms, its energy is independent of :math:`J`. This gives + zero volumetric stress and stiffness; it does **not** impose :math:`J=1` or otherwise prescribe + incompressibility. Without a separate constraint, such a model offers no resistance to volume + change and is generally unsuitable for a displacement-based solid. + +Incompressibility and rubber-like materials +------------------------------------------- + +Classical incompressible hyperelastic laws, e.g., the isochoric NeoHooke, Mooney-Rivlin, Yeoh, etc. models, often +state only an isochoric energy :math:`\Psi_\mathrm{iso}` because incompressibility is imposed +separately through a pressure Lagrange multiplier: + +.. math:: + + \Psi=\Psi_\mathrm{iso}(\bar{\boldsymbol C})+p(J-1). + +The absence of a :math:`J`-dependent term in such a law therefore does not itself enforce :math:`J=1`. +In this framework, rubber-like behavior is commonly represented as **nearly incompressible** by +combining the isochoric law with a volumetric penalty: + +.. math:: + + \Psi=\Psi_\mathrm{iso}(\bar{\boldsymbol C})+U(J). + +For example, ``ELAST_VolPenalty`` penalizes volume changes through + +.. math:: + + U(J)=\epsilon\left(J^\gamma+J^{-\gamma}-2\right). + +.. note:: + + A sufficiently large penalty parameter or bulk modulus keeps :math:`J` close to one, but does not + enforce exact incompressibility. Increasing it excessively can lead to poor conditioning and + volumetric locking. Suitable EAS or F-bar element technology can alleviate locking for nearly + incompressible displacement-based solids, but does not itself impose :math:`J=1`. + +The plain ``MAT_ElastHyper`` framework accepts elastic summands only. Use +:doc:`viscoelastic_materials` when adding time-dependent branches. + +Summand catalogs +---------------- + +.. toctree:: + :maxdepth: 1 + + hyperelastic_isotropic_coupled + hyperelastic_isochoric_volumetric + hyperelastic_anisotropic + +Example +--------- + +Here, the parent materials, which consist of two coupled material parts each, are assigned to the element. +They combine a compressible isotropic matrix with an anisotropic fiber contribution and its structural-tensor definition. +Their ``MATIDS``, that is, the material laws of the summation parts, refer to the material IDs of the energy summands, +which are given as separate material IDs in the ``MATERIALS`` section. +The example is taken from ``{{ framework_file }}``. + +{{ section_dump(framework, "MATERIALS") }} diff --git a/doc/documentation/src/analysis_guide_templates/hyperelastic_isochoric_volumetric.rst.j2 b/doc/documentation/src/analysis_guide_templates/hyperelastic_isochoric_volumetric.rst.j2 new file mode 100644 index 00000000000..5b459d0b971 --- /dev/null +++ b/doc/documentation/src/analysis_guide_templates/hyperelastic_isochoric_volumetric.rst.j2 @@ -0,0 +1,69 @@ +{% set split_file = "elasthyper_isoogden.4C.yaml" %} +{% set split = load_input_file(split_file) %} + +.. _hyperelastic-isochoric-volumetric: + +Isochoric and volumetric hyperelastic summands +============================================== + +Split hyperelasticity represents distortional and volumetric response separately. Combine at +least one isochoric contribution with one suitable volumetric contribution. The strain-energy +formulation of each summand is documented in the Input Parameter Reference. + +Isochoric summands +------------------ + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - Summand + - Model + * - :ref:`ELAST_IsoNeoHooke ` + - Isochoric Neo-Hookean elasticity. + * - :ref:`ELAST_IsoMooneyRivlin ` + - Isochoric Mooney--Rivlin elasticity. + * - :ref:`ELAST_IsoOgden ` + - Isochoric Ogden elasticity. + * - :ref:`ELAST_IsoYeoh ` + - Isochoric Yeoh elasticity. + * - :ref:`ELAST_IsoVarga ` + - Isochoric Varga elasticity. + * - :ref:`ELAST_Iso1Pow ` + - One-term isochoric power law. + * - :ref:`ELAST_Iso2Pow ` + - Two-term isochoric power law. + * - :ref:`ELAST_IsoExpoPow ` + - Isochoric exponential-power energy. + * - :ref:`ELAST_IsoMuscle_Blemker ` + - Passive isochoric muscle response. + + No scalar potential is evaluated; passive and time-dependent active stresses are assembled + from the piecewise muscle force laws. + * - :ref:`ELAST_IsoTestMaterial ` + - Test material intended for verification rather than production modeling. + +Volumetric summands +------------------- + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - Summand + - Model + * - :ref:`ELAST_VolPenalty ` + - Volumetric penalty energy. + * - :ref:`ELAST_VolOgden ` + - Ogden-type volumetric energy. + * - :ref:`ELAST_VolPow ` + - Power-law volumetric energy. + * - :ref:`ELAST_VolSussmanBathe ` + - Sussman--Bathe volumetric energy. + +Example +------- + +The following split Ogden definition is taken from ``{{ split_file }}``: + +{{ section_dump(split, "MATERIALS") }} diff --git a/doc/documentation/src/analysis_guide_templates/hyperelastic_isotropic_coupled.rst b/doc/documentation/src/analysis_guide_templates/hyperelastic_isotropic_coupled.rst new file mode 100644 index 00000000000..3b01da9e591 --- /dev/null +++ b/doc/documentation/src/analysis_guide_templates/hyperelastic_isotropic_coupled.rst @@ -0,0 +1,46 @@ +.. _hyperelastic-isotropic-coupled: + +Coupled isotropic hyperelastic summands +======================================= + +These summands define compressible isotropic energies that depend on the full deformation. They +are referenced through the parameter ``MATIDS`` and generally do not require a separate +volumetric summand. The strain-energy formulation of each summand is documented in the Input +Parameter Reference. + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - Summand + - Model + * - :ref:`ELAST_CoupNeoHooke ` + - Compressible Neo-Hookean elasticity. + * - :ref:`ELAST_CoupLogNeoHooke ` + - Logarithmic Neo-Hookean elasticity. + * - :ref:`ELAST_CoupLogMixNeoHooke ` + - Mixed logarithmic Neo-Hookean formulation. + * - :ref:`ELAST_CoupMooneyRivlin ` + - Compressible Mooney--Rivlin elasticity. + * - :ref:`ELAST_CoupBlatzKo ` + - Blatz--Ko compressible elasticity. + * - :ref:`ELAST_CoupSimoPister ` + - Simo--Pister compressible elasticity. + * - :ref:`ELAST_CoupSVK ` + - St. Venant--Kirchhoff energy as a summand. + * - :ref:`ELAST_CoupExpPol ` + - Exponential-polynomial energy. + * - :ref:`ELAST_Coup1Pow ` + - One-term power-law energy. + * - :ref:`ELAST_Coup2Pow ` + - Two-term power-law energy. + * - :ref:`ELAST_Coup3Pow ` + - Three-term power-law energy. + * - :ref:`ELAST_Coup13aPow ` + - Specialized coupled polynomial energy. + * - :ref:`ELAST_CoupVarga ` + - Compressible Varga elasticity. + +The linked Input Parameter Reference entries define the strain-energy formulation, coefficients, +and parameterization of each energy. A representative ``ELAST_CoupNeoHooke`` composition is shown +on :doc:`hyperelastic_framework`. \ No newline at end of file diff --git a/doc/documentation/src/analysis_guide_templates/material_directions.rst.j2 b/doc/documentation/src/analysis_guide_templates/material_directions.rst.j2 new file mode 100644 index 00000000000..9cbaa0ab8fe --- /dev/null +++ b/doc/documentation/src/analysis_guide_templates/material_directions.rst.j2 @@ -0,0 +1,59 @@ +.. _material-directions: + +Anisotropy: Material directions +================================ + +For anisotropic materials, it is necessary to define the material directions with respect to the +global coordinate system. +In |FOURC|, the coordinate directions in such materials can be defined in several ways, but the +definition depends on the material in use. For a number of materials, the directions are defined +on element or on node level. For others, the directions are given in the material definition by fiber direction fields. +In the hyperelastic framework, the distribution of fibers around the main axes can be defined by a +structural tensor. + +Here, we describe the input methods on element level. +For a native |FOURC| mesh, append consecutive ``FIBER1``, and, where +required, ``FIBER2``, and ``FIBER3`` vectors to each entry in ``STRUCTURE ELEMENTS``: + +.. code-block:: yaml + + STRUCTURE ELEMENTS: + - "1 SOLID HEX8 1 2 3 4 5 6 7 8 MAT 1 KINEM nonlinear FIBER1 1.0 0.0 0.0 FIBER2 0.0 1.0 0.0" + +The vectors are expressed in the Cartesian reference coordinate system and are normalized when +read. They must be nonzero and numbered without gaps: if ``FIBER1`` is absent, or ``FIBER2`` is +missing after ``FIBER1``, subsequent vectors are ignored. Fiber vectors are not automatically +orthogonalized. Materials that require an orthogonal or right-handed basis check this requirement +themselves. + +For an external mesh, the same element parameters can be assigned to every element in an element +block selected by ``ID`` or ``NAME`` in ``STRUCTURE GEOMETRY``: + +.. code-block:: yaml + + STRUCTURE GEOMETRY: + FILE: mesh.vtu + ELEMENT_BLOCKS: + - NAME: anisotropic_solid + SOLID: + HEX8: + MAT: 1 + KINEM: nonlinear + FIBER1: [1.0, 0.0, 0.0] + FIBER2: [0.0, 1.0, 0.0] + +This applies the specified directions to the complete block. No per-element input currently +available for fiber assignment through ``STRUCTURE GEOMETRY``. + +For the definition on node level, see the `FNODE` definition in :ref:`nodedefinition`. + +As an alternative, solid elements accept cylindrical coordinate-system vectors ``RAD``, ``AXI``, +and ``CIR``. All three must be given together. +Some specialized materials only support one of these input methods; the direction requirements +and restrictions for each anisotropic material or summand are documented alongside its +parameters in the Input Parameter Reference. + +``MAT_ElastHyper`` and ``MAT_ViscoElastHyper`` do not impose a direction count themselves; their +requirements are determined by the selected summands. A ``STR_TENS_ID`` controls the +structural-tensor strategy for several anisotropic summands but does not replace the underlying +mean fiber direction. diff --git a/doc/documentation/src/analysis_guide_templates/materials.rst.j2 b/doc/documentation/src/analysis_guide_templates/materials.rst.j2 index 3d0a674cb20..1ca0ab71a6d 100755 --- a/doc/documentation/src/analysis_guide_templates/materials.rst.j2 +++ b/doc/documentation/src/analysis_guide_templates/materials.rst.j2 @@ -1,13 +1,18 @@ -{% set input_file1 = "tsi_lincompression_iterstaggtemp.4C.yaml" %} -{% set input_file1_content = load_input_file(input_file1) %} - .. _materials: Materials -=========== +========= + +.. toctree:: + :maxdepth: 2 + :hidden: -General information --------------------- + solid_materials + fluid_materials + other_materials + coupling_materials + +.. rubric:: General information The definition of materials happens in the section ``MATERIALS``. A material model defines its constitutive behavior, which may consist of several terms; @@ -25,61 +30,13 @@ The explicit definition of a material model is in general given by a single line One may also define a material by summation of several potentials. -A collection of material behaviors, on the other hand, looks like this: - -.. code-block:: yaml - - MATERIALS: - - MAT: - : - NUMMAT: - MATIDS: - - - - ... - - - - -Here, the terms of the ```` constitutive behaviors have to follow with their own number, -which must correspond to `` ... ``. - - - - -Structural Material Models --------------------------- - - -A material model in structural mechanics defines the connection between deformation (usually strain) and stress. -Many material models are available, including (hyper-)elastic, elasto-plastic, visco-elastic, visco-plastic, and even damage models. -If you wish to implement a new material model, this is of course also possible, it is an in-house code after all. -You'll find more information on implementing material models in the :ref:`material section` of the developer guide. - - - -Fluid Material Models ---------------------- - - - -Other Material Models ---------------------- - -Coupling Material Models for Various Physics on a Single Discretization ------------------------------------------------------------------------ - -One may use a single (multiphysics) element type for a multiphysics simulation with matching discretizations. -However, since each discretization belongs to a single physics representation and can thus only be connected to a single material, -the other material has to be connected to the same discretization by cloning the discretization to the other physics. - -In |FOURC|, we use a material mapping section, which connects two material models to a single representation. -One can see it here in for a simple Thermo-Structure-Interaction problem, taken from {{ input_file1 }}: - -{{section_dump(input_file1_content, ["MATERIALS", "CLONING MATERIAL MAP", "STRUCTURE ELEMENTS"]) }} - - - -.. ToDo:: - - Here we should have a list of the discretizations that can be coupled +A collection of material behaviors, on the other hand, contains a number of material models, +which are defined subsequently, by a list of integers referring to the material models. +The material categories are: +* :doc:`solid_materials` for elastic, viscoelastic, hyperelastic, and plasticity models and for + material-direction input. +* :doc:`fluid_materials` for fluid material models. +* :doc:`other_materials` for material models outside the solid and fluid categories. +* :doc:`coupling_materials` for mapping material models between coupled discretizations. diff --git a/doc/documentation/src/analysis_guide_templates/other_materials.rst.j2 b/doc/documentation/src/analysis_guide_templates/other_materials.rst.j2 new file mode 100644 index 00000000000..bc6d7c0ad9e --- /dev/null +++ b/doc/documentation/src/analysis_guide_templates/other_materials.rst.j2 @@ -0,0 +1,6 @@ +.. _other-materials: + +Other materials +=============== + +Material models outside the solid and fluid categories are documented in the :doc:`../reference_guide/materials_reference`. diff --git a/doc/documentation/src/analysis_guide_templates/plasticity_materials.rst.j2 b/doc/documentation/src/analysis_guide_templates/plasticity_materials.rst.j2 new file mode 100644 index 00000000000..3553a7705be --- /dev/null +++ b/doc/documentation/src/analysis_guide_templates/plasticity_materials.rst.j2 @@ -0,0 +1,632 @@ +{% set plastic_linear_file = "plastic_pressurisedcylinder.4C.yaml" %} +{% set plastic_linear = load_input_file(plastic_linear_file) %} +{% set thermo_plastic_linear_file = "tsi_plastic_heating_monolithic.4C.yaml" %} +{% set thermo_plastic_linear = load_input_file(thermo_plastic_linear_file) %} +{% set drucker_prager_file = "mat_druckerprager_RetToCone.4C.yaml" %} +{% set drucker_prager = load_input_file(drucker_prager_file) %} +{% set gtn_file = "mat_gtn_patch_test.4C.yaml" %} +{% set gtn = load_input_file(gtn_file) %} +{% set damage_file = "plastic_necking_damage.4C.yaml" %} +{% set damage = load_input_file(damage_file) %} +{% set robinson_file = "tsi_pressurisedcylinder_robinson.4C.yaml" %} +{% set robinson = load_input_file(robinson_file) %} +{% set plastic_log_file = "solid/tutorial_solid.4C.yaml" %} +{% set plastic_log = load_input_file(plastic_log_file) %} +{% set thermo_plastic_hyper_file = "plastic_necking_fbar_thrplast.4C.yaml" %} +{% set thermo_plastic_hyper = load_input_file(thermo_plastic_hyper_file) %} +{% set plastic_hyper_vcu_file = "plastic_necking_fbar_vcu.4C.yaml" %} +{% set plastic_hyper_vcu = load_input_file(plastic_hyper_vcu_file) %} +{% set viscoplastic_file = "mat_viscoplastic_no_yield_surface_1hex8.4C.yaml" %} +{% set viscoplastic = load_input_file(viscoplastic_file) %} +{% set multiplicative_viscoplastic_file = "mat_iso_viscoplast_refJC_log_timint.4C.yaml" %} +{% set multiplicative_viscoplastic = load_input_file(multiplicative_viscoplastic_file) %} + +Plasticity materials +==================== + +This page describes the three-dimensional continuum plasticity materials available in |FOURC| +and helps users select the matching kinematic setting. Beam plasticity is not covered here. + +Materials with ``KINEM: linear`` assume small deformations and use an additive split of elastic +and plastic strain. Materials with ``KINEM: nonlinear`` support finite deformations and use a +multiplicative decomposition or an equivalent elastic/plastic metric. The selected element +kinematics must be supported by the material. + +Overview +-------- + +.. list-table:: + :header-rows: 1 + :widths: 37 13 50 + + * - Material + - Kinematics + - Main application + * - :ref:`MAT_Struct_PlasticLinElast ` + - Linear + - Von Mises plasticity with isotropic and kinematic hardening. + * - :ref:`MAT_Struct_ThermoPlasticLinElast ` + - Linear + - Thermomechanically coupled von Mises plasticity. + * - :ref:`MAT_Struct_DruckerPrager ` + - Linear + - Pressure-dependent porous metal plasticity. + * - :ref:`MAT_Struct_PlasticGTN ` + - Linear + - Porous plasticity and ductile failure. + * - :ref:`MAT_Struct_Damage ` + - Linear + - Von Mises plasticity with ductile damage. + * - :ref:`MAT_Struct_Robinson ` + - Linear + - Temperature-dependent viscoplasticity. + * - :ref:`MAT_Struct_PlasticNlnLogNeoHooke ` + - Nonlinear + - Finite-strain von Mises plasticity with Neo-Hookean elasticity. + * - :ref:`MAT_Struct_ThermoPlasticHyperElast ` + - Nonlinear + - Thermomechanically coupled finite-strain von Mises plasticity. + * - :ref:`MAT_PlasticElastHyper ` + - Nonlinear + - Finite-strain plasticity with selectable hyperelastic potentials. + * - :ref:`MAT_PlasticElastHyperVCU ` + - Nonlinear + - Variational-update variant of ``MAT_PlasticElastHyper``. + * - :ref:`MAT_Struct_Viscoplastic_No_Yield_Surface ` + - Nonlinear + - Thermally activated finite-strain viscoplasticity. + * - :ref:`MAT_MultiplicativeSplitDefgradElastHyper ` + - Nonlinear + - Composable finite-strain viscoplasticity, including anisotropy. + * - :ref:`MAT_crystal_plasticity ` + - Nonlinear + - Crystal plasticity based on crystallographic slip and twinning. +{# * - :ref:`MAT_Struct_MohrCoulomb ` + - Nonlinear + - Prospective pressure-dependent plasticity with a Mohr--Coulomb yield surface. #} + +``MAT_Struct_SuperElastSMA`` also describes nonlinear inelastic behavior, but models phase +transformation in shape-memory alloys rather than classical plasticity. + +.. _plasticity-plastic-linear: + +``MAT_Struct_PlasticLinElast`` +------------------------------ + +This small-strain material combines isotropic linear elasticity with associative von Mises +plasticity. It supports linear isotropic and linear kinematic hardening. Use it for metals when +geometric nonlinearities and temperature effects are negligible. + +The following definition of the material is taken from ``{{ plastic_linear_file }}``. +See :ref:`MAT_Struct_PlasticLinElast in the Input Parameter Reference +` for the complete parameter reference. + +{{ section_dump(plastic_linear, "MATERIALS") }} + +Output +~~~~~~ + +Gauss-point output is available as ``accumulated_plastic_strain``, ``active_plasticity``, +``back_stress_magnitude``, and ``back_stress``. Element visualization also provides +``accumulatedstrain``. + +.. _plasticity-thermo-plastic-linear: + +``MAT_Struct_ThermoPlasticLinElast`` +------------------------------------ + +This is the thermomechanically coupled extension of ``MAT_Struct_PlasticLinElast``. It includes +thermal strain, associative von Mises flow, isotropic and kinematic hardening, and heating caused +by plastic dissipation. + +The following material definition is taken from ``{{ thermo_plastic_linear_file }}``. +See :ref:`MAT_Struct_ThermoPlasticLinElast in the Input Parameter Reference +` for the complete parameter reference. + +{{ section_dump(thermo_plastic_linear, "MATERIALS") }} + +Output +~~~~~~ + +Gauss-point output is available as ``accumulated_plastic_strain``, ``active_plasticity``, +``back_stress``, and ``dissipation``. Element visualization also provides +``accumulatedstrain``. + +.. _plasticity-drucker-prager: + +``MAT_Struct_DruckerPrager`` +---------------------------- + +This small-strain pressure-dependent material uses a Drucker--Prager yield surface. +The flow rule can be non-associated and the return mapping treats both the conical surface and +its apex. It is suitable for frictional materials when a smooth approximation of a +Mohr--Coulomb surface is sufficient. + +The following material definition is taken from ``{{ drucker_prager_file }}``: +See :ref:`MAT_Struct_DruckerPrager in the Input Parameter Reference +` for the formulation of the yield surface and the complete parameter schema. + +{{ section_dump(drucker_prager, "MATERIALS") }} + +Output +~~~~~~ + +Gauss-point output is available as ``accumulated_plastic_strain`` and ``plastic_strain``. + +.. _plasticity-gtn: + +``MAT_Struct_PlasticGTN`` +------------------------- + +The Gurson--Tvergaard--Needleman model describes porous metal plasticity. Its yield surface +depends on equivalent stress, hydrostatic pressure, matrix flow stress, and void volume fraction. +The void fraction evolves through growth and nucleation and is modified after the onset of +coalescence. This model is intended for ductile damage and failure under small strains. + +The following definition is taken from ``{{ gtn_file }}``. +See :ref:`MAT_Struct_PlasticGTN in the Input Parameter Reference +` for the complete schema. + +{{ section_dump(gtn, "MATERIALS") }} + +Output +~~~~~~ + +Gauss-point output is available as ``accumulated_plastic_strain``, ``damage``, +``elastic_strain``, and ``plastic_strain``. + +.. _plasticity-damage: + +``MAT_Struct_Damage`` +--------------------- + +Formulation +~~~~~~~~~~~ + +This small-strain material combines von Mises plasticity with isotropic ductile damage. It +supports a tabulated isotropic hardening curve, kinematic hardening with recovery, and saturation +hardening. Use it when stiffness degradation and a material-failure indicator are required in +addition to metal plasticity. + +Input +~~~~~ + +The material requires ``KINEM: linear``. ``YOUNG``, ``NUE``, and ``DENS`` define elasticity and +density. ``SAMPLENUM`` sets the number of entries in the hardening data ``SIGMA_Y`` and +``EPSBAR_P``. ``DAMDEN``, ``DAMEXP``, and ``DAMTHRESHOLD`` define damage evolution. +``KINHARD`` and ``KINHARD_REC`` control kinematic hardening and recovery; ``SATHARDENING`` and +``HARDEXPO`` control saturation hardening. ``TOL`` controls the local iteration. + +See :ref:`MAT_Struct_Damage in the Input Parameter Reference +` for the complete schema. The following definition is taken from +``{{ damage_file }}``: + +{{ section_dump(damage, "MATERIALS") }} + +Output +~~~~~~ + +Gauss-point output is available as ``accumulated_plastic_strain``, ``isohardeningvar``, +``damage``, and ``failedFlag``. The same quantities are available for element visualization, +with accumulated plastic strain named ``accumulatedstrain``. + +.. _plasticity-robinson: + +``MAT_Struct_Robinson`` +----------------------- + +Formulation +~~~~~~~~~~~ + +The Robinson model is a small-strain, temperature-dependent viscoplastic model with thermal +strain, hardening, recovery, and rate-dependent flow. Several predefined parameterizations are +selected through ``KIND``. + +The elastic response uses a constant Poisson's ratio and a polynomial Young's modulus + +.. math:: + + E(T)=\sum_{i=0}^{N_E-1} E_i T^i + =E_0+E_1T+E_2T^2+\ldots , + +where ``YOUNGNUM`` is :math:`N_E` and the entries of ``YOUNG`` are +:math:`[E_0,E_1,\ldots]`. Thus, one entry defines a temperature-independent modulus. The +temperature :math:`T` is the current material temperature. + +Robinson variants +~~~~~~~~~~~~~~~~~ + +All four variants use ``HRDN_EXPO`` (:math:`n`), the Bingham--Prager threshold +:math:`K^2(T)`, ``RCVRY`` (:math:`R_0`), ``ACTV_ERGY`` (:math:`Q_0`), ``ACTV_TMPR`` +(:math:`T_0`), ``G0``, ``M_EXPO`` (:math:`m`), :math:`\beta(T)`, and ``H_FACT``. The vector +inputs ``SHRTHRSHLD`` and ``BETA`` are evaluated as temperature polynomials in the same way as +``YOUNG``; their lengths are specified by ``SHRTHRSHLDNUM`` and ``BETANUM``. + +.. list-table:: + :header-rows: 1 + :widths: 24 76 + + * - ``KIND`` + - Variant-specific interpretation + * - ``Butler`` + - Uses ``HRDN_FACT`` directly as the flow factor :math:`A`, ``H_FACT`` directly as + :math:`H`, and ``RCVRY`` directly as :math:`R_0`. + * - ``Arya`` + - Uses the same direct parameter interpretation as ``Butler`` in the current implementation. + * - ``Arya_NarloyZ`` + - Uses ``HRDN_FACT`` directly as :math:`A`. With + :math:`K_0^2=K^2(T_0)` and :math:`p_u=10^{-4}`, the implementation converts + + .. math:: + + H_\mathrm{eff} + &=H_\mathrm{FACT}\frac{6.896^{1+\beta}}{3K_0^2},\\ + R_{0,\mathrm{eff}} + &=R_0\,6.896^{1+\beta+m} + (3K_0^2p_u^2)^{m-\beta}. + + * - ``Arya_CrMoSteel`` + - Interprets ``HRDN_FACT`` as :math:`\mu` and computes + + .. math:: + + \theta_1(T)&=(23.8T-2635)\left(\frac{1}{811}-\frac{1}{T}\right),\\ + A(T)&=\frac{1}{2\mu\exp[-\theta_1(T)]},\qquad + H_\mathrm{eff}=2\mu H_\mathrm{FACT}. + +For all variants, the recovery factor entering the back-stress evolution is + +.. math:: + + R(T)=R_{0,\mathrm{eff}} + \exp\left[Q_0\frac{T-T_0}{TT_0}\right], + +with the limiting cases for zero temperatures handled by the implementation. + +Input +~~~~~ + +The material requires ``KINEM: linear``. ``KIND`` selects ``Butler``, ``Arya``, +``Arya_NarloyZ``, or ``Arya_CrMoSteel`` behavior. ``YOUNGNUM`` and ``YOUNG`` define the +polynomial coefficients of the temperature-dependent Young's modulus; ``NUE``, ``DENS``, +``THEXPANS``, and ``INITTEMP`` complete the elastic and thermal data. The viscoplastic parameters +are ``HRDN_FACT``, ``HRDN_EXPO``, ``SHRTHRSHLDNUM``, ``SHRTHRSHLD``, ``RCVRY``, +``ACTV_ERGY``, ``ACTV_TMPR``, ``G0``, ``M_EXPO``, ``BETANUM``, ``BETA``, and ``H_FACT``. +Their variant-specific meanings are summarized above. + +See :ref:`MAT_Struct_Robinson in the Input Parameter Reference +` for the complete schema. The following definition is taken from +``{{ robinson_file }}``: + +{{ section_dump(robinson, "MATERIALS") }} + +Output +~~~~~~ + +The material does not register model-specific visualization or Gauss-point output quantities. + +.. _plasticity-log-neo-hooke: + +``MAT_Struct_PlasticNlnLogNeoHooke`` +------------------------------------ + +Formulation +~~~~~~~~~~~ + +This finite-strain model combines compressible Neo-Hookean elasticity with associative von Mises +plasticity. The return mapping uses principal elastic logarithmic strains and Kirchhoff stresses, +while plastic history is evolved multiplicatively. The model supports linear and saturating +isotropic hardening, a user-defined hardening function, and optional rate dependence. + +Input +~~~~~ + +The material requires ``KINEM: nonlinear``. ``YOUNG``, ``NUE``, and ``DENS`` define elasticity +and density. Hardening is specified by ``YIELD``, ``ISOHARD``, ``SATHARDENING``, and +``HARDEXPO``, or by ``HARDENING_FUNC`` using the variable ``epsp``. ``VISC`` and +``RATE_DEPENDENCY`` enable rate-dependent behavior. ``TOL`` controls the local iteration. + +See :ref:`MAT_Struct_PlasticNlnLogNeoHooke in the Input Parameter Reference +` for the complete schema. The following definition +is taken from ``{{ plastic_log_file }}``: + +{{ section_dump(plastic_log, "MATERIALS") }} + +Output +~~~~~~ + +Gauss-point output is available as ``accumulated_plastic_strain``, ``active_plasticity``, and +``plastic_strain``. Element visualization also provides ``accumulatedstrain``. + +.. _plasticity-thermo-hyper: + +``MAT_Struct_ThermoPlasticHyperElast`` +-------------------------------------- + +Formulation +~~~~~~~~~~~ + +This thermomechanically coupled finite-strain model combines hyperelasticity with associative +von Mises plasticity. It uses a multiplicative elastic-plastic split and supports linear and +saturating isotropic hardening, thermal expansion, temperature-dependent softening, mechanical +dissipation, and thermoplastic heating. + +Input +~~~~~ + +The material requires ``KINEM: nonlinear``. ``YOUNG``, ``NUE``, and ``DENS`` define elasticity +and density. ``CTE`` and ``INITTEMP`` define thermal expansion. ``YIELD``, ``ISOHARD``, +``SATHARDENING``, and ``HARDEXPO`` define hardening; ``YIELDSOFT`` and ``HARDSOFT`` define its +temperature dependence. ``TOL`` controls the local iteration. + +See :ref:`MAT_Struct_ThermoPlasticHyperElast in the Input Parameter Reference +` for the complete schema. The following definition +is taken from ``{{ thermo_plastic_hyper_file }}``: + +{{ section_dump(thermo_plastic_hyper, "MATERIALS") }} + +Output +~~~~~~ + +Element visualization provides ``accumulatedstrain``, ``mechdiss``, and ``thrplheating``. + +.. _plasticity-elast-hyper: + +``MAT_PlasticElastHyper`` +------------------------- + +Formulation +~~~~~~~~~~~ + +This general finite-strain framework combines one or more hyperelastic potentials with a +multiplicative plastic update. It supports isotropic von Mises or anisotropic Hill yielding, +linear and saturating isotropic hardening, kinematic hardening, optional Perzyna rate dependence, +plastic spin, thermal expansion, thermal softening, and conversion of plastic work into heat. + +Input +~~~~~ + +The material requires ``KINEM: nonlinear``. ``NUMMAT`` and ``MATIDS`` reference the +hyperelastic potentials; those materials must be defined separately. ``DENS`` and ``INITYIELD`` +set density and initial yield stress. ``ISOHARD``, ``EXPISOHARD``, ``INFYIELD``, and ``KINHARD`` +define hardening. ``VISC``, ``RATE_DEPENDENCY``, and ``VISC_SOFT`` control Perzyna +viscoplasticity. ``PL_SPIN_CHI`` controls plastic spin. Nonzero ``rY_11``, ``rY_22``, ``rY_33``, +``rY_12``, ``rY_23``, and ``rY_13`` define directional Hill yield ratios. ``CTE``, ``INITTEMP``, +``YIELDSOFT``, ``HARDSOFT``, and ``TAYLOR_QUINNEY`` control thermomechanical coupling. + +See :ref:`MAT_PlasticElastHyper in the Input Parameter Reference +` for the complete schema. No regression input in the current +test suite uses this material directly. + +Output +~~~~~~ + +Gauss-point and element output is available as ``accumulated_plastic_strain``, +``plastic_strain_incr``, ``plastic_zone``, and ``kinematic_plastic_strain``. For element +visualization, accumulated plastic strain is named ``accumulatedstrain``. + +.. _plasticity-elast-hyper-vcu: + +``MAT_PlasticElastHyperVCU`` +---------------------------- + +Formulation +~~~~~~~~~~~ + +This material provides a variational constitutive-update variant of +``MAT_PlasticElastHyper``. It uses the same selectable hyperelastic potentials and the same +finite-strain yield, hardening, viscosity, anisotropy, plastic-spin, and thermal options. + +Input +~~~~~ + +The material requires ``KINEM: nonlinear`` and uses the same input parameters as +``MAT_PlasticElastHyper``. ``NUMMAT`` and ``MATIDS`` reference separately defined hyperelastic +potentials. + +See :ref:`MAT_PlasticElastHyperVCU in the Input Parameter Reference +` for the complete schema. The following definition is taken +from ``{{ plastic_hyper_vcu_file }}``: + +{{ section_dump(plastic_hyper_vcu, "MATERIALS") }} + +Output +~~~~~~ + +Element visualization provides ``accumulatedstrain``. + +.. _plasticity-no-yield: + +``MAT_Struct_Viscoplastic_No_Yield_Surface`` +-------------------------------------------- + +Formulation +~~~~~~~~~~~ + +This finite-strain material has no elastic domain and therefore no yield surface. Plastic flow is +thermally activated and rate dependent, and the isotropic flow resistance evolves toward a +saturation value. The formulation uses elastic logarithmic strain and a multiplicative plastic +deformation gradient. + +Input +~~~~~ + +The material requires ``KINEM: nonlinear``. ``YOUNG``, ``NUE``, and ``DENS`` define elasticity +and density. ``TEMPERATURE``, ``PRE_EXP_FAC``, ``ACTIVATION_ENERGY``, and ``GAS_CONSTANT`` +control thermal activation; ``STRAIN_RATE_SENS`` controls rate sensitivity. ``INIT_FLOW_RES``, +``FLOW_RES_PRE_FAC``, ``FLOW_RES_EXP``, ``FLOW_RES_SAT_FAC``, and ``FLOW_RES_SAT_EXP`` define +the evolution of isotropic flow resistance. + +See :ref:`MAT_Struct_Viscoplastic_No_Yield_Surface in the Input Parameter Reference +` for the complete schema. The following +definition is taken from ``{{ viscoplastic_file }}``: + +{{ section_dump(viscoplastic, "MATERIALS") }} + +Output +~~~~~~ + +The material does not register model-specific visualization or Gauss-point output quantities. + +.. _plasticity-multiplicative: + +``MAT_MultiplicativeSplitDefgradElastHyper`` +-------------------------------------------- + +Formulation +~~~~~~~~~~~ + +This composable finite-strain framework combines separately defined hyperelastic potentials with +one or more inelastic deformation-gradient factors. For viscoplasticity, use +``MAT_InelasticDefgradTransvIsotropElastViscoplast`` as an inelastic factor. It supports isotropic +or transversely isotropic Hill yielding and delegates its flow and hardening law to a separately +defined viscoplastic law. The available +``MAT_ViscoplasticLawReformulatedJohnsonCook`` combines rate-dependent flow, isotropic hardening, +and thermal softening. + +Input +~~~~~ + +The parent material requires ``KINEM: nonlinear``. ``NUMMATEL`` and ``MATIDSEL`` reference its +elastic potentials; ``NUMFACINEL`` and ``INELDEFGRADFACIDS`` reference its inelastic factors. +``DENS``, ``REF_TEMPERATURE``, and ``THERMAL_EXPANSION_COEFFICIENT`` set density and thermal +expansion. + +The viscoplastic factor uses ``VISCOPLAST_LAW_ID`` and ``FIBER_READER_ID`` to reference its +constitutive law and fiber direction. ``MAT_BEHAVIOR`` selects isotropic or transversely +isotropic behavior; optional ``YIELD_COND_A``, ``YIELD_COND_B``, and ``YIELD_COND_F`` specify +Hill anisotropy. Additional parameters select time integration, linearization, matrix-function +algorithms, substepping, and error handling. The complete list is available in the material input +reference. + +For ``MAT_ViscoplasticLawReformulatedJohnsonCook``, ``STRAIN_RATE_PREFAC`` and +``STRAIN_RATE_EXP_FAC`` define rate dependence; ``INIT_YIELD_STRENGTH``, +``ISOTROP_HARDEN_PREFAC``, and ``ISOTROP_HARDEN_EXP`` define hardening; and +``REF_TEMPERATURE``, ``MELT_TEMPERATURE``, and ``TEMPERATURE_SENS`` define thermal softening. + +See the Input Parameter Reference for +:ref:`MAT_MultiplicativeSplitDefgradElastHyper +`, +:ref:`MAT_InelasticDefgradTransvIsotropElastViscoplast +`, and +:ref:`MAT_ViscoplasticLawReformulatedJohnsonCook +`. The following complete material +composition is taken from ``{{ multiplicative_viscoplastic_file }}``: + +{{ section_dump(multiplicative_viscoplastic, "MATERIALS") }} + +Output +~~~~~~ + +The viscoplastic factor provides ``inverse_plastic_defgrad``, ``plastic_strain``, +``equiv_stress``, ``defgrad``, ``rightCG``, and ``local_newton_iters`` as Gauss-point output. +The reformulated Johnson--Cook law additionally provides ``yield_strength``. + +.. _plasticity-crystal: + +``MAT_crystal_plasticity`` +-------------------------- + +Formulation +~~~~~~~~~~~ + +This finite-strain crystal-plasticity model evolves the plastic deformation gradient through +crystallographic slip and optional deformation twinning. Slip and twin systems are generated for +``FCC``, ``BCC``, ``HCP``, ``D019``, and ``L10`` lattices. Rate sensitivity, dislocation-density +evolution, Hall--Petch strengthening, and interactions between slip and twinning can be specified +per system set. + +Input +~~~~~ + +The material requires ``KINEM: nonlinear``. ``YOUNG``, ``NUE``, ``DENS``, and ``TOL`` define +elasticity, density, and local tolerance. ``LAT``, ``CTOA``, and ``ABASE`` define the crystal +lattice. + +Slip systems are configured through ``NUMSLIPSYS``, ``NUMSLIPSETS``, ``SLIPSETMEMBERS``, +``SLIPRATEEXP``, ``GAMMADOTSLIPREF``, ``DISDENSINIT``, ``DISGENCOEFF``, ``DISDYNRECCOEFF``, +``TAUY0``, ``MFPSLIP``, ``SLIPHPCOEFF``, and ``SLIPBYTWIN``. Optional twinning is configured +through ``NUMTWINSYS``, ``NUMTWINSETS``, ``TWINSETMEMBERS``, ``TWINRATEEXP``, +``GAMMADOTTWINREF``, ``TAUT0``, ``MFPTWIN``, ``TWINHPCOEFF``, ``TWINBYSLIP``, and +``TWINBYTWIN``. Vector lengths must agree with the corresponding numbers of systems and sets. + +See :ref:`MAT_crystal_plasticity in the Input Parameter Reference +` for the complete schema. No regression input in the current +test suite uses this material. + +Output +~~~~~~ + +Element visualization provides the shear on each deformation system as +``plastic_shear_``, the scalar ``accumulated_plastic_shear``, dislocation density on each +slip system as ``dislocation_density_``, twin volume on each twin system as +``twinned_volume_``, and the totals ``total_dislocation_density`` and +``total_twinned_volume``. + +{# +.. _plasticity-mohr-coulomb: + + +Prospective ``MAT_Struct_MohrCoulomb`` +-------------------------------------- + +Formulation +~~~~~~~~~~~ + +``MAT_Struct_MohrCoulomb`` is a finite-strain isotropic elastoplastic material using principal +elastic logarithmic strains and their work-conjugate Kirchhoff stresses. For ordered principal +Kirchhoff stresses :math:`\tau_1 \geq \tau_2 \geq \tau_3`, its active yield plane is + +The formulation follows Clausen, Damkilde, and Andersen, +*Efficient return algorithms for associated plasticity with multiple yield planes*, +Computers & Structures 85 (2007), doi:10.1016/j.compstruc.2007.04.002. + +.. math:: + + f = k\tau_1-\tau_3-2\sqrt{k}\,c(\bar{\varepsilon}^{p}) \leq 0, + \qquad + k=\frac{1+\sin\phi}{1-\sin\phi}. + +The plastic potential has the same form with +:math:`m=(1+\sin\psi)/(1-\sin\psi)`, where :math:`\psi` is the dilatancy angle. +Setting ``DILATANCY_ANGLE`` equal to ``FRICTION_ANGLE`` gives associative plasticity. The model +accounts for smooth faces, both triaxial edges, and the hydrostatic apex. + +The cohesion hardening law combines linear and Voce terms: + +.. math:: + + c(\bar{\varepsilon}^{p}) = + c_0 + H\bar{\varepsilon}^{p} + + (c_\infty-c_0)\left(1-\exp(-b\bar{\varepsilon}^{p})\right). + +Input +~~~~~ + +The material is not yet part of the generated Input Parameter Reference. + +.. code-block:: yaml + + MAT_Struct_MohrCoulomb: + YOUNG_MODULUS: 1.0e5 + POISSON_RATIO: 0.3 + DENSITY: 2200 + COHESION: 100 + FRICTION_ANGLE: 0.5235987755982 + DILATANCY_ANGLE: 0.4363323129986 + LINEAR_HARDENING: 0 + SATURATION_HARDENING: 500 + HARDENING_EXP: 10 + TOLERANCE: 1.0e-10 + MAX_ITERATIONS: 100 + +The material requires ``KINEM: nonlinear``. Angles are specified in radians. +The dilatancy angle must be strictly positive and must not exceed the friction angle. +Set ``SATURATION_HARDENING`` to zero to disable the Voce term. + +Output +~~~~~~ + +The material provides ``plastic_strain``, ``accumulated_plastic_strain``, ``accumulated_plastic_volumetric_strain``, and +``local_dissipated_energy`` as Gauss-point output. +#} diff --git a/doc/documentation/src/analysis_guide_templates/solid_materials.rst.j2 b/doc/documentation/src/analysis_guide_templates/solid_materials.rst.j2 new file mode 100644 index 00000000000..17dacaa387e --- /dev/null +++ b/doc/documentation/src/analysis_guide_templates/solid_materials.rst.j2 @@ -0,0 +1,42 @@ +.. _solid-materials: + +Solid materials +=============== + +A solid material model defines the relation between deformation, usually expressed as strain, +and stress. + +Since users should find an appropriate material law for their application quickly, we have +grouped the material models into families based on their continuum nature. +This is just a starting point of a complete documentation, and we are always looking for +more contributions. + +The principal continuum material families and their direction input are documented +on the following pages. There are various other specialized materials, e.g., muscle materials and +growth models that are not described here yet. + +.. toctree:: + :maxdepth: 1 + :hidden: + + elastic_materials + hyperelastic_framework + viscoelastic_materials + plasticity_materials + material_directions + +The solid-material topics are: + +* :doc:`elastic_materials` summarizes elastic materials assigned directly to two- and + three-dimensional solid elements. +* :doc:`viscoelastic_materials` describes direct and framework-based material models with + time-dependent behavior. +* :doc:`hyperelastic_framework` describes hyperelastic materials composed of multiple + strain-energy terms. +* :doc:`plasticity_materials` describes continuum plasticity material models and their kinematic + settings. +* :doc:`material_directions` explains how direction-dependent solid materials obtain fiber and + coordinate-system directions. + +If you wish to implement a new material model, see the +:ref:`material section ` of the developer guide. diff --git a/doc/documentation/src/analysis_guide_templates/viscoelastic_materials.rst.j2 b/doc/documentation/src/analysis_guide_templates/viscoelastic_materials.rst.j2 new file mode 100644 index 00000000000..2257a448732 --- /dev/null +++ b/doc/documentation/src/analysis_guide_templates/viscoelastic_materials.rst.j2 @@ -0,0 +1,78 @@ +{% set visco_neohooke_file = "constr3D_NormComp_STI.4C.yaml" %} +{% set visco_neohooke = load_input_file(visco_neohooke_file) %} +{% set visco_anisotropic_file = "viscoAnisotropic_creep.4C.yaml" %} +{% set visco_anisotropic = load_input_file(visco_anisotropic_file) %} +{% set visco_hyper_file = "visco_generalized_maxwell_etd_h8.4C.yaml" %} +{% set visco_hyper = load_input_file(visco_hyper_file) %} + +.. _viscoelastic-materials: + +Viscoelastic materials +====================== + +Similar to the elastic materials, viscoelastic materials can be defined either by a +single material law, see the Direct materials section below, or by a combination of +elastic and viscous summands, see the ``MAT_ViscoElastHyper`` framework section. + +**Note:** All continuum materials on this page require ``KINEM: nonlinear``. + +Direct materials +---------------- + +``MAT_VISCONEOHOOKE`` is a finite-strain isotropic Neo-Hookean viscoelastic material. See +:ref:`MAT_VISCONEOHOOKE in the Input Parameter Reference `. +The following material section is taken from ``{{ visco_neohooke_file }}``: + +{{ section_dump(visco_neohooke, "MATERIALS") }} + +``MAT_VISCOANISO`` adds anisotropic fiber relaxation to isotropic viscoelasticity. See +:ref:`MAT_VISCOANISO in the Input Parameter Reference `. +The following material section is taken from ``{{ visco_anisotropic_file }}``: + +{{ section_dump(visco_anisotropic, "MATERIALS") }} + +``MAT_ViscoElastHyper`` framework +--------------------------------- + +``MAT_ViscoElastHyper`` combines elastic ``ELAST_*`` and viscous ``VISCO_*`` summands. +See :ref:`MAT_ViscoElastHyper in the Input Parameter Reference +` for the parameters to enter the elastic and the viscous material components. +The following definition is taken from ``{{ visco_hyper_file }}``: + +{{ section_dump(visco_hyper, "MATERIALS") }} + +Viscoelastic summands +--------------------- + +Unlike elastic summands, a viscoelastic contribution generally cannot be described by a stored +energy depending only on the current deformation. The table below lists the available +viscoelastic summands; the implemented viscous pseudo-potential or stress-evolution equation for +each is given in the Input Parameter Reference. Here, +:math:`\boldsymbol S_0` is the second Piola--Kirchhoff stress of the hyperelastic base law, +:math:`\boldsymbol Q_i` is a branch stress, and +:math:`\dot{\boldsymbol E}` is the Green--Lagrange strain rate. + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - Summand + - Model + * - :ref:`VISCO_IsoRateDep ` + - Isochoric rate-dependent contribution. + * - :ref:`VISCO_FSLS ` + - Fractional standard linear solid. + * - :ref:`VISCO_GeneralizedMaxwell ` + - Generalized Maxwell model. + * - :ref:`VISCO_GeneralizedMaxwellBranch + ` + - Branch referenced by a generalized Maxwell model. + * - :ref:`VISCO_QuasiLinearGeneralizedMaxwell + ` + - Fung-type quasi-linear generalized Maxwell model. + * - :ref:`VISCO_CoupMyocard ` + - Coupled myocardial viscoelastic contribution. + + +For the time integration of both Maxwell models, ``SOLVE`` selects either ``OneStepTheta`` or +``ExponentialTimeDiscretization`` for the branch evolution. \ No newline at end of file diff --git a/src/global_legacy_module/4C_global_legacy_module_validmaterials.cpp b/src/global_legacy_module/4C_global_legacy_module_validmaterials.cpp index f55c72ae18b..6a5bb995439 100644 --- a/src/global_legacy_module/4C_global_legacy_module_validmaterials.cpp +++ b/src/global_legacy_module/4C_global_legacy_module_validmaterials.cpp @@ -846,9 +846,13 @@ std::unordered_map Global::v {.description = "stiffness scaling parameter", .validator = positive()}), parameter( "M", {.description = "nonlinearity parameter", .validator = positive()}), - parameter( - "Q", {.description = "tension-compression asymmetry control parameter", - .validator = in_range(0.0, 1.0)}), + parameter("Q", + {.description = + "tension-compression asymmetry control parameter. " + "$q=0.5$ gives a tension--compression symmetric response, " + "$q>0.5$ makes the material stiffer in tension than in compression, " + "and $q<0.5$ makes the material stiffer in compression than in tension", + .validator = in_range(0.0, 1.0)}), parameter("KAPPA", {.description = "incompressibility parameter", .validator = positive()}), parameter( @@ -856,11 +860,16 @@ std::unordered_map Global::v }, {.description = "Hyperelastic Ogden material with tension-compression asymmetry control. The " - "second Piola--Kirchhoff stress is computed as S = sum_{i=1}^{3} [c/m * (q * " - "lambda_i^{m-2} - (1-q) * lambda_i^{-m-2}) N_i otimes N_i] + [kappa * J * (J-1) + " - "c/m * (1-2q)] C^{-1}] with J being the determinant of the deformation gradient, " - "lambda_i the principal stretches of the right Cauchy-Green deformation tensor C, " - "and N_i the corresponding principal directions."}); + "second Piola-Kirchhoff stress is computed as\n\n" + "$$\n" + "\\mathbf{S} = \\sum_{i=1}^{3} \\left[\\frac{c}{m}\\left(q\\," + "\\lambda_i^{m-2} - (1-q)\\,\\lambda_i^{-m-2}\\right) " + "\\mathbf{N}_i \\otimes \\mathbf{N}_i\\right] " + "+ \\left[\\kappa J (J-1) + \\frac{c}{m}(1-2q)\\right] \\mathbf{C}^{-1}\n" + "$$\n\n" + "with $J$ the determinant of the deformation gradient, $\\lambda_i$ the principal " + "stretches of the right Cauchy-Green deformation tensor $\\mathbf{C}$, and " + "$\\mathbf{N}_i$ the corresponding principal directions."}); } { @@ -1156,7 +1165,9 @@ std::unordered_map Global::v "[nu12, nu23, nu13]."}), parameter("DENS", {.description = "mass density"}), }, - {.description = "St.Venant--Kirchhoff material with orthotropy"}); + {.description = "St.Venant--Kirchhoff material with orthotropy. Direction requirements: " + "none; its three orthotropic axes are fixed to the Cartesian reference " + "axes and cannot be rotated through material or fiber input."}); } /*--------------------------------------------------------------------*/ @@ -1210,12 +1221,19 @@ std::unordered_map Global::v .default_value = 50, .validator = positive()}), }, - {.description = "Linear-elasto-plastic material with a Drucker-Prager yield surface: " - "$\\phi = \\sqrt{J_2} + \\eta \\, \\mathrm{tr}(\\mathbf{\\sigma}) - " - "\\xi\\, (c + H_\\mathrm{iso}\\varepsilon_\\mathrm{p}^\\mathrm{acc}$ " - "and a potentially non-associated plastic potential: = " - "\\sqrt{J_2} + \\overline{\\eta} \\, \\mathrm{tr}(\\mathbf{\\sigma}) - " - "\\xi\\, (c + H_\\mathrm{iso}\\varepsilon_\\mathrm{p}^\\mathrm{acc}$"}); + {.description = "Linear-elasto-plastic material with a Drucker-Prager yield surface\n\n" + "$$\n" + "\\phi = \\sqrt{J_2} + \\eta \\, \\mathrm{tr}(\\boldsymbol{\\sigma}) - " + "\\xi\\, \\left(c + H_\\mathrm{iso}\\varepsilon_\\mathrm{p}^\\mathrm{acc}" + "\\right)\n" + "$$\n\n" + "and a potentially non-associated plastic potential\n\n" + "$$\n" + "g = \\sqrt{J_2} + \\overline{\\eta} \\, " + "\\mathrm{tr}(\\boldsymbol{\\sigma}) - " + "\\xi\\, \\left(c + H_\\mathrm{iso}\\varepsilon_\\mathrm{p}^\\mathrm{acc}" + "\\right)\n" + "$$"}); } /*----------------------------------------------------------------------*/ @@ -1263,22 +1281,52 @@ std::unordered_map Global::v {.description = "Function number for isotropic hardening", .default_value = 0}), parameter("TOL", {.description = "Local Newton iteration tolerance"}), parameter("MAXITER", - {.description = "Maximum Neutron Raphson Iterations", .default_value = 50}), - parameter("K1", {.description = "GTN Constant k1"}), - parameter("K2", {.description = "GTN Constant k2"}), - parameter("K3", {.description = "GTN constant k3"}), - parameter("F0", {.description = "GTN constant f0 for initial damage"}), - parameter("FN", {.description = "GTN constant fN for damage nucleation"}), - parameter("EN", {.description = "GTN constant eN for damage nucleation"}), - parameter("SN", {.description = "GTN constant sN for damage nucleation"}), - parameter("FC", {.description = "GTN constant fC for damage coalescence"}), - parameter( - "KAPPA", {.description = "GTN constant kappa for damage coalescence"}), + {.description = "Maximum Newton Raphson Iterations", .default_value = 50}), + parameter("K1", {.description = "GTN Constant $k_1$"}), + parameter("K2", {.description = "GTN Constant $k_2$"}), + parameter("K3", {.description = "GTN constant $k_3$"}), + parameter( + "F0", {.description = "GTN constant $f_0$: initial void volume fraction"}), + parameter("FN", {.description = "GTN constant $f_N$ for damage nucleation"}), + parameter( + "EN", {.description = "GTN constant $\\varepsilon_N$ for damage nucleation"}), + parameter("SN", {.description = "GTN constant $s_N$ for damage nucleation"}), + parameter("FC", {.description = "GTN constant $f_C$: " + "void volume fraction at damage coalescence"}), + parameter("KAPPA", + {.description = "GTN constant $\\kappa$: Increased damage rate after coalescence"}), parameter( "EF", {.description = "GTN stabilization parameter ef for damage coalescence", .default_value = 0.0}), }, - {.description = "elastic St.Venant Kirchhoff / plastic GTN"}); + {.description = "elastic St.Venant Kirchhoff / plastic GTN for porous metal plasticity." + "It uses an associated yield function of the form\n\n" + "$$\n" + "\\Phi = \\left( \\frac{Q}{R^{(3)}} \\right)^2 + " + "2 k_1 f^* \\cosh \\left( -\\frac{3}{2} k_2 \\frac{P}{R^{(3)}} \\right) " + "- \\left(1 + k_3 {f^*}^2 \\right) = 0\n" + "$$\n\n" + "with $Q=\\sqrt{\\sigma_\\text{dev} : \\sigma_\\text{dev}}$ " + "and P being the trace of the stress.\n\n" + "The damage $f^*$ is calculated by\n\n" + "$$\n" + "f^* = \\begin{cases}\n" + "f & f \\leq f_c \\\\\n" + "f_c + \\kappa ( f - f_c) & f > f_c\n" + "\\end{cases}\n" + "$$\n\n" + "The rate of the void volume fraction includes growth and nucleation:\n\n" + "$$\n" + "\\dot{f} = \\dot{f}_\\text{growth} + \\dot{f}_\\text{nucl}\n" + "$$\n\n" + "with\n\n" + "$$\n" + "\\dot{f}_\\text{nucl} = \\frac{f_N}{s_N \\sqrt{2\\pi}} " + "\\exp \\left\\{ -\\frac{1}{2} " + "\\left[ \\frac{\\overline{\\varepsilon}^{pl} - \\epsilon_N}{s_N} " + "\\right]^2 \\right\\} " + "\\dot{\\overline{\\varepsilon}}^{pl}\n" + "$$"}); } /*----------------------------------------------------------------------*/ @@ -1579,7 +1627,9 @@ std::unordered_map Global::v parameter("ELETHICKDIR", {.description = "Element thickness direction applies also to fibers (only sosh)"}), }, - {.description = "visco-elastic anisotropic fibre material law"}); + {.description = "visco-elastic anisotropic fibre material law. Direction requirements: " + "2 derived directions; requires the cylindrical coordinate system, from " + "which two fiber families are generated using its material angle GAMMA."}); } /*----------------------------------------------------------------------*/ @@ -1613,7 +1663,11 @@ std::unordered_map Global::v parameter("POLYCONVEX", {.description = "1.0 if polyconvexity of system is checked", .default_value = 0}), }, - {.description = "list/collection of hyperelastic materials, i.e. material IDs"}); + {.description = "list/collection of hyperelastic materials, i.e. material IDs. Direction " + "requirements: none imposed by this container itself; the requirements " + "are determined by the selected summands. A `STR_TENS_ID` on an " + "anisotropic summand controls the structural-tensor strategy but does not " + "replace the underlying mean fiber direction."}); } /*----------------------------------------------------------------------*/ @@ -1635,12 +1689,18 @@ std::unordered_map Global::v "VISCO_MATIDS", {.description = "explicit visco summand IDs", .size = size_from_optional_count("NUMVISCO")}), parameter("DENS", {.description = "material mass density"}), - parameter("POLYCONVEX", - {.description = "1.0 if polyconvexity of system is checked", .default_value = 0}), + parameter( + "POLYCONVEX", {.description = "1.0 if polyconvexity of system is checked " + "(not supported for viscoelastic combinations.)", + .default_value = 0}), }, {.description = "Viscohyperelastic material. Uses NUMMAT/MATIDS as the complete summand " "list and supports explicit elastic/visco splits with NUMELAST/" - "ELAST_MATIDS and NUMVISCO/VISCO_MATIDS."}); + "ELAST_MATIDS and NUMVISCO/VISCO_MATIDS. Direction requirements: none " + "imposed by this container itself; the requirements are determined by " + "the selected summands. A `STR_TENS_ID` on an anisotropic summand " + "controls the structural-tensor strategy but does not replace the " + "underlying mean fiber direction."}); } /*----------------------------------------------------------------------*/ @@ -1715,7 +1775,11 @@ std::unordered_map Global::v {.description = "Taylor-Quinney factor for plastic heat conversion", .default_value = 1.}), }, - {.description = "collection of hyperelastic materials for finite strain plasticity"}); + {.description = "collection of hyperelastic materials for finite strain plasticity. " + "Direction requirements: 0 or 3 directions; three explicit, mutually " + "orthogonal fibers forming a right-handed basis are required for Hill " + "plasticity, while no fibers are used for isotropic von Mises " + "plasticity."}); } /*----------------------------------------------------------------------*/ @@ -1791,7 +1855,11 @@ std::unordered_map Global::v parameter("POLYCONVEX", {.description = "1.0 if polyconvexity of system is checked", .default_value = 0}), }, - {.description = "collection of hyperelastic materials for finite strain plasticity"}); + {.description = "collection of hyperelastic materials for finite strain plasticity. " + "Direction requirements: 0 or 3 directions; three explicit, mutually " + "orthogonal fibers forming a right-handed basis are required for Hill " + "plasticity, while no fibers are used for isotropic von Mises " + "plasticity."}); } /*--------------------------------------------------------------------*/ @@ -1805,7 +1873,14 @@ std::unordered_map Global::v parameter("C1", {.description = "E or mue"}), parameter("C2", {.description = "nue or lambda"}), }, - {.description = "logarithmic neo-Hooke material acc. to Bonet and Wood"}); + {.description = "Logarithmic neo-Hooke material acc. to Bonet and Wood. The strain energy " + "is computed as\n\n" + "$$\n" + "\\Psi = \\frac{\\mu}{2}(I_1-3) - \\mu \\ln(J) + " + "\\frac{\\lambda}{2}(\\ln J)^2\n" + "$$\n\n" + "with $I_1$ the first invariant of the right Cauchy-Green deformation " + "tensor and $J$ the determinant of the deformation gradient."}); } /*--------------------------------------------------------------------*/ @@ -1816,7 +1891,14 @@ std::unordered_map Global::v parameter("YOUNG", {.description = "Young's modulus"}), parameter("NUE", {.description = "Poisson's ratio"}), }, - {.description = "Saint-Venant-Kirchhoff as elastic summand"}); + {.description = "Saint-Venant-Kirchhoff as elastic summand. The strain energy is computed " + "as\n\n" + "$$\n" + "\\Psi = \\mu\\,\\mathrm{tr}(\\mathbf{E}^2) + " + "\\frac{\\lambda}{2}(\\mathrm{tr}\\,\\mathbf{E})^2\n" + "$$\n\n" + "with $\\mathbf{E}$ the Green-Lagrange strain tensor and $\\mu$, " + "$\\lambda$ the Lame constants."}); } /*--------------------------------------------------------------------*/ @@ -1826,7 +1908,12 @@ std::unordered_map Global::v { parameter("MUE", {.description = "material constant"}), }, - {.description = "Simo-Pister type material"}); + {.description = "Simo-Pister type material. The strain energy is computed as\n\n" + "$$\n" + "\\Psi = \\frac{\\mu}{2}(I_1-3) - \\mu \\ln(J)\n" + "$$\n\n" + "with $I_1$ the first invariant of the right Cauchy-Green deformation " + "tensor and $J$ the determinant of the deformation gradient."}); } /*--------------------------------------------------------------------*/ @@ -1840,7 +1927,13 @@ std::unordered_map Global::v parameter("C1", {.description = "E or mue"}), parameter("C2", {.description = "nue or lambda"}), }, - {.description = "mixed logarithmic neo-Hooke material"}); + {.description = "Mixed logarithmic neo-Hooke material. The strain energy is computed as\n\n" + "$$\n" + "\\Psi = \\frac{\\mu}{2}(I_1-3) - \\mu \\ln(J) + " + "\\frac{\\lambda}{2}(J-1)^2\n" + "$$\n\n" + "with $I_1$ the first invariant of the right Cauchy-Green deformation " + "tensor and $J$ the determinant of the deformation gradient."}); } /*--------------------------------------------------------------------*/ @@ -1852,7 +1945,13 @@ std::unordered_map Global::v parameter("B", {.description = "material constant linear I_1"}), parameter("C", {.description = "material constant linear J"}), }, - {.description = "compressible, isochoric exponential material law for soft tissue"}); + {.description = "Compressible, isochoric exponential material law for soft tissue. The " + "strain energy is computed as\n\n" + "$$\n" + "\\Psi = a \\exp\\left[b(I_1-3)-(2b+c)\\ln(J)+c(J-1)\\right] - a\n" + "$$\n\n" + "with $I_1$ the first invariant of the right Cauchy-Green deformation " + "tensor and $J$ the determinant of the deformation gradient."}); } /*--------------------------------------------------------------------*/ @@ -1863,7 +1962,13 @@ std::unordered_map Global::v parameter("YOUNG", {.description = "Young's modulus", .default_value = 0.0}), parameter("NUE", {.description = "Poisson's ratio", .default_value = 0.0}), }, - {.description = "compressible neo-Hooke material acc. to Holzapfel"}); + {.description = "Compressible neo-Hooke material acc. to Holzapfel. The strain energy is " + "computed as\n\n" + "$$\n" + "\\Psi = c(I_1-3) + \\frac{c}{\\beta}\\left(I_3^{-\\beta} - 1\\right)\n" + "$$\n\n" + "with $c = E/(4(1+\\nu))$, $\\beta = \\nu/(1-2\\nu)$, and $I_1$, $I_3$ " + "the invariants of the right Cauchy-Green deformation tensor."}); } // Mooney Rivlin material acc. to Holzapfel { @@ -1873,7 +1978,13 @@ std::unordered_map Global::v parameter("C2", {.description = "material constant", .default_value = 0.0}), parameter("C3", {.description = "material constant", .default_value = 0.0}), }, - {.description = "Mooney - Rivlin material acc. to Holzapfel"}); + {.description = "Mooney-Rivlin material acc. to Holzapfel. The strain energy is computed " + "as\n\n" + "$$\n" + "\\Psi = c_1(I_1-3)+c_2(I_2-3)-(2c_1+4c_2)\\ln(J)+c_3(J-1)^2\n" + "$$\n\n" + "with $I_1$ and $I_2$ the invariants of the right Cauchy-Green deformation " + "tensor and $J$ the determinant of the deformation gradient."}); } /*--------------------------------------------------------------------*/ @@ -1885,7 +1996,15 @@ std::unordered_map Global::v parameter("NUE", {.description = "Poisson's ratio"}), parameter("F", {.description = "interpolation parameter"}), }, - {.description = "Blatz and Ko material acc. to Holzapfel"}); + {.description = "Blatz and Ko material acc. to Holzapfel. The strain energy is computed " + "as\n\n" + "$$\n" + "\\Psi = \\frac{\\mu}{2} \\left\\{f\\left[I_1-3+\\frac{I_3^{-\\beta}-1}" + "{\\beta}\\right] + (1-f)\\left[\\frac{I_2}{I_3}-3+" + "\\frac{I_3^{\\beta}-1}{\\beta}\\right]\\right\\}\n" + "$$\n\n" + "with $\\beta = \\nu/(1-2\\nu)$, and $I_1$, $I_2$, $I_3$ the invariants of " + "the right Cauchy-Green deformation tensor."}); } /*--------------------------------------------------------------------*/ @@ -1895,7 +2014,13 @@ std::unordered_map Global::v { input_field("MUE", {.description = "Shear modulus"}), }, - {.description = "isochoric part of neo-Hooke material acc. to Holzapfel"}); + {.description = "Isochoric part of neo-Hooke material acc. to Holzapfel. The strain " + "energy is computed as\n\n" + "$$\n" + "\\Psi = \\frac{\\mu}{2}(\\bar{I}_1 - 3)\n" + "$$\n\n" + "with $\\bar{I}_1$ the first invariant of the isochoric right " + "Cauchy-Green deformation tensor."}); } /*--------------------------------------------------------------------*/ @@ -1906,7 +2031,14 @@ std::unordered_map Global::v parameter("MUE", {.description = "Shear modulus"}), parameter("ALPHA", {.description = "Nonlinearity parameter"}), }, - {.description = "isochoric part of the one-term Ogden material"}); + {.description = "Isochoric part of the one-term Ogden material. The strain energy is " + "computed as\n\n" + "$$\n" + "\\Psi = \\frac{2\\mu}{\\alpha^2}\\left(\\bar{\\lambda}_1^{\\alpha} + " + "\\bar{\\lambda}_2^{\\alpha} + \\bar{\\lambda}_3^{\\alpha} - 3\\right)\n" + "$$\n\n" + "with $\\bar{\\lambda}_i$ the principal stretches of the isochoric right " + "Cauchy-Green deformation tensor."}); } /*--------------------------------------------------------------------*/ @@ -1918,7 +2050,13 @@ std::unordered_map Global::v parameter("C2", {.description = "Quadratic modulus"}), parameter("C3", {.description = "Cubic modulus"}), }, - {.description = "isochoric part of Yeoh material acc. to Holzapfel"}); + {.description = "Isochoric part of Yeoh material acc. to Holzapfel. The strain energy is " + "computed as\n\n" + "$$\n" + "\\Psi = c_1(\\bar{I}_1-3) + c_2(\\bar{I}_1-3)^2 + c_3(\\bar{I}_1-3)^3\n" + "$$\n\n" + "with $\\bar{I}_1$ the first invariant of the isochoric right Cauchy-Green " + "deformation tensor."}); } /*--------------------------------------------------------------------*/ @@ -1929,7 +2067,13 @@ std::unordered_map Global::v parameter("C", {.description = "material parameter"}), parameter("D", {.description = "exponent"}), }, - {.description = "isochoric part of general power material"}); + {.description = "Isochoric part of general power material. The strain energy is computed " + "as\n\n" + "$$\n" + "\\Psi = c(\\bar{I}_1-3)^d\n" + "$$\n\n" + "with $\\bar{I}_1$ the first invariant of the isochoric right Cauchy-Green " + "deformation tensor."}); } /*--------------------------------------------------------------------*/ @@ -1940,7 +2084,13 @@ std::unordered_map Global::v parameter("C", {.description = "material parameter"}), parameter("D", {.description = "exponent"}), }, - {.description = "isochoric part of general power material"}); + {.description = "Isochoric part of general power material. The strain energy is computed " + "as\n\n" + "$$\n" + "\\Psi = c(\\bar{I}_2-3)^d\n" + "$$\n\n" + "with $\\bar{I}_2$ the second invariant of the isochoric right " + "Cauchy-Green deformation tensor."}); } /*--------------------------------------------------------------------*/ @@ -1951,7 +2101,12 @@ std::unordered_map Global::v parameter("C", {.description = "material parameter"}), parameter("D", {.description = "exponent"}), }, - {.description = "part of general power material"}); + {.description = "Part of general power material. The strain energy is computed as\n\n" + "$$\n" + "\\Psi = c(I_1-3)^d\n" + "$$\n\n" + "with $I_1$ the first invariant of the right Cauchy-Green deformation " + "tensor."}); } /*--------------------------------------------------------------------*/ @@ -1962,7 +2117,12 @@ std::unordered_map Global::v parameter("C", {.description = "material parameter"}), parameter("D", {.description = "exponent"}), }, - {.description = "part of general power material"}); + {.description = "Part of general power material. The strain energy is computed as\n\n" + "$$\n" + "\\Psi = c(I_2-3)^d\n" + "$$\n\n" + "with $I_2$ the second invariant of the right Cauchy-Green deformation " + "tensor."}); } /*--------------------------------------------------------------------*/ @@ -1973,7 +2133,12 @@ std::unordered_map Global::v parameter("C", {.description = "material parameter"}), parameter("D", {.description = "exponent"}), }, - {.description = "part of general power material"}); + {.description = "Part of general power material. The strain energy is computed as\n\n" + "$$\n" + "\\Psi = c\\left(I_3^{1/3}-1\\right)^d\n" + "$$\n\n" + "with $I_3$ the third invariant of the right Cauchy-Green deformation " + "tensor."}); } /*--------------------------------------------------------------------*/ @@ -1986,7 +2151,11 @@ std::unordered_map Global::v parameter("A", {.description = "negative exponent of I3"}), }, {.description = - "hyperelastic potential summand for multiplicative coupled invariants I1 and I3"}); + "Hyperelastic potential summand for multiplicative coupled invariants I1 and I3. " + "The strain energy is computed as\n\n" + "$$\n" + "\\Psi = c\\left(I_1 I_3^{-a} - 3\\right)^d\n" + "$$"}); } /*--------------------------------------------------------------------*/ @@ -1998,7 +2167,14 @@ std::unordered_map Global::v parameter("K2", {.description = "material parameter"}), parameter("C", {.description = "exponent"}), }, - {.description = "isochoric part of exponential material acc. to Holzapfel"}); + {.description = "Isochoric part of exponential material acc. to Holzapfel. The strain " + "energy is computed as\n\n" + "$$\n" + "\\Psi = \\frac{k_1}{2k_2} \\left\\{\\exp\\left[k_2(\\bar{I}_1-3)^c" + "\\right]-1\\right\\}\n" + "$$\n\n" + "with $\\bar{I}_1$ the first invariant of the isochoric right " + "Cauchy-Green deformation tensor."}); } /*--------------------------------------------------------------------*/ @@ -2009,7 +2185,13 @@ std::unordered_map Global::v parameter("C1", {.description = "Linear modulus for first invariant"}), parameter("C2", {.description = "Linear modulus for second invariant"}), }, - {.description = "isochoric part of Mooney-Rivlin material acc. to Holzapfel"}); + {.description = "Isochoric part of Mooney-Rivlin material acc. to Holzapfel. The strain " + "energy is computed as\n\n" + "$$\n" + "\\Psi = c_1(\\bar{I}_1-3)+c_2(\\bar{I}_2-3)\n" + "$$\n\n" + "with $\\bar{I}_1$ and $\\bar{I}_2$ the invariants of the isochoric right " + "Cauchy-Green deformation tensor."}); } /*--------------------------------------------------------------------*/ @@ -2048,7 +2230,9 @@ std::unordered_map Global::v "FIBER_ORIENTATION", {.description = "A unit vector field pointing in the direction of the fibers."}), }, - {.description = "anisotropic Blemker muscle material"}); + {.description = "Anisotropic Blemker muscle material. No scalar potential is evaluated; " + "passive and time-dependent active stresses are assembled from the " + "piecewise muscle force laws."}); } /*--------------------------------------------------------------------*/ @@ -2059,7 +2243,15 @@ std::unordered_map Global::v parameter("C1", {.description = "Modulus for first invariant"}), parameter("C2", {.description = "Modulus for second invariant"}), }, - {.description = "test material to test elasthyper-toolbox"}); + {.description = "Test material to test elasthyper-toolbox. The strain energy is computed " + "as\n\n" + "$$\n" + "\\Psi = c_1 x + \\frac{c_1}{2} x^2 + c_2 y + \\frac{c_2}{2} y^2 + " + "(c_1+2c_2)\\,x y\n" + "$$\n\n" + "with $x = \\bar{I}_1-3$ and $y = \\bar{I}_2-3$, where $\\bar{I}_1$ and " + "$\\bar{I}_2$ are the invariants of the isochoric right Cauchy-Green " + "deformation tensor."}); } /*----------------------------------------------------------------------*/ @@ -2081,7 +2273,11 @@ std::unordered_map Global::v .size = from_parameter("NUMMAT")}), parameter("DEPOSITIONSTRETCH", {.description = "deposition stretch"}), }, - {.description = "General fiber material for remodeling"}); + {.description = "General fiber material for remodeling. No single fixed potential is " + "used; it combines the referenced exponential fiber potentials with " + "evolving remodeling and growth histories. Direction requirements: " + "variable number of directions, one for each referenced " + "remodeling-fiber contribution."}); } /*--------------------------------------------------------------------*/ @@ -2091,7 +2287,12 @@ std::unordered_map Global::v { parameter("KAPPA", {.description = "dilatation modulus"}), }, - {.description = "volumetric part of SussmanBathe material"}); + {.description = "Volumetric part of Sussman-Bathe material. The strain energy is computed " + "as\n\n" + "$$\n" + "\\Psi = \\frac{\\kappa}{2}(J-1)^2\n" + "$$\n\n" + "with $J$ the determinant of the deformation gradient."}); } /*--------------------------------------------------------------------*/ @@ -2102,7 +2303,12 @@ std::unordered_map Global::v parameter("EPSILON", {.description = "penalty parameter"}), parameter("GAMMA", {.description = "penalty parameter"}), }, - {.description = "Penalty formulation for the volumetric part"}); + {.description = "Penalty formulation for the volumetric part. The strain energy is " + "computed as\n\n" + "$$\n" + "\\Psi = \\epsilon\\left(J^{\\gamma} + J^{-\\gamma} - 2\\right)\n" + "$$\n\n" + "with $J$ the determinant of the deformation gradient."}); } /*--------------------------------------------------------------------*/ @@ -2113,7 +2319,14 @@ std::unordered_map Global::v parameter("KAPPA", {.description = "dilatation modulus"}), parameter("BETA", {.description = "empiric constant"}), }, - {.description = "Ogden formulation for the volumetric part"}); + {.description = "Ogden formulation for the volumetric part. The strain energy is computed " + "as\n\n" + "$$\n" + "\\Psi = \\frac{\\kappa}{\\beta^2}\\left[\\beta \\ln(J) + " + "J^{-\\beta} - 1\\right]\n" + "$$\n\n" + "with $J$ the determinant of the deformation gradient; for $\\beta=0$, " + "$\\Psi = \\frac{\\kappa}{2}(\\ln J)^2$."}); } /*--------------------------------------------------------------------*/ @@ -2124,7 +2337,12 @@ std::unordered_map Global::v parameter("A", {.description = "prefactor of power law"}), parameter("EXPON", {.description = "exponent of power law"}), }, - {.description = "Power law formulation for the volumetric part"}); + {.description = "Power law formulation for the volumetric part. The strain energy is " + "computed as\n\n" + "$$\n" + "\\Psi = \\frac{a}{n-1} J^{1-n} + a J\n" + "$$\n\n" + "with $n$ = EXPON and $J$ the determinant of the deformation gradient."}); } /*--------------------------------------------------------------------*/ @@ -2140,7 +2358,13 @@ std::unordered_map Global::v parameter( "STR_TENS_ID", {.description = "MAT ID for definition of Structural Tensor"}), parameter("INIT", - {.description = "initialization modus for fiber alignment", .default_value = 1}), + {.description = + "Initialization mode for fiber alignment: " + "0 - Fibers defined by material parameters on element basis;" + "1 - Fibers defined in input file on element basis;" + "4 - Fibers defined in material on gauss point basis, i.e., by nodes;" + "3 - Fibers defined in input file on gauss point basis, i.e., by nodes", + .default_value = 1}), parameter("ADAPT_ANGLE", {.description = "adapt angle during remodeling", .default_value = false}), parameter("S", {.description = "maximum contractile stress"}), @@ -2151,7 +2375,15 @@ std::unordered_map Global::v parameter( "DENS", {.description = "total reference mass density of constrained mixture"}), }, - {.description = "anisotropic active fiber"}); + {.description = "Anisotropic active fiber. The passive strain energy follows " + "ELAST_CoupAnisoExpo. In addition, the active response is computed as\n\n" + "$$\n" + "\\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]\n" + "$$\n\n" + "Direction requirements: 1 direction, given by an element fiber or the " + "cylindrical coordinate system."}); } /*--------------------------------------------------------------------*/ @@ -2167,14 +2399,29 @@ std::unordered_map Global::v parameter( "STR_TENS_ID", {.description = "MAT ID for definition of Structural Tensor"}), parameter("INIT", - {.description = "initialization modus for fiber alignment", .default_value = 1}), + {.description = + "Initialization mode for fiber alignment: " + "0 - Fibers defined by material parameters on element basis;" + "1 - Fibers defined in input file on element basis;" + "4 - Fibers defined in material on gauss point basis, i.e., by nodes;" + "3 - Fibers defined in input file on gauss point basis, i.e., by nodes", + .default_value = 1}), parameter("ADAPT_ANGLE", {.description = "adapt angle during remodeling", .default_value = false}), parameter("FIBER_ID", {.description = "Id of the fiber to be used (1 for first fiber, default)", .default_value = 1}), }, - {.description = "anisotropic part with one exp. fiber"}); + {.description = "Anisotropic part with one exponential fiber. The strain energy is " + "computed as\n\n" + "$$\n" + "\\Psi = \\frac{k_1}{2k_2} \\left\\{\\exp\\left[k_2(I_4-1)^2\\right]" + "-1\\right\\}\n" + "$$\n\n" + "with $I_4$ the pseudo-invariant associated with the fiber direction. " + "K1COMP and K2COMP apply the same law in compression. Direction " + "requirements: 1 direction, given by an element fiber or the cylindrical " + "coordinate system; `FIBER_ID` selects the element fiber."}); } /*--------------------------------------------------------------------*/ @@ -2188,13 +2435,28 @@ std::unordered_map Global::v parameter("K1COMP", {.description = "linear constant"}), parameter("K2COMP", {.description = "exponential constant"}), parameter("INIT", - {.description = "initialization modus for fiber alignment", .default_value = 1}), + {.description = + "Initialization mode for fiber alignment: " + "0 - Fibers defined by material parameters on element basis;" + "1 - Fibers defined in input file on element basis;" + "4 - Fibers defined in material on gauss point basis, i.e., by nodes;" + "3 - Fibers defined in input file on gauss point basis, i.e., by nodes", + .default_value = 1}), parameter>( "FIBER_IDS", {.description = "Ids of the two fibers to be used (1 for the first " "fiber, 2 for the second, default)", .size = 2}), }, - {.description = "Exponential shear behavior between two fibers"}); + {.description = "Exponential shear behavior between two fibers. The strain energy is " + "computed as\n\n" + "$$\n" + "\\Psi = \\frac{k_1}{2k_2} \\left\\{\\exp\\left[k_2(I_8 - " + "\\mathbf{a}_1\\cdot\\mathbf{a}_2)^2\\right]-1\\right\\}\n" + "$$\n\n" + "with $I_8$ the mixed pseudo-invariant of the two fiber directions " + "$\\mathbf{a}_1$ and $\\mathbf{a}_2$. Direction requirements: 2 " + "directions; requires explicit element or Gauss-point fibers selected by " + "`FIBER_IDS`, a cylindrical coordinate system is not supported."}); } /*--------------------------------------------------------------------*/ @@ -2216,11 +2478,26 @@ std::unordered_map Global::v .default_value = 1}), parameter("GAMMA", {.description = "angle", .default_value = 0.0}), parameter("INIT", - {.description = "initialization modus for fiber alignment", .default_value = 1}), + {.description = + "Initialization mode for fiber alignment: " + "0 - Fibers defined by material parameters on element basis;" + "1 - Fibers defined in input file on element basis;" + "4 - Fibers defined in material on gauss point basis, i.e., by nodes;" + "3 - Fibers defined in input file on gauss point basis, i.e., by nodes", + .default_value = 1}), parameter("ADAPT_ANGLE", {.description = "adapt angle during remodeling", .default_value = false}), }, - {.description = "anisotropic part with one pow-like fiber"}); + {.description = "Anisotropic part with one pow-like fiber. Where active, the strain " + "energy is computed as\n\n" + "$$\n" + "\\Psi = k\\left(I_4^{d_1}-1\\right)^{d_2}\n" + "$$\n\n" + "with $I_4$ the pseudo-invariant associated with the fiber direction; " + "ACTIVETHRES disables its stress contribution below the selected fiber " + "stretch. Direction requirements: 1 direction, given by an element fiber " + "or the cylindrical coordinate system; its `FIBER` selector chooses the " + "family."}); } /*--------------------------------------------------------------------*/ @@ -2242,14 +2519,30 @@ std::unordered_map Global::v parameter( "STR_TENS_ID", {.description = "MAT ID for definition of Structural Tensor"}), parameter("INIT", - {.description = "initialization modus for fiber alignment", .default_value = 1}), + {.description = + "Initialization mode for fiber alignment: " + "0 - Fibers defined by material parameters on element basis;" + "1 - Fibers defined in input file on element basis;" + "4 - Fibers defined in material on gauss point basis, i.e., by nodes;" + "3 - Fibers defined in input file on gauss point basis, i.e., by nodes", + .default_value = 1}), parameter( "FIB_COMP", {.description = "fibers support compression: yes (true) or no (false)", .default_value = true}), parameter("ADAPT_ANGLE", {.description = "adapt angle during remodeling", .default_value = false}), }, - {.description = "anisotropic part with two exp. fibers"}); + {.description = "Anisotropic part with two exponential fibers. The strain energy is " + "computed as\n\n" + "$$\n" + "\\Psi = \\sum_{\\alpha=4,6,8} \\frac{a_\\alpha}{2b_\\alpha} " + "\\left[\\exp\\left(b_\\alpha x_\\alpha^2\\right)-1\\right]\n" + "$$\n\n" + "with $x_4 = I_4-1$, $x_6 = I_6-1$, and $x_8 = I_8 - " + "\\mathbf{a}_1\\cdot\\mathbf{a}_2$, where $I_4$, $I_6$, $I_8$ are the " + "pseudo-invariants of the two fiber directions $\\mathbf{a}_1$, " + "$\\mathbf{a}_2$. Direction requirements: 2 directions, given by element " + "fibers or the cylindrical coordinate system."}); } /*--------------------------------------------------------------------*/ @@ -2262,52 +2555,72 @@ std::unordered_map Global::v parameter( "STR_TENS_ID", {.description = "MAT ID for definition of Structural Tensor"}), parameter("INIT", - {.description = "initialization modus for fiber alignment", .default_value = 1}), + {.description = + "Initialization mode for fiber alignment: " + "0 - Fibers defined by material parameters on element basis;" + "1 - Fibers defined in input file on element basis;" + "4 - Fibers defined in material on gauss point basis, i.e., by nodes;" + "3 - Fibers defined in input file on gauss point basis, i.e., by nodes", + .default_value = 1}), parameter("ADAPT_ANGLE", {.description = "adapt angle during remodeling", .default_value = false}), }, - {.description = "anisotropic part with one neo Hookean fiber"}); + {.description = "Anisotropic part with one neo-Hookean fiber. The strain energy is " + "computed as\n\n" + "$$\n" + "\\Psi = c(I_4-1)\n" + "$$\n\n" + "with $I_4$ the pseudo-invariant associated with the fiber direction. " + "Direction requirements: 1 direction, given by an element fiber or the " + "cylindrical coordinate system."}); } /*--------------------------------------------------------------------*/ // coupled anisotropic material with the stress given by a simplified version of the contraction // law of Bestel-Clement-Sorine { - known_materials[Core::Materials::mes_anisoactivestress_evolution] = - group("ELAST_AnisoActiveStress_Evolution", - { - parameter("SIGMA", {.description = "Contractility (maximal stress)"}), - parameter("TAUC0", {.description = "Initial value for the active stress"}), - parameter( - "MAX_ACTIVATION", {.description = "Maximal value for the rescaled activation"}), - parameter( - "MIN_ACTIVATION", {.description = "Minimal value for the rescaled activation"}), - parameter("SOURCE_ACTIVATION", - {.description = "Where the activation comes from: 0=scatra , >0 Id for FUNCT"}), - parameter("ACTIVATION_THRES", - {.description = "Threshold for activation (contraction starts when activation " - "function is larger than this value, relaxes otherwise)"}), - parameter("STRAIN_DEPENDENCY", - {.description = "model strain dependency of contractility (Frank-Starling " - "law): no (false) or yes (true)", - .default_value = false}), - parameter( - "LAMBDA_LOWER", {.description = "lower fiber stretch for Frank-Starling law", - .default_value = 1.0}), - parameter( - "LAMBDA_UPPER", {.description = "upper fiber stretch for Frank-Starling law", - .default_value = 1.0}), - parameter("GAMMA", {.description = "angle", .default_value = 0.0}), - parameter( - "STR_TENS_ID", {.description = "MAT ID for definition of Structural Tensor"}), - parameter("INIT", - {.description = "initialization mode for fiber alignment", .default_value = 1}), - parameter("ADAPT_ANGLE", - {.description = "adapt angle during remodeling", .default_value = false}), - }, - {.description = - "anisotropic part with one fiber with coefficient given by a simplification of " - "the activation-contraction law of Bestel-Clement-Sorine-2001"}); + known_materials[Core::Materials::mes_anisoactivestress_evolution] = group( + "ELAST_AnisoActiveStress_Evolution", + { + parameter("SIGMA", {.description = "Contractility (maximal stress)"}), + parameter("TAUC0", {.description = "Initial value for the active stress"}), + parameter( + "MAX_ACTIVATION", {.description = "Maximal value for the rescaled activation"}), + parameter( + "MIN_ACTIVATION", {.description = "Minimal value for the rescaled activation"}), + parameter("SOURCE_ACTIVATION", + {.description = "Where the activation comes from: 0=scatra , >0 Id for FUNCT"}), + parameter("ACTIVATION_THRES", + {.description = "Threshold for activation (contraction starts when activation " + "function is larger than this value, relaxes otherwise)"}), + parameter("STRAIN_DEPENDENCY", + {.description = "model strain dependency of contractility (Frank-Starling " + "law): no (false) or yes (true)", + .default_value = false}), + parameter( + "LAMBDA_LOWER", {.description = "lower fiber stretch for Frank-Starling law", + .default_value = 1.0}), + parameter( + "LAMBDA_UPPER", {.description = "upper fiber stretch for Frank-Starling law", + .default_value = 1.0}), + parameter("GAMMA", {.description = "angle", .default_value = 0.0}), + parameter( + "STR_TENS_ID", {.description = "MAT ID for definition of Structural Tensor"}), + parameter("INIT", + {.description = "initialization mode for fiber alignment", .default_value = 1}), + parameter("ADAPT_ANGLE", + {.description = "adapt angle during remodeling", .default_value = false}), + }, + {.description = + "Anisotropic part with one fiber with coefficient given by a simplification of " + "the activation-contraction law of Bestel-Clement-Sorine-2001. No stored-energy " + "potential is evaluated; it supplies the evolving active stress\n\n" + "$$\n" + "\\mathbf{S}_\\mathrm{act} = \\tau(t)\\, \\mathbf{A}\n" + "$$\n\n" + "with $\\mathbf{A}$ the structural tensor of the fiber direction. Direction " + "requirements: 1 direction, given by an element fiber or the cylindrical " + "coordinate system."}); } /*--------------------------------------------------------------------*/ @@ -2328,7 +2641,15 @@ std::unordered_map Global::v parameter("ADAPT_ANGLE", {.description = "adapt angle during remodeling", .default_value = false}), }, - {.description = "anisotropic part with one neo Hookean fiber with variable coefficient"}); + {.description = "Anisotropic part with one neo-Hookean fiber with variable coefficient. " + "The strain energy is computed as\n\n" + "$$\n" + "\\Psi = c(\\mathbf{x},t)(I_4-1)\n" + "$$\n\n" + "with $I_4$ the pseudo-invariant associated with the fiber direction and " + "SOURCE_ACTIVATION defining the spatially and temporally varying " + "coefficient $c(\\mathbf{x},t)$. Direction requirements: 1 direction, " + "given by an element fiber or the cylindrical coordinate system."}); } /*--------------------------------------------------------------------*/ @@ -2344,11 +2665,26 @@ std::unordered_map Global::v parameter( "STR_TENS_ID", {.description = "MAT ID for definition of Structural Tensor"}), parameter("INIT", - {.description = "initialization modus for fiber alignment", .default_value = 1}), + {.description = + "Initialization mode for fiber alignment: " + "0 - Fibers defined by material parameters on element basis;" + "1 - Fibers defined in input file on element basis;" + "4 - Fibers defined in material on gauss point basis, i.e., by nodes;" + "3 - Fibers defined in input file on gauss point basis, i.e., by nodes", + .default_value = 1}), parameter("ADAPT_ANGLE", {.description = "adapt angle during remodeling", .default_value = false}), }, - {.description = "anisotropic part with one exp. fiber"}); + {.description = "Anisotropic part with one exponential fiber, combined isochoric-" + "anisotropic response. The strain energy is computed as\n\n" + "$$\n" + "\\Psi = \\frac{k_1}{2k_2} \\left\\{\\exp\\left[k_2(\\bar{I}_4-1)^2" + "\\right]-1\\right\\}\n" + "$$\n\n" + "with $\\bar{I}_4 = J^{-2/3} I_4$ the isochoric pseudo-invariant " + "associated with the fiber direction. Direction requirements: 1 " + "direction, given by an element fiber or the cylindrical coordinate " + "system."}); } /*--------------------------------------------------------------------*/ @@ -2379,7 +2715,16 @@ std::unordered_map Global::v parameter("C4", {.description = "constant 4 for distribution function", .default_value = 1e16}), }, - {.description = "Structural tensor strategy in anisotropic materials"}); + {.description = + "Structural tensor strategy in anisotropic materials. No potential is " + "evaluated; it supplies the structural tensor $\\mathbf{A}$, for example\n\n" + "$$\n" + "\\mathbf{A} = \\mathbf{a} \\otimes \\mathbf{a}\n" + "$$\n\n" + "for the Standard strategy, with $\\mathbf{a}$ the fiber direction and " + "$\\otimes$ the dyadic product. Direction requirements: 1 direction, " + "defining the mean fiber direction the structural tensor is built from; " + "this is a helper rather than an independent strain-energy term."}); } /*--------------------------------------------------------------------*/ @@ -2396,10 +2741,23 @@ std::unordered_map Global::v "STR_TENS_ID", {.description = "MAT ID for definition of Structural Tensor"}), parameter("FIBER", {.description = "exponential constant", .default_value = 1}), parameter("INIT", - {.description = "initialization modus for fiber alignment", .default_value = 1}), + {.description = + "Initialization mode for fiber alignment: " + "0 - Fibers defined by material parameters on element basis;" + "1 - Fibers defined in input file on element basis;" + "4 - Fibers defined in material on gauss point basis, i.e., by nodes;" + "3 - Fibers defined in input file on gauss point basis, i.e., by nodes", + .default_value = 1}), }, - {.description = "transversely part of a simple othotropic, transversely isotropic " - "hyperelastic constitutive equation"}); + {.description = "Transversely part of a simple orthotropic, transversely isotropic " + "hyperelastic constitutive equation. The strain energy is computed as\n\n" + "$$\n" + "\\Psi = \\left[\\alpha + \\frac{\\beta}{2}\\ln(I_3) + " + "\\gamma(I_4-1)\\right](I_4-1) - \\frac{\\alpha}{2}(I_5-1)\n" + "$$\n\n" + "with $I_3$, $I_4$, $I_5$ invariants of the right Cauchy-Green deformation " + "tensor and the fiber direction. Direction requirements: 1 direction, " + "given by an element fiber or the cylindrical coordinate system."}); } /*--------------------------------------------------------------------*/ @@ -2410,7 +2768,13 @@ std::unordered_map Global::v parameter("MUE", {.description = "Shear modulus"}), parameter("BETA", {.description = "'Anti-modulus'"}), }, - {.description = "Varga material acc. to Holzapfel"}); + {.description = "Varga material acc. to Holzapfel. The strain energy is computed as\n\n" + "$$\n" + "\\Psi = (2\\mu-\\beta)(\\lambda_1+\\lambda_2+\\lambda_3-3) + " + "\\beta\\left(\\lambda_1^{-1}+\\lambda_2^{-1}+\\lambda_3^{-1}-3\\right)\n" + "$$\n\n" + "with $\\lambda_i$ the principal stretches of the right Cauchy-Green " + "deformation tensor."}); } /*--------------------------------------------------------------------*/ @@ -2421,7 +2785,15 @@ std::unordered_map Global::v parameter("MUE", {.description = "Shear modulus"}), parameter("BETA", {.description = "'Anti-modulus'"}), }, - {.description = "Isochoric Varga material acc. to Holzapfel"}); + {.description = "Isochoric Varga material acc. to Holzapfel. The strain energy is " + "computed as\n\n" + "$$\n" + "\\Psi = (2\\mu-\\beta)\\left(\\bar{\\lambda}_1+\\bar{\\lambda}_2+" + "\\bar{\\lambda}_3-3\\right) + \\beta\\left(\\bar{\\lambda}_1^{-1}+" + "\\bar{\\lambda}_2^{-1}+\\bar{\\lambda}_3^{-1}-3\\right)\n" + "$$\n\n" + "with $\\bar{\\lambda}_i$ the principal stretches of the isochoric right " + "Cauchy-Green deformation tensor."}); } /*--------------------------------------------------------------------*/ @@ -2431,7 +2803,14 @@ std::unordered_map Global::v { parameter("N", {.description = "material parameter"}), }, - {.description = "Iso-rate viscous contribution of myocardial matrix"}); + {.description = + "Coupled myocardial viscoelastic contribution.\n\n" + "$$\n" + "\\Phi_\\mathrm{v} = \\frac{\\eta}{2}\\dot{\\boldsymbol E}:\\dot{\\boldsymbol E} " + "= \\frac{\\eta}{8}\\dot{\\boldsymbol C}:\\dot{\\boldsymbol C}\n" + "$$\n\n" + "hence $\\boldsymbol S_\\mathrm{v}=\\eta\\dot{\\boldsymbol E}$; `N` is " + "$\\eta$."}); } /*--------------------------------------------------------------------*/ @@ -2441,7 +2820,13 @@ std::unordered_map Global::v { parameter("N", {.description = "material parameter"}), }, - {.description = "Isochoric iso-rate viscous summand"}); + {.description = "Isochoric rate-dependent contribution.\n\n" + "$$\n" + "\\Phi_\\mathrm{v} = n\\,\\bar J_2(\\bar I_1-3)\n" + "$$\n\n" + "with $\\bar J_2=\\frac12\\dot{\\bar{\\boldsymbol C}}:" + "\\dot{\\bar{\\boldsymbol C}}$. The rate is evaluated by a backward " + "difference."}); } /*--------------------------------------------------------------------*/ @@ -2453,7 +2838,22 @@ std::unordered_map Global::v parameter("ALPHA", {.description = "fractional order derivative"}), parameter("BETA", {.description = "emphasis of viscous to elastic part"}), }, - {.description = "Fractional standard linear solid visco summand"}); + {.description = + "Fractional standard linear solid.\n" + "Hereditary viscous stress update from artificial stress $\\boldsymbol Q$. With " + "\n\n" + "$$\n" + "b_0=1,\\quad b_j=\\frac{j-1-\\alpha}{j}b_{j-1}, \\quad" + "\\lambda_1=\\frac{\\Delta t^\\alpha}{\\Delta t^\\alpha+\\tau^\\alpha},\\quad" + "\\lambda_2=-\\frac{\\tau^\\alpha}{\\Delta t^\\alpha+\\tau^\\alpha},\n" + "$$\n\n" + "the implemented history update is \n\n" + "$$\n" + "\\boldsymbol Q^{n+1}=\\lambda_1\\beta\\boldsymbol S_0^{n+1}" + "+\\lambda_2\\sum_{j=1}^{m}b_j\\boldsymbol Q^{n+1-j}," + "\\quad \\boldsymbol S_\\mathrm{v}^{n+1}" + "=\\boldsymbol Q^{n+1}-\\beta\\boldsymbol S_0^{n+1}.\n" + "$$\n"}); } /*--------------------------------------------------------------------*/ @@ -2469,7 +2869,15 @@ std::unordered_map Global::v "ExponentialTimeDiscretization (convolution integral)", .default_value = "OneStepTheta"}), }, - {.description = "Top-level generalized Maxwell visco summand"}); + {.description = + "Generalized Maxwell model, obtains a separate elastic law and $\\tau$ from each " + "VISCO_GeneralizedMaxwellBranch.\n\n" + "$$\n" + "\\boldsymbol S_\\mathrm{v} = \\sum_i \\boldsymbol Q_i\n" + "$$\n\n" + "where $\\dot{\\boldsymbol Q}_i+\\boldsymbol Q_i/\\tau_i=" + "\\dot{\\boldsymbol S}^{\\,e}_i$. Each $\\boldsymbol S^{\\,e}_i$ comes from " + "the elastic material referenced by its branch."}); } /*--------------------------------------------------------------------*/ @@ -2496,7 +2904,19 @@ std::unordered_map Global::v .default_value = 0.0, .validator = positive_or_zero()}), }, - {.description = "Fung-type quasi-linear generalized Maxwell viscoelastic summand"}); + {.description = + "Fung-type quasi-linear generalized Maxwell model; " + "uses $\\beta$ and $\\tau$ arrays and drives every branch from the same " + "surrounding hyperelastic base law. " + "Its optional viscosity $\\eta$ defines the parallel-dashpot pseudo-potential " + "$\\Phi_\\eta=\\frac{\\eta}{2}\\dot{\\boldsymbol E}:\\dot{\\boldsymbol E}$, " + "from which the viscous stress is derived as\n\n" + "$$\n" + "\\boldsymbol S_\\mathrm{v} = \\sum_i \\boldsymbol Q_i + " + "\\eta\\dot{\\boldsymbol E} \\quad \\text{with} \\quad " + "\\dot{\\boldsymbol Q}_i+\\boldsymbol Q_i/\\tau_i=" + "\\beta_i\\dot{\\boldsymbol S}_0.\n" + "$$\n"}); } /*--------------------------------------------------------------------*/ @@ -2508,7 +2928,9 @@ std::unordered_map Global::v "TAU", {.description = "dynamic viscosity divided by branch stiffness"}), parameter("MATID", {.description = "material ID of branch elasticity rule"}), }, - {.description = "Branch definition for a generalized Maxwell visco summand"}); + {.description = "Branch referenced by a generalized Maxwell model.\n\n" + "No independent equation; `MATID` defines $\\boldsymbol S^{\\,e}_i$ and " + "`TAU` defines $\\tau_i$ in the parent Maxwell law."}); } /*--------------------------------------------------------------------*/ @@ -4716,7 +5138,9 @@ std::unordered_map Global::v .default_value = std::vector{0.}, .size = from_parameter("NUMTWINSETS")}), }, - {.description = " Crystal plasticity "}); + {.description = "Crystal plasticity. Direction requirements: 3 directions; " + "`FIBER1`--`FIBER3` are the columns of the crystal-to-global rotation " + "matrix."}); } /*--------------------------------------------------------------------*/ diff --git a/utilities/four_c_python/src/four_c_documentation/make_documentation.py b/utilities/four_c_python/src/four_c_documentation/make_documentation.py index d4b5a83eddc..361ef6cc024 100644 --- a/utilities/four_c_python/src/four_c_documentation/make_documentation.py +++ b/utilities/four_c_python/src/four_c_documentation/make_documentation.py @@ -483,7 +483,21 @@ def one_of_to_md(one_of: One_Of, path_prefix: str = ""): def set_missing_description(description): if check_if_set(description): - return "*" + description + "*" + # CommonMark emphasis (*...*) cannot span a blank line, so a description + # consisting of multiple paragraphs (e.g. containing a display math block) + # must not be wrapped as a single italic span. Instead, italicize each + # paragraph separately and leave display math blocks ($$...$$) unwrapped. + paragraphs = description.split("\n\n") + if len(paragraphs) == 1: + return "*" + description + "*" + + wrapped_paragraphs = [] + for paragraph in paragraphs: + if paragraph.strip().startswith("$$") and paragraph.strip().endswith("$$"): + wrapped_paragraphs.append(paragraph) + else: + wrapped_paragraphs.append("*" + paragraph + "*") + return "\n\n".join(wrapped_paragraphs) else: return DESCRIPTION_MISSING