dynamicalnodes 0.1__tar.gz → 0.1.3__tar.gz

dynamicalnodes-0.1.3/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: dynamicalnodes
+Version: 0.1.3
+Summary: dynamicalnodes is a Python library for modeling general control systems.
+Author-email: Nehal Singh Mangat <nehalsinghmangat.software@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/nehalsinghmangat/dynamicalnodes
+Project-URL: Documentation, https://nehalsinghmangat.github.io/dynamicalnodes
+Project-URL: Issues, https://github.com/nehalsinghmangat/dynamicalnodes/issues
+Keywords: control,estimation,ros2
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-doctestplus>=1.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0; extra == "dev"
+Requires-Dist: black>=24.0; extra == "dev"
+Requires-Dist: isort>=6.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: build>=0.10; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=8.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=1.3; extra == "docs"
+Requires-Dist: sphinx-copybutton>=0.5; extra == "docs"
+Requires-Dist: myst_nb; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints>=1.24.0; extra == "docs"
+Requires-Dist: matplotlib>=3.9; extra == "docs"
+Requires-Dist: scipy>=1.11; extra == "docs"
+Requires-Dist: jupyter; extra == "docs"
+Requires-Dist: jaxtyping>=0.2; extra == "docs"
+Requires-Dist: beartype>=0.15; extra == "docs"
+Dynamic: license-file
+
+# dynamicalnodes: Control Systems on ROS 2
+
+> _"Give me a [control system] long enough and a [computer] on which to place it, and I shall move the world."_ - Archimedes 
+
+**dynamicalnodes** is a Python development framework that bridges the gap between novel control systems and their implementation onto ROS 2. Designed for hobbyists, students, and academics alike, this framework won't cure cancer, but it can do the next best thing: make robotics easier.
+
+To get started, or to explore what this framework has to offer, click here: [dynamicalnodes Documentation](https://nehalsinghmangat.github.io/dynamicalnodes).
+
+For a 22 second video describing this framework's intended workflow for, click here: [SAIL 2025 -- Presenting dynamicalnodes](https://youtu.be/5GbVHo6QZrw).
+
+---
+## Turtlebot: Whiteboard ⟶ Python ⟶ ROS 2 ⟶ World
+<table>
+  <tr>
+    <td align="center">
+      <img src="docs/source/_static/figures/turtlebot_schematic.svg" alt="TurtleBot Schematic" width="400"/><br/>
+    </td>
+    <td align="center">
+      <img src="docs/source/_static/figures/turtlebot_python_simulation.gif" alt="Turtle Software" width="200"/><br/>
+    </td>
+    <td align="center">
+      <img src="docs/source/_static/figures/turtlebot_ros_simulation.gif" alt="Turtle Simulation" width="200"/><br/>
+    </td>
+    <td align="center">
+      <img src="docs/source/_static/figures/turtlebot_mocab.gif" alt="Turtle Hardware" width="200"/><br/>
+    </td>
+  </tr>
+</table>
+
+<p align="center">
+  <img src="docs/source/_static/figures/pipeline_theory_python_ros_hardware.png" alt="Step Labels" width="800"/>
+</p>
+
+
+
+
+
+

dynamicalnodes-0.1.3/README.md

@@ -0,0 +1,38 @@
+# dynamicalnodes: Control Systems on ROS 2
+
+> _"Give me a [control system] long enough and a [computer] on which to place it, and I shall move the world."_ - Archimedes 
+
+**dynamicalnodes** is a Python development framework that bridges the gap between novel control systems and their implementation onto ROS 2. Designed for hobbyists, students, and academics alike, this framework won't cure cancer, but it can do the next best thing: make robotics easier.
+
+To get started, or to explore what this framework has to offer, click here: [dynamicalnodes Documentation](https://nehalsinghmangat.github.io/dynamicalnodes).
+
+For a 22 second video describing this framework's intended workflow for, click here: [SAIL 2025 -- Presenting dynamicalnodes](https://youtu.be/5GbVHo6QZrw).
+
+---
+## Turtlebot: Whiteboard ⟶ Python ⟶ ROS 2 ⟶ World
+<table>
+  <tr>
+    <td align="center">
+      <img src="docs/source/_static/figures/turtlebot_schematic.svg" alt="TurtleBot Schematic" width="400"/><br/>
+    </td>
+    <td align="center">
+      <img src="docs/source/_static/figures/turtlebot_python_simulation.gif" alt="Turtle Software" width="200"/><br/>
+    </td>
+    <td align="center">
+      <img src="docs/source/_static/figures/turtlebot_ros_simulation.gif" alt="Turtle Simulation" width="200"/><br/>
+    </td>
+    <td align="center">
+      <img src="docs/source/_static/figures/turtlebot_mocab.gif" alt="Turtle Hardware" width="200"/><br/>
+    </td>
+  </tr>
+</table>
+
+<p align="center">
+  <img src="docs/source/_static/figures/pipeline_theory_python_ros_hardware.png" alt="Step Labels" width="800"/>
+</p>
+
+
+
+
+
+

{dynamicalnodes-0.1 → dynamicalnodes-0.1.3}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dynamicalnodes"
-version = "0.1"
+version = "0.1.3"
 description = "dynamicalnodes is a Python library for modeling general control systems."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -16,6 +16,14 @@ authors = [
   { name = "Nehal Singh Mangat", email = "nehalsinghmangat.software@gmail.com" }
 ]
 keywords = ["control", "estimation", "ros2"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering",
+  "Topic :: Software Development :: Libraries",
+]
 dependencies = [
   "numpy>=1.24",
 ]
@@ -35,21 +43,32 @@ dev = [
 docs = [
   "sphinx>=8.0",
   "sphinx-rtd-theme>=1.3",
+  "sphinx-copybutton>=0.5",
   "myst_nb",
   "sphinx-autodoc-typehints>=1.24.0",
-  "matplotlib>=3.7",
+  "matplotlib>=3.9",
   "scipy>=1.11",
   "jupyter",
+  "jaxtyping>=0.2",
+  "beartype>=0.15",
 ]
 
 [project.urls]
 Homepage = "https://github.com/nehalsinghmangat/dynamicalnodes"
 Documentation = "https://nehalsinghmangat.github.io/dynamicalnodes"
+Issues = "https://github.com/nehalsinghmangat/dynamicalnodes/issues"
 
 [tool.pytest.ini_options]
 addopts = "--doctest-modules"
 doctest_optionflags = ["NORMALIZE_WHITESPACE", "ELLIPSIS"]
 
+[tool.isort]
+profile = "black"
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+
 [tool.setuptools]
 package-dir = {"" = "src"}
 

dynamicalnodes-0.1.3/src/dynamicalnodes/__init__.py

@@ -0,0 +1,29 @@
+"""
+dynamicalnodes: A modular Python framework for dynamical systems, estimation, and ROS2 integration.
+"""
+
+from .dynamical_system import DynamicalSystem
+from .rosnode import ROSNode
+
+# Lazy import — requires a live ROS2 installation
+_ROS2_MODULES = {
+    "ros2py_py2ros": ("ros2py_py2ros", None),
+}
+
+
+def __getattr__(name):
+    if name in _ROS2_MODULES:
+        module_name, attr = _ROS2_MODULES[name]
+        try:
+            import importlib
+            mod = importlib.import_module(f".{module_name}", package=__name__)
+            return mod if attr is None else getattr(mod, attr)
+        except ImportError as e:
+            raise ImportError(
+                f"{name} requires ROS2 dependencies. Install with: pip install dynamicalnodes[ros2]\n"
+                f"Original error: {e}"
+            ) from e
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = ["DynamicalSystem", "ROSNode"]

dynamicalnodes-0.1.3/src/dynamicalnodes/dynamical_system.py

@@ -0,0 +1,204 @@
+"""
+A discrete-time dynamical system (DTDS) is represented as a pair of functions,
+``(f, h)``, following the definition in Mangat et al., *dynamicalnodes: From
+Theory to Python to ROS*::
+
+    x_{k+1} = f(x_k, u_k, theta)
+    y_k     = h(x_k, u_k, theta)
+
+``f`` is the evolution function that propagates the state forward one step;
+``h`` is the measurement (or output) function that computes an observation
+from the current state. Either function may be omitted -- denoted ``*`` in
+the paper, ``None`` here -- giving three cases:
+
+- ``(f, *)`` -- no output function.
+- ``(*, h)`` -- stateless, e.g. a signal generator.
+- ``(f, h)`` -- both state evolution and output are defined.
+
+Function signatures are unconstrained in name, type, and number of
+parameters. ``DynamicalSystem.eval`` binds keyword arguments to each
+function's signature by name, so the same keyword argument (e.g. a shared
+state or parameter) can be passed to both ``f`` and ``h``.
+"""
+
+import inspect
+from typing import Any, Callable, Dict, Optional, Tuple
+
+
+class DynamicalSystem:
+    """
+    A discrete-time dynamical system with (optional) evolution and
+    (optional) measurement functions.
+
+    Parameters
+    ----------
+    f : Callable, optional
+        Evolution function ``f(x_k, u_k, theta) -> x_{k+1}``. ``None`` if
+        the system has no state transition, i.e. ``(*, h)``.
+    h : Callable, optional
+        Measurement function ``h(x_k, u_k, theta) -> y_k``. ``None`` if
+        the system has no output, i.e. ``(f, *)``.
+
+    Examples
+    --------
+    A stateful system with both an evolution and a measurement function --
+    a car whose state is ``(displacement, velocity)``, measured via its
+    speed:
+
+    >>> def fcar(xk, uk, theta_car):
+    ...     d, v = xk
+    ...     m, b, dt = theta_car
+    ...     return (d + dt * v, v + dt * (uk - b * v) / m)
+    >>> def hcar(xk):
+    ...     _, v = xk
+    ...     return abs(v)
+    >>> car = DynamicalSystem(f=fcar, h=hcar)
+    >>> x_next, y = car.eval(xk=(20.0, 0.0), uk=4.0, theta_car=(2.0, 0.0, 1.0))
+    >>> x_next
+    (20.0, 2.0)
+    >>> y
+    0.0
+
+    A stateless system, e.g. a signal generator -- ``(*, h)``:
+
+    >>> def h_ref(tk, A=1.0):
+    ...     return A if tk >= 1.0 else 0.0
+    >>> ref = DynamicalSystem(h=h_ref)
+    >>> ref.eval(tk=0.0)
+    (None, 0.0)
+    >>> ref.eval(tk=2.0)
+    (None, 1.0)
+
+    A system with no output function -- ``(f, *)``:
+
+    >>> def f_counter(xk):
+    ...     return xk + 1
+    >>> counter = DynamicalSystem(f=f_counter)
+    >>> counter.eval(xk=5)
+    (6, None)
+    """
+
+    def __init__(
+        self,
+        *,
+        f: Optional[Callable] = None,
+        h: Optional[Callable] = None,
+    ) -> None:
+        """
+        Parameters
+        ----------
+        f : Callable, optional
+            Evolution function ``f(x_k, u_k, theta) -> x_{k+1}``. Signature
+            typing is not enforced. ``None`` if the system is stateless.
+        h : Callable, optional
+            Measurement function ``h(x_k, u_k, theta) -> y_k``. Signature
+            typing is not enforced. ``None`` if the system has no output.
+        """
+        self._f = f
+        self._h = h
+
+    @property
+    def f(self) -> Optional[Callable]:
+        """Evolution function f(x_k, u_k, theta) -> x_{k+1}, or None if the system is stateless."""
+        return self._f
+
+    @f.setter
+    def f(self, f: Optional[Callable]) -> None:
+        self._f = f
+
+    @property
+    def h(self) -> Optional[Callable]:
+        """Measurement function h(x_k, u_k, theta) -> y_k, or None if the system has no output."""
+        return self._h
+
+    @h.setter
+    def h(self, h: Optional[Callable]) -> None:
+        self._h = h
+
+    def eval(self, **kwargs) -> Tuple[Optional[Any], Optional[Any]]:
+        """
+        Evaluate the system for one discrete time step.
+
+        Keyword arguments are lexically bound by name to whichever of ``f``
+        and/or ``h`` declare them in their signature (see
+        ``_bind_and_call``), so the same keyword argument can be shared by
+        both functions.
+
+        Returns
+        -------
+        Tuple[Optional[Any], Optional[Any]]
+            - ``(None, y_k)`` for a stateless system, ``(*, h)``.
+            - ``(x_{k+1}, None)`` for a system with no output, ``(f, *)``.
+            - ``(x_{k+1}, y_k)`` for a fully specified system, ``(f, h)``.
+
+        Notes
+        -----
+        ``h`` is evaluated on the same (pre-update) state passed in via
+        keyword arguments, not on the value returned by ``f``, so the
+        returned observation is one step behind the returned state. In a
+        simulation loop, use the returned ``x_{k+1}`` directly if you need
+        the post-update state.
+
+        Raises
+        ------
+        ValueError
+            If neither ``f`` nor ``h`` is defined.
+
+        Examples
+        --------
+        See the class docstring for worked examples covering all three
+        cases.
+
+        >>> empty = DynamicalSystem()
+        >>> empty.eval()
+        Traceback (most recent call last):
+            ...
+        ValueError: Nothing to evaluate; no f or h functions!
+        """
+
+        def _bind_and_call(
+            func: Callable[..., Any],
+            **kwargs: Any,
+        ) -> Any:
+            """
+            Call `func` with only the keyword arguments it declares.
+
+            Inspects `func`'s signature and passes only the entries of
+            `kwargs` matching its declared parameter names; if `func`
+            accepts `**kwargs`, the remaining pool is passed through too.
+            """
+            sig = inspect.signature(func)
+            pool: Dict[str, Any] = dict(kwargs)
+
+            # Filter: only pass arguments the function declares
+            call_kwargs: Dict[str, Any] = {}
+            for name, p in sig.parameters.items():
+                if p.kind in (
+                    inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                    inspect.Parameter.KEYWORD_ONLY,
+                ):
+                    if name in pool:
+                        call_kwargs[name] = pool.pop(name)
+
+            # Pass remaining kwargs if function has **kwargs
+            if any(
+                p.kind is inspect.Parameter.VAR_KEYWORD for p in sig.parameters.values()
+            ):
+                call_kwargs.update(pool)
+
+            return func(**call_kwargs)
+
+        if self.f is None and self.h:
+            return (None, _bind_and_call(self.h, **kwargs))
+
+        elif self.f and self.h is None:
+            return (_bind_and_call(self.f, **kwargs), None)
+
+        elif self.f and self.h:
+            return (
+                _bind_and_call(self.f, **kwargs),
+                _bind_and_call(self.h, **kwargs),
+            )
+
+        else:
+            raise ValueError("Nothing to evaluate; no f or h functions!")

{dynamicalnodes-0.1 → dynamicalnodes-0.1.3}/src/dynamicalnodes/ros2py_py2ros.py

@@ -24,6 +24,7 @@ from turtlesim.msg import Pose
 from nav_msgs.msg import Odometry, Path
 from sensor_msgs.msg import (
     Imu,
+    NavSatFix,
     LaserScan,
     Image,
     CompressedImage,
@@ -558,6 +559,42 @@ def py2ros_imu(arr: NDArray) -> Imu:
     return msg
 
 
+# ---------------------------------------------------------------------------
+# sensor_msgs/NavSatFix  <->  np.ndarray(3,)  [latitude, longitude, altitude]
+# ---------------------------------------------------------------------------
+
+def ros2py_nav_sat_fix(msg: NavSatFix) -> NDArray:
+    """
+    NavSatFix → [latitude, longitude, altitude]
+
+    >>> from sensor_msgs.msg import NavSatFix
+    >>> msg = NavSatFix()
+    >>> msg.latitude, msg.longitude, msg.altitude = 37.5, -122.0, 10.0
+    >>> ros2py_nav_sat_fix(msg).tolist()
+    [37.5, -122.0, 10.0]
+    """
+    return np.array([msg.latitude, msg.longitude, msg.altitude], dtype=float)
+
+
+def py2ros_nav_sat_fix(arr: NDArray) -> NavSatFix:
+    """
+    [latitude, longitude, altitude] → NavSatFix
+
+    >>> import numpy as np
+    >>> msg = py2ros_nav_sat_fix(np.array([37.5, -122.0, 10.0]))
+    >>> msg.latitude, msg.longitude, msg.altitude
+    (37.5, -122.0, 10.0)
+    """
+    flat = np.asarray(arr, dtype=float).ravel()
+    if flat.size != 3:
+        raise ValueError(f"py2ros_nav_sat_fix expected length 3, got {flat.size}")
+    msg = NavSatFix()
+    msg.latitude = float(flat[0])
+    msg.longitude = float(flat[1])
+    msg.altitude = float(flat[2])
+    return msg
+
+
 # ---------------------------------------------------------------------------
 # nav_msgs/Odometry  <->  np.ndarray(13,)
 # (pose + twist; covariances ignored)
@@ -907,9 +944,9 @@ def py2ros_uint8_multiarray(arr: NDArray) -> UInt8MultiArray:
 # std_msgs/Float64  <->  scalar float (as 1D array)
 # ---------------------------------------------------------------------------
 
-def ros2py_float64(msg: Float64) -> NDArray:
-    """Convert Float64 message to 1D numpy array with single element."""
-    return np.array([msg.data], dtype=float)
+def ros2py_float64(msg: Float64) -> float:
+    """Convert Float64 message to Python float."""
+    return float(msg.data)
 
 
 def py2ros_float64(arr: NDArray) -> Float64:
@@ -994,6 +1031,7 @@ ROS2PY_DEFAULT = {
     AccelStamped: ros2py_accel_stamped,
     Vector3Stamped: ros2py_vector3_stamped,
     Imu: ros2py_imu,
+    NavSatFix: ros2py_nav_sat_fix,
     Odometry: ros2py_odometry,
     Path: ros2py_path,
     JointState: ros2py_joint_state,
@@ -1019,6 +1057,7 @@ PY2ROS_DEFAULT = {
     AccelStamped: py2ros_accel_stamped,
     Vector3Stamped: py2ros_vector3_stamped,
     Imu: py2ros_imu,
+    NavSatFix: py2ros_nav_sat_fix,
     Odometry: py2ros_odometry,
     Path: py2ros_path,
     JointState: py2ros_joint_state,