tintroduction.rst - 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.rst (7660B)
---
1 Introduction and Installation
2 =============================
3
4 The ``sphere``-software is used for three-dimensional discrete element method
5 (DEM) particle simulations. The source code is written in C++, CUDA C and
6 Python, and is compiled by the user. The main computations are performed on the
7 graphics processing unit (GPU) using NVIDIA's general purpose parallel computing
8 architecture, CUDA. Simulation setup and data analysis is performed with the
9 included Python API.
10
11 The ultimate aim of the ``sphere`` software is to simulate soft-bedded subglacial
12 conditions, while retaining the flexibility to perform simulations of granular
13 material in other environments.
14
15 The purpose of this documentation is to provide the user with a walk-through of
16 the installation, work-flow, data-analysis and visualization methods of
17 ``sphere``. In addition, the ``sphere`` internals are exposed to provide a way of
18 understanding of the discrete element method numerical routines taking place.
19
20 .. note:: Command examples in this document starting with the symbol ``$`` are
21 meant to be executed in the shell of the operational system, and ``>>>``
22 means execution in Python. `IPython <http://ipython.org>`_ is an excellent,
23 interactive Python shell.
24
25 All numerical values in this document, the source code, and the configuration
26 files are typeset with strict respect to the SI unit system.
27
28
29 Requirements
30 ------------
31
32 The build requirements are:
33
34 * A Nvidia CUDA-supported version of Linux or Mac OS X (see the `CUDA toolkit
35 release notes <http://docs.nvidia.com/cuda/cuda-toolkit-release-notes/index.html>`_ for more information)
36 * `GNU Make <https://www.gnu.org/software/make/>`_
37 * `CMake <http://www.cmake.org>`_, version 2.8 or newer
38 * The `GNU Compiler Collection <http://gcc.gnu.org/>`_ (GCC)
39 * The `Nvidia CUDA toolkit <https://developer.nvidia.com/cuda-downloads>`_,
40 version 8.0 or newer
41
42 In Debian GNU/Linux, these dependencies can be installed by running::
43
44 $ sudo apt-get install build-essential cmake nvidia-cuda-toolkit clang-3.8
45
46 Unfortunately, the Nvidia Toolkit is shipped under a non-free license. In order
47 to install it in Debian GNU/Linux, add ``non-free`` archives to your
48 ``/etc/apt/sources.list``.
49
50 The runtime requirements are:
51
52 * A `CUDA-enabled GPU <http://www.nvidia.com/object/cuda_gpus.html>`_ with
53 compute capability 2.0 or greater.
54 * A Nvidia CUDA-enabled GPU and device driver
55
56 Optional tools, required for simulation setup and data processing:
57
58 * `Python <http://www.python.org/>`_
59 * `Numpy <http://numpy.scipy.org>`_
60 * `Matplotlib <http://matplotlib.org>`_
61 * `Python bindings for VTK <http://www.vtk.org>`_
62 * `Imagemagick <http://www.imagemagick.org/script/index.php>`_
63 * `ffmpeg <http://ffmpeg.org/>`_. Soon to be replaced by avconv!
64
65 In Debian GNU/Linux, these dependencies can be installed by running::
66
67 $ sudo apt-get install python python-numpy python-matplotlib python-vtk \
68 imagemagick libav-tools
69
70 ``sphere`` is distributed with a HTML and PDF build of the documentation. The
71 following tools are required for building the documentation:
72
73 * `Sphinx <http://sphinx-doc.org>`_
74
75 * `sphinxcontrib-programoutput <http://packages.python.org/sphinxcontrib-programoutput/>`_
76
77 * `Doxygen <http://www.stack.nl/~dimitri/doxygen/>`_
78 * `Breathe <http://michaeljones.github.com/breathe/>`_
79 * `dvipng <http://www.nongnu.org/dvipng/>`_
80 * `TeX Live <http://www.tug.org/texlive/>`_, including ``pdflatex``
81
82 In Debian GNU/Linux, these dependencies can be installed by running::
83
84 $ sudo apt-get install python-sphinx python-pip doxygen dvipng \
85 python-sphinxcontrib-programoutput texlive-full
86 $ sudo pip install breathe
87
88 `Git <http://git-scm.com>`_ is used as the distributed version control system
89 platform, and the source code is maintained at `Github
90 <https://github.com/anders-dc/sphere/>`_. ``sphere`` is licensed under the `GNU
91 Public License, v.3 <https://www.gnu.org/licenses/gpl.html>`_.
92
93 .. note:: All Debian GNU/Linux runtime, optional, and documentation dependencies
94 mentioned above can be installed by executing the following command from the
95 ``doc/`` folder::
96
97 $ make install-debian-pkgs
98
99
100 Obtaining sphere
101 ----------------
102
103 The best way to keep up to date with subsequent updates, bugfixes and
104 development, is to use the Git version control system. To obtain a local
105 copy, execute::
106
107 $ git clone git@github.com:anders-dc/sphere.git
108
109
110 Building ``sphere``
111 -------------------
112
113 ``sphere`` is built using ``cmake``, the platform-specific C/C++ compilers,
114 and ``nvcc`` from the Nvidia CUDA toolkit.
115
116 If you instead plan to execute it on a Fermi GPU, change ``set(GPU_GENERATION
117 1)`` to ``set(GPU_GENERATION 0`` in ``CMakeLists.txt``.
118
119 In some cases the CMake FindCUDA module will have troubles locating the
120 CUDA samples directory, and will complain about ``helper_math.h`` not being
121 found.
122
123 In that case, modify the ``CUDA_SDK_ROOT_DIR`` variable in
124 ``src/CMakeLists.txt`` to the path where you installed the CUDA samples, and run
125 ``cmake . && make`` again. Alternatively, copy ``helper_math.h`` from the CUDA
126 sample subdirectory ``common/inc/helper_math.h`` into the sphere ``src/``
127 directory, and run ``cmake`` and ``make`` again. Due to license restrictions,
128 sphere cannot be distributed with this file.
129
130 If you plan to run ``sphere`` on a Kepler GPU, execute the following commands
131 from the root directory::
132
133 $ cmake . && make
134
135 NOTE: If your system does not have a GCC compiler compatible with the installed
136 CUDA version (e.g. GCC-5 for CUDA 8), you will see errors at the linker stage.
137 In that case, try using ``clang-3.8`` as the C and C++ compiler instead::
138
139 $ rm -rf CMakeCache.txt CMakeFiles/
140 $ export CC=$(which clang-3.8) && export CXX=$(which clang++-3.8) && cmake . && make
141
142 After a successfull installation, the ``sphere`` executable will be located
143 in the root folder. To make sure that all components are working correctly,
144 execute::
145
146 $ make test
147
148 Disclaimer: On some systems the Navier-Stokes related tests will fail. If you
149 do encounter these problems, but do not plan on using the Navier Stokes solver
150 for fluid dynamics, carry on.
151
152 If successful the Makefiles will create the required data folders, object
153 files, as well as the ``sphere`` executable in the root folder. Issue the
154 following commands to check the executable::
155
156 $ ./sphere --version
157
158 The output should look similar to this:
159
160 .. program-output:: ../../sphere --version
161
162 The documentation can be read in the `reStructuredText
163 <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html>`_-format in
164 the ``doc/sphinx/`` folder, or in the HTML or PDF formats in the folders
165 ``doc/html`` and ``doc/pdf``.
166
167 Optionally, the documentation can be built using the following commands::
168
169 $ cd doc/sphinx
170 $ make html
171 $ make latexpdf
172
173 To see all available output formats, execute::
174
175 $ make help
176
177
178 Updating sphere
179 ---------------
180
181 To update your local version, type the following commands in the ``sphere`` root
182 directory::
183
184 $ git pull && cmake . && make
185
186
187 Work flow
188 ---------
189
190 After compiling the ``sphere`` binary, the procedure of a creating and handling
191 a simulation is typically arranged in the following order:
192
193 * Setup of particle assemblage, physical properties and conditions using the
194 Python API (``python/sphere.py``).
195 * Execution of ``sphere`` software, which simulates the particle behavior as a
196 function of time, as a result of the conditions initially specified in the
197 input file.
198 * Inspection, analysis, interpretation and visualization of ``sphere`` output
199 in Python, and/or scene rendering using the built-in ray tracer.