Update JOSS paper references and license (#163)

Co-authored-by: menon-karthik <[email protected]>
Co-authored-by: Martin Pfaller <[email protected]>
Co-authored-by: Nick Dorn <[email protected]>

Author: 3 people

CMakeLists.txt

@@ -28,7 +28,8 @@
 # NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-cmake_minimum_required(VERSION 3.22)
+set(CMAKE_POLICY_VERSION_MINIMUM 3.5)
+cmake_minimum_required(VERSION 3.5)
 set(CMAKE_CXX_STANDARD 17)
 set(CMAKE_CXX_STANDARD_REQUIRED True)
 

LICENSE.txt

@@ -1,13 +1,7 @@
 Copyright (c) Stanford University, The Regents of the University of California, and others.
 
-All Rights Reserved.
-
-See Copyright-SimVascular.txt for additional details.
-
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 
 
 The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
 
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
-License type: MIT License

paper/paper.bib

@@ -329,3 +329,91 @@ @article{crimson2021
 @article{Hirschvogel2024, doi = {10.21105/joss.05744}, url = {https://doi.org/10.21105/joss.05744}, year = {2024}, publisher = {The Open Journal}, volume = {9}, number = {93}, pages = {5744}, author = {Marc Hirschvogel}, title = {Ambit – A FEniCS-based cardiovascular multi-physics solver}, journal = {Journal of Open Source Software} }
 
 @article{Agdestein2018, doi = {10.21105/joss.01107}, url = {https://doi.org/10.21105/joss.01107}, year = {2018}, publisher = {The Open Journal}, volume = {3}, number = {32}, pages = {1107}, author = {Syver D. Agdestein and Kristian Valen-Sendstad and Alexandra K. Diem}, title = {Artery.FE: An implementation of the 1D blood flow equations in FEniCS}, journal = {Journal of Open Source Software} }
+
+@article{Diem-2017,
+ author = {Diem, Alexandra K. and Bressloff, Neil W.},
+ doi = {10.5334/jors.159},
+ journal = {Journal of Open Research Software},
+ keyword = {en_US},
+ month = {Jun},
+ title = {VaMpy: A Python Package to Solve 1D Blood Flow Problems},
+ year = {2017}
+}
+
+@article{REGAZZONI2021104641,
+title = {Accelerating the convergence to a limit cycle in 3D cardiac electromechanical simulations through a data-driven 0D emulator},
+journal = {Computers in Biology and Medicine},
+volume = {135},
+pages = {104641},
+year = {2021},
+issn = {0010-4825},
+doi = {https://doi.org/10.1016/j.compbiomed.2021.104641},
+url = {https://www.sciencedirect.com/science/article/pii/S0010482521004352},
+author = {F. Regazzoni and A. Quarteroni},
+keywords = {Mathematical modeling, Cardiac modeling, Cardiac electromechanics, Multiphysics models, Lumped-parameter models}
+}
+
+@article{benemerito2024openbf,
+  title={openBF: an open-source finite volume 1D blood flow solver},
+  author={Benemerito, I and Melis, A and Wehenkel, Antoine and Marzo, A},
+  journal={Physiological Measurement},
+  volume={45},
+  number={12},
+  pages={125002},
+  year={2024},
+  publisher={IOP Publishing}
+}
+
+@article{cellml,
+url = {https://doi.org/10.1515/jib-2020-0021},
+title = {CellML 2.0},
+author = {Michael Clerx and Michael T. Cooling and Jonathan Cooper and Alan Garny and Keri Moyle and David P. Nickerson and Poul M. F. Nielsen and Hugh Sorby},
+pages = {20200021},
+volume = {17},
+number = {2-3},
+journal = {Journal of Integrative Bioinformatics},
+doi = {doi:10.1515/jib-2020-0021},
+year = {2020}
+}
+
+@inproceedings{alastruey2012arterial,
+  title={Arterial pulse wave haemodynamics},
+  author={Alastruey, Jordi and Parker, Kim H and Sherwin, Spencer J},
+  booktitle={11th international conference on pressure surges},
+  pages={401--443},
+  year={2012},
+  organization={Virtual PiE Led t/a BHR Group}
+}
+
+@article{heldt2010cvsim,
+  title={CVSim: an open-source cardiovascular simulator for teaching and research},
+  author={Heldt, Thomas and Mukkamala, Ramakrishna and Moody, George B and Mark, Roger G},
+  journal={The open pacing, electrophysiology \& therapy journal},
+  volume={3},
+  pages={45},
+  year={2010}
+}
+
+@article{HUTTARY2017104,
+title = {Simulation, identification and statistical variation in cardiovascular analysis (SISCA) – A software framework for multi-compartment lumped modeling},
+journal = {Computers in Biology and Medicine},
+volume = {87},
+pages = {104-123},
+year = {2017},
+issn = {0010-4825},
+doi = {https://doi.org/10.1016/j.compbiomed.2017.05.021},
+url = {https://www.sciencedirect.com/science/article/pii/S0010482517301439},
+author = {Rudolf Huttary and Leonid Goubergrits and Christof Schütte and Stefan Bernhard},
+keywords = {Windkessel elements, Lumped models, 0D modeling, Multi-compartment modeling, Cardiovascular simulation, Distributed parameter modeling, Clinical data set, Coarctation of aorta, Patient-specific models, Disease-specific models, Multiscale modeling}
+}
+
+@article{rosalia2021object,
+  title={Object-oriented lumped-parameter modeling of the cardiovascular system for physiological and pathophysiological conditions},
+  author={Rosalia, Luca and Ozturk, Caglar and Van Story, David and Horvath, Markus A and Roche, Ellen T},
+  journal={Advanced Theory and Simulations},
+  volume={4},
+  number={3},
+  pages={2000216},
+  year={2021},
+  publisher={Wiley Online Library}
+}

paper/paper.md

@@ -89,12 +89,24 @@ Together, these graphical interfaces make `svZeroDSolver` intuitive for a wide r
 The functionality and accuracy of `svZeroDSolver` is assessed using continuous integration tests on GitHub, and has also been verified by comparing with high-fidelity three dimensional simulations [@pfaller22].
 This combination of features makes `svZeroDSolver` uniquely applicable to a wide range of applications in cardiovascular biomechanics.
 
+# State of the field
+
 While there are other open-source projects that provide the functionality for cardiovascular flow modeling, and specifically zero-dimensional flow modeling, `svZeroDSolver` has several features that distinguish it from previous work. 
-For one, prior packages have primarily focused on multi-physics finite element modeling for cardiovascular biomechanics [@crimson2021; @Zhu2022; @AFRICA2024109039; @Hirschvogel2024]. 
-While these projects allow the implementation of simple zero-dimensional models, usually as boundary conditions to three-dimensional models, the primary focus is on the modeling of full three-dimensional fluid and tissue mechanics. 
-There are also packages aimed at reduced-order modeling for cardiovascular flows [@Agdestein2018]. In particular, the `SimVascular` project includes `svOneDSolver` for the purpose of one-dimensional blood flow modeling.
-In contrast to these packages, the purpose of `svZeroDSolver` is to provide a modular framework specifically for simulating zero-dimensional flows in a variety of simple and complex anatomies -- by leveraging the modular nature of the code.
-The unique features listed above allow the use of `svZeroDSolver` both as a stand-along zero-dimensional flow solver for unique and patient-specific anatomies, as well as in conjunction with the aforementioned multi-physics solvers as boundary conditions, for parameters estimation and uncertainty quantification, or even as an instructional tool using its graphical interfaces.  
+In particular, prior packages have primarily focused on multi-physics finite element modeling for cardiovascular biomechanics [@crimson2021; @Zhu2022; @AFRICA2024109039; @Hirschvogel2024]. 
+Although these projects allow the implementation of simple zero-dimensional models, usually as boundary conditions to three-dimensional models, the primary focus is on the modeling of full three-dimensional fluid and tissue mechanics. 
+There are, however, packages aimed specifically at reduced-order modeling for cardiovascular flows.
+For example, the `SimVascular` project includes [`svOneDSolver`](https://github.com/SimVascular/svOneDSolver) for the purpose of one-dimensional blood flow modeling.
+Another popular package for one-dimensional blood flow simulations is `Nektar1D` [@alastruey2012arterial].
+Similarly, `Artery.FE` implements one-dimensional blood flow modeling using the FEniCS finite element framework [@Agdestein2018], the `VaMpy` toolkit includes a package for modeling one-dimensional blood flow using the Lax-Wendroff finite difference method [@Diem-2017], and `openBF` is a finite volume implementation of one-dimensional blood flow [@benemerito2024openbf].
+
+In the zero-dimensional modeling context, `CRIMSON` [@crimson2021] and `lifex-cfd` [@AFRICA2024109039] include the ability to simulate simple zero-dimensional blood flow models, primarily as boundary conditions to three-dimensional simulations.
+However, their focus is on multi-physics simulations of cardiovascular biomechanics, therefore they are not stand-alone and modular zero-dimensional flow solvers.
+The `CellML` and `CVSim`  packages include a limited set of stand-alone zero-dimensional flow models for specific anatomies/applications [@cellml; @heldt2010cvsim], but they do not provide the modular functionality to specify unique anatomical models.
+In addition, there have been other packages that use zero-dimensional modeling techniques with a focus on statistical analysis, cardiac electromechanics, or specific anatomical models [@HUTTARY2017104; @REGAZZONI2021104641; @rosalia2021object].
+However, these packages are either not focused on zero-dimensional modeling or use MATLAB implementations, which require software licenses and are not free to use. 
+
+In contrast to these existing packages, the purpose of `svZeroDSolver` is to provide an open-source framework specifically for simulating zero-dimensional flows in a variety of simple and complex anatomies that can be designed in a user-specific and application-specific manner -- by leveraging the modular nature of the code.
+The unique features listed above allow the use of `svZeroDSolver` both as a stand-alone zero-dimensional flow solver for unique and patient-specific anatomies, as well as in conjunction with the aforementioned multi-physics solvers as boundary conditions, for parameters estimation and uncertainty quantification, or even as an instructional tool using its graphical interfaces.  
 
 ![Various zero-dimensional "blocks" included in `svZeroDSolver` at the time of writing.\label{fig:blocks}](blocks.png){ width=80% }
 

paper/paper.pdf

@@ -100,6 +100,11 @@ void SparseSystem::update_jacobian(double time_coeff_ydot,
 
 void SparseSystem::solve() {
   solver->factorize(jacobian);
+  if (solver->info() != Eigen::Success) {
+    throw std::runtime_error(
+        "System is singular. Check your model (connections, boundary "
+        "conditions, parameters).");
+  }
   dydot.setZero();
   dydot += solver->solve(residual);
 }