dynamicalnodes 0.1.2__tar.gz → 0.1.4__tar.gz

{dynamicalnodes-0.1.2/src/dynamicalnodes.egg-info → dynamicalnodes-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dynamicalnodes
-Version: 0.1.2
+Version: 0.1.4
 Summary: dynamicalnodes is a Python library for modeling general control systems.
 Author-email: Nehal Singh Mangat <nehalsinghmangat.software@gmail.com>
 License-Expression: MIT
@@ -44,33 +44,33 @@ Dynamic: license-file
 
 > _"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 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.
+**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 -> World
+## Turtlebot: Whiteboard ⟶ Python ⟶ ROS 2 ⟶ World
 <table>
   <tr>
     <td align="center">
-      <img src="docs/source/_static/figure_turtlebot_pipeline/turtlebot.svg" alt="TurtleBot Overview" width="400"/><br/>
+      <img src="docs/source/_static/figures/turtlebot_schematic.svg" alt="TurtleBot Schematic" width="400"/><br/>
     </td>
     <td align="center">
-      <img src="docs/source/_static/figure_turtlebot_pipeline/turtlesim_software.gif" alt="Turtle Software" width="200"/><br/>
+      <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/figure_turtlebot_pipeline/turtlesim_simulation.gif" alt="Turtle Simulation" width="200"/><br/>
+      <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/figure_turtlebot_pipeline/turtlesim_hardware.gif" alt="Turtle Hardware" width="200"/><br/>
+      <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/figure_turtlebot_pipeline/labels_for_steps_from_theory_to_hardware.png" alt="Step Labels" width="800"/>
+  <img src="docs/source/_static/figures/pipeline_theory_python_ros_hardware.png" alt="Step Labels" width="800"/>
 </p>
 
 

dynamicalnodes-0.1.4/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.2 → dynamicalnodes-0.1.4}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dynamicalnodes"
-version = "0.1.2"
+version = "0.1.4"
 description = "dynamicalnodes is a Python library for modeling general control systems."
 readme = "README.md"
 requires-python = ">=3.12"

dynamicalnodes-0.1.4/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.2 → dynamicalnodes-0.1.4}/src/dynamicalnodes/rosnode.py

@@ -3,57 +3,14 @@ ROSNode wrapper for simulation and ROS2 deployment.
 
 Two workflows:
 
-**Simulation** — call ``step()`` directly in Python or Jupyter notebooks.
+**Simulation** — call ``eval()`` directly in Python or Jupyter notebooks to test ros2py and/or py2ros translation functions.
 No ROS2 installation required.
 
 **Deployment** — call ``write_ROSNode_to_rclpy(path)`` to emit a self-contained
 ``.py`` file that spins up a native rclpy node.  Every ROS2 detail (QoS profiles,
-buffer depths, subscription callbacks, executor setup) is written out explicitly —
-the generated file reads exactly like a hand-authored rclpy node and has no runtime
-dependency on dynamicalnodes beyond ``DynamicalSystem``.
-
-Example
--------
-Develop and simulate in a notebook, then deploy:
-
->>> import numpy as np
->>> from dynamicalnodes import DynamicalSystem, ROSNode
->>> from std_msgs.msg import Float64
->>> from dynamicalnodes.ros2py_py2ros import ros2py_float64, py2ros_float64
->>>
->>> def f_plant(xk, u_k):
-...     return xk + 0.1 * u_k
->>> def h_plant(xk):
-...     return xk
->>>
->>> sys = DynamicalSystem(f=f_plant, h=h_plant)
->>> node = ROSNode(
-...     dynamical_system=sys,
-...     subscribes_to=[
-...         {"topic": "/u_k", "msg_type": Float64, "arg": "u_k",
-...          "ros2py": ros2py_float64, "stale_after": 0.5},
-...     ],
-...     publishes_to=[
-...         {"topic": "/y_k", "msg_type": Float64, "py2ros": py2ros_float64},
-...     ],
-...     state_name="xk",
-... )
->>>
->>> # Simulate
->>> node._state = np.array([0.0])
->>> for k in range(3):
-...     y = node.step(u_k=np.array([1.0]))
-...     print(f"k={k}: x={node.state}")
-k=0: x=[0.1]
-k=1: x=[0.2]
-k=2: x=[0.3]
->>>
->>> # Deploy — writes a standalone rclpy node to disk
->>> import tempfile, os
->>> with tempfile.NamedTemporaryFile(suffix=".py", delete=False) as f:
-...     path = f.name
->>> node.write_ROSNode_to_rclpy(path, node_name="plant", initial_state=np.array([0.0]))
->>> os.unlink(path)
+buffer depths, subscription callbacks, executor setup, etc...) is written out explicitly and
+can be modified as needed. The ``.py`` file also has no runtime dependency on dynamicalnodes beyond ``DynamicalSystem`` and whatever dependencies the
+f/h functions may have.
 
 See Also
 --------
