dynamicalnodes 0.1.4__tar.gz → 0.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dynamicalnodes
-Version: 0.1.4
+Version: 0.2.0
 Summary: dynamicalnodes is a Python library for modeling general control systems.
 Author-email: Nehal Singh Mangat <nehalsinghmangat.software@gmail.com>
 License-Expression: MIT

{dynamicalnodes-0.1.4 → dynamicalnodes-0.2.0}/pyproject.toml

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

{dynamicalnodes-0.1.4 → dynamicalnodes-0.2.0}/src/dynamicalnodes/dynamical_system.py

@@ -16,7 +16,7 @@ the paper, ``None`` here -- giving three cases:
 - ``(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
+parameters. ``DynamicalSystem.step`` 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``.
 """
@@ -53,7 +53,7 @@ class DynamicalSystem:
     ...     _, 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, y = car.step(xk=(20.0, 0.0), uk=4.0, theta_car=(2.0, 0.0, 1.0))
     >>> x_next
     (20.0, 2.0)
     >>> y
@@ -64,9 +64,9 @@ class DynamicalSystem:
     >>> 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)
+    >>> ref.step(tk=0.0)
     (None, 0.0)
-    >>> ref.eval(tk=2.0)
+    >>> ref.step(tk=2.0)
     (None, 1.0)
 
     A system with no output function -- ``(f, *)``:
@@ -74,7 +74,7 @@ class DynamicalSystem:
     >>> def f_counter(xk):
     ...     return xk + 1
     >>> counter = DynamicalSystem(f=f_counter)
-    >>> counter.eval(xk=5)
+    >>> counter.step(xk=5)
     (6, None)
     """
 
@@ -97,6 +97,26 @@ class DynamicalSystem:
         self._f = f
         self._h = h
 
+    def __repr__(self) -> str:
+        """
+        Show the system as its ``(f, h)`` pair, using ``*`` for whichever
+        half is unset -- matching the paper's notation.
+
+        Examples
+        --------
+        >>> def fcar(xk): return xk
+        >>> def hcar(xk): return xk
+        >>> DynamicalSystem(f=fcar, h=hcar)
+        (fcar, hcar)
+        >>> DynamicalSystem(f=fcar)
+        (fcar, *)
+        >>> DynamicalSystem(h=hcar)
+        (*, hcar)
+        """
+        f_name = self._f.__name__ if self._f is not None else "*"
+        h_name = self._h.__name__ if self._h is not None else "*"
+        return f"({f_name}, {h_name})"
+
     @property
     def f(self) -> Optional[Callable]:
         """Evolution function f(x_k, u_k, theta) -> x_{k+1}, or None if the system is stateless."""
@@ -115,7 +135,7 @@ class DynamicalSystem:
     def h(self, h: Optional[Callable]) -> None:
         self._h = h
 
-    def eval(self, **kwargs) -> Tuple[Optional[Any], Optional[Any]]:
+    def step(self, **kwargs) -> Tuple[Optional[Any], Optional[Any]]:
         """
         Evaluate the system for one discrete time step.
 
@@ -150,7 +170,7 @@ class DynamicalSystem:
         cases.
 
         >>> empty = DynamicalSystem()
-        >>> empty.eval()
+        >>> empty.step()
         Traceback (most recent call last):
             ...
         ValueError: Nothing to evaluate; no f or h functions!

{dynamicalnodes-0.1.4 → dynamicalnodes-0.2.0}/src/dynamicalnodes/rosnode.py

@@ -3,7 +3,7 @@ ROSNode wrapper for simulation and ROS2 deployment.
 
 Two workflows:
 
-**Simulation** — call ``eval()`` directly in Python or Jupyter notebooks to test ros2py and/or py2ros translation functions.
+**Simulation** — call ``step()`` 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
@@ -36,7 +36,7 @@ class ROSNode:
     """
     Wraps a DynamicalSystem for simulation and ROS2 deployment.
 
-    Use ``eval()`` for notebook simulation; use ``write_ROSNode_to_rclpy()`` to
+    Use ``step()`` for notebook simulation; use ``write_ROSNode_to_rclpy()`` to
     generate a deployable rclpy node.
 
     Parameters
@@ -48,10 +48,9 @@ class ROSNode:
 
         - ``"topic"`` (str): ROS topic name.
         - ``"msg_type"`` (type): ROS message class.
-        - ``"arg"`` (str): kwarg name passed to eval().
+        - ``"arg"`` (str): kwarg name passed to step().
         - ``"ros2py"`` (Callable): ROS msg → NumPy array converter.
           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
           subscription buffer stores the message's own ``header.stamp``
@@ -74,14 +73,14 @@ class ROSNode:
     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``.  ``eval()`` injects ``self._state`` under this name before
-        calling ``DynamicalSystem.eval()``.
+        ``None``.  ``step()`` injects ``self._state`` under this name before
+        calling ``DynamicalSystem.step()``.
 
     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.
+    ``sync_mode``, ``timer_hz``, and ``stale_after`` 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
     --------
@@ -100,7 +99,7 @@ class ROSNode:
     ...     pubs=[{"topic": "/smooth", "msg_type": Float64,
     ...            "py2ros": py2ros_float64}],
     ... )
