Extended documentation for solid materials - #2146
Conversation
There was a problem hiding this comment.
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(...). |
It's about elasticity, plasticity, and viscoelastic materials
Description of elastic, hyper- and viscoelastic materials
043db85 to
4e1febe
Compare
|
Added the brand new material model by @lauraengelhardt ;-) |
bgoderbauer
left a comment
bgoderbauer
left a comment
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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
left a comment
lauraengelhardt
left a comment
There was a problem hiding this comment.
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 ;)
|
|
||
|
|
||
|
|
||
| Structural Material Models |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Just one question here as well: I assume we are aiming to document all materials that derive from So3Material, correct?
There was a problem hiding this comment.
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.
| vectors. For a native |FOURC| mesh, append consecutive ``FIBER1``, ``FIBER2``, and, where | ||
| required, ``FIBER3`` vectors to each entry in ``STRUCTURE ELEMENTS``: |
There was a problem hiding this comment.
| vectors. For a native |FOURC| mesh, append consecutive ``FIBER1``, ``FIBER2``, and, where | |
| required, ``FIBER3`` vectors to each entry in ``STRUCTURE ELEMENTS``: | |
| vectors. For a native |FOURC| mesh, append consecutive ``FIBER1``, and, where required ``FIBER2``, and ``FIBER3`` vectors to each entry in ``STRUCTURE ELEMENTS``: |
| - :doc:`viscoelastic_materials` | ||
| - :doc:`plasticity_materials` | ||
|
|
||
| Material directions |
There was a problem hiding this comment.
Everything written in this section only applies to materials that rely on the Anisotropy extension. There are several materials (the muscle materials and all mixture materials) that rely on fiber input through a vtu file (using FiberInterpolation). Maybe you can start the section somewhat like this:
- how anisotropy is handled depends on the material itself
- there are two approaches:
AnisotropyandFiberInterpolation - for
Anisotropythe way to input is through native 4C or constant in the element block (just as you wrote) - for
FiberInterpolationI can supply a short description after ;)
| FIBER2: [0.0, 1.0, 0.0] | ||
|
|
||
| This applies the specified directions to the complete block. No regression input currently | ||
| exercises fiber assignment through ``STRUCTURE GEOMETRY``. |
There was a problem hiding this comment.
What do you mean with "No regression input"`?
|
|
||
| As an alternative, solid elements accept the local coordinate-system vectors ``RAD``, ``AXI``, | ||
| and ``CIR``. All three must be given together. For materials using the default anisotropy | ||
| framework, this coordinate system takes precedence over explicit ``FIBER*`` vectors. Some |
There was a problem hiding this comment.
For materials using the default anisotropy
framework, this coordinate system takes precedence over explicitFIBER*vectors
I'm not so sure about this. Do you mean when you give both then RAD/AXI/CIR is used?
There was a problem hiding this comment.
If you give FIBERi and RAD/AXI/CIR, then the values for RAD|AXI|CIR are the relevant ones, the value for FIBERi are ignored. I tested it with an example where I entered fiber directions for one element by FIBER1/FIBER2 in addition to the existing RAD... values => it's true, the results don't change (and no error is thrown).
There was a problem hiding this comment.
Uff ok. IMO, this is rather a bug than intended behavior. I cannot imagine any scenario where defining both would make sense. I would rather open an issue and fix the problem than reporting it here. What do you think?
| The plain ``MAT_ElastHyper`` framework accepts elastic summands only. Use | ||
| :doc:`viscoelastic_materials` when adding time-dependent branches. | ||
|
|
||
| Notation for the potentials |
There was a problem hiding this comment.
Maybe just make this one consistent section with the split/coupled above "Basics of hyperelastic continuum mechanical material modeling" or so?
| 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 }}``. |
There was a problem hiding this comment.
Also here a very long example... Can we just use the MAT 1 part?
| ======================================= | ||
|
|
||
| These summands define compressible isotropic energies that depend on the full deformation. They | ||
| are referenced through ``MAT_ElastHyper.MATIDS`` and generally do not require a separate |
There was a problem hiding this comment.
MAT_ElastHyper.MATIDS ?
| structural-tensor strategy for several anisotropic summands but does not replace the underlying | ||
| mean fiber direction. | ||
|
|
||
| If you wish to implement a new material model, this is of course also possible, it is an in-house code after all. |
There was a problem hiding this comment.
| If you wish to implement a new material model, this is of course also possible, it is an in-house code after all. |
| :header-rows: 1 | ||
| :widths: 35 65 | ||
|
|
||
| * - Summand |
There was a problem hiding this comment.
I did not check all equations in detail yet. What I am wondering: Is there any way how we can ensure that this does not become outdated?
There was a problem hiding this comment.
@rjoussen I had the same thoughts as you had here as well!
I think introducing the general material subclasses is a good idea as they will not become outdated so fast (as I mentioned above, assuming the examples are taken from the codebase anyhow, such that changes in the parameter names etc. are automatically included in the doc).
If we want to include the actual materials we need a way to do this automatically.
I also agree with you @rjoussen: Moving the strain energy functions to the input parameter descriptions (as you recommended me to do for the TCA model) would be a good idea. In the documentation we could just link that?
- I also agree regarding moving materials to subfolders.
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
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.