@@ -79,21 +36,21 @@ class ROSNode:
     """
     Wraps a DynamicalSystem for simulation and ROS2 deployment.
 
-    Use ``step()`` for notebook simulation; use ``write_ROSNode_to_rclpy()`` to
+    Use ``eval()`` for notebook simulation; use ``write_ROSNode_to_rclpy()`` to
     generate a deployable rclpy node.
 
     Parameters
     ----------
     dynamical_system : DynamicalSystem
-        The dynamical system to step.
-    subscribes_to : list of dict, optional
+        The dynamical system to evaluate.
+    subs : list of dict, optional
         Each dict:
 
         - ``"topic"`` (str): ROS topic name.
         - ``"msg_type"`` (type): ROS message class.
-        - ``"arg"`` (str): kwarg name passed to step().
+        - ``"arg"`` (str): kwarg name passed to eval().
         - ``"ros2py"`` (Callable): ROS msg → NumPy array converter.
-          Import from ``dynamicalnodes.ros2py_py2ros``.
+          Import from ``dynamicalnodes.ros2py_py2ros`` or write your own.
         - ``"stale_after"`` (float, optional): Seconds before data expires.
         - ``"buffer_size"`` (int, optional): Queue depth (default 1).
         - ``"use_msg_timestamp"`` (bool, optional): When ``True``, the
@@ -104,7 +61,7 @@ class ROSNode:
           rather than network-arrival time (e.g. sensor fusion, bag
           replay).  Defaults to ``False``.
 
-    publishes_to : list of dict, optional
+    pubs : list of dict, optional
         Each dict:
 
         - ``"topic"`` (str): ROS topic name.
@@ -114,19 +71,17 @@ class ROSNode:
         - ``"key"`` (str, optional): Key into h() return dict. Required when
           h() returns a dict and there are multiple publishers.
 
-    sync_mode : str, required when ``subscribes_to`` has more than one entry
-        ``"any"`` — step whenever any subscription has fresh data.
-        ``"all"`` — step only when every subscription has fresh data.
-
     state_name : str, optional
         Name of the state parameter in ``f``'s signature (e.g. ``"ck"`` for
         ``f(ck, ...)``) .  Required for stateful systems; ignored if ``f`` is
-        ``None``.  ``step()`` injects ``self._state`` under this name before
-        calling ``DynamicalSystem.step()``.
+        ``None``.  ``eval()`` injects ``self._state`` under this name before
+        calling ``DynamicalSystem.eval()``.
 
-    timer_hz : float, optional
-        In the generated node: fires ``_run_step`` at this frequency instead
-        of triggering from subscription callbacks.
+    Notes
+    -----
+    ``sync_mode`` and ``timer_hz`` are not constructor parameters — they only
+    affect the generated ROS2 node's triggering behavior, so they're passed to
+    ``write_ROSNode_to_rclpy()`` instead.
 
     Examples
     --------
@@ -140,12 +95,12 @@ class ROSNode:
     >>> smoother = DynamicalSystem(h=lambda imu: imu * 0.5)
     >>> node = ROSNode(
     ...     dynamical_system=smoother,
-    ...     subscribes_to=[{"topic": "/raw", "msg_type": Float64,
-    ...                      "arg": "imu", "ros2py": ros2py_float64}],
-    ...     publishes_to=[{"topic": "/smooth", "msg_type": Float64,
-    ...                    "py2ros": py2ros_float64}],
+    ...     subs=[{"topic": "/raw", "msg_type": Float64,
+    ...            "arg": "imu", "ros2py": ros2py_float64}],
+    ...     pubs=[{"topic": "/smooth", "msg_type": Float64,
+    ...            "py2ros": py2ros_float64}],
     ... )
-    >>> out = node.step(imu=np.array([2.0]))
+    >>> out = node.eval(imu=np.array([2.0]))
     >>> out.data
     1.0
     """