-    >>> out = node.eval(imu=np.array([2.0]))
+    >>> out = node.step(imu=np.array([2.0]))
     >>> out.data
     1.0
     """
@@ -118,7 +117,7 @@ class ROSNode:
         self._state_key: Optional[str] = state_name
 
         # -------- Parse subscriptions --------
-        self._subs: List[Tuple[str, type, Any, str, Optional[float], int, bool]] = []
+        self._subs: List[Tuple[str, type, Any, str, int, bool]] = []
         for sub_dict in subs or []:
             if not isinstance(sub_dict, dict):
                 raise TypeError("Each subscription must be a dict")
@@ -127,7 +126,6 @@ class ROSNode:
             msg_type = sub_dict.get("msg_type")
             arg_name = sub_dict.get("arg")
             ros2py = sub_dict.get("ros2py")
-            stale_after = sub_dict.get("stale_after")
             buffer_size = sub_dict.get("buffer_size", 1)
             use_msg_timestamp = bool(sub_dict.get("use_msg_timestamp", False))
 
@@ -159,7 +157,6 @@ class ROSNode:
                     msg_type,
                     ros2py,
                     arg_name,
-                    float(stale_after) if stale_after else None,
                     int(buffer_size),
                     use_msg_timestamp,
                 )
@@ -204,7 +201,7 @@ class ROSNode:
     # SIMULATION API
     # --------------------------------------------------------------------------
 
-    def eval(self, **kwargs: Any) -> Any:
+    def step(self, **kwargs: Any) -> Any:
         """
         Simulate one step without ROS2.
 
@@ -241,10 +238,10 @@ class ROSNode:
         ...     pubs=[{"topic": "/y", "msg_type": Float64,
         ...            "py2ros": py2ros_float64}],
         ... )
