-
Notifications
You must be signed in to change notification settings - Fork 11
/
docsGenBC.html
528 lines (396 loc) · 38.7 KB
/
docsGenBC.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="description" content="">
<meta name="author" content="">
<title>SimVascular Docs</title>
<link href="css/bootstrap.css" rel="stylesheet" type="text/css" />
<link href="css/shop-item.css" rel="stylesheet" type="text/css" />
<link href="css/codestyle.css" rel="stylesheet" type="text/css" />
<link rel="stylesheet" href="font-awesome-4.1.0/css/font-awesome.min.css">
<link rel="stylesheet" href="https://code.ionicframework.com/ionicons/1.5.2/css/ionicons.min.css">
<link rel="shortcut icon" href="img/favicon.ico">
<!-- HTML5 Shim and Respond.js IE8 support of HTML5 elements and media queries -->
<!-- WARNING: Respond.js doesn't work if you view the page via file:// -->
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
<script src="https://oss.maxcdn.com/libs/respond.js/1.4.2/respond.min.js"></script>
<![endif]-->
</head>
<body>
<!-- Navigation -->
<nav class="navbar navbar-inverse navbar-fixed-top" role="navigation">
<div class="container">
<!-- Brand and toggle get grouped for better mobile display -->
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-main-collapse">
<i class="fa fa-bars" id="barIcon"></i>
</button>
<a class="navbar-brand" id="brandName" href="index.html">
<img src="img/svlogo/svLogoSmallText.png" alt="...">
</a>
</div>
<!-- Collect the nav links, forms, and other content for toggling -->
<div class="collapse navbar-collapse navbar-right navbar-main-collapse">
<ul class="nav navbar-nav">
<!-- USER GUIDES -->
<li>
<a href="#" id="dropdownMenu1" data-toggle="dropdown">
<b><span class="fa fa-user"></span> User Guides</b>
</a>
<ul class="dropdown-menu" role="menu" aria-labelledby="dropdownMenu1">
<li role="presentation" class="divider"></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="docsQuickGuide.html"><b><span class="icon ion-ios7-bolt"></span> Getting Started</b></a></li>
<li role="presentation" class="divider"></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="docsModelGuide.html"><b><span class="icon ion-settings"></span> Modeling</b></a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="docsMeshing.html"><b><span class="icon ion-ios7-keypad"></span> Meshing</b></a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="docsFlowSolver.html"><b><span class="icon ion-play"></span> Simulation</b></a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="docssvFSI.html"><b><span class="icon ion-plus-round"></span> svFSI</b></a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="docsSimCardio.html"><b><span class="icon ion-plus-round"></span> SimCardio</b></a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="docsROMSimulation.html"><b><span class="icon ion-plus-round"></span> ROM Simulation</b></a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="docsGenBC.html"><b><span class="icon ion-refresh"></span> GenBC</b></a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="docsPythonInterface.html"><b><span class="icon ion-refresh"></span> Python Interface</b></a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="docsReferences.html"><b><span class="icon ion-refresh"></span> References </b></a></li>
</ul>
</li>
<!-- CLINCAL CASES -->
<li>
<a href="#" id="dropdownMenu1" data-toggle="dropdown">
<b><i class="fa fa-stethoscope"></i> Clinical Cases</b>
</a>
<ul class="dropdown-menu" role="menu" aria-labelledby="dropdownMenu1">
<li role="presentation"><a role="menuitem" tabindex="-1" href="clinicalCase3.html"><b><span class="fa fa-user-md"></span> Coronary Normal</b></a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="clinicalCase1.html"><b><span class="fa fa-user-md"></span> Aortofemoral Normal - 1</b></a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="clinicalCase2.html"><b><span class="fa fa-user-md"></span> Aortofemoral Normal - 2</b></a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="clinicalCase4.html"><b><span class="fa fa-user-md"></span> Healthy Pulmonary</b></a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="https://simtk.org/projects/sv_tests"><b><span class="fa fa-user-md"></span> All demo projects</b></a></li>
</ul>
</li>
<!-- DEVELOPER GUIDES -->
<li>
<a href="#" id="dropdownMenu1" data-toggle="dropdown">
<b><span class="fa fa-caret-square-o-right"></span> Developer Guides</b>
</a>
<ul class="dropdown-menu" role="menu" aria-labelledby="dropdownMenu1">
<li role="presentation"><a role="menuitem" tabindex="-1" href="https://github.com/SimVascular/SimVascular/wiki/wiki_for_developers"><b><span class="fa fa-file-text-o"></span> Compile Source Code</b></a></li>
</ul>
</li>
<!-- svCOMMUNITY -->
<li>
<a href="#" id="dropdownMenu1" data-toggle="dropdown">
<b><i class="fa fa-users"></i> svCommunity</b>
</a>
<ul class="dropdown-menu" role="menu" aria-labelledby="dropdownMenu1">
<li role="presentation"><a role="menuitem" tabindex="-1" href="https://simtk.org/forums/viewforum.php?f=188"><b><span class="fa fa-users"></span> Public Forum</b></a></li>
<li role="presentation" class="divider"></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="https://github.com/SimVascular/SimVascular/wiki/"><b><span class="fa fa-file-text-o"></span> Wiki</b></a></li>
<li role="presentation" class="divider"></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="https://simtk.org/mailman/listinfo/simvascular-news"><b><span class="fa fa-sign-in"></span> Join News Mailing List</b></a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="https://simtk.org/pipermail/simvascular-news/"><b><span class="fa fa-pencil-square-o"></span> News Mailing List Archive</b></a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="https://github.com/SimVascular/SimVascular/issues"><b><span class="fa fa-bug"></span> Report bugs and request features</b></a></li>
</ul>
</li>
<!-- REFERENCES -->
<li>
<a href="docsRefs.html" id="dropdownMenu1" >
<b><span class="icon ion-document-text"></span>References</b>
</a>
</li>
<!-- Archives -->
<li>
<a href="#" id="dropdownMenu1" data-toggle="dropdown">
<b> Archives</b>
</a>
<ul class="dropdown-menu" role="menu" aria-labelledby="dropdownMenu1">
<li role="presentation"><a role="menuitem" tabindex="-1" href="archiveQuickGuideSV2.html"><b>SimVascular 2.0</b></a></li>
</ul>
</li>
<!-- <li><a href="docsQuickGuide.html" id="btnQuickGuide"><b><span class="icon ion-ios7-bolt"></span> Quick Guide</b></a></li>
<li><a href="docsModelGuide.html" id="btnModelGuide"><b><span class="icon ion-settings"></span> Modeling</b></a></li>
<li><a href="docsMeshing.html" id="btnMeshing"><b><span class="icon ion-ios7-keypad"></span> Meshing</b></a></li>
<li><a href="docsPresolver.html" id="btnPresolver"><b><span class="icon ion-log-in"></span> svPre</b></a></li>
<li><a href="docsFlowSolver.html" id="btnFlowSolver"><b><span class="icon ion-play"></span> svSolver</b></a></li>
<li><a href="docsRefs.html" id="btnRefs"><b><span class="icon ion-document-text"></span> References</b></a></li>
<li><a href="clinicalCase1.html" id="btnRefs"><b>Case Studies</b></a></li> -->
</ul>
</div>
<!-- /.navbar-collapse -->
</div>
<!-- /.container -->
</nav>
<!-- Page Content -->
<!--Nav Bar -->
<div class="row">
<div class="col-xs-1 col-sm-1 hidden-md hidden-lg">
</div>
<!-- ONE COLUMN OF SPACE -->
<nav class="hidden-xs hidden-sm col-md-2 col-lg-2 bs-docs-sidebar">
<ul id="sidebar" class="nav nav-stacked fixed manGenBC"> <!--Nav Bar -->
<p><h3>GenBC Tutorial</h3></p>
<li><a href="#intro">Introduction</a></li>
<li><a href="#sv_prep">Preparing SV files for <br> GenBC Simulations</a></li>
<li><a href="#genbc_setup">Setting up GenBC</a></li>
<li><a href="#final_steps">Compiling GenBC and <br> Running Simulation</a></li>
<li><a href="#pressure_waveform">Pressure Waveform <br> Inlet Boundary Condition</a></li>
<li><a href="https://simtk.org/frs/download_confirm.php/latestzip/2031/GenBCTutorialExampleFiles-latest.zip?group_id=188">Cylinder Example Project</a></li>
</ul>
</nav>
<!--Main Content -->
<div class="col-xs-10 col-sm-10 col-md-9 col-lg-9" id="manualContent">
<!-- ACTUAL CONTENT -->
<div class="manGenBC"><section id="intro" class="group"><h2>Introduction</h2>
<p>This tutorial demonstrates how to use the General Boundary Conditions (GenBC) framework to define custom inlet and outlet boundary conditions for a computational fluid dynamics (CFD) simulation in SimVascular. It will cover all of the settings and parameters that need to be specified. We will follow a simple example of a cylinder with a prescribed Dirichlet inflow and RCR outflow, which should cover the basics needed to extend the framework to most situations. Additional notes will be included to explain any additional steps needed to extend the framework for more complex models. If you have any questions or if anything is unclear, please do not hesitate to contact us through the public forums!</p>
<h2>What is GenBC?</h2>
<p>GenBC provides a framework to programmatically define custom inflow and outflow boundary conditions for a CFD simulation. The framework
allows users to create an arbitrary lumped parameter network (LPN) layout suitable for their application. Some common examples include a
lumped parameter heart model that models contraction of the heart chambers to use as an inlet boundary condition, sophisticated models of
the downstream circulation for various areas of the body such as the legs and upper body, or a closed-loop formulation where all outflow
of the SimVascular model returns back to the inflow after passing through the veins, heart, and pulmonary arteries.</p>
<p>The GenBC framework is implemented as a Fortran program called by the SimVascular flow solver svSolver. Users must derive the governing
ordinary differential equations for the lumped parameter layout and implement them in Fortran inside the GenBC program. The Fortan program
is then compiled to produce a GenBC executable program. This executable is called by svSolver during execution to provide values for
custom boundary conditions.</p>
<p>SimVascular does not currently provide functionality to define GenBC boundary conditions using the GUI. The GUI is used
to generate simulation files for built-in boundary conditions. These files are then manually edited to incorporate the commands
needed to define data for the boundary conditions and to tell svSolver to use the GenBC framework. </p>
<h2>Cylinder RCR example</h2>
<p>This tutorial demonstrates how to use GenBC to define inflow and RCR boundary conditions for flow in a cylinder. Although these
boundary conditions can be defined using the built-in features in SimVascular they are used here as a simple example of all the
steps needed to implement GenBC boundary conditions. A graphical representation of the boundary conditions for the cylinder example
is shown in the figure below. </p>
<figure>
<img class="svImg svImgMd" src="documentation/genbc/imgs/rcr_cylinder.jpeg">
<figcaption class="svCaption" >Cylinder with sinusoidal inflow and RCR outflow.</figcaption>
</figure>
<p>The SimVascular project for the cylinder example can be downloaded using the <strong>Cylinder Example Project</strong> link in the menu on the
left-hand side of this page. The project contains all of the data (image, model, and mesh) needed for the tutorial. You will need
to manually load the mesh by selecting <strong>Meshes->cylinder_mesh->Load/Unload Mesh</strong> from the <strong>SV Data Manager</strong> menu. The project
has two additional folders</p>
<pre class="highlight plaintext"><code>1) GenBC-program - Contains the Fortran code implementing the GenBC framework
2) flow-file - Contains the **inlet.flow** file used to to define the flow rate for Direchlet boundary conditions.
</code></pre>
</section>
<section id="sv_prep" class="group"><h2>Preparing SimVascular solver files for GenBC</h2>
<p>We will assume at this point that you will have already built the geometry of your model and meshed it using the model construction
pipeline in SimVascular. This tutorial will start right at the <strong>Simulations</strong> module. Create a new Simulation job by right-clicking
the <strong>Simulations</strong> item in the <strong>Data Manager</strong>, then click <strong>Create New Simulation Job</strong>. Select the appropriate Model from the
drop down menu and give it the name <strong>cyl_sim</strong>. Navigate through the various tabs to set simulation parameters discussed
in <a href="http://simvascular.github.io/docsQuickGuide.html#simulation"> Quick Guide / Simulations</a>. In particular, the values for
<strong>Number of Time Steps</strong>, <strong>Time Step Size</strong> and <strong>Number of Timesteps between Restarts</strong> parameters under the <strong>Solver Parameters</strong>
tab must be set.</p>
<p>During execution the solver will normalize the velocity profile of the Dirichlet inlets to have a flow of 1.0 and then multiply
the velocity profile by the flow that is computed in GenBC. Caps with Dirichlet boundary conditions are typically connected to
an inductor or have a specified flow waveform (e.g. measured or adapted from literature). For the cylinder example we want to specify the
<strong>inlet</strong> face to have a Dirichlet boundary condition. To set a Dirichlet boundary condition for the <strong>inlet</strong> cap double-click the
box in the row of the cap <strong>Name</strong> and the column of the <strong>BC Type</strong> and select <strong>Prescribed Velocities</strong> from the drop-down menu.
Double-click the cap name under <strong>Name</strong> to open up a window with additional parameters. Set <strong>BC Type</strong> to
<strong>Prescribed Velocities</strong> and set <strong>Analytic Shape</strong> to <strong>parabolic</strong>. For the flow rate select the <strong>inlet.flow</strong> file from the
project’s <strong>simulation-files</strong> directory. </p>
<figure>
<img class="svImg svImgMd" src="documentation/genbc/imgs/velocities_window.png">
<figcaption class="svCaption" >Prescribed inflow settings window.</figcaption>
</figure>
<p>A Neumann boundary condition is typically used for caps that interface directly with either a capacitor or a resistor.
For the <strong>outlet</strong> cap we specify a Neumann boundary condition by selecting <strong>Resistance</strong> for the <strong>BC Type</strong> and assigning it
a value of 0. These settings are used to create the appropriate entries in the <strong>solver.inp</strong> file we will later modify.
The <strong>Inlet and Outlet BCs</strong> tab should now look like this</p>
<figure>
<img class="svImg svImgMd" src="documentation/genbc/imgs/inlet_and_outlet_bcs.png">
<figcaption class="svCaption" >Inlet and outlet conditions.</figcaption>
</figure>
<p>To create the data files for the simulation go to the <strong>Create Files and Run Simulation</strong> tab, select the appropriate mesh from
the drop down menu and click <strong>Create Data Files for Simulation</strong>. The simulation files are written to the project directory inside
the <strong>Simulations</strong> folder. In this folder you will see a folder for the simulation job you created named <strong>cyl_sim</strong>. Inside this
folder are the following files and folders:</p>
<pre class="highlight plaintext"><code>1. mesh-complete – Contains mesh information and discretization in VTK format files
2. bct.dat and bct.vtp – Contains velocity profile information on your Dirichlet caps
3. cyl_sim.svpre file – Pre-solver script which instructs SimVascular how to prepare the simulation files
from your mesh. Contains the ID numbers for mesh surfaces (used later)
4. geombc.dat.1 – Simulation file that contains geometry information
5. inlet.flow - .flow file which has the template flow information at your inlet face(s)
6. numstart.dat – Dummy file which tells the solver on which timestep to start on
7. restart.0.1 – Contains initial conditions for pressure and velocity in your simulations
8. solver.inp – Solver settings file
</code></pre>
<p>Surfaces are identified using integer IDs automatically generated by SimVascular and assigned to surfaces in
the <strong>.svpre</strong> file using the <strong>set_surface_id_vtp</strong> command </p>
<figure>
<img class="svImg svImgMd" src="documentation/genbc/imgs/surface_ids.png">
<figcaption class="svCaption" >Surface IDs in .svpre file.</figcaption>
</figure>
<p>We need to manually modify the <strong>solver.inp</strong> file to use GenBC. Edit the <strong>solver.inp</strong> file with a text editor and scroll down to
the section right below <strong>Step Construction</strong>. You will see following three commands for Resistance boundary conditions</p>
<pre class="highlight plaintext"><code>Number of Resistance Surfaces: 1
List of Resistance Surfaces: 3
Resistance Values: 0
</code></pre>
<p>These commands were created for the <strong>outlet</strong> cap Neumann boundary condition but are not needed and so we delete them.</p>
<p>We next need to add commands to instruct the solver to look for GenBC and all the inlet/outlet surfaces. Below the <strong>Step Construction</strong>
command add </p>
<pre class="highlight plaintext"><code>Find the GenBC Inside the Running Directory: True
Number of Timesteps for GenBC Initialization: 0
</code></pre>
<p>We next add commands identifying the inlet Dirichlet surfaces</p>
<pre class="highlight plaintext"><code>Number of Dirichlet Surfaces: 1
List of Dirichlet Surfaces: 2
</code></pre>
<p>The <strong>Number of Dirichlet Surfaces</strong> command specifies the total number of caps in your model where Dirichlet boundary condition are
defined for GenBC. The <strong>List of Dirichlet Surfaces</strong> is a space-delimited list surface IDs for the Dirichlet boundary conditions.
For the cylinder model the <strong>inlet</strong> is assigned ID 2. </p>
<p>We now add a similar commands for surfaces with Neumann boundary conditions </p>
<pre class="highlight plaintext"><code>Number of Neumann Surfaces: 1
List of Neumann Surfaces: 3
</code></pre>
<p>We now change the value of <strong>Number of Coupled Surfaces</strong> to the total number of Dirichlet and Neumann surfaces in your model.
This is to indicate that these surfaces are coupled in the sense that the flow and pressure have the potential to be coupled in
the GenBC formulation. For this example the number of coupled surfaces is 2 because we have 1 Dirichlet surface and 1 Neumann surface.</p>
<p>After making these changes the <strong>solver.inp</strong> file should look like</p>
<figure>
<img class="svImg svImgMd" src="documentation/genbc/imgs/solver_lines.png">
<figcaption class="svCaption" >Configured solver.inp for GenBC simulation of an RCR cylinder.</figcaption>
</figure>
</section>
<section id="genbc_setup" class="group"><h2>Setting up GenBC</h2>
<p>The Fortan files implementing GenBC are found in the project directory under the <strong>GenBC-program</strong> folder. This folder contains
three Fortran source files (GenBC.f, Modules.f and USER.f) and a Makefile.</p>
<p>All of the implementation will be done in USER.f. Open this file with a text editor. We will proceed down this code and explain it in blocks. The first block that the user can change is the “unit conversion” block:</p>
<figure>
<img class="svImg svImgMd" src="documentation/genbc/imgs/unit_conversion_block.png">
<figcaption class="svCaption" >Unit conversion block of GenBC.</figcaption>
</figure>
<p>In this block, you can specify conversion factors between pressure and flow in the GenBC code, and pressure and flow in the SimVascular flowsolver. In general, SimVascular models and flowsolvers use the CGS unit system (centimeter-gram-second). The units for pressure and flow in this system are dyne/cm^2 and cm^3/s, respectively. In the GenBC framework, it is often convenient to work with “clinical” units of pressure (i.e. mmHg). The conversion factor between mmHg and dyne/cm^2 is 1334 (dyne/cm^2) / mmHg, hence the value of 1.334D3 for the pConv variable. The clinical unit for flow is mL/s, which is equivalent to cm^3/s, so we leave the qConv variable at 1.0. If you want to develop your LPN model using CGS units for the parameter values, then you can change both Conv variables to 1.0. Note that the system you will choose to work with will affect the values of the parameters in your LPN network, and the values for the initial conditions in your LPN network as will be described below.</p>
<p>The pCorr and qCorr variables are seldom used and can be left as .FALSE.
The next block is the inputs block:</p>
<figure>
<img class="svImg svImgMd" src="documentation/genbc/imgs/inputs_block.png">
<figcaption class="svCaption" >Inputs block of GenBC.</figcaption>
</figure>
<p>In this block, you must specify the number of Dirichlet and Neumann surfaces that match you specified earlier in your solver.inp. Next, you need to specify the number of unknowns. This is the total number of state variables that you will solve for in your boundary condition model. In this case, we have just a simple model with 2 unknowns for our 2 caps, so we set this number to 2. But more sophisticated models will often involve solving for more unknowns than there are caps. This is common for heart model LPNs, where the volumes, pressures, and flows need to be computed as state variables for each chamber of the heart. But these “internal variables” do not necessarily get applied as boundary conditions to the 3D model.</p>
<p>The next parameter is the number of sub time steps used in time-integrating the system of ordinary differential equations to the next time step. Because the boundary condition model is often significantly cheaper than computational fluid dynamics, we can afford to iterate the boundary condition model at a much smaller time step size. This parameter specifies how many timesteps will be used to integrate the boundary condition model IN BETWEEN time steps of the 3D model. 100 is a good number here and you will likely never have to change this.</p>
<p>Nxprint specifies the number of extra information you would like to output. This will be further explained later, but for now we can leave this as 3.</p>
<p>The next block is the initial conditions block:</p>
<figure>
<img class="svImg svImgMd" src="documentation/genbc/imgs/IC_block.png">
<figcaption class="svCaption" >Initial conditions block of GenBC.</figcaption>
</figure>
<p>Because the boundary condition model is comprised of a system of ordinary differential equations, we need to specify the initial values for all the state variables. In this example, we have defined the first state variable to be the inflow to the model, and give it an initial condition of -10 mL/s (the negative is to denote inflow, rather than outflow of the model). The second state variable is the pressure on the RCR capacitor, which we initialize to 90 mmHg.</p>
<p>The next block is the surface mapping block.</p>
<figure>
<img class="svImg svImgMd" src="documentation/genbc/imgs/srftox_block.png">
<figcaption class="svCaption" >Surface mapping block of GenBC.</figcaption>
</figure>
<p>In this block, we specify the mapping between state variables in the boundary condition model and surface IDs in the SimVascular simulation. Recall that in our solver.inp we had to specify a list of the surface IDs for the Dirichlet and Neumann surfaces. These two vectors (srfToXdPtr and srfToXPtr) are the corresponding lists in the boundary condition model. The elements of these vectors are the state variable indices that will be applied as boundary conditions on the model.</p>
<p>Take the first vector as an example. This vector is called “srfToXdPtr” and specifies the mapping between state variables and the Dirichlet surfaces of the SimVascular model. Recall from the section on the initial conditions that we defined the first state variable (i.e. index 1) to correspond to the flow at the cylinder inlet. Hence, the vector “srfToXdPtr” has a 1 to indicate this.</p>
<p>The second vector “srfToXPtr” specifies the mapping between state variables and the Neumann surfaces in our SimVascular model. Since we are using the second state variable for the RCR capacitance pressure, we put a 2 in this list.</p>
<p>Additional entries can be added to these vectors for more complex models separated by commas:</p>
<pre class="highlight plaintext"><code>srfToXdPts = (/1,4,5,6/)
</code></pre>
<p>A good safety check at this point is the make sure the vectors in this block have the exact same length as the corresponding lists of surface IDs in solver.inp. SrfToXdPtr should have the same length as “List of Dirichlet Surfaces” in solver.inp, and srfToXPtr should have the same length as “List of Neumann Surfaces”. Each element in the USER.f lists should have a matching pair in the solver.inp lists. To recap for this example, state variable 1 gets applied to surface ID 2 as a Dirichlet boundary condition, and state variable 2 gets applied to surface ID 3 as a Neumann boundary condition.</p>
<p>The final block in USER.f is the equations block:</p>
<figure>
<img class="svImg svImgMd" src="documentation/genbc/imgs/equations_block.png">
<figcaption class="svCaption" >Equations block of GenBC.</figcaption>
</figure>
<p>In this block, we specify parameter values, write out the governing differential equations, and specify any extra outputs we would like to be printed out. We first define the parameters of our RCR outlet circuit. We need to specify three parameters: proximal resistance Rp, capacitance C, and distal resistance Rd. As is typical of Windkessel models, the distal resistance is significantly higher. Here, we use a simple 10:1 ratio, which is fairly standard. Typically, the values of these parameters are specified or tuned such that the simulation results match either population average data or patient-specific data. Here, we just use nominal values for this example. Note the Fortran method for specifying variables. First the type and name of the variables must be declared:</p>
<pre class="highlight plaintext"><code>REAL(8) Rp, C, Rd
</code></pre>
<p>Then, the values can be set on subsequent lines. Also note how all non-comment lines of code start in column 7, as is required by the Fortran programming language.</p>
<p>Next, we specify the governing differential equations for our LPN model. These are saved in the output vector “f”. Note that “f” has length equal to the number of unknowns. Since we have 2 unknowns in this cylinder model, we need to specify a differential equation for both. For our inflow (i.e. state variable 1) recall that we set an initial condition of 10 mL/s. Just for the sake of this example, let’s apply a simple sinusoidal oscillation such that we get a little unsteadiness in our result. We apply a time derivative of cos(15t) to the inflow. Note that if a steady inflow is desired, simply set the time derivative to 0. This will cause the boundary condition model to maintain the initial condition.</p>
<p>For the RCR circuit, we apply the differential equation governing the pressure evolution on the capacitor. Assuming an inflow of Q into the capacitor, P is the current pressure on the capacitor, and applying Kirchoff’s laws of current and voltage conservation, the time derivative of the pressure is:</p>
<figure>
<img class="svImg svImgSm" src="documentation/genbc/imgs/dpdt.jpg">
<figcaption class="svCaption" >RCR equation for pressure.</figcaption>
</figure>
<p>This is reflected in the code in the expression for f(2). Finally, we need to add an offset for the proximal resistance. The offset serves a purpose of adding to or subtracting from a state variable before it gets applied as a boundary condition for the fluid dynamics simulation. In this case, the pressure that is applied on the simulation needs to be offset by the action of the proximal resistance. This offset pressure is simply the flow into the capacitor multiplied by the proximal resistance.</p>
<p>A quick explanation about the P and Q variables. Note how these are inputs to the FINDF subroutine we have been modifying. These are pressures and flows that are computed by the fluid dynamics simulation and passed to the boundary condition model as inputs. For Dirichlet boundary conditions, SimVascular computes an area-averaged pressure across that face and passes it to P vector. For Neumann boundary conditions, SimVascular computes the flow out of that outlet and passes it to Q vector. For most coupled boundary conditions, these P and Q values are needed as inputs. Take our RCR outlet condition for example. It needed the flow out of the outlet face (i.e. Q(1)) in order to specify the differential equation for the pressure. This is what is meant by “coupled” boundary conditions, where the pressure and flow at the caps of our model are intimately linked through the boundary condition model. We did not make use of the P vector in this case since we are using a special case of a completely prescribed inflow. But this will be used for more general Dirichlet boundary conditions.</p>
<p>Another quick explanation on the “x” variable. This vector contains the current values for the state variables. In this case, x(1) contains the current value of flow at the inflow, and x(2) contains the current value of pressure on the RCR capacitor. The current values of the state variables are often used in numerical solutions of systems of ordinary differential equations, so this x variable is how you access them. In this example, we only utilized the current pressure on the capacitor in specifying f(2), but more complex models will make more use of the “x” variable.</p>
<p>We recommend writing out the governing equations using a pencil and paper before implementing them in the Fortran code. This will keep you organized and ensure that the equations are being derived and implemented in the code correctly.</p>
<p>Finally, we can specify additional outputs that we would like to see in the Xprint vector. The variables specified here will appear in the outputs. This part is completely optional, but it can be useful to print out additional variables when debugging. Recall in the input block that we specified 3 Xprints, which will allocate 3 slots in the Xprint vector. You can raise this number if you would like to print out more. For this case, we have printed out three variables: the current time (t), the flow at the Neumann outlet (Q(1)), and the value of the proximal resistance offset.</p>
</section>
<section id="final_steps" class="group"><h2>Compiling GenBC</h2>
<p>Once all of the settings and equations have been set in USER.f you can compile the source code. Navigate to the <strong>GenBC-program</strong> folder
on your Linux or Mac machine using the terminal and type <strong>make</strong>. This creates an executable named <strong>GenBC</strong> in the current folder.
Copy the executable to the project <strong>Simulations</strong> <strong>cyl_sim</strong> folder.</p>
<h2>Running a flow simulation and checking results</h2>
<p>Now navigate to the <strong>Simulations</strong> <strong>cyl_sim</strong> folder. You can now run the svSolver program. Once the simulation starts it will
create a file named <strong>AllData</strong>. This is an output file produced by GenBC which contains the values of the state variables as a
function of time and the additional Xprint outputs we specified earlier.</p>
</section>
<section id="pressure_waveform" class="group"><h2>Prescribing a pressure waveform as an inlet boundary condition</h2>
<p>This section of the tutorial describes how to use the GenBC framework to define a Neumann boundary condition as a pressure
waveform at an inlet surface. The pressure boundary condition is implemented in Fortran using the GenBC framework. The pressure
at the cylinder inlet is obtained by interpolating a pressure waveform defined in the GenBC Fortan code.</p>
<figure>
<img class="svImg svImgMd" src="documentation/genbc/imgs/waveform.png">
<figcaption class="svCaption" >Pressure waveform used for the inlet Neumann boundary condition.</figcaption>
</figure>
<p>The pressure waveform inlet boundary condition simulation is similar to the RCR simulation we created above except
for changes to the boundary conditions and some changes in the simulation parameters needed for solver stability. Create a new
Simulation job by right-clicking the <strong>Simulations</strong> item in the <strong>Data Manager</strong>, then click <strong>Create New Simulation Job</strong>.
Select the appropriate Model from the drop down menu and give it the name <strong>cyl_pres</strong>. Navigate to the <strong>Solver Parameters</strong> tab and
set </p>
<pre class="highlight plaintext"><code>Number of Time Steps: 2000
Time Step Size: 0.000588
Number of Timesteps between Restarts: 20
</code></pre>
<p>We will define Neumann boundary conditions for both the inlet and outlet caps selecting <strong>Resistance</strong> for the <strong>BC Type</strong> and assigning it
a value of 0. These settings are used to create the appropriate entries in the <strong>solver.inp</strong> file we will later modify. The <strong>Inlet and
Outlet BCs</strong> tab should now look like this</p>
<figure>
<img class="svImg svImgMd" src="documentation/genbc/imgs/pres_inlet_and_outlet_bcs.png">
</figure>
<p>To create the data files for the simulation go to the <strong>Create Files and Run Simulation</strong> tab, select the appropriate mesh from
the drop down menu and click <strong>Create Data Files for Simulation</strong>. The simulation files are written to the project directory inside
the <strong>Simulations</strong> folder. In this folder you will see a folder for the simulation job you created named <strong>cyl_pres</strong>. Now navigate
to the <strong>cyl_pres</strong> folder. Inside this folder are the following files and folders:</p>
<pre class="highlight plaintext"><code> 1. mesh-complete – Contains mesh information and discretization in VTK format files
2. cyl_pres.svpre file – Pre-solver script which instructs SimVascular how to prepare the simulation files
from your mesh. Contains the ID numbers for mesh surfaces (used later)
3. geombc.dat.1 – Simulation file that contains geometry information
4. numstart.dat – Dummy file which tells the solver on which timestep to start on
5. restart.0.1 – Contains initial conditions for pressure and velocity in your simulations
6. solver.inp – Solver settings file
</code></pre>
<p>We need an additional <strong>rcrt.dat</strong> file containing the RCR parameters that set the relationship between flow and pressure on
the outflow face. Copt this file from the <strong>simulation-files</strong> folder to here. </p>
<p>the presover solver script (svpre) is needed to be modified by treating the inlet as a Neunmann face (see steady_rcr.svpre). Thus, to prepare a simulation with a prescribed pressure waveform, we run the presolver with the modified presolver script to generate geombc.dat and restart.0.1 files with surfaces properly tagged. Then we compile the GenBC files (user defined Fortran files) before calling the flow solver.</p>
<p>Note that apart from potentially increased computational cost and numerical instability (which might be insignificant), prescribing a pressure waveform doesn’t necessarily make flow simulations better agree with clinical target values. So extra adjustments are often needed in order to match target pressures and flow. Don’t forget to check resulting inflow when the Neumann BC (pre-defined pressure or a lumped parameter model defined pressure) is applied to the inlet.</p>
</section>
</div>
</div>
</div>
<!-- /.container -->
<nav class="navbar navbar-default navbar-fixed-bottom">
<div class="container-fluid text-center">
<ul class="nav navbar-nav">
<li><a>Copyright © SimVascular Development Team - 2017</a></li>
</ul>
</div>
<!-- /.container -->
</nav>
<script src="js/jquery-1.11.0.js" type="text/javascript"></script><script src="js/bootstrap.min.js" type="text/javascript"></script>
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
tex2jax: {inlineMath: [['$','$'], ['\\(','\\)']]}
});
$('body').scrollspy({
target: '.bs-docs-sidebar',
offset: 40
});
</script>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-55333921-1', 'auto');
ga('send', 'pageview');
</script>
<script type="text/javascript"
src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>
</body>
</html>