tgeneral updates - sphere - GPU-based 3D discrete element method algorithm with… | |
git clone git://src.adamsgaard.dk/sphere | |
Log | |
Files | |
Refs | |
LICENSE | |
--- | |
commit 31a7e78397358a6c7b91b5f037d61a71b928bc90 | |
parent 3483d6d9a230229c803b778263b77fc5ac4fa5bf | |
Author: Anders Damsgaard <[email protected]> | |
Date: Fri, 16 Aug 2013 11:22:47 +0200 | |
general updates | |
Diffstat: | |
M README.rst | 2 +- | |
M doc/html/_sources/dem.txt | 12 +++++++++++- | |
M doc/html/_sources/index.txt | 17 ++++++++++++----- | |
M doc/html/_sources/introduction.txt | 60 +++++++++++++++++++++++------… | |
M doc/html/_sources/sphere_internals… | 2 +- | |
M doc/html/dem.html | 12 +++++++++++- | |
M doc/html/genindex.html | 65 +++++++++++++++++++++++++++++… | |
M doc/html/index.html | 13 ++++++++++--- | |
M doc/html/introduction.html | 61 ++++++++++++++++++++++-------… | |
M doc/html/objects.inv | 0 | |
M doc/html/python_api.html | 106 +++++++++++++++++++++++++++++… | |
M doc/html/searchindex.js | 4 ++-- | |
M doc/html/sphere_internals.html | 27 ++++++++++++++++++++++----- | |
M doc/pdf/sphere.pdf | 0 | |
M doc/sphinx/dem.rst | 12 +++++++++++- | |
M doc/sphinx/index.rst | 17 ++++++++++++----- | |
M doc/sphinx/introduction.rst | 60 +++++++++++++++++++++++------… | |
M doc/sphinx/sphere_internals.rst | 2 +- | |
M python/darcy.py | 2 +- | |
M tests/io_tests.py | 18 ++++++++---------- | |
20 files changed, 394 insertions(+), 98 deletions(-) | |
--- | |
diff --git a/README.rst b/README.rst | |
t@@ -24,7 +24,7 @@ The build requirements are: | |
The runtime requirements are: | |
* A `CUDA-enabled GPU <http://www.nvidia.com/object/cuda_gpus.html>`_ | |
- with compute capability 1.1 or greater. | |
+ with compute capability 2.0 or greater. | |
* A Nvidia CUDA-enabled GPU and device driver | |
Optional tools, required for simulation setup and data processing: | |
diff --git a/doc/html/_sources/dem.txt b/doc/html/_sources/dem.txt | |
t@@ -1,6 +1,16 @@ | |
Discrete element method | |
======================= | |
-The discrete element method (or distinct element method) was initially formula… | |
+The discrete element method (or distinct element method) was initially | |
+formulated by Cundall and Strack (1979). It simulates the physical behavior and | |
+interaction of discrete, unbreakable particles, with their own mass and inerti… | |
+under the influence of e.g. gravity and boundary conditions such as moving | |
+walls. By discretizing time into small time steps, explicit integration of | |
+Newton's second law of motion is used to predict the new position and kinematic | |
+values for each particle from the previous sums of forces. This Lagrangian | |
+approach is ideal for simulating discontinuous materials, such as granular | |
+matter. | |
+The complexity of the computations is kept low by representing the particles as | |
+spheres, which keeps contact-searching algorithms simple. | |
diff --git a/doc/html/_sources/index.txt b/doc/html/_sources/index.txt | |
t@@ -5,11 +5,18 @@ | |
Welcome to sphere's documentation! | |
================================== | |
-This is the official documentation for the *sphere* discrete element modelling… | |
- | |
-*sphere* is developed by Anders Damsgaard Christensen under supervision of Dav… | |
- | |
-Contact: Anders Damsgaard Christensen, `<http://cs.au.dk/~adc>`_, `<[email protected]… | |
+This is the official documentation for the *sphere* discrete element modelling | |
+software. It presents the theory behind the discrete element method (DEM), the | |
+structure of the software source code, and the Python API for handling | |
+simulation setup and data analysis. | |
+ | |
+*sphere* is developed by Anders Damsgaard Christensen under supervision of Dav… | |
+Lunbek Egholm and Jan A. Piotrowski, all of the department of Geoscience, Aarh… | |
+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>`_, | |
+`<[email protected]>`_ | |
Contents: | |
diff --git a/doc/html/_sources/introduction.txt b/doc/html/_sources/introductio… | |
t@@ -1,25 +1,39 @@ | |
Introduction | |
============ | |
-The *sphere*-software is used for three-dimensional discrete element method (D… | |
-The ultimate aim of the *sphere* software is to simulate soft-bedded subglacia… | |
- | |
-The purpose of this documentation is to provide the user with a thorough walk-… | |
+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 computi… | |
+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 purpose of this documentation is to provide the user with a 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. | |
.. note:: Command examples in this document starting with the symbol ``$`` are… | |
-All numerical values in this document, the source code, and the configuration … | |
+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 toolki… | |
+ * 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/inde… | |
* `GNU Make <https://www.gnu.org/software/make/>`_ | |
* `CMake <http://www.cmake.org>`_ | |
* The `GNU Compiler Collection <http://gcc.gnu.org/>`_ (GCC) | |
* The `Nvidia CUDA toolkit and SDK <https://developer.nvidia.com/cuda-downlo… | |
The runtime requirements are: | |
- * A `CUDA-enabled GPU <http://www.nvidia.com/object/cuda_gpus.html>`_ with c… | |
+ * 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: | |
t@@ -38,16 +52,23 @@ Optional tools, required for building the documentation: | |
* `Breathe <http://michaeljones.github.com/breathe/>`_ | |
* `dvipng <http://www.nongnu.org/dvipng/>`_ | |
-`Git <http://git-scm.com>`_ is used as the distributed version control system … | |
+`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 ``… | |
+All instructions required for building *sphere* are provided in a number of | |
+``Makefile``'s. To generate the main *sphere* command-line executable, go to t… | |
+root directory, and invoke CMake and GNU Make:: | |
$ cmake . && make | |
-If successfull, the Makefiles will create the required data folders, object fi… | |
+If successfull, the Makefiles will create the required data folders, object | |
+files, as well as the *sphere* executable in the root folder. Issue the | |
+following commands to check the executable:: | |
$ ./sphere --version | |
t@@ -59,7 +80,10 @@ The build can be verified by running a number of automated … | |
$ make test | |
-The documentation can be read in the `reStructuredText <http://docutils.source… | |
+The documentation can be read in the `reStructuredText | |
+<http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html>`_-format … | |
+the ``doc/sphinx/`` folder, or build into e.g. HTML or PDF format with the | |
+following commands:: | |
$ cd doc/sphinx | |
$ make html | |
t@@ -72,9 +96,13 @@ To see all available output formats, execute:: | |
Work flow | |
--------- | |
-After compiling the *sphere* binary, the procedure of a creating and handling … | |
- * Setup of particle assemblage, physical properties and conditions using the… | |
- * Execution of *sphere* software, which simulates the particle behavior as a… | |
- * Inspection, analysis, interpretation and visualization of *sphere* output … | |
- | |
+After compiling the *sphere* binary, the procedure of a creating and handling a | |
+simulation is typically arranged in the following order: | |
+ * Setup of particle assemblage, physical properties and conditions using the | |
+ Python API. | |
+ * Execution of *sphere* software, which simulates the particle behavior as a | |
+ function of time, as a result of the conditions initially specified in the | |
+ input file. | |
+ * Inspection, analysis, interpretation and visualization of *sphere* output … | |
+ Python, and/or scene rendering using the built-in ray tracer. | |
diff --git a/doc/html/_sources/sphere_internals.txt b/doc/html/_sources/sphere_… | |
t@@ -3,7 +3,7 @@ sphere internals | |
The *sphere* executable has the following options: | |
-.. command-output:: ../../sphere_linux_X86_64 --help | |
+.. command-output:: ../../sphere --help | |
The most common way to invoke *sphere* is however via the Python API (e.g. :py… | |
diff --git a/doc/html/dem.html b/doc/html/dem.html | |
t@@ -57,7 +57,17 @@ | |
<div class="section" id="discrete-element-method"> | |
<h1>Discrete element method<a class="headerlink" href="#discrete-element-metho… | |
-<p>The discrete element method (or distinct element method) was initially form… | |
+<p>The discrete element method (or distinct element method) was initially | |
+formulated by Cundall and Strack (1979). It simulates the physical behavior and | |
+interaction of discrete, unbreakable particles, with their own mass and inerti… | |
+under the influence of e.g. gravity and boundary conditions such as moving | |
+walls. By discretizing time into small time steps, explicit integration of | |
+Newton’s second law of motion is used to predict the new position and ki… | |
+values for each particle from the previous sums of forces. This Lagrangian | |
+approach is ideal for simulating discontinuous materials, such as granular | |
+matter. | |
+The complexity of the computations is kept low by representing the particles as | |
+spheres, which keeps contact-searching algorithms simple.</p> | |
</div> | |
diff --git a/doc/html/genindex.html b/doc/html/genindex.html | |
t@@ -58,6 +58,7 @@ | |
| <a href="#C"><strong>C</strong></a> | |
| <a href="#D"><strong>D</strong></a> | |
| <a href="#E"><strong>E</strong></a> | |
+ | <a href="#F"><strong>F</strong></a> | |
| <a href="#G"><strong>G</strong></a> | |
| <a href="#I"><strong>I</strong></a> | |
| <a href="#P"><strong>P</strong></a> | |
t@@ -87,6 +88,10 @@ | |
<dt><a href="python_api.html#sphere.Spherebin.bond">bond() (sphere.Spherebin… | |
</dt> | |
+ | |
+ <dt><a href="python_api.html#sphere.Spherebin.bondsRose">bondsRose() (sphere… | |
+ </dt> | |
+ | |
</dl></td> | |
<td style="width: 33%" valign="top"><dl> | |
t@@ -107,10 +112,18 @@ | |
<dt><a href="python_api.html#sphere.Spherebin.consolidate">consolidate() (sp… | |
</dt> | |
+ | |
+ <dt><a href="python_api.html#sphere.convert">convert() (in module sphere)</a> | |
+ </dt> | |
+ | |
</dl></td> | |
<td style="width: 33%" valign="top"><dl> | |
- <dt><a href="python_api.html#sphere.convert">convert() (in module sphere)</a> | |
+ <dt><a href="python_api.html#sphere.Spherebin.createBondPair">createBondPair… | |
+ </dt> | |
+ | |
+ | |
+ <dt><a href="python_api.html#sphere.Spherebin.currentDevs">currentDevs() (sp… | |
</dt> | |
</dl></td> | |
t@@ -136,10 +149,32 @@ | |
</dl></td> | |
</tr></table> | |
+<h2 id="F">F</h2> | |
+<table style="width: 100%" class="indextable genindextable"><tr> | |
+ <td style="width: 33%" valign="top"><dl> | |
+ | |
+ <dt><a href="python_api.html#sphere.Spherebin.forcechains">forcechains() (sp… | |
+ </dt> | |
+ | |
+ </dl></td> | |
+ <td style="width: 33%" valign="top"><dl> | |
+ | |
+ <dt><a href="python_api.html#sphere.Spherebin.forcechainsRose">forcechainsRo… | |
+ </dt> | |
+ | |
+ </dl></td> | |
+</tr></table> | |
+ | |
<h2 id="G">G</h2> | |
<table style="width: 100%" class="indextable genindextable"><tr> | |
<td style="width: 33%" valign="top"><dl> | |
+ <dt><a href="python_api.html#sphere.Spherebin.generateBimodalRadii">generate… | |
+ </dt> | |
+ | |
+ </dl></td> | |
+ <td style="width: 33%" valign="top"><dl> | |
+ | |
<dt><a href="python_api.html#sphere.Spherebin.generateRadii">generateRadii()… | |
</dt> | |
t@@ -182,6 +217,12 @@ | |
<table style="width: 100%" class="indextable genindextable"><tr> | |
<td style="width: 33%" valign="top"><dl> | |
+ <dt><a href="python_api.html#sphere.Spherebin.porosities">porosities() (sphe… | |
+ </dt> | |
+ | |
+ </dl></td> | |
+ <td style="width: 33%" valign="top"><dl> | |
+ | |
<dt><a href="python_api.html#sphere.Spherebin.porosity">porosity() (sphere.S… | |
</dt> | |
t@@ -192,9 +233,15 @@ | |
<table style="width: 100%" class="indextable genindextable"><tr> | |
<td style="width: 33%" valign="top"><dl> | |
+ <dt><a href="python_api.html#sphere.Spherebin.random2bonds">random2bonds() (… | |
+ </dt> | |
+ | |
+ | |
<dt><a href="python_api.html#sphere.Spherebin.readbin">readbin() (sphere.Sph… | |
</dt> | |
+ </dl></td> | |
+ <td style="width: 33%" valign="top"><dl> | |
<dt><a href="python_api.html#sphere.render">render() (in module sphere)</a> | |
</dt> | |
t@@ -205,8 +252,6 @@ | |
</dt> | |
</dl></dd> | |
- </dl></td> | |
- <td style="width: 33%" valign="top"><dl> | |
<dt><a href="python_api.html#sphere.run">run() (in module sphere)</a> | |
</dt> | |
t@@ -228,6 +273,10 @@ | |
</dt> | |
+ <dt><a href="python_api.html#sphere.Spherebin.sheardisp">sheardisp() (sphere… | |
+ </dt> | |
+ | |
+ | |
<dt><a href="python_api.html#sphere.Spherebin.shearstrain">shearstrain() (sp… | |
</dt> | |
t@@ -263,10 +312,18 @@ | |
<dt><a href="python_api.html#sphere.thinsectionVideo">thinsectionVideo() (in… | |
</dt> | |
+ | |
+ <dt><a href="python_api.html#sphere.Spherebin.torqueScript">torqueScript() (… | |
+ </dt> | |
+ | |
</dl></td> | |
<td style="width: 33%" valign="top"><dl> | |
- <dt><a href="python_api.html#sphere.Spherebin.torqueScript">torqueScript() (… | |
+ <dt><a href="python_api.html#sphere.torqueScriptParallel3">torqueScriptParal… | |
+ </dt> | |
+ | |
+ | |
+ <dt><a href="python_api.html#sphere.torqueScriptSerial3">torqueScriptSerial3… | |
</dt> | |
</dl></td> | |
diff --git a/doc/html/index.html b/doc/html/index.html | |
t@@ -53,9 +53,16 @@ | |
<div class="section" id="welcome-to-sphere-s-documentation"> | |
<h1>Welcome to sphere’s documentation!<a class="headerlink" href="#welco… | |
-<p>This is the official documentation for the <em>sphere</em> discrete element… | |
-<p><em>sphere</em> is developed by Anders Damsgaard Christensen under supervis… | |
-<p>Contact: Anders Damsgaard Christensen, <a class="reference external" href="… | |
+<p>This is the official documentation for the <em>sphere</em> discrete element… | |
+software. It presents the theory behind the discrete element method (DEM), the | |
+structure of the software source code, and the Python API for handling | |
+simulation setup and data analysis.</p> | |
+<p><em>sphere</em> is developed by Anders Damsgaard Christensen under supervis… | |
+Lunbek Egholm and Jan A. Piotrowski, all of the department of Geoscience, Aarh… | |
+University, Denmark. This document is a work in progress, and is still in an | |
+early state.</p> | |
+<p>Contact: Anders Damsgaard Christensen, <a class="reference external" href="… | |
+<a class="reference external" href="mailto:anders.damsgaard%40… | |
<p>Contents:</p> | |
<div class="toctree-wrapper compound"> | |
<ul> | |
diff --git a/doc/html/introduction.html b/doc/html/introduction.html | |
t@@ -57,20 +57,32 @@ | |
<div class="section" id="introduction"> | |
<h1>Introduction<a class="headerlink" href="#introduction" title="Permalink to… | |
-<p>The <em>sphere</em>-software is used for three-dimensional discrete element… | |
-The ultimate aim of the <em>sphere</em> software is to simulate soft-bedded su… | |
-<p>The purpose of this documentation is to provide the user with a thorough wa… | |
+<p>The <em>sphere</em>-software is used for three-dimensional discrete element… | |
+(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 c… | |
+architecture, CUDA. Simulation setup and data analysis is performed with the | |
+included Python API.</p> | |
+<p>The ultimate aim of the <em>sphere</em> software is to simulate soft-bedded… | |
+conditions, while retaining the flexibility to perform simulations of granular | |
+material in other environments.</p> | |
+<p>The purpose of this documentation is to provide the user with a walk-throug… | |
+the installation, work-flow, data-analysis and visualization methods of | |
+<em>sphere</em>. In addition, the <em>sphere</em> internals are exposed to pro… | |
+understanding of the discrete element method numerical routines taking place.<… | |
<div class="admonition note"> | |
<p class="first admonition-title">Note</p> | |
<p class="last">Command examples in this document starting with the symbol <tt… | |
</div> | |
-<p>All numerical values in this document, the source code, and the configurati… | |
+<p>All numerical values in this document, the source code, and the configurati… | |
+files are typeset with strict respect to the SI unit system.</p> | |
<div class="section" id="requirements"> | |
<h2>Requirements<a class="headerlink" href="#requirements" title="Permalink to… | |
<dl class="docutils"> | |
<dt>The build requirements are:</dt> | |
<dd><ul class="first last simple"> | |
-<li>A Nvidia CUDA-supported version of Linux or Mac OS X (see the <a class="re… | |
+<li>A Nvidia CUDA-supported version of Linux or Mac OS X (see the <a class="re… | |
+release notes</a> for more information)</li> | |
<li><a class="reference external" href="https://www.gnu.org/software/make/">GN… | |
<li><a class="reference external" href="http://www.cmake.org">CMake</a></li> | |
<li>The <a class="reference external" href="http://gcc.gnu.org/">GNU Compiler … | |
t@@ -79,7 +91,8 @@ The ultimate aim of the <em>sphere</em> software is to simul… | |
</dd> | |
<dt>The runtime requirements are:</dt> | |
<dd><ul class="first last simple"> | |
-<li>A <a class="reference external" href="http://www.nvidia.com/object/cuda_gp… | |
+<li>A <a class="reference external" href="http://www.nvidia.com/object/cuda_gp… | |
+compute capability 1.1 or greater.</li> | |
<li>A Nvidia CUDA-enabled GPU and device driver</li> | |
</ul> | |
</dd> | |
t@@ -104,14 +117,20 @@ The ultimate aim of the <em>sphere</em> software is to s… | |
</ul> | |
</dd> | |
</dl> | |
-<p><a class="reference external" href="http://git-scm.com">Git</a> is used as … | |
+<p><a class="reference external" href="http://git-scm.com">Git</a> is used as … | |
+platform, and the source code is maintained at <a class="reference external" h… | |
+Public License, v.3</a>.</p> | |
</div> | |
<div class="section" id="building-sphere"> | |
<h2>Building <em>sphere</em><a class="headerlink" href="#building-sphere" titl… | |
-<p>All instructions required for building <em>sphere</em> are provided in a nu… | |
+<p>All instructions required for building <em>sphere</em> are provided in a nu… | |
+<tt class="docutils literal"><span class="pre">Makefile</span></tt>‘s. T… | |
+root directory, and invoke CMake and GNU Make:</p> | |
<div class="highlight-python"><pre>$ cmake . && make</pre> | |
</div> | |
-<p>If successfull, the Makefiles will create the required data folders, object… | |
+<p>If successfull, the Makefiles will create the required data folders, object | |
+files, as well as the <em>sphere</em> executable in the root folder. Issue the | |
+following commands to check the executable:</p> | |
<div class="highlight-python"><pre>$ ./sphere --version</pre> | |
</div> | |
<p>The output should look similar to this:</p> | |
t@@ -132,7 +151,9 @@ The ultimate aim of the <em>sphere</em> software is to sim… | |
<p>The build can be verified by running a number of automated tests:</p> | |
<div class="highlight-python"><pre>$ make test</pre> | |
</div> | |
-<p>The documentation can be read in the <a class="reference external" href="ht… | |
+<p>The documentation can be read in the <a class="reference external" href="ht… | |
+the <tt class="docutils literal"><span class="pre">doc/sphinx/</span></tt> fol… | |
+following commands:</p> | |
<div class="highlight-python"><pre>$ cd doc/sphinx | |
$ make html | |
$ make latexpdf</pre> | |
t@@ -143,15 +164,19 @@ $ make latexpdf</pre> | |
</div> | |
<div class="section" id="work-flow"> | |
<h2>Work flow<a class="headerlink" href="#work-flow" title="Permalink to this … | |
-<dl class="docutils"> | |
-<dt>After compiling the <em>sphere</em> binary, the procedure of a creating an… | |
-<dd><ul class="first last simple"> | |
-<li>Setup of particle assemblage, physical properties and conditions using the… | |
-<li>Execution of <em>sphere</em> software, which simulates the particle behavi… | |
-<li>Inspection, analysis, interpretation and visualization of <em>sphere</em> … | |
+<p>After compiling the <em>sphere</em> binary, the procedure of a creating and… | |
+simulation is typically arranged in the following order:</p> | |
+<blockquote> | |
+<div><ul class="simple"> | |
+<li>Setup of particle assemblage, physical properties and conditions using the | |
+Python API.</li> | |
+<li>Execution of <em>sphere</em> software, which simulates the particle behavi… | |
+function of time, as a result of the conditions initially specified in the | |
+input file.</li> | |
+<li>Inspection, analysis, interpretation and visualization of <em>sphere</em> … | |
+Python, and/or scene rendering using the built-in ray tracer.</li> | |
</ul> | |
-</dd> | |
-</dl> | |
+</div></blockquote> | |
</div> | |
</div> | |
diff --git a/doc/html/objects.inv b/doc/html/objects.inv | |
Binary files differ. | |
diff --git a/doc/html/python_api.html b/doc/html/python_api.html | |
t@@ -76,6 +76,12 @@ setup and data analysis.</p> | |
</dd></dl> | |
<dl class="method"> | |
+<dt id="sphere.Spherebin.bondsRose"> | |
+<tt class="descname">bondsRose</tt><big>(</big><em>imgformat='pdf'</em><big>)<… | |
+<dd><p>Visualize strike- and dip angles of the bond pairs in a rose plot.</p> | |
+</dd></dl> | |
+ | |
+<dl class="method"> | |
<dt id="sphere.Spherebin.bulkPorosity"> | |
<tt class="descname">bulkPorosity</tt><big>(</big><big>)</big><a class="header… | |
<dd><p>Calculate and return the bulk porosity</p> | |
t@@ -84,13 +90,29 @@ setup and data analysis.</p> | |
<dl class="method"> | |
<dt id="sphere.Spherebin.consolidate"> | |
<tt class="descname">consolidate</tt><big>(</big><em>deviatoric_stress=10000.0… | |
-<dd><p>Setup consolidation experiment. Specify the upper wall | |
+<dd><p>Setup consolidation experiment. Specify the upper wall | |
deviatoric stress in Pascal, default value is 10 kPa.</p> | |
</dd></dl> | |
<dl class="method"> | |
+<dt id="sphere.Spherebin.createBondPair"> | |
+<tt class="descname">createBondPair</tt><big>(</big><em>i</em>, <em>j</em>, <e… | |
+<dd><p>Bond particles i and j. Particle j is moved adjacent to particle i, | |
+and oriented randomly. | |
+@param spacing (float) The inter-particle distance prescribed. Positive | |
+values result in a inter-particle distance, negative equal an overlap. | |
+The value is relative to the sum of the two radii.</p> | |
+</dd></dl> | |
+ | |
+<dl class="method"> | |
+<dt id="sphere.Spherebin.currentDevs"> | |
+<tt class="descname">currentDevs</tt><big>(</big><big>)</big><a class="headerl… | |
+<dd><p>Return current magnitude of the deviatoric normal stress</p> | |
+</dd></dl> | |
+ | |
+<dl class="method"> | |
<dt id="sphere.Spherebin.defaultParams"> | |
-<tt class="descname">defaultParams</tt><big>(</big><em>mu_s=0.4</em>, <em>mu_d… | |
+<tt class="descname">defaultParams</tt><big>(</big><em>mu_s=0.4</em>, <em>mu_d… | |
<dd><p>Initialize particle parameters to default values. | |
Radii must be set prior to calling this function.</p> | |
</dd></dl> | |
t@@ -102,6 +124,38 @@ Radii must be set prior to calling this function.</p> | |
</dd></dl> | |
<dl class="method"> | |
+<dt id="sphere.Spherebin.forcechains"> | |
+<tt class="descname">forcechains</tt><big>(</big><em>lc=200.0</em>, <em>uc=650… | |
+<dd><p>Visualizes the force chains in the system from the magnitude of the | |
+normal contact forces, and produces an image of them. | |
+@param lc: Lower cutoff of contact forces. Contacts below are not | |
+visualized (float) | |
+@param uc: Upper cutoff of contact forces. Contacts above are | |
+visualized with this value (float) | |
+@param outformat: Format of output image. Possible values are | |
+‘interactive’, ‘png’, ‘epslatex’, ‘e… | |
+@param disp: Display forcechains in ‘2d’ or ‘3d’ | |
+Warning: Will segfault if no contacts are found.</p> | |
+</dd></dl> | |
+ | |
+<dl class="method"> | |
+<dt id="sphere.Spherebin.forcechainsRose"> | |
+<tt class="descname">forcechainsRose</tt><big>(</big><em>lower_limit=0.25</em>… | |
+<dd><p>Visualize strike- and dip angles of the strongest force chains in a | |
+rose plot.</p> | |
+</dd></dl> | |
+ | |
+<dl class="method"> | |
+<dt id="sphere.Spherebin.generateBimodalRadii"> | |
+<tt class="descname">generateBimodalRadii</tt><big>(</big><em>r_small=0.005</e… | |
+<dd><p>Draw radii from two sizes | |
+@param r_small: Radii of small population (float), in ]0;r_large[ | |
+@param r_large: Radii of large population (float), in ]r_small;inf[ | |
+@param ratio: Approximate volumetric ratio between the two | |
+populations (large/small).</p> | |
+</dd></dl> | |
+ | |
+<dl class="method"> | |
<dt id="sphere.Spherebin.generateRadii"> | |
<tt class="descname">generateRadii</tt><big>(</big><em>psd='logn'</em>, <em>ra… | |
<dd><p>Draw random particle radii from the selected probability distribution. | |
t@@ -158,6 +212,12 @@ prior to these.</p> | |
</dd></dl> | |
<dl class="method"> | |
+<dt id="sphere.Spherebin.porosities"> | |
+<tt class="descname">porosities</tt><big>(</big><em>outformat='pdf'</em>, <em>… | |
+<dd><p>Plot porosities with depth</p> | |
+</dd></dl> | |
+ | |
+<dl class="method"> | |
<dt id="sphere.Spherebin.porosity"> | |
<tt class="descname">porosity</tt><big>(</big><em>slices=10</em>, <em>verbose=… | |
<dd><p>Calculate the porosity as a function of depth, by averaging values | |
t@@ -166,8 +226,20 @@ Returns porosity values and depth</p> | |
</dd></dl> | |
<dl class="method"> | |
+<dt id="sphere.Spherebin.random2bonds"> | |
+<tt class="descname">random2bonds</tt><big>(</big><em>ratio=0.3</em>, <em>spac… | |
+<dd><p>Bond an amount of particles in two-particle clusters | |
+@param ratio: The amount of particles to bond, values in ]0.0;1.0] (float) | |
+@param spacing: The distance relative to the sum of radii between bonded | |
+particles, neg. values denote an overlap. Values in ]0.0,inf[ (float). | |
+The particles should be initialized beforehand. | |
+Note: The actual number of bonds is likely to be somewhat smaller than | |
+specified, due to the random selection algorithm.</p> | |
+</dd></dl> | |
+ | |
+<dl class="method"> | |
<dt id="sphere.Spherebin.readbin"> | |
-<tt class="descname">readbin</tt><big>(</big><em>targetbin</em>, <em>verbose=T… | |
+<tt class="descname">readbin</tt><big>(</big><em>targetbin</em>, <em>verbose=T… | |
<dd><p>Reads a target SPHERE binary file</p> | |
</dd></dl> | |
t@@ -186,16 +258,22 @@ Returns porosity values and depth</p> | |
<dl class="method"> | |
<dt id="sphere.Spherebin.shear"> | |
<tt class="descname">shear</tt><big>(</big><em>shear_strain_rate=1</em>, <em>p… | |
-<dd><p>Setup shear experiment. Specify the upper wall | |
+<dd><p>Setup shear experiment. Specify the upper wall | |
deviatoric stress in Pascal, default value is 10 kPa. | |
The shear strain rate is the shear length divided by the | |
initial height per second.</p> | |
</dd></dl> | |
<dl class="method"> | |
+<dt id="sphere.Spherebin.sheardisp"> | |
+<tt class="descname">sheardisp</tt><big>(</big><em>outformat='pdf'</em>, <em>z… | |
+<dd><p>Show particle x-displacement vs. the z-pos</p> | |
+</dd></dl> | |
+ | |
+<dl class="method"> | |
<dt id="sphere.Spherebin.shearstrain"> | |
<tt class="descname">shearstrain</tt><big>(</big><big>)</big><a class="headerl… | |
-<dd><p>Calculates and returns the shear strain (gamma) value of the experiment… | |
+<dd><p>Calculates and returns the current shear strain (gamma) value of the ex… | |
</dd></dl> | |
<dl class="method"> | |
t@@ -220,14 +298,14 @@ gnuplot> plot ‘<sid>-ts-x1x3.txt’ w… | |
<dl class="method"> | |
<dt id="sphere.Spherebin.torqueScript"> | |
-<tt class="descname">torqueScript</tt><big>(</big><em>email='adc@geo.au.dk… | |
+<tt class="descname">torqueScript</tt><big>(</big><em>email='adc@geo.au.dk… | |
<dd><p>Create job script for the Torque queue manager for the binary</p> | |
</dd></dl> | |
<dl class="method"> | |
<dt id="sphere.Spherebin.uniaxialStrainRate"> | |
<tt class="descname">uniaxialStrainRate</tt><big>(</big><em>wvel=-0.001</em>, … | |
-<dd><p>Setup consolidation experiment. Specify the upper wall | |
+<dd><p>Setup consolidation experiment. Specify the upper wall | |
velocity in m/s, default value is -0.001 m/s (i.e. downwards).</p> | |
</dd></dl> | |
t@@ -296,6 +374,20 @@ This function will start off by rendering the images.</p> | |
</dd></dl> | |
<dl class="function"> | |
+<dt id="sphere.torqueScriptParallel3"> | |
+<tt class="descclassname">sphere.</tt><tt class="descname">torqueScriptParalle… | |
+<dd><p>Create job script for the Torque queue manager for three binaries, | |
+executed in parallel. | |
+Returns the filename of the script</p> | |
+</dd></dl> | |
+ | |
+<dl class="function"> | |
+<dt id="sphere.torqueScriptSerial3"> | |
+<tt class="descclassname">sphere.</tt><tt class="descname">torqueScriptSerial3… | |
+<dd><p>Create job script for the Torque queue manager for three binaries</p> | |
+</dd></dl> | |
+ | |
+<dl class="function"> | |
<dt id="sphere.video"> | |
<tt class="descclassname">sphere.</tt><tt class="descname">video</tt><big>(</b… | |
<dd><p>Use ffmpeg to combine images to animation. All images should be rendere… | |
diff --git a/doc/html/searchindex.js b/doc/html/searchindex.js | |
t@@ -1 +1 @@ | |
-Search.setIndex({objects:{"":{sphere:[4,0,1,""]},sphere:{status:[4,2,1,""],con… | |
-\ No newline at end of file | |
+Search.setIndex({objects:{"":{sphere:[4,0,1,""]},sphere:{status:[4,2,1,""],tor… | |
+\ No newline at end of file | |
diff --git a/doc/html/sphere_internals.html b/doc/html/sphere_internals.html | |
t@@ -54,9 +54,26 @@ | |
<div class="section" id="sphere-internals"> | |
<h1>sphere internals<a class="headerlink" href="#sphere-internals" title="Perm… | |
<p>The <em>sphere</em> executable has the following options:</p> | |
-<div class="system-message"> | |
-<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">… | |
-Command u’../../sphere_linux_X86_64 –help’ failed: [Errno 2]… | |
+<div class="highlight-text"><div class="highlight"><pre>$ ../../sphere --help | |
+../../sphere: particle dynamics simulator | |
+Usage: ../../sphere [OPTION[S]]... [FILE1 ...] | |
+Options: | |
+-h, --help print help | |
+-V, --version print version information and exit | |
+-q, --quiet suppress status messages to stdout | |
+-n, --dry show key experiment parameters and quit | |
+-r, --render render input files instead of simulating temporal … | |
+-dc, --dont-check don't check values before running | |
+ | |
+Raytracer (-r) specific options: | |
+-m <method> <maxval> [-l <lower cutoff val>], or | |
+--method <method> <maxval> [-l <lower cutoff val>] | |
+ color visualization method, possible values: | |
+ normal, pres, vel, angvel, xdisp, angpos | |
+ 'normal' is the default mode | |
+ if -l is appended, don't render particles with value below | |
+</pre></div> | |
+</div> | |
<p>The most common way to invoke <em>sphere</em> is however via the Python API… | |
<p>subsection{The <em>sphere</em> algorithm} | |
label{subsec:spherealgo} | |
t@@ -334,8 +351,8 @@ An important note is that the texttt{C} examples of the NV… | |
<div><p></p> | |
<p></p> | |
</div></blockquote> | |
-<p id=""><span id="project0classDEM_1a0cb0fcf60594f664a9e593917c623767"></span… | |
-<div class="line">void <strong>forcechains</strong>(const std::string format =… | |
+<p id=""><span id="project0classDEM_1ad94250277dec22f68e096bbf149ff0a8"></span… | |
+<div class="line">void <strong>forcechains</strong>(const std::string format =… | |
</div> | |
</p> | |
<blockquote> | |
diff --git a/doc/pdf/sphere.pdf b/doc/pdf/sphere.pdf | |
Binary files differ. | |
diff --git a/doc/sphinx/dem.rst b/doc/sphinx/dem.rst | |
t@@ -1,6 +1,16 @@ | |
Discrete element method | |
======================= | |
-The discrete element method (or distinct element method) was initially formula… | |
+The discrete element method (or distinct element method) was initially | |
+formulated by Cundall and Strack (1979). It simulates the physical behavior and | |
+interaction of discrete, unbreakable particles, with their own mass and inerti… | |
+under the influence of e.g. gravity and boundary conditions such as moving | |
+walls. By discretizing time into small time steps, explicit integration of | |
+Newton's second law of motion is used to predict the new position and kinematic | |
+values for each particle from the previous sums of forces. This Lagrangian | |
+approach is ideal for simulating discontinuous materials, such as granular | |
+matter. | |
+The complexity of the computations is kept low by representing the particles as | |
+spheres, which keeps contact-searching algorithms simple. | |
diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst | |
t@@ -5,11 +5,18 @@ | |
Welcome to sphere's documentation! | |
================================== | |
-This is the official documentation for the *sphere* discrete element modelling… | |
- | |
-*sphere* is developed by Anders Damsgaard Christensen under supervision of Dav… | |
- | |
-Contact: Anders Damsgaard Christensen, `<http://cs.au.dk/~adc>`_, `<[email protected]… | |
+This is the official documentation for the *sphere* discrete element modelling | |
+software. It presents the theory behind the discrete element method (DEM), the | |
+structure of the software source code, and the Python API for handling | |
+simulation setup and data analysis. | |
+ | |
+*sphere* is developed by Anders Damsgaard Christensen under supervision of Dav… | |
+Lunbek Egholm and Jan A. Piotrowski, all of the department of Geoscience, Aarh… | |
+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>`_, | |
+`<[email protected]>`_ | |
Contents: | |
diff --git a/doc/sphinx/introduction.rst b/doc/sphinx/introduction.rst | |
t@@ -1,25 +1,39 @@ | |
Introduction | |
============ | |
-The *sphere*-software is used for three-dimensional discrete element method (D… | |
-The ultimate aim of the *sphere* software is to simulate soft-bedded subglacia… | |
- | |
-The purpose of this documentation is to provide the user with a thorough walk-… | |
+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 computi… | |
+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 purpose of this documentation is to provide the user with a 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. | |
.. note:: Command examples in this document starting with the symbol ``$`` are… | |
-All numerical values in this document, the source code, and the configuration … | |
+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 toolki… | |
+ * 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/inde… | |
* `GNU Make <https://www.gnu.org/software/make/>`_ | |
* `CMake <http://www.cmake.org>`_ | |
* The `GNU Compiler Collection <http://gcc.gnu.org/>`_ (GCC) | |
* The `Nvidia CUDA toolkit and SDK <https://developer.nvidia.com/cuda-downlo… | |
The runtime requirements are: | |
- * A `CUDA-enabled GPU <http://www.nvidia.com/object/cuda_gpus.html>`_ with c… | |
+ * 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: | |
t@@ -38,16 +52,23 @@ Optional tools, required for building the documentation: | |
* `Breathe <http://michaeljones.github.com/breathe/>`_ | |
* `dvipng <http://www.nongnu.org/dvipng/>`_ | |
-`Git <http://git-scm.com>`_ is used as the distributed version control system … | |
+`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 ``… | |
+All instructions required for building *sphere* are provided in a number of | |
+``Makefile``'s. To generate the main *sphere* command-line executable, go to t… | |
+root directory, and invoke CMake and GNU Make:: | |
$ cmake . && make | |
-If successfull, the Makefiles will create the required data folders, object fi… | |
+If successfull, the Makefiles will create the required data folders, object | |
+files, as well as the *sphere* executable in the root folder. Issue the | |
+following commands to check the executable:: | |
$ ./sphere --version | |
t@@ -59,7 +80,10 @@ The build can be verified by running a number of automated … | |
$ make test | |
-The documentation can be read in the `reStructuredText <http://docutils.source… | |
+The documentation can be read in the `reStructuredText | |
+<http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html>`_-format … | |
+the ``doc/sphinx/`` folder, or build into e.g. HTML or PDF format with the | |
+following commands:: | |
$ cd doc/sphinx | |
$ make html | |
t@@ -72,9 +96,13 @@ To see all available output formats, execute:: | |
Work flow | |
--------- | |
-After compiling the *sphere* binary, the procedure of a creating and handling … | |
- * Setup of particle assemblage, physical properties and conditions using the… | |
- * Execution of *sphere* software, which simulates the particle behavior as a… | |
- * Inspection, analysis, interpretation and visualization of *sphere* output … | |
- | |
+After compiling the *sphere* binary, the procedure of a creating and handling a | |
+simulation is typically arranged in the following order: | |
+ * Setup of particle assemblage, physical properties and conditions using the | |
+ Python API. | |
+ * Execution of *sphere* software, which simulates the particle behavior as a | |
+ function of time, as a result of the conditions initially specified in the | |
+ input file. | |
+ * Inspection, analysis, interpretation and visualization of *sphere* output … | |
+ Python, and/or scene rendering using the built-in ray tracer. | |
diff --git a/doc/sphinx/sphere_internals.rst b/doc/sphinx/sphere_internals.rst | |
t@@ -3,7 +3,7 @@ sphere internals | |
The *sphere* executable has the following options: | |
-.. command-output:: ../../sphere_linux_X86_64 --help | |
+.. command-output:: ../../sphere --help | |
The most common way to invoke *sphere* is however via the Python API (e.g. :py… | |
diff --git a/python/darcy.py b/python/darcy.py | |
t@@ -9,7 +9,7 @@ initialization = True | |
consolidation = True | |
#shearing = True | |
rendering = False | |
-#plots = False | |
+plots = True | |
diff --git a/tests/io_tests.py b/tests/io_tests.py | |
t@@ -5,13 +5,13 @@ from pytestutils import * | |
print("### Input/output tests ###") | |
# Generate data in python | |
-orig = Spherebin(np = 100, nw = 1, sid = "test-initgrid") | |
-orig.generateRadii(histogram = False) | |
+orig = Spherebin(np=100, nw=1, sid="test-initgrid") | |
+orig.generateRadii(histogram=False) | |
orig.defaultParams() | |
-orig.initRandomGridPos(g = numpy.zeros(orig.nd)) | |
-orig.initTemporal(current = 0.0, total = 0.0) | |
-orig.time_total = 2.0*orig.time_dt; | |
-orig.time_file_dt = orig.time_dt; | |
+orig.initRandomGridPos(g=numpy.zeros(orig.nd)) | |
+orig.initTemporal(current=0.0, total=0.0) | |
+orig.time_total=2.0*orig.time_dt | |
+orig.time_file_dt = orig.time_dt | |
orig.writebin(verbose=False) | |
# Test Python IO routines | |
t@@ -20,7 +20,8 @@ py.readbin("../input/" + orig.sid + ".bin", verbose=False) | |
compare(orig, py, "Python IO:") | |
# Test C++ IO routines | |
-orig.run(verbose=False, hideinputfile=True) | |
+#orig.run(verbose=False, hideinputfile=True) | |
+orig.run(verbose=True, hideinputfile=True) | |
cpp = Spherebin() | |
cpp.readbin("../output/" + orig.sid + ".output00000.bin", verbose=False) | |
compare(orig, cpp, "C++ IO: ") | |
t@@ -34,6 +35,3 @@ compare(orig, cuda, "CUDA IO: ") | |
# Remove temporary files | |
cleanup(orig) | |
- | |
- | |
- |