-        >>> node.eval(x=Float64(data=3.0)).data
+        >>> node.step(x=Float64(data=3.0)).data
         6.0
         """
-        sub_arg_names = {a for _, _, _, a, _, _, _ in self._subs}
+        sub_arg_names = {a for _, _, _, a, _, _ in self._subs}
         step_kwargs: Dict[str, Any] = {}
 
         for arg_name, value in kwargs.items():
@@ -252,7 +249,7 @@ class ROSNode:
                 continue
             if arg_name in sub_arg_names:
                 ros2py = next(
-                    (c for _, _, c, a, _, _, _ in self._subs if a == arg_name), None
+                    (c for _, _, c, a, _, _ in self._subs if a == arg_name), None
                 )
                 assert ros2py is not None
                 if hasattr(value, "__slots__") or hasattr(
@@ -267,7 +264,7 @@ class ROSNode:
         if self._state is not None and self._state_key is not None:
             step_kwargs[self._state_key] = self._state
 
-        x_next, yk = self._dynamical_system.eval(**step_kwargs)
+        x_next, yk = self._dynamical_system.step(**step_kwargs)
         if self._dynamical_system.f is not None:
             self._state = x_next
 
@@ -304,6 +301,7 @@ class ROSNode:
         node_name: str,
         sync_mode: Optional[str] = None,
         timer_hz: Optional[float] = None,
+        stale_after: Optional[Dict[str, float]] = None,
         deps: Optional[List[Any]] = None,
         initial_state: Optional[Any] = None,
         initial_inputs: Optional[Dict[str, Any]] = None,
@@ -334,6 +332,15 @@ class ROSNode:
         timer_hz : float, optional
             Fires ``_run_step`` at this frequency instead of triggering from
             subscription callbacks.
+        stale_after : dict, optional
+            Maximum age, in seconds, a buffered subscription value may have
+            before it's treated as stale — dropped to ``None``, the same as
+            an empty buffer, instead of being reused indefinitely. Keys must
+            match subscription ``arg`` names; a subscription not listed here
+            never expires. Use this to bound how long a value may go
+            unrefreshed before a step must skip (``sync_mode="all"``) or
+            ignore (``sync_mode="any"``) it.
+            Example: ``{"rk": 0.2, "xhatk": 0.2}``.
         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.
@@ -344,7 +351,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 ``eval()``
+            ``self._static_params = {...}`` and merged into every ``step()``
             call.  Use for values that never change after deployment.
         dynamic_params : dict, optional
             Parameters declared on the ROS2 parameter server with their
@@ -358,9 +365,9 @@ class ROSNode:
             restarting the node (e.g. controller gains).
         initial_inputs : dict, optional
             Cold-start fallback values for subscription inputs.  Keys must
-            match subscription ``arg`` names.  A value is used only when the
-            subscription buffer is completely empty — i.e. no message has
-            ever arrived on that topic.  Once the first message arrives the
+            match subscription ``arg`` names.  A value is used only while no
+            message has ever arrived on that topic (consuming a buffered
+            value in a step does not count as "never arrived").  Once the first message arrives the
             subscription value takes over permanently.  If the subscription
             later goes stale the step is skipped (``None`` is not replaced),
             preventing silent operation on dead data.  Use this to break
@@ -394,6 +401,11 @@ class ROSNode:
             If the generated file contains invalid Python (indicates a bug
             in the generator).
 
+        Returns
+        -------
+        None
+            The generated node is written to ``path``.
+
         Notes
         -----
         **Function resolution**
@@ -420,15 +432,15 @@ class ROSNode:
         >>> node = ROSNode(
         ...     dynamical_system=sys,
         ...     subs=[{"topic": "/u_k", "msg_type": Float64,
-        ...            "arg": "u_k", "ros2py": ros2py_float64,
-        ...            "stale_after": 0.5}],
+        ...            "arg": "u_k", "ros2py": ros2py_float64}],
         ...     pubs=[{"topic": "/y_k", "msg_type": Float64,
         ...            "py2ros": py2ros_float64}],
         ... )
         >>> with tempfile.NamedTemporaryFile(suffix=".py", delete=False) as tmp:
         ...     path = tmp.name
         >>> node.write_ROSNode_to_rclpy(path, node_name="plant",
-        ...                             initial_state=np.array([0.0]))
+        ...                             initial_state=np.array([0.0]),
+        ...                             stale_after={"u_k": 0.5})
         >>> content = open(path).read()
         >>> "def f_plant" in content and "def h_plant" in content
         True
@@ -438,6 +450,8 @@ class ROSNode:
         True
         >>> "SingleThreadedExecutor" in content
         True
+        >>> "_u_k_seen" in content
+        True
         >>> os.unlink(path)
         """
         import importlib
@@ -588,21 +602,26 @@ class ROSNode:
         ds = self._dynamical_system
         _check_lambda(ds.f, "DynamicalSystem.f")
         _check_lambda(ds.h, "DynamicalSystem.h")
-        for _, _, ros2py, arg, _, _, _ in self._subs:
+        for _, _, ros2py, arg, _, _ in self._subs:
             _check_lambda(ros2py, f"ros2py for '{arg}'")
         for _, _, py2ros, key in self._pubs_cfg:
             _check_lambda(py2ros, f"py2ros for key={key!r}")
 
         _sub_noise: Dict[str, float] = dict(sub_noise or {})
         _pub_noise: Dict[str, float] = dict(pub_noise or {})
+        _stale_after: Dict[str, float] = dict(stale_after or {})
         _valid_sub_topics = {t for t, *_ in self._subs}
         _valid_pub_topics = {t for t, *_ in self._pubs_cfg}
+        _valid_sub_args = {a for _, _, _, a, _, _ in self._subs}
         for t in _sub_noise:
             if t not in _valid_sub_topics:
                 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 pubs")
