Update Sphinx documentation, commit 30516ee [skip ci].

_sources/breaking_changes.rst

@@ -13,6 +13,21 @@ heyoka.py 4 includes several backwards-incompatible changes.
 API/behaviour changes
 ~~~~~~~~~~~~~~~~~~~~~
 
+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
+heyoka.py would try to automatically infer a list of variables from other
+input arguments, turned out to be in practice confusing and a source of bugs.
+
+The affected APIs include:
+
+- :ref:`compiled functions <cfunc_tut>`, which now require the list of input
+  variables to be always supplied by the user.
+
+The tutorials and the documentation have been updated accordingly.
+
 Changes to :py:func:`~heyoka.make_vars()`
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -64,8 +79,8 @@ a matter of:
 - accounting for the fact that batch propagations now return a tuple of two elements
   rather than a single value.
 
-``propagate_grid()``
-^^^^^^^^^^^^^^^^^^^^
+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

_sources/changelog.rst

@@ -25,6 +25,10 @@ New
 Changes
 ~~~~~~~
 
+- **BREAKING**: :ref:`compiled functions <cfunc_tut>` now require
+  the list of input variables to be always supplied by the user
+  (`#162 <https://github.com/bluescarni/heyoka.py/pull/162>`__).
+  This is a :ref:`breaking change <bchanges_4_0_0>`.
 - **BREAKING**: 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

_sources/notebooks/The Keplerian billiard.ipynb

@@ -238,7 +238,7 @@
    "id": "1cdc3adb",
    "metadata": {},
    "source": [
-    "We can now produce a fancy animation of the Keplerian billiard (inspired from [here](http://louistiao.me/posts/notebooks/embedding-matplotlib-animations-in-jupyter-as-interactive-javascript-widgets/)):"
+    "We can now produce a fancy animation of the Keplerian billiard:"
    ]
   },
   {

_sources/notebooks/arbitrary_precision.ipynb

@@ -634,7 +634,8 @@
     "sym_func = x**2-y**2\n",
     "\n",
     "# Compile it.\n",
-    "cf = hy.make_cfunc([sym_func], fp_type=real, prec=prec)"
+    "cf = hy.make_cfunc([sym_func], [x, y],\n",
+    "                   fp_type=real, prec=prec)"
    ]
   },
   {

_sources/notebooks/compiled_functions.ipynb

@@ -57,7 +57,12 @@
    "id": "68861247-8ac9-42a3-bf58-b893282ccdf7",
    "metadata": {},
    "source": [
-    "We can now proceed to JIT compile ``sym_func`` via the ``make_cfunc()`` function. ``make_cfunc()`` takes as a mandatory input argument the list of symbolic expressions representing the outputs of a vector function. In this case, we only have a single output, ``sym_func``:"
+    "We can now proceed to JIT compile ``sym_func`` via the ``make_cfunc()`` function. ``make_cfunc()`` takes two mandatory input arguments:\n",
+    "\n",
+    "- the list of symbolic expressions representing the outputs of the vector function, and\n",
+    "- the list of symbolic variables representing the inputs of the function.\n",
+    "\n",
+    "In this case, we only have a single output, ``sym_func``, and two inputs, ``x`` and ``y``:"
    ]
   },
   {
@@ -67,7 +72,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "cf = hy.make_cfunc([sym_func])"
+    "cf = hy.make_cfunc([sym_func], [x, y])"
    ]
   },
   {
@@ -90,24 +95,23 @@
        "array([-24.])"
       ]
      },
