Skip to content

Commit bd351ba

Browse files
ktboltktbolt
authored
Merge pull request #32 from menon-karthik/0d
Move svZeroDSolver docs to Simvascular website
2 parents de3bdc4 + 01eec55 commit bd351ba

File tree

13 files changed

+698
-24
lines changed

13 files changed

+698
-24
lines changed

‎documentation/rom_simulation.html‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -184,6 +184,21 @@ <h4 class="skipTo 1d-solver">1D Solver</h4>
184184
</div>
185185
<div>
186186
<h4 class="skipTo 0d-solver">0D Solver</h4>
187+
<div>
188+
<p class="skipTo 0d-solver-theory">Theory</p>
189+
<p class="skipTo 0d-solver-install">Installing svZeroDSolver</p>
190+
<p class="skipTo 0d-solver-user-guide">User Guide</p>
191+
<div style="margin-bottom: -10px;">
192+
<p class="skipTo 0d-solver-user-guide-run">Running svZeroDSolver</p>
193+
<p class="skipTo 0d-solver-user-guide-input">Input File Format</p>
194+
<p class="skipTo 0d-solver-user-guide-output">Simulation Outputs</p>
195+
</div>
196+
<p class="skipTo 0d-solver-calibrator">svZeroDCalibrator</p>
197+
<p class="skipTo 0d-solver-visualization">svZeroDVisualization</p>
198+
<p class="skipTo 0d-solver-gui">svZeroDGUI</p>
199+
<p class="skipTo 0d-solver-developer">Developer Guide</p>
200+
<p class="skipTo 0d-solver-refs">References</p>
201+
</div>
187202
</div>
188203
</section>
189204

@@ -253,6 +268,39 @@ <h4 class="skipTo 0d-solver">0D Solver</h4>
253268
<span id="0d-solver">
254269
<zero-md src="rom_simulation/0d-solver/solver/readme.md" no-shadow></zero-md>
255270
</span>
271+
<span id="0d-solver-theory">
272+
<zero-md src="rom_simulation/0d-solver/theory/readme.md" no-shadow></zero-md>
273+
</span>
274+
<span id="0d-solver-install">
275+
<zero-md src="rom_simulation/0d-solver/install/readme.md" no-shadow></zero-md>
276+
</span>
277+
<span id="0d-solver-user-guide">
278+
<zero-md src="rom_simulation/0d-solver/user-guide/readme.md" no-shadow></zero-md>
279+
</span>
280+
<span id="0d-solver-user-guide-run">
281+
<zero-md src="rom_simulation/0d-solver/user-guide-run/readme.md" no-shadow></zero-md>
282+
</span>
283+
<span id="0d-solver-user-guide-input">
284+
<zero-md src="rom_simulation/0d-solver/user-guide-input/readme.md" no-shadow></zero-md>
285+
</span>
286+
<span id="0d-solver-user-guide-output">
287+
<zero-md src="rom_simulation/0d-solver/user-guide-output/readme.md" no-shadow></zero-md>
288+
</span>
289+
<span id="0d-solver-calibrator">
290+
<zero-md src="rom_simulation/0d-solver/calibrator/readme.md" no-shadow></zero-md>
291+
</span>
292+
<span id="0d-solver-visualization">
293+
<zero-md src="rom_simulation/0d-solver/visualization/readme.md" no-shadow></zero-md>
294+
</span>
295+
<span id="0d-solver-gui">
296+
<zero-md src="rom_simulation/0d-solver/gui/readme.md" no-shadow></zero-md>
297+
</span>
298+
<span id="0d-solver-developer">
299+
<zero-md src="rom_simulation/0d-solver/developer/readme.md" no-shadow></zero-md>
300+
</span>
301+
<span id="0d-solver-refs">
302+
<zero-md src="rom_simulation/0d-solver/refs/readme.md" no-shadow></zero-md>
303+
</span>
256304
</section>
257305
</section>
258306
<section class="skipToTopSection">

