Update Sphinx documentation, commit 9709585 [skip ci].

_sources/breaking_changes.rst

@@ -8,6 +8,9 @@ Breaking changes
 1.0.0
 -----
 
+- The VSOP2013 functions have been moved into the
+  ``model`` submodule. The semantics of the functions
+  have not changed.
 - The ``make_nbody_sys()`` function has been replaced by
   the ``model.nbody()`` function, with identical semantics.
 

_sources/changelog.rst

@@ -40,6 +40,10 @@ New
 Changes
 ~~~~~~~
 
+- **BREAKING**: the VSOP2013 functions have been moved from the
+  main module to the new ``model`` submodule
+  (`#130 <https://github.com/bluescarni/heyoka.py/pull/130>`__).
+  This is a :ref:`breaking change <bchanges_1_0_0>`.
 - The custom NumPy memory manager that prevents memory leaks
   with ``real`` arrays is now disabled by default
   (`#129 <https://github.com/bluescarni/heyoka.py/pull/129>`__).

_sources/notebooks/vsop2013.ipynb

@@ -13,7 +13,7 @@
     "API overview\n",
     "-------\n",
     "\n",
-    "heyoka.py provides three functions to generate the analytical formulae for the VSOP2013 theory.\n",
+    "heyoka.py provides three functions to generate the analytical formulae for the VSOP2013 theory. These functions are available in the ``model`` submodule.\n",
     "\n",
     "The first one, ``vsop2013_elliptic()``, returns the formulae for the heliocentric elliptic orbital elements for a given planet. The 6 elliptic orbital elements are, in order:\n",
     "\n",
@@ -56,7 +56,7 @@
     "import heyoka as hy\n",
     "\n",
     "for thr in [1e-7, 1e-9, 1e-11]:\n",