-     "execution_count": 4,
+     "execution_count": 8,
      "metadata": {},
      "output_type": "execute_result"
     }
    ],
    "source": [
     "# Evaluate for x=1 and y=5.\n",
-    "cf([1,5])"
+    "cf([1, 5])"
    ]
   },
   {
    "cell_type": "markdown",
    "id": "08652425-9b2f-4ed1-b3ee-fb48154a79a0",
    "metadata": {},
    "source": [
-    "The value returned by ``cf`` is also a NumPy array containing the outputs of the compiled function. In this specific case, we have a single output and thus an array with a single element is returned.\n",
-    "\n",
-    "Because when we created ``cf`` we passed only the list of output expressions to ``make_cfunc()``, heyoka.py used lexicographic ordering to infer the order of the input variables during evaluation: $x$ is the first variable, $y$ is the second. This can be confirmed by examining the screen output of the ``cf`` object:"
+    "Note that we passed as first element in the list the value for ``x`` and then, as second element, the value for ``y``. This is because when we created ``cf`` we specified ``[x, y]`` (in that order) as the inputs for the function.\n",
+    "This can be confirmed by examining the screen output of the ``cf`` object:"
    ]
   },
   {
@@ -119,8 +123,9 @@
     {
      "data": {
       "text/plain": [
+       "C++ datatype: double\n",
        "Variables: [x, y]\n",
-       "Output #0: (x**2 - y**2)"
+       "Output #0: (x**2.0000000000000000 - y**2.0000000000000000)"
       ]
      },
      "execution_count": 5,
@@ -137,7 +142,7 @@
    "id": "5d8d47e9-8697-41b4-9adf-280cbf2b8103",
    "metadata": {},
    "source": [
-    "If you don't want to rely on the default lexicographic ordering, you can pass to ``make_cfunc()`` an explicit ordering for the input variables:"
+    "Any other ordering for the input variables is possible:"
    ]
   },
   {
@@ -152,14 +157,12 @@
        "array([-24.])"
       ]
      },
-     "execution_count": 6,
+     "execution_count": 10,
      "metadata": {},
      "output_type": "execute_result"
     }
    ],
    "source": [
-    "# Explicitly specify the order of the input variables:\n",
-    "# first y, then x.\n",
     "cf2 = hy.make_cfunc([sym_func], vars=[y,x])\n",
     "\n",
     "# Evaluate for x=1 and y=5.\n",
@@ -183,8 +186,9 @@
     {
      "data": {
       "text/plain": [
+       "C++ datatype: double\n",
        "Variables: [y, x]\n",
-       "Output #0: (x**2 - y**2)"
+       "Output #0: (x**2.0000000000000000 - y**2.0000000000000000)"
       ]
      },
      "execution_count": 7,
@@ -201,7 +205,7 @@
    "id": "43f895e7-2da5-440d-84f8-1932d5a9d1fc",
    "metadata": {},
    "source": [
-    "``make_cfunc()`` accepts additional keyword arguments, the most important of which is the boolean flag ``compact_mode`` (defaulting to ``False``). Similarly to the [adaptive Taylor integrators](<./Customising the adaptive integrator.ipynb>), you should enable ``compact_mode`` if you want to compile extremely large symbolic expressions that result in excessively long compilation times. The downside of ``compact_mode`` is a slight performance degradation due to the different code generation model adopted during the JIT compilation process.\n",
+    "``make_cfunc()`` accepts several additional keyword arguments, the most important of which is the boolean flag ``compact_mode`` (defaulting to ``False``). Similarly to the [adaptive Taylor integrators](<./Customising the adaptive integrator.ipynb>), you should enable ``compact_mode`` if you want to compile extremely large symbolic expressions that result in excessively long compilation times. The downside of ``compact_mode`` is a slight performance degradation due to the different code generation model adopted during the JIT compilation process.\n",
     "\n",
     "The function object returned by ``make_cfunc()`` also accepts several optional keyword arguments. It is possible, for instance, to pass as ``outputs`` argument a pre-allocated NumPy array into which the result of the evaluation will be written. This is useful to avoid the overhead of allocating new memory for the return value, if such memory is already available:"
    ]
@@ -269,7 +273,7 @@
     "sym_func_par = hy.par[0]*x**2-hy.par[1]*y**2+hy.par[2]\n",
     "\n",
     "# Compile it.\n",
-    "cf_par = hy.make_cfunc([sym_func_par])\n",
+    "cf_par = hy.make_cfunc([sym_func_par], [x, y])\n",
     "\n",
     "# Evaluate, specifying the parameter values\n",
     "cf_par([1,5], pars=[-1, -2, -3])"
@@ -311,7 +315,7 @@
     "sym_func_tm = x**2-y**2+hy.time\n",
     "\n",
     "# Compile it.\n",
-    "cf_tm = hy.make_cfunc([sym_func_tm])\n",
+    "cf_tm = hy.make_cfunc([sym_func_tm], [x, y])\n",
     "\n",
     "# Evaluate for x=1, y=5 and time=6.\n",
     "cf_tm([1,5], time=6)"

_sources/notebooks/computing_derivatives.ipynb

@@ -442,7 +442,7 @@
     }
    ],
    "source": [
-    "grad_diff_cf = hy.make_cfunc(grad_diff)\n",
+    "grad_diff_cf = hy.make_cfunc(grad_diff, sym_vars)\n",
     "grad_diff_cf.decomposition[8:-8]"
    ]
   },
