Merge pull request #155 from bluescarni/pr/heyoka_updates

New step callback API

.clang-tidy

@@ -1,5 +1,5 @@
 ---
-Checks:          'clang-diagnostic-*,clang-analyzer-*,*,-hicpp-uppercase-literal-suffix,-readability-uppercase-literal-suffix,-modernize-use-trailing-return-type,-readability-named-parameter,-hicpp-named-parameter,-cppcoreguidelines-pro-bounds-array-to-pointer-decay,-hicpp-no-array-decay,-llvm-header-guard,-cppcoreguidelines-macro-usage,-google-runtime-references,-readability-isolate-declaration,-fuchsia-default-arguments-calls,-fuchsia-overloaded-operator,-fuchsia-default-arguments-declarations,-readability-else-after-return,-google-runtime-int,-hicpp-signed-bitwise,-cert-dcl21-cpp,-cppcoreguidelines-avoid-magic-numbers,-readability-magic-numbers,-cppcoreguidelines-pro-bounds-pointer-arithmetic,-cppcoreguidelines-pro-type-reinterpret-cast,-cppcoreguidelines-avoid-c-arrays,-hicpp-avoid-c-arrays,-modernize-avoid-c-arrays,-modernize-use-transparent-functors,-cert-dcl16-c,-cppcoreguidelines-pro-type-union-access,-bugprone-branch-clone,-fuchsia-statically-constructed-objects,-cppcoreguidelines-pro-bounds-constant-array-index,-readability-static-accessed-through-instance,-cppcoreguidelines-pro-type-vararg,-hicpp-vararg,-llvmlibc-restrict-system-libc-headers,-llvmlibc-callee-namespace,-llvmlibc-implementation-in-namespace,-llvm-else-after-return,-fuchsia-trailing-return,-readability-identifier-length,-altera-unroll-loops,-altera-id-dependent-backward-branch,-altera-struct-pack-align'
+Checks:          'clang-diagnostic-*,clang-analyzer-*,*,-hicpp-uppercase-literal-suffix,-readability-uppercase-literal-suffix,-modernize-use-trailing-return-type,-readability-named-parameter,-hicpp-named-parameter,-cppcoreguidelines-pro-bounds-array-to-pointer-decay,-hicpp-no-array-decay,-llvm-header-guard,-cppcoreguidelines-macro-usage,-google-runtime-references,-readability-isolate-declaration,-fuchsia-default-arguments-calls,-fuchsia-overloaded-operator,-fuchsia-default-arguments-declarations,-readability-else-after-return,-google-runtime-int,-hicpp-signed-bitwise,-cert-dcl21-cpp,-cppcoreguidelines-avoid-magic-numbers,-readability-magic-numbers,-cppcoreguidelines-pro-bounds-pointer-arithmetic,-cppcoreguidelines-pro-type-reinterpret-cast,-cppcoreguidelines-avoid-c-arrays,-hicpp-avoid-c-arrays,-modernize-avoid-c-arrays,-modernize-use-transparent-functors,-cert-dcl16-c,-cppcoreguidelines-pro-type-union-access,-bugprone-branch-clone,-fuchsia-statically-constructed-objects,-cppcoreguidelines-pro-bounds-constant-array-index,-readability-static-accessed-through-instance,-cppcoreguidelines-pro-type-vararg,-hicpp-vararg,-llvmlibc-restrict-system-libc-headers,-llvmlibc-callee-namespace,-llvmlibc-implementation-in-namespace,-llvm-else-after-return,-fuchsia-trailing-return,-readability-identifier-length,-altera-unroll-loops,-altera-id-dependent-backward-branch,-altera-struct-pack-align,-performance-no-int-to-ptr,-readability-function-cognitive-complexity,-misc-include-cleaner,-llvmlibc-inline-function-decl'
 WarningsAsErrors: '*'
 AnalyzeTemporaryDtors: false
 FormatStyle:     none

doc/breaking_changes.rst

@@ -13,6 +13,30 @@ heyoka.py 4 includes several backwards-incompatible changes.
 API/behaviour changes
 ~~~~~~~~~~~~~~~~~~~~~
 
+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:
+
+- for the scalar ``propagate_for()`` and ``propagate_until()`` methods, the step callback is
+  the sixth element of the return tuple, while for the batch variants the step callback
+  is the second element of the return tuple;
+- for the scalar ``propagate_grid()`` method, the step callback is the fifth element of the return
+  tuple, while for the batch variant the step callback is the first element of the return
+  tuple.
+
+:ref:`The ensemble propagation <ensemble_prop>` functions have been modified in an analogous way.
+
+Adapting existing code for the new API should be straightforward. In most cases it should be just
+a matter of:
+
+- adapting unpacking declarations to account for the new element in the return tuple
+  of scalar propagations,
+- adjusting the indexing into the return tuple when fetching a specific element,
+- accounting for the fact that batch propagations now return a tuple of two elements
+  rather than a single value.
+
 ``propagate_grid()``
 ^^^^^^^^^^^^^^^^^^^^
 

doc/changelog.rst

@@ -6,9 +6,24 @@ Changelog
 4.0.0 (unreleased)
 ------------------
 
+New
+~~~
+
+- It is now possible to pass a list of step callbacks to the
+  ``propagate_*()`` functions
+  (`#155 <https://github.com/bluescarni/heyoka.py/pull/155>`__).
+- New ``angle_reducer`` step callback to automatically reduce
+  angular state variables to the :math:`\left[0, 2\pi\right)` range
+  (`#155 <https://github.com/bluescarni/heyoka.py/pull/155>`__).
+
 Changes
 ~~~~~~~
 
+- **BREAKING**: the ``propagate_*()`` functions
+  now return the (optional) step callback that can be
+  passed in input
+  (`#155 <https://github.com/bluescarni/heyoka.py/pull/155>`__).
+  This is a :ref:`breaking change <bchanges_4_0_0>`.
 - **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

doc/notebooks/Planetary embryos.ipynb

@@ -320,7 +320,7 @@
     "# up to 10000 years.\n",
     "final_t = 10000.\n",
     "t_grid = np.linspace(0, final_t, 10000)\n",
-    "_, _, _, _, out = ta.propagate_grid(t_grid, callback = cb(final_t))"
+    "_, _, _, _, _, out = ta.propagate_grid(t_grid, callback = cb(final_t))"
    ]
   },
   {