dynamicalnodes 0.1__tar.gz

dynamicalnodes-0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nehal Singh Mangat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dynamicalnodes-0.1/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: dynamicalnodes
+Version: 0.1
+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
+Keywords: control,estimation,ros2
+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: myst_nb; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints>=1.24.0; extra == "docs"
+Requires-Dist: matplotlib>=3.7; extra == "docs"
+Requires-Dist: scipy>=1.11; extra == "docs"
+Requires-Dist: jupyter; extra == "docs"
+Dynamic: license-file
+
+![Doctest Status](https://github.com/nehalsinghmangat/dynamicalnodes/actions/workflows/doctest.yml/badge.svg) [![Doctest Status](https://github.com/nehalsinghmangat/dynamicalnodes/actions/workflows/doctest.yml)](https://github.com/nehalsinghmangat/dynamicalnodes/actions/workflows/doctest.yml)
+
+# dynamicalnodes: From Theory to Python to ROS
+
+> _"Cross a river once, swim; cross a river a thousand times, build a bridge."_  — Punjabi saying
+
+**dynamicalnodes** is a Python development framework that bridges the chasm between theoretical control systems and their implementation in hardware. Designed for hobbyists, students, and academics alike, this framework won't cure cancer, but it can do the next best thing: make controlling robots easier.
+
+To get started, or to explore what this framework has to offer, click here: [dynamicalnodes Documentation](https://dynamicalnodes.readthedocs.io).
+
+For a 22 second video describing this framework's intended workflow for, please click here: [SAIL 2025 -- Presenting dynamicalnodes](https://youtu.be/5GbVHo6QZrw).
+
+---
+## Turtlebot: A journey of four steps
+<table>
+  <tr>
+    <td align="center">
+      <img src="docs/source/_static/tikz/turtlebot/turtlebot.svg" alt="TurtleBot Overview" width="400"/><br/>
+    </td>
+    <td align="center">
+      <img src="docs/source/_static/gif/turtlesim_software.gif" alt="Turtle Software" width="200"/><br/>
+    </td>
+    <td align="center">
+      <img src="docs/source/_static/gif/turtlesim_simulation.gif" alt="Turtle Simulation" width="200"/><br/>
+    </td>
+    <td align="center">
+      <img src="docs/source/_static/gif/turtlesim_hardware.gif" alt="Turtle Hardware" width="200"/><br/>
+    </td>
+  </tr>
+</table>
+
+<p align="center">
+  <img src="docs/source/_static/misc/labels_for_steps_from_theory_to_hardware.png" alt="Step Labels" width="800"/>
+</p>
+
+---
+## 👁️ Watch for Releases
+
+To get notified when **dynamicalnodes** is officially released:
+
+1. Go to the GitHub repo: [https://github.com/nehalsinghmangat/dynamicalnodes](https://github.com/nehalsinghmangat/dynamicalnodes)
+2. Click the `👁️ Watch` button near the top-right of the page.
+3. Select **"Custom"** or **"Releases only"** from the dropdown.
+4. Ensure **"Releases"** is checked.
+
+You’ll now receive notifications when the first release is published!
+
+
+
+

dynamicalnodes-0.1/README.md

@@ -0,0 +1,50 @@
+![Doctest Status](https://github.com/nehalsinghmangat/dynamicalnodes/actions/workflows/doctest.yml/badge.svg) [![Doctest Status](https://github.com/nehalsinghmangat/dynamicalnodes/actions/workflows/doctest.yml)](https://github.com/nehalsinghmangat/dynamicalnodes/actions/workflows/doctest.yml)
+
+# dynamicalnodes: From Theory to Python to ROS
+
+> _"Cross a river once, swim; cross a river a thousand times, build a bridge."_  — Punjabi saying
+
+**dynamicalnodes** is a Python development framework that bridges the chasm between theoretical control systems and their implementation in hardware. Designed for hobbyists, students, and academics alike, this framework won't cure cancer, but it can do the next best thing: make controlling robots easier.
+
+To get started, or to explore what this framework has to offer, click here: [dynamicalnodes Documentation](https://dynamicalnodes.readthedocs.io).
+
+For a 22 second video describing this framework's intended workflow for, please click here: [SAIL 2025 -- Presenting dynamicalnodes](https://youtu.be/5GbVHo6QZrw).
+
+---
+## Turtlebot: A journey of four steps
+<table>
+  <tr>
+    <td align="center">
+      <img src="docs/source/_static/tikz/turtlebot/turtlebot.svg" alt="TurtleBot Overview" width="400"/><br/>
+    </td>
+    <td align="center">
+      <img src="docs/source/_static/gif/turtlesim_software.gif" alt="Turtle Software" width="200"/><br/>
+    </td>
+    <td align="center">
+      <img src="docs/source/_static/gif/turtlesim_simulation.gif" alt="Turtle Simulation" width="200"/><br/>
+    </td>
+    <td align="center">
+      <img src="docs/source/_static/gif/turtlesim_hardware.gif" alt="Turtle Hardware" width="200"/><br/>
+    </td>
+  </tr>
+</table>
+
+<p align="center">
+  <img src="docs/source/_static/misc/labels_for_steps_from_theory_to_hardware.png" alt="Step Labels" width="800"/>
+</p>
+
+---
+## 👁️ Watch for Releases
+
+To get notified when **dynamicalnodes** is officially released:
+
+1. Go to the GitHub repo: [https://github.com/nehalsinghmangat/dynamicalnodes](https://github.com/nehalsinghmangat/dynamicalnodes)
+2. Click the `👁️ Watch` button near the top-right of the page.
+3. Select **"Custom"** or **"Releases only"** from the dropdown.
+4. Ensure **"Releases"** is checked.
+
+You’ll now receive notifications when the first release is published!
+
+
+
+

dynamicalnodes-0.1/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = [
+  "setuptools>=61.0",
+  "wheel"
+]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dynamicalnodes"
+version = "0.1"
+description = "dynamicalnodes is a Python library for modeling general control systems."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [
+  { name = "Nehal Singh Mangat", email = "nehalsinghmangat.software@gmail.com" }
+]
+keywords = ["control", "estimation", "ros2"]
+dependencies = [
+  "numpy>=1.24",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.0",
+  "pytest-doctestplus>=1.0.0",
+  "flake8>=6.0",
+  "black>=24.0",
+  "isort>=6.0",
+  "mypy>=1.0",
+  "build>=0.10",
+  "twine>=4.0",
+]
+
+docs = [
+  "sphinx>=8.0",
+  "sphinx-rtd-theme>=1.3",
+  "myst_nb",
+  "sphinx-autodoc-typehints>=1.24.0",
+  "matplotlib>=3.7",
+  "scipy>=1.11",
+  "jupyter",
+]
+
+[project.urls]
+Homepage = "https://github.com/nehalsinghmangat/dynamicalnodes"
+Documentation = "https://nehalsinghmangat.github.io/dynamicalnodes"
+
+[tool.pytest.ini_options]
+addopts = "--doctest-modules"
+doctest_optionflags = ["NORMALIZE_WHITESPACE", "ELLIPSIS"]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

dynamicalnodes-0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

dynamicalnodes-0.1/src/dynamicalnodes/__init__.py

@@ -0,0 +1,35 @@
+"""
+dynamicalnodes: A modular Python framework for dynamical systems, estimation, and ROS2 integration.
+"""
+
+from .dynamical_system import DynamicalSystem
+from . import rostools
+
+# Lazy imports for ROS2-dependent symbols — only fail if actually used
+def __getattr__(name):
+    if name == "ROSNode":
+        try:
+            from .rosnode import ROSNode
+            return ROSNode
+        except ImportError as e:
+            raise ImportError(
+                f"ROSNode requires ROS2 dependencies. Install with: pip install dynamicalnodes[ros2]\n"
+                f"Original error: {e}"
+            ) from e
+    if name == "reset_ros":
+        try:
+            from .rostools import reset_ros
+            return reset_ros
+        except ImportError as e:
+            raise ImportError(
+                f"reset_ros 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",
+    "reset_ros",
+    "rostools",
+]

dynamicalnodes-0.1/src/dynamicalnodes/dynamical_system.py

@@ -0,0 +1,221 @@
+"""
+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`.
+
+        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),
+        )