-
-
Notifications
You must be signed in to change notification settings - Fork 112
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add muscle tutorial #471
base: develop
Are you sure you want to change the base?
Add muscle tutorial #471
Changes from 41 commits
822cb19
cc8b43c
feef2d0
cfbe718
3eb5bb0
b559c85
1b4f1fe
0cb1947
bcbc6fd
ff5ed78
a80cfaa
b383782
0bdcb05
c6091ae
1d31091
f555039
6bfa0a9
5459862
c3b4db8
b24c63d
50333ef
0a5858a
e3bd5e2
83f7597
dcd7a3f
f9325f3
bbfa73e
9660161
13ccd83
d9141f5
9ec1cdb
b3602f0
e908415
b7e9272
2e6dc39
09d53d6
37233da
76b5a0f
db6820e
535342f
75c09ff
755c3e4
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,12 @@ | ||
**/__pycache__ | ||
**/lib | ||
**/logs | ||
**/out | ||
**/*.log | ||
**/*.txt | ||
**/precice-profiling | ||
**/build_release | ||
**/muscle-solver | ||
**/tendon-solver | ||
**/.sconf_temp | ||
**/.scons* |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,125 @@ | ||
--- | ||
title: Muscle-tendon complex | ||
permalink: tutorials-muscle-tendon-complex.html | ||
keywords: multi-coupling, OpenDiHu, skeletal muscle | ||
summary: In this case, a skeletal muscle (biceps) and three tendons are coupled together using a fully-implicit multi-coupling scheme. | ||
--- | ||
|
||
{% note %} | ||
Get the [case files of this tutorial](https://github.com/precice/tutorials/tree/master/muscle-tendon-complex). Read how in the [tutorials introduction](https://www.precice.org/tutorials.html). | ||
{% endnote %} | ||
|
||
## Case Setup | ||
|
||
In the following tutorial, we model the contraction of a muscle (the biceps). The biceps is attached to the bones by three tendons (one at the bottom and two at the top). We enforce an activation in the muscle which results in its contraction. The tendons move as a result of the muscle contraction. In this case, a muscle and three tendons are coupled together using a fully-implicit multi-coupling scheme. The case setup is shown in the following figure: | ||
|
||
![Setup](images/tutorials-muscle-tendon-complex-setup.png) | ||
|
||
The muscle participant (in red) is connected to three tendons. The muscle sends traction values to the tendons, which send displacement and velocity values back to the muscle. The end of each tendon which is not attached to the muscle is fixed by a dirichlet boundary condition (in reality, it would be fixed to the bones). | ||
|
||
The muscle and tendon meshes are obtained from patient imaging. The interfaces of the tendons and the muscle do not perfectly match, which is a quite common issue due to the limitations of imaging methods and postprocessing tools. Nonetheless, preCICE coupling methods are robust and can handle meshes that do not perfectly match. | ||
|
||
## Why multi-coupling? | ||
|
||
This is a case with four participants: the muscle and each tendon. In preCICE, there are two options to [couple more than two participants](https://www.precice.org/configuration-coupling-multi.html). The first option is a composition of bi-coupling schemes, in which we must specify the exchange of data in a participant-to-participant manner, limited to primarily explicit coupling schemes. However, such a composition is not suited for combining multiple strong interactions [1]. Thus, in this case, we use the second option, fully-implicit multi-coupling. For another multi-coupling tutorial, you can refer to the [multiple perpendicular flaps tutorial](http://precice.org/tutorials-multiple-perpendicular-flaps.html). | ||
|
||
We can set this in our `precice-config.xml`: | ||
|
||
```xml | ||
<coupling-scheme:multi> | ||
<participant name="Muscle" control="yes"/> | ||
<participant name="Tendon-Bottom"/> | ||
<participant name="Tendon-Top-A"/> | ||
<participant name="Tendon-Top-B"/> | ||
``` | ||
|
||
The participant that has the control is the one that it is connected to all other participants. This is why we have chosen the muscle participant for this task. | ||
|
||
## About the solvers | ||
|
||
We use solvers based on [OpenDiHu](https://github.com/opendihu/opendihu) for all participants. | ||
|
||
**The muscle solver** consists of a multi-physcis multi-scale solver itself. It combines two OpenDiHu solvers in one: the *FastMonodomainSolver* and the *MuscleContractionSolver*. The two solvers are coupled using the OpenDiHu coupling tool for weak coupling. | ||
|
||
- The [FastMonodomainSolver](https://opendihu.readthedocs.io/en/latest/settings/fast_monodomain_solver.html) models the electrochemical processes that take place in the muscle fibers. Motor neurons fire electrical signals that propagate from the neuromuscular junctions. i.e. the center of the muscle fibers, to the extremes of the muscle fibers. The propagation of the electrical signal triggers chemical reactions which lead to the contraction of sarcomeres, the smallest contraction unit in the muscle. | ||
The solver solves the so called "monodomain equation" independently for each fiber [2]. The modonomain equation has a reaction term (small time scale) and a diffusion term (large time scale) and is solved using Strang splitting. The sarcomeres, i.e., the reaction term, are modelled using a variant of the Shorten model, specified by the CellML file `opendihu/examples/electrophysiology/input/2020_06_03_hodgkin-huxley_shorten_ocallaghan_davidson_soboleva_2007.cellml`. The firing of the motor neurons is modelled by the `opendihu/examples/electrophysiology/input/MU_firing_times_always.txt` file. | ||
|
||
- The [MuscleContractionSolver](https://opendihu.readthedocs.io/en/latest/settings/muscle_contraction_solver.html) models the mechanics of the muscle. It consists of a dynamic FEM solver that models an hyperelastic active material. The active component is calculated from the activation parameter $\gamma$, which ranges from 0 (no activation) to 1 (maximum activation) and is calculated in the *FastMonodomainSolver*. The material parameters are chosen as in [Heidlauf et al.](https://link.springer.com/article/10.1007/s10237-016-0772-7) | ||
|
||
**The tendon solver** is a dynamic FEM mechanical solver. It models an hyperelastic passive material. The material parameters are chosen as in [Carniel et al.](https://pubmed.ncbi.nlm.nih.gov/28238424/) | ||
|
||
## Running the Simulation | ||
|
||
1. Preparation: | ||
- Install OpenDiHu | ||
|
||
In the OpenDiHu website you can find detailed [installation instructions](https://opendihu.readthedocs.io/en/latest/user/installation.html). | ||
We recommend to download the code from the [GitHub repository](https://github.com/opendihu/opendihu) and to run `make release_without_tests` in the parent directory. | ||
|
||
{% note %} | ||
OpenDiHu automatically downloads dependencies and installs them in the `opendihu/dependencies/` folder. You can avoid that by setting e.g., `PRECICE_DOWNLOAD = False` in the [user-variables.scons.py](https://github.com/opendihu/opendihu/blob/develop/user-variables.scons.py) before building OpenDiHu. | ||
{% endnote %} | ||
|
||
- Download input files for OpenDiHu | ||
|
||
OpenDiHu requires input files hosted in [Zenodo](https://zenodo.org/records/4705982) which include CellML files (containing model equations) and mesh files. Downloading these files is necessary to simulate muscles and/or tendons with OpenDiHu. You can [directly download the necessary files](https://zenodo.org/record/4705982/files/input.tgz?download=1). | ||
|
||
- Setup `$OPENDIHU_HOME` and `$OPENDIHU_INPUT_DIR` in your `.bashrc` file | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Just a general terminology thing: When I see "input files", I understand configuration files for a specific simulation. How do these differ that the files included in this repository? If they are specific to this tutorial, they could also be downloaded directly into this directory (and specified in the There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. What in opendihu we call input file are not what I understand as configuration files. They are files that specify meshes, i.e., geometry, and cellml models, i.e., equations. In the configuration files (the ones included in the tutorial, we give the parameters and user settings to use this files. |
||
|
||
```bash | ||
export OPENDIHU_HOME=/path/to/opendihu | ||
export OPENDIHU_INPUT_DIR=/path/to/input | ||
``` | ||
|
||
- Compile muscle and tendon solvers | ||
|
||
```bash | ||
cd solver-opendihu | ||
./build.sh | ||
``` | ||
|
||
2. Starting the simulation: | ||
|
||
We are going to run each solver in a different terminal. It is important that first we navigate to the respective case directory, so that all solvers start from directories with same parent directory (see `exchange-directory` in the `precice-config.xml`). | ||
To start the `Muscle` participant, run: | ||
|
||
```bash | ||
cd muscle-opendihu | ||
./run.sh | ||
``` | ||
|
||
To start the `Tendon-Bottom` participant, run: | ||
|
||
```bash | ||
cd tendon-bottom-opendihu | ||
./run.sh | ||
``` | ||
|
||
To start the `Tendon-Top-A` participant, run: | ||
|
||
```bash | ||
cd tendon-top-A-opendihu | ||
./run.sh | ||
``` | ||
|
||
Finally, to start the `Tendon-Top-B` participant, run: | ||
|
||
```bash | ||
cd tendon-top-B-opendihu | ||
./run.sh | ||
``` | ||
|
||
## Postprocessing... TODO | ||
|
||
After the simulation has finished, you can visualize your results using e.g. ParaView. | ||
|
||
## References TODO | ||
|
||
<!-- markdownlint-configure-file {"MD034": false } --> | ||
[1] H. Bungartz, F. Linder, M. Mehl, B. Uekermann. A plug-and-play coupling approach for parallel multi-field simulations. *Comput Mech* **55**, 1119-1129 (2015). https://doi.org/10.1007/s00466-014-1113-2 | ||
|
||
[2] T. Heidlauf, O. Röhrle. A multiscale chemo-electro-mechanical skeletal muscle model to analyze muscle contraction and force generation for different muscle fiber arrangements. *Front. Physiology* **5** (2014). https://doi.org/10.3389/fphys.2014.00498 | ||
|
||
{% disclaimer %} | ||
This offering is not approved or endorsed by OpenCFD Limited, producer and distributor of the OpenFOAM software via www.openfoam.com, and owner of the OPENFOAM® and OpenCFD® trade marks. | ||
{% enddisclaimer %} |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
../tools/clean-tutorial-base.sh |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,6 @@ | ||
#!/bin/sh | ||
set -e -u | ||
|
||
. ../../tools/cleaning-tools.sh | ||
|
||
clean_opendihu . |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
See #477 and restrict this to the difference (let's better wait until it is merged).
Are all of these files generated with the default instructions, or are some rules only as "just in case"?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sorry I don't understand. Which default instructions are you referring to?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sorry, I meant "are all these rules to ignore files that will actually be generated when I try to run the tutorial?".
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yes! Some when building and some when running