How to create a network
How to create a network
Introduction
In the model world of STARFiSh, an arterial network is described with a network xml file. The advantage of using a xml file is that it is both computer and human readable so it can be updated and modified conveniently. It is always possible for the user to create a network xml file directly and store data in it. This is a very cumbersome task if the network consists of several arteries. Therefore STARFiSh includes the vascular network creator (vnc). With this program arterial networks can be created, modified and exported in various data formats such as the network xml file. Large data sets are handled much more convenient by the use of spreadsheet programs as Excel or libreOffice-Calc. These programs can export the data with *.csv files and imported into vnc. This gives a smart solution for creating and updating large arterial networks. Note: It is important to set the csv delimiter to a semicolon! The following figure illustrates the arterial data flow while creating network xml file and use it as an input file for STARFiSh.
The table bellow illustrates the different types of data used for a simulation in STARFiSh and how they can be read in. 
Boundary condition, vessel topology and fluid data can be save in a xml file by using vnc directly or by loading a csv file into vnc to create a xml file.
Network files folder convention
In STARFiSh we us the convention that every network xml file is saved in its own directory in the networkFiles directory of STARFiSh_v0.3 folder.Example: the network singleBifurcation.xml is stored in: STARFiSh_v0.3/networkFiles/singleBifurcation/singleBifurcation.xml
The csv files for vessel data and boundary conditions of the network need to be saved in the same directory and have the following name spacing: networkName.csv for vessel data and networkNameBC.csv for the boundary conditions. If you save a network with vnc the folders will be created correctly, however if you try to open a csv file with e.g. vessel data which does not follow this convention, the program will fail.Arterial network creation
In the following it will be explained how to create a network xml file using the vnc and csv data. To start vnc open a terminal and browse into your STRAFiSh_v0.3 directory, then start vnc with the following command:$python main_vnc.pyVnc is console based but has an additional window which is visualising the current network with its topology, vessel and boundary conditions. This is based on graphviz. If you click on a vessel or boundary condition in this window, the current data stored for this object is shown in your terminal window. The following shows the main menu of vnc, the topology window is shown later on in the example network section :
===================================== # VascularNetworkCreator_v2.1 # ===================================== [a] - add vessel to network [d] - delete vessel in network [n] - new network [b] - set boundary conditions [f] - set global fluid properties [l] - load network [s] - save network [u] - update XML form CSV file(s) [g] - print network graph [p] - print network informations [q] - quit current network: None what to do?If we later explain task which start from the main menu, we only show you the last line, and the input ins marked in blue. Example:
...
what to do? q
The example network
The network concerned is the singleBifurcation you find in the STARFiSh_v0.3 version on GitHub. So you can find the csv files for the vessel data and boundary conditions in your STARFiSh_v0.3 directory. The network consist of three vessels, the parent vessel is the root vessel with id = 0 and the left vessel is the left daughter with id = 1, while the right vessel is the right daughter with vessel id = 2. The following figure provides a better illustration while the table provides the data:
Add Vessels
As explained in the Introduction, there are several ways to insert the vessel data to the xml file. Here we will do the following setps:- create the network topology with vnc
- load a csv file with the other network data
Add new vessel enter the vessel id: 0 define vessel compliance! available compliance types: [ 0 ] default (Hayashi) [ 1 ] Hayashi [ 2 ] Reymond [ 3 ] Laplace2 [ 4 ] Laplace [ 5 ] Exponential choose type 0
Repeat the same for the 2 daughter vessels, vessel id = 1 for the (left daughter and vessel id = 2 for the right daughter. vnc will ask you to specify the mother vessel Id of vessel you added, here we type in 0 for both daughter vessels.
Note: the first daughter you add to a vessel is per definition always the left daughter, the second will be right, this can be changed in the xml or csv files, or by deleting the left daughter and adding a new vessel. After you added all the vessels, the topology window should now look like this :
... what to do? l sub menu: load data [1] - load network from XML [2] - load vessel data from CSV [3] - load vessel data and boundary conditions from CSV [4] - load network from SolutionData [b] - back to the main menu what to do? 2 resent used networks load vessel data from CSV - non existing vessels are added automatically current filename: None enter/change filename (only! ENTER to use current filename): yourVesselData
Add Global Fluid properties
To set the fluid data of our current setting choose option f from the main menu. In the following sub menu you can change the fluid properties as you desire. We here take the default values and go back tu the main menu with b. The global fluid properties can only be set in the xml file or in this menu. However, it is also possible to set individual fluid properties for all vessel via the vessel data csv files.... what to do? f sub menu: set global fluid properties [1] - set all [2] - set individual [b] - back to the main menu current fluid properties: rho 1050.0 kg m-3 my 1e-06 Pa s gamma 2.0 what to do? b
Add boundary conditions
Similar to vessel data, we can set the boundary condition directly via vnc or we can read in a boundary condition csv file. Here you can as well create a template by simply saving the boundary condition csv file of your network (also in submenu boundary conditions). Set Boundary condition with vnc To set the boundary conditions with vnc, press b in the main menu and 2 in the sub menu. There will be written what vessels need a boundary condition and which one have already one defined. Here we have to enter successively the ids of all our vessels 0, 1, 2.what to do? b sub menu: boundary conditions [1] - show boundary conditions [2] - add boundary condition [3] - del boundary condition [4] - load boundary conditions from CSV [5] - write boundary conditions to CSV [b] - back to the main menu what to do? 2 add boundary condition vessels with defined boundary condition: vessels with undefined boundary condition: 1 2 0 enter existing vessel id: 0After entering a vessel Id (here 0) a list of all available boundary conditions will show up. For vessel 0 we choose 6 for Flow-Sinus2 for vessels 1 and 2 we choose 6 for a Reflection coefficient
enter existing vessel id: 0 add boundary condition type: [ 0 ] Flow-Fourier [ 1 ] Flow-FromFile [ 2 ] Flow-PhysiologicalData [ 3 ] Flow-PhysiologicalFunction [ 4 ] Flow-RampMean [ 5 ] Flow-Sinus [ 6 ] Flow-Sinus2 [ 7 ] L-network [ 8 ] Pressure-RampMean [ 9 ] Pressure-Sinus [ 10 ] Pressure-Sinus2 [ 11 ] ReflectionCoefficient [ 12 ] ReflectionCoefficientTimeVarying [ 13 ] Resistance [ 14 ] VaryingElastanceHeart [ 15 ] Velocity-Gaussian [ 16 ] Windkessel-2Elements [ 17 ] Windkessel-3Elements choose type 6After inserting the type, the system is asking you for the values of the boundary variables. You can skip this procedure with b or enter the values directly (Note: the values are assumed to be SI units). For the reflection coefficient this looks like the following:
set values for the BC condition: ReflectionCoefficient
enter 'b' for the first value to skip this procedure
set value for Rt 0.0
Load boundary condition data from csv file Alternatively you could load your boundary condition from a csv file by choosing option b from the main menu and option 4 from the sub menu. Then simply enter the name of your boundary condition csv file.
sub menu: boundary conditions
[1] - show boundary conditions
[2] - add boundary condition
[3] - del boundary condition
[4] - load boundary conditions from CSV
[5] - write boundary conditions to CSV
[b] - back to the main menu
what to do? 4
load boundary conditions from CSV
current filename: None
enter/change filename (only! ENTER to use current filename):
Save your network to a network xml file
Now we are ready to save the created arterial network to an network xml file. Choose s in the main menu and then 1 for saving the network into a network xml file.what to do? s sub menu: save data [1] - write to XML [2] - write vessel data to CSV [3] - write vessel data and boundary conditions to CSV [4] - write graph to .png and .dot files [b] - back to the main menu what to do? 1 write to XML current filename: enter/change filename (only! ENTER to use current filename):