‎documentation/rom_simulation/0d-solver/calibrator/readme.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
## svZeroDCalibrator - Quick User Guide
2+
3+
svZeroDCalibrator can be used to calibrate cardiovascular 0D models (i.e. infer optimal
4+
parameters for the 0D elements) based on a given transient result (i.e. from a
5+
3D simulation).
6+
7+
### Run svZeroDCalibrator
8+
9+
#### From the command line
10+
svZeroDCalibrator can be executed from the command line using a JSON configuration
11+
file.
12+
13+
```bash
14+
svzerodcalibrator path/to/input_file.json path/to/output_file.json
15+
```
16+
17+
The result will be written to a JSON file.
18+
19+
20+
#### In Python
21+
22+
svZeroDCalibrator can also be called directly from Python.
23+
Please make sure that you installed svZerodSolver via pip to enable this feature. We start by
24+
importing pysvzerod:
25+
26+
```python
27+
import pysvzerod
28+
29+
my_unoptimized_config = {...}
30+
my_optimized_config = pysvzerod.calibrate(my_unoptimized_config)
31+
```
32+
33+
### Configuration file
34+
35+
In order to make svZeroDCalibrator easy to use, it is based on a similar configuration
36+
file than svZeroDSolver. Instead of the `simulation_parameters` section, it has a section
37+
called `calibration_parameters`. Additionally the optimization target (i.e. a given)
38+
3D result is passed with the key `y` and it's temporal derivative via `dy`. See
39+
`tests/cases/steadyFlow_calibration.json` for an example input file.
40+
41+
```python
42+
{
43+
"calibration_parameters": {...},
44+
"vessels": [...],
45+
"junctions": [...],
46+
"boundary_conditions": [...],
47+
"y": {
48+
"flow:INFLOW:branch0_seg0": [0.0, 0.1, ...], # Time series for DOF
49+
"pressure:INFLOW:branch0_seg0": [0.0, 0.1, ...], # Time series for DOF
50+
...
51+
},
52+
"dy": {
53+
"flow:INFLOW:branch0_seg0": [0.0, 0.1, ...], # Time series for DOF
54+
"pressure:INFLOW:branch0_seg0": [0.0, 0.1, ...], # Time series for DOF
55+
...
56+
},
57+
}
58+
```
59+
60+
#### Calibration parameters
61+
62+
Here is a list of the parameters that can be specified in the `calibration_parameters`
63+
section of the configuration file.
64+
65+
Parameter key &emsp; | Description &emsp; | Default value &emsp;
66+
----------------------------------------- | ---------------------------------------------------------------------- | -----------
67+
`tolerance_gradient` &emsp; | Gradient tolerance for calibration &emsp; | $10^{-5}$ &emsp;
68+
`tolerance_increment` &emsp; | Increment tolerance for calibration &emsp; | $10^{-10}$ &emsp;
69+
`maximum_iterations` &emsp; | Maximum calibration iterations &emsp; | 100 &emsp;
70+
`calibrate_stenosis_coefficient` &emsp; | Toggle whether stenosis coefficient should be calibrated &emsp; | True &emsp;
71+
`set_capacitance_to_zero` &emsp; | Toggle whether all capacitances should be manually set to zero &emsp; | False &emsp;
72+
`initial_damping_factor` &emsp; | Initial damping factor for Levenberg-Marquardt optimization &emsp; | 1.0 &emsp;
73+

