sphere_internals.html - sphere - GPU-based 3D discrete element method algorithm with optional fluid coupling
HTML git clone git://src.adamsgaard.dk/sphere
DIR Log
DIR Files
DIR Refs
DIR LICENSE
---
sphere_internals.html (11624B)
---
1 <!DOCTYPE html>
2
3 <html lang="en" data-content_root="./">
4 <head>
5 <meta charset="utf-8" />
6 <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
7
8 <title>Sphere internals — sphere 2.15 documentation</title>
9 <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=03e43079" />
10 <link rel="stylesheet" type="text/css" href="_static/classic.css?v=2bf1fcf8" />
11
12 <script src="_static/documentation_options.js?v=d19175c4"></script>
13 <script src="_static/doctools.js?v=fd6eb6e6"></script>
14 <script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
15
16 <link rel="index" title="Index" href="genindex.html" />
17 <link rel="search" title="Search" href="search.html" />
18 <link rel="prev" title="Python API" href="python_api.html" />
19 </head><body>
20 <div class="related" role="navigation" aria-label="Related">
21 <h3>Navigation</h3>
22 <ul>
23 <li class="right" style="margin-right: 10px">
24 <a href="genindex.html" title="General Index"
25 accesskey="I">index</a></li>
26 <li class="right" >
27 <a href="py-modindex.html" title="Python Module Index"
28 >modules</a> |</li>
29 <li class="right" >
30 <a href="python_api.html" title="Python API"
31 accesskey="P">previous</a> |</li>
32 <li class="nav-item nav-item-0"><a href="index.html">sphere 2.15 documentation</a> »</li>
33 <li class="nav-item nav-item-this"><a href="">Sphere internals</a></li>
34 </ul>
35 </div>
36
37 <div class="document">
38 <div class="documentwrapper">
39 <div class="bodywrapper">
40 <div class="body" role="main">
41
42 <section id="sphere-internals">
43 <h1>Sphere internals<a class="headerlink" href="#sphere-internals" title="Link to this heading">¶</a></h1>
44 <section id="command-line-interface">
45 <h2>Command-line interface<a class="headerlink" href="#command-line-interface" title="Link to this heading">¶</a></h2>
46 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ ../../sphere --help
47 ../../sphere: particle dynamics simulator
48 Usage: ../../sphere [OPTION[S]]... [FILE1 ...]
49 Options:
50 -h, --help print help
51 -V, --version print version information and exit
52 -q, --quiet suppress status messages to stdout
53 -d <device> execute on device with specified id
54 -n, --dry show key experiment parameters and quit
55 -f, --fluid simulate fluid between particles
56 -r, --render render input files to images instead of
57 simulating the temporal evolution
58 -dc, --dont-check don't check values before running
59
60 Raytracer (-r) specific options:
61 -m <method> <maxval> [-l <lower cutoff val>], or
62 --method <method> <maxval> [-l <lower cutoff val>]
63 color visualization method, possible values:
64 normal, pres, vel, angvel, xdisp, angpos
65 'normal' is the default mode
66 if -l is appended, don't render particles with value below
67 -c, --contacts Print a list of particle-particle contacts
68 </pre></div>
69 </div>
70 <p>The most common way to invoke <code class="docutils literal notranslate"><span class="pre">sphere</span></code> is through the Python API, for example
71 with <a class="reference internal" href="python_api.html#sphere.sim.run" title="sphere.sim.run"><code class="xref py py-meth docutils literal notranslate"><span class="pre">sphere.sim.run()</span></code></a> or <a class="reference internal" href="python_api.html#sphere.sim.render" title="sphere.sim.render"><code class="xref py py-meth docutils literal notranslate"><span class="pre">sphere.sim.render()</span></code></a>.</p>
72 </section>
73 <section id="execution-pipeline">
74 <h2>Execution pipeline<a class="headerlink" href="#execution-pipeline" title="Link to this heading">¶</a></h2>
75 <p>The usual execution path is:</p>
76 <ol class="arabic simple">
77 <li><p>Parse command-line options in <code class="docutils literal notranslate"><span class="pre">main.cpp</span></code>.</p></li>
78 <li><p>Read the binary input file into a <code class="docutils literal notranslate"><span class="pre">DEM</span></code> object.</p></li>
79 <li><p>Validate parameters unless <code class="docutils literal notranslate"><span class="pre">--dont-check</span></code> or render mode is selected.</p></li>
80 <li><p>Initialize the selected backend and transfer or copy simulation state into
81 the backend arrays.</p></li>
82 <li><p>Repeatedly sort particles into grid cells, resolve contacts, optionally run
83 the fluid solver, integrate particle and wall motion, and write output files
84 at the configured interval.</p></li>
85 <li><p>Free backend and host memory before returning to the caller.</p></li>
86 </ol>
87 </section>
88 <section id="numerical-algorithm">
89 <h2>Numerical algorithm<a class="headerlink" href="#numerical-algorithm" title="Link to this heading">¶</a></h2>
90 <p>Each simulation step uses the current particle positions to rebuild the grid
91 cell index, sorts particles by cell, identifies neighbor contacts, evaluates
92 contact and body forces, and integrates translational and rotational degrees of
93 freedom. If a coupled fluid solver is enabled, the fluid state and
94 particle-fluid interaction forces are updated as part of the loop.</p>
95 <p>The length of the computational time step, <code class="docutils literal notranslate"><span class="pre">time.dt</span></code>, is calculated from the
96 particle mass and elastic stiffnesses:</p>
97 <div class="math">
98 <p><span class="math">\Delta t = 0.075 \min \left( m / \max(k_n, k_t) \right)</span></p>
99 </div><p>where <img class="math" src="_images/math/e9bc7da808d33a16a8347f27a519bd067186aa66.png" alt="m"/> is the particle mass, and <img class="math" src="_images/math/c713414d12f194f3fab98645df441d23d54164ec.png" alt="k_n"/> and <span class="math">k_t</span> are the
100 normal and tangential elastic stiffnesses. The relationship resolves elastic
101 waves several times while they travel through the smallest particle.</p>
102 </section>
103 <section id="memory-layout">
104 <h2>Memory layout<a class="headerlink" href="#memory-layout" title="Link to this heading">¶</a></h2>
105 <p>Host arrays store input/output state and backend arrays use the <code class="docutils literal notranslate"><span class="pre">dev_</span></code> prefix
106 for the working state used by kernels or emulated kernels. Constant simulation
107 parameters use the <code class="docutils literal notranslate"><span class="pre">devC_</span></code> prefix.</p>
108 <p>The internal floating-point precision is defined in <code class="docutils literal notranslate"><span class="pre">datatypes.h</span></code>. Depending
109 on the build it can be either single precision or double precision. Input and
110 output data files are written in double precision and converted when necessary.</p>
111 <p>Three-dimensional variables such as spatial vectors are stored as <code class="docutils literal notranslate"><span class="pre">Float4</span></code>
112 arrays in backend memory to preserve the memory layout expected by both backend
113 implementations.</p>
114 </section>
115 <section id="performance">
116 <h2>Performance<a class="headerlink" href="#performance" title="Link to this heading">¶</a></h2>
117 <p>Runtime depends on the number of particles, contact density, selected backend,
118 thread or GPU configuration, output interval, and whether the fluid solver or
119 raytracer is enabled. Use release builds and tune <code class="docutils literal notranslate"><span class="pre">OMP_NUM_THREADS</span></code> when using
120 the OpenMP CPU backend.</p>
121 </section>
122 <section id="compilation">
123 <h2>Compilation<a class="headerlink" href="#compilation" title="Link to this heading">¶</a></h2>
124 <p>The project is built from the repository root with CMake. The default build uses
125 the CUDA backend. Pass <code class="docutils literal notranslate"><span class="pre">-DSPHERE_GPU=OFF</span></code> to build the OpenMP CPU backend. See
126 <a class="reference internal" href="quickstart.html"><span class="doc">Quick start</span></a> for current requirements and build commands.</p>
127 </section>
128 <section id="c-reference">
129 <h2>C++ reference<a class="headerlink" href="#c-reference" title="Link to this heading">¶</a></h2>
130 <dl class="cpp class">
131 <dt class="sig sig-object cpp" id="_CPPv43DEM">
132 <span id="_CPPv33DEM"></span><span id="_CPPv23DEM"></span><span id="DEM"></span><span class="target" id="classDEM"></span><span class="k"><span class="pre">class</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">DEM</span></span></span><a class="headerlink" href="#_CPPv43DEM" title="Link to this definition">¶</a><br /></dt>
133 <dd></dd></dl>
134
135 </section>
136 </section>
137
138
139 <div class="clearer"></div>
140 </div>
141 </div>
142 </div>
143 <div class="sphinxsidebar" role="navigation" aria-label="Main">
144 <div class="sphinxsidebarwrapper">
145 <div>
146 <h3><a href="index.html">Table of Contents</a></h3>
147 <ul>
148 <li><a class="reference internal" href="#">Sphere internals</a><ul>
149 <li><a class="reference internal" href="#command-line-interface">Command-line interface</a></li>
150 <li><a class="reference internal" href="#execution-pipeline">Execution pipeline</a></li>
151 <li><a class="reference internal" href="#numerical-algorithm">Numerical algorithm</a></li>
152 <li><a class="reference internal" href="#memory-layout">Memory layout</a></li>
153 <li><a class="reference internal" href="#performance">Performance</a></li>
154 <li><a class="reference internal" href="#compilation">Compilation</a></li>
155 <li><a class="reference internal" href="#c-reference">C++ reference</a><ul>
156 <li><a class="reference internal" href="#_CPPv43DEM"><code class="docutils literal notranslate"><span class="pre">DEM</span></code></a></li>
157 </ul>
158 </li>
159 </ul>
160 </li>
161 </ul>
162
163 </div>
164 <div>
165 <h4>Previous topic</h4>
166 <p class="topless"><a href="python_api.html"
167 title="previous chapter">Python API</a></p>
168 </div>
169 <div role="note" aria-label="source link">
170 <h3>This Page</h3>
171 <ul class="this-page-menu">
172 <li><a href="_sources/sphere_internals.rst.txt"
173 rel="nofollow">Show Source</a></li>
174 </ul>
175 </div>
176 <search id="searchbox" style="display: none" role="search">
177 <h3 id="searchlabel">Quick search</h3>
178 <div class="searchformwrapper">
179 <form class="search" action="search.html" method="get">
180 <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
181 <input type="submit" value="Go" />
182 </form>
183 </div>
184 </search>
185 <script>document.getElementById('searchbox').style.display = "block"</script>
186 </div>
187 </div>
188 <div class="clearer"></div>
189 </div>
190 <div class="related" role="navigation" aria-label="Related">
191 <h3>Navigation</h3>
192 <ul>
193 <li class="right" style="margin-right: 10px">
194 <a href="genindex.html" title="General Index"
195 >index</a></li>
196 <li class="right" >
197 <a href="py-modindex.html" title="Python Module Index"
198 >modules</a> |</li>
199 <li class="right" >
200 <a href="python_api.html" title="Python API"
201 >previous</a> |</li>
202 <li class="nav-item nav-item-0"><a href="index.html">sphere 2.15 documentation</a> »</li>
203 <li class="nav-item nav-item-this"><a href="">Sphere internals</a></li>
204 </ul>
205 </div>
206 <div class="footer" role="contentinfo">
207 © Copyright 2014, Anders Damsgaard.
208 Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 9.1.0.
209 </div>
210 </body>
211