A first batch of doc updates to account for the propagate_grid() chan…

…ges.
bluescarni · Dec 16, 2023 · 60022c1 · 60022c1
1 parent 2dd233e
commit 60022c1
Show file tree

Hide file tree

Showing 3 changed files with 50 additions and 8 deletions.
diff --git a/doc/breaking_changes.rst b/doc/breaking_changes.rst
@@ -3,6 +3,27 @@
 Breaking changes
 ================
 
+.. _bchanges_4_0_0:
+
+4.0.0
+-----
+
+heyoka.py 4 includes several backwards-incompatible changes.
+
+API/behaviour changes
+~~~~~~~~~~~~~~~~~~~~~
+
+``propagate_grid()``
+^^^^^^^^^^^^^^^^^^^^
+
+The ``propagate_grid()`` methods of the adaptive integrators now require the first element of the
+time grid to be equal to the current integrator time. Previously, in case of a difference between the
+integrator time and the first grid point, heyoka.py would propagate the state of the system up to the
+first grid point with ``propagate_until()``.
+
+If you want to recover the previous behaviour, you will have to invoke manually ``propagate_until(grid[0])``
+before invoking ``propagate_grid()``.
+
 .. _bchanges_1_0_0:
 
 1.0.0

diff --git a/doc/changelog.rst b/doc/changelog.rst
@@ -9,6 +9,11 @@ Changelog
 Changes
 ~~~~~~~
 
+- **BREAKING**: the ``propagate_grid()`` methods of the
+  adaptive integrators now require the first element of the
+  time grid to be equal to the current integrator time
+  (`#154 <https://github.com/bluescarni/heyoka.py/pull/154>`__).
+  This is a :ref:`breaking change <bchanges_4_0_0>`.
 - The binary wheels are now built on top of ``manylinux2014``
   (`#153 <https://github.com/bluescarni/heyoka.py/pull/153>`__).
 - heyoka.py now requires C++20 when building from source

diff --git a/doc/notebooks/The adaptive integrator.ipynb b/doc/notebooks/The adaptive integrator.ipynb
@@ -47,6 +47,7 @@
     {
      "data": {
       "text/plain": [
+       "C++ datatype            : double\n",
        "Tolerance               : 2.220446049250313e-16\n",
        "High accuracy           : false\n",
        "Compact mode            : false\n",
@@ -149,6 +150,7 @@
     {
      "data": {
       "text/plain": [
+       "C++ datatype            : double\n",
        "Tolerance               : 2.220446049250313e-16\n",
        "High accuracy           : false\n",
        "Compact mode            : false\n",
@@ -438,6 +440,7 @@
       "Num. of steps: 97\n",
       "Current time : 0.0\n",
       "\n",
+      "C++ datatype            : double\n",
       "Tolerance               : 2.220446049250313e-16\n",
       "High accuracy           : false\n",
       "Compact mode            : false\n",
@@ -592,10 +595,11 @@
      "data": {
       "text/plain": [
        "(<taylor_outcome.time_limit: -4294967299>,\n",
-       " 0.20291845444801257,\n",
-       " 0.216140019757225,\n",
+       " 0.2021425243240425,\n",
+       " 0.21605277478009474,\n",
        " 5,\n",
-       " array([[ 0.05003035, -0.024398  ],\n",
+       " array([[ 0.05      ,  0.025     ],\n",
+       "        [ 0.05003035, -0.024398  ],\n",
        "        [ 0.04519961, -0.07142727],\n",
        "        [ 0.03597685, -0.11152037],\n",
        "        [ 0.02325783, -0.14078016],\n",
@@ -619,7 +623,7 @@
     "\n",
     "# Propagate over a time grid from 0 to 1\n",
     "# at regular intervals.\n",
-    "out = ta.propagate_grid(grid = [.1, .2, .3, .4, .5, .6, .7, .8, .9, 1.])\n",
+    "out = ta.propagate_grid(grid = [0., .1, .2, .3, .4, .5, .6, .7, .8, .9, 1.])\n",
     "out"
    ]
   },
@@ -656,8 +660,8 @@
     }
    ],
    "source": [
-    "# Print the state at t = 0.4 (index 3 in the time grid).\n",
-    "print(\"State at t = 0.4: {}\".format(out[4][3]))"
+    "# Print the state at t = 0.4 (index 4 in the time grid).\n",
+    "print(\"State at t = 0.4: {}\".format(out[4][4]))"
    ]
   },
   {
@@ -667,7 +671,17 @@
    "source": [
     "As you can see from the screen output above (where we printed the ``out`` variable), the use of ``propagate_grid()`` resulted in 5 integration timesteps being taken. Had we used ``propagate_until()``, we would have needed 10 integration timesteps to obtain the same result.\n",
     "\n",
-    "There are no special requirements on the time values in the grid (apart from the fact that they must be finite and ordered monotonically).\n",
+    "There are a few requirements on the time values in the grid:\n",
+    "\n",
+    "- they must all be finite,\n",
+    "- they must be ordered monotonically,\n",
+    "- the first value in the grid must be equal to the current\n",
+    "  time of the integrator.\n",
+    "\n",
+    "```{versionchanged} 4.0.0\n",
+    "\n",
+    "The requirement on the first value of the time grid.\n",
+    "```\n",
     "\n",
     "The ``propagate_grid()`` method\n",
     "can be invoked with additional optional keyword arguments:\n",
@@ -713,6 +727,7 @@
     "    \n",
     "    return True\n",
     "\n",
+    "ta.propagate_until(1.1)\n",
     "ta.propagate_grid(grid = [1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 2.],\n",
     "                  max_delta_t = .1, callback = cb);"
    ]
@@ -758,6 +773,7 @@
     "    def pre_hook(self, ta):\n",
     "        print(\"pre_hook() invoked!\")\n",
     "\n",
+    "ta.propagate_until(1.1)\n",
     "ta.propagate_grid(grid = [1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 2.],\n",
     "                  max_delta_t = .1, callback = cb());"
    ]
@@ -779,7 +795,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.6"
+   "version": "3.10.13"
   }
  },
  "nbformat": 4,