Doc/changelog updates.

doc/breaking_changes.rst

@@ -10,11 +10,23 @@ Breaking changes
 
 heyoka.py 4 includes several backwards-incompatible changes.
 
-API/behaviour changes
-~~~~~~~~~~~~~~~~~~~~~
+Changes to compiled functions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:ref:`Compiled functions <cfunc_tut>` have gained the ability to use multiple
+threads of execution during batched evaluations. As a consequence, compiled functions
+now require contiguous NumPy arrays to be passed as input/output arguments (whereas
+in previous heyoka.py versions compiled functions would work also with non-contiguous
+arrays). The NumPy function :py:func:`numpy.ascontiguousarray()` can be used to turn
+non-contiguous arrays into contiguous arrays.
+
+Compiled functions are now also stricter with respect to type conversions: if a NumPy
+array with the wrong datatype is passed as an input/output argument, an error will be raised
+(wheras previously heyoka.py would convert the array to the correct datatype on-the-fly).
+The NumPy method :py:meth:`numpy.ndarray.astype()` can be used for datatype conversions.
 
 A more explicit API
-^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~
 
 Several functions and classes have been changed to explicitly require
 the user to pass a list of variables in input. The previous behaviour, where
@@ -31,23 +43,25 @@ The affected APIs include:
 The tutorials and the documentation have been updated accordingly.
 
 Changes to :py:func:`~heyoka.make_vars()`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The :py:func:`~heyoka.make_vars()` function now returns a single expression (rather than a list of expressions)
 if a single argument is passed in input. This means that code such as
 
 .. code-block:: python
 
     x, = make_vars("x")
+    y = make_vars("y")[0]
 
 needs to be rewritten like this:
 
 .. code-block:: python
 
     x = make_vars("x")
+    y = make_vars("y")
 
 Terminal events callbacks
-^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The second argument in the signature of callbacks for terminal events, a ``bool`` conventionally
 called ``mr``, has been removed. This flag was meant to signal the possibility of multiple roots
@@ -58,7 +72,7 @@ Adapting existing code for this API change is straightforward: you just have to
 from the signature of a terminal event callback.
 
 Step callbacks and ``propagate_*()``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The step callbacks that can (optionally) be passed to the ``propagate_*()`` methods of the
 adaptive integrators are now part of the return value. Specifically:
@@ -82,7 +96,7 @@ a matter of:
   rather than a single value.
 
 Changes to ``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

doc/changelog.rst

@@ -9,6 +9,9 @@ Changelog
 New
 ~~~
 
+- Compiled functions now support multithreaded parallelisation
+  for batched evaluations
+  (`#168 <https://github.com/bluescarni/heyoka.py/pull/168>`__).
 - Add new example on gravity-gradient stabilisation
   (`#159 <https://github.com/bluescarni/heyoka.py/pull/159>`__).
 - Add support for Lagrangian and Hamiltonian mechanics
@@ -25,6 +28,11 @@ New
 Changes
 ~~~~~~~
 
+- **BREAKING**: compiled functions now require contiguous arrays
+  as input/output arguments. The compiled functions API is also now
+  more restrictive with respect to on-the-fly type conversions
+  (`#168 <https://github.com/bluescarni/heyoka.py/pull/168>`__).
+  These are :ref:`breaking changes <bchanges_4_0_0>`.
 - **BREAKING**: it is now mandatory to supply a list of differentiation
   arguments to :func:`~heyoka.diff_tensors()`
   (`#164 <https://github.com/bluescarni/heyoka.py/pull/164>`__).

doc/notebooks/compiled_functions.ipynb

@@ -246,6 +246,17 @@
    "id": "4bea5b7b-ab72-47cf-a2dd-7f944248992b",
    "metadata": {},
    "source": [
+    "```{warning}\n",
+    "\n",
+    "The ability to pass lists and other iterables as input/output arguments\n",
+    "to a compiled function is offered as a convenience, but it incurs into a runtime\n",
+    "cost as compiled functions need to convert the iterables into NumPy arrays\n",
+    "on-the-fly before performing the evaluation.\n",
+    "\n",
+    "For optimal performance, consider passing NumPy arrays to the call operator\n",
+    "of compiled functions in order to avoid this hidden cost.\n",
+    "```\n",
+    "\n",
     "## Functions with parameters\n",
     "\n",
     "It the compiled function references [external parameters](<./ODEs with parameters.ipynb>), the parameters array will have to be supplied during evaluation via the ``pars`` keyword argument:"