tpython_api.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
---
tpython_api.html (202743B)
---
1
2 <!DOCTYPE html>
3
4 <html xmlns="http://www.w3.org/1999/xhtml">
5 <head>
6 <meta charset="utf-8" />
7 <title>Python API — sphere 2.15-beta documentation</title>
8 <link rel="stylesheet" href="_static/classic.css" type="text/css" />
9 <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
10
11 <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
12 <script type="text/javascript" src="_static/jquery.js"></script>
13 <script type="text/javascript" src="_static/underscore.js"></script>
14 <script type="text/javascript" src="_static/doctools.js"></script>
15 <script type="text/javascript" src="_static/language_data.js"></script>
16
17 <link rel="index" title="Index" href="genindex.html" />
18 <link rel="search" title="Search" href="search.html" />
19 <link rel="next" title="sphere internals" href="sphere_internals.html" />
20 <link rel="prev" title="Fluid simulation and particle-fluid interaction" href="cfd.html" />
21 </head><body>
22 <div class="related" role="navigation" aria-label="related navigation">
23 <h3>Navigation</h3>
24 <ul>
25 <li class="right" style="margin-right: 10px">
26 <a href="genindex.html" title="General Index"
27 accesskey="I">index</a></li>
28 <li class="right" >
29 <a href="py-modindex.html" title="Python Module Index"
30 >modules</a> |</li>
31 <li class="right" >
32 <a href="sphere_internals.html" title="sphere internals"
33 accesskey="N">next</a> |</li>
34 <li class="right" >
35 <a href="cfd.html" title="Fluid simulation and particle-fluid interaction"
36 accesskey="P">previous</a> |</li>
37 <li class="nav-item nav-item-0"><a href="index.html">sphere 2.15-beta documentation</a> »</li>
38 </ul>
39 </div>
40
41 <div class="document">
42 <div class="documentwrapper">
43 <div class="bodywrapper">
44 <div class="body" role="main">
45
46 <div class="section" id="python-api">
47 <h1>Python API<a class="headerlink" href="#python-api" title="Permalink to this headline">¶</a></h1>
48 <p>The Python module <code class="docutils literal notranslate"><span class="pre">sphere</span></code> is intended as the main interface to the <code class="docutils literal notranslate"><span class="pre">sphere</span></code>
49 application. It is recommended to use this module for simulation setup,
50 simulation execution, and analysis of the simulation output data.</p>
51 <p>In order to use the API, the file <code class="docutils literal notranslate"><span class="pre">sphere.py</span></code> must be placed in the same
52 directory as the Python files.</p>
53 <div class="section" id="sample-usage">
54 <h2>Sample usage<a class="headerlink" href="#sample-usage" title="Permalink to this headline">¶</a></h2>
55 <p>Below is a simple, annotated example of how to setup, execute, and post-process
56 a <code class="docutils literal notranslate"><span class="pre">sphere</span></code> simulation. The example is also found in the <code class="docutils literal notranslate"><span class="pre">python/</span></code> folder as
57 <code class="docutils literal notranslate"><span class="pre">collision.py</span></code>.</p>
58 <div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
59 2
60 3
61 4
62 5
63 6
64 7
65 8
66 9
67 10
68 11
69 12
70 13
71 14
72 15
73 16
74 17
75 18
76 19
77 20
78 21
79 22
80 23
81 24
82 25
83 26
84 27
85 28
86 29
87 30
88 31
89 32
90 33
91 34
92 35
93 36
94 37
95 38
96 39
97 40
98 41
99 42
100 43
101 44
102 45
103 46
104 47
105 48
106 49
107 50
108 51
109 52
110 53
111 54
112 55
113 56
114 57
115 58
116 59</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="ch">#!/usr/bin/env python</span>
117 <span class="sd">'''</span>
118 <span class="sd">Example of two particles colliding.</span>
119 <span class="sd">Place script in sphere/python/ folder, and invoke with `python collision.py`</span>
120 <span class="sd">'''</span>
121
122 <span class="c1"># Import the sphere module for setting up, running, and analyzing the</span>
123 <span class="c1"># experiment. We also need the numpy module when setting arrays in the sphere</span>
124 <span class="c1"># object.</span>
125 <span class="kn">import</span> <span class="nn">sphere</span>
126 <span class="kn">import</span> <span class="nn">numpy</span>
127
128
129 <span class="c1">### SIMULATION SETUP</span>
130
131 <span class="c1"># Create a sphere object with two preallocated particles and a simulation ID</span>
132 <span class="n">SB</span> <span class="o">=</span> <span class="n">sphere</span><span class="o">.</span><span class="n">sim</span><span class="p">(</span><span class="n">np</span> <span class="o">=</span> <span class="mi">2</span><span class="p">,</span> <span class="n">sid</span> <span class="o">=</span> <span class="s1">'collision'</span><span class="p">)</span>
133
134 <span class="n">SB</span><span class="o">.</span><span class="n">radius</span><span class="p">[:]</span> <span class="o">=</span> <span class="mf">0.3</span> <span class="c1"># set radii to 0.3 m</span>
135
136 <span class="c1"># Define the positions of the two particles</span>
137 <span class="n">SB</span><span class="o">.</span><span class="n">x</span><span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="p">:]</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mf">10.0</span><span class="p">,</span> <span class="mf">5.0</span><span class="p">,</span> <span class="mf">5.0</span><span class="p">])</span> <span class="c1"># particle 1 (idx 0)</span>
138 <span class="n">SB</span><span class="o">.</span><span class="n">x</span><span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="p">:]</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mf">11.0</span><span class="p">,</span> <span class="mf">5.0</span><span class="p">,</span> <span class="mf">5.0</span><span class="p">])</span> <span class="c1"># particle 2 (idx 1)</span>
139
140 <span class="c1"># The default velocity is [0,0,0]. Slam particle 1 into particle 2 by defining</span>
141 <span class="c1"># a positive x velocity for particle 1.</span>
142 <span class="n">SB</span><span class="o">.</span><span class="n">vel</span><span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">]</span> <span class="o">=</span> <span class="mf">1.0</span>
143
144 <span class="c1"># Set the world limits and the particle sorting grid. The particles need to stay</span>
145 <span class="c1"># within the world limits for the entire simulation, otherwise it will stop!</span>
146 <span class="n">SB</span><span class="o">.</span><span class="n">initGridAndWorldsize</span><span class="p">(</span><span class="n">margin</span> <span class="o">=</span> <span class="mf">5.0</span><span class="p">)</span>
147
148 <span class="c1"># Define the temporal parameters, e.g. the total time (total) and the file</span>
149 <span class="c1"># output interval (file_dt), both in seconds</span>
150 <span class="n">SB</span><span class="o">.</span><span class="n">initTemporal</span><span class="p">(</span><span class="n">total</span> <span class="o">=</span> <span class="mf">2.0</span><span class="p">,</span> <span class="n">file_dt</span> <span class="o">=</span> <span class="mf">0.1</span><span class="p">)</span>
151
152 <span class="c1"># Using a 'dry' run, the sphere main program will display important parameters.</span>
153 <span class="c1"># sphere will end after displaying these values.</span>
154 <span class="n">SB</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">dry</span> <span class="o">=</span> <span class="bp">True</span><span class="p">)</span>
155
156
157 <span class="c1">### RUNNING THE SIMULATION</span>
158
159 <span class="c1"># Start the simulation on the GPU from the sphere program</span>
160 <span class="n">SB</span><span class="o">.</span><span class="n">run</span><span class="p">()</span>
161
162
163 <span class="c1">### ANALYSIS OF SIMULATION RESULTS</span>
164
165 <span class="c1"># Plot the system energy through time, image saved as collision-energy.png</span>
166 <span class="n">SB</span><span class="o">.</span><span class="n">visualize</span><span class="p">(</span><span class="n">method</span> <span class="o">=</span> <span class="s1">'energy'</span><span class="p">)</span>
167
168 <span class="c1"># Render the particles using the built-in raytracer</span>
169 <span class="n">SB</span><span class="o">.</span><span class="n">render</span><span class="p">()</span>
170
171 <span class="c1"># Alternative visualization using ParaView. See the documentation of</span>
172 <span class="c1"># ``sim.writeVTKall()`` for more information about displaying the</span>
173 <span class="c1"># particles in ParaView.</span>
174 <span class="n">SB</span><span class="o">.</span><span class="n">writeVTKall</span><span class="p">()</span>
175 </pre></div>
176 </td></tr></table></div>
177 <p>The full documentation of the <code class="docutils literal notranslate"><span class="pre">sphere</span></code> Python API can be found below.</p>
178 </div>
179 <div class="section" id="module-sphere">
180 <span id="the-sphere-module"></span><h2>The <code class="docutils literal notranslate"><span class="pre">sphere</span></code> module<a class="headerlink" href="#module-sphere" title="Permalink to this headline">¶</a></h2>
181 <dl class="function">
182 <dt id="sphere.V_sphere">
183 <code class="sig-prename descclassname">sphere.</code><code class="sig-name descname">V_sphere</code><span class="sig-paren">(</span><em class="sig-param">r</em><span class="sig-paren">)</span><a class="headerlink" href="#sphere.V_sphere" title="Permalink to this definition">¶</a></dt>
184 <dd><p>Calculates the volume of a sphere with radius r</p>
185 <dl class="field-list simple">
186 <dt class="field-odd">Returns</dt>
187 <dd class="field-odd"><p>The sphere volume [m^3]</p>
188 </dd>
189 <dt class="field-even">Return type</dt>
190 <dd class="field-even"><p>float</p>
191 </dd>
192 </dl>
193 </dd></dl>
194
195 <dl class="function">
196 <dt id="sphere.cleanup">
197 <code class="sig-prename descclassname">sphere.</code><code class="sig-name descname">cleanup</code><span class="sig-paren">(</span><em class="sig-param">sim</em><span class="sig-paren">)</span><a class="headerlink" href="#sphere.cleanup" title="Permalink to this definition">¶</a></dt>
198 <dd><p>Removes the input/output files and images belonging to the object simulation
199 ID from the <code class="docutils literal notranslate"><span class="pre">input/</span></code>, <code class="docutils literal notranslate"><span class="pre">output/</span></code> and <code class="docutils literal notranslate"><span class="pre">img_out/</span></code> folders.</p>
200 <dl class="field-list simple">
201 <dt class="field-odd">Parameters</dt>
202 <dd class="field-odd"><p><strong>spherebin</strong> (<a class="reference internal" href="#sphere.sim" title="sphere.sim"><em>sim</em></a>) – A sim object</p>
203 </dd>
204 </dl>
205 </dd></dl>
206
207 <dl class="function">
208 <dt id="sphere.convert">
209 <code class="sig-prename descclassname">sphere.</code><code class="sig-name descname">convert</code><span class="sig-paren">(</span><em class="sig-param">graphics_format='png'</em>, <em class="sig-param">folder='../img_out'</em>, <em class="sig-param">remove_ppm=False</em><span class="sig-paren">)</span><a class="headerlink" href="#sphere.convert" title="Permalink to this definition">¶</a></dt>
210 <dd><p>Converts all PPM images in img_out to graphics_format using ImageMagick. All
211 PPM images are subsequently removed if <cite>remove_ppm</cite> is <cite>True</cite>.</p>
212 <dl class="field-list simple">
213 <dt class="field-odd">Parameters</dt>
214 <dd class="field-odd"><ul class="simple">
215 <li><p><strong>graphics_format</strong> (<em>str</em>) – Convert the images to this format</p></li>
216 <li><p><strong>folder</strong> (<em>str</em>) – The folder containing the PPM images to convert</p></li>
217 <li><p><strong>remove_ppm</strong> (<em>bool</em>) – Remove ALL ppm files in <cite>folder</cite> after conversion</p></li>
218 </ul>
219 </dd>
220 </dl>
221 </dd></dl>
222
223 <dl class="function">
224 <dt id="sphere.render">
225 <code class="sig-prename descclassname">sphere.</code><code class="sig-name descname">render</code><span class="sig-paren">(</span><em class="sig-param">binary</em>, <em class="sig-param">method='pres'</em>, <em class="sig-param">max_val=1000.0</em>, <em class="sig-param">lower_cutoff=0.0</em>, <em class="sig-param">graphics_format='png'</em>, <em class="sig-param">verbose=True</em><span class="sig-paren">)</span><a class="headerlink" href="#sphere.render" title="Permalink to this definition">¶</a></dt>
226 <dd><p>Render target binary using the <code class="docutils literal notranslate"><span class="pre">sphere</span></code> raytracer.</p>
227 <dl class="field-list simple">
228 <dt class="field-odd">Parameters</dt>
229 <dd class="field-odd"><ul class="simple">
230 <li><p><strong>method</strong> (<em>str</em>) – The color visualization method to use for the particles.
231 Possible values are: ‘normal’: color all particles with the same
232 color, ‘pres’: color by pressure, ‘vel’: color by translational
233 velocity, ‘angvel’: color by rotational velocity, ‘xdisp’: color by
234 total displacement along the x-axis, ‘angpos’: color by angular
235 position.</p></li>
236 <li><p><strong>max_val</strong> (<em>float</em>) – The maximum value of the color bar</p></li>
237 <li><p><strong>lower_cutoff</strong> (<em>float</em>) – Do not render particles with a value below this
238 value, of the field selected by <code class="docutils literal notranslate"><span class="pre">method</span></code></p></li>
239 <li><p><strong>graphics_format</strong> (<em>str</em>) – Convert the PPM images generated by the ray
240 tracer to this image format using Imagemagick</p></li>
241 <li><p><strong>verbose</strong> (<em>bool</em>) – Show verbose information during ray tracing</p></li>
242 </ul>
243 </dd>
244 </dl>
245 </dd></dl>
246
247 <dl class="function">
248 <dt id="sphere.run">
249 <code class="sig-prename descclassname">sphere.</code><code class="sig-name descname">run</code><span class="sig-paren">(</span><em class="sig-param">binary</em>, <em class="sig-param">verbose=True</em>, <em class="sig-param">hideinputfile=False</em><span class="sig-paren">)</span><a class="headerlink" href="#sphere.run" title="Permalink to this definition">¶</a></dt>
250 <dd><p>Execute <code class="docutils literal notranslate"><span class="pre">sphere</span></code> with target binary file as input.</p>
251 <dl class="field-list simple">
252 <dt class="field-odd">Parameters</dt>
253 <dd class="field-odd"><ul class="simple">
254 <li><p><strong>binary</strong> (<em>str</em>) – Input file for <code class="docutils literal notranslate"><span class="pre">sphere</span></code></p></li>
255 <li><p><strong>verbose</strong> (<em>bool</em>) – Show <code class="docutils literal notranslate"><span class="pre">sphere</span></code> output</p></li>
256 <li><p><strong>hideinputfile</strong> (<em>bool</em>) – Hide the input file</p></li>
257 </ul>
258 </dd>
259 </dl>
260 </dd></dl>
261
262 <dl class="class">
263 <dt id="sphere.sim">
264 <em class="property">class </em><code class="sig-prename descclassname">sphere.</code><code class="sig-name descname">sim</code><span class="sig-paren">(</span><em class="sig-param">sid='unnamed'</em>, <em class="sig-param">np=0</em>, <em class="sig-param">nd=3</em>, <em class="sig-param">nw=0</em>, <em class="sig-param">fluid=False</em>, <em class="sig-param">cfd_solver=0</em><span class="sig-paren">)</span><a class="headerlink" href="#sphere.sim" title="Permalink to this definition">¶</a></dt>
265 <dd><p>Class containing all <code class="docutils literal notranslate"><span class="pre">sphere</span></code> data.</p>
266 <p>Contains functions for reading and writing binaries, as well as simulation
267 setup and data analysis. Most arrays are initialized to default values.</p>
268 <dl class="field-list simple">
269 <dt class="field-odd">Parameters</dt>
270 <dd class="field-odd"><ul class="simple">
271 <li><p><strong>np</strong> (<em>int</em>) – The number of particles to allocate memory for (default=1)</p></li>
272 <li><p><strong>nd</strong> (<em>int</em>) – The number of spatial dimensions (default=3). Note that 2D and
273 1D simulations currently are not possible.</p></li>
274 <li><p><strong>nw</strong> (<em>int</em>) – The number of dynamic walls (default=1)</p></li>
275 <li><p><strong>sid</strong> (<em>str</em>) – The simulation id (default=’unnamed’). The simulation files
276 will be written with this base name.</p></li>
277 <li><p><strong>fluid</strong> (<em>bool</em>) – Setup fluid simulation (default=False)</p></li>
278 <li><p><strong>cfd_solver</strong> (<em>int</em>) – Fluid solver to use if fluid == True. 0: Navier-Stokes
279 (default), 1: Darcy.</p></li>
280 </ul>
281 </dd>
282 </dl>
283 <dl class="method">
284 <dt id="sphere.sim.ReynoldsNumber">
285 <code class="sig-name descname">ReynoldsNumber</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#sphere.sim.ReynoldsNumber" title="Permalink to this definition">¶</a></dt>
286 <dd><p>Estimate the per-cell Reynolds number by: Re=rho * ||v_f|| * dx/mu.
287 This value is returned and also stored in <cite>self.Re</cite>.</p>
288 <dl class="field-list simple">
289 <dt class="field-odd">Returns</dt>
290 <dd class="field-odd"><p>Reynolds number</p>
291 </dd>
292 <dt class="field-even">Return type</dt>
293 <dd class="field-even"><p>Numpy array with dimensions like the fluid grid</p>
294 </dd>
295 </dl>
296 </dd></dl>
297
298 <dl class="method">
299 <dt id="sphere.sim.acceleration">
300 <code class="sig-name descname">acceleration</code><span class="sig-paren">(</span><em class="sig-param">idx=-1</em><span class="sig-paren">)</span><a class="headerlink" href="#sphere.sim.acceleration" title="Permalink to this definition">¶</a></dt>
301 <dd><p>Returns the acceleration of one or more particles, selected by their
302 index. If the index is equal to -1 (default value), all accelerations
303 are returned.</p>
304 <dl class="field-list simple">
305 <dt class="field-odd">Parameters</dt>
306 <dd class="field-odd"><p><strong>idx</strong> (<em>int</em><em>, </em><em>list</em><em> or </em><em>numpy.array</em>) – Index or index range of particles</p>
307 </dd>
308 <dt class="field-even">Returns</dt>
309 <dd class="field-even"><p>n-by-3 matrix of acceleration(s)</p>
310 </dd>
311 <dt class="field-odd">Return type</dt>
312 <dd class="field-odd"><p>numpy.array</p>
313 </dd>
314 </dl>
315 </dd></dl>
316
317 <dl class="method">
318 <dt id="sphere.sim.adaptiveGrid">
319 <code class="sig-name descname">adaptiveGrid</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#sphere.sim.adaptiveGrid" title="Permalink to this definition">¶</a></dt>
320 <dd><p>Set the height of the fluid grid to automatically readjust to the
321 height of the granular assemblage, as dictated by the position of the
322 top wall. This will readjust <cite>self.L[2]</cite> during the simulation to
323 equal the position of the top wall <cite>self.w_x[0]</cite>.</p>
324 <p>See also <a class="reference internal" href="#sphere.sim.staticGrid" title="sphere.sim.staticGrid"><code class="xref py py-func docutils literal notranslate"><span class="pre">staticGrid()</span></code></a></p>
325 </dd></dl>
326
327 <dl class="method">
328 <dt id="sphere.sim.addParticle">
mx1.adamsgaard.dk:70 /src/sphere/file/doc/html/python_api.html.gph:338: line too long