-    "    print(\"Size of Mars' semi-major axis solution @ {}: {}\".format(thr, len(hy.vsop2013_elliptic(4, 1, thresh = thr))))"
+    "    print(\"Size of Mars' semi-major axis solution @ {}: {}\".format(thr, len(hy.model.vsop2013_elliptic(4, 1, thresh = thr))))"
    ]
   },
   {
@@ -98,9 +98,9 @@
     }
    ],
    "source": [
-    "print(\"Mars' semi-major axis solution, threshold = 6e-5, default time expression:\\n{}\\n\".format(hy.vsop2013_elliptic(4, 1, thresh = 6e-5)))\n",
-    "print(\"Mars' semi-major axis solution, threshold = 6e-5, time represented by variable 'x':\\n{}\\n\".format(hy.vsop2013_elliptic(4, 1, time=hy.expression(\"x\"), thresh = 6e-5)))\n",
-    "print(\"Mars' semi-major axis solution, threshold = 6e-5, time rescaled by a factor of 100:\\n{}\".format(hy.vsop2013_elliptic(4, 1, time=hy.time / 100., thresh = 6e-5)))"
+    "print(\"Mars' semi-major axis solution, threshold = 6e-5, default time expression:\\n{}\\n\".format(hy.model.vsop2013_elliptic(4, 1, thresh = 6e-5)))\n",
+    "print(\"Mars' semi-major axis solution, threshold = 6e-5, time represented by variable 'x':\\n{}\\n\".format(hy.model.vsop2013_elliptic(4, 1, time=hy.expression(\"x\"), thresh = 6e-5)))\n",
+    "print(\"Mars' semi-major axis solution, threshold = 6e-5, time rescaled by a factor of 100:\\n{}\".format(hy.model.vsop2013_elliptic(4, 1, time=hy.time / 100., thresh = 6e-5)))"
    ]
   },
   {
@@ -161,7 +161,7 @@
     "    # position of Venus (planet index 2) in the ICRF. Replace the\n",
     "    # default time variable with the \"tm\" symbolic variable and set\n",
     "    # a custom threshold level.\n",
-    "    venus_x, venus_y, venus_z = hy.vsop2013_cartesian_icrf(2, time=tm, thresh=thr)[:3]\n",
+    "    venus_x, venus_y, venus_z = hy.model.vsop2013_cartesian_icrf(2, time=tm, thresh=thr)[:3]\n",
     "\n",
     "    # Compile the function for the evaluation of venus_x/y/z.\n",
     "    venus_cf = hy.make_cfunc([venus_x, venus_y, venus_z])\n",

breaking_changes.html

@@ -400,6 +400,9 @@ <h2> Contents </h2>
 <section id="bchanges-1-0-0">
 <span id="id2"></span><h2>1.0.0<a class="headerlink" href="#bchanges-1-0-0" title="Permalink to this heading">#</a></h2>
 <ul class="simple">
+<li><p>The VSOP2013 functions have been moved into the
+<code class="docutils literal notranslate"><span class="pre">model</span></code> submodule. The semantics of the functions
+have not changed.</p></li>
 <li><p>The <code class="docutils literal notranslate"><span class="pre">make_nbody_sys()</span></code> function has been replaced by
 the <code class="docutils literal notranslate"><span class="pre">model.nbody()</span></code> function, with identical semantics.</p></li>
 </ul>

changelog.html

@@ -540,6 +540,10 @@ <h3>New<a class="headerlink" href="#new" title="Permalink to this heading">#</a>
 <section id="changes">
 <h3>Changes<a class="headerlink" href="#changes" title="Permalink to this heading">#</a></h3>
 <ul class="simple">
+<li><p><strong>BREAKING</strong>: the VSOP2013 functions have been moved from the
+main module to the new <code class="docutils literal notranslate"><span class="pre">model</span></code> submodule
+(<a class="reference external" href="https://github.com/bluescarni/heyoka.py/pull/130">#130</a>).
+This is a <a class="reference internal" href="breaking_changes.html#bchanges-1-0-0"><span class="std std-ref">breaking change</span></a>.</p></li>
 <li><p>The custom NumPy memory manager that prevents memory leaks
 with <code class="docutils literal notranslate"><span class="pre">real</span></code> arrays is now disabled by default
 (<a class="reference external" href="https://github.com/bluescarni/heyoka.py/pull/129">#129</a>).</p></li>

notebooks/Batch mode overview.html

@@ -1306,7 +1306,7 @@ <h2>Ensemble propagations<a class="headerlink" href="#ensemble-propagations" tit
 </div>
 </div>
 <div class="cell_output docutils container">
-<img alt="../_images/f29fc07daa622ba2fca337814af20bb3620e22f95ddc98b2908cf63f261112c2.png" src="../_images/f29fc07daa622ba2fca337814af20bb3620e22f95ddc98b2908cf63f261112c2.png" />
+<img alt="../_images/4fe297d892980683335bd536c6e99ee4aaa8290de2c972882304bb1e8305a8cb.png" src="../_images/4fe297d892980683335bd536c6e99ee4aaa8290de2c972882304bb1e8305a8cb.png" />
 </div>
 </div>
 </section>

notebooks/Customising the adaptive integrator.html

@@ -560,8 +560,8 @@ <h2>Compact mode<a class="headerlink" href="#compact-mode" title="Permalink to t
 </div>
 </div>
 <div class="cell_output docutils container">
-<div class="output stream highlight-myst-ansi notranslate"><div class="highlight"><pre><span></span>CPU times: user 7.15 s, sys: 75.4 ms, total: 7.23 s
-Wall time: 7.29 s
+<div class="output stream highlight-myst-ansi notranslate"><div class="highlight"><pre><span></span>CPU times: user 5.28 s, sys: 63.8 ms, total: 5.34 s
+Wall time: 5.34 s
 </pre></div>
 </div>
 </div>
@@ -576,8 +576,8 @@ <h2>Compact mode<a class="headerlink" href="#compact-mode" title="Permalink to t
 </div>
 </div>
 <div class="cell_output docutils container">
-<div class="output stream highlight-myst-ansi notranslate"><div class="highlight"><pre><span></span>CPU times: user 237 ms, sys: 0 ns, total: 237 ms
-Wall time: 236 ms
+<div class="output stream highlight-myst-ansi notranslate"><div class="highlight"><pre><span></span>CPU times: user 189 ms, sys: 166 µs, total: 189 ms
+Wall time: 188 ms
 </pre></div>
 </div>
 </div>

notebooks/Optimal Control of the Lotka-Volterra equations.html

@@ -1022,9 +1022,9 @@ <h2>Implementing a single shooting method<a class="headerlink" href="#implementi
 </div>
 </div>
 <div class="cell_output docutils container">
-<div class="output stderr highlight-myst-ansi notranslate"><div class="highlight"><pre><span></span>/tmp/ipykernel_12891/2332358995.py:11: DeprecationWarning: Conversion of an array with ndim &gt; 0 to a scalar is deprecated, and will error in future. Ensure you extract a single element from your array before performing this operation. (Deprecated NumPy 1.25.)
+<div class="output stderr highlight-myst-ansi notranslate"><div class="highlight"><pre><span></span>/tmp/ipykernel_12919/2332358995.py:11: DeprecationWarning: Conversion of an array with ndim &gt; 0 to a scalar is deprecated, and will error in future. Ensure you extract a single element from your array before performing this operation. (Deprecated NumPy 1.25.)
   ta.pars[6] = np.heaviside(switching_function(x_0,y_0,lx_0,ly_0, ps), 1.)
-/tmp/ipykernel_12891/2332358995.py:14: DeprecationWarning: Conversion of an array with ndim &gt; 0 to a scalar is deprecated, and will error in future. Ensure you extract a single element from your array before performing this operation. (Deprecated NumPy 1.25.)
+/tmp/ipykernel_12919/2332358995.py:14: DeprecationWarning: Conversion of an array with ndim &gt; 0 to a scalar is deprecated, and will error in future. Ensure you extract a single element from your array before performing this operation. (Deprecated NumPy 1.25.)
   ta.state[0] = x_0; ta.state[1] = y_0; ta.state[2] = lx_0; ta.state[3] = ly_0
 </pre></div>
 </div>
@@ -1066,7 +1066,7 @@ <h2>Implementing a single shooting method<a class="headerlink" href="#implementi
 </div>
 </div>
 <div class="cell_output docutils container">
-<div class="output stderr highlight-myst-ansi notranslate"><div class="highlight"><pre><span></span>/tmp/ipykernel_12891/685660463.py:12: DeprecationWarning: Conversion of an array with ndim &gt; 0 to a scalar is deprecated, and will error in future. Ensure you extract a single element from your array before performing this operation. (Deprecated NumPy 1.25.)
+<div class="output stderr highlight-myst-ansi notranslate"><div class="highlight"><pre><span></span>/tmp/ipykernel_12919/685660463.py:12: DeprecationWarning: Conversion of an array with ndim &gt; 0 to a scalar is deprecated, and will error in future. Ensure you extract a single element from your array before performing this operation. (Deprecated NumPy 1.25.)
   ta.pars[6] = np.heaviside(switching_function(x_0,y_0,lx_0,ly_0, ps), 1.)
 </pre></div>
 </div>

notebooks/Periodic orbits in the CR3BP.html

@@ -661,7 +661,7 @@ <h2>Putting all together and integrating some initial conditions<a class="header
 </div>
 </div>
 <div class="cell_output docutils container">
-<div class="output stream highlight-myst-ansi notranslate"><div class="highlight"><pre><span></span>--- 15.712157011032104 seconds --- to build the Taylor integrator
+<div class="output stream highlight-myst-ansi notranslate"><div class="highlight"><pre><span></span>--- 12.197781324386597 seconds --- to build the Taylor integrator
 </pre></div>
 </div>
 </div>
@@ -692,7 +692,7 @@ <h2>Putting all together and integrating some initial conditions<a class="header
 </div>
 </div>
 <div class="cell_output docutils container">
-<div class="output stream highlight-myst-ansi notranslate"><div class="highlight"><pre><span></span>--- 0.06314849853515625 seconds --- to propagate
+<div class="output stream highlight-myst-ansi notranslate"><div class="highlight"><pre><span></span>--- 0.05441784858703613 seconds --- to propagate
 </pre></div>
 </div>
 </div>
@@ -750,7 +750,7 @@ <h2>Putting all together and integrating some initial conditions<a class="header
 </div>
 </div>
 <div class="cell_output docutils container">
-<div class="output text_plain highlight-myst-ansi notranslate"><div class="highlight"><pre><span></span>&lt;matplotlib.collections.PathCollection at 0x7f78688fec50&gt;
+<div class="output text_plain highlight-myst-ansi notranslate"><div class="highlight"><pre><span></span>&lt;matplotlib.collections.PathCollection at 0x7ff3501cf1c0&gt;
 </pre></div>
 </div>
 <img alt="../_images/38d7685311d4c0702c894ea7ed3a7c8adce228eb1b7d34e0f04fe4a77277e9da.png" src="../_images/38d7685311d4c0702c894ea7ed3a7c8adce228eb1b7d34e0f04fe4a77277e9da.png" />

notebooks/ensemble_mode.html

@@ -561,11 +561,11 @@ <h2>A simple example<a class="headerlink" href="#a-simple-example" title="Permal
  Taylor order            : 20
  Dimension               : 2
  Time                    : 20
- State                   : [0.05023369765600805, 0.056819409529623166],
+ State                   : [0.051934096186197286, 0.07392576557597509],
  &lt;taylor_outcome.time_limit: -4294967299&gt;,
- 0.19984740911611365,
- 0.2189204289521889,
- 97,
+ 0.19712479026440075,
+ 0.2213859382909007,
+ 98,
  None)
 </pre></div>
 </div>
@@ -616,7 +616,7 @@ <h2>A simple example<a class="headerlink" href="#a-simple-example" title="Permal
 </div>
 </div>
 <div class="cell_output docutils container">
-<img alt="../_images/00f4323467b843cbb4a7cf94e498a5a80e5b48f7e9247b434b911e09fd7f56a7.png" src="../_images/00f4323467b843cbb4a7cf94e498a5a80e5b48f7e9247b434b911e09fd7f56a7.png" />
+<img alt="../_images/9f492288b1efea77ca032ec82141d25f8a545aeac43777e37dd2fd877a3ce9e6.png" src="../_images/9f492288b1efea77ca032ec82141d25f8a545aeac43777e37dd2fd877a3ce9e6.png" />
 </div>
 </div>
 </section>

notebooks/second_integral.html

@@ -595,7 +595,7 @@ <h2>Running the experiments<a class="headerlink" href="#running-the-experiments"
 </div>
 </div>
 <div class="cell_output docutils container">
-<img alt="../_images/0cead41a95fb17e9124e45a3219193dea38008bb6f8a953781f86331900102ff.png" src="../_images/0cead41a95fb17e9124e45a3219193dea38008bb6f8a953781f86331900102ff.png" />
+<img alt="../_images/53a7137a6f264015cbcecb7d21f19c5b4cba0736cbd39552c2f8edd749bc37ee.png" src="../_images/53a7137a6f264015cbcecb7d21f19c5b4cba0736cbd39552c2f8edd749bc37ee.png" />
 </div>
 </div>
 <p>This Poincare’ section is suggesting that the integral of motion <span class="math notranslate nohighlight">\(\mathcal{C}\)</span> does indeed exist, because the intersections of all random orbits are clearly tracing curves on the <span class="math notranslate nohighlight">\(x=0\)</span> plane.</p>
@@ -610,7 +610,7 @@ <h2>Running the experiments<a class="headerlink" href="#running-the-experiments"
 </div>
 </div>
 <div class="cell_output docutils container">
-<img alt="../_images/cb61f488d87637e6f987fe09d40ffbf9a21c811a0c3a1272d1eef75c36a98f7a.png" src="../_images/cb61f488d87637e6f987fe09d40ffbf9a21c811a0c3a1272d1eef75c36a98f7a.png" />
+<img alt="../_images/164e273c38e85bae646659c6119bb2de8a0c98a25edd9c26f5a76a8fa9948a6d.png" src="../_images/164e273c38e85bae646659c6119bb2de8a0c98a25edd9c26f5a76a8fa9948a6d.png" />
 </div>
 </div>
 <p>The qualitative picture is now radically different. Although islands of stable motion persist, now most trajectories seem to be densely filling the plane, rather than tracing curves on it. Let us further increase the energy level:</p>
@@ -621,7 +621,7 @@ <h2>Running the experiments<a class="headerlink" href="#running-the-experiments"
 </div>
 </div>
 <div class="cell_output docutils container">
-<img alt="../_images/49971a71351f07f2166610fdd9b90162510597543302862789851bad2421b79f.png" src="../_images/49971a71351f07f2166610fdd9b90162510597543302862789851bad2421b79f.png" />
+<img alt="../_images/305eb68aea5d979569a1ac07e4575a9d5fd7ddbc7cb929fb9a3e7c0b95d63e73.png" src="../_images/305eb68aea5d979569a1ac07e4575a9d5fd7ddbc7cb929fb9a3e7c0b95d63e73.png" />
 </div>
 </div>
 <p>At higher energies, the densely-filling behaviour (which Henon and Heiles call <em>ergodic</em>) is even more prevalent than before.</p>

notebooks/sympy_interop.html

@@ -587,7 +587,7 @@ <h1>Interoperability with SymPy<a class="headerlink" href="#interoperability-wit
 </div>
 </div>
 <div class="cell_output docutils container">
-<div class="output stream highlight-myst-ansi notranslate"><div class="highlight"><pre><span></span>CPU times: user 2.37 s, sys: 710 µs, total: 2.38 s
+<div class="output stream highlight-myst-ansi notranslate"><div class="highlight"><pre><span></span>CPU times: user 2.38 s, sys: 596 µs, total: 2.38 s
 Wall time: 2.37 s
 </pre></div>
 </div>
@@ -607,8 +607,8 @@ <h1>Interoperability with SymPy<a class="headerlink" href="#interoperability-wit
 </div>
 </div>
 <div class="cell_output docutils container">
-<div class="output stream highlight-myst-ansi notranslate"><div class="highlight"><pre><span></span>CPU times: user 2.45 s, sys: 448 µs, total: 2.45 s
-Wall time: 2.45 s
+<div class="output stream highlight-myst-ansi notranslate"><div class="highlight"><pre><span></span>CPU times: user 2.49 s, sys: 240 µs, total: 2.49 s
+Wall time: 2.48 s
 </pre></div>
 </div>
 <div class="output text_plain highlight-myst-ansi notranslate"><div class="highlight"><pre><span></span>(&lt;taylor_outcome.time_limit: -4294967299&gt;,