tintroduction.html - sphere - GPU-based 3D discrete element method algorithm with optional fluid coupling
(HTM) git clone git://src.adamsgaard.dk/sphere
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) LICENSE
---
tintroduction.html (19664B)
---
1
2 <!DOCTYPE html>
3
4 <html xmlns="http://www.w3.org/1999/xhtml">
5 <head>
6 <meta charset="utf-8" />
7 <title>Introduction and Installation — sphere 2.15-beta documentation</title>
8 <link rel="stylesheet" href="_static/classic.css" type="text/css" />
9 <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
10
11 <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
12 <script type="text/javascript" src="_static/jquery.js"></script>
13 <script type="text/javascript" src="_static/underscore.js"></script>
14 <script type="text/javascript" src="_static/doctools.js"></script>
15 <script type="text/javascript" src="_static/language_data.js"></script>
16
17 <link rel="index" title="Index" href="genindex.html" />
18 <link rel="search" title="Search" href="search.html" />
19 <link rel="next" title="Discrete element method" href="dem.html" />
20 <link rel="prev" title="The sphere documentation" href="index.html" />
21 </head><body>
22 <div class="related" role="navigation" aria-label="related navigation">
23 <h3>Navigation</h3>
24 <ul>
25 <li class="right" style="margin-right: 10px">
26 <a href="genindex.html" title="General Index"
27 accesskey="I">index</a></li>
28 <li class="right" >
29 <a href="py-modindex.html" title="Python Module Index"
30 >modules</a> |</li>
31 <li class="right" >
32 <a href="dem.html" title="Discrete element method"
33 accesskey="N">next</a> |</li>
34 <li class="right" >
35 <a href="index.html" title="The sphere documentation"
36 accesskey="P">previous</a> |</li>
37 <li class="nav-item nav-item-0"><a href="index.html">sphere 2.15-beta documentation</a> »</li>
38 </ul>
39 </div>
40
41 <div class="document">
42 <div class="documentwrapper">
43 <div class="bodywrapper">
44 <div class="body" role="main">
45
46 <div class="section" id="introduction-and-installation">
47 <h1>Introduction and Installation<a class="headerlink" href="#introduction-and-installation" title="Permalink to this headline">¶</a></h1>
48 <p>The <code class="docutils literal notranslate"><span class="pre">sphere</span></code>-software is used for three-dimensional discrete element method
49 (DEM) particle simulations. The source code is written in C++, CUDA C and
50 Python, and is compiled by the user. The main computations are performed on the
51 graphics processing unit (GPU) using NVIDIA’s general purpose parallel computing
52 architecture, CUDA. Simulation setup and data analysis is performed with the
53 included Python API.</p>
54 <p>The ultimate aim of the <code class="docutils literal notranslate"><span class="pre">sphere</span></code> software is to simulate soft-bedded subglacial
55 conditions, while retaining the flexibility to perform simulations of granular
56 material in other environments.</p>
57 <p>The purpose of this documentation is to provide the user with a walk-through of
58 the installation, work-flow, data-analysis and visualization methods of
59 <code class="docutils literal notranslate"><span class="pre">sphere</span></code>. In addition, the <code class="docutils literal notranslate"><span class="pre">sphere</span></code> internals are exposed to provide a way of
60 understanding of the discrete element method numerical routines taking place.</p>
61 <div class="admonition note">
62 <p class="admonition-title">Note</p>
63 <p>Command examples in this document starting with the symbol <code class="docutils literal notranslate"><span class="pre">$</span></code> are
64 meant to be executed in the shell of the operational system, and <code class="docutils literal notranslate"><span class="pre">>>></span></code>
65 means execution in Python. <a class="reference external" href="http://ipython.org">IPython</a> is an excellent,
66 interactive Python shell.</p>
67 </div>
68 <p>All numerical values in this document, the source code, and the configuration
69 files are typeset with strict respect to the SI unit system.</p>
70 <div class="section" id="requirements">
71 <h2>Requirements<a class="headerlink" href="#requirements" title="Permalink to this headline">¶</a></h2>
72 <p>The build requirements are:</p>
73 <blockquote>
74 <div><ul class="simple">
75 <li><p>A Nvidia CUDA-supported version of Linux or Mac OS X (see the <a class="reference external" href="http://docs.nvidia.com/cuda/cuda-toolkit-release-notes/index.html">CUDA toolkit
76 release notes</a> for more information)</p></li>
77 <li><p><a class="reference external" href="https://www.gnu.org/software/make/">GNU Make</a></p></li>
78 <li><p><a class="reference external" href="http://www.cmake.org">CMake</a>, version 2.8 or newer</p></li>
79 <li><p>The <a class="reference external" href="http://gcc.gnu.org/">GNU Compiler Collection</a> (GCC)</p></li>
80 <li><p>The <a class="reference external" href="https://developer.nvidia.com/cuda-downloads">Nvidia CUDA toolkit</a>,
81 version 8.0 or newer</p></li>
82 </ul>
83 </div></blockquote>
84 <p>In Debian GNU/Linux, these dependencies can be installed by running:</p>
85 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ sudo apt-get install build-essential cmake nvidia-cuda-toolkit clang-3.8
86 </pre></div>
87 </div>
88 <p>Unfortunately, the Nvidia Toolkit is shipped under a non-free license. In order
89 to install it in Debian GNU/Linux, add <code class="docutils literal notranslate"><span class="pre">non-free</span></code> archives to your
90 <code class="docutils literal notranslate"><span class="pre">/etc/apt/sources.list</span></code>.</p>
91 <p>The runtime requirements are:</p>
92 <blockquote>
93 <div><ul class="simple">
94 <li><p>A <a class="reference external" href="http://www.nvidia.com/object/cuda_gpus.html">CUDA-enabled GPU</a> with
95 compute capability 2.0 or greater.</p></li>
96 <li><p>A Nvidia CUDA-enabled GPU and device driver</p></li>
97 </ul>
98 </div></blockquote>
99 <p>Optional tools, required for simulation setup and data processing:</p>
100 <blockquote>
101 <div><ul class="simple">
102 <li><p><a class="reference external" href="http://www.python.org/">Python</a></p></li>
103 <li><p><a class="reference external" href="http://numpy.scipy.org">Numpy</a></p></li>
104 <li><p><a class="reference external" href="http://matplotlib.org">Matplotlib</a></p></li>
105 <li><p><a class="reference external" href="http://www.vtk.org">Python bindings for VTK</a></p></li>
106 <li><p><a class="reference external" href="http://www.imagemagick.org/script/index.php">Imagemagick</a></p></li>
107 <li><p><a class="reference external" href="http://ffmpeg.org/">ffmpeg</a>. Soon to be replaced by avconv!</p></li>
108 </ul>
109 </div></blockquote>
110 <p>In Debian GNU/Linux, these dependencies can be installed by running:</p>
111 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ sudo apt-get install python python-numpy python-matplotlib python-vtk \
112 imagemagick libav-tools
113 </pre></div>
114 </div>
115 <p><code class="docutils literal notranslate"><span class="pre">sphere</span></code> is distributed with a HTML and PDF build of the documentation. The
116 following tools are required for building the documentation:</p>
117 <blockquote>
118 <div><ul class="simple">
119 <li><p><a class="reference external" href="http://sphinx-doc.org">Sphinx</a></p>
120 <ul>
121 <li><p><a class="reference external" href="http://packages.python.org/sphinxcontrib-programoutput/">sphinxcontrib-programoutput</a></p></li>
122 </ul>
123 </li>
124 <li><p><a class="reference external" href="http://www.stack.nl/~dimitri/doxygen/">Doxygen</a></p></li>
125 <li><p><a class="reference external" href="http://michaeljones.github.com/breathe/">Breathe</a></p></li>
126 <li><p><a class="reference external" href="http://www.nongnu.org/dvipng/">dvipng</a></p></li>
127 <li><p><a class="reference external" href="http://www.tug.org/texlive/">TeX Live</a>, including <code class="docutils literal notranslate"><span class="pre">pdflatex</span></code></p></li>
128 </ul>
129 </div></blockquote>
130 <p>In Debian GNU/Linux, these dependencies can be installed by running:</p>
131 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ sudo apt-get install python-sphinx python-pip doxygen dvipng \
132 python-sphinxcontrib-programoutput texlive-full
133 $ sudo pip install breathe
134 </pre></div>
135 </div>
136 <p><a class="reference external" href="http://git-scm.com">Git</a> is used as the distributed version control system
137 platform, and the source code is maintained at <a class="reference external" href="https://github.com/anders-dc/sphere/">Github</a>. <code class="docutils literal notranslate"><span class="pre">sphere</span></code> is licensed under the <a class="reference external" href="https://www.gnu.org/licenses/gpl.html">GNU
138 Public License, v.3</a>.</p>
139 <div class="admonition note">
140 <p class="admonition-title">Note</p>
141 <p>All Debian GNU/Linux runtime, optional, and documentation dependencies
142 mentioned above can be installed by executing the following command from the
143 <code class="docutils literal notranslate"><span class="pre">doc/</span></code> folder:</p>
144 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ make install-debian-pkgs
145 </pre></div>
146 </div>
147 </div>
148 </div>
149 <div class="section" id="obtaining-sphere">
150 <h2>Obtaining sphere<a class="headerlink" href="#obtaining-sphere" title="Permalink to this headline">¶</a></h2>
151 <p>The best way to keep up to date with subsequent updates, bugfixes and
152 development, is to use the Git version control system. To obtain a local
153 copy, execute:</p>
154 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ git clone git@github.com:anders-dc/sphere.git
155 </pre></div>
156 </div>
157 </div>
158 <div class="section" id="building-sphere">
159 <h2>Building <code class="docutils literal notranslate"><span class="pre">sphere</span></code><a class="headerlink" href="#building-sphere" title="Permalink to this headline">¶</a></h2>
160 <p><code class="docutils literal notranslate"><span class="pre">sphere</span></code> is built using <code class="docutils literal notranslate"><span class="pre">cmake</span></code>, the platform-specific C/C++ compilers,
161 and <code class="docutils literal notranslate"><span class="pre">nvcc</span></code> from the Nvidia CUDA toolkit.</p>
162 <p>If you instead plan to execute it on a Fermi GPU, change <code class="docutils literal notranslate"><span class="pre">set(GPU_GENERATION</span>
163 <span class="pre">1)</span></code> to <code class="docutils literal notranslate"><span class="pre">set(GPU_GENERATION</span> <span class="pre">0</span></code> in <code class="docutils literal notranslate"><span class="pre">CMakeLists.txt</span></code>.</p>
164 <p>In some cases the CMake FindCUDA module will have troubles locating the
165 CUDA samples directory, and will complain about <code class="docutils literal notranslate"><span class="pre">helper_math.h</span></code> not being
166 found.</p>
167 <p>In that case, modify the <code class="docutils literal notranslate"><span class="pre">CUDA_SDK_ROOT_DIR</span></code> variable in
168 <code class="docutils literal notranslate"><span class="pre">src/CMakeLists.txt</span></code> to the path where you installed the CUDA samples, and run
169 <code class="docutils literal notranslate"><span class="pre">cmake</span> <span class="pre">.</span> <span class="pre">&&</span> <span class="pre">make</span></code> again. Alternatively, copy <code class="docutils literal notranslate"><span class="pre">helper_math.h</span></code> from the CUDA
170 sample subdirectory <code class="docutils literal notranslate"><span class="pre">common/inc/helper_math.h</span></code> into the sphere <code class="docutils literal notranslate"><span class="pre">src/</span></code>
171 directory, and run <code class="docutils literal notranslate"><span class="pre">cmake</span></code> and <code class="docutils literal notranslate"><span class="pre">make</span></code> again. Due to license restrictions,
172 sphere cannot be distributed with this file.</p>
173 <p>If you plan to run <code class="docutils literal notranslate"><span class="pre">sphere</span></code> on a Kepler GPU, execute the following commands
174 from the root directory:</p>
175 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ cmake . && make
176 </pre></div>
177 </div>
178 <p>NOTE: If your system does not have a GCC compiler compatible with the installed
179 CUDA version (e.g. GCC-5 for CUDA 8), you will see errors at the linker stage.
180 In that case, try using <code class="docutils literal notranslate"><span class="pre">clang-3.8</span></code> as the C and C++ compiler instead:</p>
181 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ rm -rf CMakeCache.txt CMakeFiles/
182 $ export CC=$(which clang-3.8) && export CXX=$(which clang++-3.8) && cmake . && make
183 </pre></div>
184 </div>
185 <p>After a successfull installation, the <code class="docutils literal notranslate"><span class="pre">sphere</span></code> executable will be located
186 in the root folder. To make sure that all components are working correctly,
187 execute:</p>
188 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ make test
189 </pre></div>
190 </div>
191 <p>Disclaimer: On some systems the Navier-Stokes related tests will fail. If you
192 do encounter these problems, but do not plan on using the Navier Stokes solver
193 for fluid dynamics, carry on.</p>
194 <p>If successful the Makefiles will create the required data folders, object
195 files, as well as the <code class="docutils literal notranslate"><span class="pre">sphere</span></code> executable in the root folder. Issue the
196 following commands to check the executable:</p>
197 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ./sphere --version
198 </pre></div>
199 </div>
200 <p>The output should look similar to this:</p>
201 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>.-------------------------------------.
202 | _ |
203 | | | |
204 | ___ _ __ | |__ ___ _ __ ___ |
205 | / __| '_ \| '_ \ / _ \ '__/ _ \ |
206 | \__ \ |_) | | | | __/ | | __/ |
207 | |___/ .__/|_| |_|\___|_| \___| |
208 | | | |
209 | |_| Version: 2.15 |
210 `-------------------------------------´
211 A discrete-element method particle dynamics simulator.
212 Written by Anders Damsgaard, ISC license.
213 https://adamsgaard.dk
214 </pre></div>
215 </div>
216 <p>The documentation can be read in the <a class="reference external" href="http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html">reStructuredText</a>-format in
217 the <code class="docutils literal notranslate"><span class="pre">doc/sphinx/</span></code> folder, or in the HTML or PDF formats in the folders
218 <code class="docutils literal notranslate"><span class="pre">doc/html</span></code> and <code class="docutils literal notranslate"><span class="pre">doc/pdf</span></code>.</p>
219 <p>Optionally, the documentation can be built using the following commands:</p>
220 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ cd doc/sphinx
221 $ make html
222 $ make latexpdf
223 </pre></div>
224 </div>
225 <p>To see all available output formats, execute:</p>
226 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ make help
227 </pre></div>
228 </div>
229 </div>
230 <div class="section" id="updating-sphere">
231 <h2>Updating sphere<a class="headerlink" href="#updating-sphere" title="Permalink to this headline">¶</a></h2>
232 <p>To update your local version, type the following commands in the <code class="docutils literal notranslate"><span class="pre">sphere</span></code> root
233 directory:</p>
234 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ git pull && cmake . && make
235 </pre></div>
236 </div>
237 </div>
238 <div class="section" id="work-flow">
239 <h2>Work flow<a class="headerlink" href="#work-flow" title="Permalink to this headline">¶</a></h2>
240 <p>After compiling the <code class="docutils literal notranslate"><span class="pre">sphere</span></code> binary, the procedure of a creating and handling
241 a simulation is typically arranged in the following order:</p>
242 <blockquote>
243 <div><ul class="simple">
244 <li><p>Setup of particle assemblage, physical properties and conditions using the
245 Python API (<code class="docutils literal notranslate"><span class="pre">python/sphere.py</span></code>).</p></li>
246 <li><p>Execution of <code class="docutils literal notranslate"><span class="pre">sphere</span></code> software, which simulates the particle behavior as a
247 function of time, as a result of the conditions initially specified in the
248 input file.</p></li>
249 <li><p>Inspection, analysis, interpretation and visualization of <code class="docutils literal notranslate"><span class="pre">sphere</span></code> output
250 in Python, and/or scene rendering using the built-in ray tracer.</p></li>
251 </ul>
252 </div></blockquote>
253 </div>
254 </div>
255
256
257 </div>
258 </div>
259 </div>
260 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
261 <div class="sphinxsidebarwrapper">
262 <h3><a href="index.html">Table of Contents</a></h3>
263 <ul>
264 <li><a class="reference internal" href="#">Introduction and Installation</a><ul>
265 <li><a class="reference internal" href="#requirements">Requirements</a></li>
266 <li><a class="reference internal" href="#obtaining-sphere">Obtaining sphere</a></li>
267 <li><a class="reference internal" href="#building-sphere">Building <code class="docutils literal notranslate"><span class="pre">sphere</span></code></a></li>
268 <li><a class="reference internal" href="#updating-sphere">Updating sphere</a></li>
269 <li><a class="reference internal" href="#work-flow">Work flow</a></li>
270 </ul>
271 </li>
272 </ul>
273
274 <h4>Previous topic</h4>
275 <p class="topless"><a href="index.html"
276 title="previous chapter">The sphere documentation</a></p>
277 <h4>Next topic</h4>
278 <p class="topless"><a href="dem.html"
279 title="next chapter">Discrete element method</a></p>
280 <div role="note" aria-label="source link">
281 <h3>This Page</h3>
282 <ul class="this-page-menu">
283 <li><a href="_sources/introduction.rst.txt"
284 rel="nofollow">Show Source</a></li>
285 </ul>
286 </div>
287 <div id="searchbox" style="display: none" role="search">
288 <h3 id="searchlabel">Quick search</h3>
289 <div class="searchformwrapper">
290 <form class="search" action="search.html" method="get">
291 <input type="text" name="q" aria-labelledby="searchlabel" />
292 <input type="submit" value="Go" />
293 </form>
294 </div>
295 </div>
296 <script type="text/javascript">$('#searchbox').show(0);</script>
297 </div>
298 </div>
299 <div class="clearer"></div>
300 </div>
301 <div class="related" role="navigation" aria-label="related navigation">
302 <h3>Navigation</h3>
303 <ul>
304 <li class="right" style="margin-right: 10px">
305 <a href="genindex.html" title="General Index"
306 >index</a></li>
307 <li class="right" >
308 <a href="py-modindex.html" title="Python Module Index"
309 >modules</a> |</li>
310 <li class="right" >
311 <a href="dem.html" title="Discrete element method"
312 >next</a> |</li>
313 <li class="right" >
314 <a href="index.html" title="The sphere documentation"
315 >previous</a> |</li>
316 <li class="nav-item nav-item-0"><a href="index.html">sphere 2.15-beta documentation</a> »</li>
317 </ul>
318 </div>
319 <div class="footer" role="contentinfo">
320 © Copyright 2014, Anders Damsgaard.
321 Created using <a href="http://sphinx-doc.org/">Sphinx</a> 2.2.0.
322 </div>
323 </body>
324 </html>