GopherProxy

	tintroduction.rst - sphere - GPU-based 3D discrete element method algorithm wit…
	git clone git://src.adamsgaard.dk/sphere
	Log
	Files
	Refs
	LICENSE
	---
	tintroduction.rst (7660B)
	---
	1 Introduction and Installation
	2 =============================
	3
	4 The ``sphere``-software is used for three-dimensional discrete element m…
	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…
	7 graphics processing unit (GPU) using NVIDIA's general purpose parallel c…
	8 architecture, CUDA. Simulation setup and data analysis is performed with…
	9 included Python API.
	10
	11 The ultimate aim of the ``sphere`` software is to simulate soft-bedded s…
	12 conditions, while retaining the flexibility to perform simulations of gr…
	13 material in other environments.
	14
	15 The purpose of this documentation is to provide the user with a walk-thr…
	16 the installation, work-flow, data-analysis and visualization methods of
	17 ``sphere``. In addition, the ``sphere`` internals are exposed to provide…
	18 understanding of the discrete element method numerical routines taking p…
	19
	20 .. note:: Command examples in this document starting with the symbol ``$…
	21 meant to be executed in the shell of the operational system, and ``>>…
	22 means execution in Python. `IPython <http://ipython.org>`_ is an exce…
	23 interactive Python shell.
	24
	25 All numerical values in this document, the source code, and the configur…
	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 …
	35 release notes <http://docs.nvidia.com/cuda/cuda-toolkit-release-note…
	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-download…
	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-…
	45
	46 Unfortunately, the Nvidia Toolkit is shipped under a non-free license. I…
	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>`_ …
	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…
	71 following tools are required for building the documentation:
	72
	73 * `Sphinx <http://sphinx-doc.org>`_
	74
	75 * `sphinxcontrib-programoutput <http://packages.python.org/sphinxcon…
	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 s…
	89 platform, and the source code is maintained at `Github
	90 <https://github.com/anders-dc/sphere/>`_. ``sphere`` is licensed under t…
	91 Public License, v.3 <https://www.gnu.org/licenses/gpl.html>`_.
	92
	93 .. note:: All Debian GNU/Linux runtime, optional, and documentation depe…
	94 mentioned above can be installed by executing the following command f…
	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 [email protected]:anders-dc/sphere.git
	108
	109
	110 Building ``sphere``
	111 -------------------
	112
	113 ``sphere`` is built using ``cmake``, the platform-specific C/C++ compile…
	114 and ``nvcc`` from the Nvidia CUDA toolkit.
	115
	116 If you instead plan to execute it on a Fermi GPU, change ``set(GPU_GENER…
	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 be…
	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,…
	125 ``cmake . && make`` again. Alternatively, copy ``helper_math.h`` from th…
	126 sample subdirectory ``common/inc/helper_math.h`` into the sphere ``src/``
	127 directory, and run ``cmake`` and ``make`` again. Due to license restrict…
	128 sphere cannot be distributed with this file.
	129
	130 If you plan to run ``sphere`` on a Kepler GPU, execute the following com…
	131 from the root directory::
	132
	133 $ cmake . && make
	134
	135 NOTE: If your system does not have a GCC compiler compatible with the in…
	136 CUDA version (e.g. GCC-5 for CUDA 8), you will see errors at the linker …
	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) && cm…
	141
	142 After a successfull installation, the ``sphere`` executable will be loca…
	143 in the root folder. To make sure that all components are working correct…
	144 execute::
	145
	146 $ make test
	147
	148 Disclaimer: On some systems the Navier-Stokes related tests will fail. …
	149 do encounter these problems, but do not plan on using the Navier Stokes …
	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>`_-f…
	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 ``spher…
	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 h…
	191 a simulation is typically arranged in the following order:
	192
	193 * Setup of particle assemblage, physical properties and conditions usi…
	194 Python API (``python/sphere.py``).
	195 * Execution of ``sphere`` software, which simulates the particle behav…
	196 function of time, as a result of the conditions initially specified …
	197 input file.
	198 * Inspection, analysis, interpretation and visualization of ``sphere``…
	199 in Python, and/or scene rendering using the built-in ray tracer.