@@ -155,32 +110,16 @@ class ROSNode:
         *,
         dynamical_system: DynamicalSystem,
         state_name: Optional[str] = None,
-        subscribes_to: Optional[Sequence[SubDict]] = None,
-        publishes_to: Optional[Sequence[PubDict]] = None,
-        sync_mode: Optional[str] = None,
-        timer_hz: Optional[float] = None,
+        subs: Optional[Sequence[SubDict]] = None,
+        pubs: Optional[Sequence[PubDict]] = None,
     ) -> None:
-        n_subs = len(subscribes_to) if subscribes_to else 0
-        if n_subs > 1 and sync_mode is None:
-            raise ValueError(
-                "sync_mode ('any' or 'all') is required when subscribes_to has "
-                "more than one subscription"
-            )
-        sync_mode = sync_mode or "any"
-        if sync_mode not in ("any", "all"):
-            raise ValueError(f"sync_mode must be 'any' or 'all', got: {sync_mode!r}")
-        if timer_hz is not None and timer_hz <= 0:
-            raise ValueError(f"timer_hz must be positive, got {timer_hz}")
-
         self._dynamical_system = dynamical_system
         self._state: Optional[Any] = None
         self._state_key: Optional[str] = state_name
-        self._sync_mode = sync_mode
-        self._timer_hz = timer_hz
 
         # -------- Parse subscriptions --------
         self._subs: List[Tuple[str, type, Any, str, Optional[float], int, bool]] = []
-        for sub_dict in subscribes_to or []:
+        for sub_dict in subs or []:
             if not isinstance(sub_dict, dict):
                 raise TypeError("Each subscription must be a dict")
 
@@ -233,7 +172,7 @@ class ROSNode:
 
         # -------- Parse publications --------
         self._pubs_cfg: List[Tuple[str, type, Any, Optional[str]]] = []
-        for pub_dict in publishes_to or []:
+        for pub_dict in pubs or []:
             if not isinstance(pub_dict, dict):
                 raise TypeError("Each publication must be a dict")
 
@@ -265,7 +204,7 @@ class ROSNode:
     # SIMULATION API
     # --------------------------------------------------------------------------
 
-    def step(self, **kwargs: Any) -> Any:
+    def eval(self, **kwargs: Any) -> Any:
         """
         Simulate one step without ROS2.
 
@@ -297,12 +236,12 @@ class ROSNode:
         >>> double = DynamicalSystem(h=lambda x: x * 2)
         >>> node = ROSNode(
         ...     dynamical_system=double,
-        ...     subscribes_to=[{"topic": "/x", "msg_type": Float64,
-        ...                      "arg": "x", "ros2py": ros2py_float64}],
-        ...     publishes_to=[{"topic": "/y", "msg_type": Float64,
-        ...                    "py2ros": py2ros_float64}],
+        ...     subs=[{"topic": "/x", "msg_type": Float64,
+        ...            "arg": "x", "ros2py": ros2py_float64}],
+        ...     pubs=[{"topic": "/y", "msg_type": Float64,
+        ...            "py2ros": py2ros_float64}],
         ... )
-        >>> node.step(x=Float64(data=3.0)).data
+        >>> node.eval(x=Float64(data=3.0)).data
         6.0
         """
         sub_arg_names = {a for _, _, _, a, _, _, _ in self._subs}
@@ -328,11 +267,9 @@ class ROSNode:
         if self._state is not None and self._state_key is not None:
             step_kwargs[self._state_key] = self._state
 
