Directionally distributed active stress

[aabrown100-git]

Current situation

Resolves #496

Release Notes

• Allow user to specify what fraction of total active stress is applied in the fiber, sheet, and sheet-normal directions
• Implemented for the following material models: Guccione, Holzapfel-Ogden, and Holzapfel-Ogden-Modified-Anisotropy

Documentation

Document on SimVascular website?

Testing

• Added new test case struct/directionally_distributed_active_stress

Code of Conduct & Contributing Guidelines

• I agree to follow the Code of Conduct and Contributing Guidelines.

[Copilot]

Pull request overview

Adds support for distributing total active (fiber reinforcement) stress across fiber, sheet, and sheet-normal directions, and introduces a new regression test case exercising the feature.

Changes:

• Adds new XML parameters to specify active stress fractions in fiber/sheet/sheet-normal directions and validates their sum.
• Updates material model stress assembly to apply directional active stress (implemented in Guccione, Holzapfel-Ogden, and Holzapfel-Ogden-Modified-Anisotropy paths).
• Adds a new struct/directionally_distributed_active_stress test case and hooks it into the Python test suite.

Reviewed changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
Code/Source/solver/read_files.cpp	Reads new fraction parameters and validates them.
Code/Source/solver/mat_models.cpp	Computes/distributes total active stress and applies it in select constitutive-model branches.
Code/Source/solver/distribute.cpp	Broadcasts the new fraction parameters in parallel runs.
Code/Source/solver/Parameters.h	Documents new XML tags for fiber reinforcement stress.
Code/Source/solver/Parameters.cpp	Registers new XML parameters with defaults.
Code/Source/solver/ComMod.h	Stores new per-domain fraction values in fibStrsType.
tests/test_struct.py	Adds a new pytest entry for the new struct test case.
tests/cases/struct/directionally_distributed_active_stress/solver.xml	New solver input demonstrating 70/20/10 directional stress fractions.
tests/cases/struct/directionally_distributed_active_stress/README.md	Documents the new test case and expected behavior.
tests/cases/struct/directionally_distributed_active_stress/generate_stress.py	Utility to regenerate stress.dat and plot the profile.
tests/cases/struct/directionally_distributed_active_stress/stress.dat	Test input time series (Git LFS).
tests/cases/struct/directionally_distributed_active_stress/result_001.vtu	Reference output (Git LFS).
tests/cases/struct/directionally_distributed_active_stress/mesh/mesh-complete.mesh.vtu	Mesh for the test (Git LFS).
tests/cases/struct/directionally_distributed_active_stress/mesh/mesh-surfaces/X0.vtp	Surface mesh (Git LFS).
tests/cases/struct/directionally_distributed_active_stress/mesh/mesh-surfaces/X1.vtp	Surface mesh (Git LFS).
tests/cases/struct/directionally_distributed_active_stress/mesh/mesh-surfaces/Y0.vtp	Surface mesh (Git LFS).
tests/cases/struct/directionally_distributed_active_stress/mesh/mesh-surfaces/Y1.vtp	Surface mesh (Git LFS).
tests/cases/struct/directionally_distributed_active_stress/mesh/mesh-surfaces/Z0.vtp	Surface mesh (Git LFS).
tests/cases/struct/directionally_distributed_active_stress/mesh/mesh-surfaces/Z1.vtp	Surface mesh (Git LFS).
tests/cases/struct/directionally_distributed_active_stress/media/stress.png	Documentation image (Git LFS).
tests/cases/struct/directionally_distributed_active_stress/media/animation.gif	Documentation animation (Git LFS).
tests/cases/struct/directionally_distributed_active_stress/media/animation_fiber_1.gif	Documentation animation (Git LFS).
tests/cases/struct/directionally_distributed_active_stress/media/animation_sheet_1.gif	Documentation animation (Git LFS).
tests/cases/struct/directionally_distributed_active_stress/media/animation_sheet_normal_1.gif	Documentation animation (Git LFS).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

❌ Patch coverage is 72.05882% with 38 lines in your changes missing coverage. Please review.
✅ Project coverage is 67.70%. Comparing base (1b42aaa) to head (55b60d3).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
Code/Source/solver/Parameters.cpp	55.07%	31 Missing ⚠️
Code/Source/solver/mat_models.cpp	88.13%	7 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #497      +/-   ##
==========================================
- Coverage   67.70%   67.70%   -0.01%     
==========================================
  Files         169      168       -1     
  Lines       32653    32752      +99     
  Branches     5727     5750      +23     
==========================================
+ Hits        22109    22176      +67     
- Misses      10407    10439      +32     
  Partials      137      137              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[dseyler]

Maybe not worth it for this implementation, but I think it could be interesting to be able to supply a mesh containing the stress distributions at every point, similar to the variable Robin BCs, so that the directional anisotropy in cDTI data can be incorporated. Could also help smooth out some of the "noisy" cDTI data by having it contract more isotropically where we have less confidence in the longitudinal fiber direction. I've seen some material models do something similar, but I'm not sure about active stress.

[aabrown100-git]

@dseyler That's a good idea. If we do something like that, I think it would be better to create a whole new ActiveStress class. This could contains spatially-variable directional distributions, as you say, and also perhaps spatially-variable activation times, or more generally spatially-variable temporal curves of active stress (#366).

[dseyler]

@aabrown100-git Good idea. I'll check with @kko27 to see if he's made any progress on this

[aabrown100-git]

@ktbolt thanks for the approval. I noticed we now need two approval from reviewers with write access. Was this change intentional?

[ktbolt]

@aabrown100-git I changed the PR approval to need two approvals so PRs could not be pushed through without proper review.

[aabrown100-git]

@divyaadil23 @dseyler Could you review my PR when you get a chance?