doc/html/main.html

   1 <?xml version="1.0" encoding="utf-8" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   6 <meta name="generator" content="Docutils 0.12: http://docutils.sourceforge.net/" />
   7 <title>LBM Benchmark Kernels Documentation</title>
   8 <style type="text/css">
   9
  10 /*
  11 :Author: David Goodger (goodger@python.org)
  12 :Id: $Id: html4css1.css 7614 2013-02-21 15:55:51Z milde $
  13 :Copyright: This stylesheet has been placed in the public domain.
  14
  15 Default cascading style sheet for the HTML output of Docutils.
  16
  17 See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
  18 customize this style sheet.
  19 */
  20
  21 /* used to remove borders from tables and images */
  22 .borderless, table.borderless td, table.borderless th {
  23   border: 0 }
  24
  25 table.borderless td, table.borderless th {
  26   /* Override padding for "table.docutils td" with "! important".
  27      The right padding separates the table cells. */
  28   padding: 0 0.5em 0 0 ! important }
  29
  30 .first {
  31   /* Override more specific margin styles with "! important". */
  32   margin-top: 0 ! important }
  33
  34 .last, .with-subtitle {
  35   margin-bottom: 0 ! important }
  36
  37 .hidden {
  38   display: none }
  39
  40 a.toc-backref {
  41   text-decoration: none ;
  42   color: black }
  43
  44 blockquote.epigraph {
  45   margin: 2em 5em ; }
  46
  47 dl.docutils dd {
  48   margin-bottom: 0.5em }
  49
  50 object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] {
  51   overflow: hidden;
  52 }
  53
  54 /* Uncomment (and remove this text!) to get bold-faced definition list terms
  55 dl.docutils dt {
  56   font-weight: bold }
  57 */
  58
  59 div.abstract {
  60   margin: 2em 5em }
  61
  62 div.abstract p.topic-title {
  63   font-weight: bold ;
  64   text-align: center }
  65
  66 div.admonition, div.attention, div.caution, div.danger, div.error,
  67 div.hint, div.important, div.note, div.tip, div.warning {
  68   margin: 2em ;
  69   border: medium outset ;
  70   padding: 1em }
  71
  72 div.admonition p.admonition-title, div.hint p.admonition-title,
  73 div.important p.admonition-title, div.note p.admonition-title,
  74 div.tip p.admonition-title {
  75   font-weight: bold ;
  76   font-family: sans-serif }
  77
  78 div.attention p.admonition-title, div.caution p.admonition-title,
  79 div.danger p.admonition-title, div.error p.admonition-title,
  80 div.warning p.admonition-title, .code .error {
  81   color: red ;
  82   font-weight: bold ;
  83   font-family: sans-serif }
  84
  85 /* Uncomment (and remove this text!) to get reduced vertical space in
  86    compound paragraphs.
  87 div.compound .compound-first, div.compound .compound-middle {
  88   margin-bottom: 0.5em }
  89
  90 div.compound .compound-last, div.compound .compound-middle {
  91   margin-top: 0.5em }
  92 */
  93
  94 div.dedication {
  95   margin: 2em 5em ;
  96   text-align: center ;
  97   font-style: italic }
  98
  99 div.dedication p.topic-title {
 100   font-weight: bold ;
 101   font-style: normal }
 102
 103 div.figure {
 104   margin-left: 2em ;
 105   margin-right: 2em }
 106
 107 div.footer, div.header {
 108   clear: both;
 109   font-size: smaller }
 110
 111 div.line-block {
 112   display: block ;
 113   margin-top: 1em ;
 114   margin-bottom: 1em }
 115
 116 div.line-block div.line-block {
 117   margin-top: 0 ;
 118   margin-bottom: 0 ;
 119   margin-left: 1.5em }
 120
 121 div.sidebar {
 122   margin: 0 0 0.5em 1em ;
 123   border: medium outset ;
 124   padding: 1em ;
 125   background-color: #ffffee ;
 126   width: 40% ;
 127   float: right ;
 128   clear: right }
 129
 130 div.sidebar p.rubric {
 131   font-family: sans-serif ;
 132   font-size: medium }
 133
 134 div.system-messages {
 135   margin: 5em }
 136
 137 div.system-messages h1 {
 138   color: red }
 139
 140 div.system-message {
 141   border: medium outset ;
 142   padding: 1em }
 143
 144 div.system-message p.system-message-title {
 145   color: red ;
 146   font-weight: bold }
 147
 148 div.topic {
 149   margin: 2em }
 150
 151 h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
 152 h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
 153   margin-top: 0.4em }
 154
 155 h1.title {
 156   text-align: center }
 157
 158 h2.subtitle {
 159   text-align: center }
 160
 161 hr.docutils {
 162   width: 75% }
 163
 164 img.align-left, .figure.align-left, object.align-left {
 165   clear: left ;
 166   float: left ;
 167   margin-right: 1em }
 168
 169 img.align-right, .figure.align-right, object.align-right {
 170   clear: right ;
 171   float: right ;
 172   margin-left: 1em }
 173
 174 img.align-center, .figure.align-center, object.align-center {
 175   display: block;
 176   margin-left: auto;
 177   margin-right: auto;
 178 }
 179
 180 .align-left {
 181   text-align: left }
 182
 183 .align-center {
 184   clear: both ;
 185   text-align: center }
 186
 187 .align-right {
 188   text-align: right }
 189
 190 /* reset inner alignment in figures */
 191 div.align-right {
 192   text-align: inherit }
 193
 194 /* div.align-center * { */
 195 /*   text-align: left } */
 196
 197 ol.simple, ul.simple {
 198   margin-bottom: 1em }
 199
 200 ol.arabic {
 201   list-style: decimal }
 202
 203 ol.loweralpha {
 204   list-style: lower-alpha }
 205
 206 ol.upperalpha {
 207   list-style: upper-alpha }
 208
 209 ol.lowerroman {
 210   list-style: lower-roman }
 211
 212 ol.upperroman {
 213   list-style: upper-roman }
 214
 215 p.attribution {
 216   text-align: right ;
 217   margin-left: 50% }
 218
 219 p.caption {
 220   font-style: italic }
 221
 222 p.credits {
 223   font-style: italic ;
 224   font-size: smaller }
 225
 226 p.label {
 227   white-space: nowrap }
 228
 229 p.rubric {
 230   font-weight: bold ;
 231   font-size: larger ;
 232   color: maroon ;
 233   text-align: center }
 234
 235 p.sidebar-title {
 236   font-family: sans-serif ;
 237   font-weight: bold ;
 238   font-size: larger }
 239
 240 p.sidebar-subtitle {
 241   font-family: sans-serif ;
 242   font-weight: bold }
 243
 244 p.topic-title {
 245   font-weight: bold }
 246
 247 pre.address {
 248   margin-bottom: 0 ;
 249   margin-top: 0 ;
 250   font: inherit }
 251
 252 pre.literal-block, pre.doctest-block, pre.math, pre.code {
 253   margin-left: 2em ;
 254   margin-right: 2em }
 255
 256 pre.code .ln { color: grey; } /* line numbers */
 257 pre.code, code { background-color: #eeeeee }
 258 pre.code .comment, code .comment { color: #5C6576 }
 259 pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold }
 260 pre.code .literal.string, code .literal.string { color: #0C5404 }
 261 pre.code .name.builtin, code .name.builtin { color: #352B84 }
 262 pre.code .deleted, code .deleted { background-color: #DEB0A1}
 263 pre.code .inserted, code .inserted { background-color: #A3D289}
 264
 265 span.classifier {
 266   font-family: sans-serif ;
 267   font-style: oblique }
 268
 269 span.classifier-delimiter {
 270   font-family: sans-serif ;
 271   font-weight: bold }
 272
 273 span.interpreted {
 274   font-family: sans-serif }
 275
 276 span.option {
 277   white-space: nowrap }
 278
 279 span.pre {
 280   white-space: pre }
 281
 282 span.problematic {
 283   color: red }
 284
 285 span.section-subtitle {
 286   /* font-size relative to parent (h1..h6 element) */
 287   font-size: 80% }
 288
 289 table.citation {
 290   border-left: solid 1px gray;
 291   margin-left: 1px }
 292
 293 table.docinfo {
 294   margin: 2em 4em }
 295
 296 table.docutils {
 297   margin-top: 0.5em ;
 298   margin-bottom: 0.5em }
 299
 300 table.footnote {
 301   border-left: solid 1px black;
 302   margin-left: 1px }
 303
 304 table.docutils td, table.docutils th,
 305 table.docinfo td, table.docinfo th {
 306   padding-left: 0.5em ;
 307   padding-right: 0.5em ;
 308   vertical-align: top }
 309
 310 table.docutils th.field-name, table.docinfo th.docinfo-name {
 311   font-weight: bold ;
 312   text-align: left ;
 313   white-space: nowrap ;
 314   padding-left: 0 }
 315
 316 /* "booktabs" style (no vertical lines) */
 317 table.docutils.booktabs {
 318   border: 0px;
 319   border-top: 2px solid;
 320   border-bottom: 2px solid;
 321   border-collapse: collapse;
 322 }
 323 table.docutils.booktabs * {
 324   border: 0px;
 325 }
 326 table.docutils.booktabs th {
 327   border-bottom: thin solid;
 328   text-align: left;
 329 }
 330
 331 h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
 332 h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
 333   font-size: 100% }
 334
 335 ul.auto-toc {
 336   list-style-type: none }
 337
 338 </style>
 339 <style type="text/css">
 340
 341
 342 h1, h2, h3, h4, h5, h6 {
 343   font-family: sans-serif;
 344   font-size: 100%;
 345   background-color: #dcdcdc;
 346 }
 347
 348 h1.title {
 349   background-color: gray;
 350   color: white
 351 }
 352
 353 table.footnote {
 354   padding-left: 0.5ex;
 355 }
 356
 357 table.citation {
 358   padding-left: 0.5ex
 359 }
 360
 361 td.label {
 362   width: 10%;
 363 }
 364
 365 table, table.docutils, td, th {
 366   border: 0;
 367 }
 368
 369 table.citation, table.footnote {
 370   width: 100%;
 371 }
 372
 373 th {
 374     background-color: lavender ;
 375 }
 376
 377 tr:nth-child(even) {
 378     xxbackground-color: aliceblue;
 379     background-color: white;
 380 }
 381 tr:nth-child(odd) {
 382     xxbackground-color: lavender;
 383     background-color: whitesmoke;
 384 }
 385
 386
 387
 388 </style>
 389 </head>
 390 <body>
 391 <div class="document" id="lbm-benchmark-kernels-documentation">
 392 <h1 class="title">LBM Benchmark Kernels Documentation</h1>
 393
 394 <!-- # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 395 #
 396 # Copyright
 397 #   Markus Wittmann, 2016-2017
 398 #   RRZE, University of Erlangen-Nuremberg, Germany
 399 #   markus.wittmann -at- fau.de or hpc -at- rrze.fau.de
 400 #
 401 #   Viktor Haag, 2016
 402 #   LSS, University of Erlangen-Nuremberg, Germany
 403 #
 404 #  This file is part of the Lattice Boltzmann Benchmark Kernels (LbmBenchKernels).
 405 #
 406 #  LbmBenchKernels is free software: you can redistribute it and/or modify
 407 #  it under the terms of the GNU General Public License as published by
 408 #  the Free Software Foundation, either version 3 of the License, or
 409 #  (at your option) any later version.
 410 #
 411 #  LbmBenchKernels is distributed in the hope that it will be useful,
 412 #  but WITHOUT ANY WARRANTY; without even the implied warranty of
 413 #  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 414 #  GNU General Public License for more details.
 415 #
 416 #  You should have received a copy of the GNU General Public License
 417 #  along with LbmBenchKernels.  If not, see <http://www.gnu.org/licenses/>.
 418 #
 419 # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
 420 <div class="contents topic" id="contents">
 421 <p class="topic-title first">Contents</p>
 422 <ul class="auto-toc simple">
 423 <li><a class="reference internal" href="#compilation" id="id2">1&nbsp;&nbsp;&nbsp;Compilation</a><ul class="auto-toc">
 424 <li><a class="reference internal" href="#debug-and-verification" id="id3">1.1&nbsp;&nbsp;&nbsp;Debug and Verification</a></li>
 425 <li><a class="reference internal" href="#benchmarking" id="id4">1.2&nbsp;&nbsp;&nbsp;Benchmarking</a></li>
 426 <li><a class="reference internal" href="#release-and-verification" id="id5">1.3&nbsp;&nbsp;&nbsp;Release and Verification</a></li>
 427 <li><a class="reference internal" href="#compilers" id="id6">1.4&nbsp;&nbsp;&nbsp;Compilers</a></li>
 428 <li><a class="reference internal" href="#cleaning" id="id7">1.5&nbsp;&nbsp;&nbsp;Cleaning</a></li>
 429 <li><a class="reference internal" href="#options-summary" id="id8">1.6&nbsp;&nbsp;&nbsp;Options Summary</a></li>
 430 </ul>
 431 </li>
 432 <li><a class="reference internal" href="#invocation" id="id9">2&nbsp;&nbsp;&nbsp;Invocation</a><ul class="auto-toc">
 433 <li><a class="reference internal" href="#command-line-parameters" id="id10">2.1&nbsp;&nbsp;&nbsp;Command Line Parameters</a></li>
 434 <li><a class="reference internal" href="#kernels" id="id11">2.2&nbsp;&nbsp;&nbsp;Kernels</a></li>
 435 </ul>
 436 </li>
 437 <li><a class="reference internal" href="#id1" id="id12">3&nbsp;&nbsp;&nbsp;Benchmarking</a><ul class="auto-toc">
 438 <li><a class="reference internal" href="#padding" id="id13">3.1&nbsp;&nbsp;&nbsp;Padding</a></li>
 439 </ul>
 440 </li>
 441 <li><a class="reference internal" href="#geometries" id="id14">4&nbsp;&nbsp;&nbsp;Geometries</a></li>
 442 <li><a class="reference internal" href="#results" id="id15">5&nbsp;&nbsp;&nbsp;Results</a></li>
 443 <li><a class="reference internal" href="#licence" id="id16">6&nbsp;&nbsp;&nbsp;Licence</a></li>
 444 <li><a class="reference internal" href="#acknowledgements" id="id17">7&nbsp;&nbsp;&nbsp;Acknowledgements</a></li>
 445 </ul>
 446 </div>
 447 <div class="section" id="compilation">
 448 <h1><a class="toc-backref" href="#id2">1&nbsp;&nbsp;&nbsp;Compilation</a></h1>
 449 <p>The benchmark framework currently supports only Linux systems and the GCC and
 450 Intel compilers. Every other configuration probably requires adjustment inside
 451 the code and the makefiles. Further some code might be platform or at least
 452 POSIX specific.</p>
 453 <p>The benchmark can be build via <tt class="docutils literal">make</tt> from the <tt class="docutils literal">src</tt> subdirectory. This will
 454 generate one binary which hosts all implemented benchmark kernels.</p>
 455 <p>Binaries are located under the <tt class="docutils literal">bin</tt> subdirectory and will have different names
 456 depending on compiler and build configuration.</p>
 457 <div class="section" id="debug-and-verification">
 458 <h2><a class="toc-backref" href="#id3">1.1&nbsp;&nbsp;&nbsp;Debug and Verification</a></h2>
 459 <pre class="literal-block">
 460 make BUILD=debug BENCHMARK=off
 461 </pre>
 462 <p>Running <tt class="docutils literal">make</tt> with <tt class="docutils literal">BUILD=debug</tt> builds the debug version of
 463 the benchmark kernels, where no optimizations are performed,  line numbers and
 464 debug symbols are included as well as <tt class="docutils literal">DEBUG</tt> will be defined.  The resulting
 465 binary will be found in the <tt class="docutils literal">bin</tt> subdirectory and named
 466 <tt class="docutils literal"><span class="pre">lbmbenchk-linux-&lt;compiler&gt;-debug</span></tt>.</p>
 467 <p>Specifying <tt class="docutils literal">BENCHMARK=off</tt> turns on verification
 468 (<tt class="docutils literal">VERIFICATION=on</tt>), statistics (<tt class="docutils literal">STATISTICS=on</tt>), and VTK output
 469 (<tt class="docutils literal">VTK_OUTPUT=on</tt>) enabled.</p>
 470 <p>Please note that the generated binary will therefore
 471 exhibit a poor performance.</p>
 472 </div>
 473 <div class="section" id="benchmarking">
 474 <h2><a class="toc-backref" href="#id4">1.2&nbsp;&nbsp;&nbsp;Benchmarking</a></h2>
 475 <p>To generate a binary for benchmarking run make with</p>
 476 <pre class="literal-block">
 477 make
 478 </pre>
 479 <p>As default <tt class="docutils literal">BENCHMARK=on</tt> and <tt class="docutils literal">BUILD=release</tt> is set, where
 480 BUILD=release turns optimizations on and <tt class="docutils literal">BENCHMARK=on</tt> disables
 481 verfification, statistics, and VTK output.</p>
 482 </div>
 483 <div class="section" id="release-and-verification">
 484 <h2><a class="toc-backref" href="#id5">1.3&nbsp;&nbsp;&nbsp;Release and Verification</a></h2>
 485 <p>Verification with the debug builds can be extremely slow. Hence verification
 486 capabilities can be build with release builds:</p>
 487 <pre class="literal-block">
 488 make BENCHMARK=off
 489 </pre>
 490 </div>
 491 <div class="section" id="compilers">
 492 <h2><a class="toc-backref" href="#id6">1.4&nbsp;&nbsp;&nbsp;Compilers</a></h2>
 493 <p>Currently only the GCC and Intel compiler under Linux are supported. Between
 494 both configuration can be chosen via <tt class="docutils literal"><span class="pre">CONFIG=linux-gcc</span></tt> or
 495 <tt class="docutils literal"><span class="pre">CONFIG=linux-intel</span></tt>.</p>
 496 </div>
 497 <div class="section" id="cleaning">
 498 <h2><a class="toc-backref" href="#id7">1.5&nbsp;&nbsp;&nbsp;Cleaning</a></h2>
 499 <p>For each configuration and build (debug/release) a subdirectory under the
 500 <tt class="docutils literal">src/obj</tt> directory is created where the dependency and object files are
 501 stored.
 502 With</p>
 503 <pre class="literal-block">
 504 make CONFIG=... BUILD=... clean
 505 </pre>
 506 <p>a specific combination is select and cleaned, whereas with</p>
 507 <pre class="literal-block">
 508 make clean-all
 509 </pre>
 510 <p>all object and dependency files are deleted.</p>
 511 </div>
 512 <div class="section" id="options-summary">
 513 <h2><a class="toc-backref" href="#id8">1.6&nbsp;&nbsp;&nbsp;Options Summary</a></h2>
 514 <p>Options that can be specified when building the framework with make:</p>
 515 <table border="1" class="docutils">
 516 <colgroup>
 517 <col width="8%" />
 518 <col width="13%" />
 519 <col width="7%" />
 520 <col width="72%" />
 521 </colgroup>
 522 <tbody valign="top">
 523 <tr><td>name</td>
 524 <td>values</td>
 525 <td>default</td>
 526 <td>description</td>
 527 </tr>
 528 <tr><td>BENCHMARK</td>
 529 <td>on, off</td>
 530 <td>on</td>
 531 <td>If enabled, disables VERIFICATION, STATISTICS, VTK_OUTPUT. If disabled enables the three former options.</td>
 532 </tr>
 533 <tr><td>BUILD</td>
 534 <td>debug, release</td>
 535 <td>release</td>
 536 <td>No optimization, debug symbols, DEBUG defined.</td>
 537 </tr>
 538 <tr><td>CONFIG</td>
 539 <td>linux-gcc, linux-intel</td>
 540 <td>linux-intel</td>
 541 <td>Select GCC or Intel compiler.</td>
 542 </tr>
 543 <tr><td>ISA</td>
 544 <td>avx, sse</td>
 545 <td>avx</td>
 546 <td>Determines which ISA extension is used for macro definitions. This is <em>not</em> the architecture the compiler generates code for.</td>
 547 </tr>
 548 <tr><td>OPENMP</td>
 549 <td>on, off</td>
 550 <td>on</td>
 551 <td>OpenMP, i.,e.. threading support.</td>
 552 </tr>
 553 <tr><td>STATISTICS</td>
 554 <td>on, off</td>
 555 <td>off</td>
 556 <td>View statistics, like density etc, during simulation.</td>
 557 </tr>
 558 <tr><td>TARCH</td>
 559 <td>--</td>
 560 <td>--</td>
 561 <td>Via TARCH the architecture the compiler generates code for can be overridden. The value depends on the chosen compiler.</td>
 562 </tr>
 563 <tr><td>VERIFICATION</td>
 564 <td>on, off</td>
 565 <td>off</td>
 566 <td>Turn verification on/off.</td>
 567 </tr>
 568 <tr><td>VTK_OUTPUT</td>
 569 <td>on, off</td>
 570 <td>off</td>
 571 <td>Enable/Disable VTK file output.</td>
 572 </tr>
 573 </tbody>
 574 </table>
 575 </div>
 576 </div>
 577 <div class="section" id="invocation">
 578 <h1><a class="toc-backref" href="#id9">2&nbsp;&nbsp;&nbsp;Invocation</a></h1>
 579 <p>Running the binary will print among the GPL licence header a line like the following:</p>
 580 <pre class="literal-block">
 581 LBM Benchmark Kernels 0.1, compiled Jul  5 2017 21:59:22, type: verification
 582 </pre>
 583 <p>if verfication was enabled during compilation or</p>
 584 <pre class="literal-block">
 585 LBM Benchmark Kernels 0.1, compiled Jul  5 2017 21:59:22, type: benchmark
 586 </pre>
 587 <p>if verfication was disabled during compilation.</p>
 588 <div class="section" id="command-line-parameters">
 589 <h2><a class="toc-backref" href="#id10">2.1&nbsp;&nbsp;&nbsp;Command Line Parameters</a></h2>
 590 <p>Running the binary with <tt class="docutils literal"><span class="pre">-h</span></tt> list all available parameters:</p>
 591 <pre class="literal-block">
 592 Usage:
 593 ./lbmbenchk -list
 594 ./lbmbenchk
 595     [-dims XxYyZ] [-geometry box|channel|pipe|blocks[-&lt;block size&gt;]] [-iterations &lt;iterations&gt;] [-lattice-dump-ascii]
 596     [-rho-in &lt;density&gt;] [-rho-out &lt;density] [-omega &lt;omega&gt;] [-kernel &lt;kernel&gt;]
 597     [-periodic-x]
 598     [-t &lt;number of threads&gt;]
 599     [-pin core{,core}*]
 600     [-verify]
 601     -- &lt;kernel specific parameters&gt;
 602
 603 -list           List available kernels.
 604
 605 -dims XxYxZ     Specify geometry dimensions.
 606
 607 -geometry blocks-&lt;block size&gt;
 608                 Geometetry with blocks of size &lt;block size&gt; regularily layout out.
 609 </pre>
 610 <p>If an option is specified multiple times the last one overrides previous ones.
 611 This holds also true for <tt class="docutils literal"><span class="pre">-verify</span></tt> which sets geometry dimensions,
 612 iterations, etc, which can afterward be override, e.g.:</p>
 613 <pre class="literal-block">
 614 $ bin/lbmbenchk-linux-intel-release -verfiy -dims 32x32x32
 615 </pre>
 616 <p>Kernel specific parameters can be opatained via selecting the specific kernel
 617 and passing <tt class="docutils literal"><span class="pre">-h</span></tt> as parameter:</p>
 618 <pre class="literal-block">
 619 $ bin/lbmbenchk-linux-intel-release -kernel kernel-name -- -h
 620 ...
 621 Kernel parameters:
 622 [-blk &lt;n&gt;] [-blk-[xyz] &lt;n&gt;]
 623 </pre>
 624 <p>A list of all available kernels can be obtained via <tt class="docutils literal"><span class="pre">-list</span></tt>:</p>
 625 <pre class="literal-block">
 626 $ ../bin/lbmbenchk-linux-gcc-debug -list
 627 Lattice Boltzmann Benchmark Kernels (LbmBenchKernels) Copyright (C) 2016, 2017 LSS, RRZE
 628 This program comes with ABSOLUTELY NO WARRANTY; for details see LICENSE.
 629 This is free software, and you are welcome to redistribute it under certain conditions.
 630
 631 LBM Benchmark Kernels 0.1, compiled Jul  5 2017 21:59:22, type: verification
 632 Available kernels to benchmark:
 633    list-aa-pv-soa
 634    list-aa-ria-soa
 635    list-aa-soa
 636    list-aa-aos
 637    list-pull-split-nt-1s-soa
 638    list-pull-split-nt-2s-soa
 639    list-push-soa
 640    list-push-aos
 641    list-pull-soa
 642    list-pull-aos
 643    push-soa
 644    push-aos
 645    pull-soa
 646    pull-aos
 647    blk-push-soa
 648    blk-push-aos
 649    blk-pull-soa
 650    blk-pull-aos
 651 </pre>
 652 </div>
 653 <div class="section" id="kernels">
 654 <h2><a class="toc-backref" href="#id11">2.2&nbsp;&nbsp;&nbsp;Kernels</a></h2>
 655 <p>The following list shortly describes available kernels:</p>
 656 <ul class="simple">
 657 <li>push-soa/push-aos/pull-soa/pull-aos:
 658 Unoptimized kernels (but stream/collide are already fused) using two grids as
 659 source and destination. Implement push/pull semantics as well structure of
 660 arrays (soa) or array of structures (aos) layout.</li>
 661 <li>blk-push-soa/blk-push-aos/blk-pull-soa/blk-pull-aos:
 662 The same as the unoptimized kernels without the blk prefix, except that they support
 663 spatial blocking, i.e. loop blocking of the three loops used to iterate over
 664 the lattice. Here manual work sharing for OpenMP is used.</li>
 665 <li>list-push-soa/list-push-aos/list-pull-soa/list-pull-aos:
 666 The same as the unoptimized kernels without the list prefix, but for indirect addressing.
 667 Here only a 1D vector of is used to store the fluid nodes, omitting the
 668 obstacles. An adjacency list is used to recover the neighborhood associations.</li>
 669 <li>list-pull-split-nt-1s-soa/list-pull-split-nt-2s-soa:
 670 Optimized variant of list-pull-soa. Chunks of the lattice are processed as
 671 once. Postcollision values are written back via nontemporal stores in 18 (1s)
 672 or 9 (2s) loops.</li>
 673 <li>list-aa-aos/list-aa-soa:
 674 Unoptimized implementation of the AA pattern for the 1D vector with adjacency
 675 list. Supported are array of structures (aos) and structure of arrays (soa)
 676 data layout is supported.</li>
 677 <li>list-aa-ria-soa:
 678 Implementation of AA pattern with intrinsics for the 1D vector with adjacency
 679 list. Furthermore it contains a vectorized even time step and run length
 680 coding to reduce the loop balance of the odd time step.</li>
 681 <li>list-aa-pv-soa:
 682 All optimizations of list-aa-ria-soa. Additional with partial vectorization
 683 of the odd time step.</li>
 684 </ul>
 685 <p>Note that all array of structures (aos) kernels might require blocking
 686 (depending on the domain size) to reach the performance of their structure of
 687 arrays (soa) counter parts.</p>
 688 <p>The following table summarizes the properties of the kernels. Here <strong>D</strong> means
 689 direct addressing, i.e. full array, <strong>I</strong> means indirect addressing, i.e. 1D
 690 vector with adjacency list, <strong>x</strong> means supported, whereas <strong>--</strong> means unsupported.
 691 The loop balance B_l is computed for D3Q19 model with double precision floating
 692 point for PDFs (8 byte) and 4 byte integers for the index (adjacency list).
 693 As list-aa-ria-soa and list-aa-pv-soa support run length coding their effective
 694 loop balance depends on the geometry. The effective loop balance is printed
 695 during each run.</p>
 696 <table border="1" class="docutils">
 697 <colgroup>
 698 <col width="29%" />
 699 <col width="14%" />
 700 <col width="14%" />
 701 <col width="6%" />
 702 <col width="10%" />
 703 <col width="10%" />
 704 <col width="16%" />
 705 </colgroup>
 706 <thead valign="bottom">
 707 <tr><th class="head">kernel name</th>
 708 <th class="head">prop. step</th>
 709 <th class="head">data layout</th>
 710 <th class="head">addr.</th>
 711 <th class="head">parallel</th>
 712 <th class="head">blocking</th>
 713 <th class="head">B_l [B/FLUP]</th>
 714 </tr>
 715 </thead>
 716 <tbody valign="top">
 717 <tr><td>push-soa</td>
 718 <td>OS</td>
 719 <td>SoA</td>
 720 <td>D</td>
 721 <td>x</td>
 722 <td>--</td>
 723 <td>456</td>
 724 </tr>
 725 <tr><td>push-aos</td>
 726 <td>OS</td>
 727 <td>AoS</td>
 728 <td>D</td>
 729 <td>x</td>
 730 <td>--</td>
 731 <td>456</td>
 732 </tr>
 733 <tr><td>pull-soa</td>
 734 <td>OS</td>
 735 <td>SoA</td>
 736 <td>D</td>
 737 <td>x</td>
 738 <td>--</td>
 739 <td>456</td>
 740 </tr>
 741 <tr><td>pull-aos</td>
 742 <td>OS</td>
 743 <td>AoS</td>
 744 <td>D</td>
 745 <td>x</td>
 746 <td>--</td>
 747 <td>456</td>
 748 </tr>
 749 <tr><td>blk-push-soa</td>
 750 <td>OS</td>
 751 <td>SoA</td>
 752 <td>D</td>
 753 <td>x</td>
 754 <td>x</td>
 755 <td>456</td>
 756 </tr>
 757 <tr><td>blk-push-aos</td>
 758 <td>OS</td>
 759 <td>AoS</td>
 760 <td>D</td>
 761 <td>x</td>
 762 <td>x</td>
 763 <td>456</td>
 764 </tr>
 765 <tr><td>blk-pull-soa</td>
 766 <td>OS</td>
 767 <td>SoA</td>
 768 <td>D</td>
 769 <td>x</td>
 770 <td>x</td>
 771 <td>456</td>
 772 </tr>
 773 <tr><td>blk-pull-aos</td>
 774 <td>OS</td>
 775 <td>AoS</td>
 776 <td>D</td>
 777 <td>x</td>
 778 <td>x</td>
 779 <td>456</td>
 780 </tr>
 781 <tr><td>list-push-soa</td>
 782 <td>OS</td>
 783 <td>SoA</td>
 784 <td>I</td>
 785 <td>x</td>
 786 <td>x</td>
 787 <td>528</td>
 788 </tr>
 789 <tr><td>list-push-aos</td>
 790 <td>OS</td>
 791 <td>AoS</td>
 792 <td>I</td>
 793 <td>x</td>
 794 <td>x</td>
 795 <td>528</td>
 796 </tr>
 797 <tr><td>list-pull-soa</td>
 798 <td>OS</td>
 799 <td>SoA</td>
 800 <td>I</td>
 801 <td>x</td>
 802 <td>x</td>
 803 <td>528</td>
 804 </tr>
 805 <tr><td>list-pull-aos</td>
 806 <td>OS</td>
 807 <td>AoS</td>
 808 <td>I</td>
 809 <td>x</td>
 810 <td>x</td>
 811 <td>528</td>
 812 </tr>
 813 <tr><td>list-pull-split-nt-1s</td>
 814 <td>OS</td>
 815 <td>SoA</td>
 816 <td>I</td>
 817 <td>x</td>
 818 <td>x</td>
 819 <td>376</td>
 820 </tr>
 821 <tr><td>list-pull-split-nt-2s</td>
 822 <td>OS</td>
 823 <td>SoA</td>
 824 <td>I</td>
 825 <td>x</td>
 826 <td>x</td>
 827 <td>376</td>
 828 </tr>
 829 <tr><td>list-aa-soa</td>
 830 <td>AA</td>
 831 <td>SoA</td>
 832 <td>I</td>
 833 <td>x</td>
 834 <td>x</td>
 835 <td>340</td>
 836 </tr>
 837 <tr><td>list-aa-aos</td>
 838 <td>AA</td>
 839 <td>AoS</td>
 840 <td>I</td>
 841 <td>x</td>
 842 <td>x</td>
 843 <td>340</td>
 844 </tr>
 845 <tr><td>list-aa-ria-soa</td>
 846 <td>AA</td>
 847 <td>SoA</td>
 848 <td>I</td>
 849 <td>x</td>
 850 <td>x</td>
 851 <td>304-342</td>
 852 </tr>
 853 <tr><td>list-aa-pv-soa</td>
 854 <td>AA</td>
 855 <td>SoA</td>
 856 <td>I</td>
 857 <td>x</td>
 858 <td>x</td>
 859 <td>304-342</td>
 860 </tr>
 861 </tbody>
 862 </table>
 863 </div>
 864 </div>
 865 <div class="section" id="id1">
 866 <h1><a class="toc-backref" href="#id12">3&nbsp;&nbsp;&nbsp;Benchmarking</a></h1>
 867 <p>Correct benchmarking is a nontrivial task. Whenever benchmark results should be
 868 created make sure the binary was compiled with:</p>
 869 <ul class="simple">
 870 <li><tt class="docutils literal">BENCHMARK=on</tt> (default if not overriden) and</li>
 871 <li><tt class="docutils literal">BUILD=release</tt> (default if not overriden) and</li>
 872 <li>the correct ISA for macros is used, selected via <tt class="docutils literal">ISA</tt> and</li>
 873 <li>use <tt class="docutils literal">TARCH</tt> to specify the architecture the compiler generates code for.</li>
 874 </ul>
 875 <p>During benchmarking pinning should be used via the <tt class="docutils literal"><span class="pre">-pin</span></tt> parameter. Running
 876 a benchmark with 10 threads an pin them to the first 10 cores works like</p>
 877 <pre class="literal-block">
 878 $ bin/lbmbenchk-linux-intel-release ... -t 10 -pin $(seq -s , 0 9)
 879 </pre>
 880 <p>Things the binary does nor check or controll:</p>
 881 <ul class="simple">
 882 <li>transparent huge pages: when allocating memory small 4 KiB pages might be
 883 replaced with larger ones. This is in general a good thing, but if this is
 884 really the case, depends on the system settings (check e.g. the status of
 885 <tt class="docutils literal">/sys/kernel/mm/transparent_hugepage/enabled</tt>).
 886 Currently <tt class="docutils literal">madvise(MADV_HUGEPAGE)</tt> is used for allocations which are aligned to
 887 a 4 KiB page, which should be the case for the lattices.
 888 This should result in huge pages except THP is disabled on the machine.
 889 (NOTE: madvise() is used if <tt class="docutils literal">HAVE_HUGE_PAGES</tt> is defined, which is currently
 890 hard coded defined in <tt class="docutils literal">Memory.c</tt>).</li>
 891 <li>CPU/core frequency: For reproducible results the frequency of all cores
 892 should be fixed.</li>
 893 <li>NUMA placement policy: The benchmark assumes a first touch policy, which
 894 means the memory will be placed at the NUMA domain the touching core is
 895 associated with. If a different policy is in place or the NUMA domain to be
 896 used is already full memory might be allocated in a remote domain. Accesses
 897 to remote domains typically have a higher latency and lower bandwidth.</li>
 898 <li>System load: interference with other application, espcially on desktop
 899 systems should be avoided.</li>
 900 <li>Padding: For SoA based kernels the number of (fluid) nodes is automatically
 901 adjusted so that no cache or TLB thrashing should occur. The parameters are
 902 optimized for current Intel based systems. For more details look into the
 903 padding section.</li>
 904 <li>CPU dispatcher function: the compiler might add different versions of a
 905 function for different ISA extensions. Make sure the code you might think is
 906 executed is actually the code which is executed.</li>
 907 </ul>
 908 <div class="section" id="padding">
 909 <h2><a class="toc-backref" href="#id13">3.1&nbsp;&nbsp;&nbsp;Padding</a></h2>
 910 <p>With correct padding cache and TLB thrashing can be avoided. Therefore the
 911 number of (fluid) nodes used in the data layout is artificially increased.</p>
 912 <p>Currently automatic padding is active for kernels which support it. It can be
 913 controlled via the kernel parameter (i.e. parameter after the <tt class="docutils literal"><span class="pre">--</span></tt>)
 914 <tt class="docutils literal"><span class="pre">-pad</span></tt>. Supported values are <tt class="docutils literal">auto</tt> (default), <tt class="docutils literal">no</tt> (to disable padding),
 915 or a manual padding.</p>
 916 <p>Automatic padding tries to avoid cache and TLB thrashing and pads for a 32
 917 entry (huge pages) TLB with 8 sets and a 512 set (L2) cache. This reflects the
 918 parameters of current Intel based processors.</p>
 919 <p>Manual padding is done via a padding string and has the format
 920 <tt class="docutils literal"><span class="pre">mod_1+offset_1(,mod_n+offset_n)</span></tt>, which specifies numbers of bytes.
 921 SoA data layouts can exhibit TLB thrashing. Therefore we want to distribute the
 922 19 pages with one lattice (36 with two lattices) we are concurrently accessing
 923 over as much sets in the TLB as possible.
 924 This is controlled by the distance between the accessed pages, which is the
 925 number of (fluid) nodes in between them and can be adjusted by adding further
 926 (fluid) nodes.
 927 We want the distance d (in bytes) between two accessed pages to be e.g.
 928 <strong>d % (PAGE_SIZE * TLB_SETS) = PAGE_SIZE</strong>.
 929 This would distribute the pages evenly over the sets. Hereby <strong>PAGE_SIZE * TLB_SETS</strong>
 930 would be our <tt class="docutils literal">mod_1</tt> and <strong>PAGE_SIZE</strong> (after the =) our <tt class="docutils literal">offset_1</tt>.
 931 Measurements show that with only a quarter of half of a page size as offset
 932 higher performance is achieved, which is done by automatic padding.
 933 On top of this padding more paddings can be added. They are just added to the
 934 padding string and are separated by commas.</p>
 935 <p>A zero modulus in the padding string has a special meaning. Here the
 936 corresponding offset is just added to the number of nodes. A padding string
 937 like <tt class="docutils literal"><span class="pre">-pad</span> 0+16</tt> would at a static padding of two nodes (one node = 8 b).</p>
 938 </div>
 939 </div>
 940 <div class="section" id="geometries">
 941 <h1><a class="toc-backref" href="#id14">4&nbsp;&nbsp;&nbsp;Geometries</a></h1>
 942 <p>TODO: supported geometries: channel, pipe, blocks</p>
 943 </div>
 944 <div class="section" id="results">
 945 <h1><a class="toc-backref" href="#id15">5&nbsp;&nbsp;&nbsp;Results</a></h1>
 946 <p>TODO</p>
 947 </div>
 948 <div class="section" id="licence">
 949 <h1><a class="toc-backref" href="#id16">6&nbsp;&nbsp;&nbsp;Licence</a></h1>
 950 <p>The Lattice Boltzmann Benchmark Kernels are licensed under GPLv3.</p>
 951 </div>
 952 <div class="section" id="acknowledgements">
 953 <h1><a class="toc-backref" href="#id17">7&nbsp;&nbsp;&nbsp;Acknowledgements</a></h1>
 954 <p>This work was funded by BMBF, grant no. 01IH15003A (project SKAMPY).</p>
 955 <p>This work was funded by KONWHIR project OMI4PAPS.</p>
 956 <p>Document was generated at 2017-11-02 15:33.</p>
 957 </div>
 958 </div>
 959 </body>
 960 </html>