-        result = self._dynamical_system.step(**step_kwargs)
+        x_next, yk = self._dynamical_system.eval(**step_kwargs)
         if self._dynamical_system.f is not None:
-            self._state, yk = result
-        else:
-            yk = result
+            self._state = x_next
 
         if not self._pubs_cfg:
             return yk
@@ -365,6 +302,8 @@ class ROSNode:
         path: str,
         *,
         node_name: str,
+        sync_mode: Optional[str] = None,
+        timer_hz: Optional[float] = None,
         deps: Optional[List[Any]] = None,
         initial_state: Optional[Any] = None,
         initial_inputs: Optional[Dict[str, Any]] = None,
@@ -388,6 +327,13 @@ class ROSNode:
         node_name : str
             ROS2 node name (used for the generated class name, ``super().__init__``,
             and logger messages).
+        sync_mode : str, optional
+            Required when there is more than one subscription. ``"any"`` —
+            step whenever any subscription has fresh data. ``"all"`` — step
+            only when every subscription has fresh data.
+        timer_hz : float, optional
+            Fires ``_run_step`` at this frequency instead of triggering from
+            subscription callbacks.
         deps : list of callable, optional
             Helper functions that ``f`` or ``h`` depend on.  Each function's
             source is inlined before the dynamics functions in the output file.
@@ -398,7 +344,7 @@ class ROSNode:
             ``__init__``.  Supports NumPy arrays and any ``repr()``-able value.
         static_params : dict, optional
             Parameters baked into the node at generation time.  Embedded as
-            ``self._static_params = {...}`` and merged into every ``step()``
+            ``self._static_params = {...}`` and merged into every ``eval()``
             call.  Use for values that never change after deployment.
         dynamic_params : dict, optional
             Parameters declared on the ROS2 parameter server with their
@@ -434,6 +380,10 @@ class ROSNode:
         ------
         ValueError
             If any function is a lambda (cannot be serialized).
+        ValueError
+            If there is more than one subscription and ``sync_mode`` is not
+            given, or ``sync_mode`` is not ``"any"``/``"all"``, or
+            ``timer_hz`` is not positive.
         ValueError
             If the node has no subscriptions and no ``timer_hz`` — the
             generated node would never step.
@@ -446,7 +396,8 @@ class ROSNode:
 
         Notes
         -----
-        **Function resolution**:
+        **Function resolution**
+
         Functions from ``dynamicalnodes.ros2py_py2ros`` are emitted as import
         statements.  Functions from any other importable module (not
         ``__main__`` or an IPython cell) are also imported by name.  All other
@@ -468,11 +419,11 @@ class ROSNode:
         >>> sys = DynamicalSystem(f=f_plant, h=h_plant)
         >>> node = ROSNode(
         ...     dynamical_system=sys,
-        ...     subscribes_to=[{"topic": "/u_k", "msg_type": Float64,
-        ...                      "arg": "u_k", "ros2py": ros2py_float64,
-        ...                      "stale_after": 0.5}],
-        ...     publishes_to=[{"topic": "/y_k", "msg_type": Float64,
-        ...                    "py2ros": py2ros_float64}],
+        ...     subs=[{"topic": "/u_k", "msg_type": Float64,
+        ...            "arg": "u_k", "ros2py": ros2py_float64,
+        ...            "stale_after": 0.5}],
+        ...     pubs=[{"topic": "/y_k", "msg_type": Float64,
+        ...            "py2ros": py2ros_float64}],
         ... )
         >>> with tempfile.NamedTemporaryFile(suffix=".py", delete=False) as tmp:
         ...     path = tmp.name
@@ -616,10 +567,22 @@ class ROSNode:
 
         # ── validate ──────────────────────────────────────────────────────────
 
