New tutorial, small docs reorg, docs for the pendulum model.

doc/api_model.rst

@@ -15,3 +15,4 @@ Functions
    nrlmsise00_tn
    jb08_tn
    fixed_centres
+   pendulum

doc/examples_astro.rst

@@ -43,4 +43,3 @@ Celestial mechanics and astrodynamics
   notebooks/tides_spokes
   notebooks/lagrangian_propagator
   notebooks/gg_stab
-  notebooks/learning_mascons

doc/examples_var_ode_sys.rst

@@ -0,0 +1,30 @@
+.. _examples_var_ode_sys:
+
+Variational equations
+=====================
+
+.. only:: html
+
+  .. important::
+
+     .. raw:: html
+
+        <p>
+        Most of these examples can be launched as online interactive notebooks
+        thanks to the infrastructure provided by <a href="https://mybinder.org/">binder</a>.
+        Look for the rocket icon <i class="fas fa-rocket"></i> on top of each page!
+        </p>
+
+  .. important::
+
+     Some examples may use features not available yet in the latest stable release
+     of heyoka.py, and thus might fail to execute correctly in the online interactive
+     notebooks. Please refer to the :ref:`changelog <changelog>` for an overview of
+     the features currently
+     available only in the development version of heyoka.py.
+
+.. toctree::
+  :maxdepth: 1
+
+  notebooks/tmap_pendulum
+  notebooks/learning_mascons

doc/index.md

@@ -100,6 +100,7 @@ advanced_tutorials
 examples_astro
 examples_event
 examples_ml
+examples_var_ode_sys
 examples_others
 ```
 

heyoka/docstrings.cpp

@@ -706,4 +706,28 @@ Several checks are run on the input arguments:
 )";
 }
 
+std::string pendulum()
+{
+    return R"(pendulum(gconst: expression | str | numpy.single | float | numpy.longdouble = 1., length: expression | str | numpy.single | float | numpy.longdouble = 1.) -> list[tuple[expression, expression]]
+
+Produces the expression for the dynamics of the simple pendulum.
+
+The gravitational constant is *gconst*, while the length of the pendulum is *length*.
+In the return value, the angle with respect to the downwards vertical is represented by
+the state variable ``x``, while its time derivative is represented by the state
+variable ``v``.
+
+:param gconst: the gravitational constant.
+:param length: the length of the pendulum.
+
+:returns: the dynamics of the simple pendulum.
+
+Examples:
+  >>> from heyoka import model
+  >>> model.pendulum()
+  [(x, v), (v, -sin(x))]
+
+)";
+}
+
 } // namespace heyoka_py::docstrings

heyoka/docstrings.hpp

@@ -49,6 +49,7 @@ std::string cart2geo();
 std::string nrlmsise00_tn();
 std::string jb08_tn();
 std::string fixed_centres();
+std::string pendulum();
 
 // var_ode_sys() and related.
 std::string var_args();

heyoka/expose_models.cpp

@@ -262,7 +262,7 @@ void expose_models(py::module_ &m)
     m.def(
         "_model_pendulum",
         [](const vex_t &gconst, const vex_t &l) { return detail::pendulum_impl(hy::model::pendulum, gconst, l); },
-        "gconst"_a.noconvert() = 1., "length"_a.noconvert() = 1.);
+        "gconst"_a.noconvert() = 1., "length"_a.noconvert() = 1., docstrings::pendulum().c_str());
     m.def(
         "_model_pendulum_energy",
         [](const vex_t &gconst, const vex_t &l) {