@@ -527,7 +527,7 @@
     }
    ],
    "source": [
-    "grad_diff_tensors_cf = hy.make_cfunc(grad_diff_tensors)\n",
+    "grad_diff_tensors_cf = hy.make_cfunc(grad_diff_tensors, sym_vars)\n",
     "grad_diff_tensors_cf.decomposition[8:-8]"
    ]
   },
@@ -564,7 +564,7 @@
     "    sym_vars = [hy.expression(f\"x_{i}\") for i in range(1, nvars+1)]\n",
     "    sp_func = hy.prod(sym_vars)\n",
     "    grad_diff_tensors = [t[1] for t in hy.diff_tensors([sp_func], diff_order=1).get_derivatives(1)]\n",
-    "    grad_diff_tensors_cf = hy.make_cfunc(grad_diff_tensors)\n",
+    "    grad_diff_tensors_cf = hy.make_cfunc(grad_diff_tensors, sym_vars)\n",
     "    nops.append(len(grad_diff_tensors_cf.decomposition) - 2*nvars)\n",
     "\n",
     "%matplotlib inline\n",

_sources/notebooks/elp2000.ipynb

@@ -230,7 +230,7 @@
     "                                                            thresh=thr)\n",
     "\n",
     "    # Compile the function for the evaluation of moon_x/y/z.\n",
-    "    moon_cf = hy.make_cfunc([moon_x, moon_y, moon_z], compact_mode=True)\n",
+    "    moon_cf = hy.make_cfunc([moon_x, moon_y, moon_z], [tm], compact_mode=True)\n",
     "    \n",
     "    # Run the evaluation.\n",
     "    elp2000_states = moon_cf(dates.reshape((1,-1)))\n",

_sources/notebooks/ex_system_revisited.ipynb

@@ -499,7 +499,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "f_cf = hy.make_cfunc([x+y+1., x+y+z])"
+    "f_cf = hy.make_cfunc([x+y+1., x+y+z], [x, y, z])"
    ]
   },
   {
@@ -608,7 +608,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "f_cf_fix = hy.make_cfunc([hy.fix(x+y)+1., hy.fix(x+y)+z])"
+    "f_cf_fix = hy.make_cfunc([hy.fix(x+y)+1., hy.fix(x+y)+z],\n",
+    "                        [x, y, z])"
    ]
   },
   {
@@ -710,7 +711,7 @@
     }
    ],
    "source": [
-    "g_cf = hy.make_cfunc([2.0 * (x + y + z)])\n",
+    "g_cf = hy.make_cfunc([2.0 * (x + y + z)], [x, y, z])\n",
     "g_cf.decomposition"
    ]
   },
@@ -740,7 +741,8 @@
     }
    ],
    "source": [
-    "g_cf_fix = hy.make_cfunc([2.0 * hy.fix(x + y + z)])\n",
+    "g_cf_fix = hy.make_cfunc([2.0 * hy.fix(x + y + z)],\n",
+    "                        [x, y, z])\n",
     "g_cf_fix.decomposition"
    ]
   },