tIntroduction finished - 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
---
(DIR) commit b9800d3a2ef6aa3ec0a0bbf31643f7968d03e01f
(DIR) parent 47d72c195f6a1da29ff8d6dc6ed5c2bb475b6e45
(HTM) Author: Anders Damsgaard Christensen <adc@geo.au.dk>
Date: Thu, 6 Dec 2012 08:09:10 +0100
Introduction finished
Diffstat:
M doc/sphinx/Makefile | 13 +++++++------
M doc/sphinx/conf.py | 2 +-
M doc/sphinx/index.rst | 5 +++--
M doc/sphinx/introduction.rst | 59 +++++++++++++++++++++++++++----
4 files changed, 63 insertions(+), 16 deletions(-)
---
(DIR) diff --git a/doc/sphinx/Makefile b/doc/sphinx/Makefile
t@@ -16,7 +16,7 @@ I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
-default: doxygen-xml html
+default: html
help:
@echo "Please use \`make <target>' where <target> is one of"
t@@ -43,14 +43,15 @@ help:
clean:
-rm -rf $(BUILDDIR)/*
-doxygen-xml: ../doxygen/Makefile ../doxygen/Doxyfile
- $(MAKE) -C ../doxygen/
-html:
+html: doxygen-xml
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+doxygen-xml: ../doxygen/Makefile ../doxygen/Doxyfile
+ $(MAKE) -C ../doxygen/
+
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
t@@ -100,14 +101,14 @@ epub:
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
-latex:
+latex: doxygen-xml
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
-latexpdf:
+latexpdf: doxygen-xml
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
(DIR) diff --git a/doc/sphinx/conf.py b/doc/sphinx/conf.py
t@@ -32,7 +32,7 @@ sys.path.insert(0, os.path.abspath('../../python/'))
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
#extensions = []
-extensions = ['sphinx.ext.autodoc','breathe']
+extensions = ['sphinx.ext.autodoc','breathe','sphinx.ext.pngmath']
breathe_projects = { "sphere": "../doxygen/xml/" }
breathe_default_project = "sphere"
(DIR) diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst
t@@ -9,7 +9,7 @@ This is the official documentation for the *sphere* discrete element modelling s
*sphere* is developed by Anders Damsgaard Christensen under supervision of David Lunbek Egholm and Jan A. Piotrowski, all of the department of Geology, Aarhus University, Denmark. This document is a work in progress, and is still in an early state.
-Contact: Anders Damsgaard Christensen, http://cs.au.dk/~adc, adc@geo.au.dk
+Contact: Anders Damsgaard Christensen, `<http://cs.au.dk/~adc>`_, `<adc@geo.au.dk>`_
Contents:
t@@ -27,7 +27,8 @@ Contents:
Indices and tables
==================
+.. * :ref:`modindex`
+
* :ref:`genindex`
-* :ref:`modindex`
* :ref:`search`
(DIR) diff --git a/doc/sphinx/introduction.rst b/doc/sphinx/introduction.rst
t@@ -1,14 +1,59 @@
Introduction
============
-The \texttt{SPHERE}-software is used for three-dimensional discrete element method (DEM) particle simulations. The source code is written in \texttt{C++} and \texttt{CUDA C}, and compiled by the user. The main computations are performed on the graphics processing unit (GPU) using NVIDIA's general purpose parallel computing architecture, CUDA.
+The *sphere*-software is used for three-dimensional discrete element method (DEM) particle simulations. The source code is written in C++, CUDA C and Python, and is compiled by the user. The main computations are performed on the graphics processing unit (GPU) using NVIDIA's general purpose parallel computing architecture, CUDA. Simulation setup and data analysis is performed with the included Python API.
+The ultimate aim of the *sphere* software is to simulate soft-bedded subglacial conditions, while retaining the flexibility to perform simulations of granular material in other environments.
-The ultimate aim of the \texttt{SPHERE} software is to simulate soft-bedded subglacial conditions, while retaining the flexibility to perform simulations of granular material in other environments. The requirements to the host computer are:
+The purpose of this documentation is to provide the user with a thorough walk-through of the installation, work-flow, data-analysis and visualization methods of *sphere*. In addition, the *sphere* internals are exposed to provide a way of understanding of the discrete element method numerical routines taking place.
-* UNIX, Linux or Mac OS X operating system.
-* GCC, the GNU compiler collection.
-* A CUDA-enabled GPU with compute capability 1.1 or greater\footnote{See \url{http://www.nvidia.com/object/cuda_gpus.html} for an official list of NVIDIA CUDA GPUs.}.
-* The CUDA Developer Drivers and the CUDA Toolkit\footnote{Obtainable free of charge from \url{http://developer.nvidia.com/object/cuda_3_2_downloads.html}}.
+.. note:: Command examples in this document starting with the symbol ``$`` are meant to be executed in the shell of the operational system, and ``>>>`` means execution in Python.
-For simulation setup and data handling, a Python distribution of a recent version is essential. Required Python modules include Numpy\footnote{\url{http://numpy.scipy.org}}. There is however no requirement of Python on the computer running the \texttt{SPHERE} calculations, i.e. model setup and data analysis can be performed on a separate device. Command examples in this document starting with the symbol '\verb"$"' are executed in the shell of the operational system, and '\verb">>>"' means execution in Python. All numerical values in this document, the source code, and the configuration files are typeset with strict respect to the SI unit system.
+All numerical values in this document, the source code, and the configuration files are typeset with strict respect to the SI unit system.
+Requirements
+------------
+The build requirements are:
+ * A Nvidia CUDA-supported version of Linux or Mac OS X (see the `CUDA toolkit release notes <http://docs.nvidia.com/cuda/cuda-toolkit-release-notes/index.html>`_ for more information)
+ * `GNU Make <https://www.gnu.org/software/make/>`_
+ * The `GNU Compiler Collection <http://gcc.gnu.org/>`_ (GCC)
+ * The `Nvidia CUDA toolkit and SDK <https://developer.nvidia.com/cuda-downloads>`_
+
+The runtime requirements are:
+ * A `CUDA-enabled GPU <http://www.nvidia.com/object/cuda_gpus.html>`_ with compute capability 1.1 or greater.
+ * A Nvidia CUDA-enabled GPU and device driver
+
+Optional tools, required for simulation setup and data processing:
+ * `Python 2.7 <http://www.python.org/getit/releases/2.7/>`_
+ * `Numpy <http://numpy.scipy.org>`_
+ * `Matplotlib <http://matplotlib.org>`_
+ * `Imagemagick <http://www.imagemagick.org/script/index.php>`_
+ * `ffmpeg <http://ffmpeg.org/>`_
+
+Optional tools, required for building the documentation:
+ * `Sphinx <http://sphinx-doc.org>`_
+ * `Doxygen <http://www.stack.nl/~dimitri/doxygen/>`_
+ * `Breathe <http://michaeljones.github.com/breathe/>`_
+
+`Git <http://git-scm.com>`_ is used as the distributed version control system platform, and the source code is maintained at `Github <https://github.com/anders-dc/sphere/>`_. *sphere* is licensed under the `GNU Public License, v.3 <https://www.gnu.org/licenses/gpl.html>`_.
+
+
+Building *sphere*
+-----------------
+All instructions required for building *sphere* are provided in a number of ``Makefiles``. To generate the main *sphere* command-line executable, go to the source code directory, and invoke GNU Make::
+
+ $ cd src
+ $ make
+
+If successfull, the GNU Makefile will create the required data folders, object files, as well as the *sphere* executable in the root folder. The executable will be named after the host architecture, e.g. ``sphere_darwin_i386`` on a 32-bit OS X system, or ``sphere_linux_x86_64`` on a 64-bit linux system. Issue the following command to check the executable::
+
+ $ ./sphere_* --version
+
+The documentation can be read in the `reStructuredText <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html>`_-format in the ``doc/sphinx/`` folder, or build into e.g. HTML or PDF format with the following commands::
+
+ $ cd doc/sphinx
+ $ make html
+ $ make latexpdf
+
+To see all available output formats, execute::
+
+ $ make help