Merge pull request #32 from menon-karthik/0d

Move svZeroDSolver docs to Simvascular website

documentation/rom_simulation.html

@@ -184,6 +184,21 @@ <h4 class="skipTo 1d-solver">1D Solver</h4>
       </div>
       <div>
         <h4 class="skipTo 0d-solver">0D Solver</h4>
+        <div>
+          <p class="skipTo 0d-solver-theory">Theory</p>
+          <p class="skipTo 0d-solver-install">Installing svZeroDSolver</p>
+          <p class="skipTo 0d-solver-user-guide">User Guide</p>
+          <div style="margin-bottom: -10px;">
+            <p class="skipTo 0d-solver-user-guide-run">Running svZeroDSolver</p>
+            <p class="skipTo 0d-solver-user-guide-input">Input File Format</p>
+            <p class="skipTo 0d-solver-user-guide-output">Simulation Outputs</p>
+          </div>
+          <p class="skipTo 0d-solver-calibrator">svZeroDCalibrator</p>
+          <p class="skipTo 0d-solver-visualization">svZeroDVisualization</p>
+          <p class="skipTo 0d-solver-gui">svZeroDGUI</p>
+          <p class="skipTo 0d-solver-developer">Developer Guide</p>
+          <p class="skipTo 0d-solver-refs">References</p>
+        </div>
       </div>
     </section>
 
@@ -253,6 +268,39 @@ <h4 class="skipTo 0d-solver">0D Solver</h4>
       <span id="0d-solver">
         <zero-md src="rom_simulation/0d-solver/solver/readme.md" no-shadow></zero-md>
       </span>
+      <span id="0d-solver-theory">
+        <zero-md src="rom_simulation/0d-solver/theory/readme.md" no-shadow></zero-md>
+      </span>
+      <span id="0d-solver-install">
+        <zero-md src="rom_simulation/0d-solver/install/readme.md" no-shadow></zero-md>
+      </span>
+      <span id="0d-solver-user-guide">
+        <zero-md src="rom_simulation/0d-solver/user-guide/readme.md" no-shadow></zero-md>
+      </span>
+      <span id="0d-solver-user-guide-run">
+        <zero-md src="rom_simulation/0d-solver/user-guide-run/readme.md" no-shadow></zero-md>
+      </span>
+      <span id="0d-solver-user-guide-input">
+        <zero-md src="rom_simulation/0d-solver/user-guide-input/readme.md" no-shadow></zero-md>
+      </span>
+      <span id="0d-solver-user-guide-output">
+        <zero-md src="rom_simulation/0d-solver/user-guide-output/readme.md" no-shadow></zero-md>
+      </span>
+      <span id="0d-solver-calibrator">
+        <zero-md src="rom_simulation/0d-solver/calibrator/readme.md" no-shadow></zero-md>
+      </span>
+      <span id="0d-solver-visualization">
+        <zero-md src="rom_simulation/0d-solver/visualization/readme.md" no-shadow></zero-md>
+      </span>
+      <span id="0d-solver-gui">
+        <zero-md src="rom_simulation/0d-solver/gui/readme.md" no-shadow></zero-md>
+      </span>
+      <span id="0d-solver-developer">
+        <zero-md src="rom_simulation/0d-solver/developer/readme.md" no-shadow></zero-md>
+      </span>
+      <span id="0d-solver-refs">
+        <zero-md src="rom_simulation/0d-solver/refs/readme.md" no-shadow></zero-md>
+      </span>
     </section>
   </section>
   <section class="skipToTopSection">

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

