Merge pull request #89 from SimVascular/JOSS_paper

Merge changes made during JOSS review to main branch.

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)

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

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")

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

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 <IMAGE ID>
+   ```
+
+
+
+### 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.

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.
 
 <hr style="border:2px solid gray"> </hr>
 

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="<Path_to_Trilinos>/lib/cmake/Trilinos;<Path_to_any_other_package>;"`.
 
-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 <number of MPI processes>  <Path to Build>/svFSI-build/bin/svFSI <Pa
 ```
 ## Features
 
-`svFSI` provides the capability to model a variety of physics including unsteady diffusion, linear and nonlinear elastodynamics, convective heat transfer, fluid flows, fluid-structure-interaction (FSI), and cardiac electrophysiology. As the code is modular, the users are provided with a choice to couple these physics depending on their needs. We strongly recommend users to browse through the examples provided in the GitHub repository [svFSI-Tests](https://github.com/SimVascular/svFSI-Tests) to get a detailed insight into the capability of the code.
+`svFSI` provides the capability to model a variety of physics including unsteady diffusion, linear and nonlinear elastodynamics, convective heat transfer, fluid flows, fluid-structure-interaction (FSI), and cardiac electrophysiology. As the code is modular, the users are provided with a choice to couple these physics depending on their needs. We strongly recommend users to browse through the examples provided in the GitHub repository [svFSI-Tests](https://github.com/SimVascular/svFSI-Tests) to get a detailed insight into the capability of the code. Also, most of the examples contain established simulation results, which users can use to verify the functionality of `svFSI`. Here is a list of the main features of `svFSI`.
+
+   | *Physics Solved*  | *Documentation/Tutorial* | *Examples* |
+   |-------------------|--------------------------|------------|
+   | Fluid             | [Webpage](http://simvascular.github.io/docssvFSI-Fluid.html)                                                                                                              | [pipe flow with RCR BC](https://github.com/SimVascular/svFSI-Tests/tree/master/04-fluid/01-pipe3D_RCR);<br>[dye transportation](https://github.com/SimVascular/svFSI-Tests/tree/master/04-fluid/02-dye_AD);<br>[GenBC/cplBC](https://github.com/SimVascular/svFSI-Tests/tree/master/04-fluid/04-3D0D-coupling-BC);<br>[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:<br>[block compression](https://github.com/SimVascular/svFSI-Tests/tree/master/05-struct/01-block-compression);<br>[passive inflation of LV model](https://github.com/SimVascular/svFSI-Tests/tree/master/05-struct/02-LV-Guccione-passive)<br>ustruct:<br>[block compression](https://github.com/SimVascular/svFSI-Tests/tree/master/06-ustruct/01-block-compression);<br>[tension of arterial strip](https://github.com/SimVascular/svFSI-Tests/tree/master/06-ustruct/02-tensile-adventitia_HGO);<br>[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); <br>[ten-Tusscher-Panfilov model](https://github.com/SimVascular/svFSI-Tests/tree/master/08-cep/03-benchmark_tTP); <br>[Bueno-Orovio-Cherry-Fenton model](https://github.com/SimVascular/svFSI-Tests/tree/master/08-cep/04-2Dspiral_BO); <br>[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:<br>[2D heart valve](https://github.com/SimVascular/svFSI-Tests/tree/master/07-fsi/ale/01-channel-leaflets_2D); <br>[2D flag behind a block](https://github.com/SimVascular/svFSI-Tests/tree/master/07-fsi/ale/02-channel-block-flag_2D); <br>[pressure pulse inside aorta](https://github.com/SimVascular/svFSI-Tests/tree/master/07-fsi/ale/03-pipe_3D)<br>CMM:<br>[pipe flow with RCR BC](https://github.com/SimVascular/svFSI-Tests/tree/master/07-fsi/cmm/01-pipe_RCR);<br>[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.

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.
+