-        if not self._subs and self._timer_hz is None and self._pubs_cfg:
+        n_subs = len(self._subs)
+        if n_subs > 1 and sync_mode is None:
+            raise ValueError(
+                "sync_mode ('any' or 'all') is required when subs has "
+                "more than one subscription"
+            )
+        sync_mode = sync_mode or "any"
+        if sync_mode not in ("any", "all"):
+            raise ValueError(f"sync_mode must be 'any' or 'all', got: {sync_mode!r}")
+        if timer_hz is not None and timer_hz <= 0:
+            raise ValueError(f"timer_hz must be positive, got {timer_hz}")
+
+        if not self._subs and timer_hz is None and self._pubs_cfg:
             raise ValueError(
                 "Cannot write a node with no subscriptions and no timer_hz — "
-                "the generated node would never step.  Add timer_hz or subscribes_to."
+                "the generated node would never step.  Add timer_hz or subs."
             )
 
         ds = self._dynamical_system
@@ -636,10 +599,10 @@ class ROSNode:
         _valid_pub_topics = {t for t, *_ in self._pubs_cfg}
         for t in _sub_noise:
             if t not in _valid_sub_topics:
-                raise ValueError(f"sub_noise topic {t!r} not in subscribes_to")
+                raise ValueError(f"sub_noise topic {t!r} not in subs")
         for t in _pub_noise:
             if t not in _valid_pub_topics:
-                raise ValueError(f"pub_noise topic {t!r} not in publishes_to")
+                raise ValueError(f"pub_noise topic {t!r} not in pubs")
 
         # ── classify all functions ─────────────────────────────────────────────
 
@@ -863,17 +826,17 @@ class ROSNode:
                     f"        {topic}  ({msg_type.__name__})  [{_ref_name(py2ros, py2ros_cls)}{key_str}]"
                 )
         ln("")
-        if self._timer_hz is not None:
-            ln(f"    step trigger: timer at {self._timer_hz} Hz")
+        if timer_hz is not None:
+            ln(f"    step trigger: timer at {timer_hz} Hz")
         else:
             ln("    step trigger: event-driven (fires on each subscription callback)")
         if subs:
             sync_desc = (
                 "step only when every subscription has a fresh value"
-                if self._sync_mode == "all"
+                if sync_mode == "all"
                 else "step when any subscription receives a fresh value"
             )
-            ln(f"    sync_mode={self._sync_mode!r}: {sync_desc}.")
+            ln(f"    sync_mode={sync_mode!r}: {sync_desc}.")
         _dynamic = dict(dynamic_params or {})
         if _dynamic:
             ln("")
@@ -946,12 +909,12 @@ class ROSNode:
                 ln(f"            {msg_type.__name__}, {topic!r}, QOS,")
                 ln(f"        )")
 
-        if self._timer_hz is not None:
+        if timer_hz is not None:
             blank()
             ln("        # ── Timer " + "─" * 60)
-            period = 1.0 / self._timer_hz
+            period = 1.0 / timer_hz
             ln(f"        self._timer = self.create_timer(")
-            ln(f"            {period},  # {self._timer_hz} Hz")
+            ln(f"            {period},  # {timer_hz} Hz")
             ln(f"            self._run_step,")
             ln(f"            callback_group=self._cb_group,")
             ln(f"        )")
@@ -984,7 +947,9 @@ class ROSNode:
             )
             if topic in _sub_noise:
                 std = _sub_noise[topic]
-                ln(f"        arr = arr + np.random.normal(0.0, {std!r}, arr.shape)  # noise std={std}")
+                ln(
+                    f"        arr = arr + np.random.normal(0.0, {std!r}, arr.shape)  # noise std={std}"
+                )
             if use_msg_ts:
                 ln(
                     f"        ts = msg.header.stamp.sec + msg.header.stamp.nanosec * 1e-9"
@@ -992,7 +957,7 @@ class ROSNode:
             else:
                 ln(f"        ts = self.get_clock().now().nanoseconds * 1e-9")
             ln(f"        self._{arg}_buf.append((ts, arr))")
-            if self._timer_hz is None:
+            if timer_hz is None:
                 ln(f"        self._run_step()")
 
         # _fresh
@@ -1015,7 +980,7 @@ class ROSNode:
         ln("    # Control step")
         ln("    # " + "─" * 68)
         ln("    # Builds kwargs from static params, dynamic params, fresh subscription")
-        ln("    # values, and current state, then calls DynamicalSystem.step() and")
+        ln("    # values, and current state, then calls DynamicalSystem.eval() and")
         ln("    # publishes. Skipped entirely when sync_mode conditions are not met.")
         blank()
         ln("    def _run_step(self) -> None:")
@@ -1047,8 +1012,8 @@ class ROSNode:
                     )
 
             blank()
-            ln(f"        # sync_mode={self._sync_mode!r}")
-            if self._sync_mode == "all":
+            ln(f"        # sync_mode={sync_mode!r}")
+            if sync_mode == "all":
                 cond = " or ".join(f"{a} is None" for _, _, _, _, a, _, _, _ in subs)
                 ln(f"        if {cond}:")
                 ln("            return  # not all inputs are fresh — skip this tick")
@@ -1069,11 +1034,9 @@ class ROSNode:
             ln(f'            kwargs["{self._state_key}"] = self._state')
 
         blank()
-        ln("        result = self._system.step(**kwargs)")
+        ln("        x_next, yk = self._system.eval(**kwargs)")
         ln("        if self._system.f is not None:")
-        ln("            self._state, yk = result  # stateful: (next_state, output)")
-        ln("        else:")
-        ln("            yk = result               # stateless: output only")
+        ln("            self._state = x_next  # stateful: advance to next state")
 
         if pubs:
             blank()
@@ -1081,10 +1044,14 @@ class ROSNode:
                 py2ros_name = _ref_name(py2ros, cls)
                 if key is not None:
                     ln(f"        if isinstance(yk, dict) and {key!r} in yk:")
-                    ln(f"            _arr = np.asarray(yk[{key!r}], dtype=float).ravel()")
+                    ln(
+                        f"            _arr = np.asarray(yk[{key!r}], dtype=float).ravel()"
+                    )
                     if topic in _pub_noise:
                         std = _pub_noise[topic]
