Merge pull request #177 from bluescarni/pr/var_ode_sys

Variational ODEs

README.md

@@ -43,6 +43,8 @@ compilation via [LLVM](https://llvm.org/). Notable features include:
 * accurate and reliable event detection,
 * builtin support for analytical mechanics - bring your own Lagrangians/Hamiltonians
   and let heyoka.py formulate and solve the equations of motion,
+* builtin support for high-order variational equations - compute not only the solution,
+  but also its partial derivatives,
 * builtin support for machine learning applications via neural network models,
 * the ability to maintain machine precision accuracy over
   tens of billions of timesteps,

doc/api_exsys.rst

@@ -34,6 +34,7 @@ Attributes
    :toctree: autosummary_generated
 
    par
+   time
 
 Enums
 -----

doc/api_var_ode_sys.rst

@@ -0,0 +1,24 @@
+.. _api_var_ode_sys:
+
+Variational ODE systems
+=======================
+
+.. currentmodule:: heyoka
+
+Classes
+-------
+
+.. autosummary::
+   :toctree: autosummary_generated
+   :template: custom-class-template.rst
+
+   var_ode_sys
+
+Enums
+-----
+
+.. autosummary::
+   :toctree: autosummary_generated
+   :template: custom-enum-template.rst
+
+   var_args

doc/basic_tutorials.rst

@@ -34,3 +34,4 @@ Basic
   notebooks/Non-autonomous systems.ipynb
   notebooks/Dense output.ipynb
   notebooks/Event detection
+  notebooks/var_ode_sys.ipynb

doc/changelog.rst

@@ -9,6 +9,11 @@ Changelog
 New
 ~~~
 
+- Add support for variational ODE systems and Taylor map computation
+  (`#177 <https://github.com/bluescarni/heyoka.py/pull/177>`__).
+- Add thermonets: neural, differentiable, high-performance
+  models for the Earth's thermosphere density
+  (`#176 <https://github.com/bluescarni/heyoka.py/pull/176>`__).
 - Add a vectorised implementation of ``diff()``
   (`#173 <https://github.com/bluescarni/heyoka.py/pull/173>`__).
 

doc/index.md

@@ -16,6 +16,8 @@ compilation via [LLVM](https://llvm.org/). Notable features include:
 - accurate and reliable event detection,
 - builtin support for analytical mechanics - bring your own Lagrangians/Hamiltonians
   and let heyoka.py formulate and solve the equations of motion,
+- builtin support for high-order variational equations - compute not only the solution,
+  but also its partial derivatives,
 - builtin support for machine learning applications via neural network models,
 - the ability to maintain machine precision accuracy over
   tens of billions of timesteps,
@@ -107,6 +109,7 @@ examples_others
 
 api_exsys
 api_integrators
+api_var_ode_sys
 api_lagham
 api_model
 ```

doc/notebooks/Batch mode overview.ipynb

@@ -22,10 +22,10 @@
     "It is important to emphasise that batch mode does not reduce\n",
     "the CPU time required to integrate a system of ODEs. Rather, as a fine-grained\n",
     "form of data parallelism, batch mode allows to integrate multiple ODE systems in parallel\n",
-    "at no additional cost, and it is thus most useful when the need arise\n",
+    "at (almost) no additional cost, and it is thus most useful when the need arise\n",
     "to integrate the same ODE system with different initial conditions and parameters.\n",
     "\n",
-    "Although batch mode can in principle be used with all floating-point types supported\n",
+    "Although batch mode can in principle be used with all the fundamental C++ floating-point types supported\n",
     "by heyoka.py, in practice at this time no CPU provides SIMD instructions for extended-precision\n",
     "datatypes. Thus, heyoka.py currently enables batch mode only for single and double precision\n",
     "computations. Specifically, in this tutorial we will consider the application of batch mode to\n",

doc/notebooks/Customising the adaptive integrator.ipynb

@@ -128,6 +128,8 @@
    "id": "national-investing",
    "metadata": {},
    "source": [
+    "(ta_compact_mode)=\n",
+    "\n",
     "Compact mode\n",
     "------------\n",
     "\n",
@@ -290,7 +292,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.6"
+   "version": "3.10.13"
   }
  },
  "nbformat": 4,

doc/notebooks/The variational equations.ipynb

@@ -5,12 +5,17 @@
    "id": "excited-uganda",
    "metadata": {},
    "source": [
+    "```{note}\n",
+    "\n",
+    "Starting with version 5.0.0, heyoka.py features builtin support for the formulation of the [variational equations](./var_ode_sys.ipynb). This tutorial is now deprecated and it will be removed in a future version.\n",
+    "\n",
+    "```\n",
+    "\n",
     "The variational equations\n",
     "=========================\n",
     "\n",
     "In this tutorial, we will show how it is possible to exploit heyoka.py's [expression system](<./The expression system.ipynb>) to implement first-order variational equations for a system of ODEs.\n",
     "\n",
-    "\n",
     "First, let's start with a brief recap on the variational equations. For simplicity, we will consider an autonomous ODE system in the variables $x$ and $y$ (the extension to more variables just complicates the notation):\n",
     "\n",
     "$$\n",
@@ -292,7 +297,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.13"
+   "version": "3.10.13"
   }
  },
  "nbformat": 4,

doc/notebooks/ensemble_mode.ipynb

@@ -9,6 +9,10 @@
     "\n",
     "# Ensemble propagations\n",
     "\n",
+    "```{versionadded} 0.17.0\n",
+    "\n",
+    "```\n",
+    "\n",
     "Starting with version 0.17.0, heyoka.py offers support for\n",
     "*ensemble propagations*. In ensemble mode, multiple distinct\n",
     "instances of the same ODE system are integrated in parallel,\n",