+        for a in _stale_after:
+            if a not in _valid_sub_args:
+                raise ValueError(f"stale_after key {a!r} not a subscription 'arg'")
 
         # ── classify all functions ─────────────────────────────────────────────
 
@@ -611,7 +630,7 @@ class ROSNode:
 
         # subs: [(topic, msg_type, ros2py, cls, arg, stale, buf, use_msg_ts), ...]
         subs = []
-        for topic, msg_type, ros2py, arg, stale, buf, use_msg_ts in self._subs:
+        for topic, msg_type, ros2py, arg, buf, use_msg_ts in self._subs:
             subs.append(
                 (
                     topic,
@@ -619,7 +638,7 @@ class ROSNode:
                     ros2py,
                     _classify(ros2py),
                     arg,
-                    stale,
+                    _stale_after.get(arg),
                     buf,
                     use_msg_ts,
                 )
@@ -891,6 +910,7 @@ class ROSNode:
             ln("        # ── Subscription buffers " + "─" * 47)
             for _, _, _, _, arg, _, buf, _ in subs:
                 ln(f"        self._{arg}_buf: deque = deque(maxlen={buf})")
+                ln(f"        self._{arg}_seen: bool = False  # any message ever received")
 
             blank()
             ln("        # ── Subscriptions " + "─" * 52)
@@ -937,7 +957,11 @@ class ROSNode:
             ln(
                 "    # enables the staleness check in _fresh(). _run_step() proceeds only when"
             )
-            ln("    # sync_mode conditions are satisfied.")
+            ln(
+                "    # sync_mode conditions are satisfied, and pops each value it consumes —"
+            )
+            ln("    # so a stored value can trigger at most one step before it must be")
+            ln("    # refreshed by new data.")
         for topic, msg_type, ros2py, cls, arg, _, _, use_msg_ts in subs:
             ros2py_name = _ref_name(ros2py, cls)
             blank()
@@ -957,6 +981,7 @@ class ROSNode:
             else:
                 ln(f"        ts = self.get_clock().now().nanoseconds * 1e-9")
             ln(f"        self._{arg}_buf.append((ts, arr))")
+            ln(f"        self._{arg}_seen = True")
             if timer_hz is None:
                 ln(f"        self._run_step()")
 
@@ -980,7 +1005,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.eval() and")
+        ln("    # values, and current state, then calls DynamicalSystem.step() and")
         ln("    # publishes. Skipped entirely when sync_mode conditions are not met.")
         blank()
         ln("    def _run_step(self) -> None:")
@@ -1006,7 +1031,7 @@ class ROSNode:
                     "        # Cold-start fallbacks — used only before first message arrives"
                 )
                 for arg in cold_start_args:
-                    ln(f"        if {arg} is None and not self._{arg}_buf:")
+                    ln(f"        if {arg} is None and not self._{arg}_seen:")
                     ln(
                         f"            {arg} = {_repr_value(_initial[arg])}  # initial input"
                     )
@@ -1022,6 +1047,17 @@ class ROSNode:
                 ln(f"        if {cond}:")
                 ln("            return  # all inputs are stale — skip this tick")
 
+            blank()
+            ln("        # Consume: pop each fresh value now that we're committing to a")
+            ln(
+                "        # step, so it cannot re-trigger another step until genuinely new"
+            )
+            ln("        # data arrives (prevents event-driven feedback loops from")
+            ln("        # cascading at an unbounded rate).")
+            for _, _, _, _, arg, _, _, _ in subs:
+                ln(f"        if {arg} is not None and self._{arg}_buf:")
+                ln(f"            self._{arg}_buf.pop()")
+
         blank()
         ln('        kwargs: dict = {"tk": tk, **self._static_params}')
         for name in _dynamic:
@@ -1034,7 +1070,7 @@ class ROSNode:
             ln(f'            kwargs["{self._state_key}"] = self._state')
 
         blank()
-        ln("        x_next, yk = self._system.eval(**kwargs)")
+        ln("        x_next, yk = self._system.step(**kwargs)")
         ln("        if self._system.f is not None:")
         ln("            self._state = x_next  # stateful: advance to next state")
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dynamicalnodes
-Version: 0.1.4
+Version: 0.2.0
 Summary: dynamicalnodes is a Python library for modeling general control systems.
 Author-email: Nehal Singh Mangat <nehalsinghmangat.software@gmail.com>
 License-Expression: MIT