documentation.html

---
layout: main
title: Documentation
---

<h1>Documentation</h1>
<div class="description">
  <p>archTK documentation is composed by <a href="/tutorials.html" target="_blank" title="video Tutorials">archTk video tutorials</a>, <a href="/usecases.html" target="_blank" title="use cases">archTK usecases</a>, <a href="#pyNS_architecture">pyNS architecture</a>, <a href="#pyNS_how-to">pyNS how-to guidelines</a>, <a href="#pyNS_examples">pyNS development examples</a>, <a href="#regex">regex building for xml equations</a> and <a href="#archNE_documentation">"few words on archNE".</a></p>
</div>
<div class="button_container">
	<a class="button2" href="/tutorials.html" target="_blank" onclick="this.blur();"><span>Video Tutorials</span></a> 
	<a class="button2" href="/usecases.html" target="_blank" onclick="this.blur();"><span>Use Cases</span></a> 
</div>
  
<h2><a name="archNE_documentation">Few words on archNE</a></h2>
<div class="description_2">
<p><a href="https://github.com/archTk/arch-ne" target="_blank">The ARCH Network Editor (archNE)</a> aims at providing a GUI for the usage of <a href="https://github.com/archTk/pyNS" target="_blank">pyNS</a> and it  has been developed by <a href="http://www.orobix.com" title="www.orobix.com" target="_blank">Orobix</a> in the context of <a href="http://www.vph-arch.eu" target="_blank">EC FP7/2007-2013: ARCH, Project n. 224390.</a>
archNE uses the cross-platform user interface framework <a href="http://www.qt.nokia.com" target="_blank">Qt</a> and its architecture is based on the Model-View-Controller paradigm in order to allow an easy object-oriented programming (OOP). The OOP nature of the system allows it to be adapted to other 0D-1D solvers by simply changing one class of its: the IO class governing the exchange of data with the external solver.</p>
</div>  
  
<h2><a name="pyNS_architecture">pyNS architecture</a></h2>
<h3>Background</h3>

<div class="description_2">
<p>The python Network Solver (pyNS), is a software developed in Python with numpy package, needed for scientific computing with Python, with the aim to simulate hemodynamic behavior in vascular networks. pyNS is developed in the <a href="http://www.marionegri.it/mn/en/dipLab.html?dip=2" target="_blank">Department of Bioengineering</a>, at <a href="http://www.marionegri.it" target="_blank">Mario Negri Institute (MNI)</a> with support from the <a href="http://www.vph-arch.eu" target="_blank">EC FP7/2007-2013: ARCH, Project n. 224390.</a></p>
<p>In the contest of the Arch Project, the aim of the application is to simulate hemodynamic changes induced by AVF surgery and long-term vascular and cardiac adaptation and to predict AVF function for improvement of surgical planning and AVF management. Verification of model prediction of AVF maturation, patency, onset of steal syndrome and cardiac overload will be performed on the basis of prospective observational studies in HD patients.</p>
</div>

<h3>Product Perspective</h3>
<div class="description_2">
<div class="attachment_container">
	<a href="media/pyNS_overall.png" rel="lightbox" title="Major components of the overall system and subsystem interconnections."><img class="screenshot" width="150" src="media/pyNS_overall.png" alt="pyNS Architecture"/></a>
</div>
<p>pyNS has been designed with an object-oriented approach, which allows to abstracts the concept of element from the numerical solver itself.</p>
<p>All the components developed are open-source and pyNS can simply be installed and run on all platforms. It only needs <a href="http://www.python.org/download/" target="_blank" title="Python">Python(2.x)</a>, <a href="http://www.scipy.org/Download" target="_blank" title="Numpy package">numPy package</a> and <a href="http://www.scipy.org/Download" target="_blank" title="Scipy package">SciPy package</a>for Windows users</p>
<p>pyNS currently supports <a href="#elements">elements</a> with constant properties and with linear or nonlinear expressions. <a href="#evaluator">Evaluator class</a>, using <a href="#regex">regular expressions</a>, computes values from expressions setting them into elements.</p>
<p>The <a href="#input">input data</a> for the solver will be an XML file modeling the <a href="#vascular_network">vascular network</a> and an XML file with <a href="#parameters">simulation parameters</a> and <a href="#boundary_conditions">boundary conditions.</a> <a href="#patient_data">Patient specific data</a> can be easily imported using .csv files. <a href="#model_adaptor">Model Adaptor class</a> takes as input <a href="#patient_specific">patient specific information</a> (.csv) and creates specific vascular network model from generic one and specific input provided. <a href="#mesh_generation">The mesh generation process</a> creates elements from vascular network depending of maximum length parameter or maximum radius variation. User can decide which strategy to use.</p>
<p>pyNS will provide <a href="#numerical_solver">methods for numerical integration</a> and <a href="#non_linear_convergence">non linear convergence strategies.</a></p>
<p><a href="#post_processing">Post-processing</a> features allow to visualize hemodynamic information (flow, pressure, wall shear stress...) for each element of the network. Information could be in a numeric and/or graphic (.png format) way.</p>
</div>

<h3><a name="input">Input files</a></h3>
<div class="description_2">
<p>The input data for the solver is an XML file modeling the <a href="#vascular_network">vascular network</a> and an XML file with <a href="#parameters">simulation parameters</a> and <a href="#boundary_conditions">boundary conditions.</a></p>
</div>

