Users are recommended to use the remote service for the up to date methods and functions. Users are also recommended to use Red Hat or Fedora, unless they use Sun Solaris or bare Linux. Mac middleware cannot be supported, and Windows computers are out of scope for simulations (but not the GUI). The SimVascular GUI (for interactive image segmentation) is not supported, and is known to work on Unix, Linux, MacOS, and Windows. It is reccommended that the GUI is used for segmentation, model (anatomical and function) building, inclusion of inlet and outlet boundary conditions, and creating the model scripts. Support for research simulations will be provided during production runs.
Local copies of the source have been provided in the Goldman, Anazodo, and Welsh groups. The routinely updated source is distributed from GitHub @ mccsssk2:
https://github.com/mccsssk2/SimVascularPM3_March2020.git
1D WPs use the GUI and 1D binaries, which are provided locally and on Compute Canada. As of 13th April 2021, sufficient support is provided to construct and test 3D models.
The users for the 1D work plans have been provided with usernames and passwords within the kharches account. The generic username is pm3user. The machines used are mainly Cedar, Niagara, Graham. We will provide PM3-SV on Beluga over the course of the year (2021). All users should connect to the computers using:
ssh -XY username@whicevercomputer.ca
Ensure that you are using the bash shell, and you may need to use both their .profile and $HOME/.bashrc files. All PM3-SV binaries' soft links, data (structures, PM3-SV scripts), and other repositories are provided to you in your $HOME.
All PM3 users have access (some read, all execute) to the maintained PM3-SV and related software on remote services. The location is:
All binaries and supporting scripts are located in: computer_name:/home/kharches/software/
computers: Kirk (local), Graham and Cedar (national), Goldman (Med Bio dept, UWO) and Anazodo (St. Jo's hospital, UAs Scientific Linux) groups.
Specifically for 1D modelling, users will need to add following path to their profile and bashrc:
/home/kharches/software/PM3SV/svOneDSolver/bin/{pm3_1dserial, pm3_1dparallel}
It is recommended that users start using the serial binary prior to production runs (simulation experiments) using the parallel binary. Users should consult slurm documentation to generate batch scripts. Users have been provided slurm scripts, both serial and parallel for specific computers. A serial batch script example is given below for the account "kharches" on our national services.
#!/bin/bash
# Use a bash environement using standard modules
#SBATCH --time=00:15:00 # run for 15 minutes.
#SBATCH --account=def-kharches # account charged, this is fixed.
./binary input_script_name.in /path/to/output # run the program.
1D models consist of a blood vessel network (structure) with one inlet (called inlet) and multiple outlets (called boundary conditions). The structure is encoded into a SWC file format.
SWC files are created by the user either by segmenting centerlines from images of vasculature, or from published morphometry data, or are given in repositories for the brain, skeletal muscle, heart, and other organs. When generating centerlines from 3D objects (images or binary volumes/surfaces), the users may wish to use Vascular Modelling ToolKit. The SWC file is a 7 column text file consisting of the following:
Node_number vessel_attribute(not_used) x_coordinate_mm y_mm z_mm starting_radius_mm parent_node_number
In the SWC format, inlets are always numbered 1 and the inlet's parent defaults to -1. The network is assumed to have bifurcations. Trifurcations are to be manually converted to bifurcations by adding short segments. Using the number labels of nodes and their parents, segments are constructed. Following is an example of a SWC file for the human female aorta obtained after processing the Visible Human Female NIH images.
1 2 80 75 120 14 -1
2 3 80 70 100 14 1
3 3 72 82 80 14 2
4 3 55 97 72 12 3
5 3 44 100 74 11 4
6 3 38 102 77 11 5
7 3 28 102 85 11 6
8 3 14 110 180 12 7
9 3 22 104 230 11 8
A python (also matlab) script, called onedInScript.py, is provided to all users that further processes above SWC file into a PM3-SV script. PM3-SV (and SimVascular) scripting, called in scripting, generates scripts with a .in extension, e.g. femaleAorta1D.in .
In the 1D case, the inlet is generated with the recently developed 0D model's heart or aorta pressure or flow wave forms. 0D model here. The inlet model provides the inlet lumped parameter network (LPN components for the 1D models required for all 3 WPs that are onboarded in April 2021. The outlet boundary conditions (outlet LPNs) are discussed below. unlike SimVascular, PM3-SV generates its scripts using custom programs provided to all users. Users may wish to use SimVascular GUI for rapid prototyping. An example of an PM3-SV script is as follows.
MODEL VisibleHumanFemaleAorta # The following list of nodes comes from the SWC network/morphology. NODE 0 26.400000 24.750000 39.600000 NODE 1 26.400000 23.100000 33.000000 NODE 2 23.760000 27.060000 26.400000 NODE 3 18.150000 32.010000 23.760000 NODE 4 14.520000 33.000000 24.420000 NODE 5 12.540000 33.660000 25.410000 NODE 6 9.240000 33.660000 28.050000 NODE 7 4.620000 36.300000 59.400000 NODE 8 7.260000 34.320000 75.900000 # Segments and joints (bifurcations) are generated using the nodes above. SEGMENT seg0 0 20.615528 10 0 1 67.055410 67.055410 0.000000 MAT1 NONE 0.000000 0 0 NOBOUND NONE SEGMENT seg1 1 24.657656 10 1 2 67.055410 67.055410 0.000000 MAT1 NONE 0.000000 0 0 NOBOUND NONE SEGMENT seg2 2 24.041631 10 2 3 49.265199 49.265199 0.000000 MAT1 NONE 0.000000 1 0 NOBOUND NONE SEGMENT seg3 3 11.575837 10 3 4 41.396452 41.396452 0.000000 MAT1 NONE 0.000000 2 0 NOBOUND NONE SEGMENT seg4 4 7.000000 10 4 5 41.396452 41.396452 0.000000 MAT1 NONE 0.000000 3 0 NOBOUND NONE SEGMENT seg5 5 12.806248 10 5 6 41.396452 41.396452 0.000000 MAT1 NONE 0.000000 4 0 NOBOUND NONE SEGMENT seg6 6 96.358705 10 6 7 49.265199 49.265199 0.000000 MAT1 NONE 0.000000 5 0 NOBOUND NONE SEGMENT seg7 7 50.990195 10 7 8 41.396452 41.396452 0.000000 MAT1 NONE 0.000000 6 0 RESISTANCE OUTLETDATA # # JOINTINLET IN1 1 0 JOINTINLET IN2 1 1 JOINTINLET IN3 1 2 JOINTINLET IN4 1 3 JOINTINLET IN5 1 4 JOINTINLET IN6 1 5 JOINTINLET IN7 1 6 JOINTINLET IN8 1 7 JOINTOUTLET OUT1 1 0 JOINTOUTLET OUT2 1 1 JOINTOUTLET OUT3 1 2 JOINTOUTLET OUT4 1 3 JOINTOUTLET OUT5 1 4 JOINTOUTLET OUT6 1 5 JOINTOUTLET OUT7 1 6 JOINTOUTLET OUT8 1 7 JOINT JOINT1 1 IN1 OUT2 JOINT JOINT2 2 IN2 OUT3 JOINT JOINT3 3 IN3 OUT4 JOINT JOINT4 4 IN4 OUT5 JOINT JOINT5 5 IN5 OUT6 JOINT JOINT6 6 IN6 OUT7 JOINT JOINT7 7 IN7 OUT8 # # Inlet boundary conditions (inlet LPNs). # In this case, a constant flow/pressure of 21 was applied. DATATABLE INLETDATA LIST 0.0 21.0 32.5 21.0 ENDDATATABLE # # Outlet boundary conditions. # In this case the one outlet was assumed to have constant resistance of 151. DATATABLE OUTLETDATA LIST 0.0 151.0 ENDDATATABLE # Simulation/integration parameters. SOLVEROPTIONS 0.001 100 1000 4 INLETDATA FLOW 0.001 1 1 MATERIAL MAT1 OLUFSEN 1.06 0.04 0 2.0 1.0e15 -20 1e9 # # Outputs are VTK for viz, and text for generating the hemodynamic risk factors. OUTPUT VTK OUTPUT text # pressures and flows for each finite element are output here.
In all the 1D cases that are onboarded to date, the inlet is generated with the recently developed 0D model's heart or aorta pressure or flow wave forms. 0D model here. The lead developer will provide inlet waveforms (LPNs) of either pressure or flow according to user requirements. The inlet LPN will be further developed and maintained according to user requirements.
Three types of outlet boundary conditions, to represent inlet left ventricle, and microvasculature at the ends of the large vessels, are available. The onboarded teams will be supported thru' their simulation experiments for debugging and testing their respective in files, and underlying codes. Each boundary condition (inlet and outlet) can be transient (time dependent) or constant.
Users should organize their in script by first defining SEGMENTS, followed by the outlet conditions. As shown above, segment 7 (seg7) is a terminal and must have a boundary condition at its distal end. First, the boundary condition is given a name (OUTLETDATA, this model has just one outlet), after which it is defined as below (reproduced from above in file).
. . . # define terminal segment with named outlet boundary conditions. SEGMENT seg7 7 50.990195 10 7 8 41.396452 41.396452 0.000000 MAT1 NONE 0.000000 6 0 RESISTANCE OUTLETDATA # # Outlet boundary conditions. # In this case the one outlet was assumed to have constant resistance of 151. DATATABLE OUTLETDATA LIST 0.0 151.0 # first number is time, second is value of the resistance, or quantitiy at the distal (terminal) end of a segment. 0.2 150.0 # the list is as long as the simulation if the resistance is time varying. ENDDATATABLE . . .
User defined outlet boundary conditions, such as time dependent R-C-R can be generated using our 0D code, or from GenBC, which requires fortran programming. Users will be supported for general boundary conditions.
Velocity, or inflow conditions are expected to be used by the onboarded teams. The inlet LPN, constant or transient, waveforms will be generated using our 0D LPN models and used in the in scripts to apply the inlet boundary conditions.
All model outputs are output at the user defined rate in the in file. The VTK outputs are a series of vtp (VTK points) files and have pressure, flow, and WSS at the centres of all finite elements in the model. Outside of PM3-SV, PM3 will offer customized functions that can take the VTP files and further process (combine) them to generate more clinically relevant outputs, dependending on user requirements.
All model outputs are output at the user defined rate in the in file. The text outputs are a series of ASCII text files and have pressure, flow, and WSS at the centres of all finite elements in the model. Outside of PM3-SV, PM3 will offer users some simple python and matlab functions that take the text files and further process (combine) them to generate more clinically relevant outputs, dependending on user requirements
WP specific data, scripts, models, and documentation is provided to support individual users. Due to the material being research live, it cannot be made openly available as of 13th April 2021.
Model is used within context to mean segmented anatomical model of centerlines and surfaces, a solid model, finite element mesh model of the structure, and functional CFD model. In this part, finite element meshing using TetGen is explained in a practical manner.
This guide assumes that the user has already generated the centrelines and reasonably smooth surfaces of their incidental vasculature.
The combination of the centerlines, surface, volumes, are stored in multiple files across the directory strucuture of a project. If the
user has not yet done so, it is highly reccommended that all images be strictly processed using the SV-GUI and a project directory
created. Each attempt at segmenting the imaging dataset can be saved in multiple anatomical models, to be subsequently
and individually meshed. The SV provided directory structure holds the relative paths to various files, and as such should not
be changed as GUI support is not provided within PM3-SV.
Finite element mesh generation is a two step process where you first create a solid model (providing an STL file) followed by the finite
element mesh itself. In this project, we will use TetGen FE mesher that is provided within the SimVascular GUI.
To generate a solid model and FE mesh, use the following procedure as you learn about the GUI functions: