Documentation tweaks

doc/tutorials.rst → doc/advanced_tutorials.rst

@@ -1,7 +1,7 @@
-.. _tutorials:
+.. _adv_tutorials:
 
-Tutorials
-=========
+Advanced tutorials
+==================
 
 .. only:: html
 
@@ -23,24 +23,6 @@ Tutorials
      the features currently
      available only in the development version of heyoka.py.
 
-Basics
--------
-
-.. toctree::
-  :maxdepth: 1
-
-  tut_taylor_method
-  notebooks/The expression system.ipynb
-  notebooks/The adaptive integrator.ipynb
-  notebooks/Customising the adaptive integrator.ipynb
-  notebooks/ODEs with parameters.ipynb
-  notebooks/Non-autonomous systems.ipynb
-  notebooks/Dense output.ipynb
-  notebooks/Event detection
-
-Advanced
---------
-
 .. toctree::
   :maxdepth: 1
 

doc/basic_tutorials.rst

@@ -0,0 +1,36 @@
+.. _basic_tutorials:
+
+Basic tutorials
+===============
+
+.. only:: html
+
+  .. important::
+
+     .. raw:: html
+
+        <p>
+        Most of these tutorials can be launched as online interactive notebooks
+        thanks to the infrastructure provided by <a href="https://mybinder.org/">binder</a>.
+        Look for the rocket icon <i class="fas fa-rocket"></i> on top of each page!
+        </p>
+
+  .. important::
+
+     Some tutorials may use features not available yet in the latest stable release
+     of heyoka.py, and thus might fail to execute correctly in the online interactive
+     notebooks. Please refer to the :ref:`changelog <changelog>` for an overview of
+     the features currently
+     available only in the development version of heyoka.py.
+
+.. toctree::
+  :maxdepth: 1
+
+  tut_taylor_method
+  notebooks/The expression system.ipynb
+  notebooks/The adaptive integrator.ipynb
+  notebooks/Customising the adaptive integrator.ipynb
+  notebooks/ODEs with parameters.ipynb
+  notebooks/Non-autonomous systems.ipynb
+  notebooks/Dense output.ipynb
+  notebooks/Event detection

doc/index.md

@@ -72,7 +72,8 @@ The authors are Francesco Biscani and Dario Izzo (European Space Agency).
 :caption: Contents
 
 install
-tutorials
+basic_tutorials
+advanced_tutorials
 examples
 benchmarks
 changelog

doc/notebooks/ex_system_revisited.ipynb