<h4><a name="vascular_network">The vascular network</a></h4>
<div class="description_2">
<div class="attachment_container">
<img class="left_snippet" src="media/vascular_network.png" alt="Vascular network graph"/>
</div>
<p>The XML schema of the vascular network has been created by using named types. We chose to use <em>element</em> to express information in a structured form (if an element id directly derived from an other or to take into account the possibility of extending an element content to carry more information); otherwise, to provide additional information about an element, we use one or more <em>attributes</em>. We described the Vascular Network as a graph, composed by case, nodes, edges and superedges. These elements allow defining the network topology. The first element declared (root element) is called Network Graph. Case, nodes, edges and superedges are the leaf elements; each of this is identified with a unique ID. The parameters involved in the model are given with information about unit, accuracy and source of measurement.</p>
<p>Case element provides some general information about the dataset (subject Id and protocol visit).</p>
<p>Superedges element, identified by an integer <em>id</em> and a <em>name</em>, represents a group of edges or a group of other superedges. For example, superedge <em>arm</em> can be composed by <em>brachial artery</em>, <em>radial artery</em>... superedges. Each of them is a group of edges. Superedge can be very useful when user has to assign the same parameter (or boundary condition) to many edges of the network.</p>
</div>
<div class="description_2">
<p>
<div class="attachment_container">
<img class="left_snippet" src="media/nodes.png" alt="Edge elements"/>
</div>
<div class="attachment_container">
<img class="snippet" src="media/edges.png" alt="Edge elements"/>
</div>
Each node of the vascular network is identified by an unique <em>id</em> and can be classified with a <em>type</em> attribute and with a <em>name</em>. User can specify some properties related to each node, depending of its classification. For example, if a node is classified as <em>anastomosis</em>, properties are related to resistance expressions to model the pressure drop over this element. A node can be classified as <em>anastomosis</em>, <em>bifurcation</em>, <em>inflow</em>, <em>outflow</em> or <em>downstream network</em>.<br/>
Each edge of the vascular network is identified by an unique <em>id</em>, a <em>couple of nodes</em>, a <em>name</em> and a <em>side</em> attributes which represents if edge is belonging to arterial or venous side. User can decide to specify the type of the elements generated from this edge during the <a href="#mesh_generation">mesh generation</a> process. Each edge is composed by geometry, properties and features elements. Geometry is used for specifying characteristics such as the <em>length</em> of the edge or for providing its xyz <em>spatial coordinates</em>. An edge can have one or more properties related to its radius, distensibility, wall thickness, young's modulus, specific resistance and specific compliance. If specific information are available each property can be expressed as an array of values in several locations; each value is identified by a curvilinear abscissa <em>s</em>, which can assume values from 0 to 1. <br />
It is possible to have physiological or pathological <em>features</em> (e.g., kink, stenosis, other...). Each of these conditions is identified by a curvilinear abscissa <em>s</em> and by a parameter of interest (e.g., radius and curvature for kink, radius and length for stenosis).
</p>
</div>

<h4><a name="boundary_conditions">Boundary Conditions</a></h4>
<div class="description_2">
<div class="attachment_container">
<img class="snippet" src="media/boundary_conditions.png" alt="Boundary conditions graph"/>
</div>
<p>The boundary conditions model is described as a graph, composed by different types of boundary conditions. Each boundary condition is identified by an integer <em>id</em>, a <em>type</em> and a <em>name</em>.  Each type of boundary condition is specified with its own characteristically parameters and entities associated to it. Each entity represents a group of meshes with the same type of boundary condition and is identified with a unique <em>id</em> which is related to <a href="#vascular_network">vascular network superedge's name</a> and, if needed, also with a <em>node id</em> related to <a href="#vascular_network">vascular network nodes.</a><br />
Characteristically parameters can be related to prescribed external pressures (e.g. element's transmural pressures), inflow's parameters or outflow prescribed pressures. Transmural pressure can be expressed with scalar value or in an array form. If expressed in array form, transmural pressure is time-related; so each pressure is associated with its specific time value.</p>
</div>

<h4><a name="parameters">Simulation parameters</a> and <a name="patient_data">patient data</a></h4>
<div class="description_2">
<div class="attachment_container">
<img class="medium_snippet" src="media/specific_dataset.png" alt="Patient data and parameters"/>
</div>
<p>Simulation parameters and patient data provide additional information for patient-specific <a href="#simulation">simulation.</a> </p>
<p>Simulation parameters graph is composed by a list of variables and each of them is expressed with a scalar value. By default, <em>blood density</em> (1050 kg/m<small><sup>3</small></sup>), <em>poisson ratio</em> (0.5), <em>timestep</em> (0.001 s) and <em>total number of simulation cycles</em> (10) are defined.</p>
<p>Patient data graph contains a sequence of patient personal data. Each element can be expressed by a scalar value or with an <a href="#regex">expression</a> which will be <a href="#evaluator">evaluated</a> by pyNS. User can provide patient-specific information about date of birth, date of surgery, age, gender, arm (left or right), fistula type, height (cm) and weight (kg), systolic and diastolic pressures (mmHg), mean value of cardiac output (mL/min), cardiac period (s), information about brachial, radial and ulnar mean flows (mL/min) from US measurements, blood analysis data (plasma protein concentration (cp, g/dL) and hematocrit (ht, %)), blood viscosity (Pa*s) and information about pathological problems such as diabetes (yes/no) and hypertension (yes/no).</p>
</div>

<h3><a name="generic_network">From a generic network template</a> to a <a name="patient_specific">patient-specific network</a></h3>
<div class="description_2">
<div class="attachment_container">
	<a href="media/csv.png" rel="lightbox" title="Example of csv file for patient specific customization"><img class="small_left_screenshot" width="150" src="media/csv.png" alt="Example of csv file for patient specific customization"/></a>
</div>
<div class="attachment_container">
	<a href="media/pat_spec.png" rel="lightbox" title="Patient specific customization workflow"><img class="screenshot" width="150" src="media/pat_spec.png" alt="Patient specific customization workflow"/></a>
</div>
<p>pyNS allows to generate a patient-specific network from some default generic templates, giving user the possibility to specify only some basic patient information. Vascular network geometry and properties, boundary conditions and simulation parameters are computed according to <a href="#regex">generic rules defined as expressions</a> in generic templates xml files.</p>
<p>This process can be executed either by <a href="#">archNE customization</a> or pyNS. To run customization from pyNS user has to pass a .csv file with a list of parameters and their values to <a name="model_adaptor">ModelAdaptor class</a>.</p>
<p>The primary functional responsibility of this class is to calculate parameters from <a href="#regex">expressions</a> (using <a href="#evaluator">evaluator class</a>) and to write the new <a href="#vascular_network">vascular network xml file.</a></p>
<p>A short how-to for building a patient-specific .csv file can be found in the <a href="#csv_file">pyNS how-to section</a>.</p>
</div>

<h3><a name="evaluator">Evaluator class</a></h3>
<div class="description_2">
<p>This class evaluates xml equations using <a href="#regex">regular expressions.</a></p>
<p>Evaluator class is structured for evaluating equations related to both edges of the vascular network graph and mesh elements. Moreover, an effective caching strategy was developed to save overall computational time.</p>
<p>A short how-to for building a xml equations using regular expressions can be found in the <a href="#regex">regular expression for xml equations section</a>.</p>

</div>

<h3><a name="elements">Elements class</a></h3>
<div class="description_2">
<p>Elements module is a collection of different kind of elements. Each element of the network has common characteristics, although they can be very different from each other.</p> 
<p>The element defined in the Elements class represents a general element and each specific element must be referred to it. This class provides methods for building its zero order matrix, first order matrix and second order matrix; this is a general strategy adopted for all kind of elements.</p> 
<p>Each kind of element represents a mathematical model which is implemented for the scope of modeling and studying pressure, volumetric flow rate and wall-shear stress distribution over the complete vascular system or a specific part of it.</p>
<p>A short how-to for implementing a new element into pyNS can be found in the <a href="#new_elements">pyNS example section</a>.</p>
</div>

<h4><a name="wave_propagation">Wave propagation element</a></h4>
<div class="description_2">
<div class="attachment_container">
	<a href="media/wp_el.png" rel="lightbox" title="Wave propagation element"><img class="snippet" width="150" src="media/wp_el.png" alt="Wave propagation element"/></a>
</div>
<p>This element has been implemented with a discretized 1D pulse wave propagation model (5 degrees of freedom) as illustrated in <em>Huberts W. et al., A pulse wave propagation model to support decision-making in vascular access planning in the clinic. Med Eng and Physics, (2011)</em>.</p> 
<div class="attachment_container">
	<a href="media/wp_el_eq1.png" rel="lightbox" title="Resistance and inductance equations"><img class="left_snippet" width="150" src="media/wp_el_eq1.png" alt="Resistance and inductance equations"/></a>
</div>
<p>The relations between pressure and volumetric flow rate for each vascular segment are derived from conservation of mass and momentum by assuming fully-developed incompressible Newtonian volumetric flow rate in a straight vessel. In the momentum equation the convection term, the axial diffusion term and the effect of body forces are neglected. The lumped parameter model obtained consists of a resistor per unit length R (representing the resistance to volumetric flow rate through the vessel) and an inductor per unit length L (representing the inertia of the blood) in series. Both R and L also depend on Womersley number.</p>
<p>To incorporate the storage capacity of the vessel in the model, a capacitor C is added to each side of the vascular segment, representing half of the total vascular compliance over that segment. It is assumed that the artery is a thick-walled linear elastic tube.</p>
<div class="attachment_container">
	<a href="media/wp_el_eq2.png" rel="lightbox" title="Arterial compliance equation"><img class="left_snippet" width="150" src="media/wp_el_eq2.png" alt="Arterial compliance equation"/></a>
</div>
<p>Veins diameter(D) and compliance(C) are defined as functions of pressure p in which <em>D<sub>0</sub></em> is the diameter of the vein measured in correspondence of the mean pressure[Pa].</p>
<div class="attachment_container">
	<a href="media/wp_el_eq3.png" rel="lightbox" title="Venous diameter and compliance equations"><img class="snippet" width="150" src="media/wp_el_eq3.png" alt="Venous diameter and compliance equations"/></a>
</div>
<p>The leakage <em>R<sub>L</sub></em> is captured by adding linear resistances (representing resistance to volumetric flow rate through small side-branches) in parallel to the capacitors. In addition, extravascular pressures Pe are prescribed as a boundary condition parameter. The total resistance, total inertance and total compliance are obtained by integrating R, L and C over the segment length.</p>
</div>

<h4><a name="resistance">Resistance element</a></h4>
<div class="description_2">
<div class="attachment_container">
	<a href="media/r_el.png" rel="lightbox" title="Resistance element"><img class="snippet" width="150" src="media/r_el.png" alt="Resistance element"/></a>
</div>
<p>This element is a very simple 0D model realized with a resistance, which can be linear or not, between two nodes.</p>
<p>Resistor <em>R</em> can be implemented as a variable resistance and its law will be described in the vascular network xml file according to the <a href="#regex">regular expression</a> structure for pyNS. User can decide to mesh each edge with this model simply assigning to the edge's <em>type</em> attribute the value <em>"Resistance"</em>.</p>
</div>

<h4><a name="anastomosis">Anastomosis element</a></h4>
<div class="description_2">
<div class="attachment_container">
	<a href="media/an_el.png" rel="lightbox" title="Anastomosis element"><img class="snippet" width="150" src="media/an_el.png" alt="Anastomosis element"/></a>
</div>
<p>This element is a 0D model realized with 2 resistor between 3 nodes.</p>
<p>Anastomosis cannot be modeled by linear segments because the radial velocity component is no longer infinitesimally small compared to the axial velocity and flow separation can occur in this region. The velocity profile can thus not be based on fully developed flow in straight vessels. Consequently, a special element named Anastomosis, used as connection between an artery and a vein, is created to model the pressure losses over it.</p>
<p>In order to evaluate the non-linear resistance associated to each anastomosis configuration, the pressure drop across the computational domain must be accurately evaluated by means of CFD computations. We model blood as a Newtonian fluid with constant properties so that the flow across the anastomosis is approximated numerically solving the incompressible Navier-Stokes equations. The simulations are performed with <a href="https://github.com/lorbot/Gnuid" target="_blank">the opensource hemodynamics solver Gnuid</a> while <a href="http://www.vmtk.org/vmtk" target="_blank">vmtk</a> has been used for the generation of the vessels surfaces defining the anastomosis model.</p>
<div class="attachment_container">
	<a href="media/3dmesh.png" rel="lightbox" title="Hybrid mesh of the parameterized anastomosis obtained with vmtk"><img class="screenshot" width="150" src="media/3dmesh.png" alt="Hybrid mesh of the parameterized anastomosis obtained with vmtk"/></a>
</div>
<p>The Gnuid solver is based on a fully implicit implementation of the well known Pressure-Correction scheme introduced by Guermond and Quartapelle (<em>Guermond JL et al., On stability and convergence of projection methods based on pressure poisson equation. Int. J. Num. Meth. Fluids, 26:1039-1053 (1998).</em>) and used a discontinuous approximation for the velocity unknown and a continuous approximation for the pressure. The ability to combine a discontinuous Galerkin (dG) and a continuous Galerkin (cG) discretization in a dG-cG velocity-pressure space couple provides some interesting properties. It yields inherently inf-sup stable equal-order velocity-pressure discretizations, the better behaviour of discontinuous approximations in convection-dominated regimes is exploited in the advection-diffusion step and the cG formulation limits the cost of the Laplacian operator associated to the projection step.</p>
<div class="attachment_container">
	<a href="media/3dsim.png" rel="lightbox" title="CFD results on end-to-side anastomoses models"><img class="screenshot" width="150" src="media/3dsim.png" alt="CFD results on end-to-side anastomoses models"/></a>
</div>
<p>To ensure stability at high-Reynolds numbers and reduce the amount of artificial diffusion, the convective term is discretized following Di Pietro and Ern (<em>D. A. Di Pietro et al., Discrete functional analysis tools for discontinuous Galerkin methods with application to the incompressible Navier-Stokes equations. Math. Comp. 79, 1303-1330 (2010).</em>), where a non-dissipative formulation has been proposed.</p>
<div class="attachment_container">
	<a href="media/Pdrop.png" rel="lightbox" title="Pressure drop equation for anastomosis element"><img class="left_snippet" width="150" src="media/Pdrop.png" alt="Pressure drop equation for anastomosis element"/></a>
</div>
<p>The discretization has been validated against a large set of classical two- and three-dimensional tests covering a wide range of Reynolds numbers and has proved effective for the simulation of convection-dominated flows both from the accuracy and the computational cost viewpoints (<em>L. Botti et al., A pressure-correction scheme for convection-dominated incompressible flows with discontinuous velocity and continuous pressure. J. Comput. Phys., 230 (2011).</em>).</p>
</div>

<h4><a name="windkessel">Windkessel element</a></h4>
<div class="description_2">
<div class="attachment_container">
	<a href="media/wk_el.png" rel="lightbox" title="Windkessel element"><img class="snippet" src="media/wk_el.png" alt="Windkessel element"/></a>
</div>
<p>This element has been implemented with a 0D three-element Windkessel model, as illustrated in <em>Westerhof N. et al., An artificial arterial system for pumping hearts. J. Appl Phys (1971).</em>, consisting of a characteristic impedance, <em>Z<sub>wk</sub></em>, a resistance, <em>R<sub>wk</sub></em> and a compliance, <em>C<sub>wk</sub></em>. The characteristic impedance is chosen such that the reflections from high frequencies are attenuated. Standard reference pressure <em>P<sub>v</sub></em> and extravascular pressure <em>P<sub>e</sub></em> are prescribed as <a href="#boundary_conditions">boundary condition parameters.</a> Total resistance <em>R<sub>p</sub></em> (<em>Z<sub>wk</sub>+R<sub>wk</sub></em>) is defined as <em>P/(k*Q)</em> with <em>k</em> the fraction of the cardiac output flowing though the peripheral bed, <em>p</em> the mean arterial pressure and <em>q</em> the cardiac output. The pressure wave decreases during diastole with a time constant, that is equal to <em>R<sub>wk</sub>*C<sub>wk</sub></em>, which can be obtained from the descending slope of the local pressure curve during diastole or can be estimated based on literature.</p>
</div> 

<h3><a name="mesh_generation">Mesh generation</a></h3>
<div class="description_2">
<p>The mesh generation process is handled by Mesh Generator class which provides two different type of meshing strategies. The first method, called maxLenghtMeshing, creates meshes from edges taking into account the maximum length parameter decided by the user. Default value is 5 cm. If edge's length is greater than the maximum length parameter, mesh generator creates a number of meshes, each of them with the same length, corresponding to the integer value of the ratio between edge's length and maximum length parameter.</p>
<p>The second method, called toleranceMeshing, creates meshes from edges taking into account the radius tolerance parameter decided by the user. Default value is 33%. If edge's radius along the curvilinear abscissa increases more than tolerance, a new mesh is created.</p>
<p>During mesh generation process pyNS creates entities from superedges and builds the corresponding network Mesh object from its network Graph. This class can write vascular network mesh in a specific xml file which can be <a href="#load_mesh">imported into archNE.</a></p>
</div> 

<h3><a name="dofmap">From a local to a global environment</a></h3>
<div class="description_2">
<div class="attachment_container">
	<a href="media/dofmap.png" rel="lightbox" title="From a local to a global environment"><img class="screenshot" width="150" src="media/dofmap.png" alt="From a local to a global environment"/></a>
</div>
<p>Each element of the network builds three local matrices by applying an analogue of Kirchoff’s current law to satisfy element-to-element mass conservation: a zero order matrix(M0), a first order matrix(M1) and a second order matrix(M2) containing reciprocal in- ertances, reciprocal resistances and compliances respectively. Each one is a square matrix of order corresponding to the total number of element’s degrees of freedom in which qe is a column vector containing nonzero values at the nodes where the flow is prescribed, pe is a column vector containing the global node pressure values.</p>
<div class="attachment_container">
	<a href="media/local_M_eq.png" rel="lightbox" title="Set of differential equations"><img class="snippet" width="150" src="media/local_M_eq.png" alt="Set of differential equations"/></a>
</div>
<p>A class, named dofmap, maps each local degree of freedom into a global degree of freedom, handling connectivity between elements of the network. Dofmap is used by <a href="#assembler">Assembler class</a> to assembling global matrix from element's local matrices.</p>
</div>

<h3><a name="numerical_solver">The numerical solver</a></h3>
<div class="description_2">
<div class="attachment_container">
  <a href="media/numerical_scheme.png" rel="lightbox" title="Numerical scheme"><img class="snippet" src="media/numerical_scheme.png" alt="Numerical scheme"/></a>
</div>
<p>Solver class provides methods for solving the set of differential equations obtained by applying an analogue of Kirchoff's current law to satisfy element-to-element mass conservation.</p>
<div class="attachment_container">
	<a href="media/solver_eq.png" rel="lightbox" title="Numerical scheme"><img class="left_snippet" width="150" src="media/solver_eq.png" alt="Numerical scheme"/></a>
</div>
<p>The time derivative and time integral in the set of the differential equations are approximated by using an implicit trapezium rule with initial conditions (q<sub>0</sub>=0 and p<sub>0</sub>=0). The final scheme is shown in the figures.</p> 
<p>To solve, an iterative procedure is used. User can set timestep value and the total number of simulation cycles into <a href="#parameters">simulation parameters file.</a></p>
</div>

<h4><a name="assembler">Assembler class</a></h4>
<div class="description_2">
<p>Assembler class, using local to global map of degrees of freedom (dofmap) provided by dofmap class, builds three global matrices <em>M<sub>G</sub></em> (zero, first and second order) joining into one square matrix of order corresponding to the number of global degrees of freedom all local matrices <em>M<sub>el</sub></em> of the same type.</p>
<div class="attachment_container">
	<a href="media/ass_eq.png" rel="lightbox" title="From local to global matrices"><img class="snippet" width="150" src="media/ass_eq.png" alt="From local to global matrices"/></a>
</div>
<p>Moreover assembler class stores a copy of linear global matrices built excluding local matrices of non linear elements, for improving performances during non linear simulations. This architecture permits to avoid the complete reassembling of global matrices in case of non linearities and to stay focused only on a section of global matrices corresponding to the non linearity.</p>
</div>

<h4><a name="non_linear_convergence">Non-linear convergence strategy</a></h4>
<div class="description_2">
<p>A non-linear convergence strategy has been implemented for solving system with non-linear characteristics. Solver class introduces an inertia relax coefficient (0.9) for improving convergence performances. Solution is thus considered as the sum between the 90% of the current solution <em(p)</em> and the 10% of the solution at the previous non-linear incremental step <em>(p<sub>i</sub>)</em>. If the non linear error<em>(nlerr)</em>, described as the ratio between the infinite norm of <em>p − p<sub>i</sub></em> and the infinite norm of <em>p<sub>i</sub></em>, is larger than a predefined convergence tolerance <em>nltol</em>, the next non-linear incremental step is executed.</p> 
<div class="attachment_container">
	<a href="media/nl_eq.png" rel="lightbox" title="Non linear convergence strategy"><img class="left_snippet" width="150" src="media/nl_eq.png" alt="Non linear convergence strategy"/></a>
</div>
<p>Before executing the next non-linear incremental step pyNS has to evaluate non-linear elements and updating the system matrix. Assembler class stores a copy of linear global matrices built excluding local matrices of non linear elements, for improving performances during non linear simulations. This architecture permits to avoid the complete reassembling of global matrices in case of non linearities and to stay focused only on a section of global matrices corresponding to the non linearity.</p>
</div>

<h3><a name="post_processing">Post processing features</a></h3>
<div class="description_2">
<p>Network Solution class elaborates results for post-processing providing a family of methods related to volumetric flow rate, reynolds number, vascular pressure, wall shear stress and pulse wave velocity. pyNS is able to provide information for each global degree of freedom of the vascular network. Moreover, this class allows to write hemodynamic information in a specific xml file which can be <a href="#">imported</a> in archNE.</p>
<p>Post processed results can be visualized in a browser (Firefox, Chrome, Safari and Opera) without installing any additional library. pyNS simply provides information about pressure, volumetric flow rate, wall shear stress and reynolds number for each mesh. In case of vascular adaptation simulations, user can visualize results for each adaptation step.</p>
<p>As example, a vascular network representing a radio-cephalic end-to-side fistula in a right arm with vascular adaptation (40 days from surgery) has been simulated and <a href="/results/post_processing.html" target="_blank">post processed results are available here<a/>.
</div>

<h4><a name="post_processing_plots">Graphical plots</a></h4>
<div class="description_2">
<div class="attachment_container">
  <a href="media/flow.png" rel="lightbox" title="Example of volumetric flow rate signal"><img class="screenshot" width="150px" src="media/flow.png" alt="Example of volumetric flow rate signal"/></a>
</div>
<p>Thanks to <a href="http://matplotlib.sourceforge.net/" target="_blank" title="Matplotlib library">Matplotlib library</a>, a python 2D plotting library which produces publication quality figures in a variety of hardcopy formats and interactive environments across platforms, this class can elaborate solutions in a graphical form.</p>
<p>A short how-to for handling graphical features of post processing class can be found in the <a href="#post_processing_guidelines">pyNS how-to section</a>.</p>
</div>

<h4><a name="post_processing_txt">Writing results in a text file</a></h4>
<div class="description_2">
<p>Network Solution class provides methods for writing volumetric flow rate, reynolds number, pressure, wall shear stress and pulse wave velocity time-signals for each mesh in specific text files.</p>
<p>A short how-to for handling basic features of post processing class can be found in the <a href="#post_processing_guidelines">pyNS how-to section</a>.</p>
</div>

<h4><a name="inverse_womersley">The inverse womersley method for computing wall shear stress</a></h4>
<div class="description_2">
<div class="attachment_container">
  <a href="media/wss.png" rel="lightbox" title="Example of wall shear stress signal computed with the inverse womersley method"><img class="screenshot" width="150px" src="media/wss.png" alt="Example of wall shear stress signal computed with the inverse womersley method"/></a>
</div>
<p>The Inverse Womersley class implements the method described in <em>Cezeaux J.L. et al., Accuracy of the inverse Womersley method for the calculation of hemodynamic variables. Annals of biomedical engineering, 25:536-546 (1997)</em> for the accurate determination of wall shear stress.</p>
<div class="attachment_container">
	<a href="media/wom_eq.png" rel="lightbox" title="Inverse womersley method equations"><img class="left_snippet" width="150" src="media/wom_eq.png" alt="Inverse womersley method equations"/></a>
</div>
<p>The fluid mechanics of the arterial system can have a direct effect on the physiology of the blood vessel wall. The accurate determination of arterial wall shear stress, however, is problematic. Calculations of wall shear stress from measured velocity profiles remain inaccurate due to the failure of these methods to resolve the velocity in the thin shear layer near the arterial wall. This difficulty has led investigators to the calculation of wall shear stress from other hemodynamic variables that can be more accurately and easily measured. One such calculation involves the inverse Womersley method that uses either the volumetric flow rate or centerline velocity to determine the wall shear stress.</p>
<p>This module allows to plot velocity profiles into image files (.png format) and makes a movie (.avi format) from images set. The related movie represents the blood velocity profile during a cardiac cycle along the fractional radius of the selected vessel. MEncoder, a free command line video decoding, encoding and filtering tool released under the GNU General Public License, is required for using this feature.</p>
</div>

<h2><a name="pyNS_how-to">pyNS how-to</a></h2>
<div class="description_2">
<div class="attachment_container">
  <a href="media/command_line.png" rel="lightbox" title="List of command line arguments for Main.py"><img class="big_snippet" src="media/command_line.png" alt="List of command line arguments for Main.py"/></a>
</div>
<p><br />In this section is shortly explained how to setup and run a simulation using pyNS. In this figure is displayed a list of some command line arguments allowed for the pyNS.py file. Running pyNS.py -h or pyNS.py --help a brief explanation of implemented command line arguments is displayed.</p>
</div>
<h3><a name="pyNS_how-to">Setting input files and meshing elements</a></h3>
<div class="description_2">
<div class="attachment_container">
  <a href="media/csv_guideline.png" rel="lightbox" title="Example of csv files for additional patient-specific data"><img class="snippet" src="media/csv_guideline.png" alt="Example of csv files for additional patient-specific data"/></a>
</div>
<p>User has first to choice between a generic template network or a specific network.</p>
<p>In case of generic template simulation, user has now the possibility to <a name="csv_file">specify additional patient-specific</a> geometry data (length and radius of vessels) and parameters (gender, date of birth, date of simulation, height, weight, systolic and diastolic pressures, cardiac period, hematocrit, protein plasma concentration...) using two different csv files (comma separated value). Some parameters has to be expressed in a standardized way: <em>gender</em> can be 0 (female) or 1 (male); <em>arm</em> can be 0 (left) or 1 (right	); <em>ftype</em> parameter, representing the fistula type, can be 0 (lower radio-cephalic end-to-end), 1 (lower radio-cephalic end-to-side), 2 (lower radio-cephalic side-to-side), 3 (upper brachio-cephalic end-to-side), 4 (upper brachio-cephalic side-to-side), 5 (upper brachio-basilic end-to-side), 6 (upper brachio-basilic side-to-side) or 7 (Pre-surgery, no fistula); <em>hyp</em> (hypertension pathology) and <em>diab</em> (diabetes) can be 0 (not present) or 1 (present).</p>
<p>User can choose from <a href="#mesh_generation">two different types of meshing</a>, MaxLenghtMeshing and ToleranceMeshing. MaxLenghtMeshing simply checks vessel edge's length and if it's greater than a user-defined length, a new mesh is created. (Default value is 5 centimeters). ToleranceMeshing checks vessel edge's radius variation along curvilinear abscissa. If radius increases more than a tolerance value (%), a new mesh is created. (Default value is 33%).
<em>Example:
meshGenerator.SetMaxLength(5.0e-2) or meshGenerator.SetTolerance(33)</em></p>
</div>

<h3><a name="post_processing_guidelines">Post-processing guidelines</a></h3>
<div class="description_2">
<p>User can choose a textual and/or graphical representation of solutions. pyNS provides information about pressures, volumetric flow rates, reynolds numbers, pulse wave velocities and wall shear stresses along all network.</p>
</div>

<h4>General information</h4>
<div class="description_2">
<p>PlotBrachial, PlotRadial and PlotCephalic methods plot pressure, flow and wall shear stress signals into the same picture for a quickly view. WriteToXML method writes xml vascular output file which provides information about solutions in vascular network format. GetSolution method takes as input a superedge and plots pressure, flow and wall shear stress signals into the same picture for a quickly view. PulseWaveVelocity method takes as input one or two superedges and plot pulse wave velocity signal.</p>
</div>

<h4>Specific volumetric flow rate information</h4>
<div class="description_2">
<p>GetInflow method plots inflow cardiac function specified in boundary conditions XML file. PlotFlow method takes as input a single mesh and plots mean flow signal over it. PlotFlowComparative method plots brachial, radial and ulnar flow signals into the same picture for a quickly view. WriteFlowOutput method takes as input a single mesh and writes in a txt file flow signal over it. Additional methods related to Reynolds number computation have been implemented taking as input a single mesh and plottin reynolds number values over it.</p>
</div>

<h4>Specific pressure information</h4>
<div class="description_2">
<p>PlotPressure method takes as input a single mesh and plots mean pressure signal over it. PlotPressureTwo method takes as input a couple of mesh and plots mean pressure signals over them into the same picture for a quickly comparison. PlotPressureComparative method plots brachial, radial and ulnar pressure signals into the same picture for a quickly view. PlotPressureDrop method takes as input a single mesh and plots pressure drop signal over it. WritePressureInput and WritePressureOutput methods take as input a single mesh and write in a txt file pressure signal (respectively input or output) over it.</p>
</div>

<h4>Specific wall shear stress information</h4>
<div class="description_2">
<p>PlotPWSS method takes as input a single mesh and plots Poiseuille wall shear stress signal over it. PlotPWSSComparative method plots brachial, radial and ulnar Poiseuille wall shear stress signals into the same picture for a quickly view. PlotWSS takes as input a single mesh and plots Womersley wall shear stress signal over it. WriteWSSOutput method takes as input a single mesh and writes in a txt file Womersley wall shear stress signal over it.</p>
</div>

<h4>Other information</h4>
<div class="description_2">
<p>pyNS provides information about Reynolds number, pulse wave velocity and velocity profile over the fractional radius.</p>
<p>WriteReynolds method takes as input a single mesh and writes reynolds number signal in a txt file while PlotReynolds plots the signal.</p>
<p>PulseWaveVelocity method takes as input one or two superedges and computes the pulse wave velocity(m/s) along a superedge or from the first to the last superedge.</p>
<p>ShowVelocityProfile takes as input a single mesh and show a movie(.avi) with the velocity profile over the fractional radius while SaveVelocityProfile saves the movie in a subfolder.</p>
</div>

<h2><a name="pyNS_examples">pyNS examples</a></h2>

<h3><a name="new_elements">Adding a new element into pyNS</a></h3>
<div class="description_2">
<div class="attachment_container">
  <a href="media/LowPassFilter_init.png" rel="lightbox" title="LowPassFilter Class, constructor"><img class="snippet" src="media/LowPassFilter_init.png" alt="LowPassFilter Class, constructor"/></a>
</div>
<p>pyNS has been designed with an object-oriented approach, which allows to abstracts the concept of element from the numerical solver itself. This approach makes it very easy to add a new element into pyNS.</p>
<div class="attachment_container">
  <a href="media/LowPassFilter_input.png" rel="lightbox" title="LowPassFilter Class, InputParameters method"><img class="left_snippet" src="media/LowPassFilter_input.png" alt="LowPassFilter Class, InputParameters method"/></a>
</div>
<p><strong>First Step: creating the new element class.</strong> In this example we will implement a new element representing a low-pass filter, called "LowPassFilterElement". This element is composed by a resistor in series with a load and a capacitor in parallel with the load. Constructor method has to define common element characteristics such as id, its nodes, its name, local degrees of freedom and element parameters. Parameters can be described by a scalar value or with an <a href="#regex">equation</a>, thus making the element <a href="#nonLinear_element">non-linear</a>. InputParameters method, after calling method from the superclass, has to check if its parameters are expressed with an <a href="#regex">equation</a> or not. If any parameter is in a non-linear form, inputParameters method has to call <a href="#evaluator">evaluator class</a> for evaluating the <a href="#regex">equation</a>. </p> 
<p> Don't forget to define Set methods for resistance and compliance parameters.</p> 
<div class="attachment_container">
  <a href="media/LowPassFilter_circuit.png" rel="lightbox" title="LowPassFilter Class, Element internal circuit definition"><img class="snippet" src="media/LowPassFilter_circuit.png" alt="LowPassFilter Class, Element internal circuit definition"/></a>
</div>
<p>Last but not least, we have to define a method called GetCircuitMatrix for building electrical circuit design,a method for setting prescibed pressures and a set of methods for managing local degrees of freedom and element's nodes. Each row of the circuit matrix is an edge and each column is a variable (Node1, Node2, R, C, L). The prescribed pressure is located after the capacitor, and a method called GetExternalPressureLocalDofs has to set prescribed pressure in the correct local degree of freedom.</p>
<p>The complete code for this example is available <a href="examples/lowPassFilter.py" target="_parent" title="lowPassFilterElement">here.</a></p>
<p><strong>Second Step: add the register Element statement to support this new element.</strong> Element class has to create LowPassFilterElement if edge meshType variable is specified as LowPass Filter. Add this line at the end of the LowPassFilterElement class, as shown in the picture.</p>
<div class="attachment_container">
  <a href="media/LowPassFilter_parent.png" rel="lightbox" title="LowPassFilter Class, adding the register element statement"><img class="snippet" src="media/LowPassFilter_parent.png" alt="LowPassFilter Class, adding the register element statement"/></a>
</div>
<em><xmp>RegisterElementType("LowPassFilter",LowPassFilterElement)</xmp></em>
</div>

<h3><a name="nonLinear_element">Building a non-linear element</a></h3>
<div class="description_2">
<p>An element is non-linear if at least one of its parameters is expressed with a <a href="#regex">regex equation.</a> Element class sets nonLinear variable to True if a non-linear parameter is present. User has to define into inputParameters method possibility to specify parameters both with a linear and a non-linear way. For example:</p>
<p><em>if type(self.Resistance) is not str: self.R = self.Resistance</p>
<p>else: evaluator.evaluate(self.Resistance)</em></p>
<p>User has to define also a method for setting the non-linear parameter. Evaluator class will call this method for setting value into element after evaluating the expression. For example:</p>
<p><em>def SetResistance(self, resistance, info=none):</p>
<p>self.R = resistance</p></em>
</div>

<h2><a name="regex">Regular expression for xml equations</a></h2>
<div class="description_2">
<p>In computing, a regular expression, also referred to as regex or regexp, provides a concise and flexible means for matching strings of text, such as particular characters, words, or patterns of characters. A regular expression is written in a formal language that can be interpreted by a regular expression processor (pyNS uses the <a href="#evaluator">Evaluator class</a>), a program that either serves as a parser generator or examines text and identifies parts that match the provided specification.</p>
</div>
<h3>Syntax</h3>
<div class="description_2">
<p>Any xml equation has to be expressed with this structure: a property of an edge or an element = mathematical expression.</p>
<p>For specifying an element: the edge name, which the element is belonging to, has to be enclosed in square brackets. Additional information about curvilinear abscissa (the position of the element inside its edge) can be provided, otherwise default value is 0.0. This type of expressions is evaluated everytime the element is initialized.</p>
<p>For specifying an edge: its name has to be enclosed in curly brackets. Additional information about curvilinear abscissa (which permits to assign the computed value in the exact location along the edge) can be provided, otherwise default value is 0.0. This type of expressions is evaluated only during <a href="#model_adaptor">model adaptor</a> phase and it's used for a <a href="#patient_specific">patient-specific</a> adaption from a <a href="#generic_network">generic template.</a></p>
<p>Every variable has to be expressed with a prefix tag, <em>$</em> and has to be assigned to an edge or an element. If variable refers to a costant <a href="#parameters">parameter</a> defined in the <a href="#boundary_conditions">boundary conditions xml file</a>, variable has to be followed by empty square brackets.</p>
<p>Any xml equation must be included in xml file between xml expression tag.</p>
</div>

<h4>Building a regex equation for model adaptor</h4>
<div class="description_2">
<p>The structure for building an xml equation for model adaptor is very simple.</p>
<p><xmp><length unit="m" accuracy="10%" source="US">
  <expression>$Length{radial_prox} = (0.09855*$height[])*1e-2</expression>
</length></xmp></p>
<p>In this example we assign to the length property of the radial_prox edge the computed value resulting from the product between a numerical costant and a parameter defined in the boundary conditions file (patient height).</p>
<p><xmp><radius_array unit="m" accuracy="10%" source="US">
  <value s = "0.0">
    <expression>$Radius{radial_prox,0.0} = 1.03*$Radius{radial_prox,1.0}</expression>
  </value>
  <value s = "1.0">
    <expression>$Radius{radial_prox,1.0} = 0.55*$Radius{brachial_dist,1.0}</expression>
  </value>
</radius_array></xmp></p>
<p>In this example we assign to the radius array property of the radial_prox edge the computed value resulting from the product between a numerical costant and a property value of corresponding edge. In this example, abscissa value is indicated for assigning computed value in the corresponding <em>s</em> position along the edge.</p>
</div>

<h4>Building a regex equation for element properties and non-linearities features.</h4>
<div class="description_2">
<p>The structure for building an xml equation for element properties and non-linearities features is similar to previous one. The main diffence consists to enclosing edge name between  square brackets [] instead of curly brackets {}.</p>
<p><xmp><windkessel>
  <expression>$WindkesselRel[wk_left_carotid] = (($mean_pressure[])/(0.07*$cardiac_output[]))
  *(133.3223684211*6.0e7)</expression>
</windkessel></xmp></p>
<p>In this example we assign to the WindkesselRel property of the wk_left_carotid element the computed value resulting from the right hand-side expression. This resistance is described as the ratio between arterial mean pressure and the /% of the cardiac output. Numerical costant are used for unit conversion.</p>
<p><xmp><radius_array unit="m" accuracy="10%" source="US">
  <value s = "0.0">
    <scalar>1.32e-3</scalar>
    <expression>$Radius[basilic_vein]=$RadiusAtRest[basilic_vein]*sqrt((1.0-0.55*
    (1.0-($Pressure[basilic_vein]/(1066.66+$Pressure[basilic_vein])))))</expression>
  </value>
  <value s = "1.0">
    <scalar>1.8e-3</scalar>
    <expression>$Radius[basilic_vein]=$RadiusAtRest[basilic_vein]*sqrt((1.0-0.55*
    (1.0-($Pressure[basilic_vein]/(1066.66+$Pressure[basilic_vein])))))</expression>
  </value>
</radius_array></xmp></p>
<p>In this example we assign to the Radius property of the basilic vein elements the computed value resulting from the right hand-side expression. This property is non-linear because it depend on pressure value. Each timestep this expression is evaluated using as input the pressure value computed in the previous timestep. RadiusAtRest variable represent the scalar value of the radius measured with the tourniquet, which is indicated between scalar tags.</p>
</div>

<div class="pre_footer"></div>