diff --git a/Class.png b/Class.png new file mode 100644 index 00000000..7350e61d Binary files /dev/null and b/Class.png differ diff --git a/Code/Source/svFSI/BF.f b/Code/Source/svFSI/BF.f index 7268b8df..fcce3524 100755 --- a/Code/Source/svFSI/BF.f +++ b/Code/Source/svFSI/BF.f @@ -138,7 +138,7 @@ SUBROUTINE SETBFL(lBf, lM, Dg) RETURN END SUBROUTINE SETBFL !#################################################################### -! This subroutine is reached only for shell follower pressre loads +! This subroutine is reached only for shell follower pressure loads ! or applying initialization pressure for CMM method. nsd must be ! equal to 3 SUBROUTINE BFCONSTRUCT(lM, e, eNoN, idof, xl, dl, bfl, ptr) diff --git a/Code/Source/svFSI/CHNL.f b/Code/Source/svFSI/CHNL.f index bea21cdb..3a636523 100755 --- a/Code/Source/svFSI/CHNL.f +++ b/Code/Source/svFSI/CHNL.f @@ -230,7 +230,6 @@ SUBROUTINE CHNLOUTPUT(chnl,isTmp) IF (chnl%oTF) THEN INQUIRE(UNIT=chnl%fId, OPENED=flag) IF (.NOT.flag) THEN - IF (appPath .NE. "") CALL SYSTEM("mkdir -p "//TRIM(appPath)) fName = TRIM(appPath)//TRIM(chnl%fName) INQUIRE(FILE=fName, OPENED=flag) IF (.NOT.flag) THEN diff --git a/Code/Source/svFSI/READFILES.f b/Code/Source/svFSI/READFILES.f index b84b8a44..66ab7909 100755 --- a/Code/Source/svFSI/READFILES.f +++ b/Code/Source/svFSI/READFILES.f @@ -122,6 +122,7 @@ SUBROUTINE READFILES saveName = "" appPath = STR(cm%np())//"-procs"//delimiter END IF + IF (appPath .NE. "") CALL SYSTEM("mkdir -p "//TRIM(appPath)) lPtr => list%get(std%oTS,"Verbose") lPtr => list%get(wrn%oTS,"Warning") diff --git a/Docker/Dockerfile b/Docker/Dockerfile new file mode 100644 index 00000000..fd70a314 --- /dev/null +++ b/Docker/Dockerfile @@ -0,0 +1,31 @@ +FROM ubuntu:18.04 + +ENV DEBIAN_FRONTEND=noninteractive + +# Install supporting packages +RUN apt-get update +RUN apt-get install -yq --no-install-recommends apt-utils +RUN apt-get install -yq git make cmake +RUN apt-get install -yq libblas-dev liblapack-dev +RUN apt-get install -yq gcc g++ gfortran +RUN apt-get install -yq openmpi-bin libopenmpi-dev + +# Create directory +RUN mkdir -p /home/test + +# Add non-root user and set up home directory +RUN useradd testuser -u 1000 -g 100 -m -s /bin/bash +RUN chown testuser /home/test +USER testuser +WORKDIR /home/test + +# Obtain source code +RUN git clone https://github.com/SimVascular/svFSI + +# Compile svFSI source code +RUN mkdir Build && \ + cd Build && \ + cmake ../svFSI && \ + make + +ENV PATH=$PATH:/home/test/Build/svFSI-build/bin diff --git a/Docker/README.md b/Docker/README.md new file mode 100644 index 00000000..d8188534 --- /dev/null +++ b/Docker/README.md @@ -0,0 +1,46 @@ +# Docker-svFSI +This Dockerfile will build [`svFSI`](https://github.com/SimVascular/svFSI) executable from the most recent source code in the main repository. This procedure has been successfully tested on MacOS Big Sur, Ubuntu 18.04 and Windows 10 with WSL 2. Assuming you already have [Docker](https://docs.docker.com/get-docker/) installed, please follow the steps below to run `svFSI`. + +1. Build Docker image. In the current directory (Path_to_svFSI/Docker), run the following command. + + ```bash + docker build -t svfsi-image . + ``` + + This may take a while. Afterwards, run the command `docker images`, and you should see `svfsi-image`. + +3. Download the examples. + + ```bash + git clone https://github.com/SimVascular/svFSI-Tests + ``` + +4. Run the container in interactive mode. + + ```bash + docker container run --cap-add=SYS_PTRACE -v "$PWD"/svFSI-Tests:/home/test/svFSI-Tests -it --rm --name svfsi-demo svfsi-image + ``` + + This will open a shell prompt and you can proceed as usual. Here, `--cap-add=SYS_PTRACE` fixes a known [issue](https://github.com/open-mpi/ompi/issues/4948) of running openmpi in Docker. + +5. Let's take `04-fluid/06-channel-flow-2D` for example. In the shell prompt, run the following commands to generate the simulation results. + + ```bash + cd svFSI-Tests/04-fluid/06-channel-flow-2D && \ + mpiexec -n 4 svFSI ./svFSI_Taylor-Hood.inp + ``` + + The results will be stored in `4-procs` in vtu format, and can be viewed with [Paraview](https://www.paraview.org). + +6. After all tests are done, execute the following commands to exit the docker and delete the image. + + ```bash + exit && \ + docker rmi + ``` + + + +### Known Issues + +`svFSI` built with this Dockerfile won't work with any example that requires Trilinos. Trilinos takes too long to build within the Docker image, and we encourage any user that needs it to build `svFSI` from source. Please report any other issue through the GitHub page. \ No newline at end of file diff --git a/INSTALL.md b/INSTALL.md index 0de58b63..2d362771 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,7 +1,7 @@ # **Build svFSI from Source** -Below are the instructions to build svFSI on Ubuntu and MacOS. +If you are interested in testing the new features in the most recent commit, we recommend you to build and run `svFSI` in [Docker container](./Docker/README.md). Otherwise, please follow the instructions below to build `svFSI` on Ubuntu and MacOS.
diff --git a/Copyright-SimVascular.txt b/License.txt similarity index 100% rename from Copyright-SimVascular.txt rename to License.txt diff --git a/Mesh.png b/Mesh.png new file mode 100644 index 00000000..e64d9f91 Binary files /dev/null and b/Mesh.png differ diff --git a/README.md b/README.md index 6c5bc5ca..cf309994 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,17 @@ +## NOTE + +This branch is created from master on Jan 4, 2022 and will be referenced in the manuscript to be submitted for the Journal of Open Source Software (JOSS). + ## Introduction -`svFSI` is a multi-physics finite element solver designed for computational modeling of the cardiovascular system. Some of the unique capabilities of `svFSI` include modeling cardiac electrophysiology, biological tissue mechanics, blood flow, and large deformation fluid-structure interaction (FSI). `svFSI` also offers a wide choice of boundary conditions for performing patient-specific modeling of cardiovascular biomechanics. The code is parallelized using message-passing-interface (MPI) and offers multiple options to choose a linear solver and preconditioner. `svFSI` can be used as part of the [SimVascular](https://simvascular.github.io) software or can be used as a stand-alone solver. +`svFSI` is a multi-physics finite element solver designed for computational modeling of the cardiovascular system. It is a major component of the ongoing SimVascular [**SimCardio**](http://simvascular.github.io/docsSimCardio.html) project that aims to provide the complete pipeline for cardiac modeling, from image segmentation to computational modeling. + +Some of the unique capabilities of `svFSI` include modeling cardiac electrophysiology, biological tissue mechanics, blood flow, and large deformation fluid-structure interaction (FSI). `svFSI` also offers a wide choice of boundary conditions for performing patient-specific modeling of cardiovascular biomechanics. The code is parallelized using message-passing-interface (MPI) and offers multiple options to choose a linear solver and preconditioner. `svFSI` can be used as part of the [SimVascular](https://simvascular.github.io) software or can be used as a stand-alone solver. It is distributed under a MIT-like open source license. + +## Binary and Container +Precompiled binaries for Ubuntu and MacOS are available for download from [SimTK](https://simtk.org/frs/index.php?group_id=188). + +Instructions to build and run `svFSI` in Docker container are provided [here](./Docker/README.md). ## Dependence @@ -15,9 +26,7 @@ The following packages are required to build and use `svFSI`. On Ubuntu, most of the dependencies can be installed using `apt install`. On macOS, the dependencies may be installed using `brew`. Apart from GNU compilers, `svFSI` can also be built with Intel oneAPI Toolkits. For more details, please refer to [`INSTALL.md`](./INSTALL.md#Build) and [`INSTALL-DEPS.md`](./INSTALL-DEPS.md#intel-oneapi-toolkitsd). -## Quick Build - -Precompiled binaries for Ubuntu and MacOS are available for download from [SimTK](https://simtk.org/frs/index.php?group_id=188). +## Quick Build from Source Users are recommended to build from the source code to access the most recent features and bug fixes. Instructions for a quick build are provided here for a Linux/Mac OS system. @@ -34,7 +43,7 @@ Users are recommended to build from the source code to access the most recent fe ```bash make ``` - A successful build will generate a solver binary, called `svFSI` in the following directory `build/svFSI-build/bin`. + A successful build will generate a solver binary called `svFSI` in the following directory `build/svFSI-build/bin`. For more advanced users, please refer [`INSTALL.md`](./INSTALL.md) for detailed platform-specific instructions to install `svFSI`. @@ -52,11 +61,11 @@ option(SV_USE_TRILINOS "Use Trilinos Library with svFSI" ON) In most cases, users can proceed to build `svFSI` following the [Quick Build](#quick-build), and CMake should be able to locate Trilinos automatically through `find_package`. In case the automatic way fails, users can also specify the path to Trilinos through `ccmake -DCMAKE_PREFIX_PATH:PATH="/lib/cmake/Trilinos;;"`. -For more detailed instructions, please refer INSTALL.md. +For more detailed instructions, please refer to [`INSTALL.md`](./INSTALL.md). ## Run Simulation -`svFSI` requires a plain-text input file to specify simulation parameters. The syntax of the input file can be found [here](https://sites.google.com/site/memt63/tools/MUPFES/mupfes-scripting). +`svFSI` requires a plain-text input file to specify simulation parameters. The syntax of the input file can be found [here](http://simvascular.github.io/docssvFSI.html#input). A master template is provided in the current repository, [svFSI_master.inp](./svFSI_master.inp). Users are also recommended to go through the input files in the [examples](https://github.com/SimVascular/svFSI-Tests) and modify them for their needs. @@ -66,7 +75,15 @@ mpiexec -np /svFSI-build/bin/svFSI [dye transportation](https://github.com/SimVascular/svFSI-Tests/tree/master/04-fluid/02-dye_AD);
[GenBC/cplBC](https://github.com/SimVascular/svFSI-Tests/tree/master/04-fluid/04-3D0D-coupling-BC);
[Non-Newtonian flow](https://github.com/SimVascular/svFSI-Tests/tree/master/04-fluid/05-nonNewtonian) | + | Structure | [Webpage](http://simvascular.github.io/docssvFSI-Structure.html); [YouTube](https://www.youtube.com/watch?v=Jm3VSi6Aci8&list=PL1CBZ8Wh-xvRnux0eMmbZPbx-C078Qzqu&index=2) | struct:
[block compression](https://github.com/SimVascular/svFSI-Tests/tree/master/05-struct/01-block-compression);
[passive inflation of LV model](https://github.com/SimVascular/svFSI-Tests/tree/master/05-struct/02-LV-Guccione-passive)
ustruct:
[block compression](https://github.com/SimVascular/svFSI-Tests/tree/master/06-ustruct/01-block-compression);
[tension of arterial strip](https://github.com/SimVascular/svFSI-Tests/tree/master/06-ustruct/02-tensile-adventitia_HGO);
[active inflation of LV model](https://github.com/SimVascular/svFSI-Tests/tree/master/06-ustruct/03-LV-Guccione-active) | + | Electrophysiology | [Webpage](http://simvascular.github.io/docssvFSI-CEP.html); [YouTube](https://www.youtube.com/watch?v=TCK3SmGwBa8&list=PL1CBZ8Wh-xvRnux0eMmbZPbx-C078Qzqu&index=2) | [Aliev-Panfilov model](https://github.com/SimVascular/svFSI-Tests/tree/master/08-cep/01-2Dsqr_AP);
[ten-Tusscher-Panfilov model](https://github.com/SimVascular/svFSI-Tests/tree/master/08-cep/03-benchmark_tTP);
[Bueno-Orovio-Cherry-Fenton model](https://github.com/SimVascular/svFSI-Tests/tree/master/08-cep/04-2Dspiral_BO);
[Purkinje network](https://github.com/SimVascular/svFSI-Tests/tree/master/08-cep/05-Purkinje) | + | FSI | [Webpage](http://simvascular.github.io/docssvFSI-FSI.html); [YouTube](https://www.youtube.com/watch?v=QIpyThIAD7k&list=PL1CBZ8Wh-xvRnux0eMmbZPbx-C078Qzqu&index=4) | ALE:
[2D heart valve](https://github.com/SimVascular/svFSI-Tests/tree/master/07-fsi/ale/01-channel-leaflets_2D);
[2D flag behind a block](https://github.com/SimVascular/svFSI-Tests/tree/master/07-fsi/ale/02-channel-block-flag_2D);
[pressure pulse inside aorta](https://github.com/SimVascular/svFSI-Tests/tree/master/07-fsi/ale/03-pipe_3D)
CMM:
[pipe flow with RCR BC](https://github.com/SimVascular/svFSI-Tests/tree/master/07-fsi/cmm/01-pipe_RCR);
[vein graft](https://github.com/SimVascular/svFSI-Tests/tree/master/07-fsi/cmm/02-vein-graft) | + Below, we provide a list of the available choice of constitutive models for different types of equations being solved. Users are also encouraged to implement new constitutive models. Users may use global search tools such as `grep` to locate the implementations of the available constitutive models in the code using the abbreviated names below. @@ -107,13 +124,29 @@ Below, we provide a list of the available choice of constitutive models for diff | cepModel\_FN | Fitzhugh-Nagumo model | "FN", "Fitzhugh-Nagumo" | | cepModel\_TTP | tenTusscher-Panfilov model | "TTP", "tenTusscher-Panfilov" | -## Additional Resource -More details can be found here: -- Fluid-Structure Interaction (FSI): https://simvascular.github.io/docssvFSI.html -- SimCardio: http://simvascular.github.io/docsSimCardio.html -- Cardiac electrophysiology modeling: http://simvascular.github.io/docsSimCardio.html#cep-modeling -- Cardiac mechanics modeling: http://simvascular.github.io/docsSimCardio.html#mechanics-modeling -- Prescribed-motion LV modeling: https://simvascular.github.io/docsSimCardio.html#automatic-cardiac-modeling +## Documentation +More details can be found on the [**svFSI**](http://simvascular.github.io/docssvFSI.html) page, and direct links to the documentation for different functionalities are provided here: +- [Fluid-Structure Interaction (FSI)](http://simvascular.github.io/docssvFSI-FSI.html) +- [Cardiac electrophysiology modeling](http://simvascular.github.io/docssvFSI-CEP.html) +- [Cardiac mechanics modeling](http://simvascular.github.io/docssvFSI-Structure.html) +- [Prescribed-motion LV modeling](http://simvascular.github.io/docssvFSI-Fluid.html#pres) + +## Tutorial +- SimVascular group uploads hands-on tutorials to our [YouTube](https://www.youtube.com/channel/UCT61XgTRqpfb39Hyio9IqGQ) channel periodically. Here are some for `svFSI`: + - Fluid-Structure Interaction (FSI): https://www.youtube.com/watch?v=QIpyThIAD7k + - Cardiac electrophysiology modeling: https://www.youtube.com/watch?v=TCK3SmGwBa8 + - Cardiac mechanics modeling: https://www.youtube.com/watch?v=Jm3VSi6Aci8 +- We also maintain a large collection of examples that showcase different functionalities of `svFSI`. You can find them here: https://github.com/SimVascular/svFSI-Tests. Each case includes a README file that explains the problem in hand and some key aspects of the software configuration. + +## Pre/Post Processing Tool +We are also maintaining a collection of useful pre and post processing tools that are compatible with `svFSI`: +https://github.com/SimVascular/svFSI-Tools + +## Contribute to `svFSI` +We welcome and appreciate all types of contributions to `svFSI`. +- Seek support, suggest new features or report bugs, please contact us through [GitHub Issues](https://github.com/SimVascular/svFSI/issues) or [SimTK forum](https://simtk.org/plugins/phpBB/indexPhpbb.php?f=188). +- Contribute your code to `svFSI`, please submit a pull request through GitHub. +- Share your novel applications of `svFSI` with the community, please consider contribute your case to [svFSI-Tests](https://github.com/SimVascular/svFSI-Tests). ## Citation In preparation. diff --git a/README_JOSS.md b/README_JOSS.md new file mode 100644 index 00000000..9f966677 --- /dev/null +++ b/README_JOSS.md @@ -0,0 +1,17 @@ +- There are two ways to generate pdf file: + +1. GitHub Action + + GitHub will automatically compile the paper each time the repository is updated. The pdf is available via the Actions tab in the project and click on the latest workflow run. + +2. Docker +``` +docker run --rm \ + --volume $PWD:/data \ + --user $(id -u):$(id -g) \ + --env JOURNAL=joss \ + openjournals/paperdraft +``` + +- [Official documentation](https://joss.readthedocs.io/en/latest/submitting.html#what-should-my-paper-contain) on what should be included in the paper. + diff --git a/paper.bib b/paper.bib new file mode 100644 index 00000000..4926c10c --- /dev/null +++ b/paper.bib @@ -0,0 +1,225 @@ +@article{Xu2020, + author={Xu, JQ and Murphy, SL and Kochanek, KD and Arias, E}, + title={{Mortality in the United States, 2018}}, + journal={NCHS Data Brief No. 355}, + year={2020}, + publisher={National Center for Health Statistics}, + url = {https://www.cdc.gov/nchs/products/databriefs/db355.htm} +} + +@article{Mittal2015, + author = {Mittal, Rajat and Seo, Jung Hee and Vedula, Vijay and Choi, Young J. and Liu, Hang and Huang, H. Howie and Jain, Saurabh and Younes, Laurent and Abraham, Theodore and George, Richard T.}, + doi = {10.1016/j.jcp.2015.11.022}, + issn = {00219991}, + journal = {Journal of Computational Physics}, + pages = {1065--1082}, + publisher = {Elsevier Inc.}, + title = {{Computational modeling of cardiac hemodynamics: Current status and future outlook}}, + url = {http://linkinghub.elsevier.com/retrieve/pii/S0021999115007627}, + volume = {305}, + year = {2015} +} + +@article{Trayanova2011, +author = {Trayanova, Natalia A.}, +doi = {10.1161/CIRCRESAHA.110.223610}, +issn = {00097330}, +journal = {Circulation Research}, +keywords = {Cardiac disease,Electromechanical modeling,Electrophysiological modeling,Simulation,Whole-heart model}, +number = {1}, +pages = {113--128}, +pmid = {21212393}, +title = {{Whole-heart modeling : Applications to cardiac electrophysiology and electromechanics}}, +volume = {108}, +year = {2011} +} + + +@article{Updegrove2017, + author = {Updegrove, Adam and Wilson, Nathan M. and Merkow, Jameson and Lan, Hongzhi and Marsden, Alison L. and Shadden, Shawn C.}, + doi = {10.1007/s10439-016-1762-8}, + issn = {15739686}, + journal = {Annals of Biomedical Engineering}, + keywords = {Hemodynamics,Image-based CFD,Open-source,Patient-specific modeling}, + number = {3}, + pages = {525--541}, + pmid = {27933407}, + title = {{SimVascular: An Open Source Pipeline for Cardiovascular Simulation}}, + volume = {45}, + year = {2017} +} + +@article{Maas2012, + title={FEBio: finite elements for biomechanics}, + author={Maas, Steve A and Ellis, Benjamin J and Ateshian, Gerard A and Weiss, Jeffrey A}, + journal={Journal of biomechanical engineering}, + volume={134}, + number={1}, + year={2012}, + doi={10.1115/1.4005694}, + publisher={American Society of Mechanical Engineers Digital Collection} +} + +@article{Plank2021, +title = {The openCARP simulation environment for cardiac electrophysiology}, +journal = {Computer Methods and Programs in Biomedicine}, +volume = {208}, +pages = {106223}, +year = {2021}, +issn = {0169-2607}, +doi = {https://doi.org/10.1016/j.cmpb.2021.106223}, +url = {https://www.sciencedirect.com/science/article/pii/S0169260721002972}, +author = {Gernot Plank and Axel Loewe and Aurel Neic and Christoph Augustin and Yung-Lin Huang and Matthias A.F. Gsell and Elias Karabelas and Mark Nothstein and Anton J. Prassl and Jorge Sánchez and Gunnar Seemann and Edward J. Vigmond}, +} + +@article{Bertagna2017, + title={The LifeV library: engineering mathematics beyond the proof of concept}, + author={Bertagna, Luca and Deparis, Simone and Formaggia, Luca and Forti, Davide and Veneziani, Alessandro}, + journal={arXiv preprint}, + year={2017}, + url={https://arxiv.org/abs/1710.06596} +} + +@book{Logg2012, + title = {Automated Solution of Differential Equations by the Finite Element Method}, + author = {Anders Logg and Kent-Andre Mardal and Garth N. Wells and others}, + year = {2012}, + publisher = {Springer}, + doi = {10.1007/978-3-642-23099-8}, + isbn = {978-3-642-23098-1}, +} + +@article{Vedula2017, + title={A method to quantify mechanobiologic forces during zebrafish cardiac development using 4-D light sheet imaging and computational modeling}, + author={Vedula, Vijay and Lee, Juhyun and Xu, Hao and Kuo, C-C Jay and Hsiai, Tzung K and Marsden, Alison L}, + journal={PLoS computational biology}, + volume={13}, + number={10}, + pages={e1005828}, + year={2017}, + doi={10.1371/journal.pcbi.1005828}, + publisher={Public Library of Science San Francisco, CA USA} +} + +@article{Grande2021, + title={Computational modeling of blood component transport related to coronary artery thrombosis in Kawasaki disease}, + author={Grande Guti{\'e}rrez, Noelia and Alber, Mark and Kahn, Andrew M and Burns, Jane C and Mathew, Mathew and McCrindle, Brian W and Marsden, Alison L}, + journal={PLOS Computational Biology}, + volume={17}, + number={9}, + pages={e1009331}, + year={2021}, + doi={10.1371/journal.pcbi.1009331}, + publisher={Public Library of Science San Francisco, CA USA} +} + +@article{Arzani2018, +title = {Wall shear stress fixed points in cardiovascular fluid mechanics}, +journal = {Journal of Biomechanics}, +volume = {73}, +pages = {145-152}, +year = {2018}, +issn = {0021-9290}, +doi = {10.1016/j.jbiomech.2018.03.034}, +url = {https://www.sciencedirect.com/science/article/pii/S0021929018302239}, +author = {Amirhossein Arzani and Shawn C. Shadden}, +keywords = {Blood flow, Hemodynamics, Mass transport, Endothelial cells}, +} + +@article{Seo2020a, + title={The effects of clinically-derived parametric data uncertainty in patient-specific coronary simulations with deformable walls}, + author={Seo, Jongmin and Schiavazzi, Daniele E and Kahn, Andrew M and Marsden, Alison L}, + journal={International journal for numerical methods in biomedical engineering}, + volume={36}, + number={8}, + pages={e3351}, + year={2020}, + doi={10.1002/cnm.3351}, + publisher={Wiley Online Library} +} + +@article{Seo2020b, + title={Multifidelity estimators for coronary circulation models under clinically informed data uncertainty}, + author={Seo, Jongmin and Fleeter, Casey and Kahn, Andrew M and Marsden, Alison L and Schiavazzi, Daniele E}, + journal={International Journal for Uncertainty Quantification}, + volume={10}, + number={5}, + year={2020}, + doi={10.1615/Int.J.UncertaintyQuantification.2020033068}, + publisher={Begel House Inc.} +} + +@article{Baumler2020, + title={Fluid--structure interaction simulations of patient-specific aortic dissection}, + author={B{\"a}umler, Kathrin and Vedula, Vijay and Sailer, Anna M and Seo, Jongmin and Chiu, Peter and Mistelbauer, Gabriel and Chan, Frandics P and Fischbein, Michael P and Marsden, Alison L and Fleischmann, Dominik}, + journal={Biomechanics and modeling in mechanobiology}, + volume={19}, + number={5}, + pages={1607--1628}, + year={2020}, + doi={10.1007/s10237-020-01294-8}, + publisher={Springer} +} + +@article{Kong2020, + author = {Kong, Fanwei and Shadden, Shawn C.}, + title = "{Automating Model Generation for Image-Based Cardiac Flow Simulation}", + journal = {Journal of Biomechanical Engineering}, + volume = {142}, + number = {11}, + year = {2020}, + month = {09}, + issn = {0148-0731}, + doi = {10.1115/1.4048032}, + url = {https://doi.org/10.1115/1.4048032}, + note = {111011}, + eprint = {https://asmedigitalcollection.asme.org/biomechanical/article-pdf/142/11/111011/6565541/bio\_142\_11\_111011.pdf}, +} + +@article{heroux2005, + title={An overview of the Trilinos project}, + author={Heroux, Michael A and Bartlett, Roscoe A and Howle, Vicki E and Hoekstra, Robert J and Hu, Jonathan J and Kolda, Tamara G and Lehoucq, Richard B and Long, Kevin R and Pawlowski, Roger P and Phipps, Eric T and others}, + journal={ACM Transactions on Mathematical Software (TOMS)}, + volume={31}, + number={3}, + pages={397--423}, + year={2005}, + publisher={ACM New York, NY, USA}, + url={https://doi.org/10.1145/1089014.1089021} +} + +@article{quateroni_a, + doi = {10.48550/ARXIV.2201.03303}, + + url = {https://arxiv.org/abs/2201.03303}, + + author = {Africa, Pasquale C. and Piersanti, Roberto and Fedele, Marco and Dede', Luca and Quarteroni, Alfio}, + + keywords = {Mathematical Software (cs.MS), Distributed, Parallel, and Cluster Computing (cs.DC), Numerical Analysis (math.NA), FOS: Computer and information sciences, FOS: Computer and information sciences, FOS: Mathematics, FOS: Mathematics, G.4; G.1; J.3, 68-04, 68N30 (Primary), 35-04, 65-04, 65M60, 65N30, 65Y05, 92-04, 92C50 (Secondary)}, + + title = {life$^x$ - heart module: a high-performance simulator for the cardiac function. Package 1: Fiber generation}, + + publisher = {arXiv}, + + year = {2022}, + + copyright = {Creative Commons Attribution Non Commercial Share Alike 4.0 International} +} + + +@article{quateroni_b, + doi = {10.48550/ARXIV.2207.12460}, + url = {https://arxiv.org/abs/2207.12460}, + + author = {Fedele, Marco and Piersanti, Roberto and Regazzoni, Francesco and Salvador, Matteo and Africa, Pasquale Claudio and Bucelli, Michele and Zingaro, Alberto and Dede', Luca and Quarteroni, Alfio}, + + keywords = {Numerical Analysis (math.NA), Computational Engineering, Finance, and Science (cs.CE), Distributed, Parallel, and Cluster Computing (cs.DC), Medical Physics (physics.med-ph), FOS: Mathematics, FOS: Mathematics, FOS: Computer and information sciences, FOS: Computer and information sciences, FOS: Physical sciences, FOS: Physical sciences}, + + title = {A comprehensive and biophysically detailed computational model of the whole human heart electromechanics}, + + publisher = {arXiv}, + + year = {2022}, + + copyright = {Creative Commons Attribution Non Commercial No Derivatives 4.0 International} +} diff --git a/paper.md b/paper.md new file mode 100755 index 00000000..57db291f --- /dev/null +++ b/paper.md @@ -0,0 +1,94 @@ +--- +title: '`svFSI`: A Multiphysics Package for Integrated Cardiac Modeling' +tags: + - fortran + - cardiac modeling + - active contraction + - fluid-structure interaction + - finite element method +authors: + - name: Chi Zhu + orcid: 0000-0002-1099-8893 + equal-contrib: true + affiliation: "1, 2" + - name: Vijay Vedula + affiliation: 3 + equal-contrib: true + - name: Dave Parker + affiliation: 4 + - name: Nathan Wilson + affiliation: 5 + - name: Shawn Shadden + affiliation: 1 + corresponding: true + - name: Alison Marsden + affiliation: 4 + corresponding: true +affiliations: + - name: University of California, Berkeley, United States of America + index: 1 + - name: Peking University, Beijing, People's Republic of China + index: 2 + - name: Columbia University, New York City, United States of America + index: 3 + - name: Stanford University, Stanford, United States of America + index: 4 + - name: University of California, Los Angeles, United States of America + index: 5 +date: 20 January 2021 +bibliography: paper.bib + +# Optional fields if submitting to a AAS journal too, see this blog post: +# # https://blog.joss.theoj.org/2018/12/a-new-collaboration-with-aas-publishing +# aas-doi: 10.3847/xxxxx <- update this with the DOI from AAS once you know it. +# aas-journal: Astrophysical Journal <- The name of the AAS journal. +--- + +# Summary + +Heart disease is the number one cause of death in the US [@Xu2020]. Many efforts have been devoted to studying its progression, diagnosis, and treatment. During the past decade, computational modeling has made significant inroads into the research of heart disease. The heart is inherently a multiphysics system that includes electrophysiology, tissue mechanics, and blood dynamics. Its normal function starts with the propagation of electrical signals that trigger the active contraction of the heart muscle to pump blood into the circulatory system. Rooted in fundamental laws of physics such as the balance of mass, momentum, and energy, computational modeling has been instrumental in studying cardiac physiology such as left ventricular function [@Mittal2015], cardiac arrhythmia [@Trayanova2011], and blood flow in the cardiovascular system [@Arzani2018;@Grande2021]. `svFSI` is the first open source software that specializes in enabling coupled electro-mechano-hemodynamic simulations of the heart. + +# Statement of need + +Accompanying the growing popularity of studying cardiac physiology with computational modeling, many open source software tools that specialize in modeling one or two aspects of the multiphysics process in the heart have been developed. For example, `SimVascular` [@Updegrove2017] enables patient-specific blood flow modeling by providing a complete pipeline from medical image segmentation to simulation results. `FEBio` [@Maas2012] specializes in modeling large-deformation structure mechanics in biophysics with fluid-structure interaction (FSI) capability as well. `openCARP` [@Plank2021] focuses on modeling cardiac electrophysiology. There are other general-purpose open source software such as `LifeV` [@Bertagna2017] and `FEniCS` [@Logg2012], that can be flexibly adapted to simulate different physics in the heart, but significant development effort may be required for this purpose. Recently, Quarteroni et al. have also been developing an open source simulator for the cardiac function, and the fiber generation module [@quateroni_a] and electromechanics [@quateroni_b] have been announced so far. + +`svFSI` is a new multiphysics finite element solver designed specifically for computational modeling of integrative heart dynamics. As the next generation finite element solver for the `SimVascular` software, `svFSI` is capable of modeling hemodynamics, performing large-deformation FSI to capture the motion of cardiac chambers and their interaction with the blood flow, and simulating the complex excitation-contraction coupling between the intracellular ion-exchange processes and tissue contraction. To suit the diverse needs of users, our team has implemented non-Newtonian blood viscosity models, fiber-reinforced nonlinear hyperelastic material models, and both phenomenological and biophysics-based cellular activation models. `svFSI` is also capable of resolving the inherent multi-scale phenomena in cardiac physiology such as the interaction between Purkinje fibers and cardiac muscle, and setting up closed-loop multi-scale hemodynamic simulations with physiological boundary conditions. Moreover, it is worth emphasizing that `svFSI` is fully compatibility with `SimVascular`, and thus can take advantage of the existing pipeline for medical image segmentation, anatomic model construction, meshing, boundary condition prescription, etc. `svFSI` is written in Fortran, taking advantage of the object-oriented programming features of Fortran 2003. It is capable of parallel simulation using MPI. It also provides several built-in iterative linear solvers and preconditioners, along with many other options through Trilinos[@heroux2005]. The code is highly modularized for ease of interoperability and extension. We acknowledge the limited open source compiler support for Fortran on Windows systems, and there is an ongoing effort to convert `svFSI` into pure C++ software. + +# Software architecture + +![Illustration of a multi-mesh, multi-domain simulation configuration.\label{fig:mesh}](Mesh.png){ width=80% } + +The `svFSI` solver defines a modeling task through three key components (objects): mesh, domain, and equation. A mesh defines a spatial discretization of the physical regions such as the Purkinje network, myocardium, or the blood volume. It can be divided into non-overlapping domains through unique domain IDs. Different physical equations, such as the Navier-Stokes (fluid) equation and the structural mechanics (struct) equation are solved on each domain with domain-specific material properties. \autoref{fig:mesh} illustrates how these three objects are utilized in the multiphysics modeling of cardiac mechanics. The whole computational model is composed of two meshes. Mesh 1 represents the ventricular myocardium, where both electrophysiology and nonlinear solid mechanics equations are solved. Given the material heterogeneity of the myocardium, mesh 1 can be further divided into multiple domains so that domain-specific material properties, such as electrical conductivity and material elasticity, can be assigned. Mesh 2 is the fluid region where only the Navier-Stokes equations are solved. + +![Class hierarchy that constitutes a simulation. Description of each class is provided in \autoref{tab:class}. \label{fig:class}](Class.png){ width=80% } + +This highly flexible, multi-mesh, and multi-domain modeling capability is realized in `svFSI` through the class hierarchy depicted in \autoref{fig:class}. The three key components, i.e. mesh, domain, and equation, correspond to classes mshType, dmnType and eqType, respectively. The material heterogeneity for electrophysiology, tissue mechanics or hemodynamics within each domain is defined through cepModelType, stModelType or viscModelType (see \autoref{tab:class}). Two other important classes, bcType and lsType, are also shown in \autoref{fig:class}. They define the boundary conditions and settings for the linear solver that are essential to generating a well-posed simulation configuration. + +\begin{table}[H] + \centering + \begin{tabular}{|l|p{8cm}|} + \hline + \textbf{Class name} & \textbf{Description} \\ \hline + mshType & Defines properties of the mesh, such as the element type, number of nodes per element, and coordinates. \\ \hline + eqType & Defines properties of the equation, such as the physics (fluid/struct/electrophysiology), domains, linear solvers, and boundary conditions. \\ \hline + dmnType & Defines properties of the domain, such as the physics (fluid/structure/electrophysiology), material properties, stabilization parameters, etc. \\ \hline + bcType & Defines properties of the boundary conditions, such as Dirichlet or Neumann, time dependence, spatial profile, etc. \\ \hline + lsType & Defines properties of linear solvers. \\ \hline + cepModelType & Defines properties of the electrophysiology model \\ \hline + stModelType & Defines properties of the structure material model \\ \hline + viscModelType & Defines properties of the viscosity model for fluids \\ \hline + \end{tabular} + \caption{Main classes defined in svFSI.} + \label{tab:class} +\end{table} + +Full documentation for `svFSI` functionality is available from the `SimVascular` website at http://simvascular.github.io. + +# Conclusion +`svFSI` is a multiphysics finite-element solver focusing on whole heart modeling and consists of modules that can efficiently simulate hemodynamics, cardiac mechanics, cardiac electrophysiology as well as the multiphysical interactions among them. `svFSI` has been used to generate several publications [@Vedula2017;@Seo2020a;@Seo2020b;@Baumler2020;@Kong2020] and is employed in several active projects. We will continue to support and develop the software. New features such as methods to simulate heart valves, vascular growth and remodeling are currently under development. The software is envisioned to be applicable to a wide range of research questions in both pediatric and adult cardiovascular disease. + +# Acknowledgments + +This work was supported by the National Science Foundation SI2-SSI 1663671 and 1663747. C.Z. also acknowledges funding from the American Heart Association award 20POST35200253. Previous contribution to the software by Dr. Mahdi Esmaily-Moghadam and Dr. Justin Tran is also acknowledged. + +# References diff --git a/paper.pdf b/paper.pdf new file mode 100644 index 00000000..b735431b Binary files /dev/null and b/paper.pdf differ