-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathget-started.html
188 lines (182 loc) · 14.4 KB
/
get-started.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
<html >
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="Content-Style-Type" content="text/css">
<meta name="generator" content="pandoc">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" crossorigin="anonymous">
<link rel="stylesheet" type="text/css" href="/style.css">
<link rel="stylesheet" type="text/css" href="https://fonts.googleapis.com/css?family=Raleway:600,800|Open+Sans">
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.12.4/jquery.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js" integrity="sha384-Tc5IQib027qvyjSMfHjOMaLkfuWVxZxUPnCJA7l2mCWNIpG9mGCD8wGNIcPD7Txa" crossorigin="anonymous"></script>
<script src="https://use.fontawesome.com/c754f00c7e.js"></script>
<!-- <script src="https://cdn.polyfill.io/v2/polyfill.min.js"></script> -->
<title>Accelerate: Get Started</title>
<style type="text/css">code{white-space: pre;}</style>
<style type="text/css">
div.sourceCode { overflow-x: auto; }
table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode {
margin: 0; padding: 0; vertical-align: baseline; border: none; }
table.sourceCode { width: 100%; line-height: 100%; }
td.lineNumbers { text-align: right; padding-right: 4px; padding-left: 4px; color: #aaaaaa; border-right: 1px solid #aaaaaa; }
td.sourceCode { padding-left: 5px; }
code > span.kw { color: #007020; font-weight: bold; } /* Keyword */
code > span.dt { color: #902000; } /* DataType */
code > span.dv { color: #40a070; } /* DecVal */
code > span.bn { color: #40a070; } /* BaseN */
code > span.fl { color: #40a070; } /* Float */
code > span.ch { color: #4070a0; } /* Char */
code > span.st { color: #4070a0; } /* String */
code > span.co { color: #60a0b0; font-style: italic; } /* Comment */
code > span.ot { color: #007020; } /* Other */
code > span.al { color: #ff0000; font-weight: bold; } /* Alert */
code > span.fu { color: #06287e; } /* Function */
code > span.er { color: #ff0000; font-weight: bold; } /* Error */
code > span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
code > span.cn { color: #880000; } /* Constant */
code > span.sc { color: #4070a0; } /* SpecialChar */
code > span.vs { color: #4070a0; } /* VerbatimString */
code > span.ss { color: #bb6688; } /* SpecialString */
code > span.im { } /* Import */
code > span.va { color: #19177c; } /* Variable */
code > span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
code > span.op { color: #666666; } /* Operator */
code > span.bu { } /* BuiltIn */
code > span.ex { } /* Extension */
code > span.pp { color: #bc7a00; } /* Preprocessor */
code > span.at { color: #7d9029; } /* Attribute */
code > span.do { color: #ba2121; font-style: italic; } /* Documentation */
code > span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
code > span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
</style>
</head>
<nav class="navbar navbar-inverse navbar-fixed-top">
<div class="container-fluid">
<!-- Brand and toggle get grouped for better mobile display -->
<div class="navbar-header">
<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1" aria-expanded="false">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="/index.html" style="font-family: 'Raleway'; font-weight: 600;">AccelerateHS</a>
</div>
<!-- Collect the nav links, forms, and other content for toggling -->
<div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
<ul class="nav navbar-nav">
<li class="active"><a href="/get-started.html">Get Started</a></li>
<li><a href="/documentation.html">Documentation</a></li>
<li><a href="/libraries.html">Libraries</a></li>
<li><a href="/examples.html">Examples</a></li>
<li><a href="/community.html">Community</a></li>
<li><a href="/publications.html">Publications</a></li>
</ul>
<ul class="nav navbar-nav navbar-right">
<li><a href="https://github.com/AccelerateHS/accelerate"><i class="fa fa-github fa-lg" aria-hidden="true"></i></a></li>
<li><a href="http://groups.google.com/group/accelerate-haskell"><i class="fa fa-envelope-o fa-lg" aria-hidden="true"></i></a></li>
</ul>
</div><!-- /.navbar-collapse -->
</div><!-- /.container-fluid -->
</nav>
<body>
<div class="container">
<div class="row">
<div id="TOC" class="well">
<!-- <ul> -->
<!-- <li class="nav-header" id="toctitle">Table of Contents</il> -->
<!-- </ul> -->
<ul>
<li><a href="#get-started">Get Started</a><ul>
<li><a href="#setup-haskell-llvm">1. Setup Haskell & LLVM</a></li>
<li><a href="#install-accelerate">2. Install Accelerate</a><ul>
<li><a href="#using-cabal">2.1 Using cabal</a></li>
<li><a href="#using-stack">2.2 Using stack</a></li>
</ul></li>
<li><a href="#run-an-accelerate-program">3. Run an Accelerate program</a></li>
<li><a href="#next-steps">4. Next steps</a></li>
</ul></li>
</ul>
</div>
<div class="container">
<h1 id="get-started">Get Started</h1>
<p><em>Accelerate</em> is a language for data-parallel array computations embedded within the programming language <a href="https://www.haskell.org"><em>Haskell</em></a>. More specifically, it is a deeply embedded language. This means that when you write programs with Accelerate, you are writing a Haskell program using operations from the Accelerate library, but the method by which the program runs is different from a conventional Haskell program. A program written in Accelerate is actually a Haskell program that generates, optimises, and compiles code for the GPU or CPU on-the-fly at program runtime.</p>
<p>To get started you will need to set up a Haskell environment as well as a few external libraries.</p>
<h2 id="setup-haskell-llvm">1. Setup Haskell & LLVM</h2>
<p>Select your operating system:</p>
<p><a href="/get-started/macos" title="macOS" class="os-logo os-choose"> <img src="/media/apple-logo.svg"> </a> <a href="/get-started/linux" title="Linux" class="os-logo os-choose"> <img src="/media/linux-logo.svg"> </a> <a href="/get-started/windows" title="Windows" class="os-logo os-choose"> <img src="/media/windows-logo.svg"> </a></p>
<h2 id="install-accelerate">2. Install Accelerate</h2>
<p>The Haskell ecosystem has two tools to help with building and installing packages: <a href="https://www.haskell.org/cabal/"><code>cabal</code></a> (the default) which installs packages to a global location, and <a href="https://docs.haskellstack.org/en/stable/README/"><code>stack</code></a>, which has a more project-centric focus.</p>
<h3 id="using-cabal">2.1 Using cabal</h3>
<p>We can now install the core Accelerate library:</p>
<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">cabal</span> install accelerate</code></pre></div>
<p>This will install the current stable release of Accelerate from <a href="https://hackage.haskell.org">Hackage</a>. If you would like to instead install the latest in-development version, see how to <a href="/get-started/install-from-github.html">install from GitHub</a>.</p>
<p>This is sufficient to write programs in Accelerate as well as execute them using the included interpreter backend.<a href="#fn1" class="footnoteRef" id="fnref1"><sup>1</sup></a> For good performance however we also need to install one (or both) of the LLVM backends, which will compile Accelerate programs to native code.</p>
<p>Install a version of the <code>llvm-hs</code> package suitable for the version of LLVM installed on your system. The first two numbers of the version of LLVM and the <code>llvm-hs</code> package must match. We must also install with shared library support so that we can use <code>llvm-hs</code> from within <code>ghci</code> and Template Haskell. For example, if you have LLVM-4.0 installed:</p>
<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">cabal</span> install llvm-hs -fshared-llvm --constraint=<span class="st">"llvm-hs==4.0.*"</span></code></pre></div>
<p>Install the Accelerate LLVM backend for multicore CPUs:</p>
<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">cabal</span> install accelerate-llvm-native</code></pre></div>
<p>(Optional) If you have a CUDA capable GPU, you can also install the Accelerate backend for NVIDIA GPUs:</p>
<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">cabal</span> install accelerate-llvm-ptx</code></pre></div>
<h3 id="using-stack">2.2 Using stack</h3>
<p>You can use Accelerate in a stack-based workflow by including the following (or similar) into the <code>stack.yaml</code> file of your project:</p>
<div class="sourceCode"><pre class="sourceCode yaml"><code class="sourceCode yaml"><span class="fu">resolver:</span> lts-9.0
<span class="fu">extra-deps:</span>
<span class="kw">-</span> <span class="st">'accelerate-llvm-1.0.0.0'</span>
<span class="kw">-</span> <span class="st">'accelerate-llvm-native-1.0.0.0'</span>
<span class="kw">-</span> <span class="st">'accelerate-llvm-ptx-1.0.0.0'</span>
<span class="kw">-</span> <span class="st">'cuda-0.7.5.3'</span>
<span class="kw">-</span> <span class="st">'llvm-hs-4.0.1.0'</span>
<span class="kw">-</span> <span class="st">'llvm-hs-pure-4.0.0.0'</span>
<span class="fu">flags:</span>
<span class="fu">llvm-hs:</span>
<span class="fu">shared-llvm:</span> true</code></pre></div>
<h2 id="run-an-accelerate-program">3. Run an Accelerate program</h2>
<p>Copy the following content into a file called <code>Dotp.hs</code>. This simple example computes the dot product of two vectors of single-precision floating-point numbers. If you installed the GPU backend in step <a href="#install-accelerate">2</a>, you can uncomment the third line (delete the leading <code>--</code>) to enable both the CPU and GPU backends.</p>
<div class="sourceCode"><pre class="sourceCode haskell"><code class="sourceCode haskell"><span class="kw">import </span><span class="dt">Data.Array.Accelerate</span> <span class="kw">as</span> <span class="dt">A</span>
<span class="kw">import </span><span class="dt">Data.Array.Accelerate.LLVM.Native</span> <span class="kw">as</span> <span class="dt">CPU</span>
<span class="co">-- import Data.Array.Accelerate.LLVM.PTX as GPU</span>
<span class="ot">dotp ::</span> <span class="dt">Acc</span> (<span class="dt">Vector</span> <span class="dt">Float</span>) <span class="ot">-></span> <span class="dt">Acc</span> (<span class="dt">Vector</span> <span class="dt">Float</span>) <span class="ot">-></span> <span class="dt">Acc</span> (<span class="dt">Scalar</span> <span class="dt">Float</span>)
dotp xs ys <span class="fu">=</span> A.fold (<span class="fu">+</span>) <span class="dv">0</span> (A.zipWith (<span class="fu">*</span>) xs ys)</code></pre></div>
<p>Open up a terminal and load the file into the Haskell interpreter with <code>ghci Dotp.hs</code>.</p>
<ol style="list-style-type: decimal">
<li><p>Create some arrays to feed into the computation. See the <a href="/documentation.html">documentation</a> for more information, as well as additional ways to get data into the program.</p>
<pre><code>ghci> let xs = fromList (Z:.10) [0..] :: Vector Float
ghci> let ys = fromList (Z:.10) [1,3..] :: Vector Float</code></pre></li>
<li><p>Run the computation:</p>
<pre><code>ghci> CPU.run $ dotp (use xs) (use ys)
Scalar Z [615.0]</code></pre>
<p>This will convert the Accelerate program into LLVM code, optimise, compile, and execute it on the CPU. If your computer has multiple CPU cores, you can execute using multiple CPU cores by launching <code>ghci</code> (or running a compiled program) with the additional command line options <code>+RTS -Nx -RTS</code>, to use <em>x</em> CPU cores (or omit <em>x</em> to use as many cores as your machine has).</p></li>
<li><p>(Optional) If you installed the <code>accelerate-llvm-ptx</code> backend, you can also execute the computation on the GPU simply by:</p>
<pre><code>ghci> GPU.run $ dotp (use xs) (use ys)
Scalar Z [615.0]</code></pre>
<p>This will instead convert the Accelerate program into LLVM code suitable for the GPU, optimise, compile, and execute it on the GPU, as well as copy the input arrays into GPU memory and copy the result back into CPU memory.</p></li>
</ol>
<h2 id="next-steps">4. Next steps</h2>
<p>Congratulations, you are set up to use Accelerate! Now you are ready to:</p>
<ul>
<li><p><a href="/documentation.html">Learn more about the Accelerate language</a></p></li>
<li><p><a href="/libraries.html">Browse libraries that you can use in your projects</a></p></li>
<li><p><a href="/examples.html">Check out some example programs</a></p></li>
</ul>
<div class="footnotes">
<hr />
<ol>
<li id="fn1"><p>Although the core <code>accelerate</code> package includes an interpreter that can be used to run Accelerate programs, its performance is fairly poor as it is designed as a reference implementation of the language semantics, rather than for performance.<a href="#fnref1">↩</a></p></li>
</ol>
</div>
</div>
</div>
</div>
<footer class="footer">
<div class="container text-center">
<p class="text-muted">
<a href="https://github.com/AccelerateHS/accelerate">GitHub Project</a> ·
<a href="https://github.com/AccelerateHS/accelerate/issues">Issue Tracker</a> ·
<a href="http://groups.google.com/group/accelerate-haskell">Mailing List</a>
</p>
</div>
</footer>
</body>
</html>