@@ -0,0 +1,73 @@
+## svZeroDCalibrator - Quick User Guide
+
+svZeroDCalibrator can be used to calibrate cardiovascular 0D models (i.e. infer optimal
+parameters for the 0D elements) based on a given transient result (i.e. from a
+3D simulation).
+
+### Run svZeroDCalibrator
+
+#### From the command line
+svZeroDCalibrator can be executed from the command line using a JSON configuration
+file.
+
+```bash
+svzerodcalibrator path/to/input_file.json path/to/output_file.json
+```
+
+The result will be written to a JSON file.
+
+
+#### In Python
+
+svZeroDCalibrator can also be called directly from Python.
+Please make sure that you installed svZerodSolver via pip to enable this feature. We start by
+importing pysvzerod:
+
+```python
+import pysvzerod
+
+my_unoptimized_config = {...}
+my_optimized_config = pysvzerod.calibrate(my_unoptimized_config)
+```
+
+### Configuration file
+
+In order to make svZeroDCalibrator easy to use, it is based on a similar configuration
+file than svZeroDSolver. Instead of the `simulation_parameters` section, it has a section
+called `calibration_parameters`. Additionally the optimization target (i.e. a given)
+3D result is passed with the key `y` and it's temporal derivative via `dy`. See
+`tests/cases/steadyFlow_calibration.json` for an example input file.
+
+```python
+{
+    "calibration_parameters": {...},
+    "vessels": [...],
+    "junctions": [...],
+    "boundary_conditions": [...],
+    "y": {
+      "flow:INFLOW:branch0_seg0": [0.0, 0.1, ...],  # Time series for DOF
+      "pressure:INFLOW:branch0_seg0": [0.0, 0.1, ...],  # Time series for DOF
+      ...
+    },
+    "dy": {
+      "flow:INFLOW:branch0_seg0": [0.0, 0.1, ...],  # Time series for DOF
+      "pressure:INFLOW:branch0_seg0": [0.0, 0.1, ...],  # Time series for DOF
+      ...
+    },
+}
+```
+
+#### Calibration parameters
+
+Here is a list of the parameters that can be specified in the `calibration_parameters`
+section of the configuration file.
+
+Parameter key                        | Description                                                       | Default value  
+----------------------------------------- | ---------------------------------------------------------------------- | -----------
+`tolerance_gradient`                 | Gradient tolerance for calibration                                | $10^{-5}$  
+`tolerance_increment`                | Increment tolerance for calibration                               | $10^{-10}$  
+`maximum_iterations`                 | Maximum calibration iterations                                    | 100  
+`calibrate_stenosis_coefficient`     | Toggle whether stenosis coefficient should be calibrated          | True  
+`set_capacitance_to_zero`            | Toggle whether all capacitances should be manually set to zero    | False  
+`initial_damping_factor`             | Initial damping factor for Levenberg-Marquardt optimization       | 1.0  
+

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

@@ -0,0 +1,3 @@
+## Developer guide
+
+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

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

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

@@ -0,0 +1,43 @@
+## Installation
+
+There are three ways to install svZeroDSolver:
+
+1. Download an installer from [SimTK Simvascular Downloads](https://simtk.org/frs/?group_id=188). 
+2. Install using pip. This is the recommended method for using the Python API.
+3. Build using CMake. This is the recommended method for using the C++ interface. 
+
+Instructions on the pip and CMake installation methods are below.
+
+### Using pip
+
+For a pip installation, simply run the following command
+(cloning of the repository is not required):
+
+```bash
+pip install git+https://github.com/simvascular/svZeroDSolver.git
+```
+
+### Using CMake
+
+If you want to build svZeroDSolver manually from source, clone the repository
+and run the following commands from the top directory of the project:
+
+```bash
+mkdir Release
+cd Release
+cmake -DCMAKE_BUILD_TYPE=Release ..
+cmake --build .
+```
+<br/>
+<details>
+  <summary><mark><b>Note: Building on Sherlock for Stanford users</b></mark></summary>
+
+```bash
+module load cmake/3.23.1 gcc/14.2.0 binutils/2.38
+mkdir Release
+cd Release
+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 ..
+cmake --build .
+```
+</details>
+<br/>

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

@@ -1,18 +1,67 @@
-# References
+## References
 
-<p><a id="ref-1">
-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.
+#### References cited in the documentation above:
+
+<p><a id="0d-Pfaller2021">
+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.
+</a></p>
+
+<p><a id="0d-Menon2023">
+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.
 </a></p>
 
-<p><a id="ref-2">
-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.
+<p><a id="0d-Jansen2000">
+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.
 </a></p>
 
-<p><a id="ref-3">
-Mehran Mirramezani and Shawn C. Shadden. <strong>A distributed lumped parameter model of blood flow. Annals
-of Biomedical Engineering</strong>, 2020.
+<p><a id="0d-Bazilevs2013">
+Yuri Bazilevs, Kenji Takizawa, and Tayfun E. Tezduyar. <i>Computational Fluid-Structure Interaction.</i> John Wiley & Sons, 2013.
+</a></p>
+
+#### References relevant to some of the blocks in svZeroDSolver:
+
+**Cardiac chamber:** 
+
+<p><a id="0d-Kerckhoffs2007">
+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
+</a></p>
+
+**Coronary boundary condition:**
+
+<p><a id="0d-Kim2010">
+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.
+</a></p>
+
+**RCR boundary condition:**
+
+<p><a id="0d-Vignon2004">
+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.
+</a></p>
+
+**Heart valve:**
+
+<p><a id="0d-Pfaller2019">
+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.
+</a></p>
+
+#### Some papers using svZeroDSolver:
+
+**Generating 0D  models from 3D models:**
+
+<p><a id="0d-Pfaller2022">
+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.
+</a></p>
+
+**Coupled 3D-0D modeling:**
+
+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.
+
+**Parameter estimation and uncertainty quantification:**
+
+<p><a id="0d-Richter2024">
+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.
 </a></p>
 
-<p><a id="ref-4">
-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.
+<p><a id="0d-Menon2024">
+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.
 </a></p>