[Swift-commit] r8056 - www/Swift-T
wozniak at ci.uchicago.edu
wozniak at ci.uchicago.edu
Mon Jul 21 14:20:26 CDT 2014
Author: wozniak
Date: 2014-07-21 14:22:06 -0500 (Mon, 21 Jul 2014)
New Revision: 8056
Added:
www/Swift-T/guide.html
www/Swift-T/turbine-sites.html
Removed:
www/Swift-T/swift.html
Log:
Rename/relink
Added: www/Swift-T/guide.html
===================================================================
--- www/Swift-T/guide.html (rev 0)
+++ www/Swift-T/guide.html 2014-07-21 19:22:06 UTC (rev 8056)
@@ -0,0 +1,3772 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
+ "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+<head>
+<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
+<meta name="generator" content="AsciiDoc 8.6.9" />
+<title>Swift/T Guide</title>
+<style type="text/css">
+/* Shared CSS for AsciiDoc xhtml11 and html5 backends */
+
+/* Default font. */
+body {
+ font-family: Georgia,serif;
+}
+
+/* Title font. */
+h1, h2, h3, h4, h5, h6,
+div.title, caption.title,
+thead, p.table.header,
+#toctitle,
+#author, #revnumber, #revdate, #revremark,
+#footer {
+ font-family: Arial,Helvetica,sans-serif;
+}
+
+body {
+ margin: 1em 5% 1em 5%;
+}
+
+a {
+ color: blue;
+ text-decoration: underline;
+}
+a:visited {
+ color: fuchsia;
+}
+
+em {
+ font-style: italic;
+ color: navy;
+}
+
+strong {
+ font-weight: bold;
+ color: #083194;
+}
+
+h1, h2, h3, h4, h5, h6 {
+ color: #527bbd;
+ margin-top: 1.2em;
+ margin-bottom: 0.5em;
+ line-height: 1.3;
+}
+
+h1, h2, h3 {
+ border-bottom: 2px solid silver;
+}
+h2 {
+ padding-top: 0.5em;
+}
+h3 {
+ float: left;
+}
+h3 + * {
+ clear: left;
+}
+h5 {
+ font-size: 1.0em;
+}
+
+div.sectionbody {
+ margin-left: 0;
+}
+
+hr {
+ border: 1px solid silver;
+}
+
+p {
+ margin-top: 0.5em;
+ margin-bottom: 0.5em;
+}
+
+ul, ol, li > p {
+ margin-top: 0;
+}
+ul > li { color: #aaa; }
+ul > li > * { color: black; }
+
+.monospaced, code, pre {
+ font-family: "Courier New", Courier, monospace;
+ font-size: inherit;
+ color: navy;
+ padding: 0;
+ margin: 0;
+}
+pre {
+ white-space: pre-wrap;
+}
+
+#author {
+ color: #527bbd;
+ font-weight: bold;
+ font-size: 1.1em;
+}
+#email {
+}
+#revnumber, #revdate, #revremark {
+}
+
+#footer {
+ font-size: small;
+ border-top: 2px solid silver;
+ padding-top: 0.5em;
+ margin-top: 4.0em;
+}
+#footer-text {
+ float: left;
+ padding-bottom: 0.5em;
+}
+#footer-badges {
+ float: right;
+ padding-bottom: 0.5em;
+}
+
+#preamble {
+ margin-top: 1.5em;
+ margin-bottom: 1.5em;
+}
+div.imageblock, div.exampleblock, div.verseblock,
+div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
+div.admonitionblock {
+ margin-top: 1.0em;
+ margin-bottom: 1.5em;
+}
+div.admonitionblock {
+ margin-top: 2.0em;
+ margin-bottom: 2.0em;
+ margin-right: 10%;
+ color: #606060;
+}
+
+div.content { /* Block element content. */
+ padding: 0;
+}
+
+/* Block element titles. */
+div.title, caption.title {
+ color: #527bbd;
+ font-weight: bold;
+ text-align: left;
+ margin-top: 1.0em;
+ margin-bottom: 0.5em;
+}
+div.title + * {
+ margin-top: 0;
+}
+
+td div.title:first-child {
+ margin-top: 0.0em;
+}
+div.content div.title:first-child {
+ margin-top: 0.0em;
+}
+div.content + div.title {
+ margin-top: 0.0em;
+}
+
+div.sidebarblock > div.content {
+ background: #ffffee;
+ border: 1px solid #dddddd;
+ border-left: 4px solid #f0f0f0;
+ padding: 0.5em;
+}
+
+div.listingblock > div.content {
+ border: 1px solid #dddddd;
+ border-left: 5px solid #f0f0f0;
+ background: #f8f8f8;
+ padding: 0.5em;
+}
+
+div.quoteblock, div.verseblock {
+ padding-left: 1.0em;
+ margin-left: 1.0em;
+ margin-right: 10%;
+ border-left: 5px solid #f0f0f0;
+ color: #888;
+}
+
+div.quoteblock > div.attribution {
+ padding-top: 0.5em;
+ text-align: right;
+}
+
+div.verseblock > pre.content {
+ font-family: inherit;
+ font-size: inherit;
+}
+div.verseblock > div.attribution {
+ padding-top: 0.75em;
+ text-align: left;
+}
+/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
+div.verseblock + div.attribution {
+ text-align: left;
+}
+
+div.admonitionblock .icon {
+ vertical-align: top;
+ font-size: 1.1em;
+ font-weight: bold;
+ text-decoration: underline;
+ color: #527bbd;
+ padding-right: 0.5em;
+}
+div.admonitionblock td.content {
+ padding-left: 0.5em;
+ border-left: 3px solid #dddddd;
+}
+
+div.exampleblock > div.content {
+ border-left: 3px solid #dddddd;
+ padding-left: 0.5em;
+}
+
+div.imageblock div.content { padding-left: 0; }
+span.image img { border-style: none; vertical-align: text-bottom; }
+a.image:visited { color: white; }
+
+dl {
+ margin-top: 0.8em;
+ margin-bottom: 0.8em;
+}
+dt {
+ margin-top: 0.5em;
+ margin-bottom: 0;
+ font-style: normal;
+ color: navy;
+}
+dd > *:first-child {
+ margin-top: 0.1em;
+}
+
+ul, ol {
+ list-style-position: outside;
+}
+ol.arabic {
+ list-style-type: decimal;
+}
+ol.loweralpha {
+ list-style-type: lower-alpha;
+}
+ol.upperalpha {
+ list-style-type: upper-alpha;
+}
+ol.lowerroman {
+ list-style-type: lower-roman;
+}
+ol.upperroman {
+ list-style-type: upper-roman;
+}
+
+div.compact ul, div.compact ol,
+div.compact p, div.compact p,
+div.compact div, div.compact div {
+ margin-top: 0.1em;
+ margin-bottom: 0.1em;
+}
+
+tfoot {
+ font-weight: bold;
+}
+td > div.verse {
+ white-space: pre;
+}
+
+div.hdlist {
+ margin-top: 0.8em;
+ margin-bottom: 0.8em;
+}
+div.hdlist tr {
+ padding-bottom: 15px;
+}
+dt.hdlist1.strong, td.hdlist1.strong {
+ font-weight: bold;
+}
+td.hdlist1 {
+ vertical-align: top;
+ font-style: normal;
+ padding-right: 0.8em;
+ color: navy;
+}
+td.hdlist2 {
+ vertical-align: top;
+}
+div.hdlist.compact tr {
+ margin: 0;
+ padding-bottom: 0;
+}
+
+.comment {
+ background: yellow;
+}
+
+.footnote, .footnoteref {
+ font-size: 0.8em;
+}
+
+span.footnote, span.footnoteref {
+ vertical-align: super;
+}
+
+#footnotes {
+ margin: 20px 0 20px 0;
+ padding: 7px 0 0 0;
+}
+
+#footnotes div.footnote {
+ margin: 0 0 5px 0;
+}
+
+#footnotes hr {
+ border: none;
+ border-top: 1px solid silver;
+ height: 1px;
+ text-align: left;
+ margin-left: 0;
+ width: 20%;
+ min-width: 100px;
+}
+
+div.colist td {
+ padding-right: 0.5em;
+ padding-bottom: 0.3em;
+ vertical-align: top;
+}
+div.colist td img {
+ margin-top: 0.3em;
+}
+
+ at media print {
+ #footer-badges { display: none; }
+}
+
+#toc {
+ margin-bottom: 2.5em;
+}
+
+#toctitle {
+ color: #527bbd;
+ font-size: 1.1em;
+ font-weight: bold;
+ margin-top: 1.0em;
+ margin-bottom: 0.1em;
+}
+
+div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
+ margin-top: 0;
+ margin-bottom: 0;
+}
+div.toclevel2 {
+ margin-left: 2em;
+ font-size: 0.9em;
+}
+div.toclevel3 {
+ margin-left: 4em;
+ font-size: 0.9em;
+}
+div.toclevel4 {
+ margin-left: 6em;
+ font-size: 0.9em;
+}
+
+span.aqua { color: aqua; }
+span.black { color: black; }
+span.blue { color: blue; }
+span.fuchsia { color: fuchsia; }
+span.gray { color: gray; }
+span.green { color: green; }
+span.lime { color: lime; }
+span.maroon { color: maroon; }
+span.navy { color: navy; }
+span.olive { color: olive; }
+span.purple { color: purple; }
+span.red { color: red; }
+span.silver { color: silver; }
+span.teal { color: teal; }
+span.white { color: white; }
+span.yellow { color: yellow; }
+
+span.aqua-background { background: aqua; }
+span.black-background { background: black; }
+span.blue-background { background: blue; }
+span.fuchsia-background { background: fuchsia; }
+span.gray-background { background: gray; }
+span.green-background { background: green; }
+span.lime-background { background: lime; }
+span.maroon-background { background: maroon; }
+span.navy-background { background: navy; }
+span.olive-background { background: olive; }
+span.purple-background { background: purple; }
+span.red-background { background: red; }
+span.silver-background { background: silver; }
+span.teal-background { background: teal; }
+span.white-background { background: white; }
+span.yellow-background { background: yellow; }
+
+span.big { font-size: 2em; }
+span.small { font-size: 0.6em; }
+
+span.underline { text-decoration: underline; }
+span.overline { text-decoration: overline; }
+span.line-through { text-decoration: line-through; }
+
+div.unbreakable { page-break-inside: avoid; }
+
+
+/*
+ * xhtml11 specific
+ *
+ * */
+
+div.tableblock {
+ margin-top: 1.0em;
+ margin-bottom: 1.5em;
+}
+div.tableblock > table {
+ border: 3px solid #527bbd;
+}
+thead, p.table.header {
+ font-weight: bold;
+ color: #527bbd;
+}
+p.table {
+ margin-top: 0;
+}
+/* Because the table frame attribute is overriden by CSS in most browsers. */
+div.tableblock > table[frame="void"] {
+ border-style: none;
+}
+div.tableblock > table[frame="hsides"] {
+ border-left-style: none;
+ border-right-style: none;
+}
+div.tableblock > table[frame="vsides"] {
+ border-top-style: none;
+ border-bottom-style: none;
+}
+
+
+/*
+ * html5 specific
+ *
+ * */
+
+table.tableblock {
+ margin-top: 1.0em;
+ margin-bottom: 1.5em;
+}
+thead, p.tableblock.header {
+ font-weight: bold;
+ color: #527bbd;
+}
+p.tableblock {
+ margin-top: 0;
+}
+table.tableblock {
+ border-width: 3px;
+ border-spacing: 0px;
+ border-style: solid;
+ border-color: #527bbd;
+ border-collapse: collapse;
+}
+th.tableblock, td.tableblock {
+ border-width: 1px;
+ padding: 4px;
+ border-style: solid;
+ border-color: #527bbd;
+}
+
+table.tableblock.frame-topbot {
+ border-left-style: hidden;
+ border-right-style: hidden;
+}
+table.tableblock.frame-sides {
+ border-top-style: hidden;
+ border-bottom-style: hidden;
+}
+table.tableblock.frame-none {
+ border-style: hidden;
+}
+
+th.tableblock.halign-left, td.tableblock.halign-left {
+ text-align: left;
+}
+th.tableblock.halign-center, td.tableblock.halign-center {
+ text-align: center;
+}
+th.tableblock.halign-right, td.tableblock.halign-right {
+ text-align: right;
+}
+
+th.tableblock.valign-top, td.tableblock.valign-top {
+ vertical-align: top;
+}
+th.tableblock.valign-middle, td.tableblock.valign-middle {
+ vertical-align: middle;
+}
+th.tableblock.valign-bottom, td.tableblock.valign-bottom {
+ vertical-align: bottom;
+}
+
+
+/*
+ * manpage specific
+ *
+ * */
+
+body.manpage h1 {
+ padding-top: 0.5em;
+ padding-bottom: 0.5em;
+ border-top: 2px solid silver;
+ border-bottom: 2px solid silver;
+}
+body.manpage h2 {
+ border-style: none;
+}
+body.manpage div.sectionbody {
+ margin-left: 3em;
+}
+
+ at media print {
+ body.manpage div#toc { display: none; }
+}
+
+
+
+/* SWIFT/T GUIDE CUSTOMIZATIONS */
+
+a:visited {
+ color: gray;
+}
+h5 {
+ font-size: 0.8em;
+}
+
+</style>
+<script type="text/javascript">
+/*<+'])');
+ // Function that scans the DOM tree for header elements (the DOM2
+ // nodeIterator API would be a better technique but not supported by all
+ // browsers).
+ var iterate = function (el) {
+ for (var i = el.firstChild; i != null; i = i.nextSibling) {
+ if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
+ var mo = re.exec(i.tagName);
+ if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
+ result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
+ }
+ iterate(i);
+ }
+ }
+ }
+ iterate(el);
+ return result;
+ }
+
+ var toc = document.getElementById("toc");
+ if (!toc) {
+ return;
+ }
+
+ // Delete existing TOC entries in case we're reloading the TOC.
+ var tocEntriesToRemove = [];
+ var i;
+ for (i = 0; i < toc.childNodes.length; i++) {
+ var entry = toc.childNodes[i];
+ if (entry.nodeName.toLowerCase() == 'div'
+ && entry.getAttribute("class")
+ && entry.getAttribute("class").match(/^toclevel/))
+ tocEntriesToRemove.push(entry);
+ }
+ for (i = 0; i < tocEntriesToRemove.length; i++) {
+ toc.removeChild(tocEntriesToRemove[i]);
+ }
+
+ // Rebuild TOC entries.
+ var entries = tocEntries(document.getElementById("content"), toclevels);
+ for (var i = 0; i < entries.length; ++i) {
+ var entry = entries[i];
+ if (entry.element.id == "")
+ entry.element.id = "_toc_" + i;
+ var a = document.createElement("a");
+ a.href = "#" + entry.element.id;
+ a.appendChild(document.createTextNode(entry.text));
+ var div = document.createElement("div");
+ div.appendChild(a);
+ div.className = "toclevel" + entry.toclevel;
+ toc.appendChild(div);
+ }
+ if (entries.length == 0)
+ toc.parentNode.removeChild(toc);
+},
+
+
+/////////////////////////////////////////////////////////////////////
+// Footnotes generator
+/////////////////////////////////////////////////////////////////////
+
+/* Based on footnote generation code from:
+ * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
+ */
+
+footnotes: function () {
+ // Delete existing footnote entries in case we're reloading the footnodes.
+ var i;
+ var noteholder = document.getElementById("footnotes");
+ if (!noteholder) {
+ return;
+ }
+ var entriesToRemove = [];
+ for (i = 0; i < noteholder.childNodes.length; i++) {
+ var entry = noteholder.childNodes[i];
+ if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") == "footnote")
+ entriesToRemove.push(entry);
+ }
+ for (i = 0; i < entriesToRemove.length; i++) {
+ noteholder.removeChild(entriesToRemove[i]);
+ }
+
+ // Rebuild footnote entries.
+ var cont = document.getElementById("content");
+ var spans = cont.getElementsByTagName("span");
+ var refs = {};
+ var n = 0;
+ for (i=0; i<spans.length; i++) {
+ if (spans[i].className == "footnote") {
+ n++;
+ var note = spans[i].getAttribute("data-note");
+ if (!note) {
+ // Use [\s\S] in place of . so multi-line matches work.
+ // Because JavaScript has no s (dotall) regex flag.
+ note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
+ spans[i].innerHTML =
+ "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
+ "' title='View footnote' class='footnote'>" + n + "</a>]";
+ spans[i].setAttribute("data-note", note);
+ }
+ noteholder.innerHTML +=
+ "<div class='footnote' id='_footnote_" + n + "'>" +
+ "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
+ n + "</a>. " + note + "</div>";
+ var id =spans[i].getAttribute("id");
+ if (id != null) refs["#"+id] = n;
+ }
+ }
+ if (n == 0)
+ noteholder.parentNode.removeChild(noteholder);
+ else {
+ // Process footnoterefs.
+ for (i=0; i<spans.length; i++) {
+ if (spans[i].className == "footnoteref") {
+ var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
+ href = href.match(/#.*/)[0]; // Because IE return full URL.
+ n = refs[href];
+ spans[i].innerHTML =
+ "[<a href='#_footnote_" + n +
+ "' title='View footnote' class='footnote'>" + n + "</a>]";
+ }
+ }
+ }
+},
+
+install: function(toclevels) {
+ var timerId;
+
+ function reinstall() {
+ asciidoc.footnotes();
+ if (toclevels) {
+ asciidoc.toc(toclevels);
+ }
+ }
+
+ function reinstallAndRemoveTimer() {
+ clearInterval(timerId);
+ reinstall();
+ }
+
+ timerId = setInterval(reinstall, 500);
+ if (document.addEventListener)
+ document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);
+ else
+ window.onload = reinstallAndRemoveTimer;
+}
+
+}
+asciidoc.install(2);
+/*]]>*/
+</script>
+</head>
+<body class="article" style="max-width:750px">
+<div id="header">
+<h1>Swift/T Guide</h1>
+<span id="author">v0.6.0, July 2014</span><br />
+<div id="toc">
+ <div id="toctitle">Table of Contents</div>
+ <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
+</div>
+</div>
+<div id="content">
+<div id="preamble">
+<div class="sectionbody">
+<div class="paragraph"><p>The Swift/Turbine Compiler (STC) allows you to write Swift programs
+and run them using Turbine.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_support">1. Support</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>An overview of Swift/T may be found at the ExM project site:</p></div>
+<div class="paragraph"><p><a href="https://sites.google.com/site/exmcomputing">https://sites.google.com/site/exmcomputing</a></p></div>
+<div class="paragraph"><p>The Swift/T user discussion mailing list is found here:</p></div>
+<div class="paragraph"><p><a href="http://lists.mcs.anl.gov/mailman/listinfo/exm-user">http://lists.mcs.anl.gov/mailman/listinfo/exm-user</a></p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_installation">2. Installation</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Writing and running Swift/Turbine programs requires multiple packages.
+This section provides generic instructions for installing Swift/T
+on a range of systems. We first cover locating and/or installing
+prerequisite software packages, then we cover building Swift/T
+from a source package.</p></div>
+<div class="paragraph"><p>The <a href="turbine-sites.html">Turbine Sites Guide</a>
+is a accompanying resource for configuration settings and preinstalled software
+for specific systems.</p></div>
+<div class="sect2">
+<h3 id="_installation_of_prerequisites">2.1. Installation of Prerequisites</h3>
+<div class="olist arabic"><ol class="arabic">
+<li>
+<p>
+Install or locate MPI implementation (MPICH, OpenMPI, etc.)
+</p>
+<div class="ulist"><ul>
+<li>
+<p>
+On compute clusters, an MPI will almost certainly be pre-installed
+</p>
+</li>
+<li>
+<p>
+Many operating systems provide packages with MPI implementations
+ that are usable, but often outdated.
+ E.g. the <code>mpich2</code> package on Debian/Ubuntu.
+</p>
+</li>
+<li>
+<p>
+See <a href="http://www.mpich.org">MPICH Guides</a> for information on installing the
+ latest version of MPICH.
+</p>
+</li>
+<li>
+<p>
+Other MPI implementations are <a href="#Build_configuration">supported</a> as well.
+</p>
+<div class="paragraph"><p>Swift/T attempts to use MPI 3.0 functionality by default. If you
+are using an MPI implementation that does not support the MPI 3.0 standard,
+you must set <code>MPI_VERSION=2</code> (if using the <code>exm-setup.zsh</code> build process),
+or provide the <code>--enable-mpi-2</code> configure option (if using
+the manual build process).</p></div>
+</li>
+</ul></div>
+</li>
+<li>
+<p>
+Install or locate Tcl 8.6.
+</p>
+<div class="ulist"><ul>
+<li>
+<p>
+Tcl is available through the package manager on many systems.
+ You may need to install an additional Tcl development package
+ in addition to the standard tcl package,
+ e.g. <code>tcl8.6</code> plus <code>tcl8.6-dev</code> on Debian/Ubuntu systems.
+</p>
+</li>
+<li>
+<p>
+Source distributions are available at the <a href="http://www.tcl.tk">Tcl web site</a>
+</p>
+</li>
+</ul></div>
+</li>
+<li>
+<p>
+Install or locate SWIG
+</p>
+<div class="ulist"><ul>
+<li>
+<p>
+You can check if SWIG is installed by running <code>swig -version</code>
+</p>
+</li>
+<li>
+<p>
+SWIG is available through the package manager on many systems.
+</p>
+</li>
+<li>
+<p>
+Source distributions are available at
+ the <a href="http://swig.org">SWIG web site</a>
+</p>
+</li>
+</ul></div>
+</li>
+</ol></div>
+</div>
+<div class="sect2">
+<h3 id="_installation_of_swift_t_from_source">2.2. Installation of Swift/T from Source</h3>
+<div class="paragraph"><p>Once you have found all prerequisites, we can continue with building
+Swift/T from source.</p></div>
+<div class="olist arabic"><ol class="arabic">
+<li>
+<p>
+Obtain the Swift/T source package
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code>wget http://www.mcs.anl.gov/exm/local/downloads/exm-0.5.0.tar.gz</code></pre>
+</div></div>
+<div class="paragraph"><p>Cf. <a href="http://www.mcs.anl.gov/exm/local/downloads/downloads.html">Swift/T Downloads</a>
+for other packages</p></div>
+</li>
+<li>
+<p>
+Unpack and enter package directory
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code>tar xfz exm-trunk.tar.gz
+cd exm-trunk</code></pre>
+</div></div>
+</li>
+<li>
+<p>
+Edit the settings file: <code>exm-settings.sh</code>
+</p>
+<div class="paragraph"><p>At a minimum, you must set the install directory with <code>EXM_PREFIX</code>.
+On a standard system, no further configuration may be needed.
+In many cases, however, you will need to modify additional
+configuration settings so that all prerequisites can
+be correctly located and configured (see Section
+<a href="#Build_configuration">Build configuration</a>).</p></div>
+<div class="paragraph"><p>A range of other settings are also available here:
+enabling/disabling features, debug or optimized builds, etc.</p></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Tip</div>
+</td>
+<td class="content">Save your <code>exm-settings.sh</code> when you download a new package</td>
+</tr></table>
+</div>
+</li>
+<li>
+<p>
+Run the setup script
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code>./exm-setup.zsh</code></pre>
+</div></div>
+<div class="paragraph"><p>If <code>exm-setup.zsh</code> does not succeed on your system, see Section
+<a href="#Build_configuration">Build configuration</a> below.</p></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Tip</div>
+</td>
+<td class="content">if you want more control than <code>exm-setup.zsh</code> provides, you can
+ build Swift/T with the
+ <a href="#Manual_build_configuration">manual configure/make workflow</a>.</td>
+</tr></table>
+</div>
+</li>
+<li>
+<p>
+Add Turbine and STC to your paths
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code>PATH=${PATH}:/path/to/exm-install/turbine/bin
+PATH=${PATH}:/path/to/exm-install/stc/bin</code></pre>
+</div></div>
+</li>
+</ol></div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_usage">3. Usage</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Swift code is conventionally written in <code>*.swift</code> files. Turbine
+code is stored in Tcl files <code>*.tcl</code>. After writing the Swift program
+<code>program.swift</code>, run:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>stc program.swift</code></pre>
+</div></div>
+<div class="paragraph"><p>This will compile the program to <code>program.tcl</code>. A second, optional
+argument may be given as an alternate output file name.</p></div>
+<div class="paragraph"><p>Then, to run the program, use Turbine:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>turbine -n 4 program.tcl</code></pre>
+</div></div>
+<div class="paragraph"><p>See the <a href="#Turbine">Turbine section</a> for more information about
+running the program.</p></div>
+<div class="paragraph" id="stc_arguments"><p>STC accepts the following arguments:</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<code>-A <em>name</em>=<em>value</em></code>
+</dt>
+<dd>
+<p>
+Set a command-line argument at
+compile-time. This may be found at runtime using the Swift
+<a href="#argv">argument processing</a> library. This option enables these
+arguments to be treated as compile-time constants for optimization.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>-D <em>macro</em>=<em>value</em></code>
+</dt>
+<dd>
+<p>
+Define a C preprocessor macro.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>-E</code>
+</dt>
+<dd>
+<p>
+Just run the C preprocessor: do not compile the program. The
+output goes into the STC output file (the second file name argument).
+</p>
+</dd>
+<dt class="hdlist1">
+<code>-I</code>
+</dt>
+<dd>
+<p>
+Add a directory to the import and include search path.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>-O</code>
+</dt>
+<dd>
+<p>
+Set optimization level: 0, 1, 2, or 3. See <a href="#Optimizations">[Optimizations]</a>.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>-j</code>
+</dt>
+<dd>
+<p>
+Set the location of the <code>java</code> executable.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>-p</code>
+</dt>
+<dd>
+<p>
+Disable the C preprocessor.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>-u</code>
+</dt>
+<dd>
+<p>
+Only compile if output file is not up-to-date.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>-v</code>
+</dt>
+<dd>
+<p>
+Output version number and exit.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>-V</code>
+</dt>
+<dd>
+<p>
+Verbose output.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>STC runs as a Java program. You may use <code>-j</code> to set the Java VM
+executable. This Java VM must be compatible with the <code>javac</code> used to
+compile STC.</p></div>
+<div class="paragraph"><p>By default, STC runs the user script through the C preprocessor
+(<code>cpp</code>), enabling arbitrary macro processing, etc. The <code>-D</code>, <code>-E</code>,
+<code>-I</code>, and <code>-p</code> options are relevant to this feature.</p></div>
+<div class="paragraph"><p>Additional arguments for advanced users/developers:</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<code>-C</code>
+</dt>
+<dd>
+<p>
+Specify an output file for STC internal representation
+</p>
+</dd>
+<dt class="hdlist1">
+<code>-l</code>
+</dt>
+<dd>
+<p>
+Specify log file for STC debug log
+</p>
+</dd>
+<dt class="hdlist1">
+<code>-L</code>
+</dt>
+<dd>
+<p>
+Specify log file for more verbose STC debug log
+</p>
+</dd>
+<dt class="hdlist1">
+<code>-T</code>
+</dt>
+<dd>
+<p>
+Enable a specific optimization. See <a href="#Optimizations">[Optimizations]</a>
+</p>
+</dd>
+<dt class="hdlist1">
+<code>-t</code>
+</dt>
+<dd>
+<p>
+Disable a specific compiler optimization. See <a href="#Optimizations">[Optimizations]</a>
+</p>
+</dd>
+</dl></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_program_structure">4. Program structure</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Swift programs are composed of <em>composite</em> functions. These
+share syntax with C-like languages. The program starts in <code>main()</code>.
+The following is a complete Swift program:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>main
+{}</code></pre>
+</div></div>
+<div class="paragraph"><p>STC input is preprocessed by <code>cpp</code>, the C preprocessor.</p></div>
+<div class="paragraph"><p>Hello world is written as:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>import io;
+main
+{
+ printf("Hello world");
+}</code></pre>
+</div></div>
+<div class="paragraph"><p>The newline is supplied by <code>printf()</code>.</p></div>
+<div class="paragraph"><p>Swift programs eventually call <em>leaf</em> functions, which are the primary
+way to do work. From the perspective of the Swift script, they are
+atomic operations that wait for input variables and set output
+variables. They may be implemented as native code functions or
+external application programs.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_comments">5. Comments</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Swift supports C/C++-style comments:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>// This is a comment
+/* This is a
+comment */
+/** Also a
+comment */</code></pre>
+</div></div>
+<div class="paragraph"><p>Additionally, if the preprocessor is disabled, single-line comments
+starting with # are supported:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code># This will work if source file is not preprocessed</code></pre>
+</div></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_modules">6. Modules</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Swift has a module system that allows you to import function and variable
+definitions into your source file. Importing a module will import all
+function and variable definitions from that module into your program.</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>import io;
+import mypackage.mymodule;</code></pre>
+</div></div>
+<div class="paragraph"><p>The mechanisms for locating source files is as follows:</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+STC searches a list of directories in order to find a Swift source
+ file in the correct directory with the correct name.
+</p>
+</li>
+<li>
+<p>
+The standard library is always first on the search path,
+ and the current working directory is last.
+</p>
+</li>
+<li>
+<p>
+Additional directories can be added with the <code>-I</code> option to STC.
+</p>
+</li>
+<li>
+<p>
+Swift source files must have a <code>.swift</code> suffix. E.g. <code>import io;</code>
+ looks for a file called <code>io.swift</code>.
+</p>
+</li>
+<li>
+<p>
+In the case of a multi-part import name, E.g. <code>import mypackage.mymodule</code>,
+ then, it looks for <code>mymodule.swift</code> in subdirectory <code>mypackage</code>.
+</p>
+</li>
+</ul></div>
+<div class="paragraph"><p>The alternative <code>#include</code> statement textually includes an entire
+file using the C preprocessor at the point of the statement.
+Note that <code>#include</code> will only work if the preprocessor is enabled
+on the current file. In contrast to <code>import</code>, <code>#include</code> will run the
+C preprocessor on any included modules. <code>import</code> is recommended over
+<code>#include</code> unless the imported module requires preprocessing.</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>#include <mypackage/mymodule.swift></code></pre>
+</div></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_dataflow_evaluation">7. Dataflow evaluation</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Swift expressions are evaluated in <em>dataflow</em> order:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>int z1,z2;
+int y;
+int x = f(y);
+y = g(2);
+z1 = h(x,y,1);
+z2 = h(x,y,2);
+int output = r(z1,z2);</code></pre>
+</div></div>
+<div class="paragraph"><p>This allows code to execute as concurrently as possible, limited
+only by data availability. In this example, <code>g()</code> runs first, because it
+is dependent only on a literal. When <code>y</code> is set, <code>f()</code> runs, setting
+<code>x</code>. Then, two invocations of <code>h()</code> execute. Finally, <code>z1</code> and <code>z2</code>
+are set, allowing <code>r()</code> to run.</p></div>
+<div class="paragraph"><p>Variables may be assigned only once. Multiple assignment is often
+detected at compile time, and will always be detected at run time,
+resulting in a run time error. If variable is not assigned,
+expressions that depend on the variable cannot execute. If the variable
+is never assigned during the course of program execution, these
+expressions will never execute. Upon program completion, Swift/T will
+report the error and print debug information about any unexecuted
+expressions and identifiers of corresponding unassigned variables.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_composite_functions">8. Composite functions</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Swift code is written in composite functions. The composite function
+<code>main</code> is required.</p></div>
+<div class="paragraph"><p>Composite functions have the form:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>[(<output list>)] function_name [(<input list>)]
+{
+ statement;
+ statement;
+ ...
+}</code></pre>
+</div></div>
+<div class="paragraph"><p>An empty input or output list may be omitted or written as <code>()</code>.</p></div>
+<div class="paragraph"><p>The output list may have more than one entry. Thus, assignments
+may be written as:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>x1, x2 = f(i1, i2);
+// or equivalently:
+(x1, x2) = f(i1, i2);</code></pre>
+</div></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_types">9. Types</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Swift provides a similar range of primitive types to many other
+programming languages. Files are a primitive type in Swift, unlike
+in many other languages, and have a number of special characteristics
+that merit special mention.
+Two basic kinds of data structure are provided: arrays and structs.</p></div>
+<div class="sect2">
+<h3 id="_primitive_types">9.1. Primitive types</h3>
+<div class="paragraph"><p>Swift has the conventional types:</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<code>string</code>
+</dt>
+<dd>
+<p>
+A complete string (not an array of characters).
+</p>
+</dd>
+<dt class="hdlist1">
+<code>int</code>
+</dt>
+<dd>
+<p>
+A 64-bit integer.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>float</code>
+</dt>
+<dd>
+<p>
+A 64-bit (double-precision) floating point number.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>boolean</code>
+</dt>
+<dd>
+<p>
+A boolean (true/false).
+</p>
+</dd>
+<dt class="hdlist1">
+<code>file</code>
+</dt>
+<dd>
+<p>
+A file (see Section Files).
+</p>
+</dd>
+<dt class="hdlist1">
+<code>blob</code>
+</dt>
+<dd>
+<p>
+External byte data (see Section Blobs).
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Literals for these types use conventional syntax:</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+<code>int</code> literals are written as decimal numbers, e.g. <code>-1234</code>
+</p>
+</li>
+<li>
+<p>
+<code>float</code> literals are written as decimal numbers with a decimal point,
+ e.g <code>5493.352</code> or <code>1.0</code>.
+ Scientific notation may be used,
+ as in <code>2.3e-2</code> which is equivalent to <code>0.023</code>.
+ The literals <code>NaN</code> and <code>inf</code> may be used. In some contexts <code>int</code>
+ literals are promoted automatically to <code>float</code>.
+</p>
+</li>
+<li>
+<p>
+<code>boolean</code> literals <code>true</code> and <code>false</code> may be used.
+</p>
+</li>
+<li>
+<p>
+<code>string</code> literals are enclosed in double quotes, with a range of escape
+ sequences supported:
+</p>
+<div class="ulist"><ul>
+<li>
+<p>
+<code>\\</code> for a single backslash
+</p>
+</li>
+<li>
+<p>
+<code>\"</code> for a quote
+</p>
+</li>
+<li>
+<p>
+<code>\n</code> for newline
+</p>
+</li>
+<li>
+<p>
+<code>\t</code> for tab
+</p>
+</li>
+<li>
+<p>
+<code>\a</code> (alarm)
+</p>
+</li>
+<li>
+<p>
+<code>\b</code> (backspace)
+</p>
+</li>
+<li>
+<p>
+<code>\f</code> (form feed)
+</p>
+</li>
+<li>
+<p>
+<code>\r</code> (carriage return)
+</p>
+</li>
+<li>
+<p>
+<code>\v</code> (vertical tab)
+</p>
+</li>
+<li>
+<p>
+octal escape codes, e.g. <code>\001</code>
+</p>
+</li>
+<li>
+<p>
+hexadecimal escape codes, e.g. <code>\xf2</code>
+</p>
+</li>
+<li>
+<p>
+For more information: <a href="http://en.wikipedia.org/wiki/US-ASCII#ASCII_control_code_chart">ASCII control codes</a>.
+</p>
+</li>
+</ul></div>
+</li>
+<li>
+<p>
+Multi-line strings may be used in two syntaxes:
+</p>
+<div class="ulist"><ul>
+<li>
+<p>
+Python-style:
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code>string s =
+"""
+line data 1
+line data 2
+""";</code></pre>
+</div></div>
+</li>
+<li>
+<p>
+Asciidoc-style: like Python-style but use 4 dashes instead of 3 quotes.
+</p>
+</li>
+<li>
+<p>
+<strong>Note:</strong> Multi-line strings are somewhat incompatible with the C preprocessor:
+ if you try to compile a Swift program using multi-line strings with
+ the preprocessor enabled, you will likely see warnings or strange
+ behavior. To disable the C preprocessor, use the <code>-p</code> option
+ to STC.
+</p>
+</li>
+</ul></div>
+</li>
+</ul></div>
+</div>
+<div class="sect2">
+<h3 id="_files">9.2. Files</h3>
+<div class="paragraph"><p>A file is a first-class entity in Swift that in many ways can be treated
+as any other variable. The main difference is that a file can be
+<strong>mapped</strong> to path in a filesystem. Assigning to a mapped file variable
+results in a file being created in the file system at the specified path.
+File paths can be arbitrary Swift expressions of type <code>string</code>. Absolute
+paths or relative paths are specified, with relative paths interpreted
+relative to the path in which turbine was run.
+File variables can also be initialized with data from a pre-existing
+file using the <code>input_file</code> function. File paths are relative to the
+working directory for Turbine.</p></div>
+<div class="paragraph"><p>For example, if <code>/home/user/in.txt</code> is a file with some data in it,
+the following Swift program will copy the file to <code>/home/user/out.txt</code>.</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>main
+{
+ file x = input_file("/home/user/in.txt");
+ file y <"/home/user/out.txt">; // Declare a mapped file
+ y = x; // Do the copy
+}</code></pre>
+</div></div>
+<div class="paragraph"><p>A range of functions to work with files are provided in the
+<code>files</code> library module.</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>// Initialize an array of files from a range of files on disk with glob
+file f[] = glob("directory/*.txt");
+
+// Read the contents of a file with read
+string filename = "in.txt";
+string contents = read(input_file(filename));
+trace("Contents of " + filename + ":\n" + contents);
+
+// Write directly to a file with write
+file tmp = write("first line\nsecond line");
+
+// Find the name of a file with filename
+trace("Temporary filename is: " + filename(tmp));</code></pre>
+</div></div>
+<div class="paragraph"><p>Temporary files are created as necessary if unmapped files are
+written to. For example, the file <code>tmp</code> in the above code snippet.
+This feature is implemented by calling GNU <code>mktemp</code> with suffix
+<code>.turbine</code>; thus, the directory is set with environment variable
+<code>TMPDIR</code> which defaults to <code>/tmp</code>.</p></div>
+<div class="paragraph"><p>Currently Swift/T assumes that the file system is shared among
+all nodes.</p></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">
+<div class="paragraph"><p>The syntax</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>file f<"f.txt"> = g();</code></pre>
+</div></div>
+<div class="paragraph"><p>is allowed but</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>file f<"f.txt">=g();</code></pre>
+</div></div>
+<div class="paragraph"><p>results in a parse error: the <code>>=</code> sequence is tokenized as
+<em>greater-than-or-equal-to</em>.</p></div>
+</td>
+</tr></table>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_blobs">9.3. Blobs</h3>
+<div class="paragraph"><p>Blobs represent raw byte data. They are primarily used to pass
+data to and from native code libraries callable from Swift. They are
+like Swift strings but may contain arbitrary data.</p></div>
+<div class="paragraph"><p>Swift provides multiple builtin functions to create blobs, convert
+blobs to and from Swift types, and pass blobs to leaf functions.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_arrays">9.4. Arrays</h3>
+<div class="paragraph"><p>Arrays can be declared with empty square brackets:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>int A[];</code></pre>
+</div></div>
+<div class="paragraph"><p>Arrays with empty square brackets have integer indices. It is
+also possible to declare integers with other index types, such as
+strings:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>string dict[string];</code></pre>
+</div></div>
+<div class="paragraph"><p>They are dynamically sized, expanding each time an item is inserted at
+a new index. Arrays are indexed using square brackets.</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>int A[string];
+int B[];
+B = function_returning_array();
+A["zero"] = B[0];
+A["one"] = B[1];</code></pre>
+</div></div>
+<div class="paragraph"><p>Each array index can only be assigned to once.</p></div>
+<div class="paragraph"><p>A given array variable must be assigned either <em>in toto</em> (as a whole)
+or <em>in partes</em> (piece by piece). In this example, <code>B</code> is assigned in toto
+and <code>A</code> is assigned in partes. Code that attempts to do both is in error.</p></div>
+<div class="paragraph"><p>Arrays may be used as inputs or outputs of functions.</p></div>
+<div class="paragraph"><p>Arrays are part of Swift dataflow semantics. An array is closed
+when all possible insertions to it are complete.</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>(int B[]) f(int j)
+{
+ int A[];
+ A = subroutine_function(1);
+
+ // Error: A has already been assigned in toto:
+ A[3] = 4;
+
+ // OK: assigning to output variable
+ B = subroutine_function(2);
+}</code></pre>
+</div></div>
+<div class="paragraph"><p>Array literals may be expressed using the range operator:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>int start = 0;
+int stop = 10;
+int step = 2;
+// Array of length 10:
+int A[] = [start:stop];
+// Array of length 5, containing only even numbers:
+int B[] = [start:stop:step];</code></pre>
+</div></div>
+<div class="paragraph"><p>Array literals may also be expressed with list syntax:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>int C[] = [4,5,6];</code></pre>
+</div></div>
+</div>
+<div class="sect2">
+<h3 id="_nested_arrays">9.5. Nested arrays</h3>
+<div class="paragraph"><p>Swift allows arrays of arrays: nested arrays. They can be declared and
+assigned as follows:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>// An array of arrays of files with string keys
+file A[string][string];
+A["foo"]["bar"] = input_file("test.txt");
+A["foo"]["qux"] = input_file("test2.txt");</code></pre>
+</div></div>
+<div class="paragraph"><p><strong>Note:</strong> there is currently a limitation in assignment of nested arrays
+that a given array can only be assigned at a single "index level". If
+<code>A</code> is a 2D array, for example, then you cannot mix assignments specifying
+one index (e.g. <code>A[i] = …</code>) with assignments specifying three indices
+(e.g. <code>A[i][j] = …</code>).</p></div>
+</div>
+<div class="sect2">
+<h3 id="_structs">9.6. Structs</h3>
+<div class="paragraph"><p>In Swift, structs are defined with the <code>type</code> keyword. They define
+a new type.</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>type person
+{
+ string name;
+ int age;
+ int events[];
+}</code></pre>
+</div></div>
+<div class="paragraph"><p>Structs are accessed with the <code>.</code> syntax:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>person p;
+p.name = "Abe";
+p.age = 90;</code></pre>
+</div></div>
+<div class="paragraph"><p>It is possible to have arrays of structs, with some restriction on
+how they can be assigned. Each struct in the array must be assigned
+<em>in toto</em> (as a whole). For example, the following code is valid:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>person people[], p1, p2;
+
+p1.name = "Thelma";
+p1.age = 31;
+
+p2.name = "Louise";
+p2.age = 29;
+
+people[0] = p1;
+people[1] = p2;</code></pre>
+</div></div>
+<div class="paragraph"><p>However, attempting to assign the structs in the following way is
+currently unsupported:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>people[2].name = "Abe"; // Not supported!
+people[2].age = 90; // Not supported!</code></pre>
+</div></div>
+</div>
+<div class="sect2">
+<h3 id="_defining_new_types">9.7. Defining new types</h3>
+<div class="paragraph"><p>Swift has two ways to define new types based on existing types.</p></div>
+<div class="paragraph"><p>The first is <code>typedef</code>, which creates a new name for the type.
+The new type and the existing type will be completely interchangeable,
+since they are simply different names for the same underlying type.
+The new type name simply serves to improve readability or documentation.</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>typedef newint int;
+
+main {
+ // We can freely convert between int and newint
+ newint x = 1;
+ int y = x;
+ newint z = y;
+}</code></pre>
+</div></div>
+<div class="paragraph"><p>The second is with <code>type</code>, which creates a new type that is a
+specialization of an existing type. That is, it is a distinct
+type that is not interchangeable. A specialized type can be
+converted into the original type, but the reverse transformation is
+not possible. This means that you can write functions that are more
+strictly typechecked, for example, only accepted particular types of
+file.</p></div>
+<div class="paragraph"><p><strong>Note:</strong> This feature is immature, so you will have a higher probability
+of encountering compiler bugs or limitations.</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>typedef sorted_file file;
+app (sorted_file out) sort (file i) {
+ "/usr/bin/sort" "-o" out i
+}
+
+// uniq utility requires sorted input
+app (file o) unique (sorted_file i) {
+ "/usr/bin/uniq" i @stdout=o
+}
+
+main {
+ file unsorted = input_file("input.txt");
+ sorted_file sorted <"sorted.txt"> = sort(unsorted);
+ file u <"unique.txt"> = unique(sorted);
+
+ // Can convert from sorted_file to file
+ file result2 = sort(unsorted);
+
+ // This would cause a type error
+ // sorted_file not_sorted = unsorted;
+}</code></pre>
+</div></div>
+</div>
+<div class="sect2">
+<h3 id="_global_constants">9.8. Global Constants</h3>
+<div class="paragraph"><p>Swift supports a basic feature for defining globally visible constants. You
+can use the <code>global const</code> statement at the top level of the program. The
+syntax only supports literals of scalar types: e.g. integer literals, floating
+point literals and string literals.</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>global const string hello = "Hello World";
+global const float pi_approx = 3.142;
+global const int ONE = 1;
+
+main () {
+ trace(hello, pi_approx, ONE);
+}</code></pre>
+</div></div>
+<div class="paragraph"><p><strong>Note:</strong> global constants provide no performance benefit compared with
+variables initialized to constant values at optimization levels <code>O1</code>
+or greater.</p></div>
+<div class="paragraph"><p><strong>Note:</strong> better support is planned in future for more flexible support for
+global variables and code.</p></div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_control_structures">10. Control structures</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Swift provides control structures that may be placed as statements
+inside a composite function.</p></div>
+<div class="sect2">
+<h3 id="_conditionals">10.1. Conditionals</h3>
+<div class="sect3">
+<h4 id="_if_statement">10.1.1. If statement</h4>
+<div class="paragraph"><p>If statements have the form:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>if (<condition>)
+{
+ statement;
+ ...
+}
+else
+{
+ statement;
+ ...
+}</code></pre>
+</div></div>
+<div class="paragraph"><p>As required by dataflow processing, neither branch of the conditional can
+execute until the value of the condition expression is available.</p></div>
+</div>
+<div class="sect3">
+<h4 id="_switch_statement">10.1.2. Switch statement</h4>
+<div class="listingblock">
+<div class="content">
+<pre><code>int a = 20;
+switch (a)
+{
+ case 1:
+ int c;
+ c = a + a;
+ b = a + 1;
+ case 20:
+ b = 1;
+ case 2000:
+ b = 2;
+ default:
+ b = 2102 + 2420;
+}
+printf("b: %i\n", b);</code></pre>
+</div></div>
+<div class="paragraph"><p><strong>Note:</strong> there is no fall-through between cases in switch statements.</p></div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_iteration">10.2. Iteration</h3>
+<div class="paragraph"><p>Iteration is performed with the <code>foreach</code> and <code>for</code> statements.</p></div>
+<div class="sect3">
+<h4 id="_foreach_loop">10.2.1. Foreach loop</h4>
+<div class="paragraph"><p>The <code>foreach</code> loop allows for parallel iteration over an array:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>string A[];
+foreach value, index in A
+{
+ printf("A[%i] = %s\n", index, value);
+}</code></pre>
+</div></div>
+<div class="paragraph"><p>The <code>index</code> and <code>value</code> variables are automatically declared. The
+<code>index</code> variable may be omitted from the syntax.</p></div>
+<div class="paragraph"><p>A special case of the foreach loop occurs when combined with the
+array range operator. This is the idiomatic way to iterate over
+a range of integer values in Swift. The STC compiler has special
+handling for this case that avoids constructing an array.</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>foreach i in [start:stop:step] {
+ ...
+}</code></pre>
+</div></div>
+</div>
+<div class="sect3">
+<h4 id="_for_loop">10.2.2. For loop</h4>
+<div class="paragraph"><p>The <code>for</code> loop allows for sequential iteration. This example
+implements a counter based on the return values of a function that
+accepts integers:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>int N = 100;
+int count = 0;
+for (int i = 0; i < N; i = i+1, count = count+c)
+{
+ int c;
+ if (condition_function(i))
+ {
+ c = 1;
+ }
+ else
+ {
+ c = 0;
+ }
+}</code></pre>
+</div></div>
+<div class="paragraph"><p>The general form is:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>for ( <initializer> ; <condition> ; <updates> )
+{
+ statement;
+ ...
+}</code></pre>
+</div></div>
+<div class="paragraph"><p>The initializer is executed first, once. The initializer is a
+comma-separated list of statements. The body statements are then
+executed. Then, the assignments are performed, formatted as a
+comma-separated list. Each is a special assignment in which the
+left-hand-side is the variable in the <em>next</em> iteration of the loop,
+while the right-hand-side is the variable in the <em>previous</em> loop
+iteration. Then, the condition is checked for loop exit. If the loop
+continues, the body is executed again, etc.</p></div>
+<div class="paragraph"><p><strong>Performance Tip:</strong> use the <code>foreach</code> loop instead of <code>for</code> if your
+loop iterations are independent and can be executed in parallel.</p></div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_explicit_data_dependent_execution">10.3. Explicit data-dependent execution</h3>
+<div class="paragraph"><p>In general, execution ordering in Swift/T is implicit and driven by
+data dependencies. In some cases it is useful to add explicit data
+dependencies, for example if you want to print a message to indicate
+that variable was assigned. It is possible for the programmer to
+express additional execution ordering using two constructs: the <code>wait</code>
+statement and the <code>=></code> chaining operator.</p></div>
+<div class="paragraph"><p>In a wait statement, a block of code is executed after
+one or more variables are closed.</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>x = f();
+y = g();
+wait (x) {
+ trace("x is closed!");
+}
+wait(x, y) {
+ trace("x and y are closed!");
+}</code></pre>
+</div></div>
+<div class="paragraph"><p>The chaining operator chains statements together so that a
+statement only executes after the previous statement’s output
+value is closed. This is
+a more concise way to express dependencies than the <code>wait</code> statement.</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>sleep(1) =>
+ x = f() =>
+ int y = g() =>
+ trace("DONE!");</code></pre>
+</div></div>
+<div class="paragraph"><p>Chaining is based on the <strong>output values</strong>
+of a statement. In the simple case of a function call <code>f() => …</code>,
+the output values are the output values of the function. In the
+case of and assignment <code>x = f() => …</code> or a declaration,
+<code>int y = g() => …</code>, then the next statement is dependent on
+the assigned values, or the declared values. Some functions such
+as <code>sleep</code> have <code>void</code> output values so that they can be used
+in this fashion.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_scoping_blocks">10.4. Scoping blocks</h3>
+<div class="paragraph"><p>Arbitrary scoping blocks may be used. In this example, two different
+variables, both represented by <code>b</code>, are assigned different values.</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>{
+ int b;
+ b = 1;
+}
+{
+ int b;
+ b = 2;
+}</code></pre>
+</div></div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_operators">11. Operators</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The following binary arithmetic operators on numbers are defined:</p></div>
+<div class="paragraph"><p><code>+</code> (plus), <code>-</code> (minus), <code>*</code> (times), <code>/</code> (divide),
+<code>%/</code> (integer divide), <code>%%</code> (modulus), <code>**</code> (power)</p></div>
+<div class="paragraph"><p><code>&&</code> (boolean and), <code>||</code> (boolean or),
+<code>==</code> (equals), <code>!=</code> (not equals), <code>></code> (greater than), <code><</code> (less than),
+<code>>=</code> (greater than or equal to), <code><=</code> (less than or equal to)</p></div>
+<div class="paragraph"><p><code>xor()</code> is a builtin function.</p></div>
+<div class="paragraph"><p>Swift boolean operators are not short-circuited (to allow maximal
+concurrency). For conditional execution, use an <code>if</code> statement.</p></div>
+<div class="paragraph"><p>The following unary operators are defined:</p></div>
+<div class="paragraph"><p><code>-</code> (negate), <code>!</code> (boolean not)</p></div>
+<div class="paragraph"><p>String concatenation is also performed with <code>+</code> (plus). <code>==</code> and
+<code>!=</code> may also be used on strings. Operator <code>s1/s2</code> is equivalent to
+<code>s1+"/"+s2</code>.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_standard_library">12. Standard library</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Each category of function is shown with the required import
+statement, if necessary.</p></div>
+<div class="paragraph"><p>Functions that accept an input of any type are denoted <code>anything</code>.
+Functions that accept variable numbers of arguments are denoted with
+ellipsis <code>…</code>.</p></div>
+<div class="paragraph"><p>A function that accepts more than one type is denoted as <code>f(int|string)</code>.</p></div>
+<div class="paragraph"><p>If a function is described below an <strong>Import:</strong> label, be sure to
+<code>import</code> that package.</p></div>
+<div class="sect2">
+<h3 id="_general">12.1. General</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<code>xor(boolean,boolean) → boolean</code>
+</dt>
+<dd>
+<p>
+Exclusive logical or
+</p>
+</dd>
+<dt class="hdlist1">
+<code>make_void() → void</code>
+</dt>
+<dd>
+<p>
+Create a void value
+</p>
+</dd>
+<dt class="hdlist1">
+<code>size(A[]) → int</code>
+</dt>
+<dd>
+<p>
+Obtain the size of array <code>A</code>
+</p>
+</dd>
+<dt class="hdlist1">
+<code>contains(A[], key) → boolean</code>
+</dt>
+<dd>
+<p>
+Test that future <code>A[key]</code> exists.
+This function blocks until <code>A</code> is closed. Consumers of <code>A[key]</code> may
+block again until <code>A[key]</code> is stored.
+</p>
+</dd>
+</dl></div>
+</div>
+<div class="sect2">
+<h3 id="_type_conversion">12.2. Type conversion</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<code>fromint(int) → string</code>
+</dt>
+<dd>
+<p>
+Convert integer to string
+</p>
+</dd>
+<dt class="hdlist1">
+<code>toint(string) → int</code>
+</dt>
+<dd>
+<p>
+Convert string to integer
+</p>
+</dd>
+<dt class="hdlist1">
+<code>fromfloat(float) → string</code>
+</dt>
+<dd>
+<p>
+Convert float to string
+</p>
+</dd>
+<dt class="hdlist1">
+<code>tofloat(string) → float</code>
+</dt>
+<dd>
+<p>
+Convert string to float
+</p>
+</dd>
+<dt class="hdlist1">
+<code>itof(int) → float</code>
+</dt>
+<dd>
+<p>
+Convert integer to float
+</p>
+</dd>
+</dl></div>
+</div>
+<div class="sect2">
+<h3 id="_output">12.3. Output</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<code>trace(anything, anything, …)</code>
+</dt>
+<dd>
+<p>
+Report the value of any variable
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p><strong>Import:</strong> <code>io</code></p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<code>printf(string format, int|float|string|boolean…)</code>
+</dt>
+<dd>
+<p>
+As <code>printf()</code> in C
+</p>
+</dd>
+</dl></div>
+</div>
+<div class="sect2">
+<h3 id="_string_functions">12.4. String functions</h3>
+<div class="paragraph"><p><code>strcat(string,string)</code>: Concatenation</p></div>
+<div class="paragraph"><p><strong>Import:</strong> <code>string</code></p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<code>substring(string s, int start, int length) → string</code>
+</dt>
+<dd>
+<p>
+Obtain substring of given string <code>s</code> starting at character <code>start</code> and of
+length <code>length</code>
+</p>
+</dd>
+<dt class="hdlist1">
+<code>find(string s, string substring, int start_index, int end_index) → int</code>
+</dt>
+<dd>
+<p>
+Find the index of the first occurence of the string <code>substring</code> within
+the string <code>s</code> between the indices <code>start_index</code> and <code>end_index</code>. Here
+an index of <code>-1</code> passed to <code>end_index</code> results in <code>end_index</code> being
+treated as the length of the string <code>s</code>. <code>find</code> returns <code>-1</code> in case
+there is no occurence of <code>substring</code> in <code>s</code> in the specified range.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>string_count(string s, string substring, int start_index, int end_index) → int</code>
+</dt>
+<dd>
+<p>
+Counts the occurences of the string <code>substring</code> within the string <code>s</code>
+between the indices <code>start_index</code> and <code>end_index</code>. Here an index of
+<code>-1</code> passed to <code>end_index</code> results in <code>end_index</code> being treated as the
+length of the string <code>s</code>
+</p>
+</dd>
+<dt class="hdlist1">
+<code>is_int(string s) → boolean</code>
+</dt>
+<dd>
+<p>
+Returns true if string <code>s</code> is a number, else false.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>replace(string s, string substring, string rep_string, int start_index) → string</code>
+</dt>
+<dd>
+<p>
+Obtain the string created by replacing the first occurence of the
+string <code>substring</code> within string <code>s</code>, after the index <code>start_index</code>,
+with the string <code>rep_string</code>. In case there is no such occurence of
+the string <code>substring</code> in string <code>s</code>, the original string <code>s</code> is
+returned unmodified.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>replace_all(string s, string substring, string rep_string, int start_index) → string</code>
+</dt>
+<dd>
+<p>
+Obtain the string created by replacing all the occurences of the
+string <code>substring</code> within string <code>s</code>, after the index <code>start_index</code>,
+with the string <code>rep_string</code>. In case no such occurence of <code>substring</code>
+exists in <code>s</code>, the original string <code>s</code> is returned unmodified.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>split(string s, string delimiter) → string[]</code>
+</dt>
+<dd>
+<p>
+Tokenize string <code>s</code> with given delimiter
+</p>
+</dd>
+<dt class="hdlist1">
+<code>trim(string s) → string</code>
+</dt>
+<dd>
+<p>
+Remove leading and trailing whitespace from <code>s</code>
+</p>
+</dd>
+<dt class="hdlist1">
+<code>strlen(string) → int</code>
+</dt>
+<dd>
+<p>
+Obtain the length of the given string
+</p>
+</dd>
+<dt class="hdlist1">
+<code>hash(string) → int</code>
+</dt>
+<dd>
+<p>
+Hash the string to a 32-bit integer
+</p>
+</dd>
+<dt class="hdlist1">
+<code>sprintf(string format, int|float|string|boolean…)</code>
+</dt>
+<dd>
+<p>
+As <code>sprintf()</code> in C
+</p>
+</dd>
+<dt class="hdlist1">
+<code>string_join(string A[], string separator) → string</code>
+</dt>
+<dd>
+<p>
+Join strings in <code>A</code> with given separator. The separator may be the
+empty string
+</p>
+</dd>
+</dl></div>
+</div>
+<div class="sect2">
+<h3 id="_math">12.5. Math</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<code>max|min_integer(int,int) → int</code>
+</dt>
+<dd>
+<p>
+Obtain maximum or minimum integer,
+respectively
+</p>
+</dd>
+<dt class="hdlist1">
+<code>max|min_float(float,float) → float</code>
+</dt>
+<dd>
+<p>
+Obtain maximum or minimum float,
+respectively
+</p>
+</dd>
+<dt class="hdlist1">
+<code>pow_integer(int b,int x)</code>
+</dt>
+<dd>
+<p>
+Obtain b<sup>x</sup>
+</p>
+</dd>
+<dt class="hdlist1">
+<code>pow_float(float b,float x)</code>
+</dt>
+<dd>
+<p>
+Obtain b<sup>x</sup>
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p><strong>Import:</strong> <code>math</code></p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<code>floor(float) → int</code>
+</dt>
+<dd>
+<p>
+Round down
+</p>
+</dd>
+<dt class="hdlist1">
+<code>ceil(float) → int</code>
+</dt>
+<dd>
+<p>
+Round up
+</p>
+</dd>
+<dt class="hdlist1">
+<code>round(float) → int</code>
+</dt>
+<dd>
+<p>
+Round nearest
+</p>
+</dd>
+<dt class="hdlist1">
+<code>log(float) → float</code>
+</dt>
+<dd>
+<p>
+Natural logarithm
+</p>
+</dd>
+<dt class="hdlist1">
+<code>exp(float) → float</code>
+</dt>
+<dd>
+<p>
+Natural exponentiation: e<sup>i</sup>
+</p>
+</dd>
+<dt class="hdlist1">
+<code>sqrt(float) → float</code>
+</dt>
+<dd>
+<p>
+Square root
+</p>
+</dd>
+<dt class="hdlist1">
+<code>is_nan(float) → boolean</code>
+</dt>
+<dd>
+<p>
+Check for NaN
+</p>
+</dd>
+<dt class="hdlist1">
+<code>abs_integer(int) → int</code>
+</dt>
+<dd>
+<p>
+Absolute value
+</p>
+</dd>
+<dt class="hdlist1">
+<code>abs_float(float) → float</code>
+</dt>
+<dd>
+<p>
+Absolute value
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p><strong>Import:</strong> <code>random</code></p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<code>random() → float</code>
+</dt>
+<dd>
+<p>
+Obtain random number
+</p>
+</dd>
+<dt class="hdlist1">
+<code>randint(int start, int end)</code>
+</dt>
+<dd>
+<p>
+Obtain random integer from <code>start</code>, inclusive, to <code>end</code>, exclusive
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p><strong>Import:</strong> stats</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<code>sum_integer(int[]) → int</code>
+</dt>
+<dd>
+<p>
+Sum
+</p>
+</dd>
+<dt class="hdlist1">
+<code>avg(int|float[]) → float</code>
+</dt>
+<dd>
+<p>
+Average
+</p>
+</dd>
+</dl></div>
+</div>
+<div class="sect2">
+<h3 id="_system">12.6. System</h3>
+<div class="paragraph"><p><strong>Import:</strong> <code>sys</code></p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<code>getenv(string) → string</code>
+</dt>
+<dd>
+<p>
+Obtain an environment variable
+</p>
+</dd>
+</dl></div>
+<div class="sect3">
+<h4 id="argv">12.6.1. Command line</h4>
+<div class="paragraph"><p>Consider this command line:</p></div>
+<div class="literalblock">
+<div class="content">
+<pre><code>turbine -l -n 3 program.tcl -v -a=file1.txt file2.txt --exec="prog thing1 thing2" --help file4.txt</code></pre>
+</div></div>
+<div class="paragraph"><p>The arguments to <code>program.tcl</code> are just the tokens after <code>program.tcl</code></p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<code>args() → string</code>
+</dt>
+<dd>
+<p>
+Obtain all arguments as single string
+</p>
+<div class="paragraph"><p>E.g., <code>"-v -a=file1.txt file2.txt --exec="prog thing1 thing2" --help file4.txt"</code></p></div>
+</dd>
+</dl></div>
+<div class="paragraph"><p>The remaining functions are convenience functions oriented around
+Swift conventions. Under these conventions, the example command above
+has <em>flagged</em> arguments <code>v</code>, <code>a=file.txt</code>, <code>exec="prog thing1
+thing2"</code>, and <code>help</code>. The command has <em>unflagged</em> arguments
+<code>file2.txt</code> and <code>file4.txt</code></p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<code>argc()</code>
+</dt>
+<dd>
+<p>
+Get count of unflagged arguments
+</p>
+</dd>
+<dt class="hdlist1">
+<code>argv(string)</code>
+</dt>
+<dd>
+<p>
+<em>(argument-value)</em>
+Given a string, returns the flagged argument with that key:
+</p>
+<div class="paragraph"><p><code>argv("a") → file1.txt</code></p></div>
+<div class="paragraph"><p>In addition to regular run-time arguments, the STC <em>compile-time
+arguments</em> feature allows <code>argv()</code> arguments to be provided at compile
+time. This allows a specialized, optimized version of code to be
+compiled for a particular set of arguments. See the <code>-A
+<em>name</em>=<em>value</em></code> <a href="#stc_arguments">argument</a> to <code>stc</code>. Note that if the
+argument is re-specified at run-time, an error will occur.</p></div>
+</dd>
+<dt class="hdlist1">
+<code>argp(int)</code>
+</dt>
+<dd>
+<p>
+<em>(argument-positional)</em>
+Given an integer, returns the unflagged argument at that index:
+</p>
+<div class="paragraph"><p><code>argp(2) → file4.txt</code></p></div>
+<div class="paragraph"><p>Given 0, returns the program name,</p></div>
+<div class="paragraph"><p><code>argp(0) → /path/to/program.tcl</code></p></div>
+</dd>
+<dt class="hdlist1">
+<code>argv_accept(string…)</code>
+</dt>
+<dd>
+<p>
+If program is given flagged command line arguments not contained in given
+list, abort.
+E.g., <code>argv_accept("x")</code> would cause program failure at run time
+</p>
+</dd>
+<dt class="hdlist1">
+<code>argv_contains(string) → boolean</code>
+</dt>
+<dd>
+<p>
+Test if the command line contains the given flagged argument:
+</p>
+<div class="paragraph"><p><code>argv_contains("v") → true</code></p></div>
+</dd>
+</dl></div>
+</div>
+<div class="sect3">
+<h4 id="_debugging">12.6.2. Debugging</h4>
+<div class="paragraph"><p><strong>Import:</strong> <code>assert</code></p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<code>assert(boolean condition, string message)</code>
+</dt>
+<dd>
+<p>
+If condition is false, report <code>message</code> and exit immediately.
+</p>
+</dd>
+</dl></div>
+</div>
+<div class="sect3">
+<h4 id="Turbine_information">12.6.3. Turbine information</h4>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<code>adlb_servers() → int</code>
+</dt>
+<dd>
+<p>
+Number of ADLB servers
+</p>
+</dd>
+<dt class="hdlist1">
+<code>turbine_workers() → int</code>
+</dt>
+<dd>
+<p>
+Number of Turbine workers
+</p>
+</dd>
+</dl></div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_files_2">12.7. Files</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<code>filename(file) → string</code>
+</dt>
+<dd>
+<p>
+Obtain the name of a file
+</p>
+</dd>
+<dt class="hdlist1">
+<code>input(string) → file</code>
+</dt>
+<dd>
+<p>
+Obtain a <code>file</code>. At run time, the
+filesystem is checked for the given file name
+</p>
+</dd>
+<dt class="hdlist1">
+<code>input_file(string) → file</code>
+</dt>
+<dd>
+<p>
+Alias for <code>input()</code>
+</p>
+</dd>
+<dt class="hdlist1">
+<code>input_url(string) → file</code>
+</dt>
+<dd>
+<p>
+Obtain a <code>file</code>. Some
+automatic operations and optimizations are disabled
+</p>
+</dd>
+<dt class="hdlist1">
+<code>urlname(file) → string</code>
+</dt>
+<dd>
+<p>
+Obtain the name of a file created with
+<code>input_url()</code>
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p><strong>Import:</strong> <code>files</code></p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<code>read(file) → string</code>
+</dt>
+<dd>
+<p>
+Read file as a string
+</p>
+</dd>
+<dt class="hdlist1">
+<code>write(string) → file</code>
+</dt>
+<dd>
+<p>
+Write string to file
+</p>
+</dd>
+<dt class="hdlist1">
+<code>file_lines(file) → string[]</code>
+</dt>
+<dd>
+<p>
+Reads the whole file, returning each line as a separate entry in the
+output array. Comments with <code>#</code> are excised, leading and trailing
+whitespace is trimmed, and blank lines are omitted.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>glob(string) → file[]</code>
+</dt>
+<dd>
+<p>
+Perform glob operation, returning files
+that match. Available glob symbols include:
+</p>
+<div class="ulist"><ul>
+<li>
+<p>
+<code>*</code>: any character sequence (including the zero-length sequence)
+</p>
+</li>
+<li>
+<p>
+<code>?</code>: any character
+</p>
+</li>
+<li>
+<p>
+<code>[chars]</code>: any of the given characters
+</p>
+</li>
+<li>
+<p>
+<code>\x</code>: character <code>x</code>
+</p>
+</li>
+<li>
+<p>
+<code>{a,b,c,…}</code> any of <code>a</code>, <code>b</code>, <code>c</code>, etc.
+</p>
+</li>
+</ul></div>
+</dd>
+</dl></div>
+</div>
+<div class="sect2">
+<h3 id="_blobs_2">12.8. Blobs</h3>
+<div class="paragraph"><p><strong>Import:</strong> <code>blob</code></p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<code>blob_size(blob) → int</code>
+</dt>
+<dd>
+<p>
+Obtain the size of a blob in bytes.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>blob_null() → blob</code>
+</dt>
+<dd>
+<p>
+Obtain an empty blob of size 0.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>blob_from_string(string) → blob</code>
+</dt>
+<dd>
+<p>
+Convert a string into a blob.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>string_from_blob(blob) → string</code>
+</dt>
+<dd>
+<p>
+Convert a blob into a string. If
+the blob is not NULL-terminated, this function appends the
+NULL-terminator.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>blob_from_floats(float[]) → blob</code>
+</dt>
+<dd>
+<p>
+Convert an array of Swift floats
+(implemented as doubles) to blob containing the C-formatted array of
+doubles .
+</p>
+</dd>
+<dt class="hdlist1">
+<code>blob_from_floats(blob) → float[]</code>
+</dt>
+<dd>
+<p>
+Convert blob containing the
+C-formatted array of doubles to an array of Swift floats
+(implemented as doubles).
+</p>
+</dd>
+<dt class="hdlist1">
+<code>blob_from_ints(int i[]) → blob</code>
+</dt>
+<dd>
+<p>
+Convert blob containing the
+C-formatted array of ints to an array of Swift ints (implemented
+as 64-bit integers).
+</p>
+</dd>
+<dt class="hdlist1">
+<code>blob_from_file(file) → blob</code>
+</dt>
+<dd>
+<p>
+Reads whole file, returning it as a
+blob.
+</p>
+</dd>
+</dl></div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_defining_leaf_functions">13. Defining leaf functions</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>In typical Swift applications, the computationally intensive parts of
+the application are not written in the Swift language. Rather, the
+work is done by <em>leaf functions</em> that are <em>composed</em> together with
+Swift code. Leaf functions may be extension or app functions.</p></div>
+<div class="paragraph"><p>The Swift runtime, Turbine, is built on Tcl, a language which intends
+to makes it easy to call C/C++/Fortran functions. The builtin
+functions mentioned above are implemented as extension functions in
+Tcl, which may wrap C/C++/Fortran functions.</p></div>
+<div class="sect2">
+<h3 id="_swift_extension_functions">13.1. Swift extension functions</h3>
+<div class="paragraph"><p>Currently we support Tcl extension functions, where a function is
+implemented as a Tcl function. Tcl has good support for wrapping
+native C/C++ functions, so this provides an indirect way to call
+C/C++ functions from Swift.</p></div>
+<div class="paragraph"><p>Several components are required to implement a Swift native code function:</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+Tcl bindings to your function.
+</p>
+</li>
+<li>
+<p>
+For complex types such as structures, arrays and files, you may need
+ additional logic to marshal inputs and outputs to/from the global
+ data store.
+</p>
+</li>
+<li>
+<p>
+The requisite files required to build a Tcl package
+ (e.g <code>pkgIndex.tcl</code>)
+</p>
+</li>
+<li>
+<p>
+Swift declarations for the function that specify the type of the
+ function and the Tcl implementation.
+</p>
+</li>
+</ul></div>
+<div class="sect3">
+<h4 id="_simple_tcl_fragment_example">13.1.1. Simple Tcl fragment example</h4>
+<div class="paragraph"><p>In this example, the Swift program will simply use Tcl to output a
+string:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>() my_output (string s) "turbine" "0.0" [
+ "puts <<s>>"
+];
+
+main {
+ my_output("HELLO");
+}</code></pre>
+</div></div>
+<div class="paragraph"><p><code>puts</code> is the Tcl builtin for screen output, like <code>puts()</code> in C.</p></div>
+<div class="paragraph"><p>The above definition has, from left to right, the output arguments
+(none), the name of the new Swift function, input arguments, the name
+of the Tcl package containing the file (here, none, so we use
+<code>turbine</code>), and the minimum version of that package (here, 0.0).</p></div>
+<div class="paragraph"><p>We tell the compiler how to call our Tcl function using inline
+Tcl code as a template with variable names surrounded by <code><< >></code>
+indicating where variables should be substituted.</p></div>
+</div>
+<div class="sect3">
+<h4 id="_simple_tcl_package_example">13.1.2. Simple Tcl package example</h4>
+<div class="paragraph"><p>In this first example we will implement a trivial Tcl extension function
+that doubles an integer. Here is the Tcl code that will go in
+<code>myextension.tcl</code>:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>namespace eval myextension {
+ proc double { x } {
+ return [ expr $x * 2 ]
+ }
+}</code></pre>
+</div></div>
+<div class="paragraph"><p>Here is the Swift function definition that will go in <code>myextension.swift</code>:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>@pure
+(int o) double (int i) "myextension" "0.0.1" [
+ "set <<o>> [ myextension::double <<i>> ]"
+];</code></pre>
+</div></div>
+<div class="paragraph"><p>We can also tell the Swift compiler a little about the function so
+that it can better optimize your programs. For example, <code>double</code> has
+no side-effects and produces the same result each time for the same
+arguments (i.e. is deterministic), so we can annotate it as a <code>@pure</code>
+function.</p></div>
+<div class="paragraph"><p>If your function has a long running time and should be dispatched to a
+worker process for execution, then you need to label the function as a
+worker function, for example:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>@dispatch=WORKER
+(int o) process (int i) "pkg" "0.0.1" [
+ "set <<o>> [ pkg::process <<i>> ]"
+];</code></pre>
+</div></div>
+<div class="paragraph"><p>Tcl code is conventionally placed into <em>packages</em>. In this example,
+<code>myextension.tcl</code> would be part of the package.</p></div>
+<div class="paragraph"><p>More information about building Tcl packages may be found
+<a href="http://www.tcl.tk/man/tcl8.5/TclCmd/pkgMkIndex.htm">here</a>. Ultimately,
+you produce a <code>pkgIndex.tcl</code> file that contains necessary information
+about the package.</p></div>
+<div class="paragraph"><p>To ensure that Swift can find your package, use</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>stc -r <package directory> ...</code></pre>
+</div></div>
+<div class="paragraph"><p>or set <code>TURBINE_USER_LIB</code> at run time.</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+<strong>Tip:</strong> advanced users can also create <a href="#mkstatic">standalone executables</a>
+ with compiled code and Tcl code for the extension directly linked in.
+</p>
+</li>
+</ul></div>
+</div>
+<div class="sect3">
+<h4 id="_swift_tcl_data_type_mapping">13.1.3. Swift/Tcl data type mapping</h4>
+<div class="paragraph"><p>If you are defining Tcl functions in the way above with inline
+Tcl code, Swift types are mapped to Tcl types in the following way:</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+<code>int</code>/<code>float</code>/<code>string</code>/<code>bool</code> are converted to the standard
+ Tcl representations
+</p>
+</li>
+<li>
+<p>
+blobs are represented as a Tcl list with first element a pointer
+ to the data, the second element the length of the data, and if
+ the blob was loaded from the ADLB data store, a third element
+ which is the ADLB ID of the blob
+</p>
+</li>
+<li>
+<p>
+files are represented as a list, with the first element the
+ file path, and the second element a reference count
+</p>
+</li>
+</ul></div>
+</div>
+<div class="sect3">
+<h4 id="_calling_native_libraries_from_swift">13.1.4. Calling native libraries from Swift</h4>
+<div class="paragraph"><p>The first step is to test that you can successfully call your
+C/C++/Fortran function from a test Tcl script. If so, you will then
+be able to use the Swift→Tcl techniques to call it from Swift.</p></div>
+<div class="paragraph"><p>A popular tool to automate Tcl→C bindings is
+<a href="http://www.swig.org">SWIG</a>, which will wrap your C/C++ functions and
+help you produce a Tcl package suitable for use by Swift.</p></div>
+<div class="paragraph"><p>To call Fortran functions, first wrap your code with
+<a href="http://fortwrap.sourceforge.net">FortWrap</a>. Then, use SWIG to produce
+Tcl bindings.</p></div>
+</div>
+<div class="sect3">
+<h4 id="_writing_custom_tcl_interfaces">13.1.5. Writing custom Tcl interfaces</h4>
+<div class="paragraph"><p>For Tcl functions that take complex argument types, such as arrays or
+structures, you may need to write a Tcl wrapper function that is
+directly passed references to data in Swift’s global data store. In
+this case your function must manually retrieve/store data from/to the
+global distributed data store. In this case, you do not use the STC
+Tcl argument substitution syntax (<code><<<code>i</code>>></code>).</p></div>
+<div class="paragraph"><p>Consider this custom Swift→Tcl binding:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>(int o) complex_function (int arr[]) "pkg" "0.0.1" "complex";</code></pre>
+</div></div>
+<div class="paragraph"><p>This function jumps into Tcl function <code>complex</code>, which must
+perform its own data dependency management.</p></div>
+<div class="paragraph"><p>See the <a href="leaf.html">Swift/T Leaf Function Guide</a> for more
+information about this process.</p></div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="app_functions">13.2. App functions</h3>
+<div class="paragraph"><p>App functions are functions that are implemented as command-line
+programs. These command-line programs can be brought into a Swift
+program as functions with typed inputs and outputs.
+An app function definition comprises:</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+The standard components of a Swift function declaration: input and
+ output arguments and the function name. Note that the output
+ variable types are restricted to individual <code>file</code>s.
+</p>
+</li>
+<li>
+<p>
+The command line, which comprises an initial string which is the
+ executable to run, and then a series of arguments which are
+ the command-line arguments to pass to the program.
+</p>
+</li>
+</ul></div>
+<div class="paragraph"><p>App arguments can be:</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+Literals such as numbers or strings.
+</p>
+</li>
+<li>
+<p>
+File variables (passed as file paths).
+</p>
+</li>
+<li>
+<p>
+Other variables, which are converted to string arguments.
+ Arrays (including multi-dimensional arrays) are expanded to
+ multiple arguments.
+</p>
+</li>
+<li>
+<p>
+Arbitrary expressions surrounded by parentheses.
+</p>
+</li>
+</ul></div>
+<div class="paragraph"><p>Standard input, output and error can be redirected to files via
+<code>@stdin=</code>, <code>@stdout=</code>, and <code>@stderr=</code> expressions. If used, these should point
+to a <code>file</code>.</p></div>
+<div class="paragraph"><p>Here is an example of an app function that joins multiple files
+with the <code>cat</code> utility:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>import files;
+
+app (file out) cat (file inputs[]) {
+ "/bin/cat" inputs @stdout=out
+}
+
+main {
+ file joined <"joined.txt"> = cat(glob("*.txt"));
+}</code></pre>
+</div></div>
+<div class="paragraph"><p>Here is an example of an app function that sleeps for an arbitrary
+amount of time:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>app (void signal) sleep (int secs) {
+ "/bin/sleep" secs
+}
+
+main {
+ foreach time in [1:5] {
+ void signal = sleep(time);
+ // Wait on output signal so that trace occurs after sleep
+ wait(signal) {
+ trace("Slept " + fromint(time));
+ }
+ }
+}</code></pre>
+</div></div>
+</div>
+<div class="sect2">
+<h3 id="_external_scripting_support">13.3. External scripting support</h3>
+<div class="sect3">
+<h4 id="_calling_python">13.3.1. Calling Python</h4>
+<div class="paragraph"><p>You can evaluate arbitrary Python code from within Swift/T. For
+example, you can perform processing with a Python library.
+Once you have that working, you can use Swift/T to coordinate
+concurrent calls to that library.</p></div>
+<div class="paragraph"><p>Consider the following Swift script:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>import io;
+import python;
+
+main {
+ i = python("print(\"python works\")\nrepr(2+2)");
+ printf("i: %s", i);
+}</code></pre>
+</div></div>
+<div class="paragraph"><p>This simply evaluates the Python code line by line. The last line must
+return a Python string to Swift, in this case, the Python string
+<code>'4'</code>. The expected output is shown below:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>python works
+i: 4</code></pre>
+</div></div>
+<div class="paragraph"><p>Swift multi-line strings may be used to enter more complex Python code
+without the explicit use of <code>\n</code>.</p></div>
+<div class="paragraph"><p>Additionally, you can call Python libraries such as
+<a href="http://www.numpy.org">Numpy</a> if available on your system. The
+following code adds matrices <em>I</em><sub>3</sub> + <em>I</em><sub>3</sub> using Numpy arrays.</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>import io;
+import python;
+import string;
+
+global const string numpy = "from numpy import *\n\n";
+
+typedef matrix string;
+
+(matrix A) eye(int n)
+{
+ string command = sprintf("repr(eye(%i))", n);
+ string code = numpy+command;
+ matrix t = python(code);
+ A = replace_all(t, "\n", "", 0);
+}
+
+(matrix R) add(matrix A1, matrix A2)
+{
+ string command = sprintf("repr(%s+%s)", A1, A2);
+ string code = numpy+command;
+ matrix t = python(code);
+ R = replace_all(t, "\n", "", 0);
+}
+
+main
+{
+ matrix A1 = eye(3);
+ matrix A2 = eye(3);
+ matrix sum = add(A1, A2);
+ printf("2*eye(3)=%s", sum);
+}</code></pre>
+</div></div>
+<div class="paragraph"><p>An Python script template is created that imports Numpy and performs
+some simple calculations. This code is represented in a Swift string.
+The template is filled in by the Swift call to <code>sprintf()</code>. Then, the
+code is passed to Python for evaluation. The output is:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>2*eye(3)=array([[ 2., 0., 0.],
+ [ 0., 2., 0.],
+ [ 0., 0., 2.]])</code></pre>
+</div></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">To use this, Turbine must be configured with Python enabled
+ before compiling, by setting <code>ENABLE_PYTHON=1</code>
+ in <code>exm-settings.sh</code>, or by providing the <code>--enable-python</code> argument
+ to <code>configure</code>. This feature is implemented by linking to Python
+ as a shared library, enabling better performance than calling the
+ <code>python</code> program (which may be done by using a normal Swift
+ <a href="#app_functions">app function</a>). Error messages for minor coding
+ mistakes may be badly mangled and refer to missing Python symbols-
+ refer to the first error in the Python stack trace.</td>
+</tr></table>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_calling_r">13.3.2. Calling R</h4>
+<div class="paragraph"><p>Consider the following Swift script:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>import io;
+import string;
+import R;
+
+global const string template =
+"""
+ x <- %i
+ a <- x+100
+ cat("the answer is: ", a, "\\n")
+ a
+""";
+
+main
+{
+ code = sprintf(template, 4);
+ s = R(code);
+ printf("the answer was: %i", s);
+}</code></pre>
+</div></div>
+<div class="paragraph"><p>An <a href="http://www.r-project.org">R language</a> script template is placed in a
+Swift string. The template is filled in with the value 4 by the Swift
+call to <code>sprintf()</code> (note the <code>%i</code> conversion specifier). Then, the
+code is passed to R for evaluation. The output is:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>the answer is: 104
+the answer was: 104</code></pre>
+</div></div>
+<div class="paragraph"><p>As coded here, both R and Swift report the value of <code>a</code>.</p></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">To use this, Turbine must be configured with R enabled
+ before compiling, by setting <code>ENABLE_R=1</code>
+ in <code>exm-settings.sh</code>, or by providing the <code>--enable-r</code> argument
+ to <code>configure</code>. This feature is implemented by linking to R as a shared
+ library, enabling better performance than calling the <code>R</code> program
+ (which may be done by using a normal Swift <a href="#app_functions">app function</a>). When installing R, be sure to include the <code>devel</code>
+ package. When installing R from source, configure with
+ <code>--enable-R-shlib</code>. You may need to set the environment variable
+ <code>R_HOME</code> to the directory containing the R installation. For the APT
+ package, this is <code>/usr/lib/R</code>.</td>
+</tr></table>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_calling_julia">13.3.3. Calling Julia</h4>
+<div class="paragraph"><p>Consider the following Swift script:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>import io;
+import julia;
+import string;
+import sys;
+
+main {
+ start = clock();
+ f =
+"""
+begin
+ f(x) = begin
+ sleep(1)
+ x+1
+ end
+ f(%s)
+end
+""";
+ s1 = julia(sprintf(f, 1));
+ s2 = julia(sprintf(f, 2));
+ s3 = julia(sprintf(f, 3));
+ printf("julia results: %s %s %s", s1, s2, s3);
+ wait (s1, s2, s3) {
+ printf("duration: %0.2f", clock()-start);
+ }
+}</code></pre>
+</div></div>
+<div class="paragraph"><p>In this example, a <a href="http://julialang.org">Julia</a> script is placed in
+string <code>f</code>. It is parameterized three times by <code>sprintf()</code>. Each
+Julia invocation runs concurrently (if enough processes are provided
+to Swift/T).</p></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">To use this, Turbine must be configured with Julia enabled
+ before compiling, by providing the <code>--enable-julia</code> argument
+ to <code>configure</code>. This feature is implemented by linking to Julia
+ as a shared library, enabling better performance than calling the
+ <code>julia</code> program (which may be done by using a normal Swift
+ <a href="#app_functions">app function</a>).</td>
+</tr></table>
+</div>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="Optimizations">14. Optimizations</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>STC performs a range of compiler optimizations that can significantly
+speed up most Swift programs. The optimization level can be controlled
+by the <code>-O</code> command line option. The default optimization
+level <code>-O2</code>, or the increased optimization level <code>-O3</code> are usually
+the best choices. Some applications benefit markedly from <code>-O3</code>,
+while others do not, and compile times can increase slightly.</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code># No optimizations at all (not recommended)
+stc -O0 example.swift example.tcl
+
+# Basic optimizations (not recommended)
+stc -O1 example.swift example.tcl
+
+# Standard optimizations (recommended)
+stc example.swift example.tcl
+# OR
+stc -O2 example.swift example.tcl
+
+# All optimizations (also recommended)
+stc -O3 example.swift example.tcl</code></pre>
+</div></div>
+<div class="paragraph"><p>Individual optimizations can be toggled on using <code>-T <opt name></code>
+or off with <code>-t <opt name></code>, but this typically is only useful for
+debugging. You can find an up-to-date list of optimizations in
+the stc command-line help:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>stc -h</code></pre>
+</div></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="Turbine">15. Running in Turbine</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The following describes how to run Turbine programs.</p></div>
+<div class="sect2">
+<h3 id="_architecture">15.1. Architecture</h3>
+<div class="paragraph"><p>Turbine runs as an MPI program consisting of many processes. Turbine
+programs are ADLB programs. Thus, they produce and execute discrete
+tasks that are distributed and load balanced at run time.</p></div>
+<div class="paragraph"><p>Each process runs in a <em>mode</em>: <em>worker</em>, or <em>server</em>.</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Workers
+</dt>
+<dd>
+<p>
+Evaluate the Swift logic. Produce tasks. Execute tasks.
+</p>
+</dd>
+<dt class="hdlist1">
+Servers
+</dt>
+<dd>
+<p>
+Distributes tasks. Manages data.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Typical Swift programs perform compute-intensive work in leaf
+functions that execute on workers.
+Execution of the Swift logic is split and distributed among workers.</p></div>
+<div class="paragraph"><p>Servers distribute tasks in a scalable, load balanced manner. They
+also store Swift data (integers, strings, etc.).</p></div>
+</div>
+<div class="sect2">
+<h3 id="_concurrency">15.2. Concurrency</h3>
+<div class="paragraph"><p>The available concurrency and efficiency in your Swift script is
+limited by the following factors:</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+The available concurrency in the Swift logic. Sequential
+ dependencies will be evaluated sequentially. <code>foreach</code> loops and
+ branching function calls may be evaluated concurrently
+</p>
+</li>
+<li>
+<p>
+The number of workers available to process leaf functions
+ concurrently
+</p>
+</li>
+<li>
+<p>
+The number of servers available to control the Turbine run.
+ Adding more servers can improve performance for applications with
+ small tasks or complex data dependencies but ties up processes
+</p>
+</li>
+</ul></div>
+</div>
+<div class="sect2">
+<h3 id="_invocation">15.3. Invocation</h3>
+<div class="paragraph"><p>The form of a Turbine invocation for STC-generated
+<code>program.tcl</code> is:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>turbine <turbine arguments> <program.tcl> <program arguments></code></pre>
+</div></div>
+<div class="paragraph"><p>The program arguments are available to Swift (<a href="#argv">[argv]</a>).</p></div>
+<div class="paragraph"><p>Turbine accepts the following arguments:</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<code>-f <file></code>
+</dt>
+<dd>
+<p>
+Provide a machine file to <code>mpiexec</code>
+</p>
+</dd>
+<dt class="hdlist1">
+<code>-h</code>
+</dt>
+<dd>
+<p>
+Print a help message
+</p>
+</dd>
+<dt class="hdlist1">
+<code>-l</code>
+</dt>
+<dd>
+<p>
+Enable <code>mpiexec -l</code> ranked output formatting
+</p>
+</dd>
+<dt class="hdlist1">
+<code>-n <procs></code>
+</dt>
+<dd>
+<p>
+The total number of Turbine MPI processes
+</p>
+</dd>
+<dt class="hdlist1">
+<code>-v</code>
+</dt>
+<dd>
+<p>
+Report the Turbine version number
+</p>
+</dd>
+<dt class="hdlist1">
+<code>-V</code>
+</dt>
+<dd>
+<p>
+Make the Turbine launch script verbose
+</p>
+</dd>
+<dt class="hdlist1">
+<code>-x</code>
+</dt>
+<dd>
+<p>
+Use turbine_sh launcher with compiled-in libraries instead of tclsh
+ (reduces number of files that must be read from file system)
+</p>
+</dd>
+<dt class="hdlist1">
+<code>-X</code>
+</dt>
+<dd>
+<p>
+In place of of program.tcl, run standalone Turbine executable
+ (e.g. created by <a href="#mkstatic">mkstatic.tcl</a>)
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>The user controls the Turbine run time configuration through
+environment variables:</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<code>ADLB_SERVERS</code>
+</dt>
+<dd>
+<p>
+Number of ADLB servers
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>The remaining processes are workers. These values are available to
+Swift (<a href="#Turbine_information">Turbine information</a>).</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<code>TURBINE_LOG=0</code>
+</dt>
+<dd>
+<p>
+Disable logging. <code>TURBINE_LOG=1</code> or unset enables
+logging, assuming logging was not disabled at configure time. Logging
+goes to tandard output by default.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>TURBINE_LOG_FILE=<file></code>
+</dt>
+<dd>
+<p>
+Set log file location. Defaults to
+standard output.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>TURBINE_LOG_RANKS=1</code>
+</dt>
+<dd>
+<p>
+Using <code>turbine -l</code> or equivalent prepend the
+MPI rank number to each output line. This works with typical MPICH or
+OpenMPI systems, however, this is not available on some systems, so
+set this to emulate the rank output on such systems.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>ADLB_PRINT_TIME=1</code>
+</dt>
+<dd>
+<p>
+Enable a short report of total elapsed time (via
+<code>MPI_Wtime()</code>)
+</p>
+</dd>
+<dt class="hdlist1">
+<code>ADLB_PERF_COUNTERS=1</code>
+</dt>
+<dd>
+<p>
+Enable performance counters (printed at end of execution). The
+<a href="internals.html">Swift/T internals guide</a> has information
+about interpreting the output.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>ADLB_EXHAUST_TIME</code>
+</dt>
+<dd>
+<p>
+Time in seconds taken by ADLB task servers to shut down. May include
+a decimal point. Default 0.1 . Setting this lower will reduce
+delay in detection exhaustion. Setting this higher will reduce
+overhead due to failed exhaust checks. The default setting is
+almost always adequate.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>ADLB_REPORT_LEAKS=1</code>
+</dt>
+<dd>
+<p>
+Enable reporting of any unfreed data in ADLB data store at end of
+execution.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>ADLB_TRACE=true</code>
+</dt>
+<dt class="hdlist1">
+<code>ADLB_DEBUG=true</code>
+</dt>
+<dd>
+<p>
+To print DEBUG/TRACE level information for ADLB (if ADLB was compiled
+with it enabled)
+</p>
+</dd>
+<dt class="hdlist1">
+<code>TURBINE_LAUNCH_OPTIONS</code>
+</dt>
+<dd>
+<p>
+Provide other arguments to <code>mpiexec</code>, such as a machine file, etc.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>TURBINE_SRAND</code>
+</dt>
+<dd>
+<p>
+If unset or empty, the random number generator seed will be set to the
+process rank for each process, giving reproducible results. If set to
+an integer <code>seed</code>, the random number generator seed for each process
+will be set to <code>seed</code> + <code>rank</code>.
+</p>
+<div class="paragraph"><p>For non-reproducible random results, use the following shell commands:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>export TURBINE_SRAND=$( date +%s )
+turbine ...</code></pre>
+</div></div>
+<div class="paragraph"><p>The seed is recorded in the log.</p></div>
+</dd>
+<dt class="hdlist1">
+<code>ADLB_DEBUG_RANKS=1</code>
+</dt>
+<dd>
+<p>
+Enable a report showing the rank and hostname
+of each process. This allows you to determine whether your process
+layout on a given machine is as intended.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>ADLB_DEBUG_HOSTMAP=1</code>
+</dt>
+<dd>
+<p>
+Enable a report showing the hostmap, which
+maps hostnames to ranks for use with the location functionality.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>ADLB_DISABLE_HOSTMAP=1</code>
+</dt>
+<dd>
+<p>
+Prevent the hostmap from being constructed.
+</p>
+</dd>
+</dl></div>
+</div>
+<div class="sect2">
+<h3 id="Build_configuration">15.4. Build configuration</h3>
+<div class="paragraph"><p>The following describes how to turn Swift/T programs in Turbine
+on more complex systems.</p></div>
+<div class="sect3">
+<h4 id="_build_troubleshooting">15.4.1. Build troubleshooting</h4>
+<div class="paragraph"><p>If <code>exm-setup.zsh</code> does not succeed, you may need to change how it
+tries to configure and compile Swift/T.</p></div>
+<div class="paragraph"><p>Troubleshooting a build problem can require a few steps. The first
+step is to determine why the build failed. <code>exm-setup.zsh</code> will usually
+report the step at which configuration failed. For example, if it was unable
+to locate a valid Tcl install, it will report this. Then you can try
+these steps to resolve the problem:</p></div>
+<div class="olist arabic"><ol class="arabic">
+<li>
+<p>
+If your system is covered by the <a href="turbine-sites.html">Sites Guide</a>,
+ check to see if the problem and solution are described there.
+</p>
+</li>
+<li>
+<p>
+Inspect <code>exm-settings.sh</code> settings related to the reported problem.
+ For example, if locating a Tcl install failed, setting
+ the <code>TCL_INSTALL</code> and <code>TCL_VERSION</code> variables to the correct location
+ and version may help.
+</p>
+</li>
+<li>
+<p>
+If the options in <code>exm-settings.sh</code> do not give sufficient control to
+ fix the problem, you may need to manually configure some components
+ of Swift/T, as described in the next section.
+</p>
+</li>
+</ol></div>
+</div>
+<div class="sect3">
+<h4 id="Manual_build_configuration">15.4.2. Manual configuration</h4>
+<div class="paragraph"><p><code>exm-setup.zsh</code> and <code>exm-settings.sh</code> provide a convenient way to install
+Swift/T. However, this method does not allow full control over
+the configuration. Swift/T is built with standard Ant (Java) and
+Autotools/Makefile (C,Tcl) techniques. You can more directly control
+the configuration when building through the arguments to <code>ant</code> or
+<code>configure</code>.</p></div>
+<div class="paragraph"><p>To perform the installation using <code>configure</code>/<code>make</code>, simply untar the
+distribution package and do:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>cd c-utils
+./configure ...
+make install
+
+cd ../lb
+./configure ...
+make install
+
+cd ../turbine
+./configure ...
+make install
+
+cd ../stc
+ant install -Ddist.dir=... -Dturbine.home=...</code></pre>
+</div></div>
+<div class="ulist"><ul>
+<li>
+<p>
+You may use <code>./configure --help</code> and the
+ <a href="turbine-sites.html">Sites Guide</a> for further options.
+</p>
+</li>
+</ul></div>
+</div>
+<div class="sect3">
+<h4 id="_non_standard_mpi_locations">15.4.3. Non-standard MPI locations</h4>
+<div class="paragraph"><p>Sometimes simply specifying the MPI directory is not enough to
+configure Swift/T.</p></div>
+<div class="paragraph"><p>You can modify these settings in <code>exm-settings.sh</code> to more precisely
+define locations of MPI resources</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>EXM_CUSTOM_MPI=1
+MPI_INCLUDE=/path/to/mpi.h/include
+MPI_LIB_DIR=/path/to/mpi_lib/lib
+MPI_LIB_NAME=funny.mpi.a</code></pre>
+</div></div>
+<div class="paragraph"><p>If you are following the manual build process, configure Turbine with:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code> --enable-custom --with-mpi-include=/path/to/mpi.h/include
+ --with-mpi-lib-dir=/path/to/mpi_lib/lib
+ --with-mpi-lib-name=funny.mpi.a</code></pre>
+</div></div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_performance_enhancements">15.5. Performance enhancements</h3>
+<div class="olist arabic"><ol class="arabic">
+<li>
+<p>
+Disable logging/debugging via environment
+</p>
+</li>
+<li>
+<p>
+Disable logging/debugging at configure/compile time
+</p>
+<div class="ulist"><ul>
+<li>
+<p>
+Configure c-utils with <code>--disable-log</code>
+</p>
+</li>
+</ul></div>
+</li>
+<li>
+<p>
+Specify <code>EXM_OPT_BUILD=1</code> in <code>exm-settings.sh</code> or configure everything
+ with <code>--enable-fast</code>. This disables assertions and other checks
+</p>
+</li>
+<li>
+<p>
+When making performance measurements, always subtract 0.1 seconds
+ (or the value of <code>ADLB_EXHAUST_TIME</code>) from the Turbine run time
+ due to the ADLB shutdown protocol, which does not start until the
+ system is idle for that amount of time.
+</p>
+</li>
+<li>
+<p>
+Reduce the number of program files that must be read off the
+ filesystem. This is particularly useful for parallel file systems
+ and large scale applications. In increasing order of effectiveness,
+ you can:
+</p>
+<div class="ulist"><ul>
+<li>
+<p>
+use the turbine_sh launcher in place of tclsh in submit script,
+ or by specifying the <code>-x</code> argument to <code>turbine</code>
+</p>
+</li>
+<li>
+<p>
+Use <a href="#mkstatic">mkstatic.tcl</a> to create a standalone executable with
+ the Tcl main script and Tcl library code compiled in, and compiled
+ code statically linked.
+</p>
+</li>
+</ul></div>
+</li>
+</ol></div>
+</div>
+<div class="sect2">
+<h3 id="mkstatic">15.6. Building standalone executables with mkstatic.tcl</h3>
+<div class="paragraph"><p>It is possible to build a fully self-contained executable, including
+all Tcl scripts and compiled code, provided that all dependencies support
+static linking. If not, it is also possible to build an executable with
+a subset of Tcl scripts and code linked in, providing some performance
+benefits.</p></div>
+<div class="paragraph"><p>The provided <code>mkstatic.tcl</code> utility can produce a C source
+file with Tcl scripts bundled in, which can then be compiled and linked
+with a C compiler. This is a multi-step process that can be automated
+as part of your build process.</p></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">Ensure that static versions of the <code>c-utils</code>, <code>lb</code>, and <code>turbine</code> libraries
+ were built, typically with a <code>.a</code> suffix, e.g. <code>libadlb.a</code>. These
+ are created by default, unless you specified <code>DISABLE_STATIC=0</code> or
+ <code>--disable-static</code>. To build a fully standalone
+ executable, you will also need to build a static version of Tcl
+ (with the <code>--disable-shared</code> configure option), and static versions
+ of any other libraries your own code needs to link with, such
+ as your MPI distribution or application code.</td>
+</tr></table>
+</div>
+<div class="olist arabic"><ol class="arabic">
+<li>
+<p>
+Compile your Swift script
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code>stc my.swift</code></pre>
+</div></div>
+<div class="paragraph"><p>producing the Turbine Tcl script <code>my.tcl</code>.</p></div>
+</li>
+<li>
+<p>
+Create a manifest file, e.g. <code>my.manifest</code>. This file describes the
+ resources to be bundled, including the STC-generated code and any
+ user libraries.
+</p>
+<div class="paragraph"><p>To do this, make a copy of <code>scripts/mkstatic/example.manifest</code> from
+the Turbine installation directory. This file contains examples and
+descriptions of all the the possible settings.
+Note that an empty
+manifest file corresponds to the <code>turbine_sh</code> utility, which is a
+replacement for <code>tclsh</code> with required Turbine libraries statically
+linked in.
+For a simple Swift program with no user Tcl libraries,
+you only need to set <code>main_script = my.tcl</code>.</p></div>
+</li>
+<li>
+<p>
+Invoke <code>mkstatic.tcl</code> (found under <code>scripts/mkstatic/mkstatic.tcl</code> in
+ the Turbine installation) to translate your Tcl script to a C main
+ program (e.g., <code>my_main.c</code>) with Tcl source code included.
+ The minimal invocation is
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code>mkstatic.tcl my.manifest -c my_main.c</code></pre>
+</div></div>
+<div class="paragraph"><p>You will likely wish to include Tcl system libraries with
+<code>--include-sys-lib /home/example/tcl-install/lib --tcl-version 8.6</code>.
+The Tcl system library directory can be identified by the fact that
+it contains the file <code>init.tcl</code>. This directory must be specified
+with a special flag so that <code>mkstatic.tcl</code> can correctly replace
+the regular Tcl initialization process.</p></div>
+<div class="paragraph"><p>You can include additional libraries and packages with
+<code>--include-lib /home/example/tcl-lib/</code>. Any <code>.tcl</code> or <code>.tm</code> source files
+in the directory will be included. Source-only packages can
+generally be completely linked into the executable, but if a package
+loads shared libraries, only the <code>pkgIndex.tcl</code> file will be linked
+into the executable. A package with compiled code can be converted to
+support static linking by specifying a package init function, plus
+static library or object files in the manifest file.</p></div>
+</li>
+<li>
+<p>
+Link together the compiled C main program with user libraries and
+ Swift/T libraries to produce a final executable. The details of the
+ process vary depending on the compiler and system: we assume GCC.
+ You will need to provide the correct flags to link in all libraries
+ required by Swift/T or your own user code.
+</p>
+<div class="ulist"><ul>
+<li>
+<p>
+<strong>User code:</strong> you must identify the libraries used by your application
+ and ensure link flags are provided. If linking static libraries, ensure
+ that any indirect dependencies of these libraries are also linked.
+</p>
+</li>
+<li>
+<p>
+<strong>Swift/T system:</strong> The Turbine distribution includes a helper script,
+ <code>turbine-build-config.sh</code>, that can be sourced to obtain linker flags
+ for Swift/T dependencies.
+</p>
+</li>
+<li>
+<p>
+<strong>Link order:</strong> In the case of static linking, if <strong>libA</strong> depends on <strong>libB</strong>,
+ then the <code>-lA</code> flag must precede <code>-lB</code> on the command line. To
+ actually do the linking, there are two further cases to consider:
+</p>
+<div class="ulist"><ul>
+<li>
+<p>
+If building a fully static executable, you can
+ provide the <code>-static</code> flag, plus all object files, plus <code>-L</code>
+ and <code>-l</code> flags for all required library directories and libraries.
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code>gcc -static script_main.c file1.o file2.o -L/path/to/lib/dir -lsomething ...</code></pre>
+</div></div>
+</li>
+<li>
+<p>
+If you are building an executable that depends on one or more shared
+ libraries, you will need to provide the <code>-dynamic</code> flag, and then
+ ensure that static libraries are linked statically. If a shared
+ version of a library is available, <code>gcc</code> will use that in preference
+ to a static version. You can override this behaviour by specifying
+ <code>-Wl,-Bstatic</code> on the command line before the flags for the libraries
+ you wish to statically link, then <code>-Wl,-Bdynamic</code> to reset to
+ dynamic linking for any libraries after those.
+</p>
+</li>
+</ul></div>
+</li>
+</ul></div>
+</li>
+</ol></div>
+<div class="paragraph"><p>We have described the most commonly-used options. A full list of options
+and descriptions can be obtained by invoking <code>mkstatic.tcl -h</code>.
+Additional options include:</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<code>--main-script</code>
+</dt>
+<dd>
+<p>
+Specify Tcl main script (overrides manifest file)
+</p>
+</dd>
+<dt class="hdlist1">
+<code>-r</code>
+</dt>
+<dd>
+<p>
+Specify non-standard variable prefix for C code
+</p>
+</dd>
+<dt class="hdlist1">
+<code>-v</code>
+</dt>
+<dd>
+<p>
+Print verbose messages
+</p>
+</dd>
+<dt class="hdlist1">
+<code>--deps</code>
+</dt>
+<dd>
+<p>
+Generate Makefile include for generating C file
+</p>
+</dd>
+<dt class="hdlist1">
+<code>--ignore-no-manifest</code>
+</dt>
+<dd>
+<p>
+Pretend empty manifest present
+</p>
+</dd>
+</dl></div>
+</div>
+</div>
+</div>
+</div>
+<div id="footnotes"><hr /></div>
+<div id="footer">
+<div id="footer-text">
+Last updated 2014-07-21 14:19:02 CDT
+</div>
+</div>
+</body>
+</html>
Deleted: www/Swift-T/swift.html
===================================================================
--- www/Swift-T/swift.html 2014-07-21 19:10:58 UTC (rev 8055)
+++ www/Swift-T/swift.html 2014-07-21 19:22:06 UTC (rev 8056)
@@ -1,3772 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
- "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
-<head>
-<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
-<meta name="generator" content="AsciiDoc 8.6.9" />
-<title>Swift/T Guide</title>
-<style type="text/css">
-/* Shared CSS for AsciiDoc xhtml11 and html5 backends */
-
-/* Default font. */
-body {
- font-family: Georgia,serif;
-}
-
-/* Title font. */
-h1, h2, h3, h4, h5, h6,
-div.title, caption.title,
-thead, p.table.header,
-#toctitle,
-#author, #revnumber, #revdate, #revremark,
-#footer {
- font-family: Arial,Helvetica,sans-serif;
-}
-
-body {
- margin: 1em 5% 1em 5%;
-}
-
-a {
- color: blue;
- text-decoration: underline;
-}
-a:visited {
- color: fuchsia;
-}
-
-em {
- font-style: italic;
- color: navy;
-}
-
-strong {
- font-weight: bold;
- color: #083194;
-}
-
-h1, h2, h3, h4, h5, h6 {
- color: #527bbd;
- margin-top: 1.2em;
- margin-bottom: 0.5em;
- line-height: 1.3;
-}
-
-h1, h2, h3 {
- border-bottom: 2px solid silver;
-}
-h2 {
- padding-top: 0.5em;
-}
-h3 {
- float: left;
-}
-h3 + * {
- clear: left;
-}
-h5 {
- font-size: 1.0em;
-}
-
-div.sectionbody {
- margin-left: 0;
-}
-
-hr {
- border: 1px solid silver;
-}
-
-p {
- margin-top: 0.5em;
- margin-bottom: 0.5em;
-}
-
-ul, ol, li > p {
- margin-top: 0;
-}
-ul > li { color: #aaa; }
-ul > li > * { color: black; }
-
-.monospaced, code, pre {
- font-family: "Courier New", Courier, monospace;
- font-size: inherit;
- color: navy;
- padding: 0;
- margin: 0;
-}
-pre {
- white-space: pre-wrap;
-}
-
-#author {
- color: #527bbd;
- font-weight: bold;
- font-size: 1.1em;
-}
-#email {
-}
-#revnumber, #revdate, #revremark {
-}
-
-#footer {
- font-size: small;
- border-top: 2px solid silver;
- padding-top: 0.5em;
- margin-top: 4.0em;
-}
-#footer-text {
- float: left;
- padding-bottom: 0.5em;
-}
-#footer-badges {
- float: right;
- padding-bottom: 0.5em;
-}
-
-#preamble {
- margin-top: 1.5em;
- margin-bottom: 1.5em;
-}
-div.imageblock, div.exampleblock, div.verseblock,
-div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
-div.admonitionblock {
- margin-top: 1.0em;
- margin-bottom: 1.5em;
-}
-div.admonitionblock {
- margin-top: 2.0em;
- margin-bottom: 2.0em;
- margin-right: 10%;
- color: #606060;
-}
-
-div.content { /* Block element content. */
- padding: 0;
-}
-
-/* Block element titles. */
-div.title, caption.title {
- color: #527bbd;
- font-weight: bold;
- text-align: left;
- margin-top: 1.0em;
- margin-bottom: 0.5em;
-}
-div.title + * {
- margin-top: 0;
-}
-
-td div.title:first-child {
- margin-top: 0.0em;
-}
-div.content div.title:first-child {
- margin-top: 0.0em;
-}
-div.content + div.title {
- margin-top: 0.0em;
-}
-
-div.sidebarblock > div.content {
- background: #ffffee;
- border: 1px solid #dddddd;
- border-left: 4px solid #f0f0f0;
- padding: 0.5em;
-}
-
-div.listingblock > div.content {
- border: 1px solid #dddddd;
- border-left: 5px solid #f0f0f0;
- background: #f8f8f8;
- padding: 0.5em;
-}
-
-div.quoteblock, div.verseblock {
- padding-left: 1.0em;
- margin-left: 1.0em;
- margin-right: 10%;
- border-left: 5px solid #f0f0f0;
- color: #888;
-}
-
-div.quoteblock > div.attribution {
- padding-top: 0.5em;
- text-align: right;
-}
-
-div.verseblock > pre.content {
- font-family: inherit;
- font-size: inherit;
-}
-div.verseblock > div.attribution {
- padding-top: 0.75em;
- text-align: left;
-}
-/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
-div.verseblock + div.attribution {
- text-align: left;
-}
-
-div.admonitionblock .icon {
- vertical-align: top;
- font-size: 1.1em;
- font-weight: bold;
- text-decoration: underline;
- color: #527bbd;
- padding-right: 0.5em;
-}
-div.admonitionblock td.content {
- padding-left: 0.5em;
- border-left: 3px solid #dddddd;
-}
-
-div.exampleblock > div.content {
- border-left: 3px solid #dddddd;
- padding-left: 0.5em;
-}
-
-div.imageblock div.content { padding-left: 0; }
-span.image img { border-style: none; vertical-align: text-bottom; }
-a.image:visited { color: white; }
-
-dl {
- margin-top: 0.8em;
- margin-bottom: 0.8em;
-}
-dt {
- margin-top: 0.5em;
- margin-bottom: 0;
- font-style: normal;
- color: navy;
-}
-dd > *:first-child {
- margin-top: 0.1em;
-}
-
-ul, ol {
- list-style-position: outside;
-}
-ol.arabic {
- list-style-type: decimal;
-}
-ol.loweralpha {
- list-style-type: lower-alpha;
-}
-ol.upperalpha {
- list-style-type: upper-alpha;
-}
-ol.lowerroman {
- list-style-type: lower-roman;
-}
-ol.upperroman {
- list-style-type: upper-roman;
-}
-
-div.compact ul, div.compact ol,
-div.compact p, div.compact p,
-div.compact div, div.compact div {
- margin-top: 0.1em;
- margin-bottom: 0.1em;
-}
-
-tfoot {
- font-weight: bold;
-}
-td > div.verse {
- white-space: pre;
-}
-
-div.hdlist {
- margin-top: 0.8em;
- margin-bottom: 0.8em;
-}
-div.hdlist tr {
- padding-bottom: 15px;
-}
-dt.hdlist1.strong, td.hdlist1.strong {
- font-weight: bold;
-}
-td.hdlist1 {
- vertical-align: top;
- font-style: normal;
- padding-right: 0.8em;
- color: navy;
-}
-td.hdlist2 {
- vertical-align: top;
-}
-div.hdlist.compact tr {
- margin: 0;
- padding-bottom: 0;
-}
-
-.comment {
- background: yellow;
-}
-
-.footnote, .footnoteref {
- font-size: 0.8em;
-}
-
-span.footnote, span.footnoteref {
- vertical-align: super;
-}
-
-#footnotes {
- margin: 20px 0 20px 0;
- padding: 7px 0 0 0;
-}
-
-#footnotes div.footnote {
- margin: 0 0 5px 0;
-}
-
-#footnotes hr {
- border: none;
- border-top: 1px solid silver;
- height: 1px;
- text-align: left;
- margin-left: 0;
- width: 20%;
- min-width: 100px;
-}
-
-div.colist td {
- padding-right: 0.5em;
- padding-bottom: 0.3em;
- vertical-align: top;
-}
-div.colist td img {
- margin-top: 0.3em;
-}
-
- at media print {
- #footer-badges { display: none; }
-}
-
-#toc {
- margin-bottom: 2.5em;
-}
-
-#toctitle {
- color: #527bbd;
- font-size: 1.1em;
- font-weight: bold;
- margin-top: 1.0em;
- margin-bottom: 0.1em;
-}
-
-div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
- margin-top: 0;
- margin-bottom: 0;
-}
-div.toclevel2 {
- margin-left: 2em;
- font-size: 0.9em;
-}
-div.toclevel3 {
- margin-left: 4em;
- font-size: 0.9em;
-}
-div.toclevel4 {
- margin-left: 6em;
- font-size: 0.9em;
-}
-
-span.aqua { color: aqua; }
-span.black { color: black; }
-span.blue { color: blue; }
-span.fuchsia { color: fuchsia; }
-span.gray { color: gray; }
-span.green { color: green; }
-span.lime { color: lime; }
-span.maroon { color: maroon; }
-span.navy { color: navy; }
-span.olive { color: olive; }
-span.purple { color: purple; }
-span.red { color: red; }
-span.silver { color: silver; }
-span.teal { color: teal; }
-span.white { color: white; }
-span.yellow { color: yellow; }
-
-span.aqua-background { background: aqua; }
-span.black-background { background: black; }
-span.blue-background { background: blue; }
-span.fuchsia-background { background: fuchsia; }
-span.gray-background { background: gray; }
-span.green-background { background: green; }
-span.lime-background { background: lime; }
-span.maroon-background { background: maroon; }
-span.navy-background { background: navy; }
-span.olive-background { background: olive; }
-span.purple-background { background: purple; }
-span.red-background { background: red; }
-span.silver-background { background: silver; }
-span.teal-background { background: teal; }
-span.white-background { background: white; }
-span.yellow-background { background: yellow; }
-
-span.big { font-size: 2em; }
-span.small { font-size: 0.6em; }
-
-span.underline { text-decoration: underline; }
-span.overline { text-decoration: overline; }
-span.line-through { text-decoration: line-through; }
-
-div.unbreakable { page-break-inside: avoid; }
-
-
-/*
- * xhtml11 specific
- *
- * */
-
-div.tableblock {
- margin-top: 1.0em;
- margin-bottom: 1.5em;
-}
-div.tableblock > table {
- border: 3px solid #527bbd;
-}
-thead, p.table.header {
- font-weight: bold;
- color: #527bbd;
-}
-p.table {
- margin-top: 0;
-}
-/* Because the table frame attribute is overriden by CSS in most browsers. */
-div.tableblock > table[frame="void"] {
- border-style: none;
-}
-div.tableblock > table[frame="hsides"] {
- border-left-style: none;
- border-right-style: none;
-}
-div.tableblock > table[frame="vsides"] {
- border-top-style: none;
- border-bottom-style: none;
-}
-
-
-/*
- * html5 specific
- *
- * */
-
-table.tableblock {
- margin-top: 1.0em;
- margin-bottom: 1.5em;
-}
-thead, p.tableblock.header {
- font-weight: bold;
- color: #527bbd;
-}
-p.tableblock {
- margin-top: 0;
-}
-table.tableblock {
- border-width: 3px;
- border-spacing: 0px;
- border-style: solid;
- border-color: #527bbd;
- border-collapse: collapse;
-}
-th.tableblock, td.tableblock {
- border-width: 1px;
- padding: 4px;
- border-style: solid;
- border-color: #527bbd;
-}
-
-table.tableblock.frame-topbot {
- border-left-style: hidden;
- border-right-style: hidden;
-}
-table.tableblock.frame-sides {
- border-top-style: hidden;
- border-bottom-style: hidden;
-}
-table.tableblock.frame-none {
- border-style: hidden;
-}
-
-th.tableblock.halign-left, td.tableblock.halign-left {
- text-align: left;
-}
-th.tableblock.halign-center, td.tableblock.halign-center {
- text-align: center;
-}
-th.tableblock.halign-right, td.tableblock.halign-right {
- text-align: right;
-}
-
-th.tableblock.valign-top, td.tableblock.valign-top {
- vertical-align: top;
-}
-th.tableblock.valign-middle, td.tableblock.valign-middle {
- vertical-align: middle;
-}
-th.tableblock.valign-bottom, td.tableblock.valign-bottom {
- vertical-align: bottom;
-}
-
-
-/*
- * manpage specific
- *
- * */
-
-body.manpage h1 {
- padding-top: 0.5em;
- padding-bottom: 0.5em;
- border-top: 2px solid silver;
- border-bottom: 2px solid silver;
-}
-body.manpage h2 {
- border-style: none;
-}
-body.manpage div.sectionbody {
- margin-left: 3em;
-}
-
- at media print {
- body.manpage div#toc { display: none; }
-}
-
-
-
-/* SWIFT/T GUIDE CUSTOMIZATIONS */
-
-a:visited {
- color: gray;
-}
-h5 {
- font-size: 0.8em;
-}
-
-</style>
-<script type="text/javascript">
-/*<+'])');
- // Function that scans the DOM tree for header elements (the DOM2
- // nodeIterator API would be a better technique but not supported by all
- // browsers).
- var iterate = function (el) {
- for (var i = el.firstChild; i != null; i = i.nextSibling) {
- if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
- var mo = re.exec(i.tagName);
- if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
- result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
- }
- iterate(i);
- }
- }
- }
- iterate(el);
- return result;
- }
-
- var toc = document.getElementById("toc");
- if (!toc) {
- return;
- }
-
- // Delete existing TOC entries in case we're reloading the TOC.
- var tocEntriesToRemove = [];
- var i;
- for (i = 0; i < toc.childNodes.length; i++) {
- var entry = toc.childNodes[i];
- if (entry.nodeName.toLowerCase() == 'div'
- && entry.getAttribute("class")
- && entry.getAttribute("class").match(/^toclevel/))
- tocEntriesToRemove.push(entry);
- }
- for (i = 0; i < tocEntriesToRemove.length; i++) {
- toc.removeChild(tocEntriesToRemove[i]);
- }
-
- // Rebuild TOC entries.
- var entries = tocEntries(document.getElementById("content"), toclevels);
- for (var i = 0; i < entries.length; ++i) {
- var entry = entries[i];
- if (entry.element.id == "")
- entry.element.id = "_toc_" + i;
- var a = document.createElement("a");
- a.href = "#" + entry.element.id;
- a.appendChild(document.createTextNode(entry.text));
- var div = document.createElement("div");
- div.appendChild(a);
- div.className = "toclevel" + entry.toclevel;
- toc.appendChild(div);
- }
- if (entries.length == 0)
- toc.parentNode.removeChild(toc);
-},
-
-
-/////////////////////////////////////////////////////////////////////
-// Footnotes generator
-/////////////////////////////////////////////////////////////////////
-
-/* Based on footnote generation code from:
- * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
- */
-
-footnotes: function () {
- // Delete existing footnote entries in case we're reloading the footnodes.
- var i;
- var noteholder = document.getElementById("footnotes");
- if (!noteholder) {
- return;
- }
- var entriesToRemove = [];
- for (i = 0; i < noteholder.childNodes.length; i++) {
- var entry = noteholder.childNodes[i];
- if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") == "footnote")
- entriesToRemove.push(entry);
- }
- for (i = 0; i < entriesToRemove.length; i++) {
- noteholder.removeChild(entriesToRemove[i]);
- }
-
- // Rebuild footnote entries.
- var cont = document.getElementById("content");
- var spans = cont.getElementsByTagName("span");
- var refs = {};
- var n = 0;
- for (i=0; i<spans.length; i++) {
- if (spans[i].className == "footnote") {
- n++;
- var note = spans[i].getAttribute("data-note");
- if (!note) {
- // Use [\s\S] in place of . so multi-line matches work.
- // Because JavaScript has no s (dotall) regex flag.
- note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
- spans[i].innerHTML =
- "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
- "' title='View footnote' class='footnote'>" + n + "</a>]";
- spans[i].setAttribute("data-note", note);
- }
- noteholder.innerHTML +=
- "<div class='footnote' id='_footnote_" + n + "'>" +
- "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
- n + "</a>. " + note + "</div>";
- var id =spans[i].getAttribute("id");
- if (id != null) refs["#"+id] = n;
- }
- }
- if (n == 0)
- noteholder.parentNode.removeChild(noteholder);
- else {
- // Process footnoterefs.
- for (i=0; i<spans.length; i++) {
- if (spans[i].className == "footnoteref") {
- var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
- href = href.match(/#.*/)[0]; // Because IE return full URL.
- n = refs[href];
- spans[i].innerHTML =
- "[<a href='#_footnote_" + n +
- "' title='View footnote' class='footnote'>" + n + "</a>]";
- }
- }
- }
-},
-
-install: function(toclevels) {
- var timerId;
-
- function reinstall() {
- asciidoc.footnotes();
- if (toclevels) {
- asciidoc.toc(toclevels);
- }
- }
-
- function reinstallAndRemoveTimer() {
- clearInterval(timerId);
- reinstall();
- }
-
- timerId = setInterval(reinstall, 500);
- if (document.addEventListener)
- document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);
- else
- window.onload = reinstallAndRemoveTimer;
-}
-
-}
-asciidoc.install(2);
-/*]]>*/
-</script>
-</head>
-<body class="article" style="max-width:750px">
-<div id="header">
-<h1>Swift/T Guide</h1>
-<span id="author">v0.6.0, July 2014</span><br />
-<div id="toc">
- <div id="toctitle">Table of Contents</div>
- <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
-</div>
-</div>
-<div id="content">
-<div id="preamble">
-<div class="sectionbody">
-<div class="paragraph"><p>The Swift/Turbine Compiler (STC) allows you to write Swift programs
-and run them using Turbine.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_support">1. Support</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An overview of Swift/T may be found at the ExM project site:</p></div>
-<div class="paragraph"><p><a href="https://sites.google.com/site/exmcomputing">https://sites.google.com/site/exmcomputing</a></p></div>
-<div class="paragraph"><p>The Swift/T user discussion mailing list is found here:</p></div>
-<div class="paragraph"><p><a href="http://lists.mcs.anl.gov/mailman/listinfo/exm-user">http://lists.mcs.anl.gov/mailman/listinfo/exm-user</a></p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_installation">2. Installation</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Writing and running Swift/Turbine programs requires multiple packages.
-This section provides generic instructions for installing Swift/T
-on a range of systems. We first cover locating and/or installing
-prerequisite software packages, then we cover building Swift/T
-from a source package.</p></div>
-<div class="paragraph"><p>The <a href="http://www.mcs.anl.gov/exm/local/guides/turbine-sites.html">Turbine Sites Guide</a>
-is a accompanying resource for configuration settings and preinstalled software
-for specific systems.</p></div>
-<div class="sect2">
-<h3 id="_installation_of_prerequisites">2.1. Installation of Prerequisites</h3>
-<div class="olist arabic"><ol class="arabic">
-<li>
-<p>
-Install or locate MPI implementation (MPICH, OpenMPI, etc.)
-</p>
-<div class="ulist"><ul>
-<li>
-<p>
-On compute clusters, an MPI will almost certainly be pre-installed
-</p>
-</li>
-<li>
-<p>
-Many operating systems provide packages with MPI implementations
- that are usable, but often outdated.
- E.g. the <code>mpich2</code> package on Debian/Ubuntu.
-</p>
-</li>
-<li>
-<p>
-See <a href="http://www.mpich.org">MPICH Guides</a> for information on installing the
- latest version of MPICH.
-</p>
-</li>
-<li>
-<p>
-Other MPI implementations are <a href="#Build_configuration">supported</a> as well.
-</p>
-<div class="paragraph"><p>Swift/T attempts to use MPI 3.0 functionality by default. If you
-are using an MPI implementation that does not support the MPI 3.0 standard,
-you must set <code>MPI_VERSION=2</code> (if using the <code>exm-setup.zsh</code> build process),
-or provide the <code>--enable-mpi-2</code> configure option (if using
-the manual build process).</p></div>
-</li>
-</ul></div>
-</li>
-<li>
-<p>
-Install or locate Tcl 8.6.
-</p>
-<div class="ulist"><ul>
-<li>
-<p>
-Tcl is available through the package manager on many systems.
- You may need to install an additional Tcl development package
- in addition to the standard tcl package,
- e.g. <code>tcl8.6</code> plus <code>tcl8.6-dev</code> on Debian/Ubuntu systems.
-</p>
-</li>
-<li>
-<p>
-Source distributions are available at the <a href="http://www.tcl.tk">Tcl web site</a>
-</p>
-</li>
-</ul></div>
-</li>
-<li>
-<p>
-Install or locate SWIG
-</p>
-<div class="ulist"><ul>
-<li>
-<p>
-You can check if SWIG is installed by running <code>swig -version</code>
-</p>
-</li>
-<li>
-<p>
-SWIG is available through the package manager on many systems.
-</p>
-</li>
-<li>
-<p>
-Source distributions are available at
- the <a href="http://swig.org">SWIG web site</a>
-</p>
-</li>
-</ul></div>
-</li>
-</ol></div>
-</div>
-<div class="sect2">
-<h3 id="_installation_of_swift_t_from_source">2.2. Installation of Swift/T from Source</h3>
-<div class="paragraph"><p>Once you have found all prerequisites, we can continue with building
-Swift/T from source.</p></div>
-<div class="olist arabic"><ol class="arabic">
-<li>
-<p>
-Obtain the Swift/T source package
-</p>
-<div class="listingblock">
-<div class="content">
-<pre><code>wget http://www.mcs.anl.gov/exm/local/downloads/exm-0.5.0.tar.gz</code></pre>
-</div></div>
-<div class="paragraph"><p>Cf. <a href="http://www.mcs.anl.gov/exm/local/downloads/downloads.html">Swift/T Downloads</a>
-for other packages</p></div>
-</li>
-<li>
-<p>
-Unpack and enter package directory
-</p>
-<div class="listingblock">
-<div class="content">
-<pre><code>tar xfz exm-trunk.tar.gz
-cd exm-trunk</code></pre>
-</div></div>
-</li>
-<li>
-<p>
-Edit the settings file: <code>exm-settings.sh</code>
-</p>
-<div class="paragraph"><p>At a minimum, you must set the install directory with <code>EXM_PREFIX</code>.
-On a standard system, no further configuration may be needed.
-In many cases, however, you will need to modify additional
-configuration settings so that all prerequisites can
-be correctly located and configured (see Section
-<a href="#Build_configuration">Build configuration</a>).</p></div>
-<div class="paragraph"><p>A range of other settings are also available here:
-enabling/disabling features, debug or optimized builds, etc.</p></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<div class="title">Tip</div>
-</td>
-<td class="content">Save your <code>exm-settings.sh</code> when you download a new package</td>
-</tr></table>
-</div>
-</li>
-<li>
-<p>
-Run the setup script
-</p>
-<div class="listingblock">
-<div class="content">
-<pre><code>./exm-setup.zsh</code></pre>
-</div></div>
-<div class="paragraph"><p>If <code>exm-setup.zsh</code> does not succeed on your system, see Section
-<a href="#Build_configuration">Build configuration</a> below.</p></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<div class="title">Tip</div>
-</td>
-<td class="content">if you want more control than <code>exm-setup.zsh</code> provides, you can
- build Swift/T with the
- <a href="#Manual_build_configuration">manual configure/make workflow</a>.</td>
-</tr></table>
-</div>
-</li>
-<li>
-<p>
-Add Turbine and STC to your paths
-</p>
-<div class="listingblock">
-<div class="content">
-<pre><code>PATH=${PATH}:/path/to/exm-install/turbine/bin
-PATH=${PATH}:/path/to/exm-install/stc/bin</code></pre>
-</div></div>
-</li>
-</ol></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_usage">3. Usage</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Swift code is conventionally written in <code>*.swift</code> files. Turbine
-code is stored in Tcl files <code>*.tcl</code>. After writing the Swift program
-<code>program.swift</code>, run:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>stc program.swift</code></pre>
-</div></div>
-<div class="paragraph"><p>This will compile the program to <code>program.tcl</code>. A second, optional
-argument may be given as an alternate output file name.</p></div>
-<div class="paragraph"><p>Then, to run the program, use Turbine:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>turbine -n 4 program.tcl</code></pre>
-</div></div>
-<div class="paragraph"><p>See the <a href="#Turbine">Turbine section</a> for more information about
-running the program.</p></div>
-<div class="paragraph" id="stc_arguments"><p>STC accepts the following arguments:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>-A <em>name</em>=<em>value</em></code>
-</dt>
-<dd>
-<p>
-Set a command-line argument at
-compile-time. This may be found at runtime using the Swift
-<a href="#argv">argument processing</a> library. This option enables these
-arguments to be treated as compile-time constants for optimization.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>-D <em>macro</em>=<em>value</em></code>
-</dt>
-<dd>
-<p>
-Define a C preprocessor macro.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>-E</code>
-</dt>
-<dd>
-<p>
-Just run the C preprocessor: do not compile the program. The
-output goes into the STC output file (the second file name argument).
-</p>
-</dd>
-<dt class="hdlist1">
-<code>-I</code>
-</dt>
-<dd>
-<p>
-Add a directory to the import and include search path.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>-O</code>
-</dt>
-<dd>
-<p>
-Set optimization level: 0, 1, 2, or 3. See <a href="#Optimizations">[Optimizations]</a>.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>-j</code>
-</dt>
-<dd>
-<p>
-Set the location of the <code>java</code> executable.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>-p</code>
-</dt>
-<dd>
-<p>
-Disable the C preprocessor.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>-u</code>
-</dt>
-<dd>
-<p>
-Only compile if output file is not up-to-date.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>-v</code>
-</dt>
-<dd>
-<p>
-Output version number and exit.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>-V</code>
-</dt>
-<dd>
-<p>
-Verbose output.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>STC runs as a Java program. You may use <code>-j</code> to set the Java VM
-executable. This Java VM must be compatible with the <code>javac</code> used to
-compile STC.</p></div>
-<div class="paragraph"><p>By default, STC runs the user script through the C preprocessor
-(<code>cpp</code>), enabling arbitrary macro processing, etc. The <code>-D</code>, <code>-E</code>,
-<code>-I</code>, and <code>-p</code> options are relevant to this feature.</p></div>
-<div class="paragraph"><p>Additional arguments for advanced users/developers:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>-C</code>
-</dt>
-<dd>
-<p>
-Specify an output file for STC internal representation
-</p>
-</dd>
-<dt class="hdlist1">
-<code>-l</code>
-</dt>
-<dd>
-<p>
-Specify log file for STC debug log
-</p>
-</dd>
-<dt class="hdlist1">
-<code>-L</code>
-</dt>
-<dd>
-<p>
-Specify log file for more verbose STC debug log
-</p>
-</dd>
-<dt class="hdlist1">
-<code>-T</code>
-</dt>
-<dd>
-<p>
-Enable a specific optimization. See <a href="#Optimizations">[Optimizations]</a>
-</p>
-</dd>
-<dt class="hdlist1">
-<code>-t</code>
-</dt>
-<dd>
-<p>
-Disable a specific compiler optimization. See <a href="#Optimizations">[Optimizations]</a>
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_program_structure">4. Program structure</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Swift programs are composed of <em>composite</em> functions. These
-share syntax with C-like languages. The program starts in <code>main()</code>.
-The following is a complete Swift program:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>main
-{}</code></pre>
-</div></div>
-<div class="paragraph"><p>STC input is preprocessed by <code>cpp</code>, the C preprocessor.</p></div>
-<div class="paragraph"><p>Hello world is written as:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>import io;
-main
-{
- printf("Hello world");
-}</code></pre>
-</div></div>
-<div class="paragraph"><p>The newline is supplied by <code>printf()</code>.</p></div>
-<div class="paragraph"><p>Swift programs eventually call <em>leaf</em> functions, which are the primary
-way to do work. From the perspective of the Swift script, they are
-atomic operations that wait for input variables and set output
-variables. They may be implemented as native code functions or
-external application programs.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_comments">5. Comments</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Swift supports C/C++-style comments:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>// This is a comment
-/* This is a
-comment */
-/** Also a
-comment */</code></pre>
-</div></div>
-<div class="paragraph"><p>Additionally, if the preprocessor is disabled, single-line comments
-starting with # are supported:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code># This will work if source file is not preprocessed</code></pre>
-</div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_modules">6. Modules</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Swift has a module system that allows you to import function and variable
-definitions into your source file. Importing a module will import all
-function and variable definitions from that module into your program.</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>import io;
-import mypackage.mymodule;</code></pre>
-</div></div>
-<div class="paragraph"><p>The mechanisms for locating source files is as follows:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-STC searches a list of directories in order to find a Swift source
- file in the correct directory with the correct name.
-</p>
-</li>
-<li>
-<p>
-The standard library is always first on the search path,
- and the current working directory is last.
-</p>
-</li>
-<li>
-<p>
-Additional directories can be added with the <code>-I</code> option to STC.
-</p>
-</li>
-<li>
-<p>
-Swift source files must have a <code>.swift</code> suffix. E.g. <code>import io;</code>
- looks for a file called <code>io.swift</code>.
-</p>
-</li>
-<li>
-<p>
-In the case of a multi-part import name, E.g. <code>import mypackage.mymodule</code>,
- then, it looks for <code>mymodule.swift</code> in subdirectory <code>mypackage</code>.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>The alternative <code>#include</code> statement textually includes an entire
-file using the C preprocessor at the point of the statement.
-Note that <code>#include</code> will only work if the preprocessor is enabled
-on the current file. In contrast to <code>import</code>, <code>#include</code> will run the
-C preprocessor on any included modules. <code>import</code> is recommended over
-<code>#include</code> unless the imported module requires preprocessing.</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>#include <mypackage/mymodule.swift></code></pre>
-</div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_dataflow_evaluation">7. Dataflow evaluation</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Swift expressions are evaluated in <em>dataflow</em> order:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>int z1,z2;
-int y;
-int x = f(y);
-y = g(2);
-z1 = h(x,y,1);
-z2 = h(x,y,2);
-int output = r(z1,z2);</code></pre>
-</div></div>
-<div class="paragraph"><p>This allows code to execute as concurrently as possible, limited
-only by data availability. In this example, <code>g()</code> runs first, because it
-is dependent only on a literal. When <code>y</code> is set, <code>f()</code> runs, setting
-<code>x</code>. Then, two invocations of <code>h()</code> execute. Finally, <code>z1</code> and <code>z2</code>
-are set, allowing <code>r()</code> to run.</p></div>
-<div class="paragraph"><p>Variables may be assigned only once. Multiple assignment is often
-detected at compile time, and will always be detected at run time,
-resulting in a run time error. If variable is not assigned,
-expressions that depend on the variable cannot execute. If the variable
-is never assigned during the course of program execution, these
-expressions will never execute. Upon program completion, Swift/T will
-report the error and print debug information about any unexecuted
-expressions and identifiers of corresponding unassigned variables.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_composite_functions">8. Composite functions</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Swift code is written in composite functions. The composite function
-<code>main</code> is required.</p></div>
-<div class="paragraph"><p>Composite functions have the form:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>[(<output list>)] function_name [(<input list>)]
-{
- statement;
- statement;
- ...
-}</code></pre>
-</div></div>
-<div class="paragraph"><p>An empty input or output list may be omitted or written as <code>()</code>.</p></div>
-<div class="paragraph"><p>The output list may have more than one entry. Thus, assignments
-may be written as:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>x1, x2 = f(i1, i2);
-// or equivalently:
-(x1, x2) = f(i1, i2);</code></pre>
-</div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">9. Types</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Swift provides a similar range of primitive types to many other
-programming languages. Files are a primitive type in Swift, unlike
-in many other languages, and have a number of special characteristics
-that merit special mention.
-Two basic kinds of data structure are provided: arrays and structs.</p></div>
-<div class="sect2">
-<h3 id="_primitive_types">9.1. Primitive types</h3>
-<div class="paragraph"><p>Swift has the conventional types:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>string</code>
-</dt>
-<dd>
-<p>
-A complete string (not an array of characters).
-</p>
-</dd>
-<dt class="hdlist1">
-<code>int</code>
-</dt>
-<dd>
-<p>
-A 64-bit integer.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>float</code>
-</dt>
-<dd>
-<p>
-A 64-bit (double-precision) floating point number.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>boolean</code>
-</dt>
-<dd>
-<p>
-A boolean (true/false).
-</p>
-</dd>
-<dt class="hdlist1">
-<code>file</code>
-</dt>
-<dd>
-<p>
-A file (see Section Files).
-</p>
-</dd>
-<dt class="hdlist1">
-<code>blob</code>
-</dt>
-<dd>
-<p>
-External byte data (see Section Blobs).
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Literals for these types use conventional syntax:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<code>int</code> literals are written as decimal numbers, e.g. <code>-1234</code>
-</p>
-</li>
-<li>
-<p>
-<code>float</code> literals are written as decimal numbers with a decimal point,
- e.g <code>5493.352</code> or <code>1.0</code>.
- Scientific notation may be used,
- as in <code>2.3e-2</code> which is equivalent to <code>0.023</code>.
- The literals <code>NaN</code> and <code>inf</code> may be used. In some contexts <code>int</code>
- literals are promoted automatically to <code>float</code>.
-</p>
-</li>
-<li>
-<p>
-<code>boolean</code> literals <code>true</code> and <code>false</code> may be used.
-</p>
-</li>
-<li>
-<p>
-<code>string</code> literals are enclosed in double quotes, with a range of escape
- sequences supported:
-</p>
-<div class="ulist"><ul>
-<li>
-<p>
-<code>\\</code> for a single backslash
-</p>
-</li>
-<li>
-<p>
-<code>\"</code> for a quote
-</p>
-</li>
-<li>
-<p>
-<code>\n</code> for newline
-</p>
-</li>
-<li>
-<p>
-<code>\t</code> for tab
-</p>
-</li>
-<li>
-<p>
-<code>\a</code> (alarm)
-</p>
-</li>
-<li>
-<p>
-<code>\b</code> (backspace)
-</p>
-</li>
-<li>
-<p>
-<code>\f</code> (form feed)
-</p>
-</li>
-<li>
-<p>
-<code>\r</code> (carriage return)
-</p>
-</li>
-<li>
-<p>
-<code>\v</code> (vertical tab)
-</p>
-</li>
-<li>
-<p>
-octal escape codes, e.g. <code>\001</code>
-</p>
-</li>
-<li>
-<p>
-hexadecimal escape codes, e.g. <code>\xf2</code>
-</p>
-</li>
-<li>
-<p>
-For more information: <a href="http://en.wikipedia.org/wiki/US-ASCII#ASCII_control_code_chart">ASCII control codes</a>.
-</p>
-</li>
-</ul></div>
-</li>
-<li>
-<p>
-Multi-line strings may be used in two syntaxes:
-</p>
-<div class="ulist"><ul>
-<li>
-<p>
-Python-style:
-</p>
-<div class="listingblock">
-<div class="content">
-<pre><code>string s =
-"""
-line data 1
-line data 2
-""";</code></pre>
-</div></div>
-</li>
-<li>
-<p>
-Asciidoc-style: like Python-style but use 4 dashes instead of 3 quotes.
-</p>
-</li>
-<li>
-<p>
-<strong>Note:</strong> Multi-line strings are somewhat incompatible with the C preprocessor:
- if you try to compile a Swift program using multi-line strings with
- the preprocessor enabled, you will likely see warnings or strange
- behavior. To disable the C preprocessor, use the <code>-p</code> option
- to STC.
-</p>
-</li>
-</ul></div>
-</li>
-</ul></div>
-</div>
-<div class="sect2">
-<h3 id="_files">9.2. Files</h3>
-<div class="paragraph"><p>A file is a first-class entity in Swift that in many ways can be treated
-as any other variable. The main difference is that a file can be
-<strong>mapped</strong> to path in a filesystem. Assigning to a mapped file variable
-results in a file being created in the file system at the specified path.
-File paths can be arbitrary Swift expressions of type <code>string</code>. Absolute
-paths or relative paths are specified, with relative paths interpreted
-relative to the path in which turbine was run.
-File variables can also be initialized with data from a pre-existing
-file using the <code>input_file</code> function. File paths are relative to the
-working directory for Turbine.</p></div>
-<div class="paragraph"><p>For example, if <code>/home/user/in.txt</code> is a file with some data in it,
-the following Swift program will copy the file to <code>/home/user/out.txt</code>.</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>main
-{
- file x = input_file("/home/user/in.txt");
- file y <"/home/user/out.txt">; // Declare a mapped file
- y = x; // Do the copy
-}</code></pre>
-</div></div>
-<div class="paragraph"><p>A range of functions to work with files are provided in the
-<code>files</code> library module.</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>// Initialize an array of files from a range of files on disk with glob
-file f[] = glob("directory/*.txt");
-
-// Read the contents of a file with read
-string filename = "in.txt";
-string contents = read(input_file(filename));
-trace("Contents of " + filename + ":\n" + contents);
-
-// Write directly to a file with write
-file tmp = write("first line\nsecond line");
-
-// Find the name of a file with filename
-trace("Temporary filename is: " + filename(tmp));</code></pre>
-</div></div>
-<div class="paragraph"><p>Temporary files are created as necessary if unmapped files are
-written to. For example, the file <code>tmp</code> in the above code snippet.
-This feature is implemented by calling GNU <code>mktemp</code> with suffix
-<code>.turbine</code>; thus, the directory is set with environment variable
-<code>TMPDIR</code> which defaults to <code>/tmp</code>.</p></div>
-<div class="paragraph"><p>Currently Swift/T assumes that the file system is shared among
-all nodes.</p></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<div class="title">Note</div>
-</td>
-<td class="content">
-<div class="paragraph"><p>The syntax</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>file f<"f.txt"> = g();</code></pre>
-</div></div>
-<div class="paragraph"><p>is allowed but</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>file f<"f.txt">=g();</code></pre>
-</div></div>
-<div class="paragraph"><p>results in a parse error: the <code>>=</code> sequence is tokenized as
-<em>greater-than-or-equal-to</em>.</p></div>
-</td>
-</tr></table>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_blobs">9.3. Blobs</h3>
-<div class="paragraph"><p>Blobs represent raw byte data. They are primarily used to pass
-data to and from native code libraries callable from Swift. They are
-like Swift strings but may contain arbitrary data.</p></div>
-<div class="paragraph"><p>Swift provides multiple builtin functions to create blobs, convert
-blobs to and from Swift types, and pass blobs to leaf functions.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_arrays">9.4. Arrays</h3>
-<div class="paragraph"><p>Arrays can be declared with empty square brackets:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>int A[];</code></pre>
-</div></div>
-<div class="paragraph"><p>Arrays with empty square brackets have integer indices. It is
-also possible to declare integers with other index types, such as
-strings:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>string dict[string];</code></pre>
-</div></div>
-<div class="paragraph"><p>They are dynamically sized, expanding each time an item is inserted at
-a new index. Arrays are indexed using square brackets.</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>int A[string];
-int B[];
-B = function_returning_array();
-A["zero"] = B[0];
-A["one"] = B[1];</code></pre>
-</div></div>
-<div class="paragraph"><p>Each array index can only be assigned to once.</p></div>
-<div class="paragraph"><p>A given array variable must be assigned either <em>in toto</em> (as a whole)
-or <em>in partes</em> (piece by piece). In this example, <code>B</code> is assigned in toto
-and <code>A</code> is assigned in partes. Code that attempts to do both is in error.</p></div>
-<div class="paragraph"><p>Arrays may be used as inputs or outputs of functions.</p></div>
-<div class="paragraph"><p>Arrays are part of Swift dataflow semantics. An array is closed
-when all possible insertions to it are complete.</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>(int B[]) f(int j)
-{
- int A[];
- A = subroutine_function(1);
-
- // Error: A has already been assigned in toto:
- A[3] = 4;
-
- // OK: assigning to output variable
- B = subroutine_function(2);
-}</code></pre>
-</div></div>
-<div class="paragraph"><p>Array literals may be expressed using the range operator:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>int start = 0;
-int stop = 10;
-int step = 2;
-// Array of length 10:
-int A[] = [start:stop];
-// Array of length 5, containing only even numbers:
-int B[] = [start:stop:step];</code></pre>
-</div></div>
-<div class="paragraph"><p>Array literals may also be expressed with list syntax:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>int C[] = [4,5,6];</code></pre>
-</div></div>
-</div>
-<div class="sect2">
-<h3 id="_nested_arrays">9.5. Nested arrays</h3>
-<div class="paragraph"><p>Swift allows arrays of arrays: nested arrays. They can be declared and
-assigned as follows:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>// An array of arrays of files with string keys
-file A[string][string];
-A["foo"]["bar"] = input_file("test.txt");
-A["foo"]["qux"] = input_file("test2.txt");</code></pre>
-</div></div>
-<div class="paragraph"><p><strong>Note:</strong> there is currently a limitation in assignment of nested arrays
-that a given array can only be assigned at a single "index level". If
-<code>A</code> is a 2D array, for example, then you cannot mix assignments specifying
-one index (e.g. <code>A[i] = …</code>) with assignments specifying three indices
-(e.g. <code>A[i][j] = …</code>).</p></div>
-</div>
-<div class="sect2">
-<h3 id="_structs">9.6. Structs</h3>
-<div class="paragraph"><p>In Swift, structs are defined with the <code>type</code> keyword. They define
-a new type.</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>type person
-{
- string name;
- int age;
- int events[];
-}</code></pre>
-</div></div>
-<div class="paragraph"><p>Structs are accessed with the <code>.</code> syntax:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>person p;
-p.name = "Abe";
-p.age = 90;</code></pre>
-</div></div>
-<div class="paragraph"><p>It is possible to have arrays of structs, with some restriction on
-how they can be assigned. Each struct in the array must be assigned
-<em>in toto</em> (as a whole). For example, the following code is valid:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>person people[], p1, p2;
-
-p1.name = "Thelma";
-p1.age = 31;
-
-p2.name = "Louise";
-p2.age = 29;
-
-people[0] = p1;
-people[1] = p2;</code></pre>
-</div></div>
-<div class="paragraph"><p>However, attempting to assign the structs in the following way is
-currently unsupported:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>people[2].name = "Abe"; // Not supported!
-people[2].age = 90; // Not supported!</code></pre>
-</div></div>
-</div>
-<div class="sect2">
-<h3 id="_defining_new_types">9.7. Defining new types</h3>
-<div class="paragraph"><p>Swift has two ways to define new types based on existing types.</p></div>
-<div class="paragraph"><p>The first is <code>typedef</code>, which creates a new name for the type.
-The new type and the existing type will be completely interchangeable,
-since they are simply different names for the same underlying type.
-The new type name simply serves to improve readability or documentation.</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>typedef newint int;
-
-main {
- // We can freely convert between int and newint
- newint x = 1;
- int y = x;
- newint z = y;
-}</code></pre>
-</div></div>
-<div class="paragraph"><p>The second is with <code>type</code>, which creates a new type that is a
-specialization of an existing type. That is, it is a distinct
-type that is not interchangeable. A specialized type can be
-converted into the original type, but the reverse transformation is
-not possible. This means that you can write functions that are more
-strictly typechecked, for example, only accepted particular types of
-file.</p></div>
-<div class="paragraph"><p><strong>Note:</strong> This feature is immature, so you will have a higher probability
-of encountering compiler bugs or limitations.</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>typedef sorted_file file;
-app (sorted_file out) sort (file i) {
- "/usr/bin/sort" "-o" out i
-}
-
-// uniq utility requires sorted input
-app (file o) unique (sorted_file i) {
- "/usr/bin/uniq" i @stdout=o
-}
-
-main {
- file unsorted = input_file("input.txt");
- sorted_file sorted <"sorted.txt"> = sort(unsorted);
- file u <"unique.txt"> = unique(sorted);
-
- // Can convert from sorted_file to file
- file result2 = sort(unsorted);
-
- // This would cause a type error
- // sorted_file not_sorted = unsorted;
-}</code></pre>
-</div></div>
-</div>
-<div class="sect2">
-<h3 id="_global_constants">9.8. Global Constants</h3>
-<div class="paragraph"><p>Swift supports a basic feature for defining globally visible constants. You
-can use the <code>global const</code> statement at the top level of the program. The
-syntax only supports literals of scalar types: e.g. integer literals, floating
-point literals and string literals.</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>global const string hello = "Hello World";
-global const float pi_approx = 3.142;
-global const int ONE = 1;
-
-main () {
- trace(hello, pi_approx, ONE);
-}</code></pre>
-</div></div>
-<div class="paragraph"><p><strong>Note:</strong> global constants provide no performance benefit compared with
-variables initialized to constant values at optimization levels <code>O1</code>
-or greater.</p></div>
-<div class="paragraph"><p><strong>Note:</strong> better support is planned in future for more flexible support for
-global variables and code.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_control_structures">10. Control structures</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Swift provides control structures that may be placed as statements
-inside a composite function.</p></div>
-<div class="sect2">
-<h3 id="_conditionals">10.1. Conditionals</h3>
-<div class="sect3">
-<h4 id="_if_statement">10.1.1. If statement</h4>
-<div class="paragraph"><p>If statements have the form:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>if (<condition>)
-{
- statement;
- ...
-}
-else
-{
- statement;
- ...
-}</code></pre>
-</div></div>
-<div class="paragraph"><p>As required by dataflow processing, neither branch of the conditional can
-execute until the value of the condition expression is available.</p></div>
-</div>
-<div class="sect3">
-<h4 id="_switch_statement">10.1.2. Switch statement</h4>
-<div class="listingblock">
-<div class="content">
-<pre><code>int a = 20;
-switch (a)
-{
- case 1:
- int c;
- c = a + a;
- b = a + 1;
- case 20:
- b = 1;
- case 2000:
- b = 2;
- default:
- b = 2102 + 2420;
-}
-printf("b: %i\n", b);</code></pre>
-</div></div>
-<div class="paragraph"><p><strong>Note:</strong> there is no fall-through between cases in switch statements.</p></div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_iteration">10.2. Iteration</h3>
-<div class="paragraph"><p>Iteration is performed with the <code>foreach</code> and <code>for</code> statements.</p></div>
-<div class="sect3">
-<h4 id="_foreach_loop">10.2.1. Foreach loop</h4>
-<div class="paragraph"><p>The <code>foreach</code> loop allows for parallel iteration over an array:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>string A[];
-foreach value, index in A
-{
- printf("A[%i] = %s\n", index, value);
-}</code></pre>
-</div></div>
-<div class="paragraph"><p>The <code>index</code> and <code>value</code> variables are automatically declared. The
-<code>index</code> variable may be omitted from the syntax.</p></div>
-<div class="paragraph"><p>A special case of the foreach loop occurs when combined with the
-array range operator. This is the idiomatic way to iterate over
-a range of integer values in Swift. The STC compiler has special
-handling for this case that avoids constructing an array.</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>foreach i in [start:stop:step] {
- ...
-}</code></pre>
-</div></div>
-</div>
-<div class="sect3">
-<h4 id="_for_loop">10.2.2. For loop</h4>
-<div class="paragraph"><p>The <code>for</code> loop allows for sequential iteration. This example
-implements a counter based on the return values of a function that
-accepts integers:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>int N = 100;
-int count = 0;
-for (int i = 0; i < N; i = i+1, count = count+c)
-{
- int c;
- if (condition_function(i))
- {
- c = 1;
- }
- else
- {
- c = 0;
- }
-}</code></pre>
-</div></div>
-<div class="paragraph"><p>The general form is:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>for ( <initializer> ; <condition> ; <updates> )
-{
- statement;
- ...
-}</code></pre>
-</div></div>
-<div class="paragraph"><p>The initializer is executed first, once. The initializer is a
-comma-separated list of statements. The body statements are then
-executed. Then, the assignments are performed, formatted as a
-comma-separated list. Each is a special assignment in which the
-left-hand-side is the variable in the <em>next</em> iteration of the loop,
-while the right-hand-side is the variable in the <em>previous</em> loop
-iteration. Then, the condition is checked for loop exit. If the loop
-continues, the body is executed again, etc.</p></div>
-<div class="paragraph"><p><strong>Performance Tip:</strong> use the <code>foreach</code> loop instead of <code>for</code> if your
-loop iterations are independent and can be executed in parallel.</p></div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_explicit_data_dependent_execution">10.3. Explicit data-dependent execution</h3>
-<div class="paragraph"><p>In general, execution ordering in Swift/T is implicit and driven by
-data dependencies. In some cases it is useful to add explicit data
-dependencies, for example if you want to print a message to indicate
-that variable was assigned. It is possible for the programmer to
-express additional execution ordering using two constructs: the <code>wait</code>
-statement and the <code>=></code> chaining operator.</p></div>
-<div class="paragraph"><p>In a wait statement, a block of code is executed after
-one or more variables are closed.</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>x = f();
-y = g();
-wait (x) {
- trace("x is closed!");
-}
-wait(x, y) {
- trace("x and y are closed!");
-}</code></pre>
-</div></div>
-<div class="paragraph"><p>The chaining operator chains statements together so that a
-statement only executes after the previous statement’s output
-value is closed. This is
-a more concise way to express dependencies than the <code>wait</code> statement.</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>sleep(1) =>
- x = f() =>
- int y = g() =>
- trace("DONE!");</code></pre>
-</div></div>
-<div class="paragraph"><p>Chaining is based on the <strong>output values</strong>
-of a statement. In the simple case of a function call <code>f() => …</code>,
-the output values are the output values of the function. In the
-case of and assignment <code>x = f() => …</code> or a declaration,
-<code>int y = g() => …</code>, then the next statement is dependent on
-the assigned values, or the declared values. Some functions such
-as <code>sleep</code> have <code>void</code> output values so that they can be used
-in this fashion.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_scoping_blocks">10.4. Scoping blocks</h3>
-<div class="paragraph"><p>Arbitrary scoping blocks may be used. In this example, two different
-variables, both represented by <code>b</code>, are assigned different values.</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>{
- int b;
- b = 1;
-}
-{
- int b;
- b = 2;
-}</code></pre>
-</div></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_operators">11. Operators</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The following binary arithmetic operators on numbers are defined:</p></div>
-<div class="paragraph"><p><code>+</code> (plus), <code>-</code> (minus), <code>*</code> (times), <code>/</code> (divide),
-<code>%/</code> (integer divide), <code>%%</code> (modulus), <code>**</code> (power)</p></div>
-<div class="paragraph"><p><code>&&</code> (boolean and), <code>||</code> (boolean or),
-<code>==</code> (equals), <code>!=</code> (not equals), <code>></code> (greater than), <code><</code> (less than),
-<code>>=</code> (greater than or equal to), <code><=</code> (less than or equal to)</p></div>
-<div class="paragraph"><p><code>xor()</code> is a builtin function.</p></div>
-<div class="paragraph"><p>Swift boolean operators are not short-circuited (to allow maximal
-concurrency). For conditional execution, use an <code>if</code> statement.</p></div>
-<div class="paragraph"><p>The following unary operators are defined:</p></div>
-<div class="paragraph"><p><code>-</code> (negate), <code>!</code> (boolean not)</p></div>
-<div class="paragraph"><p>String concatenation is also performed with <code>+</code> (plus). <code>==</code> and
-<code>!=</code> may also be used on strings. Operator <code>s1/s2</code> is equivalent to
-<code>s1+"/"+s2</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_standard_library">12. Standard library</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Each category of function is shown with the required import
-statement, if necessary.</p></div>
-<div class="paragraph"><p>Functions that accept an input of any type are denoted <code>anything</code>.
-Functions that accept variable numbers of arguments are denoted with
-ellipsis <code>…</code>.</p></div>
-<div class="paragraph"><p>A function that accepts more than one type is denoted as <code>f(int|string)</code>.</p></div>
-<div class="paragraph"><p>If a function is described below an <strong>Import:</strong> label, be sure to
-<code>import</code> that package.</p></div>
-<div class="sect2">
-<h3 id="_general">12.1. General</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>xor(boolean,boolean) → boolean</code>
-</dt>
-<dd>
-<p>
-Exclusive logical or
-</p>
-</dd>
-<dt class="hdlist1">
-<code>make_void() → void</code>
-</dt>
-<dd>
-<p>
-Create a void value
-</p>
-</dd>
-<dt class="hdlist1">
-<code>size(A[]) → int</code>
-</dt>
-<dd>
-<p>
-Obtain the size of array <code>A</code>
-</p>
-</dd>
-<dt class="hdlist1">
-<code>contains(A[], key) → boolean</code>
-</dt>
-<dd>
-<p>
-Test that future <code>A[key]</code> exists.
-This function blocks until <code>A</code> is closed. Consumers of <code>A[key]</code> may
-block again until <code>A[key]</code> is stored.
-</p>
-</dd>
-</dl></div>
-</div>
-<div class="sect2">
-<h3 id="_type_conversion">12.2. Type conversion</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>fromint(int) → string</code>
-</dt>
-<dd>
-<p>
-Convert integer to string
-</p>
-</dd>
-<dt class="hdlist1">
-<code>toint(string) → int</code>
-</dt>
-<dd>
-<p>
-Convert string to integer
-</p>
-</dd>
-<dt class="hdlist1">
-<code>fromfloat(float) → string</code>
-</dt>
-<dd>
-<p>
-Convert float to string
-</p>
-</dd>
-<dt class="hdlist1">
-<code>tofloat(string) → float</code>
-</dt>
-<dd>
-<p>
-Convert string to float
-</p>
-</dd>
-<dt class="hdlist1">
-<code>itof(int) → float</code>
-</dt>
-<dd>
-<p>
-Convert integer to float
-</p>
-</dd>
-</dl></div>
-</div>
-<div class="sect2">
-<h3 id="_output">12.3. Output</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>trace(anything, anything, …)</code>
-</dt>
-<dd>
-<p>
-Report the value of any variable
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p><strong>Import:</strong> <code>io</code></p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>printf(string format, int|float|string|boolean…)</code>
-</dt>
-<dd>
-<p>
-As <code>printf()</code> in C
-</p>
-</dd>
-</dl></div>
-</div>
-<div class="sect2">
-<h3 id="_string_functions">12.4. String functions</h3>
-<div class="paragraph"><p><code>strcat(string,string)</code>: Concatenation</p></div>
-<div class="paragraph"><p><strong>Import:</strong> <code>string</code></p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>substring(string s, int start, int length) → string</code>
-</dt>
-<dd>
-<p>
-Obtain substring of given string <code>s</code> starting at character <code>start</code> and of
-length <code>length</code>
-</p>
-</dd>
-<dt class="hdlist1">
-<code>find(string s, string substring, int start_index, int end_index) → int</code>
-</dt>
-<dd>
-<p>
-Find the index of the first occurence of the string <code>substring</code> within
-the string <code>s</code> between the indices <code>start_index</code> and <code>end_index</code>. Here
-an index of <code>-1</code> passed to <code>end_index</code> results in <code>end_index</code> being
-treated as the length of the string <code>s</code>. <code>find</code> returns <code>-1</code> in case
-there is no occurence of <code>substring</code> in <code>s</code> in the specified range.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>string_count(string s, string substring, int start_index, int end_index) → int</code>
-</dt>
-<dd>
-<p>
-Counts the occurences of the string <code>substring</code> within the string <code>s</code>
-between the indices <code>start_index</code> and <code>end_index</code>. Here an index of
-<code>-1</code> passed to <code>end_index</code> results in <code>end_index</code> being treated as the
-length of the string <code>s</code>
-</p>
-</dd>
-<dt class="hdlist1">
-<code>is_int(string s) → boolean</code>
-</dt>
-<dd>
-<p>
-Returns true if string <code>s</code> is a number, else false.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>replace(string s, string substring, string rep_string, int start_index) → string</code>
-</dt>
-<dd>
-<p>
-Obtain the string created by replacing the first occurence of the
-string <code>substring</code> within string <code>s</code>, after the index <code>start_index</code>,
-with the string <code>rep_string</code>. In case there is no such occurence of
-the string <code>substring</code> in string <code>s</code>, the original string <code>s</code> is
-returned unmodified.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>replace_all(string s, string substring, string rep_string, int start_index) → string</code>
-</dt>
-<dd>
-<p>
-Obtain the string created by replacing all the occurences of the
-string <code>substring</code> within string <code>s</code>, after the index <code>start_index</code>,
-with the string <code>rep_string</code>. In case no such occurence of <code>substring</code>
-exists in <code>s</code>, the original string <code>s</code> is returned unmodified.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>split(string s, string delimiter) → string[]</code>
-</dt>
-<dd>
-<p>
-Tokenize string <code>s</code> with given delimiter
-</p>
-</dd>
-<dt class="hdlist1">
-<code>trim(string s) → string</code>
-</dt>
-<dd>
-<p>
-Remove leading and trailing whitespace from <code>s</code>
-</p>
-</dd>
-<dt class="hdlist1">
-<code>strlen(string) → int</code>
-</dt>
-<dd>
-<p>
-Obtain the length of the given string
-</p>
-</dd>
-<dt class="hdlist1">
-<code>hash(string) → int</code>
-</dt>
-<dd>
-<p>
-Hash the string to a 32-bit integer
-</p>
-</dd>
-<dt class="hdlist1">
-<code>sprintf(string format, int|float|string|boolean…)</code>
-</dt>
-<dd>
-<p>
-As <code>sprintf()</code> in C
-</p>
-</dd>
-<dt class="hdlist1">
-<code>string_join(string A[], string separator) → string</code>
-</dt>
-<dd>
-<p>
-Join strings in <code>A</code> with given separator. The separator may be the
-empty string
-</p>
-</dd>
-</dl></div>
-</div>
-<div class="sect2">
-<h3 id="_math">12.5. Math</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>max|min_integer(int,int) → int</code>
-</dt>
-<dd>
-<p>
-Obtain maximum or minimum integer,
-respectively
-</p>
-</dd>
-<dt class="hdlist1">
-<code>max|min_float(float,float) → float</code>
-</dt>
-<dd>
-<p>
-Obtain maximum or minimum float,
-respectively
-</p>
-</dd>
-<dt class="hdlist1">
-<code>pow_integer(int b,int x)</code>
-</dt>
-<dd>
-<p>
-Obtain b<sup>x</sup>
-</p>
-</dd>
-<dt class="hdlist1">
-<code>pow_float(float b,float x)</code>
-</dt>
-<dd>
-<p>
-Obtain b<sup>x</sup>
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p><strong>Import:</strong> <code>math</code></p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>floor(float) → int</code>
-</dt>
-<dd>
-<p>
-Round down
-</p>
-</dd>
-<dt class="hdlist1">
-<code>ceil(float) → int</code>
-</dt>
-<dd>
-<p>
-Round up
-</p>
-</dd>
-<dt class="hdlist1">
-<code>round(float) → int</code>
-</dt>
-<dd>
-<p>
-Round nearest
-</p>
-</dd>
-<dt class="hdlist1">
-<code>log(float) → float</code>
-</dt>
-<dd>
-<p>
-Natural logarithm
-</p>
-</dd>
-<dt class="hdlist1">
-<code>exp(float) → float</code>
-</dt>
-<dd>
-<p>
-Natural exponentiation: e<sup>i</sup>
-</p>
-</dd>
-<dt class="hdlist1">
-<code>sqrt(float) → float</code>
-</dt>
-<dd>
-<p>
-Square root
-</p>
-</dd>
-<dt class="hdlist1">
-<code>is_nan(float) → boolean</code>
-</dt>
-<dd>
-<p>
-Check for NaN
-</p>
-</dd>
-<dt class="hdlist1">
-<code>abs_integer(int) → int</code>
-</dt>
-<dd>
-<p>
-Absolute value
-</p>
-</dd>
-<dt class="hdlist1">
-<code>abs_float(float) → float</code>
-</dt>
-<dd>
-<p>
-Absolute value
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p><strong>Import:</strong> <code>random</code></p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>random() → float</code>
-</dt>
-<dd>
-<p>
-Obtain random number
-</p>
-</dd>
-<dt class="hdlist1">
-<code>randint(int start, int end)</code>
-</dt>
-<dd>
-<p>
-Obtain random integer from <code>start</code>, inclusive, to <code>end</code>, exclusive
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p><strong>Import:</strong> stats</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>sum_integer(int[]) → int</code>
-</dt>
-<dd>
-<p>
-Sum
-</p>
-</dd>
-<dt class="hdlist1">
-<code>avg(int|float[]) → float</code>
-</dt>
-<dd>
-<p>
-Average
-</p>
-</dd>
-</dl></div>
-</div>
-<div class="sect2">
-<h3 id="_system">12.6. System</h3>
-<div class="paragraph"><p><strong>Import:</strong> <code>sys</code></p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>getenv(string) → string</code>
-</dt>
-<dd>
-<p>
-Obtain an environment variable
-</p>
-</dd>
-</dl></div>
-<div class="sect3">
-<h4 id="argv">12.6.1. Command line</h4>
-<div class="paragraph"><p>Consider this command line:</p></div>
-<div class="literalblock">
-<div class="content">
-<pre><code>turbine -l -n 3 program.tcl -v -a=file1.txt file2.txt --exec="prog thing1 thing2" --help file4.txt</code></pre>
-</div></div>
-<div class="paragraph"><p>The arguments to <code>program.tcl</code> are just the tokens after <code>program.tcl</code></p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>args() → string</code>
-</dt>
-<dd>
-<p>
-Obtain all arguments as single string
-</p>
-<div class="paragraph"><p>E.g., <code>"-v -a=file1.txt file2.txt --exec="prog thing1 thing2" --help file4.txt"</code></p></div>
-</dd>
-</dl></div>
-<div class="paragraph"><p>The remaining functions are convenience functions oriented around
-Swift conventions. Under these conventions, the example command above
-has <em>flagged</em> arguments <code>v</code>, <code>a=file.txt</code>, <code>exec="prog thing1
-thing2"</code>, and <code>help</code>. The command has <em>unflagged</em> arguments
-<code>file2.txt</code> and <code>file4.txt</code></p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>argc()</code>
-</dt>
-<dd>
-<p>
-Get count of unflagged arguments
-</p>
-</dd>
-<dt class="hdlist1">
-<code>argv(string)</code>
-</dt>
-<dd>
-<p>
-<em>(argument-value)</em>
-Given a string, returns the flagged argument with that key:
-</p>
-<div class="paragraph"><p><code>argv("a") → file1.txt</code></p></div>
-<div class="paragraph"><p>In addition to regular run-time arguments, the STC <em>compile-time
-arguments</em> feature allows <code>argv()</code> arguments to be provided at compile
-time. This allows a specialized, optimized version of code to be
-compiled for a particular set of arguments. See the <code>-A
-<em>name</em>=<em>value</em></code> <a href="#stc_arguments">argument</a> to <code>stc</code>. Note that if the
-argument is re-specified at run-time, an error will occur.</p></div>
-</dd>
-<dt class="hdlist1">
-<code>argp(int)</code>
-</dt>
-<dd>
-<p>
-<em>(argument-positional)</em>
-Given an integer, returns the unflagged argument at that index:
-</p>
-<div class="paragraph"><p><code>argp(2) → file4.txt</code></p></div>
-<div class="paragraph"><p>Given 0, returns the program name,</p></div>
-<div class="paragraph"><p><code>argp(0) → /path/to/program.tcl</code></p></div>
-</dd>
-<dt class="hdlist1">
-<code>argv_accept(string…)</code>
-</dt>
-<dd>
-<p>
-If program is given flagged command line arguments not contained in given
-list, abort.
-E.g., <code>argv_accept("x")</code> would cause program failure at run time
-</p>
-</dd>
-<dt class="hdlist1">
-<code>argv_contains(string) → boolean</code>
-</dt>
-<dd>
-<p>
-Test if the command line contains the given flagged argument:
-</p>
-<div class="paragraph"><p><code>argv_contains("v") → true</code></p></div>
-</dd>
-</dl></div>
-</div>
-<div class="sect3">
-<h4 id="_debugging">12.6.2. Debugging</h4>
-<div class="paragraph"><p><strong>Import:</strong> <code>assert</code></p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>assert(boolean condition, string message)</code>
-</dt>
-<dd>
-<p>
-If condition is false, report <code>message</code> and exit immediately.
-</p>
-</dd>
-</dl></div>
-</div>
-<div class="sect3">
-<h4 id="Turbine_information">12.6.3. Turbine information</h4>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>adlb_servers() → int</code>
-</dt>
-<dd>
-<p>
-Number of ADLB servers
-</p>
-</dd>
-<dt class="hdlist1">
-<code>turbine_workers() → int</code>
-</dt>
-<dd>
-<p>
-Number of Turbine workers
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_files_2">12.7. Files</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>filename(file) → string</code>
-</dt>
-<dd>
-<p>
-Obtain the name of a file
-</p>
-</dd>
-<dt class="hdlist1">
-<code>input(string) → file</code>
-</dt>
-<dd>
-<p>
-Obtain a <code>file</code>. At run time, the
-filesystem is checked for the given file name
-</p>
-</dd>
-<dt class="hdlist1">
-<code>input_file(string) → file</code>
-</dt>
-<dd>
-<p>
-Alias for <code>input()</code>
-</p>
-</dd>
-<dt class="hdlist1">
-<code>input_url(string) → file</code>
-</dt>
-<dd>
-<p>
-Obtain a <code>file</code>. Some
-automatic operations and optimizations are disabled
-</p>
-</dd>
-<dt class="hdlist1">
-<code>urlname(file) → string</code>
-</dt>
-<dd>
-<p>
-Obtain the name of a file created with
-<code>input_url()</code>
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p><strong>Import:</strong> <code>files</code></p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>read(file) → string</code>
-</dt>
-<dd>
-<p>
-Read file as a string
-</p>
-</dd>
-<dt class="hdlist1">
-<code>write(string) → file</code>
-</dt>
-<dd>
-<p>
-Write string to file
-</p>
-</dd>
-<dt class="hdlist1">
-<code>file_lines(file) → string[]</code>
-</dt>
-<dd>
-<p>
-Reads the whole file, returning each line as a separate entry in the
-output array. Comments with <code>#</code> are excised, leading and trailing
-whitespace is trimmed, and blank lines are omitted.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>glob(string) → file[]</code>
-</dt>
-<dd>
-<p>
-Perform glob operation, returning files
-that match. Available glob symbols include:
-</p>
-<div class="ulist"><ul>
-<li>
-<p>
-<code>*</code>: any character sequence (including the zero-length sequence)
-</p>
-</li>
-<li>
-<p>
-<code>?</code>: any character
-</p>
-</li>
-<li>
-<p>
-<code>[chars]</code>: any of the given characters
-</p>
-</li>
-<li>
-<p>
-<code>\x</code>: character <code>x</code>
-</p>
-</li>
-<li>
-<p>
-<code>{a,b,c,…}</code> any of <code>a</code>, <code>b</code>, <code>c</code>, etc.
-</p>
-</li>
-</ul></div>
-</dd>
-</dl></div>
-</div>
-<div class="sect2">
-<h3 id="_blobs_2">12.8. Blobs</h3>
-<div class="paragraph"><p><strong>Import:</strong> <code>blob</code></p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>blob_size(blob) → int</code>
-</dt>
-<dd>
-<p>
-Obtain the size of a blob in bytes.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>blob_null() → blob</code>
-</dt>
-<dd>
-<p>
-Obtain an empty blob of size 0.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>blob_from_string(string) → blob</code>
-</dt>
-<dd>
-<p>
-Convert a string into a blob.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>string_from_blob(blob) → string</code>
-</dt>
-<dd>
-<p>
-Convert a blob into a string. If
-the blob is not NULL-terminated, this function appends the
-NULL-terminator.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>blob_from_floats(float[]) → blob</code>
-</dt>
-<dd>
-<p>
-Convert an array of Swift floats
-(implemented as doubles) to blob containing the C-formatted array of
-doubles .
-</p>
-</dd>
-<dt class="hdlist1">
-<code>blob_from_floats(blob) → float[]</code>
-</dt>
-<dd>
-<p>
-Convert blob containing the
-C-formatted array of doubles to an array of Swift floats
-(implemented as doubles).
-</p>
-</dd>
-<dt class="hdlist1">
-<code>blob_from_ints(int i[]) → blob</code>
-</dt>
-<dd>
-<p>
-Convert blob containing the
-C-formatted array of ints to an array of Swift ints (implemented
-as 64-bit integers).
-</p>
-</dd>
-<dt class="hdlist1">
-<code>blob_from_file(file) → blob</code>
-</dt>
-<dd>
-<p>
-Reads whole file, returning it as a
-blob.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_defining_leaf_functions">13. Defining leaf functions</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>In typical Swift applications, the computationally intensive parts of
-the application are not written in the Swift language. Rather, the
-work is done by <em>leaf functions</em> that are <em>composed</em> together with
-Swift code. Leaf functions may be extension or app functions.</p></div>
-<div class="paragraph"><p>The Swift runtime, Turbine, is built on Tcl, a language which intends
-to makes it easy to call C/C++/Fortran functions. The builtin
-functions mentioned above are implemented as extension functions in
-Tcl, which may wrap C/C++/Fortran functions.</p></div>
-<div class="sect2">
-<h3 id="_swift_extension_functions">13.1. Swift extension functions</h3>
-<div class="paragraph"><p>Currently we support Tcl extension functions, where a function is
-implemented as a Tcl function. Tcl has good support for wrapping
-native C/C++ functions, so this provides an indirect way to call
-C/C++ functions from Swift.</p></div>
-<div class="paragraph"><p>Several components are required to implement a Swift native code function:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Tcl bindings to your function.
-</p>
-</li>
-<li>
-<p>
-For complex types such as structures, arrays and files, you may need
- additional logic to marshal inputs and outputs to/from the global
- data store.
-</p>
-</li>
-<li>
-<p>
-The requisite files required to build a Tcl package
- (e.g <code>pkgIndex.tcl</code>)
-</p>
-</li>
-<li>
-<p>
-Swift declarations for the function that specify the type of the
- function and the Tcl implementation.
-</p>
-</li>
-</ul></div>
-<div class="sect3">
-<h4 id="_simple_tcl_fragment_example">13.1.1. Simple Tcl fragment example</h4>
-<div class="paragraph"><p>In this example, the Swift program will simply use Tcl to output a
-string:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>() my_output (string s) "turbine" "0.0" [
- "puts <<s>>"
-];
-
-main {
- my_output("HELLO");
-}</code></pre>
-</div></div>
-<div class="paragraph"><p><code>puts</code> is the Tcl builtin for screen output, like <code>puts()</code> in C.</p></div>
-<div class="paragraph"><p>The above definition has, from left to right, the output arguments
-(none), the name of the new Swift function, input arguments, the name
-of the Tcl package containing the file (here, none, so we use
-<code>turbine</code>), and the minimum version of that package (here, 0.0).</p></div>
-<div class="paragraph"><p>We tell the compiler how to call our Tcl function using inline
-Tcl code as a template with variable names surrounded by <code><< >></code>
-indicating where variables should be substituted.</p></div>
-</div>
-<div class="sect3">
-<h4 id="_simple_tcl_package_example">13.1.2. Simple Tcl package example</h4>
-<div class="paragraph"><p>In this first example we will implement a trivial Tcl extension function
-that doubles an integer. Here is the Tcl code that will go in
-<code>myextension.tcl</code>:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>namespace eval myextension {
- proc double { x } {
- return [ expr $x * 2 ]
- }
-}</code></pre>
-</div></div>
-<div class="paragraph"><p>Here is the Swift function definition that will go in <code>myextension.swift</code>:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>@pure
-(int o) double (int i) "myextension" "0.0.1" [
- "set <<o>> [ myextension::double <<i>> ]"
-];</code></pre>
-</div></div>
-<div class="paragraph"><p>We can also tell the Swift compiler a little about the function so
-that it can better optimize your programs. For example, <code>double</code> has
-no side-effects and produces the same result each time for the same
-arguments (i.e. is deterministic), so we can annotate it as a <code>@pure</code>
-function.</p></div>
-<div class="paragraph"><p>If your function has a long running time and should be dispatched to a
-worker process for execution, then you need to label the function as a
-worker function, for example:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>@dispatch=WORKER
-(int o) process (int i) "pkg" "0.0.1" [
- "set <<o>> [ pkg::process <<i>> ]"
-];</code></pre>
-</div></div>
-<div class="paragraph"><p>Tcl code is conventionally placed into <em>packages</em>. In this example,
-<code>myextension.tcl</code> would be part of the package.</p></div>
-<div class="paragraph"><p>More information about building Tcl packages may be found
-<a href="http://www.tcl.tk/man/tcl8.5/TclCmd/pkgMkIndex.htm">here</a>. Ultimately,
-you produce a <code>pkgIndex.tcl</code> file that contains necessary information
-about the package.</p></div>
-<div class="paragraph"><p>To ensure that Swift can find your package, use</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>stc -r <package directory> ...</code></pre>
-</div></div>
-<div class="paragraph"><p>or set <code>TURBINE_USER_LIB</code> at run time.</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>Tip:</strong> advanced users can also create <a href="#mkstatic">standalone executables</a>
- with compiled code and Tcl code for the extension directly linked in.
-</p>
-</li>
-</ul></div>
-</div>
-<div class="sect3">
-<h4 id="_swift_tcl_data_type_mapping">13.1.3. Swift/Tcl data type mapping</h4>
-<div class="paragraph"><p>If you are defining Tcl functions in the way above with inline
-Tcl code, Swift types are mapped to Tcl types in the following way:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<code>int</code>/<code>float</code>/<code>string</code>/<code>bool</code> are converted to the standard
- Tcl representations
-</p>
-</li>
-<li>
-<p>
-blobs are represented as a Tcl list with first element a pointer
- to the data, the second element the length of the data, and if
- the blob was loaded from the ADLB data store, a third element
- which is the ADLB ID of the blob
-</p>
-</li>
-<li>
-<p>
-files are represented as a list, with the first element the
- file path, and the second element a reference count
-</p>
-</li>
-</ul></div>
-</div>
-<div class="sect3">
-<h4 id="_calling_native_libraries_from_swift">13.1.4. Calling native libraries from Swift</h4>
-<div class="paragraph"><p>The first step is to test that you can successfully call your
-C/C++/Fortran function from a test Tcl script. If so, you will then
-be able to use the Swift→Tcl techniques to call it from Swift.</p></div>
-<div class="paragraph"><p>A popular tool to automate Tcl→C bindings is
-<a href="http://www.swig.org">SWIG</a>, which will wrap your C/C++ functions and
-help you produce a Tcl package suitable for use by Swift.</p></div>
-<div class="paragraph"><p>To call Fortran functions, first wrap your code with
-<a href="http://fortwrap.sourceforge.net">FortWrap</a>. Then, use SWIG to produce
-Tcl bindings.</p></div>
-</div>
-<div class="sect3">
-<h4 id="_writing_custom_tcl_interfaces">13.1.5. Writing custom Tcl interfaces</h4>
-<div class="paragraph"><p>For Tcl functions that take complex argument types, such as arrays or
-structures, you may need to write a Tcl wrapper function that is
-directly passed references to data in Swift’s global data store. In
-this case your function must manually retrieve/store data from/to the
-global distributed data store. In this case, you do not use the STC
-Tcl argument substitution syntax (<code><<<code>i</code>>></code>).</p></div>
-<div class="paragraph"><p>Consider this custom Swift→Tcl binding:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>(int o) complex_function (int arr[]) "pkg" "0.0.1" "complex";</code></pre>
-</div></div>
-<div class="paragraph"><p>This function jumps into Tcl function <code>complex</code>, which must
-perform its own data dependency management.</p></div>
-<div class="paragraph"><p>See the <a href="leaf.html">Swift/T Leaf Function Guide</a> for more
-information about this process.</p></div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="app_functions">13.2. App functions</h3>
-<div class="paragraph"><p>App functions are functions that are implemented as command-line
-programs. These command-line programs can be brought into a Swift
-program as functions with typed inputs and outputs.
-An app function definition comprises:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-The standard components of a Swift function declaration: input and
- output arguments and the function name. Note that the output
- variable types are restricted to individual <code>file</code>s.
-</p>
-</li>
-<li>
-<p>
-The command line, which comprises an initial string which is the
- executable to run, and then a series of arguments which are
- the command-line arguments to pass to the program.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>App arguments can be:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Literals such as numbers or strings.
-</p>
-</li>
-<li>
-<p>
-File variables (passed as file paths).
-</p>
-</li>
-<li>
-<p>
-Other variables, which are converted to string arguments.
- Arrays (including multi-dimensional arrays) are expanded to
- multiple arguments.
-</p>
-</li>
-<li>
-<p>
-Arbitrary expressions surrounded by parentheses.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Standard input, output and error can be redirected to files via
-<code>@stdin=</code>, <code>@stdout=</code>, and <code>@stderr=</code> expressions. If used, these should point
-to a <code>file</code>.</p></div>
-<div class="paragraph"><p>Here is an example of an app function that joins multiple files
-with the <code>cat</code> utility:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>import files;
-
-app (file out) cat (file inputs[]) {
- "/bin/cat" inputs @stdout=out
-}
-
-main {
- file joined <"joined.txt"> = cat(glob("*.txt"));
-}</code></pre>
-</div></div>
-<div class="paragraph"><p>Here is an example of an app function that sleeps for an arbitrary
-amount of time:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>app (void signal) sleep (int secs) {
- "/bin/sleep" secs
-}
-
-main {
- foreach time in [1:5] {
- void signal = sleep(time);
- // Wait on output signal so that trace occurs after sleep
- wait(signal) {
- trace("Slept " + fromint(time));
- }
- }
-}</code></pre>
-</div></div>
-</div>
-<div class="sect2">
-<h3 id="_external_scripting_support">13.3. External scripting support</h3>
-<div class="sect3">
-<h4 id="_calling_python">13.3.1. Calling Python</h4>
-<div class="paragraph"><p>You can evaluate arbitrary Python code from within Swift/T. For
-example, you can perform processing with a Python library.
-Once you have that working, you can use Swift/T to coordinate
-concurrent calls to that library.</p></div>
-<div class="paragraph"><p>Consider the following Swift script:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>import io;
-import python;
-
-main {
- i = python("print(\"python works\")\nrepr(2+2)");
- printf("i: %s", i);
-}</code></pre>
-</div></div>
-<div class="paragraph"><p>This simply evaluates the Python code line by line. The last line must
-return a Python string to Swift, in this case, the Python string
-<code>'4'</code>. The expected output is shown below:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>python works
-i: 4</code></pre>
-</div></div>
-<div class="paragraph"><p>Swift multi-line strings may be used to enter more complex Python code
-without the explicit use of <code>\n</code>.</p></div>
-<div class="paragraph"><p>Additionally, you can call Python libraries such as
-<a href="http://www.numpy.org">Numpy</a> if available on your system. The
-following code adds matrices <em>I</em><sub>3</sub> + <em>I</em><sub>3</sub> using Numpy arrays.</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>import io;
-import python;
-import string;
-
-global const string numpy = "from numpy import *\n\n";
-
-typedef matrix string;
-
-(matrix A) eye(int n)
-{
- string command = sprintf("repr(eye(%i))", n);
- string code = numpy+command;
- matrix t = python(code);
- A = replace_all(t, "\n", "", 0);
-}
-
-(matrix R) add(matrix A1, matrix A2)
-{
- string command = sprintf("repr(%s+%s)", A1, A2);
- string code = numpy+command;
- matrix t = python(code);
- R = replace_all(t, "\n", "", 0);
-}
-
-main
-{
- matrix A1 = eye(3);
- matrix A2 = eye(3);
- matrix sum = add(A1, A2);
- printf("2*eye(3)=%s", sum);
-}</code></pre>
-</div></div>
-<div class="paragraph"><p>An Python script template is created that imports Numpy and performs
-some simple calculations. This code is represented in a Swift string.
-The template is filled in by the Swift call to <code>sprintf()</code>. Then, the
-code is passed to Python for evaluation. The output is:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>2*eye(3)=array([[ 2., 0., 0.],
- [ 0., 2., 0.],
- [ 0., 0., 2.]])</code></pre>
-</div></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<div class="title">Note</div>
-</td>
-<td class="content">To use this, Turbine must be configured with Python enabled
- before compiling, by setting <code>ENABLE_PYTHON=1</code>
- in <code>exm-settings.sh</code>, or by providing the <code>--enable-python</code> argument
- to <code>configure</code>. This feature is implemented by linking to Python
- as a shared library, enabling better performance than calling the
- <code>python</code> program (which may be done by using a normal Swift
- <a href="#app_functions">app function</a>). Error messages for minor coding
- mistakes may be badly mangled and refer to missing Python symbols-
- refer to the first error in the Python stack trace.</td>
-</tr></table>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_calling_r">13.3.2. Calling R</h4>
-<div class="paragraph"><p>Consider the following Swift script:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>import io;
-import string;
-import R;
-
-global const string template =
-"""
- x <- %i
- a <- x+100
- cat("the answer is: ", a, "\\n")
- a
-""";
-
-main
-{
- code = sprintf(template, 4);
- s = R(code);
- printf("the answer was: %i", s);
-}</code></pre>
-</div></div>
-<div class="paragraph"><p>An <a href="http://www.r-project.org">R language</a> script template is placed in a
-Swift string. The template is filled in with the value 4 by the Swift
-call to <code>sprintf()</code> (note the <code>%i</code> conversion specifier). Then, the
-code is passed to R for evaluation. The output is:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>the answer is: 104
-the answer was: 104</code></pre>
-</div></div>
-<div class="paragraph"><p>As coded here, both R and Swift report the value of <code>a</code>.</p></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<div class="title">Note</div>
-</td>
-<td class="content">To use this, Turbine must be configured with R enabled
- before compiling, by setting <code>ENABLE_R=1</code>
- in <code>exm-settings.sh</code>, or by providing the <code>--enable-r</code> argument
- to <code>configure</code>. This feature is implemented by linking to R as a shared
- library, enabling better performance than calling the <code>R</code> program
- (which may be done by using a normal Swift <a href="#app_functions">app function</a>). When installing R, be sure to include the <code>devel</code>
- package. When installing R from source, configure with
- <code>--enable-R-shlib</code>. You may need to set the environment variable
- <code>R_HOME</code> to the directory containing the R installation. For the APT
- package, this is <code>/usr/lib/R</code>.</td>
-</tr></table>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_calling_julia">13.3.3. Calling Julia</h4>
-<div class="paragraph"><p>Consider the following Swift script:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>import io;
-import julia;
-import string;
-import sys;
-
-main {
- start = clock();
- f =
-"""
-begin
- f(x) = begin
- sleep(1)
- x+1
- end
- f(%s)
-end
-""";
- s1 = julia(sprintf(f, 1));
- s2 = julia(sprintf(f, 2));
- s3 = julia(sprintf(f, 3));
- printf("julia results: %s %s %s", s1, s2, s3);
- wait (s1, s2, s3) {
- printf("duration: %0.2f", clock()-start);
- }
-}</code></pre>
-</div></div>
-<div class="paragraph"><p>In this example, a <a href="http://julialang.org">Julia</a> script is placed in
-string <code>f</code>. It is parameterized three times by <code>sprintf()</code>. Each
-Julia invocation runs concurrently (if enough processes are provided
-to Swift/T).</p></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<div class="title">Note</div>
-</td>
-<td class="content">To use this, Turbine must be configured with Julia enabled
- before compiling, by providing the <code>--enable-julia</code> argument
- to <code>configure</code>. This feature is implemented by linking to Julia
- as a shared library, enabling better performance than calling the
- <code>julia</code> program (which may be done by using a normal Swift
- <a href="#app_functions">app function</a>).</td>
-</tr></table>
-</div>
-</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="Optimizations">14. Optimizations</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>STC performs a range of compiler optimizations that can significantly
-speed up most Swift programs. The optimization level can be controlled
-by the <code>-O</code> command line option. The default optimization
-level <code>-O2</code>, or the increased optimization level <code>-O3</code> are usually
-the best choices. Some applications benefit markedly from <code>-O3</code>,
-while others do not, and compile times can increase slightly.</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code># No optimizations at all (not recommended)
-stc -O0 example.swift example.tcl
-
-# Basic optimizations (not recommended)
-stc -O1 example.swift example.tcl
-
-# Standard optimizations (recommended)
-stc example.swift example.tcl
-# OR
-stc -O2 example.swift example.tcl
-
-# All optimizations (also recommended)
-stc -O3 example.swift example.tcl</code></pre>
-</div></div>
-<div class="paragraph"><p>Individual optimizations can be toggled on using <code>-T <opt name></code>
-or off with <code>-t <opt name></code>, but this typically is only useful for
-debugging. You can find an up-to-date list of optimizations in
-the stc command-line help:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>stc -h</code></pre>
-</div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="Turbine">15. Running in Turbine</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The following describes how to run Turbine programs.</p></div>
-<div class="sect2">
-<h3 id="_architecture">15.1. Architecture</h3>
-<div class="paragraph"><p>Turbine runs as an MPI program consisting of many processes. Turbine
-programs are ADLB programs. Thus, they produce and execute discrete
-tasks that are distributed and load balanced at run time.</p></div>
-<div class="paragraph"><p>Each process runs in a <em>mode</em>: <em>worker</em>, or <em>server</em>.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Workers
-</dt>
-<dd>
-<p>
-Evaluate the Swift logic. Produce tasks. Execute tasks.
-</p>
-</dd>
-<dt class="hdlist1">
-Servers
-</dt>
-<dd>
-<p>
-Distributes tasks. Manages data.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Typical Swift programs perform compute-intensive work in leaf
-functions that execute on workers.
-Execution of the Swift logic is split and distributed among workers.</p></div>
-<div class="paragraph"><p>Servers distribute tasks in a scalable, load balanced manner. They
-also store Swift data (integers, strings, etc.).</p></div>
-</div>
-<div class="sect2">
-<h3 id="_concurrency">15.2. Concurrency</h3>
-<div class="paragraph"><p>The available concurrency and efficiency in your Swift script is
-limited by the following factors:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-The available concurrency in the Swift logic. Sequential
- dependencies will be evaluated sequentially. <code>foreach</code> loops and
- branching function calls may be evaluated concurrently
-</p>
-</li>
-<li>
-<p>
-The number of workers available to process leaf functions
- concurrently
-</p>
-</li>
-<li>
-<p>
-The number of servers available to control the Turbine run.
- Adding more servers can improve performance for applications with
- small tasks or complex data dependencies but ties up processes
-</p>
-</li>
-</ul></div>
-</div>
-<div class="sect2">
-<h3 id="_invocation">15.3. Invocation</h3>
-<div class="paragraph"><p>The form of a Turbine invocation for STC-generated
-<code>program.tcl</code> is:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>turbine <turbine arguments> <program.tcl> <program arguments></code></pre>
-</div></div>
-<div class="paragraph"><p>The program arguments are available to Swift (<a href="#argv">[argv]</a>).</p></div>
-<div class="paragraph"><p>Turbine accepts the following arguments:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>-f <file></code>
-</dt>
-<dd>
-<p>
-Provide a machine file to <code>mpiexec</code>
-</p>
-</dd>
-<dt class="hdlist1">
-<code>-h</code>
-</dt>
-<dd>
-<p>
-Print a help message
-</p>
-</dd>
-<dt class="hdlist1">
-<code>-l</code>
-</dt>
-<dd>
-<p>
-Enable <code>mpiexec -l</code> ranked output formatting
-</p>
-</dd>
-<dt class="hdlist1">
-<code>-n <procs></code>
-</dt>
-<dd>
-<p>
-The total number of Turbine MPI processes
-</p>
-</dd>
-<dt class="hdlist1">
-<code>-v</code>
-</dt>
-<dd>
-<p>
-Report the Turbine version number
-</p>
-</dd>
-<dt class="hdlist1">
-<code>-V</code>
-</dt>
-<dd>
-<p>
-Make the Turbine launch script verbose
-</p>
-</dd>
-<dt class="hdlist1">
-<code>-x</code>
-</dt>
-<dd>
-<p>
-Use turbine_sh launcher with compiled-in libraries instead of tclsh
- (reduces number of files that must be read from file system)
-</p>
-</dd>
-<dt class="hdlist1">
-<code>-X</code>
-</dt>
-<dd>
-<p>
-In place of of program.tcl, run standalone Turbine executable
- (e.g. created by <a href="#mkstatic">mkstatic.tcl</a>)
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>The user controls the Turbine run time configuration through
-environment variables:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>ADLB_SERVERS</code>
-</dt>
-<dd>
-<p>
-Number of ADLB servers
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>The remaining processes are workers. These values are available to
-Swift (<a href="#Turbine_information">Turbine information</a>).</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>TURBINE_LOG=0</code>
-</dt>
-<dd>
-<p>
-Disable logging. <code>TURBINE_LOG=1</code> or unset enables
-logging, assuming logging was not disabled at configure time. Logging
-goes to tandard output by default.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>TURBINE_LOG_FILE=<file></code>
-</dt>
-<dd>
-<p>
-Set log file location. Defaults to
-standard output.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>TURBINE_LOG_RANKS=1</code>
-</dt>
-<dd>
-<p>
-Using <code>turbine -l</code> or equivalent prepend the
-MPI rank number to each output line. This works with typical MPICH or
-OpenMPI systems, however, this is not available on some systems, so
-set this to emulate the rank output on such systems.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>ADLB_PRINT_TIME=1</code>
-</dt>
-<dd>
-<p>
-Enable a short report of total elapsed time (via
-<code>MPI_Wtime()</code>)
-</p>
-</dd>
-<dt class="hdlist1">
-<code>ADLB_PERF_COUNTERS=1</code>
-</dt>
-<dd>
-<p>
-Enable performance counters (printed at end of execution). The
-<a href="internals.html">Swift/T internals guide</a> has information
-about interpreting the output.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>ADLB_EXHAUST_TIME</code>
-</dt>
-<dd>
-<p>
-Time in seconds taken by ADLB task servers to shut down. May include
-a decimal point. Default 0.1 . Setting this lower will reduce
-delay in detection exhaustion. Setting this higher will reduce
-overhead due to failed exhaust checks. The default setting is
-almost always adequate.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>ADLB_REPORT_LEAKS=1</code>
-</dt>
-<dd>
-<p>
-Enable reporting of any unfreed data in ADLB data store at end of
-execution.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>ADLB_TRACE=true</code>
-</dt>
-<dt class="hdlist1">
-<code>ADLB_DEBUG=true</code>
-</dt>
-<dd>
-<p>
-To print DEBUG/TRACE level information for ADLB (if ADLB was compiled
-with it enabled)
-</p>
-</dd>
-<dt class="hdlist1">
-<code>TURBINE_LAUNCH_OPTIONS</code>
-</dt>
-<dd>
-<p>
-Provide other arguments to <code>mpiexec</code>, such as a machine file, etc.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>TURBINE_SRAND</code>
-</dt>
-<dd>
-<p>
-If unset or empty, the random number generator seed will be set to the
-process rank for each process, giving reproducible results. If set to
-an integer <code>seed</code>, the random number generator seed for each process
-will be set to <code>seed</code> + <code>rank</code>.
-</p>
-<div class="paragraph"><p>For non-reproducible random results, use the following shell commands:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>export TURBINE_SRAND=$( date +%s )
-turbine ...</code></pre>
-</div></div>
-<div class="paragraph"><p>The seed is recorded in the log.</p></div>
-</dd>
-<dt class="hdlist1">
-<code>ADLB_DEBUG_RANKS=1</code>
-</dt>
-<dd>
-<p>
-Enable a report showing the rank and hostname
-of each process. This allows you to determine whether your process
-layout on a given machine is as intended.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>ADLB_DEBUG_HOSTMAP=1</code>
-</dt>
-<dd>
-<p>
-Enable a report showing the hostmap, which
-maps hostnames to ranks for use with the location functionality.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>ADLB_DISABLE_HOSTMAP=1</code>
-</dt>
-<dd>
-<p>
-Prevent the hostmap from being constructed.
-</p>
-</dd>
-</dl></div>
-</div>
-<div class="sect2">
-<h3 id="Build_configuration">15.4. Build configuration</h3>
-<div class="paragraph"><p>The following describes how to turn Swift/T programs in Turbine
-on more complex systems.</p></div>
-<div class="sect3">
-<h4 id="_build_troubleshooting">15.4.1. Build troubleshooting</h4>
-<div class="paragraph"><p>If <code>exm-setup.zsh</code> does not succeed, you may need to change how it
-tries to configure and compile Swift/T.</p></div>
-<div class="paragraph"><p>Troubleshooting a build problem can require a few steps. The first
-step is to determine why the build failed. <code>exm-setup.zsh</code> will usually
-report the step at which configuration failed. For example, if it was unable
-to locate a valid Tcl install, it will report this. Then you can try
-these steps to resolve the problem:</p></div>
-<div class="olist arabic"><ol class="arabic">
-<li>
-<p>
-If your system is covered by the <a href="turbine-sites.html">Sites Guide</a>,
- check to see if the problem and solution are described there.
-</p>
-</li>
-<li>
-<p>
-Inspect <code>exm-settings.sh</code> settings related to the reported problem.
- For example, if locating a Tcl install failed, setting
- the <code>TCL_INSTALL</code> and <code>TCL_VERSION</code> variables to the correct location
- and version may help.
-</p>
-</li>
-<li>
-<p>
-If the options in <code>exm-settings.sh</code> do not give sufficient control to
- fix the problem, you may need to manually configure some components
- of Swift/T, as described in the next section.
-</p>
-</li>
-</ol></div>
-</div>
-<div class="sect3">
-<h4 id="Manual_build_configuration">15.4.2. Manual configuration</h4>
-<div class="paragraph"><p><code>exm-setup.zsh</code> and <code>exm-settings.sh</code> provide a convenient way to install
-Swift/T. However, this method does not allow full control over
-the configuration. Swift/T is built with standard Ant (Java) and
-Autotools/Makefile (C,Tcl) techniques. You can more directly control
-the configuration when building through the arguments to <code>ant</code> or
-<code>configure</code>.</p></div>
-<div class="paragraph"><p>To perform the installation using <code>configure</code>/<code>make</code>, simply untar the
-distribution package and do:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>cd c-utils
-./configure ...
-make install
-
-cd ../lb
-./configure ...
-make install
-
-cd ../turbine
-./configure ...
-make install
-
-cd ../stc
-ant install -Ddist.dir=... -Dturbine.home=...</code></pre>
-</div></div>
-<div class="ulist"><ul>
-<li>
-<p>
-You may use <code>./configure --help</code> and the
- <a href="turbine-sites.html">Sites Guide</a> for further options.
-</p>
-</li>
-</ul></div>
-</div>
-<div class="sect3">
-<h4 id="_non_standard_mpi_locations">15.4.3. Non-standard MPI locations</h4>
-<div class="paragraph"><p>Sometimes simply specifying the MPI directory is not enough to
-configure Swift/T.</p></div>
-<div class="paragraph"><p>You can modify these settings in <code>exm-settings.sh</code> to more precisely
-define locations of MPI resources</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>EXM_CUSTOM_MPI=1
-MPI_INCLUDE=/path/to/mpi.h/include
-MPI_LIB_DIR=/path/to/mpi_lib/lib
-MPI_LIB_NAME=funny.mpi.a</code></pre>
-</div></div>
-<div class="paragraph"><p>If you are following the manual build process, configure Turbine with:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code> --enable-custom --with-mpi-include=/path/to/mpi.h/include
- --with-mpi-lib-dir=/path/to/mpi_lib/lib
- --with-mpi-lib-name=funny.mpi.a</code></pre>
-</div></div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_performance_enhancements">15.5. Performance enhancements</h3>
-<div class="olist arabic"><ol class="arabic">
-<li>
-<p>
-Disable logging/debugging via environment
-</p>
-</li>
-<li>
-<p>
-Disable logging/debugging at configure/compile time
-</p>
-<div class="ulist"><ul>
-<li>
-<p>
-Configure c-utils with <code>--disable-log</code>
-</p>
-</li>
-</ul></div>
-</li>
-<li>
-<p>
-Specify <code>EXM_OPT_BUILD=1</code> in <code>exm-settings.sh</code> or configure everything
- with <code>--enable-fast</code>. This disables assertions and other checks
-</p>
-</li>
-<li>
-<p>
-When making performance measurements, always subtract 0.1 seconds
- (or the value of <code>ADLB_EXHAUST_TIME</code>) from the Turbine run time
- due to the ADLB shutdown protocol, which does not start until the
- system is idle for that amount of time.
-</p>
-</li>
-<li>
-<p>
-Reduce the number of program files that must be read off the
- filesystem. This is particularly useful for parallel file systems
- and large scale applications. In increasing order of effectiveness,
- you can:
-</p>
-<div class="ulist"><ul>
-<li>
-<p>
-use the turbine_sh launcher in place of tclsh in submit script,
- or by specifying the <code>-x</code> argument to <code>turbine</code>
-</p>
-</li>
-<li>
-<p>
-Use <a href="#mkstatic">mkstatic.tcl</a> to create a standalone executable with
- the Tcl main script and Tcl library code compiled in, and compiled
- code statically linked.
-</p>
-</li>
-</ul></div>
-</li>
-</ol></div>
-</div>
-<div class="sect2">
-<h3 id="mkstatic">15.6. Building standalone executables with mkstatic.tcl</h3>
-<div class="paragraph"><p>It is possible to build a fully self-contained executable, including
-all Tcl scripts and compiled code, provided that all dependencies support
-static linking. If not, it is also possible to build an executable with
-a subset of Tcl scripts and code linked in, providing some performance
-benefits.</p></div>
-<div class="paragraph"><p>The provided <code>mkstatic.tcl</code> utility can produce a C source
-file with Tcl scripts bundled in, which can then be compiled and linked
-with a C compiler. This is a multi-step process that can be automated
-as part of your build process.</p></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<div class="title">Note</div>
-</td>
-<td class="content">Ensure that static versions of the <code>c-utils</code>, <code>lb</code>, and <code>turbine</code> libraries
- were built, typically with a <code>.a</code> suffix, e.g. <code>libadlb.a</code>. These
- are created by default, unless you specified <code>DISABLE_STATIC=0</code> or
- <code>--disable-static</code>. To build a fully standalone
- executable, you will also need to build a static version of Tcl
- (with the <code>--disable-shared</code> configure option), and static versions
- of any other libraries your own code needs to link with, such
- as your MPI distribution or application code.</td>
-</tr></table>
-</div>
-<div class="olist arabic"><ol class="arabic">
-<li>
-<p>
-Compile your Swift script
-</p>
-<div class="listingblock">
-<div class="content">
-<pre><code>stc my.swift</code></pre>
-</div></div>
-<div class="paragraph"><p>producing the Turbine Tcl script <code>my.tcl</code>.</p></div>
-</li>
-<li>
-<p>
-Create a manifest file, e.g. <code>my.manifest</code>. This file describes the
- resources to be bundled, including the STC-generated code and any
- user libraries.
-</p>
-<div class="paragraph"><p>To do this, make a copy of <code>scripts/mkstatic/example.manifest</code> from
-the Turbine installation directory. This file contains examples and
-descriptions of all the the possible settings.
-Note that an empty
-manifest file corresponds to the <code>turbine_sh</code> utility, which is a
-replacement for <code>tclsh</code> with required Turbine libraries statically
-linked in.
-For a simple Swift program with no user Tcl libraries,
-you only need to set <code>main_script = my.tcl</code>.</p></div>
-</li>
-<li>
-<p>
-Invoke <code>mkstatic.tcl</code> (found under <code>scripts/mkstatic/mkstatic.tcl</code> in
- the Turbine installation) to translate your Tcl script to a C main
- program (e.g., <code>my_main.c</code>) with Tcl source code included.
- The minimal invocation is
-</p>
-<div class="listingblock">
-<div class="content">
-<pre><code>mkstatic.tcl my.manifest -c my_main.c</code></pre>
-</div></div>
-<div class="paragraph"><p>You will likely wish to include Tcl system libraries with
-<code>--include-sys-lib /home/example/tcl-install/lib --tcl-version 8.6</code>.
-The Tcl system library directory can be identified by the fact that
-it contains the file <code>init.tcl</code>. This directory must be specified
-with a special flag so that <code>mkstatic.tcl</code> can correctly replace
-the regular Tcl initialization process.</p></div>
-<div class="paragraph"><p>You can include additional libraries and packages with
-<code>--include-lib /home/example/tcl-lib/</code>. Any <code>.tcl</code> or <code>.tm</code> source files
-in the directory will be included. Source-only packages can
-generally be completely linked into the executable, but if a package
-loads shared libraries, only the <code>pkgIndex.tcl</code> file will be linked
-into the executable. A package with compiled code can be converted to
-support static linking by specifying a package init function, plus
-static library or object files in the manifest file.</p></div>
-</li>
-<li>
-<p>
-Link together the compiled C main program with user libraries and
- Swift/T libraries to produce a final executable. The details of the
- process vary depending on the compiler and system: we assume GCC.
- You will need to provide the correct flags to link in all libraries
- required by Swift/T or your own user code.
-</p>
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>User code:</strong> you must identify the libraries used by your application
- and ensure link flags are provided. If linking static libraries, ensure
- that any indirect dependencies of these libraries are also linked.
-</p>
-</li>
-<li>
-<p>
-<strong>Swift/T system:</strong> The Turbine distribution includes a helper script,
- <code>turbine-build-config.sh</code>, that can be sourced to obtain linker flags
- for Swift/T dependencies.
-</p>
-</li>
-<li>
-<p>
-<strong>Link order:</strong> In the case of static linking, if <strong>libA</strong> depends on <strong>libB</strong>,
- then the <code>-lA</code> flag must precede <code>-lB</code> on the command line. To
- actually do the linking, there are two further cases to consider:
-</p>
-<div class="ulist"><ul>
-<li>
-<p>
-If building a fully static executable, you can
- provide the <code>-static</code> flag, plus all object files, plus <code>-L</code>
- and <code>-l</code> flags for all required library directories and libraries.
-</p>
-<div class="listingblock">
-<div class="content">
-<pre><code>gcc -static script_main.c file1.o file2.o -L/path/to/lib/dir -lsomething ...</code></pre>
-</div></div>
-</li>
-<li>
-<p>
-If you are building an executable that depends on one or more shared
- libraries, you will need to provide the <code>-dynamic</code> flag, and then
- ensure that static libraries are linked statically. If a shared
- version of a library is available, <code>gcc</code> will use that in preference
- to a static version. You can override this behaviour by specifying
- <code>-Wl,-Bstatic</code> on the command line before the flags for the libraries
- you wish to statically link, then <code>-Wl,-Bdynamic</code> to reset to
- dynamic linking for any libraries after those.
-</p>
-</li>
-</ul></div>
-</li>
-</ul></div>
-</li>
-</ol></div>
-<div class="paragraph"><p>We have described the most commonly-used options. A full list of options
-and descriptions can be obtained by invoking <code>mkstatic.tcl -h</code>.
-Additional options include:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>--main-script</code>
-</dt>
-<dd>
-<p>
-Specify Tcl main script (overrides manifest file)
-</p>
-</dd>
-<dt class="hdlist1">
-<code>-r</code>
-</dt>
-<dd>
-<p>
-Specify non-standard variable prefix for C code
-</p>
-</dd>
-<dt class="hdlist1">
-<code>-v</code>
-</dt>
-<dd>
-<p>
-Print verbose messages
-</p>
-</dd>
-<dt class="hdlist1">
-<code>--deps</code>
-</dt>
-<dd>
-<p>
-Generate Makefile include for generating C file
-</p>
-</dd>
-<dt class="hdlist1">
-<code>--ignore-no-manifest</code>
-</dt>
-<dd>
-<p>
-Pretend empty manifest present
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-</div>
-</div>
-<div id="footnotes"><hr /></div>
-<div id="footer">
-<div id="footer-text">
-Last updated 2014-07-18 17:10:42 CDT
-</div>
-</div>
-</body>
-</html>
Added: www/Swift-T/turbine-sites.html
===================================================================
--- www/Swift-T/turbine-sites.html (rev 0)
+++ www/Swift-T/turbine-sites.html 2014-07-21 19:22:06 UTC (rev 8056)
@@ -0,0 +1,2161 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
+ "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+<head>
+<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
+<meta name="generator" content="AsciiDoc 8.6.9" />
+<title>Turbine Sites Guide</title>
+<style type="text/css">
+/* Shared CSS for AsciiDoc xhtml11 and html5 backends */
+
+/* Default font. */
+body {
+ font-family: Georgia,serif;
+}
+
+/* Title font. */
+h1, h2, h3, h4, h5, h6,
+div.title, caption.title,
+thead, p.table.header,
+#toctitle,
+#author, #revnumber, #revdate, #revremark,
+#footer {
+ font-family: Arial,Helvetica,sans-serif;
+}
+
+body {
+ margin: 1em 5% 1em 5%;
+}
+
+a {
+ color: blue;
+ text-decoration: underline;
+}
+a:visited {
+ color: fuchsia;
+}
+
+em {
+ font-style: italic;
+ color: navy;
+}
+
+strong {
+ font-weight: bold;
+ color: #083194;
+}
+
+h1, h2, h3, h4, h5, h6 {
+ color: #527bbd;
+ margin-top: 1.2em;
+ margin-bottom: 0.5em;
+ line-height: 1.3;
+}
+
+h1, h2, h3 {
+ border-bottom: 2px solid silver;
+}
+h2 {
+ padding-top: 0.5em;
+}
+h3 {
+ float: left;
+}
+h3 + * {
+ clear: left;
+}
+h5 {
+ font-size: 1.0em;
+}
+
+div.sectionbody {
+ margin-left: 0;
+}
+
+hr {
+ border: 1px solid silver;
+}
+
+p {
+ margin-top: 0.5em;
+ margin-bottom: 0.5em;
+}
+
+ul, ol, li > p {
+ margin-top: 0;
+}
+ul > li { color: #aaa; }
+ul > li > * { color: black; }
+
+.monospaced, code, pre {
+ font-family: "Courier New", Courier, monospace;
+ font-size: inherit;
+ color: navy;
+ padding: 0;
+ margin: 0;
+}
+pre {
+ white-space: pre-wrap;
+}
+
+#author {
+ color: #527bbd;
+ font-weight: bold;
+ font-size: 1.1em;
+}
+#email {
+}
+#revnumber, #revdate, #revremark {
+}
+
+#footer {
+ font-size: small;
+ border-top: 2px solid silver;
+ padding-top: 0.5em;
+ margin-top: 4.0em;
+}
+#footer-text {
+ float: left;
+ padding-bottom: 0.5em;
+}
+#footer-badges {
+ float: right;
+ padding-bottom: 0.5em;
+}
+
+#preamble {
+ margin-top: 1.5em;
+ margin-bottom: 1.5em;
+}
+div.imageblock, div.exampleblock, div.verseblock,
+div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
+div.admonitionblock {
+ margin-top: 1.0em;
+ margin-bottom: 1.5em;
+}
+div.admonitionblock {
+ margin-top: 2.0em;
+ margin-bottom: 2.0em;
+ margin-right: 10%;
+ color: #606060;
+}
+
+div.content { /* Block element content. */
+ padding: 0;
+}
+
+/* Block element titles. */
+div.title, caption.title {
+ color: #527bbd;
+ font-weight: bold;
+ text-align: left;
+ margin-top: 1.0em;
+ margin-bottom: 0.5em;
+}
+div.title + * {
+ margin-top: 0;
+}
+
+td div.title:first-child {
+ margin-top: 0.0em;
+}
+div.content div.title:first-child {
+ margin-top: 0.0em;
+}
+div.content + div.title {
+ margin-top: 0.0em;
+}
+
+div.sidebarblock > div.content {
+ background: #ffffee;
+ border: 1px solid #dddddd;
+ border-left: 4px solid #f0f0f0;
+ padding: 0.5em;
+}
+
+div.listingblock > div.content {
+ border: 1px solid #dddddd;
+ border-left: 5px solid #f0f0f0;
+ background: #f8f8f8;
+ padding: 0.5em;
+}
+
+div.quoteblock, div.verseblock {
+ padding-left: 1.0em;
+ margin-left: 1.0em;
+ margin-right: 10%;
+ border-left: 5px solid #f0f0f0;
+ color: #888;
+}
+
+div.quoteblock > div.attribution {
+ padding-top: 0.5em;
+ text-align: right;
+}
+
+div.verseblock > pre.content {
+ font-family: inherit;
+ font-size: inherit;
+}
+div.verseblock > div.attribution {
+ padding-top: 0.75em;
+ text-align: left;
+}
+/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
+div.verseblock + div.attribution {
+ text-align: left;
+}
+
+div.admonitionblock .icon {
+ vertical-align: top;
+ font-size: 1.1em;
+ font-weight: bold;
+ text-decoration: underline;
+ color: #527bbd;
+ padding-right: 0.5em;
+}
+div.admonitionblock td.content {
+ padding-left: 0.5em;
+ border-left: 3px solid #dddddd;
+}
+
+div.exampleblock > div.content {
+ border-left: 3px solid #dddddd;
+ padding-left: 0.5em;
+}
+
+div.imageblock div.content { padding-left: 0; }
+span.image img { border-style: none; vertical-align: text-bottom; }
+a.image:visited { color: white; }
+
+dl {
+ margin-top: 0.8em;
+ margin-bottom: 0.8em;
+}
+dt {
+ margin-top: 0.5em;
+ margin-bottom: 0;
+ font-style: normal;
+ color: navy;
+}
+dd > *:first-child {
+ margin-top: 0.1em;
+}
+
+ul, ol {
+ list-style-position: outside;
+}
+ol.arabic {
+ list-style-type: decimal;
+}
+ol.loweralpha {
+ list-style-type: lower-alpha;
+}
+ol.upperalpha {
+ list-style-type: upper-alpha;
+}
+ol.lowerroman {
+ list-style-type: lower-roman;
+}
+ol.upperroman {
+ list-style-type: upper-roman;
+}
+
+div.compact ul, div.compact ol,
+div.compact p, div.compact p,
+div.compact div, div.compact div {
+ margin-top: 0.1em;
+ margin-bottom: 0.1em;
+}
+
+tfoot {
+ font-weight: bold;
+}
+td > div.verse {
+ white-space: pre;
+}
+
+div.hdlist {
+ margin-top: 0.8em;
+ margin-bottom: 0.8em;
+}
+div.hdlist tr {
+ padding-bottom: 15px;
+}
+dt.hdlist1.strong, td.hdlist1.strong {
+ font-weight: bold;
+}
+td.hdlist1 {
+ vertical-align: top;
+ font-style: normal;
+ padding-right: 0.8em;
+ color: navy;
+}
+td.hdlist2 {
+ vertical-align: top;
+}
+div.hdlist.compact tr {
+ margin: 0;
+ padding-bottom: 0;
+}
+
+.comment {
+ background: yellow;
+}
+
+.footnote, .footnoteref {
+ font-size: 0.8em;
+}
+
+span.footnote, span.footnoteref {
+ vertical-align: super;
+}
+
+#footnotes {
+ margin: 20px 0 20px 0;
+ padding: 7px 0 0 0;
+}
+
+#footnotes div.footnote {
+ margin: 0 0 5px 0;
+}
+
+#footnotes hr {
+ border: none;
+ border-top: 1px solid silver;
+ height: 1px;
+ text-align: left;
+ margin-left: 0;
+ width: 20%;
+ min-width: 100px;
+}
+
+div.colist td {
+ padding-right: 0.5em;
+ padding-bottom: 0.3em;
+ vertical-align: top;
+}
+div.colist td img {
+ margin-top: 0.3em;
+}
+
+ at media print {
+ #footer-badges { display: none; }
+}
+
+#toc {
+ margin-bottom: 2.5em;
+}
+
+#toctitle {
+ color: #527bbd;
+ font-size: 1.1em;
+ font-weight: bold;
+ margin-top: 1.0em;
+ margin-bottom: 0.1em;
+}
+
+div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
+ margin-top: 0;
+ margin-bottom: 0;
+}
+div.toclevel2 {
+ margin-left: 2em;
+ font-size: 0.9em;
+}
+div.toclevel3 {
+ margin-left: 4em;
+ font-size: 0.9em;
+}
+div.toclevel4 {
+ margin-left: 6em;
+ font-size: 0.9em;
+}
+
+span.aqua { color: aqua; }
+span.black { color: black; }
+span.blue { color: blue; }
+span.fuchsia { color: fuchsia; }
+span.gray { color: gray; }
+span.green { color: green; }
+span.lime { color: lime; }
+span.maroon { color: maroon; }
+span.navy { color: navy; }
+span.olive { color: olive; }
+span.purple { color: purple; }
+span.red { color: red; }
+span.silver { color: silver; }
+span.teal { color: teal; }
+span.white { color: white; }
+span.yellow { color: yellow; }
+
+span.aqua-background { background: aqua; }
+span.black-background { background: black; }
+span.blue-background { background: blue; }
+span.fuchsia-background { background: fuchsia; }
+span.gray-background { background: gray; }
+span.green-background { background: green; }
+span.lime-background { background: lime; }
+span.maroon-background { background: maroon; }
+span.navy-background { background: navy; }
+span.olive-background { background: olive; }
+span.purple-background { background: purple; }
+span.red-background { background: red; }
+span.silver-background { background: silver; }
+span.teal-background { background: teal; }
+span.white-background { background: white; }
+span.yellow-background { background: yellow; }
+
+span.big { font-size: 2em; }
+span.small { font-size: 0.6em; }
+
+span.underline { text-decoration: underline; }
+span.overline { text-decoration: overline; }
+span.line-through { text-decoration: line-through; }
+
+div.unbreakable { page-break-inside: avoid; }
+
+
+/*
+ * xhtml11 specific
+ *
+ * */
+
+div.tableblock {
+ margin-top: 1.0em;
+ margin-bottom: 1.5em;
+}
+div.tableblock > table {
+ border: 3px solid #527bbd;
+}
+thead, p.table.header {
+ font-weight: bold;
+ color: #527bbd;
+}
+p.table {
+ margin-top: 0;
+}
+/* Because the table frame attribute is overriden by CSS in most browsers. */
+div.tableblock > table[frame="void"] {
+ border-style: none;
+}
+div.tableblock > table[frame="hsides"] {
+ border-left-style: none;
+ border-right-style: none;
+}
+div.tableblock > table[frame="vsides"] {
+ border-top-style: none;
+ border-bottom-style: none;
+}
+
+
+/*
+ * html5 specific
+ *
+ * */
+
+table.tableblock {
+ margin-top: 1.0em;
+ margin-bottom: 1.5em;
+}
+thead, p.tableblock.header {
+ font-weight: bold;
+ color: #527bbd;
+}
+p.tableblock {
+ margin-top: 0;
+}
+table.tableblock {
+ border-width: 3px;
+ border-spacing: 0px;
+ border-style: solid;
+ border-color: #527bbd;
+ border-collapse: collapse;
+}
+th.tableblock, td.tableblock {
+ border-width: 1px;
+ padding: 4px;
+ border-style: solid;
+ border-color: #527bbd;
+}
+
+table.tableblock.frame-topbot {
+ border-left-style: hidden;
+ border-right-style: hidden;
+}
+table.tableblock.frame-sides {
+ border-top-style: hidden;
+ border-bottom-style: hidden;
+}
+table.tableblock.frame-none {
+ border-style: hidden;
+}
+
+th.tableblock.halign-left, td.tableblock.halign-left {
+ text-align: left;
+}
+th.tableblock.halign-center, td.tableblock.halign-center {
+ text-align: center;
+}
+th.tableblock.halign-right, td.tableblock.halign-right {
+ text-align: right;
+}
+
+th.tableblock.valign-top, td.tableblock.valign-top {
+ vertical-align: top;
+}
+th.tableblock.valign-middle, td.tableblock.valign-middle {
+ vertical-align: middle;
+}
+th.tableblock.valign-bottom, td.tableblock.valign-bottom {
+ vertical-align: bottom;
+}
+
+
+/*
+ * manpage specific
+ *
+ * */
+
+body.manpage h1 {
+ padding-top: 0.5em;
+ padding-bottom: 0.5em;
+ border-top: 2px solid silver;
+ border-bottom: 2px solid silver;
+}
+body.manpage h2 {
+ border-style: none;
+}
+body.manpage div.sectionbody {
+ margin-left: 3em;
+}
+
+ at media print {
+ body.manpage div#toc { display: none; }
+}
+
+
+</style>
+<script type="text/javascript">
+/*<+'])');
+ // Function that scans the DOM tree for header elements (the DOM2
+ // nodeIterator API would be a better technique but not supported by all
+ // browsers).
+ var iterate = function (el) {
+ for (var i = el.firstChild; i != null; i = i.nextSibling) {
+ if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
+ var mo = re.exec(i.tagName);
+ if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
+ result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
+ }
+ iterate(i);
+ }
+ }
+ }
+ iterate(el);
+ return result;
+ }
+
+ var toc = document.getElementById("toc");
+ if (!toc) {
+ return;
+ }
+
+ // Delete existing TOC entries in case we're reloading the TOC.
+ var tocEntriesToRemove = [];
+ var i;
+ for (i = 0; i < toc.childNodes.length; i++) {
+ var entry = toc.childNodes[i];
+ if (entry.nodeName.toLowerCase() == 'div'
+ && entry.getAttribute("class")
+ && entry.getAttribute("class").match(/^toclevel/))
+ tocEntriesToRemove.push(entry);
+ }
+ for (i = 0; i < tocEntriesToRemove.length; i++) {
+ toc.removeChild(tocEntriesToRemove[i]);
+ }
+
+ // Rebuild TOC entries.
+ var entries = tocEntries(document.getElementById("content"), toclevels);
+ for (var i = 0; i < entries.length; ++i) {
+ var entry = entries[i];
+ if (entry.element.id == "")
+ entry.element.id = "_toc_" + i;
+ var a = document.createElement("a");
+ a.href = "#" + entry.element.id;
+ a.appendChild(document.createTextNode(entry.text));
+ var div = document.createElement("div");
+ div.appendChild(a);
+ div.className = "toclevel" + entry.toclevel;
+ toc.appendChild(div);
+ }
+ if (entries.length == 0)
+ toc.parentNode.removeChild(toc);
+},
+
+
+/////////////////////////////////////////////////////////////////////
+// Footnotes generator
+/////////////////////////////////////////////////////////////////////
+
+/* Based on footnote generation code from:
+ * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
+ */
+
+footnotes: function () {
+ // Delete existing footnote entries in case we're reloading the footnodes.
+ var i;
+ var noteholder = document.getElementById("footnotes");
+ if (!noteholder) {
+ return;
+ }
+ var entriesToRemove = [];
+ for (i = 0; i < noteholder.childNodes.length; i++) {
+ var entry = noteholder.childNodes[i];
+ if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") == "footnote")
+ entriesToRemove.push(entry);
+ }
+ for (i = 0; i < entriesToRemove.length; i++) {
+ noteholder.removeChild(entriesToRemove[i]);
+ }
+
+ // Rebuild footnote entries.
+ var cont = document.getElementById("content");
+ var spans = cont.getElementsByTagName("span");
+ var refs = {};
+ var n = 0;
+ for (i=0; i<spans.length; i++) {
+ if (spans[i].className == "footnote") {
+ n++;
+ var note = spans[i].getAttribute("data-note");
+ if (!note) {
+ // Use [\s\S] in place of . so multi-line matches work.
+ // Because JavaScript has no s (dotall) regex flag.
+ note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
+ spans[i].innerHTML =
+ "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
+ "' title='View footnote' class='footnote'>" + n + "</a>]";
+ spans[i].setAttribute("data-note", note);
+ }
+ noteholder.innerHTML +=
+ "<div class='footnote' id='_footnote_" + n + "'>" +
+ "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
+ n + "</a>. " + note + "</div>";
+ var id =spans[i].getAttribute("id");
+ if (id != null) refs["#"+id] = n;
+ }
+ }
+ if (n == 0)
+ noteholder.parentNode.removeChild(noteholder);
+ else {
+ // Process footnoterefs.
+ for (i=0; i<spans.length; i++) {
+ if (spans[i].className == "footnoteref") {
+ var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
+ href = href.match(/#.*/)[0]; // Because IE return full URL.
+ n = refs[href];
+ spans[i].innerHTML =
+ "[<a href='#_footnote_" + n +
+ "' title='View footnote' class='footnote'>" + n + "</a>]";
+ }
+ }
+ }
+},
+
+install: function(toclevels) {
+ var timerId;
+
+ function reinstall() {
+ asciidoc.footnotes();
+ if (toclevels) {
+ asciidoc.toc(toclevels);
+ }
+ }
+
+ function reinstallAndRemoveTimer() {
+ clearInterval(timerId);
+ reinstall();
+ }
+
+ timerId = setInterval(reinstall, 500);
+ if (document.addEventListener)
+ document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);
+ else
+ window.onload = reinstallAndRemoveTimer;
+}
+
+}
+asciidoc.install(2);
+/*]]>*/
+</script>
+</head>
+<body class="article">
+<div id="header">
+<h1>Turbine Sites Guide</h1>
+<span id="author">Justin M. Wozniak</span><br />
+<span id="email"><code><<a href="mailto:wozniak at mcs.anl.gov">wozniak at mcs.anl.gov</a>></code></span><br />
+<span id="revnumber">version 0.5.0,</span>
+<span id="revdate">April 2014</span>
+<div id="toc">
+ <div id="toctitle">Table of Contents</div>
+ <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
+</div>
+</div>
+<div id="content">
+<div class="sect1">
+<h2 id="_how_to_use_this_guide">How to use this guide</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>This manual provides a reference on how to run Swift/T Turbine
+programs on a variety of systems. It also contains an index of sites
+maintained by the Swift/T team for use by Turbine.</p></div>
+<div class="paragraph"><p>For each machine, a <strong>public installation</strong> and/or a <strong>build procedure</strong> will
+be provided. The user need only follow one set of directions.</p></div>
+<div class="paragraph" id="login_node"><p>A <strong>login node installation</strong> may be available on certain systems. This
+will run Swift/T on the login node of that system. This only acceptable for
+short debugging runs of 1 minute or less. It will affect other users
+so please be cautious when using this mode for debugging.</p></div>
+<div class="sect2">
+<h3 id="_public_installations">Public installations</h3>
+<div class="paragraph"><p>These are maintained by the Swift/T team. Because they may become out
+of date after a release, the release version and a timestamp are
+recorded below.</p></div>
+<div class="paragraph"><p>To request maintenance on a public installation, simply email
+<a href="mailto:exm-user at mcs.anl.gov">exm-user at mcs.anl.gov</a> .</p></div>
+</div>
+<div class="sect2">
+<h3 id="_build_procedures">Build procedures</h3>
+<div class="paragraph"><p>The build procedure is based on the installation process
+described in the <a href="./swift.html">Swift/T Guide</a>. You
+should follow that build procedure, and use this
+guide for information on specific configuration
+settings for your system.</p></div>
+<div class="paragraph"><p>The settings are generally implemented by modifying the
+<code>exm-settings.sh</code> configuration script. In some cases,
+where the setting is not configurable through <code>exm-settings.sh</code>,
+it may be necessary to directly modify the <code>configure</code> or <code>make</code>
+command lines by following the manual build process, or by modifying
+build scripts under the <code>build</code> subdirectory
+(e.g. <code>turbine-build.sh</code>).</p></div>
+</div>
+<div class="sect2">
+<h3 id="_version_numbers">Version numbers</h3>
+<div class="paragraph"><p>The component version numbers that correspond together to make up a
+Swift/T release may be found on the
+<a href="../downloads/downloads.html">Downloads</a> page.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_freshness">Freshness</h3>
+<div class="paragraph"><p>These instructions may become stale for various reasons. For example,
+system administrators may update directory locations, breaking these
+instructions. Thus, we mark <strong>As of:</strong> dates on the instructions for
+each system.</p></div>
+<div class="paragraph"><p>To report a problem, simply email <a href="mailto:exm-user at mcs.anl.gov">exm-user at mcs.anl.gov</a> .</p></div>
+</div>
+<div class="sect2">
+<h3 id="_for_more_information">For more information</h3>
+<div class="ulist"><ul>
+<li>
+<p>
+See the <a href="./swift.html">Swift/T Guide</a> for more information about Swift/T.
+</p>
+</li>
+<li>
+<p>
+Join the ExM (Swift/T project) <a href="http://lists.mcs.anl.gov/mailman/listinfo/exm-user">user mailing list</a>.
+</p>
+</li>
+</ul></div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_turbine_as_mpi_program">Turbine as MPI program</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Turbine is a moderately complex MPI program. It is essentially a Tcl
+library that glues together multiple C-based systems, including MPI,
+ADLB, and the Turbine dataflow library.</p></div>
+<div class="paragraph"><p>Running Turbine on a MPI-enabled system works as follows:</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+Compilation and installation: This builds the Turbine libraries and
+ links with the system-specific MPI library. STC must also be
+ informed of the Turbine installation to access correct built-in
+ function information
+</p>
+</li>
+<li>
+<p>
+Run-time configuration: The startup job submission script locates
+ the Turbine installation and reads configuration information
+</p>
+</li>
+<li>
+<p>
+Process launch: The Tcl shell, <code>tclsh</code>, is launched in parallel and
+ configuration information is passed to it so it can find the
+ libraries. The Tcl program script is the STC-generated user program
+ file. The MPI library enables communication among the <code>tclsh</code>
+ processes.
+</p>
+</li>
+</ul></div>
+<div class="paragraph"><p>Each of the systems below follows this basic outline.</p></div>
+<div class="paragraph"><p>On simpler systems, use the <code>turbine</code> program. This is a small shell
+script wrapper that configures Turbine and essentially runs:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>mpiexec tclsh program.tcl</code></pre>
+</div></div>
+<div class="paragraph"><p>On more complex, scheduled systems, users do not invoke <code>mpiexec</code>
+directly. Thus, sample scripts are provided below.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="scheduled_systems">Submitting Turbine jobs on scheduled systems</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>On scheduled systems (PBS, SLURM, Cobalt, etc.), Turbine is launched
+with a customized <em>run script</em> (<code>turbine-<name>-run</code>) that launches Turbine
+on that system. This produces a batch script if necessary and submits
+it with the job submission program (e.g., <code>qsub</code>).</p></div>
+<div class="sect2">
+<h3 id="_turbine_run_scripts">Turbine run scripts</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+PBS
+</dt>
+<dd>
+<p>
+<code>turbine-pbs-run.zsh</code>
+</p>
+</dd>
+<dt class="hdlist1">
+Cobalt
+</dt>
+<dd>
+<p>
+<code>turbine-cobalt-run.zsh</code>
+</p>
+</dd>
+<dt class="hdlist1">
+Cray/APRUN
+</dt>
+<dd>
+<p>
+<code>turbine-aprun-run.zsh</code> (PBS with Cray’s <code>aprun</code>)
+</p>
+</dd>
+<dt class="hdlist1">
+SLURM
+</dt>
+<dd>
+<p>
+<code>turbine-slurm-run.zsh</code>
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Each script accepts input via environment variables and command-line options.</p></div>
+<div class="paragraph"><p>A typical invocation is:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>stc program.swift
+turbine-pbs-run.zsh -n 96 -s settings.sh program.tcl</code></pre>
+</div></div>
+<div class="paragraph"><p>where <code>program.tcl</code> is the output of STC and <code>settings.sh</code> contains:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>export QUEUE=bigqueue
+export PPN=8</code></pre>
+</div></div>
+<div class="paragraph"><p>which would run <code>program.tcl</code> in 96 MPI processes on 12 nodes (8
+processes per node), submitted by PBS to queue <code>bigqueue</code>.</p></div>
+</div>
+<div class="sect2">
+<h3 id="variables">Turbine scheduler variables</h3>
+<div class="paragraph"><p>For scheduled systems, Turbine accepts a common set of environment
+variables.</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<code>PROCS</code>
+</dt>
+<dd>
+<p>
+Number of processes to use
+</p>
+</dd>
+<dt class="hdlist1">
+<code>PPN</code>
+</dt>
+<dd>
+<p>
+Number of processes per node
+</p>
+</dd>
+<dt class="hdlist1">
+<code>PROJECT</code>
+</dt>
+<dd>
+<p>
+The project name to use with the system scheduler
+</p>
+</dd>
+<dt class="hdlist1">
+<code>QUEUE</code>
+</dt>
+<dd>
+<p>
+Name of queue in which to run
+</p>
+</dd>
+<dt class="hdlist1">
+<code>TURBINE_OUTPUT</code>
+</dt>
+<dd>
+<p>
+Directory in which to place Turbine output (if
+unset, a default value is automatically created)
+</p>
+</dd>
+<dt class="hdlist1">
+<code>TURBINE_OUTPUT_ROOT</code>
+</dt>
+<dd>
+<p>
+Directory under which Turbine will
+automatically create <code>TURBINE_OUTPUT</code> if necessary
+</p>
+</dd>
+</dl></div>
+</div>
+<div class="sect2">
+<h3 id="options">Turbine scheduler script options</h3>
+<div class="paragraph"><p>For scheduled systems, Turbine accepts a common set of command line options.</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<code>-d <directory></code>
+</dt>
+<dd>
+<p>
+Set the Turbine output directory. (Overrides
+<code>TURBINE_OUTPUT</code>).
+</p>
+</dd>
+<dt class="hdlist1">
+<code>-e <key>=<value></code>
+</dt>
+<dd>
+<p>
+Set an environment variable in the job
+environment. This may be used multiple times
+</p>
+</dd>
+<dt class="hdlist1">
+<code>-i <script></code>
+</dt>
+<dd>
+<p>
+Set a script to run before launching Turbine. This
+script will have <code>TURBINE_OUTPUT</code> in the environment, so you may
+perform additional configuration just before job launch.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>-n <procs></code>
+</dt>
+<dd>
+<p>
+Number of processes. (Overrides <code>PROCS</code>.)
+</p>
+</dd>
+<dt class="hdlist1">
+<code>-o <directory></code>
+</dt>
+<dd>
+<p>
+Set the Turbine output directory root, in which
+default Turbine output directories are automatically created based on
+the date. (Overrides <code>TURBINE_OUTPUT_ROOT</code>.)
+</p>
+</dd>
+<dt class="hdlist1">
+<code>-s <script></code>
+</dt>
+<dd>
+<p>
+Source this file for environment variables. These
+variables override any other <a href="#variables">Turbine scheduler variables</a>. You may place arbitrary shell code in this script.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>-t <time></code>
+</dt>
+<dd>
+<p>
+Set scheduler walltime. The argument format is passed
+through to the scheduler
+</p>
+</dd>
+<dt class="hdlist1">
+<code>-V</code>
+</dt>
+<dd>
+<p>
+Make script verbose. This typically just applies <code>set -x</code>,
+allowing you to inspect variables and arguments as passed to the
+system scheduler.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>-x</code>
+</dt>
+<dd>
+<p>
+Use <code>turbine_sh</code> launcher with compiled-in libraries instead of <code>tclsh</code>
+ (reduces number of files that must be read from file system).
+</p>
+</dd>
+<dt class="hdlist1">
+<code>-X</code>
+</dt>
+<dd>
+<p>
+Run standalone Turbine executable
+ (created by <a href="swift.html#mkstatic">mkstatic.tcl</a>) instead of
+ <code>program.tcl</code>.
+</p>
+</dd>
+</dl></div>
+</div>
+<div class="sect2">
+<h3 id="_turbine_output_directory">Turbine output directory</h3>
+<div class="paragraph"><p>The working directory (<code>PWD</code>) for the job is called <code>TURBINE_OUTPUT</code>.</p></div>
+<div class="paragraph"><p>If the user does not set this variable, Turbine will select one based on the date
+and report it. The automatically selected directory will be placed
+under <code>TURBINE_OUTPUT_ROOT</code>, which defaults to <code>$HOME/turbine-output</code>.
+The user program will be copied to <code>TURBINE_OUTPUT</code> before submission.
+Standard output and error goes to <code>TURBINE_OUTPUT/output.txt</code>.</p></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Tip</div>
+</td>
+<td class="content">When running on a big HPC machine, it may be difficult to get STC
+(a Java-based program) running. STC output (<code>program.tcl</code>) is
+platform-independent. You may run STC to develop and debug your
+script on your local workstation, then simply copy <code>program.tcl</code> to
+the big machine for execution. Just make sure that the STC and
+Turbine versions are compatible (the same release number).</td>
+</tr></table>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_x86_clusters">x86 clusters</h2>
+<div class="sectionbody">
+<div class="sect2">
+<h3 id="generic_clusters">Generic clusters</h3>
+<div class="paragraph"><p>This is the simplest method to run Turbine.</p></div>
+<div class="sect3">
+<h4 id="_build_procedure">Build procedure</h4>
+<div class="paragraph"><p>The <code>exm-setup.zsh</code> script should work without any special configuration.</p></div>
+<div class="paragraph"><p>To run, simply build a MPI hosts file and pass that to Turbine, which
+will pass it to <code>mpiexec</code>.</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>turbine -l -n 3 -f hosts.txt program.tcl</code></pre>
+</div></div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_mcs_compute_servers">MCS compute servers</h3>
+<div class="paragraph"><p>Compute servers at MCS Division, ANL.
+Operates as a generic cluster (see above).</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>echo crush.mcs.anl.gov > hosts.txt
+echo crank.mcs.anl.gov >> hosts.txt
+turbine -l -n 3 -f hosts.txt program.tcl</code></pre>
+</div></div>
+<div class="sect3">
+<h4 id="_public_installation">Public installation</h4>
+<div class="paragraph"><p><strong>As of:</strong> trunk, 8/13/2013</p></div>
+<div class="paragraph"><p>MCS users are welcome to use this installation.</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+STC: <code>~wozniak/Public/stc/bin/stc</code>
+</p>
+</li>
+<li>
+<p>
+Turbine: <code>~wozniak/Public/turbine/bin/turbine</code>
+</p>
+</li>
+</ul></div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_breadboard">Breadboard</h3>
+<div class="paragraph"><p>Cf. <a href="http://wiki.mcs.anl.gov/radix/index.php/Breadboard">Breadboard Wiki</a></p></div>
+<div class="paragraph"><p>Breadboard is a cloud-ish cluster for software development in
+MCS. This is a fragile resource used by many MCS developers. Do not
+overuse.</p></div>
+<div class="paragraph"><p>Operates as a generic cluster (see above). No scheduler. Once you
+have the nodes, you can use them until you release them or time
+expires (12 hours by default).</p></div>
+<div class="olist arabic"><ol class="arabic">
+<li>
+<p>
+Allocate nodes with <code>heckle</code>. See Breadboard wiki
+</p>
+</li>
+<li>
+<p>
+Wait for nodes to boot
+</p>
+</li>
+<li>
+<p>
+Use <code>heckle allocate -w</code> for better interaction
+</p>
+</li>
+<li>
+<p>
+Create MPICH hosts file:
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code>heckle stat | grep $USER | cut -f 1 -d ' ' > hosts.txt</code></pre>
+</div></div>
+</li>
+<li>
+<p>
+Run:
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code>export TURBINE_LAUNCH_OPTS='-f hosts.txt'
+turbine -l -n 4 program.tcl</code></pre>
+</div></div>
+</li>
+<li>
+<p>
+Run as many jobs as desired on the allocation
+</p>
+</li>
+<li>
+<p>
+When done, release the allocation:
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code>for h in $( cat hosts.txt )
+do
+ heckle free $h
+done</code></pre>
+</div></div>
+</li>
+</ol></div>
+</div>
+<div class="sect2">
+<h3 id="_midway">Midway</h3>
+<div class="paragraph"><p>Midway is a mid-sized SLURM cluster at the University of Chicago</p></div>
+<div class="sect3">
+<h4 id="_public_installation_2">Public installation</h4>
+<div class="paragraph"><p><strong>As of:</strong> 0.2.1 - 02/11/2013</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+STC: <code>~wozniak/Public/stc-0.0.3/bin/stc</code>
+</p>
+</li>
+</ul></div>
+<div class="paragraph"><p>To run:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>srun ~wozniak/Public/turbine-0.1.1/scripts/submit/slurm/turbine-slurm.sh -n 3 ~/program.tcl</code></pre>
+</div></div>
+</div>
+<div class="sect3">
+<h4 id="_build_procedure_2">Build procedure</h4>
+<div class="ulist"><ul>
+<li>
+<p>
+Midway uses OpenMPI. We have tested with <code>/software/openmpi-1.6-el6-x86_64</code>
+</p>
+</li>
+<li>
+<p>
+Put <code>mpicc</code> in your <code>PATH</code>
+</p>
+</li>
+<li>
+<p>
+Use these settings in <code>exm-settings.sh</code>:
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code>export LDFLAGS="-Wl,-rpath -Wl,/software/openmpi-1.6-el6-x86_64/lib"
+MPI_VERSION=2
+MPI_LIB_NAME=mpi</code></pre>
+</div></div>
+</li>
+<li>
+<p>
+Or if doing a manual build with <code>configure</code> and make:
+</p>
+<div class="ulist"><ul>
+<li>
+<p>
+Configure ADLB with:
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code>LDFLAGS="-Wl,-rpath -Wl,/software/openmpi-1.6-el6-x86_64/lib" --enable-mpi-2</code></pre>
+</div></div>
+</li>
+<li>
+<p>
+Configure Turbine with:
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code> --with-mpi-lib-name=mpi</code></pre>
+</div></div>
+</li>
+</ul></div>
+</li>
+</ul></div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_eureka">Eureka</h3>
+<div class="paragraph"><p>Eureka is a 100-node x86 cluster at the Argonne Leadership Computing
+Facility (ALCF). It uses the Cobalt scheduler.</p></div>
+<div class="sect3">
+<h4 id="_build_procedure_3">Build procedure</h4>
+<div class="ulist"><ul>
+<li>
+<p>
+Configure Tcl and c-utils with gcc
+</p>
+</li>
+<li>
+<p>
+Configure ADLB with mpicc
+</p>
+</li>
+</ul></div>
+<div class="paragraph"><p>To run:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>export MODE=cluster
+submit/cobalt/turbine-cobalt-run.zsh -n 3 ~/program.tcl</code></pre>
+</div></div>
+<div class="paragraph"><p>The normal Turbine environment variables are honored, plus the
+<a href="#variables">Turbine scheduler variables</a>.</p></div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_tukey">Tukey</h3>
+<div class="paragraph"><p><a href="https://www.alcf.anl.gov/user-guides/tukey">Tukey</a> is a 96-node x86
+cluster at the Argonne Leadership Computing Facility (ALCF). It uses
+the Cobalt scheduler.</p></div>
+<div class="paragraph"><p><strong>As of:</strong> Trunk, 4/9/2014</p></div>
+<div class="sect3">
+<h4 id="_public_installation_3">Public installation</h4>
+<div class="paragraph"><p>Add to <code>PATH</code>:
+* STC: <code><sub>wozniak/Public/sfw/x86/stc/bin</code>
+* Turbine submit script: <code></sub>wozniak/Public/sfw/x86/turbine/scripts/submit/cobalt</code></p></div>
+<div class="paragraph"><p>To run:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>export MODE=cluster
+export QUEUE=pubnet
+export PROJECT=...
+turbine-cobalt-run.zsh -n 3 program.tcl</code></pre>
+</div></div>
+</div>
+<div class="sect3">
+<h4 id="_build_procedure_4">Build procedure</h4>
+<div class="ulist"><ul>
+<li>
+<p>
+Check that the system-provided MVAPICH <code>mpicc</code> is in your <code>PATH</code>
+</p>
+</li>
+<li>
+<p>
+Configure c-utils with <code>gcc</code>
+</p>
+</li>
+<li>
+<p>
+Configure ADLB with <code>CC=mpicc --enable-mpi-2</code>
+</p>
+</li>
+<li>
+<p>
+Configure Turbine with <code>--with-launcher=/soft/libraries/mpi/mvapich2/gcc/bin/mpiexec</code>
+</p>
+</li>
+</ul></div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_blues">Blues</h3>
+<div class="paragraph"><p><a href="http://www.lcrc.anl.gov/about/blues">Blues</a> is a 310-node x86
+cluster at ANL. It uses PBS.</p></div>
+<div class="sect3">
+<h4 id="_public_installation_4">Public installation</h4>
+<div class="ulist"><ul>
+<li>
+<p>
+STC: <code>~wozniak/Public/stc/bin/stc</code>
+</p>
+</li>
+</ul></div>
+<div class="paragraph"><p>To run:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>export QUEUE=batch
+~wozniak/Public/turbine/scripts/submit/pbs/turbine-pbs-run.zsh -n 3 program.tcl</code></pre>
+</div></div>
+<div class="paragraph"><p>See the <a href="#variables">Turbine scheduler variables</a> and
+<a href="#options">Turbine run script options</a> for additional settings.</p></div>
+</div>
+<div class="sect3">
+<h4 id="_build_procedure_5">Build procedure</h4>
+<div class="paragraph"><p>Apparently need to append to use GCC 4.7.2 and set <code>LD_LIBRARY_PATH</code>:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>$ which gcc
+/software/gcc-4.7.2/bin/gcc
+$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/software/gcc-4.7.2/lib64</code></pre>
+</div></div>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_blue_gene">Blue Gene</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The Blue Gene systems at ANL are <a href="#scheduled_systems">scheduled systems</a> that use Cobalt.</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+The job ID is placed in <code>TURBINE_OUTPUT/jobid.txt</code>
+</p>
+</li>
+<li>
+<p>
+Job metadata is placed in <code>TURBINE_OUTPUT/turbine-cobalt.log</code>
+</p>
+</li>
+<li>
+<p>
+The Cobalt log is placed in <code>TURBINE_OUTPUT</code>
+</p>
+</li>
+</ul></div>
+<div class="sect2">
+<h3 id="_blue_gene_p">Blue Gene/P</h3>
+<div class="sect3">
+<h4 id="_surveyor_intrepid_challenger">Surveyor/Intrepid/Challenger</h4>
+<div class="paragraph"><p>These machines were at the Argonne Leadership Computing Facility
+(ALCF). Other existing Blue Gene/P systems may be configured in a
+similar way.</p></div>
+<div class="sect4">
+<h5 id="_public_installation_5">Public installation</h5>
+<div class="ulist"><ul>
+<li>
+<p>
+Based on trunk
+</p>
+</li>
+<li>
+<p>
+STC: <code>~wozniak/Public/stc-trunk/bin/stc</code>
+</p>
+</li>
+</ul></div>
+<div class="paragraph"><p>To run:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>~wozniak/Public/turbine/scripts/submit/cobalt/turbine-cobalt-run.zsh -n 3 ~/program.tcl</code></pre>
+</div></div>
+</div>
+<div class="sect4">
+<h5 id="_build_procedure_6">Build procedure</h5>
+<div class="paragraph"><p>To run on the <a href="#login_node">login node</a>:</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+Install MPICH for the login nodes
+</p>
+</li>
+<li>
+<p>
+Configure Tcl and c-utils with gcc
+</p>
+</li>
+<li>
+<p>
+Configure ADLB with your MPICH
+</p>
+</li>
+<li>
+<p>
+Configure Turbine with
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code>--enable-bgp LDFLAGS=-shared-libgcc</code></pre>
+</div></div>
+<div class="paragraph"><p>This makes adjustments for some Blue Gene quirks.</p></div>
+</li>
+<li>
+<p>
+Then, simply use the <code>bin/turbine</code> program to run. Be cautious in
+ your use of the login nodes to avoid affecting other users.
+</p>
+</li>
+</ul></div>
+<div class="paragraph"><p><em>To run on the compute nodes under IBM CNK:</em></p></div>
+<div class="paragraph"><p>In this mode, you cannot use <code>app</code> functions to launch external
+programs because CNK does not support this. See ZeptoOS below.</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+Configure Tcl with mpixlc
+</p>
+</li>
+<li>
+<p>
+Configure c-utils with gcc
+</p>
+</li>
+<li>
+<p>
+Configure ADLB with:
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code>--enable-xlc
+CC=/bgsys/drivers/ppcfloor/comm/bin/mpixlc</code></pre>
+</div></div>
+</li>
+<li>
+<p>
+Configure Turbine with:
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code>CC=/soft/apps/gcc-4.3.2/gnu-linux/bin/powerpc-bgp-linux-gcc
+--enable-custom
+--with-mpi-include=/bgsys/drivers/V1R4M2_200_2010-100508P/ppc/comm/default/include</code></pre>
+</div></div>
+</li>
+</ul></div>
+<div class="paragraph"><p>To run, use <code>scripts/submit/bgp/turbine-cobalt.zsh</code>
+See the script header for usage.</p></div>
+<div class="paragraph"><p><em>To run on the compute nodes under ZeptoOS:</em></p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+Configure Tcl with zmpicc
+</p>
+</li>
+<li>
+<p>
+Configure c-utils with gcc
+</p>
+</li>
+<li>
+<p>
+Configure ADLB with
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code>CC=zmpicc --enable-mpi-2</code></pre>
+</div></div>
+</li>
+<li>
+<p>
+Configure Turbine with
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code>CC=/soft/apps/gcc-4.3.2/gnu-linux/bin/powerpc-bgp-linux-gcc
+--enable-custom
+--with-mpi-include=/bgsys/drivers/V1R4M2_200_2010-100508P/ppc/comm/default/include</code></pre>
+</div></div>
+</li>
+</ul></div>
+<div class="paragraph"><p>To run, use <code>scripts/submit/bgp/turbine-cobalt.zsh</code>
+See the script header for usage.</p></div>
+</div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_blue_gene_q">Blue Gene/Q</h3>
+<div class="sect3">
+<h4 id="_vesta">Vesta</h4>
+<div class="sect4">
+<h5 id="_public_installation_6">Public installation</h5>
+<div class="paragraph"><p><strong>As of:</strong> 0.4.0 - 07/29/2013</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+STC: <code>~wozniak/Public/stc-bgq/bin/stc</code>
+</p>
+</li>
+<li>
+<p>
+Turbine: <code>~wozniak/Public/turbine-bgq/scrips/submit/cobalt/turbine-cobalt-run.zsh</code>
+</p>
+</li>
+<li>
+<p>
+Run as:
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code>export MODE=BGQ
+export QUEUE=<queue_name>
+turbine-cobalt-run.zsh -n 3 program.tcl</code></pre>
+</div></div>
+</li>
+</ul></div>
+<div class="paragraph"><p>The normal Turbine environment variables are honored, plus the
+<a href="#variables">Turbine scheduler variables</a>.</p></div>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_mira_cetus">Mira/Cetus</h4>
+<div class="paragraph"><p><strong>As of:</strong> 0.5.0 - 4/4/2014</p></div>
+<div class="paragraph"><p>Add to <code>PATH</code>:
+* STC: <code><sub>wozniak/Public/ppc64/stc/bin</code>
+* Turbine:
+<code></sub>wozniak/Public/ppc64/turbine/scripts/submit/cobalt</code></p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+Run as:
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code>export MODE=BGQ
+export QUEUE=...
+export PROJECT=...
+turbine-cobalt-run.zsh -n 3 program.tcl</code></pre>
+</div></div>
+</li>
+</ul></div>
+<div class="sect4">
+<h5 id="_build_procedure_7">Build procedure</h5>
+<div class="paragraph"><p><strong>As of:</strong> 0.5.0 - 4/4/2014</p></div>
+<div class="paragraph"><p><strong>Tcl:</strong></p></div>
+<div class="paragraph"><p>The GCC installation does not support shared libraries. Thus, you
+must compile Tcl with <code>bgxlc</code>. You must modify the Makefile to use
+<code>bgxlc</code> arguments: <code>-qpic</code>, <code>-qmkshrobj</code>. You must link with
+<code>-qnostaticlink</code>.</p></div>
+<div class="paragraph"><p>You may get errors that say <code>wrong digit</code>. This is apparently a bgxlc
+bug when applied to Tcl’s <code>StrToD.c</code>. Compiling this file with <code>-O3</code> fixes
+the problem.</p></div>
+<div class="paragraph"><p>Put <code>/bgsys/drivers/V1R2M1/ppc64/comm/bin/gcc</code> in your <code>PATH</code>.</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+Compile c-utils with <code>CC=/usr/bin/gcc</code>
+</p>
+</li>
+<li>
+<p>
+Configure ADLB with <code>CC=mpixlc --enable-mpi-2 --enable-xlc</code>
+</p>
+</li>
+<li>
+<p>
+Configure Turbine with <code>CC=/usr/bin/gcc --disable-static --with-tcl=/home/wozniak/Public/sfw/ppc64/tcl-8.5.12 --with-mpi=/bgsys/drivers/V1R2M1/ppc64/comm --with-mpi-lib-name=mpich-gcc</code>
+</p>
+</li>
+</ul></div>
+<div class="paragraph"><p><strong>External scripting:</strong></p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+Python
+</p>
+<div class="ulist"><ul>
+<li>
+<p>
+Configure Python with BGXLC
+</p>
+</li>
+</ul></div>
+</li>
+<li>
+<p>
+R
+</p>
+<div class="ulist"><ul>
+<li>
+<p>
+Configure R with GCC as usual
+</p>
+</li>
+<li>
+<p>
+Run with:
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code>turbine-cobalt-run.zsh -e R_HOME=/path/to/R/lib64/R -e LD_LIBRARY_PATH=/path/to/R/lib64/R/lib</code></pre>
+</div></div>
+</li>
+</ul></div>
+</li>
+</ul></div>
+</div>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_cray">Cray</h2>
+<div class="sectionbody">
+<div class="sect2">
+<h3 id="_blue_waters">Blue Waters</h3>
+<div class="paragraph"><p>Blue Waters is a Cray XE6/XK7 at the University of Illinois at
+Urbana-Champaign.</p></div>
+<div class="sect3">
+<h4 id="_build_procedure_8">Build procedure</h4>
+<div class="paragraph"><p><strong>As of:</strong> 11/05/2013</p></div>
+<div class="paragraph"><p>Cray systems do not use <code>mpicc</code>. We set <code>CC=gcc</code> and use compiler
+flags to configure the MPI library.</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+Use the following settings in <code>exm-settings.sh</code>
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code>export CC=cc
+
+MPI_VERSION=2
+EXM_CUSTOM_MPI=1
+
+EXM_CRAY=1
+
+# Optionally, if you want to exclusively build static executables
+EXM_BUILD_STATIC=1</code></pre>
+</div></div>
+</li>
+</ul></div>
+<div class="paragraph"><p>Or, if doing a manual build with <code>configure</code>/<code>make</code>:</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+Configure ADLB with:
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code>./configure --prefix=/path/to/lb --with-c-utils=/path/to/c-utils
+CC=gcc
+CFLAGS=-I/opt/cray/mpt/default/gni/mpich2-gnu/47/include
+LDFLAGS="-L/opt/cray/mpt/default/gni/mpich2-gnu/47/lib -lmpich"
+--enable-mpi-2</code></pre>
+</div></div>
+</li>
+<li>
+<p>
+In the Turbine configure step, replace the <code>--with-mpi</code> option with:
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code>--enable-custom-mpi --with-mpi=/opt/cray/mpt/default/gni/mpich2-gnu/47</code></pre>
+</div></div>
+</li>
+</ul></div>
+</div>
+<div class="sect3">
+<h4 id="_submitting_jobs">Submitting jobs</h4>
+<div class="paragraph"><p>Submitting jobs on Blue Waters is largely the same with with other Cray
+systems. One difference is that the size of the job is specified using a
+different notation.</p></div>
+<div class="paragraph"><p>Blue Waters requires the submit script to specify job size using
+different directives to other Cray systems. It does <strong>not</strong> support the
+<em>mpp</em> directives: trying to use an <em>mpp</em> directive may cause your job
+to be rejected or stuck in the queue. The correct directive is:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>#PBS -l nodes=1:ppn=32</code></pre>
+</div></div>
+<div class="paragraph"><p>The <code>turbine-aprun-run.zsh</code> script supports Blue Waters. You can invoke
+it as follows (for a single node/32 processes per node):</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>QUEUE=normal BLUE_WATERS=true PPN=32 turbine-aprun-run.zsh -n 32 helloworld.tcl</code></pre>
+</div></div>
+</div>
+<div class="sect3">
+<h4 id="_installing_from_source">Installing from source</h4>
+<div class="sect4">
+<h5 id="_prerequisites">Prerequisites</h5>
+<div class="ulist"><ul>
+<li>
+<p>
+Tcl 8.5 is installed in: <code>/usr/bin/tclsh</code>
+</p>
+</li>
+<li>
+<p>
+Swig 1.3.36 is installed in: <code>/usr/bin/swig</code>
+</p>
+</li>
+<li>
+<p>
+The following steps ensure that the right compiler modules are loaded.
+</p>
+</li>
+<li>
+<p>
+Switch your programming environment to use <code>gcc</code>.
+</p>
+</li>
+</ul></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>module unload PrgEnv-cray
+module load PrgEnv-gnu</code></pre>
+</div></div>
+<div class="ulist"><ul>
+<li>
+<p>
+Load module with latest Oracle Java JDK 7+
+</p>
+</li>
+</ul></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>module load java</code></pre>
+</div></div>
+<div class="ulist"><ul>
+<li>
+<p>
+Download and install the Apache Ant build tool (required to
+ build STC)
+</p>
+</li>
+</ul></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>wget http://www.apache.org/dist/ant/binaries/apache-ant-1.9.2-bin.tar.bz2
+# Check archive is valid
+ant_xsum=$(shasum apache-ant-1.9.2-bin.tar.bz2 | awk '{ print $1 }')
+if [ ! "$ant_xsum" = "50cfaaeecee4f88a3ff9de5068fc98e4e9268daf" ]
+then
+ echo "Bad ant download checksum"
+fi
+
+# Extract ant install ant somewhere permanent
+tar xvjf apache-ant-1.9.2-bin.tar.bz2
+mkdir -p ~/soft
+mv apache-ant-1.9.2/ ~/soft/
+
+# Add ant to path (put this in .bashrc)
+export PATH="$PATH:$HOME/soft/apache-ant-1.9.2/bin"
+
+# Check ant version
+ant -version</code></pre>
+</div></div>
+</div>
+<div class="sect4">
+<h5 id="_installation">Installation</h5>
+<div class="ulist"><ul>
+<li>
+<p>
+Need to install to a lustre fs:
+</p>
+</li>
+<li>
+<p>
+<code>/scratch</code> (not backed up, best performance)
+</p>
+</li>
+<li>
+<p>
+<code>/u</code> home directory (backed up, good performance)
+</p>
+</li>
+<li>
+<p>
+<code>/projects</code> (backed up, good performance)
+</p>
+</li>
+<li>
+<p>
+I used a prepackaged distro built using <code>distro/construct.zsh -t</code> to build
+ from trunk. The following instructions are to install from this distro to
+ trunk on Blue Waters.
+</p>
+</li>
+<li>
+<p>
+First extract the tarball
+</p>
+</li>
+</ul></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>tar xvzf exm-trunk.tar.gz
+cd exm-trunk</code></pre>
+</div></div>
+<div class="ulist"><ul>
+<li>
+<p>
+exm-settings.sh needs some customization. The changed settings were:
+</p>
+</li>
+</ul></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>EXM_PREFIX=/u/sciteam/tarmstro/soft/exm-trunk-r8770
+
+# Use the latest GNU-compatible version of mpich
+EXM_MPI=/opt/cray/mpt/default/gni/mpich2-gnu/48
+# Need to use gcc (mpicc doesn't exist on Cray)
+EXM_MPICC=`which gcc`
+
+# Custom MPI
+EXM_CUSTOM_MPI=1
+
+# Since we're not using mpicc wrapper, add CC options for MPI libraries
+export CFLAGS="-I/opt/cray/mpt/default/gni/mpich2-gnu/48/include/"
+export LDFLAGS="-L/opt/cray/mpt/default/gni/mpich2-gnu/48/lib/ -lmpich"
+
+# Currently MPI 3 not supported
+MPI_VERSION=2</code></pre>
+</div></div>
+</div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_beagle">Beagle</h3>
+<div class="paragraph"><p>Beagle is a Cray XE6 at the University of Chicago</p></div>
+<div class="paragraph"><p>Remember that at run time, Beagle jobs can access only <code>/lustre</code>, not
+NFS (including home directories). Thus, you must install Turbine and
+its libraries in <code>/lustre</code>. Also, your data must be in <code>/lustre</code>.</p></div>
+<div class="sect3">
+<h4 id="_public_installation_7">Public installation</h4>
+<div class="sect4">
+<h5 id="_login_nodes">Login nodes</h5>
+<div class="paragraph"><p>This installation is for use on the <a href="#login_node">login node</a>.</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+Swift/T trunk - 6/11/2013
+</p>
+</li>
+<li>
+<p>
+Turbine: <code>~wozniak/Public/turbine-trunk-beagle-login</code>
+</p>
+</li>
+<li>
+<p>
+STC: <code>~wozniak/Public/stc-trunk-beagle-login</code>
+</p>
+</li>
+</ul></div>
+</div>
+<div class="sect4">
+<h5 id="_compute_nodes">Compute nodes</h5>
+<div class="ulist"><ul>
+<li>
+<p>
+Swift/T trunk - 6/11/2013
+</p>
+</li>
+<li>
+<p>
+Turbine: <code>/lustre/beagle/wozniak/Public/turbine</code>
+</p>
+</li>
+<li>
+<p>
+STC: <code>/lustre/beagle/wozniak/Public/stc</code>
+</p>
+</li>
+</ul></div>
+<div class="paragraph"><p>To run:</p></div>
+<div class="olist arabic"><ol class="arabic">
+<li>
+<p>
+Set environment variables. The normal Turbine environment
+variables are honored, plus the <a href="#variables">Turbine scheduler variables</a> and <a href="#options">Turbine scheduler options</a>..
+</p>
+</li>
+<li>
+<p>
+Run submit script (in <code>turbine/scripts/submit/cray</code>):
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code>turbine-aprun-run.zsh -n <numprocs> script.tcl --arg1=value1 ...</code></pre>
+</div></div>
+</li>
+</ol></div>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_build_procedure_9">Build procedure</h4>
+<div class="paragraph"><p>Cray systems do not use <code>mpicc</code>. We set <code>CC=gcc</code> and use compiler
+flags to configure the MPI library.</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+Configure ADLB with:
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code>./configure --prefix=/path/to/lb --with-c-utils=/path/to/c-utils
+CC=gcc
+CFLAGS=-I/opt/cray/mpt/default/gni/mpich2-gnu/47/include
+LDFLAGS="-L/opt/cray/mpt/default/gni/mpich2-gnu/47/lib -lmpich"
+--enable-mpi-2</code></pre>
+</div></div>
+</li>
+<li>
+<p>
+In the Turbine configure step, replace the <code>--with-mpi</code> option with:
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code>--enable-custom-mpi --with-mpi=/opt/cray/mpt/default/gni/mpich2-gnu/47</code></pre>
+</div></div>
+</li>
+</ul></div>
+</div>
+<div class="sect3">
+<h4 id="_build_procedure_with_mpe">Build procedure with MPE</h4>
+<div class="paragraph"><p>Configure MPE 1.3.0 with:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>export CFLAGS=-fPIC
+export MPI_CFLAGS="-I/opt/cray/mpt/default/gni/mpich2-gnu/47/include -fPIC"
+export LDFLAGS="-L/opt/cray/mpt/default/gni/mpich2-gnu/47/lib -lmpich"
+export F77=gfortran
+export MPI_F77=$F77
+export MPI_FFLAGS=$MPI_CFLAGS
+CC="gcc -fPIC" ./configure --prefix=... --disable-graphics</code></pre>
+</div></div>
+<div class="paragraph"><p>Configure ADLB with:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>export CFLAGS=-mpilog
+export LDFLAGS="-L/path/to/mpe/lib -lmpe -Wl,-rpath -Wl,/path/to/mpe/lib"
+./configure --prefix=... CC=mpecc --with-c-utils=/path/to/c-utils --with-mpe=/path/to/mpe --enable-mpi-2</code></pre>
+</div></div>
+<div class="paragraph"><p>Configure Turbine with:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>./configure --enable-custom-mpi --with-mpi=/opt/cray/mpt/default/gni/mpich2-gnu/47 --with-mpe=/path/to/mpe</code></pre>
+</div></div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_raven">Raven</h3>
+<div class="paragraph"><p>Raven is a Cray XE6/XK7 at Cray.</p></div>
+<div class="sect3">
+<h4 id="_build_procedure_10">Build procedure</h4>
+<div class="ulist"><ul>
+<li>
+<p>
+Configure ADLB with:
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code>./configure --prefix=/path/to/lb --with-c-utils=/path/to/c-utils
+CC=gcc
+CFLAGS=-I/opt/cray/mpt/default/gni/mpich2-gnu/46/include
+LDFLAGS="-L/opt/cray/mpt/default/gni/mpich2-gnu/46/lib -lmpich"
+--enable-mpi-2</code></pre>
+</div></div>
+</li>
+<li>
+<p>
+In the Turbine configure step, use:
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code>--with-mpi=/opt/cray/mpt/default/gni/mpich2-gnu/46</code></pre>
+</div></div>
+</li>
+<li>
+<p>
+Use this Java when compiling/running STC: <code>/opt/java/jdk1.7.0_07/bin/java</code>
+</p>
+</li>
+</ul></div>
+<div class="paragraph"><p>To run:</p></div>
+<div class="olist arabic"><ol class="arabic">
+<li>
+<p>
+Set environment variables. The normal Turbine environment
+variables are honored, plus the <a href="#variables">Turbine scheduler variables</a>.
+</p>
+</li>
+<li>
+<p>
+Run submit script (in <code>turbine/scripts/submit/cray</code>):
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code>turbine-aprun-run.zsh script.tcl --arg1=value1 ...</code></pre>
+</div></div>
+</li>
+</ol></div>
+</div>
+<div class="sect3">
+<h4 id="_advanced_usage">Advanced usage:</h4>
+<div class="paragraph"><p>Turbine uses a PBS template file called
+<code>turbine/scripts/submit/cray/turbine-aprun.sh.m4</code>. This file is
+simply filtered and submitted via <code>qsub</code>. You can edit this file to
+add additional settings as necessary.</p></div>
+</div>
+<div class="sect3">
+<h4 id="_module">Module:</h4>
+<div class="paragraph"><p>You may load Swift/T with:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>module use /home/users/p01577/Public/modules
+module load swift-t</code></pre>
+</div></div>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_cloud">Cloud</h2>
+<div class="sectionbody">
+<div class="sect2">
+<h3 id="_ec2">EC2</h3>
+<div class="sect3">
+<h4 id="_setup">Setup</h4>
+<div class="ulist"><ul>
+<li>
+<p>
+Install <a href="http://instagram-engineering.tumblr.com/post/11399488246/simplifying-ec2-ssh-connections"><code>ec2-host</code></a> on your local system
+</p>
+</li>
+<li>
+<p>
+Launch EC2 instances.
+</p>
+<div class="ulist"><ul>
+<li>
+<p>
+Enable SSH among instances.
+</p>
+</li>
+<li>
+<p>
+Firewall settings must allow all all TCP/IP traffic for MPICH to run.
+</p>
+</li>
+<li>
+<p>
+If necessary, install Swift/T
+</p>
+</li>
+<li>
+<p>
+An AMI with Swift/T installed is available
+</p>
+</li>
+</ul></div>
+</li>
+<li>
+<p>
+Use the provided script <code>turbine/scripts/submit/ec2/turbine-setup-ec2.zsh</code>.
+</p>
+<div class="ulist"><ul>
+<li>
+<p>
+See the script header for usage notes
+</p>
+</li>
+<li>
+<p>
+This will configure SSH settings and create a hosts file for MPICH
+ and install them on the EC2 instance
+</p>
+</li>
+</ul></div>
+</li>
+</ul></div>
+<div class="paragraph"><p>To run:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>export TURBINE_LAUNCH_OPTS="-f $HOME/hosts.txt"
+turbine program.tcl</code></pre>
+</div></div>
+</div>
+</div>
+</div>
+</div>
+</div>
+<div id="footnotes"><hr /></div>
+<div id="footer">
+<div id="footer-text">
+Version 0.5.0<br />
+Last updated 2014-04-22 13:21:57 CDT
+</div>
+</div>
+</body>
+</html>
More information about the Swift-commit
mailing list