docs(kepler2d): add tutorial for Kepler2D; improve docstring of Kepler2D

#82

docs/tutorials/kepler_problem.py

@@ -22,13 +22,56 @@
 # ## Usage
 
 # %%
+import numpy as np
+import plotly.express as px
 
+from hamilflow.models.kepler_problem import Kepler2D
+
+# %% [markdown]
+# To make it easy to use the Kepler system, we implemented an interface `Kepler2D.from_geometry` to specify the configuration using the geometry of the orbit. The geometry of the orbit requires three parameters:
+#
+# - `positive_angular_mom`: whether the angular momentum is positive
+# - `ecc`: the eccentricity of the orbit
+# - `parameter`: the semi-latus rectum of the orbits, for circular orbits, this is the radius
 
 # %%
-# system = {"alpha": 1.0, "mass": 1.0}
-# ic = {"r_0": 1.0, "phi_0": 0.0, "drdt_0": 0.0, "dphidt_0": 0.1}
+system = {
+    "alpha": 1.0,
+    "mass": 1.0,
+}
+
+k2d = Kepler2D.from_geometry(
+    system=system,
+    geometries={
+        "positive_angular_mom": True,
+        "ecc": 0,
+        "parameter": 1.0,
+    },
+)
 
-# t = np.linspace(0, 1, 11)
+# %%
+t = np.linspace(0, 10, 101)
+
+# %%
+df_p_1 = k2d(t=t)
+df_p_1  # noqa: B018
+
+# %%
+fig = px.line_polar(
+    df_p_1.assign(phi_degree=df_p_1.phi / (2 * np.pi) * 360),
+    r="r",
+    theta="phi_degree",
+)
+
+fig.update_layout(
+    polar={
+        "angularaxis_thetaunit": "radians",
+    },
+)
+
+fig.show()
+
+# %%
 
 # %% [markdown]
 # ## Formalism

hamilflow/models/kepler_problem/model.py

@@ -110,14 +110,14 @@ def from_geometry(
     ) -> "Self":
         r"""Alternative initialiser from system and geometry specifications.
 
-        Given the eccentricity $e$ and the conic section parameter $p$,
+        Given the eccentricity $e$ and the conic section semi-latus rectum $p$,
         $$l = \pm \sqrt{mp}\,,\quad E = (e^2-1) \left|E_\text{min}\right|\,.$$
 
         :param system: the Kepler problem system specification
         :param geometries: geometric specifications
             `positive_angular_mom`: whether the angular momentum is positive
             `ecc`: eccentricity of the conic section
-            `parameter`: parameter of the conic section
+            `parameter`: semi-latus rectum of the conic section
         """
         mass, alpha = system["mass"], system["alpha"]
         positive_angular_mom = bool(geometries["positive_angular_mom"])
@@ -195,7 +195,7 @@ def period(self) -> float:
     # FIXME is it called parameter in English?
     @cached_property
     def parameter(self) -> float:
-        r"""Conic section parameter of the Kepler problem.
+        r"""Conic section semi-latus rectum of the Kepler problem.
 
         $$ p = \frac{l^2}{\alpha m}\,. $$
         """