‎documentation/rom_simulation/0d-solver/developer/readme.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
## Developer guide
2+
3+
If you are a developer and want to contribute to svZeroDSolver, you can find more helpful information in our [Developer Guide](https://simvascular.github.io/svZeroDSolver/developer_guide.html).

‎documentation/rom_simulation/0d-solver/gui/readme.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
## svZeroDGUI
2+
3+
### About
4+
5+
The svZeroDGUI application is designed to facilitate the creation of 0D model input files
6+
through an intuitive graphical user interface. Located in the `applications` folder,
7+
this tool allows users to generate input files for the svZeroDSolver by visually
8+
drawing and configuring the network.
9+
10+
Unlike manual file creation, which can be
11+
cumbersome and error-prone, svZeroDGUI provides an easy-to-use interface that
12+
simplifies the process of defining network components such as vessels, junctions, and
13+
boundary conditions. This application is especially valuable for users who lack access to
14+
3D models or seek an efficient alternative to manual file generation, making the model creation
15+
process both faster and more user-friendly.
16+
17+
### How to Use
18+
1. Create a virtual environment with the required `flask` dependency. If using `conda`, use the below commands:
19+
```bash
20+
conda create -n svZeroDGUI python=3.10 flask
21+
conda activate svZeroDGUI
22+
```
23+
2. Navigate to the `applications` folder and then to the `create_0dmodel` subdirectory.
24+
3. Launch the `app.py` file.
25+
```bash
26+
python applications/svZeroDGUI/app.py
27+
```
28+
4. Select a node type and name the node.
29+
- For vessels, after drawing the node, click on it to open a form
30+
where you can enter details such as vessel length, diameter, and more.
31+
- For junctions, click the node to specify if it’s a Normal %Junction
32+
or a Blood Vessel %Junction.
33+
5. To draw edges between nodes, toggle the `Draw on` button on the right.
34+
Once active, you can start connecting nodes by drawing edges between them.
35+
6. When you wish to stop drawing edges and continue adding or moving nodes,
36+
click the `Draw off` button.
37+
7. Once you’ve completed the network, click `Export to JSON` on the right.
38+
If there are any incorrect connections or patterns, an alert will prompt you
39+
to make necessary changes so the network can be processed by svZeroDSolver.
40+
8. Open the downloaded JSON file and add any additional information,
41+
such as boundary condition data, before running it through svZeroDSolver.

‎documentation/rom_simulation/0d-solver/install/readme.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
## Installation
2+
3+
There are three ways to install svZeroDSolver:
4+
5+
1. Download an installer from [SimTK Simvascular Downloads](https://simtk.org/frs/?group_id=188).
6+
2. Install using pip. This is the recommended method for using the Python API.
7+
3. Build using CMake. This is the recommended method for using the C++ interface.
8+
9+
Instructions on the pip and CMake installation methods are below.
10+
11+
### Using pip
12+
13+
For a pip installation, simply run the following command
14+
(cloning of the repository is not required):
15+
16+
```bash
17+
pip install git+https://github.com/simvascular/svZeroDSolver.git
18+
```
19+
20+
### Using CMake
21+
22+
If you want to build svZeroDSolver manually from source, clone the repository
23+
and run the following commands from the top directory of the project:
24+
25+
```bash
26+
mkdir Release
27+
cd Release
28+
cmake -DCMAKE_BUILD_TYPE=Release ..
29+
cmake --build .
30+
```
31+
<br/>
32+
<details>
33+
<summary><mark><b>Note: Building on Sherlock for Stanford users</b></mark></summary>
34+
35+
```bash
36+
module load cmake/3.23.1 gcc/14.2.0 binutils/2.38
37+
mkdir Release
38+
cd Release
39+
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER=/share/software/user/open/gcc/14.2.0/bin/g++ -DCMAKE_C_COMPILER=/share/software/user/open/gcc/14.2.0/bin/gcc ..
40+
cmake --build .
41+
```
42+
</details>
43+
<br/>

‎documentation/rom_simulation/0d-solver/refs/readme.md‎

Lines changed: 59 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,67 @@
1-
# References
1+
## References
22

3-
<p><a id="ref-1">
4-
Seo J, Fleeter C, Kahn A, Marsden A, Schiavazzi D. <strong>Multi-fidelity estimators for coronary artery models under clinically-informed data uncertainty</strong>. Int J Uncertain Quantif. 2020.
3+
#### References cited in the documentation above:
4+
5+
<p><a id="0d-Pfaller2021">
6+
Martin R. Pfaller, Jonathan Pham, Nathan M. Wilson, David W. Parker, and Alison L. Marsden. On the periodicity of cardiovascular fluid dynamics simulations. <i>Annals of Biomedical Engineering</i>, 49, 2021.
7+
</a></p>
8+
9+
<p><a id="0d-Menon2023">
10+
Karthik Menon, Jongmin Seo, Ryuji Fukazawa, Shunichi Ogawa, Andrew M Kahn, Jane C Burns, and Alison L Marsden. Predictors of myocardial ischemia in patients with Kawasaki Disease: Insights from patient-specific simulations of coronary hemodynamics. <i>Journal of Cardiovascular Translational Research</i>, 16:1099–1109, 2023.
511
</a></p>
612

7-
<p><a id="ref-2">
8-
K.E. Jansen, C.H. Whiting, G.M. Hulbert, <strong>A generalized-$\alpha$ method for integrating the filtered Navier–Stokes equations with a stabilized finite element method</strong>, Comp. Methods Appl. Mech. Engrg. 190 (1999) 305–319.
13+
<p><a id="0d-Jansen2000">
14+
Kenneth E. Jansen, Christian H. Whiting, and Gregory M. Hulbert. A generalized-alpha method for integrating the filtered navier–stokes equations with a stabilized finite element method. <i>Computer Methods in Applied Mechanics and Engineering</i>, 190(3):305–319, 2000.
915
</a></p>
1016

11-
<p><a id="ref-3">
12-
Mehran Mirramezani and Shawn C. Shadden. <strong>A distributed lumped parameter model of blood flow. Annals
13-
of Biomedical Engineering</strong>, 2020.
17+
<p><a id="0d-Bazilevs2013">
18+
Yuri Bazilevs, Kenji Takizawa, and Tayfun E. Tezduyar. <i>Computational Fluid-Structure Interaction.</i> John Wiley & Sons, 2013.
19+
</a></p>
20+
21+
#### References relevant to some of the blocks in svZeroDSolver:
22+
23+
**Cardiac chamber:**
24+
25+
<p><a id="0d-Kerckhoffs2007">
26+
Roy CP Kerckhoffs, Maxwell L Neal, Quan Gu, James B Bassingthwaighte, Jeff H Omens, and Andrew D McCulloch. Coupling of a 3d finite element model of cardiac ventricular mechanics to lumped systems models of the systemic and pulmonic circulation. <i>Annals of Biomedical Engineering</i>, 35:1–18, 2007
27+
</a></p>
28+
29+
**Coronary boundary condition:**
30+
31+
<p><a id="0d-Kim2010">
32+
H Kim, Irene Vignon-Clementel, Jessica Coogan, Carlos Figueroa, Kenneth Jansen, and CA Taylor. Patient-specific modeling of blood flow and pressure in human coronary arteries. <i>Annals of Biomedical Engineering</i>, 38:3195–209, 10 2010.
33+
</a></p>
34+
35+
**RCR boundary condition:**
36+
37+
<p><a id="0d-Vignon2004">
38+
Irene E. Vignon and Charles A. Taylor. Outflow boundary conditions for one-dimensional finite element modeling of blood flow and pressure waves in arteries. <i>Wave Motion</i>, 39(4):361–374, 2004.
39+
</a></p>
40+
41+
**Heart valve:**
42+
43+
<p><a id="0d-Pfaller2019">
44+
Martin R Pfaller, Julia M Hörmann, Martina Weigl, Andreas Nagler, Radomir Chabiniok, Cristóbal Bertoglio, and Wolfgang A Wall. The importance of the pericardium for cardiac biomechanics: from physiology to computational modeling. <i>Biomechanics and Modeling in Mechanobiology</i>, 18:503–529, 2019.
45+
</a></p>
46+
47+
#### Some papers using svZeroDSolver:
48+
49+
**Generating 0D models from 3D models:**
50+
51+
<p><a id="0d-Pfaller2022">
52+
Martin R. Pfaller, Jonathan Pham, Aekaansh Verma, Luca Pegolotti, Nathan M. Wilson, David W. Parker, Weiguang Yang, and Alison L. Marsden. Automated generation of 0D and 1D reduced-order models of patient-specific blood flow. <i>International Journal for Numerical Methods in Biomedical Engineering</i>, 38(10), aug 2022.
53+
</a></p>
54+
55+
**Coupled 3D-0D modeling:**
56+
57+
Karthik Menon, Muhammed Owais Khan, Zachary A. Sexton, Jakob Richter, Patricia K. Nguyen, Sachin B. Malik, Jack Boyd, Koen Nieman and Alison L. Marsden. Personalized coronary and myocardial blood flow models incorporating CT perfusion imaging and synthetic vascular trees. <i>npj Imaging</i>, 2(9), 2004.
58+
59+
**Parameter estimation and uncertainty quantification:**
60+
61+
<p><a id="0d-Richter2024">
62+
Jakob Richter, Jonas Nitzler, Luca Pegolotti, Karthik Menon, Jonas Biehler, Wolfgang A. Wall, Daniele E. Schiavazzi, Alison L. Marsden, Martin R. Pfaller. Bayesian Windkessel calibration using optimized 0D surrogate models. <i>Philosophical Transactions of the Royal Society A</i>, 2024.
1463
</a></p>
1564

16-
<p><a id="ref-4">
17-
H.J. Kim, I.E. Vignon-Clementel, J.S. Coogan, C.A. Figueroa, K.E. Jansen and C.A. Taylor, <strong>Patient-specific modeling of blood flow and pressure in human coronary arteries</strong>, Annals of Biomedical Engineering, 38(10):3195-3209, 2010.
65+
<p><a id="0d-Menon2024">
66+
Karthik Menon, Andrea Zanoni, Owais Khan, Gianluca Geraci, Koen Nieman, Daniele E. Schiavazzi, Alison L. Marsden. Personalized and uncertainty-aware coronary hemodynamics simulations: From bayesian estimation to improved multi-fidelity uncertainty quantification, <i>arXiv</i> 2409:02247, 2024.
1867
</a></p>

0 commit comments

Comments
 (0)