heyoka updates

doc/api_exsys.rst

@@ -9,3 +9,4 @@ Expression system
    :toctree: autosummary_generated
 
    expression
+   make_vars

doc/breaking_changes.rst

@@ -13,6 +13,22 @@ heyoka.py 4 includes several backwards-incompatible changes.
 API/behaviour changes
 ~~~~~~~~~~~~~~~~~~~~~
 
+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")
+
+needs to be rewritten like this:
+
+.. code-block:: python
+
+    x = make_vars("x")
+
 Terminal events callbacks
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 

doc/changelog.rst

@@ -25,6 +25,11 @@ New
 Changes
 ~~~~~~~
 
+- **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
+  (`#161 <https://github.com/bluescarni/heyoka.py/pull/161>`__).
+  This is a :ref:`breaking change <bchanges_4_0_0>`.
 - **BREAKING**: the signature of callbacks for terminal events
   has been simplified
   (`#158 <https://github.com/bluescarni/heyoka.py/pull/158>`__).

doc/notebooks/Box control for Formation Flying Satellites.ipynb

@@ -170,7 +170,7 @@
    "outputs": [],
    "source": [
     "# The state (using km as unit length)\n",
-    "xC, yC, zC, vxC, vyC, vzC, xD, yD, zD, vxD, vyD, vzD, = hy.make_vars(\"xC\", \"yC\", \"zC\", \"vxC\", \"vyC\", \"vzC\", \"xD\", \"yD\", \"zD\", \"vxD\", \"vyD\", \"vzD\")\n",
+    "xC, yC, zC, vxC, vyC, vzC, xD, yD, zD, vxD, vyD, vzD = hy.make_vars(\"xC\", \"yC\", \"zC\", \"vxC\", \"vyC\", \"vzC\", \"xD\", \"yD\", \"zD\", \"vxD\", \"vyD\", \"vzD\")\n",
     "\n",
     "# Parameters\n",
     "mu = 398600.4418 #km^3/sec^2 \n",

doc/notebooks/Comparing coordinate systems.ipynb

@@ -864,7 +864,7 @@
     "\n",
     "# Additional dynamical variable to\n",
     "# integrate t(tau).\n",
-    "t, = hy.make_vars(\"t\")\n",
+    "t = hy.make_vars(\"t\")\n",
     "\n",
     "ta_del_e = hy.taylor_adaptive(\n",
     "    [(L, dL_dt*dt_dtau),\n",

doc/notebooks/Optimal Control of the Lotka-Volterra equations.ipynb

@@ -93,7 +93,7 @@
     "lx, ly = hy.make_vars(\"lambda_x\", \"lambda_y\")\n",
     "\n",
     "# the control\n",
-    "u, = hy.make_vars(\"u\")\n",
+    "u = hy.make_vars(\"u\")\n",
     "\n",
     "# and the dynamics fx, fy\n",
     "fx = hy.par[0]*x - hy.par[1]*x*y - x * hy.par[4] * u\n",

doc/notebooks/definite_integrals.ipynb

@@ -58,7 +58,7 @@
    ],
    "source": [
     "import heyoka as hy, numpy as np\n",
-    "x, = hy.make_vars(\"x\")\n",
+    "x = hy.make_vars(\"x\")\n",
     "\n",
     "# Integrate sin(t) between 0 and pi.\n",
     "ta = hy.taylor_adaptive([(x, hy.sin(hy.time))], [0.])\n",
@@ -161,7 +161,7 @@
     {
      "data": {
       "text/plain": [
-       "-0.012382281847117878"
+       "-0.012382281847117866"
       ]
      },
      "execution_count": 4,
@@ -260,7 +260,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.13"
+   "version": "3.10.13"
   }
  },
  "nbformat": 4,

doc/notebooks/ffnn.ipynb

@@ -61,7 +61,7 @@
    ],
    "source": [
     "# We create the symbols for the network inputs (only one in this first simple case)\n",
-    "x, = hy.make_vars(\"x\")\n",
+    "x = hy.make_vars(\"x\")\n",
     "\n",
     "# We define as nonlinearity a simple linear layer\n",
     "linear = lambda inp: inp\n",

heyoka/_test_expression.py

@@ -12,6 +12,7 @@
 class expression_test_case(_ut.TestCase):
     def test_basic(self):
         from . import expression as ex, core
+        from . import make_vars
         import numpy as np
 
         with_real128 = hasattr(core, "real128")
@@ -20,6 +21,24 @@ def test_basic(self):
         if with_real128:
             real128 = core.real128
 
+        # Minimal make_vars() testing.
+        with self.assertRaises(ValueError) as cm:
+            make_vars()
+        self.assertTrue(
+            "At least one argument is required when invoking 'make_vars()'"
+            in str(cm.exception)
+        )
+
+        x = make_vars("x")
+        self.assertTrue(isinstance(x, ex))
+        self.assertEqual(x, ex("x"))
+
+        l = make_vars("x", "y")
+        self.assertTrue(isinstance(l, list))
+        x, y = l
+        self.assertEqual(x, ex("x"))
+        self.assertEqual(y, ex("y"))
+
         # Constructors.
         self.assertEqual(ex(), ex(0))
         self.assertEqual(ex(123), ex(123.0))

heyoka/docstrings.cpp

@@ -13,6 +13,26 @@
 namespace heyoka_py::docstrings
 {
 
+std::string make_vars()
+{
+    return R"(make_vars(*args: str) -> expression | list[expression]
+
+Create expressions from strings.
+
+This function will return one or more :py:class:`~heyoka.expression`
+instances constructed from the input arguments. If a single argument
+is supplied, a single expression is returned. Otherwise, a list of
+expressions (one for each argument) is returned.
+
+:param args: the input string(s).
+
+:returns: one or more expressions constructed from *args*.
+
+:raises ValueError: if the number of *args* is zero.
+
+)";
+}
+
 std::string lagrangian()
 {
     return R"(lagrangian(L: expression, qs: list[expression], qdots: list[expression], D: expression = expression(0.)) -> list[tuple[expression, expression]]

heyoka/docstrings.hpp

@@ -14,6 +14,9 @@
 namespace heyoka_py::docstrings
 {
 
+// Expression system.
+std::string make_vars();
+
 // Lagrangian/Hamiltonian mechanics.
 std::string lagrangian();
 std::string hamiltonian();

heyoka/expose_expression.cpp

@@ -50,6 +50,7 @@
 
 #include "common_utils.hpp"
 #include "custom_casters.hpp"
+#include "docstrings.hpp"
 #include "pickle_wrappers.hpp"
 
 namespace heyoka_py
@@ -319,13 +320,24 @@ void expose_expression(py::module_ &m)
         "arg"_a);
 
     // make_vars() helper.
-    m.def("make_vars", [](const py::args &v_str) {
-        py::list retval;
-        for (auto o : v_str) {
-            retval.append(hey::expression(py::cast<std::string>(o)));
-        }
-        return retval;
-    });
+    m.def(
+        "make_vars",
+        [](const py::args &v_str) -> std::variant<hey::expression, py::list> {
+            if (py::len(v_str) == 0u) {
+                py_throw(PyExc_ValueError, "At least one argument is required when invoking 'make_vars()'");
+            }
+
+            if (py::len(v_str) == 1u) {
+                return hey::expression(py::cast<std::string>(v_str[0]));
+            }
+
+            py::list retval;
+            for (auto o : v_str) {
+                retval.append(hey::expression(py::cast<std::string>(o)));
+            }
+            return retval;
+        },
+        docstrings::make_vars().c_str());
 
     // Math functions.