python_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
---
python_api.html (292337B)
---
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>Python API — 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="next" title="Sphere internals" href="sphere_internals.html" />
19 <link rel="prev" title="Fluid simulation and particle-fluid interaction" href="cfd.html" />
20 </head><body>
21 <div class="related" role="navigation" aria-label="Related">
22 <h3>Navigation</h3>
23 <ul>
24 <li class="right" style="margin-right: 10px">
25 <a href="genindex.html" title="General Index"
26 accesskey="I">index</a></li>
27 <li class="right" >
28 <a href="py-modindex.html" title="Python Module Index"
29 >modules</a> |</li>
30 <li class="right" >
31 <a href="sphere_internals.html" title="Sphere internals"
32 accesskey="N">next</a> |</li>
33 <li class="right" >
34 <a href="cfd.html" title="Fluid simulation and particle-fluid interaction"
35 accesskey="P">previous</a> |</li>
36 <li class="nav-item nav-item-0"><a href="index.html">sphere 2.15 documentation</a> »</li>
37 <li class="nav-item nav-item-this"><a href="">Python API</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 <section id="python-api">
47 <h1>Python API<a class="headerlink" href="#python-api" title="Link to this heading">¶</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 <section id="using-the-module">
52 <h2>Using the module<a class="headerlink" href="#using-the-module" title="Link to this heading">¶</a></h2>
53 <p>The package lives in <code class="docutils literal notranslate"><span class="pre">python/sphere/</span></code>. Use it from the repository root with
54 <code class="docutils literal notranslate"><span class="pre">PYTHONPATH=python</span></code>.</p>
55 <div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="nv">PYTHONPATH</span><span class="o">=</span>python<span class="w"> </span>python3<span class="w"> </span>experiments/collision.py
56 </pre></div>
57 </div>
58 <p>Most workflows follow this pattern: create <a class="reference internal" href="#sphere.sim" title="sphere.sim"><code class="xref py py-class docutils literal notranslate"><span class="pre">sphere.sim</span></code></a>, initialize
59 particles and parameters, call <a class="reference internal" href="#sphere.sim.writebin" title="sphere.sim.writebin"><code class="xref py py-meth docutils literal notranslate"><span class="pre">sphere.sim.writebin()</span></code></a>, run the compiled
60 binary with <a class="reference internal" href="#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 <code class="docutils literal notranslate"><span class="pre">./sphere</span></code>, then read outputs with
61 <a class="reference internal" href="#sphere.sim.readlast" title="sphere.sim.readlast"><code class="xref py py-meth docutils literal notranslate"><span class="pre">sphere.sim.readlast()</span></code></a> or related helpers.</p>
62 </section>
63 <section id="sample-usage">
64 <h2>Sample usage<a class="headerlink" href="#sample-usage" title="Link to this heading">¶</a></h2>
65 <p>Below is a simple, annotated example of how to setup, execute, and post-process
66 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">experiments/</span></code>
67 folder as <code class="docutils literal notranslate"><span class="pre">collision.py</span></code>.</p>
68 <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="ch">#!/usr/bin/env python</span>
69 <span class="linenos"> 2</span><span class="sd">'''</span>
70 <span class="linenos"> 3</span><span class="sd">Example of two particles colliding.</span>
71 <span class="linenos"> 4</span><span class="sd">Place script in sphere/experiments/ folder, and invoke with `python collision.py`</span>
72 <span class="linenos"> 5</span><span class="sd">'''</span>
73 <span class="linenos"> 6</span>
74 <span class="linenos"> 7</span><span class="c1"># Import the sphere module for setting up, running, and analyzing the</span>
75 <span class="linenos"> 8</span><span class="c1"># experiment. We also need the numpy module when setting arrays in the sphere</span>
76 <span class="linenos"> 9</span><span class="c1"># object.</span>
77 <span class="linenos">10</span><span class="kn">import</span><span class="w"> </span><span class="nn">sphere</span>
78 <span class="linenos">11</span><span class="kn">import</span><span class="w"> </span><span class="nn">numpy</span>
79 <span class="linenos">12</span>
80 <span class="linenos">13</span>
81 <span class="linenos">14</span><span class="c1">### SIMULATION SETUP</span>
82 <span class="linenos">15</span>
83 <span class="linenos">16</span><span class="c1"># Create a sphere object with two preallocated particles and a simulation ID</span>
84 <span class="linenos">17</span><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>
85 <span class="linenos">18</span>
86 <span class="linenos">19</span><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>
87 <span class="linenos">20</span>
88 <span class="linenos">21</span><span class="c1"># Define the positions of the two particles</span>
89 <span class="linenos">22</span><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>
90 <span class="linenos">23</span><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>
91 <span class="linenos">24</span>
92 <span class="linenos">25</span><span class="c1"># The default velocity is [0,0,0]. Slam particle 1 into particle 2 by defining</span>
93 <span class="linenos">26</span><span class="c1"># a positive x velocity for particle 1.</span>
94 <span class="linenos">27</span><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>
95 <span class="linenos">28</span>
96 <span class="linenos">29</span><span class="c1"># Set the world limits and the particle sorting grid. The particles need to stay</span>
97 <span class="linenos">30</span><span class="c1"># within the world limits for the entire simulation, otherwise it will stop!</span>
98 <span class="linenos">31</span><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>
99 <span class="linenos">32</span>
100 <span class="linenos">33</span><span class="c1"># Define the temporal parameters, e.g. the total time (total) and the file</span>
101 <span class="linenos">34</span><span class="c1"># output interval (file_dt), both in seconds</span>
102 <span class="linenos">35</span><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>
103 <span class="linenos">36</span>
104 <span class="linenos">37</span><span class="c1"># Using a 'dry' run, the sphere main program will display important parameters.</span>
105 <span class="linenos">38</span><span class="c1"># sphere will end after displaying these values.</span>
106 <span class="linenos">39</span><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="kc">True</span><span class="p">)</span>
107 <span class="linenos">40</span>
108 <span class="linenos">41</span>
109 <span class="linenos">42</span><span class="c1">### RUNNING THE SIMULATION</span>
110 <span class="linenos">43</span>
111 <span class="linenos">44</span><span class="c1"># Start the simulation on the GPU from the sphere program</span>
112 <span class="linenos">45</span><span class="n">SB</span><span class="o">.</span><span class="n">run</span><span class="p">()</span>
113 <span class="linenos">46</span>
114 <span class="linenos">47</span>
115 <span class="linenos">48</span><span class="c1">### ANALYSIS OF SIMULATION RESULTS</span>
116 <span class="linenos">49</span>
117 <span class="linenos">50</span><span class="c1"># Plot the system energy through time, image saved as collision-energy.png</span>
118 <span class="linenos">51</span><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>
119 <span class="linenos">52</span>
120 <span class="linenos">53</span><span class="c1"># Render the particles using the built-in raytracer</span>
121 <span class="linenos">54</span><span class="n">SB</span><span class="o">.</span><span class="n">render</span><span class="p">()</span>
122 <span class="linenos">55</span>
123 <span class="linenos">56</span><span class="c1"># Alternative visualization using ParaView. See the documentation of</span>
124 <span class="linenos">57</span><span class="c1"># ``sim.writeVTKall()`` for more information about displaying the</span>
125 <span class="linenos">58</span><span class="c1"># particles in ParaView.</span>
126 <span class="linenos">59</span><span class="n">SB</span><span class="o">.</span><span class="n">writeVTKall</span><span class="p">()</span>
127 </pre></div>
128 </div>
129 <p>The full documentation of the <code class="docutils literal notranslate"><span class="pre">sphere</span></code> Python API can be found below.</p>
130 </section>
131 <section id="module-sphere">
132 <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="Link to this heading">¶</a></h2>
133 <p>sphere: discrete element method simulation interface. See sphere.sim.</p>
134 <dl class="py function">
135 <dt class="sig sig-object py" id="sphere.V_sphere">
136 <span class="sig-prename descclassname"><span class="pre">sphere.</span></span><span class="sig-name descname"><span class="pre">V_sphere</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">r</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#sphere.V_sphere" title="Link to this definition">¶</a></dt>
137 <dd><p>Calculates the volume of a sphere with radius r</p>
138 <dl class="field-list simple">
139 <dt class="field-odd">Returns<span class="colon">:</span></dt>
140 <dd class="field-odd"><p>The sphere volume [m^3]</p>
141 </dd>
142 <dt class="field-even">Return type<span class="colon">:</span></dt>
143 <dd class="field-even"><p>float</p>
144 </dd>
145 </dl>
146 </dd></dl>
147
148 <dl class="py function">
149 <dt class="sig sig-object py" id="sphere.cleanup">
150 <span class="sig-prename descclassname"><span class="pre">sphere.</span></span><span class="sig-name descname"><span class="pre">cleanup</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">sb</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#sphere.cleanup" title="Link to this definition">¶</a></dt>
151 <dd><p>Removes the input/output files and images belonging to the object simulation
152 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>
153 <dl class="field-list simple">
154 <dt class="field-odd">Parameters<span class="colon">:</span></dt>
155 <dd class="field-odd"><p><strong>sb</strong> (<a class="reference internal" href="#sphere.sim" title="sphere.sim"><em>sim</em></a>) – A sphere.sim object</p>
156 </dd>
157 </dl>
158 </dd></dl>
159
160 <dl class="py function">
161 <dt class="sig sig-object py" id="sphere.convert">
162 <span class="sig-prename descclassname"><span class="pre">sphere.</span></span><span class="sig-name descname"><span class="pre">convert</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">graphics_format</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'png'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">folder</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'../img_out'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">remove_ppm</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#sphere.convert" title="Link to this definition">¶</a></dt>
163 <dd><p>Converts all PPM images in img_out to graphics_format using ImageMagick. All
164 PPM images are subsequently removed if <cite>remove_ppm</cite> is <cite>True</cite>.</p>
165 <dl class="field-list simple">
166 <dt class="field-odd">Parameters<span class="colon">:</span></dt>
167 <dd class="field-odd"><ul class="simple">
168 <li><p><strong>graphics_format</strong> (<em>str</em>) – Convert the images to this format</p></li>
169 <li><p><strong>folder</strong> (<em>str</em>) – The folder containing the PPM images to convert</p></li>
170 <li><p><strong>remove_ppm</strong> (<em>bool</em>) – Remove ALL ppm files in <cite>folder</cite> after conversion</p></li>
171 </ul>
172 </dd>
173 </dl>
174 </dd></dl>
175
176 <dl class="py function">
177 <dt class="sig sig-object py" id="sphere.render">
mx1.adamsgaard.dk:70 /src/sphere/file/doc/html/python_api.html.gph:187: line too long