-                        ln(f"            _arr = _arr + np.random.normal(0.0, {std!r}, _arr.shape)  # noise std={std}")
+                        ln(
+                            f"            _arr = _arr + np.random.normal(0.0, {std!r}, _arr.shape)  # noise std={std}"
+                        )
                     ln(f"            msg = {py2ros_name}(_arr)")
                     ln(f"            if hasattr(msg, 'header'):")
                     ln(
@@ -1095,7 +1062,9 @@ class ROSNode:
                     ln(f"        _arr = np.asarray(yk, dtype=float).ravel()")
                     if topic in _pub_noise:
                         std = _pub_noise[topic]
-                        ln(f"        _arr = _arr + np.random.normal(0.0, {std!r}, _arr.shape)  # noise std={std}")
+                        ln(
+                            f"        _arr = _arr + np.random.normal(0.0, {std!r}, _arr.shape)  # noise std={std}"
+                        )
                     ln(f"        msg = {py2ros_name}(_arr)")
                     ln(f"        if hasattr(msg, 'header'):")
                     ln(

{dynamicalnodes-0.1.2 → dynamicalnodes-0.1.4/src/dynamicalnodes.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dynamicalnodes
-Version: 0.1.2
+Version: 0.1.4
 Summary: dynamicalnodes is a Python library for modeling general control systems.
 Author-email: Nehal Singh Mangat <nehalsinghmangat.software@gmail.com>
 License-Expression: MIT
@@ -44,33 +44,33 @@ Dynamic: license-file
 
 > _"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 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.
+**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 -> World
+## Turtlebot: Whiteboard ⟶ Python ⟶ ROS 2 ⟶ World
 <table>
   <tr>
     <td align="center">
-      <img src="docs/source/_static/figure_turtlebot_pipeline/turtlebot.svg" alt="TurtleBot Overview" width="400"/><br/>
+      <img src="docs/source/_static/figures/turtlebot_schematic.svg" alt="TurtleBot Schematic" width="400"/><br/>
     </td>
     <td align="center">
-      <img src="docs/source/_static/figure_turtlebot_pipeline/turtlesim_software.gif" alt="Turtle Software" width="200"/><br/>
+      <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/figure_turtlebot_pipeline/turtlesim_simulation.gif" alt="Turtle Simulation" width="200"/><br/>
+      <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/figure_turtlebot_pipeline/turtlesim_hardware.gif" alt="Turtle Hardware" width="200"/><br/>
+      <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/figure_turtlebot_pipeline/labels_for_steps_from_theory_to_hardware.png" alt="Step Labels" width="800"/>
+  <img src="docs/source/_static/figures/pipeline_theory_python_ros_hardware.png" alt="Step Labels" width="800"/>
 </p>
 
 

dynamicalnodes-0.1.2/README.md

@@ -1,38 +0,0 @@
-# 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 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 -> World
-<table>
-  <tr>
-    <td align="center">
-      <img src="docs/source/_static/figure_turtlebot_pipeline/turtlebot.svg" alt="TurtleBot Overview" width="400"/><br/>
-    </td>
-    <td align="center">
-      <img src="docs/source/_static/figure_turtlebot_pipeline/turtlesim_software.gif" alt="Turtle Software" width="200"/><br/>
-    </td>
-    <td align="center">
-      <img src="docs/source/_static/figure_turtlebot_pipeline/turtlesim_simulation.gif" alt="Turtle Simulation" width="200"/><br/>
-    </td>
-    <td align="center">
-      <img src="docs/source/_static/figure_turtlebot_pipeline/turtlesim_hardware.gif" alt="Turtle Hardware" width="200"/><br/>
-    </td>
-  </tr>
-</table>
-
-<p align="center">
-  <img src="docs/source/_static/figure_turtlebot_pipeline/labels_for_steps_from_theory_to_hardware.png" alt="Step Labels" width="800"/>
-</p>
-
-
-
-
-
-

dynamicalnodes-0.1.2/src/dynamicalnodes/dynamical_system.py

@@ -1,226 +0,0 @@
-"""
-Core abstraction for modeling dynamical systems in dynamicalnodes.
-
-A dynamical system is defined by two functions:
-- f: State transition function (optional) - computes next state
-- h: Observation function (required) - computes output from state
-
-This abstraction allows any control system component (plants, controllers,
-observers, reference signals) to be modeled uniformly and composed together.
-"""
-
-import inspect
-from typing import Any, Callable, Dict, Optional
-
-
-class DynamicalSystem:
-    """
-    A discrete-time dynamical system with state transition and observation functions.
-
-    This class provides a unified abstraction for modeling control system components.
-    Each component is defined by:
-
-    - **f(x_k, u_k, ...) -> x_{k+1}**: State transition function (optional)
-    - **h(x_k, u_k, ...) -> y_k**: Observation/output function (required)
-
-    The `step()` method executes one timestep: it calls f to update state,
-    then calls h to compute the output.
-
-    Parameters
-    ----------
-    f : Callable, optional
-        State transition function. Signature: f(x_k, u_k, ...) -> x_{k+1}
-        If None, the system is stateless (e.g., a reference signal generator).
-    h : Callable
-        Observation function. Signature: h(x_k, u_k, ...) -> y_k
-        This function computes the system output.
-
-    Examples
-    --------
-    Stateless reference signal (step function):
-
-    >>> def h_ref(tk, params):
-    ...     u0, t_step = params
-    ...     return u0 if tk >= t_step else 0.0
-    >>> ref_signal = DynamicalSystem(h=h_ref)
-    >>> ref_signal.step(tk=0.0, params=(100, 15))  # Before step time
-    0.0
-    >>> ref_signal.step(tk=20.0, params=(100, 15))  # After step time
-    100
-
-    Stateful plant (discrete-time integrator):
-
-    >>> def f_plant(x_k, u_k, dt):
-    ...     return x_k + u_k * dt
-    >>> def h_plant(x_k, u_k, dt):
-    ...     return x_k
-    >>> plant = DynamicalSystem(f=f_plant, h=h_plant)
-    >>> x_next, y = plant.step(x_k=0.0, u_k=1.0, dt=0.1)
-    >>> x_next
-    0.1
-
-    Notes
-    -----
-    The `_smart_call` mechanism allows flexible parameter binding. Functions
-    only receive the parameters they declare in their signature, enabling
-    components with different interfaces to be composed together.
-
-    See Also
-    --------
-    ROSNode : Wraps a DynamicalSystem as a ROS2 node for deployment.
-    """
-
-    def __init__(
-        self,
-        *,
-        f: Optional[Callable] = None,
-        h: Callable,
-    ) -> None:
-        """
-        Initialize a DynamicalSystem with state transition and observation functions.
-
-        Parameters
-        ----------
-        f : Callable, optional
-            State transition function: f(x_k, u_k, ...) -> x_{k+1}
-        h : Callable
-            Observation function: h(x_k, u_k, ...) -> y_k
-        """
-        self._f = f
-        self._h = h
-
-    @property
-    def f(self) -> Optional[Callable]:
-        """State transition function f(x_k, u_k, ...) -> x_{k+1}, or None if stateless."""
-        return self._f
-
-    @f.setter
-    def f(self, f: Optional[Callable]) -> None:
-        self._f = f
-
-    @property
-    def h(self) -> Callable:
-        """Observation function h(x_k, u_k, ...) -> y_k."""
-        return self._h
-
-    @h.setter
-    def h(self, h: Callable) -> None:
-        self._h = h
-
-    @staticmethod
-    def _smart_call(
-        func: Callable[..., Any],
-        **kwargs: Any,
-    ) -> Any:
-        """
-        Call a function with smart parameter binding by name.
-
-        This method inspects the function signature and passes only the
-        parameters that the function declares. This enables flexible
-        composition of components with different interfaces.
-
-        Parameters
-        ----------
-        func : Callable
-            The function to call.
-        **kwargs : Any
-            Keyword arguments pool. Only arguments matching the function's
-            declared parameters are passed.
-
-        Returns
-        -------
-        Any
-            The return value of the function.
-
-        Notes
-        -----
-        If the function has a **kwargs parameter, all remaining kwargs
-        from the pool are passed through.
-
-        Examples
-        --------
-        Functions receive only the parameters they declare:
-
-        >>> def needs_time(tk, gain): return tk * gain
-        >>> def needs_state(xk, gain): return (xk, gain)
-        >>> def needs_both(tk, xk, gain): return (tk, xk, gain)
-
-        >>> DynamicalSystem._smart_call(needs_time, tk=1.0, xk=[0, 0], gain=2.0)
-        2.0
-        >>> DynamicalSystem._smart_call(needs_state, tk=1.0, xk=[5, 5], gain=2.0)
-        ([5, 5], 2.0)
-        >>> DynamicalSystem._smart_call(needs_both, tk=1.0, xk='state', gain=2.0)
-        (1.0, 'state', 2.0)
-        """
-        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)
-
-    def step(self, **kwargs: Any) -> Any:
-        """
-        Execute one timestep of the dynamical system.
-
-        This method calls the state transition function f (if defined) and
-        the observation function h with the provided keyword arguments.
-
-        Parameters
-        ----------
-        **kwargs : Any
-            Keyword arguments passed to f and h. Each function receives
-            only the kwargs it declares in its signature via `_smart_call`.
-
-            A reserved key ``_state`` may be passed to inject the current
-            state without knowing ``f``'s first parameter name. It is
-            removed from kwargs before dispatch and inserted under the
-            correct name automatically.
-
-        Returns
-        -------
-        Any
-            If f is None (stateless system):
-                Returns y_k = h(...)
-            If f is defined (stateful system):
-                Returns (x_{k+1}, y_k) = (f(...), h(...))
-
-        Examples
-        --------
-        Stateless system (no f):
-
-        >>> def h(tk): return tk * 2
-        >>> sys = DynamicalSystem(h=h)
-        >>> sys.step(tk=5.0)
-        10.0
-
-        Stateful system (with f):
-
-        >>> def f(x, u): return x + u
-        >>> def h(x, u): return x
-        >>> sys = DynamicalSystem(f=f, h=h)
-        >>> x_next, y = sys.step(x=0.0, u=1.0)
-        >>> x_next, y
-        (1.0, 0.0)
-        """
-        if self.f is None:
-            return self._smart_call(self.h, **kwargs)
-
-        return (
-            self._smart_call(self.f, **kwargs),
-            self._smart_call(self.h, **kwargs),
-        )