add ml agent base class; add module and submodule level docstrings

pyrcf/__init__.py

@@ -0,0 +1,13 @@
+"""A Python Robot Control Framework for quickly prototyping control algorithms for different robot
+embodiments.
+
+Primarily, this library provides an implementation of a typical control loop (via a
+`MinimalCtrlLoop` (extended from `SimpleManagedCtrlLoop`) class), and defines interfaces for the
+components in a control loop that can be used directly in these control loop implementations. It
+also provides utility and debugging tools that will be useful for developing controllers and
+planners for different robots. This package also provides implementations of basic controllers
+and planners.
+
+In the long run, this package will also provide implementations of popular motion planners and
+controllers from literature and using existing libraries.
+"""

pyrcf/components/__init__.py

@@ -1,3 +1,3 @@
-"""Base classes for control loop components."""
+"""Components that can be run in the control loop."""
 
 from .pyrcf_component import PyRCFComponent

pyrcf/components/agents/__init__.py

@@ -1,2 +1,9 @@
+"""Defines agents that can be used to compute control commands to be sent to
+a robot given a global plan (target/task). When using 'classical' methods,
+an agent may just be a local planner + a controller (use the PlannerControllerAgent in
+this case). When using machine-learned controller, this could be a policy that direcly
+uses the global plan and outputs a robot command (implement an agent from MLAgentBase)."""
+
 from .agent_base import AgentBase, DummyAgent
 from .planner_controller_agent import PlannerControllerAgent
+from .ml_agent_base import MLAgentBase

pyrcf/components/agents/ml_agent_base.py

@@ -0,0 +1,79 @@
+from abc import ABC, abstractmethod
+import numpy as np
+
+from ...core.types import (
+    GlobalMotionPlan,
+    RobotCmd,
+    RobotState,
+    JointStates,
+)
+from .agent_base import AgentBase
+
+
+class MLAgentBase(AgentBase, ABC):
+    """An abstract base class machine-learned controller agents.
+
+    See docstrings for each method to be implemented.
+    """
+
+    @abstractmethod
+    def initialise_robot_cmd(self, joint_states: JointStates):
+        """Override this method in child class if custom initilisation is required (e.g. joint name order).
+        By default, this method sets the joint name and position values to be equal to the input joint states
+        object, with kp and kd set to be the default (in constructor).
+        """
+
+    @abstractmethod
+    def update_input_to_model(
+        self,
+        robot_state: RobotState,
+        global_plan: GlobalMotionPlan,
+        t: float,
+        dt: float,
+    ) -> np.ndarray:
+        """Should update (`self._input_ndarray`) using appropriate values (input to model). This method
+        has access to `self._latest_ctrl_cmd` (type `RobotCmd`) as well if needed.
+        (NOTE: `self._latest_ctrl_cmd` is set to be the initial robot joint positions (zero velocities
+        and efforts commands) with `default_kp` and `default_kd` at start).
+        """
+
+    @abstractmethod
+    def update_cmd_from_model_output(
+        self,
+        model_output: np.ndarray,
+        robot_state: RobotState,
+        global_plan: GlobalMotionPlan,
+        t: float,
+        dt: float,
+    ) -> None:
+        """Should update `self._latest_robot_cmd` (type `RobotCmd`) using the output from the NN model.
+
+        Args:
+            model_output (np.ndarray): the numpy array created from the output tensor from the model
+                after the inference query was done. This is the output of the neural network. This
+                method should use this object to update `self._latest_robot_cmd` to be sent to the
+                robot.
+        """
+
+    @abstractmethod
+    def get_action(
+        self,
+        robot_state: RobotState,
+        global_plan: GlobalMotionPlan,
+        t: float = None,
+        dt: float = None,
+    ) -> RobotCmd:
+        """Should return the control command given the current robot state and global plan.
+
+        Args:
+            robot_state (RobotState): The current state information from the robot.
+            global_plan (GlobalMotionPlan): the latest global plan generated by the global planner
+                used in the loop.
+            t (float, optional): the current time signature of the control loop. Defaults to None
+                (controllers may or may not need this).
+            dt (float, optional): the time since the last control loop. Defaults to None
+                (controllers may or may not need this).
+
+        Returns:
+            RobotCmd: The output control command to be sent to the robot.
+        """

pyrcf/components/callback_handlers/__init__.py

@@ -1 +1,3 @@
+"""Defines custom callbacks that can be run in the control loop (pre-step and post-step)."""
+
 from .base_callbacks import CustomCallbackBase, RateTriggeredMultiCallbacks

pyrcf/components/controller_manager/__init__.py

@@ -1,2 +1,5 @@
+"""Defines controller managers that can be used to handle multiple controllers
+in the control loop."""
+
 from .controller_manager_base import ControllerManagerBase
 from .simple_controller_manager import SimpleControllerManager

pyrcf/components/controller_manager/command_accumulators/__init__.py

@@ -1 +1,4 @@
+"""Accumulation policies will decide how control commands from multiple controllers (if present)
+in the same control loop will be combined before sending them to the robot."""
+
 from .cmd_accumulation_policies import CommandAccumulatorBase, SimpleCmdOverride

pyrcf/components/controllers/__init__.py

@@ -1 +1,3 @@
+"""Module containing interface and definitions of controllers that can be used in the control loop."""
+
 from .controller_base import ControllerBase, DummyController

pyrcf/components/ctrl_loop_debuggers/__init__.py

@@ -1 +1,4 @@
+"""Module containing interface and definitions of control loop debuggers that
+can be used in the control loop."""
+
 from .ctrl_loop_debugger_base import CtrlLoopDebuggerBase, DummyDebugger

pyrcf/components/global_planners/__init__.py

@@ -1 +1,4 @@
+"""Module containing interface and definitions of global planners (and ui reference generators)
+that can be used in the control loop."""
+
 from .global_planner_base import GlobalMotionPlannerBase

pyrcf/components/global_planners/ui_reference_generators/__init__.py

@@ -1 +1,4 @@
+"""Module containing interface and definitions of User interfaces such as keyboard interface and
+joystick interface that can be used in the control loop in place of true Global planners."""
+
 from .ui_base import UIBase, DummyUI

pyrcf/components/local_planners/__init__.py

@@ -1 +1,4 @@
+"""Module containing interface and definitions of local planner components that can be used in the
+control loop."""
+
 from .local_planner_base import LocalPlannerBase, DummyLocalPlanner

pyrcf/components/robot_interfaces/__init__.py

@@ -1 +1,6 @@
+"""Defines interface for robots that can be used in the control loop.
+
+Also has a submodule for simulated robots.
+"""
+
 from .robot_interface_base import RobotInterface, DummyRobot

pyrcf/components/state_estimators/__init__.py

@@ -1 +1,6 @@
+"""Defines state estimators that can be used in the control loop.
+Currently, because we operate only in simulation, we directly use
+data from the simulator and do not use any custom state estimation
+algorithms."""
+
 from .state_estimator_base import StateEstimatorBase, DummyStateEstimator

pyrcf/core/__init__.py

@@ -0,0 +1,2 @@
+"""Contains the core components that are used to create PyRCF control loops and control loop
+components."""

pyrcf/executables/__init__.py

@@ -0,0 +1,2 @@
+"""Contains executable scripts that will be installed with the package and
+can be run globally from the python environment."""

pyrcf/utils/__init__.py

@@ -0,0 +1 @@
+"""Helper utilities for use in PyRCF library."""