Extended documentation for solid materials

[ischeider]

Description and Context

The analysis guide is being extended by a description of the solid material models. The added doc includes documentation for all
model representing

• elasticity
• plasticity
• viscoelasticity
• hyperelastic framework
• viscohyperelastic framework

No Mixture or Growth models are included so far (because I have no clue about them ;-) )

The LLM, which looked up for the available models and respective equations for me, also identified flaws in the output of two material models, which will be fixed in a separate PR.

[Copilot]

Pull request overview

Note

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Extends the analysis guide with new documentation pages covering continuum solid material families (elastic, hyperelastic framework/summands, viscoelasticity, and plasticity), and adds cross-links/navigation for these pages.

Changes:

• Added new analysis-guide pages for elastic materials, hyperelastic framework (including summand catalogs), viscoelastic materials, and plasticity materials.
• Expanded the main “Structural Material Models” page with links, a “Material directions” section, and a hidden toctree for navigation.
• Updated documentation CMake configuration to copy additional regression input files used by the new Jinja templates.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
doc/documentation/src/analysis_guide_templates/viscoelastic_materials.rst.j2	New viscoelastic material documentation + equations and references.
doc/documentation/src/analysis_guide_templates/plasticity_materials.rst.j2	New plasticity material documentation with overview tables and detailed sections.
doc/documentation/src/analysis_guide_templates/materials.rst.j2	Adds navigation to the new pages and documents material direction assignment.
doc/documentation/src/analysis_guide_templates/hyperelastic_isotropic_coupled.rst	New catalog of coupled isotropic hyperelastic summands.
doc/documentation/src/analysis_guide_templates/hyperelastic_isochoric_volumetric.rst.j2	New catalog of split isochoric/volumetric hyperelastic summands + example dump.
doc/documentation/src/analysis_guide_templates/hyperelastic_framework.rst.j2	New hyperelastic framework overview, composition rules, notation, and toctree.
doc/documentation/src/analysis_guide_templates/hyperelastic_anisotropic.rst.j2	New catalog of anisotropic/active/structural-tensor summands + example dump.
doc/documentation/src/analysis_guide_templates/elastic_materials.rst.j2	New elastic-materials page with examples sourced from regression inputs.
doc/documentation/CMakeLists.txt	Copies additional test input files so templates can load_input_file(...).

[ischeider]

Added the brand new material model by @lauraengelhardt ;-)

[bgoderbauer]

Thanks a lot for improving the documentation! I've mainly looked into viscoelastic materials, which I think provide just the right amount of user-facing information.

[rjoussen]

I really like this direction and the initiative to add more thorough documentation for the materials! We definitely need more documentation on them, and especially putting them into the different categories that you defined makes a lot of sense and really helps with finding/selecting the right material.

The main problem I am seeing with this approach, though, is that it adds a giant second source of truth. The material descriptions and categories might be correct and up to date right now, but they will inevitably drift out of sync with the codebase over time. With this, almost every change to the material code will then also require changes to the documentation (e.g., deleting or adding a material, changing parameter names, enabling a material for different kinematics, adding coupling, ...).

On top of that, I think we already have a place for material documentation in the schema descriptions, which are also directly useful when writing YAML input files. I think much of the information added here could instead live there (because these descriptions are often way too short)

Regarding the categorization of materials, I think a safer approach would be to either put them in subfolders in the codebase and use that structure directly in the documentation (I never understood why all ~270 materials are in the same folder anyway), or to use some sort of a tagging system (like tag materials with their supported kinematics, what category they are, for what physics, etc.) and then use these tags to generate the documentation. Such tags could live closer to the actual implementation and are hence easier to maintain.

So, to sum up, I definitely agree that this additional documentation would be a massive improvement right now, but I also think it has the potential to become outdated very quickly and, as a result, become counterproductive.

Of course, I am also open to discussing this, those are just my personal thoughts on it :)

[lauraengelhardt]

Thanks a lot, Ingo, for adding the documentation. I took a look at the hyperelastic materials. Someone else will have to check plasticity and viscoelasticity ;)

[lauraengelhardt]

I think this should actually be Solid material models.
I know we are not really concise with the distinction between solid and structural mechanics in 4C.

[lauraengelhardt]

Just one question here as well: I assume we are aiming to document all materials that derive from So3Material, correct?

[ischeider]

It is still a subset of the So3Material, since I did not include the MIXTURE materials nor Muscle materials (maybe others also left out). Let say, these are (most of) the general purpose materials. But you are right, since the title is Solid Material Models, it should contain all materials derived from So3Material, or one has to scope the section.

[lauraengelhardt]

Maybe just make this one consistent section with the split/coupled above "Basics of hyperelastic continuum mechanical material modeling" or so?

[ischeider]

Reordered the section. Maybe I could also remove the whole subseciton title "Notation for the potentials".