@@ -7,7 +7,7 @@
    "source": [
     "(ex_system_rev)=\n",
     "\n",
-    "# The expression system, revisited\n",
+    "# Using the expression system effectively\n",
     "\n",
     "## Long sums and products\n",
     "\n",
@@ -1032,7 +1032,7 @@
     {
      "data": {
       "text/plain": [
-       "exp((x - z))"
+       "{exp((x - z))}"
       ]
      },
      "execution_count": 35,
@@ -1091,11 +1091,11 @@
      "data": {
       "text/plain": [
        "[([0, 1, 0, 0], 1.0000000000000000),\n",
-       " ([0, 0, 1, 0], (z * -sin((y * z)))),\n",
-       " ([0, 0, 0, 1], (y * -sin((y * z)))),\n",
-       " ([1, 1, 0, 0], exp((x - z))),\n",
-       " ([1, 0, 1, 0], y**-1.0000000000000000),\n",
-       " ([1, 0, 0, 1], -exp((x - z)))]"
+       " ([0, 0, 1, 0], {({z} * {-sin((y * z))})}),\n",
+       " ([0, 0, 0, 1], {({y} * {-sin((y * z))})}),\n",
+       " ([1, 1, 0, 0], {exp((x - z))}),\n",
+       " ([1, 0, 1, 0], {y**-1.0000000000000000}),\n",
+       " ([1, 0, 0, 1], {-{exp((x - z))}})]"
       ]
      },
      "execution_count": 37,
@@ -1112,7 +1112,7 @@
    "id": "45ccb1ef-96b0-4ccc-89fd-1161b19e5d4b",
    "metadata": {},
    "source": [
-    "We can also ask for the derivatives of a specific component:"
+    "We can also ask for the derivatives of a specific component. For instance, here's the gradient of the first component of the function:"
    ]
   },
   {
@@ -1125,8 +1125,8 @@
      "data": {
       "text/plain": [
        "[([0, 1, 0, 0], 1.0000000000000000),\n",
-       " ([0, 0, 1, 0], (z * -sin((y * z)))),\n",
-       " ([0, 0, 0, 1], (y * -sin((y * z))))]"
+       " ([0, 0, 1, 0], {({z} * {-sin((y * z))})}),\n",
+       " ([0, 0, 0, 1], {({y} * {-sin((y * z))})})]"
       ]
      },
      "execution_count": 38,
@@ -1159,7 +1159,7 @@
     "\n",
     "has often been used to ([incorrectly](https://arxiv.org/abs/1904.02990)) argue that numerical reverse-mode AD is superior to symbolic differentiation. Let us try to compute the gradient of this function first using ``diff()`` and then using ``diff_tensors()``.\n",
     "\n",
-    "Let us begin with the definition of the function (we take $n=8$):"
+    "We begin with the definition of the function (taking $n=8$):"
    ]
   },
   {
@@ -1278,14 +1278,14 @@
     {
      "data": {
       "text/plain": [
-       "[(x_2 * (((x_5 * x_6) * (x_7 * x_8)) * (x_3 * x_4))),\n",
-       " (x_1 * (((x_5 * x_6) * (x_7 * x_8)) * (x_3 * x_4))),\n",
-       " (x_4 * (((x_5 * x_6) * (x_7 * x_8)) * (x_1 * x_2))),\n",
-       " (x_3 * (((x_5 * x_6) * (x_7 * x_8)) * (x_1 * x_2))),\n",
-       " (x_6 * ((x_7 * x_8) * ((x_1 * x_2) * (x_3 * x_4)))),\n",
-       " (x_5 * ((x_7 * x_8) * ((x_1 * x_2) * (x_3 * x_4)))),\n",
-       " (x_8 * ((x_5 * x_6) * ((x_1 * x_2) * (x_3 * x_4)))),\n",
-       " (x_7 * ((x_5 * x_6) * ((x_1 * x_2) * (x_3 * x_4))))]"
+       "[{({x_2} * {({((x_5 * x_6) * (x_7 * x_8))} * {(x_3 * x_4)})})},\n",
+       " {({x_1} * {({((x_5 * x_6) * (x_7 * x_8))} * {(x_3 * x_4)})})},\n",
+       " {({x_4} * {({((x_5 * x_6) * (x_7 * x_8))} * {(x_1 * x_2)})})},\n",
+       " {({x_3} * {({((x_5 * x_6) * (x_7 * x_8))} * {(x_1 * x_2)})})},\n",
+       " {({x_6} * {({(x_7 * x_8)} * {((x_1 * x_2) * (x_3 * x_4))})})},\n",
+       " {({x_5} * {({(x_7 * x_8)} * {((x_1 * x_2) * (x_3 * x_4))})})},\n",
+       " {({x_8} * {({(x_5 * x_6)} * {((x_1 * x_2) * (x_3 * x_4))})})},\n",
+       " {({x_7} * {({(x_5 * x_6)} * {((x_1 * x_2) * (x_3 * x_4))})})}]"
       ]
      },
      "execution_count": 42,
@@ -1294,6 +1294,7 @@
     }
    ],
    "source": [
+    "# Compute the gradient via diff_tensors().\n",
     "grad_diff_tensors = [t[1] for t in hy.diff_tensors([sp_func], diff_order=1).get_derivatives(1)]\n",
     "grad_diff_tensors"
    ]
@@ -1399,6 +1400,8 @@
    "id": "5c56d8f1-4acd-4e6f-80fc-60bb6c6edacb",
    "metadata": {},
    "source": [
+    "This is clearly a marked improvement with respect to the quadratic complexity of the gradient computed via ``diff()``.\n",
+    "\n",
     "### General guidelines\n",
     "\n",
     "In conclusion, how should one choose whether to use ``diff()`` or ``diff_tensors()`` to compute symbolic derivatives in heyoka.py?\n",

doc/notebooks/sympy_interop.ipynb

@@ -15,8 +15,6 @@
     "\n",
     "In this tutorial, we will show how SymPy interoperability can be used for expression simplification purposes, which ultimately leads to a measurable performance increase in the numerical integration of a system of ODEs.\n",
     "\n",
-    "> **NOTE**: [another tutorial](<./tides_spokes.ipynb>) showcasing a more complex interaction between heyoka.py and SymPy is available.\n",
-    "\n",
     "For this example, we will consider the relativistic dynamics of Mercury's orbit around the Sun, which, in the first post-Newtonian approximation, can be described by the following Hamiltonian:\n",
     "\n",
     "$$\n",

tools/gha_manylinux.sh

@@ -38,7 +38,7 @@ echo "PYTHON_DIR: ${PYTHON_DIR}"
 export NUMPY_VERSION="1.24.*"
 
 # The heyoka version to be used for releases.
-export HEYOKA_VERSION_RELEASE="0.21.0"
+export HEYOKA_VERSION_RELEASE="1.0.0"
 
 # Check if this is a release build.
 if [[ "${GITHUB_REF}" == "refs/tags/v"* ]]; then