prpl_utils 0.0.1__tar.gz

prpl_utils-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Tom Silver
+
+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.

prpl_utils-0.0.1/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: prpl_utils
+Version: 0.0.1
+Summary: Common Python utilities for the Princeton Robot Planning and Learning lab.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Requires-Dist: graphviz
+Requires-Dist: pyperplan
+Requires-Dist: gymnasium
+Requires-Dist: moviepy
+Provides-Extra: develop
+Requires-Dist: black; extra == "develop"
+Requires-Dist: docformatter; extra == "develop"
+Requires-Dist: isort; extra == "develop"
+Requires-Dist: mypy; extra == "develop"
+Requires-Dist: pylint>=2.14.5; extra == "develop"
+Requires-Dist: pytest-pylint>=0.18.0; extra == "develop"
+Requires-Dist: pytest>=7.2.2; extra == "develop"
+Dynamic: license-file
+
+# PRPL Utils
+
+Miscellaneous Python utilities from the Princeton Robot Planning and Learning group.
+- **Motion planning**: RRT, BiRRT
+- **PDDL planning**: interfaces to pyperplan, Fast Downward
+- **Heuristic search**: A*, GBFS, hill-climbing, policy-guided A*
+- **Gymnasium**: agent interface, helper spaces
+- **Other**: a few other miscellaneous utils
+
+## Requirements
+
+- Python 3.10+
+- Tested on MacOS Monterey and Ubuntu 22.04
+
+## Installation
+
+1. Recommended: create and source a virtualenv.
+2. `pip install -e ".[develop]"`
+
+## Check Installation
+
+Run `./run_ci_checks.sh`. It should complete with all green successes in 5-10 seconds.
+
+## Contributing
+
+Pull requests welcome. Note that this is meant to be a **lightweight** package. For example, it should be safe to use in homework assignments with minimal assumptions about the user's setup. Do not add heavy-duty dependencies.

prpl_utils-0.0.1/README.md

@@ -0,0 +1,26 @@
+# PRPL Utils
+
+Miscellaneous Python utilities from the Princeton Robot Planning and Learning group.
+- **Motion planning**: RRT, BiRRT
+- **PDDL planning**: interfaces to pyperplan, Fast Downward
+- **Heuristic search**: A*, GBFS, hill-climbing, policy-guided A*
+- **Gymnasium**: agent interface, helper spaces
+- **Other**: a few other miscellaneous utils
+
+## Requirements
+
+- Python 3.10+
+- Tested on MacOS Monterey and Ubuntu 22.04
+
+## Installation
+
+1. Recommended: create and source a virtualenv.
+2. `pip install -e ".[develop]"`
+
+## Check Installation
+
+Run `./run_ci_checks.sh`. It should complete with all green successes in 5-10 seconds.
+
+## Contributing
+
+Pull requests welcome. Note that this is meant to be a **lightweight** package. For example, it should be safe to use in homework assignments with minimal assumptions about the user's setup. Do not add heavy-duty dependencies.

prpl_utils-0.0.1/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "prpl_utils"
+version = "0.0.1"
+description = "Common Python utilities for the Princeton Robot Planning and Learning lab."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+   "matplotlib",
+   "numpy",
+   "graphviz",
+   "pyperplan",
+   "gymnasium",
+   "moviepy",
+]
+
+[project.optional-dependencies]
+develop = [
+    "black",
+    "docformatter",
+    "isort",
+    "mypy",
+    "pylint>=2.14.5",
+    "pytest-pylint>=0.18.0",
+    "pytest>=7.2.2",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+prpl_utils = ["py.typed"]
+
+[tool.black]
+line-length = 88
+target-version = ["py310"]
+
+[tool.isort]
+py_version = 310
+profile = "black"
+multi_line_output = 2
+skip_glob = ["venv/*", ".venv/*", "build", "dist", "third_party", "third-party", "__pycache__/"]
+split_on_trailing_comma = true
+
+[tool.docformatter]
+line-length = 88
+wrap-summaries = 88
+wrap-descriptions = 88
+
+[tool.mypy]
+strict_equality = true
+disallow_untyped_calls = true
+warn_unreachable = true
+exclude = ["venv/*", ".venv/*", "build", "dist", "third_party", "third-party", "__pycache__/"]
+
+[[tool.mypy.overrides]]
+module = [
+    "matplotlib.*",
+    "pyperplan.*",
+    "graphviz.*",
+]
+ignore_missing_imports = true

prpl_utils-0.0.1/setup.cfg

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

prpl_utils-0.0.1/src/prpl_utils/gym_agent.py

@@ -0,0 +1,77 @@
+"""A basic agent interface compatible with gym envs."""
+
+import abc
+from typing import Any, Generic, TypeVar
+
+import numpy as np
+
+_ObsType = TypeVar("_ObsType")
+_ActType = TypeVar("_ActType")
+
+
+class Agent(Generic[_ObsType, _ActType]):
+    """Base class for a sequential decision-making agent."""
+
+    def __init__(self, seed: int) -> None:
+        self._rng = np.random.default_rng(seed)
+        self._last_observation: _ObsType | None = None
+        self._last_action: _ActType | None = None
+        self._last_info: dict[str, Any] | None = None
+        self._timestep: int = 0
+        self._train_or_eval = "eval"
+
+    @abc.abstractmethod
+    def _get_action(self) -> _ActType:
+        """Produce an action to execute now."""
+
+    def _learn_from_transition(
+        self,
+        obs: _ObsType,
+        act: _ActType,
+        next_obs: _ObsType,
+        reward: float,
+        done: bool,
+        info: dict[str, Any],
+    ) -> None:
+        """Update any internal models based on the observed transition."""
+
+    def reset(
+        self,
+        obs: _ObsType,
+        info: dict[str, Any],
+    ) -> None:
+        """Start a new episode."""
+        self._last_observation = obs
+        self._last_info = info
+        self._timestep = 0
+
+    def step(self) -> _ActType:
+        """Get the next action to take."""
+        self._last_action = self._get_action()
+        self._timestep += 1
+        return self._last_action
+
+    def update(
+        self, obs: _ObsType, reward: float, done: bool, info: dict[str, Any]
+    ) -> None:
+        """Record the reward and next observation following an action."""
+        assert self._last_observation is not None
+        assert self._last_action is not None
+        if self._train_or_eval == "train":
+            self._learn_from_transition(
+                self._last_observation, self._last_action, obs, reward, done, info
+            )
+        self._last_observation = obs
+        self._last_info = info
+
+    def seed(self, seed: int) -> None:
+        """Reset the random number generator."""
+        self._rng = np.random.default_rng(seed)
+
+    def train(self) -> None:
+        """Switch to train mode."""
+        self._train_or_eval = "train"
+
+    def eval(self) -> None:
+        """Switch to eval mode."""
+        self._train_or_eval = "eval"

prpl_utils-0.0.1/src/prpl_utils/gym_utils.py

@@ -0,0 +1,105 @@
+"""Utilities for Gym/Gymnasium environment compatibility and wrappers."""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+import numpy as np
+from gymnasium import spaces
+
+
+class GymToGymnasium:
+    """Wrap a legacy Gym environment to present the Gymnasium API.
+
+    - Maps `reset()` → `(obs, info)`; seeds via `env.seed(seed)` if available.
+    - Maps `step()` → `(obs, reward, terminated, truncated, info)`; derives
+      `truncated` from `info.get('TimeLimit.truncated', False)`.
+    - Forwards `observation_space`, `action_space`, `spec`, `render()`, `close()`.
+    """
+
+    def __init__(self, base_env: Any) -> None:
+        """Wrap a legacy gym environment."""
+        self._env = base_env
+        self.observation_space: spaces.Space | None = getattr(
+            base_env, "observation_space", None
+        )
+        self.action_space: spaces.Space | None = getattr(base_env, "action_space", None)
+        self.spec = getattr(base_env, "spec", None)
+
+    @property
+    def unwrapped(self) -> Any:
+        """Get the underlying unwrapped environment."""
+        return getattr(self._env, "unwrapped", self._env)
+
+    def reset(self, *, seed: int | None = None) -> tuple[Any, dict[str, Any]]:
+        """Reset environment and return (obs, info)."""
+        if seed is not None:
+            if hasattr(self._env, "seed") and callable(self._env.seed):
+                try:
+                    self._env.seed(seed)
+                except (AttributeError, TypeError):
+                    # Legacy env has broken seed implementation, continue without seeding
+                    _ = None
+        res = self._env.reset()
+        if isinstance(res, tuple) and len(res) == 2:
+            return res  # already (obs, info)
+        return res, {}
+
+    def step(self, action: Any) -> tuple[Any, float, bool, bool, dict[str, Any]]:
+        """Step environment and return (obs, reward, terminated, truncated, info)."""
+        result = self._env.step(action)
+        if isinstance(result, tuple):
+            if len(result) == 4:
+                obs, reward, done, info = result
+                terminated = bool(done)
+                truncated = bool(info.get("TimeLimit.truncated", False))
+                return obs, float(reward), terminated, truncated, info
+            if len(result) == 5:
+                obs, reward, terminated, truncated, info = result
+                return obs, float(reward), bool(terminated), bool(truncated), info
+        raise ValueError("Unexpected number of values returned from env.step")
+
+    def render(self) -> Any:
+        """Render the environment."""
+        if hasattr(self._env, "render"):
+            try:
+                return self._env.render()
+            except TypeError:
+                return self._env.render(mode="human")
+        return None
+
+    def close(self) -> None:
+        """Close the environment."""
+        getattr(self._env, "close", lambda: None)()
+
+
+def patch_box_float32() -> Callable[..., None]:
+    """Resolves Gymnasium Box precision warnings by patching space creation to use
+    float32 dtypes from the start, eliminating the need for runtime casting that
+    triggers "precision lowered" warnings from environment libraries like KinDER (KinDER
+    creates box spaces with float64 bounds).
+
+    Returns:
+        The original Box.__init__ method for restoration.
+    """
+
+    original_box_init = spaces.Box.__init__
+
+    def patched_box_init(self, low, high, shape=None, dtype=np.float32, seed=None):
+        # Convert bounds to float32 if they're float64 to avoid warnings
+        if hasattr(low, "dtype") and low.dtype == np.float64:
+            low = low.astype(np.float32)
+        if hasattr(high, "dtype") and high.dtype == np.float64:
+            high = high.astype(np.float32)
+
+        # Force dtype to float32 for floating point types
+        if dtype == np.float64:
+            dtype = np.float32
+
+        return original_box_init(self, low, high, shape, dtype, seed)
+
+    spaces.Box.__init__ = patched_box_init  # type: ignore
+    return original_box_init
+
+
+__all__ = ["GymToGymnasium", "patch_box_float32"]

prpl_utils-0.0.1/src/prpl_utils/motion_planning.py

@@ -0,0 +1,222 @@
+"""Motion planning utilities."""
+
+from __future__ import annotations
+
+import functools
+from typing import Callable, Generic, Iterable, Optional, TypeVar
+
+import numpy as np
+
+_RRTState = TypeVar("_RRTState")
+
+
+class RRT(Generic[_RRTState]):
+    """Rapidly-exploring random tree."""
+
+    def __init__(
+        self,
+        sample_fn: Callable[[_RRTState], _RRTState],
+        extend_fn: Callable[[_RRTState, _RRTState], Iterable[_RRTState]],
+        collision_fn: Callable[[_RRTState], bool],
+        distance_fn: Callable[[_RRTState, _RRTState], float],
+        rng: np.random.Generator,
+        num_attempts: int,
+        num_iters: int,
+        smooth_amt: int,
+    ):
+        self._sample_fn = sample_fn
+        self._extend_fn = extend_fn
+        self._collision_fn = collision_fn
+        self._distance_fn = distance_fn
+        self._rng = rng
+        self._num_attempts = num_attempts
+        self._num_iters = num_iters
+        self._smooth_amt = smooth_amt
+
+    def query(
+        self, pt1: _RRTState, pt2: _RRTState, sample_goal_eps: float = 0.0
+    ) -> Optional[list[_RRTState]]:
+        """Query the RRT, to get a collision-free path from pt1 to pt2.
+
+        If none is found, returns None.
+        """
+        if self._collision_fn(pt1) or self._collision_fn(pt2):
+            return None
+        direct_path = self.try_direct_path(pt1, pt2)
+        if direct_path is not None:
+            return direct_path
+        for _ in range(self._num_attempts):
+            path = self._rrt_connect(
+                pt1, goal_sampler=lambda: pt2, sample_goal_eps=sample_goal_eps
+            )
+            if path is not None:
+                return self._smooth_path(path)
+        return None
+
+    def query_to_goal_fn(
+        self,
+        start: _RRTState,
+        goal_fn: Callable[[_RRTState], bool],
+        goal_sampler: Callable[[], _RRTState] | None = None,
+        sample_goal_eps: float = 0.0,
+    ) -> Optional[list[_RRTState]]:
+        """Query the RRT, to get a collision-free path from start to a point such that
+        goal_fn(point) is True. Uses goal_sampler to sample a target for a direct path
+        or with probability sample_goal_eps.
+
+        If none is found, returns None.
+        """
+        assert sample_goal_eps == 0.0 or goal_sampler is not None
+        if self._collision_fn(start):
+            return None
+        if goal_sampler:
+            direct_path = self.try_direct_path(start, goal_sampler())
+            if direct_path is not None:
+                return direct_path
+        for _ in range(self._num_attempts):
+            path = self._rrt_connect(
+                start, goal_sampler, goal_fn, sample_goal_eps=sample_goal_eps
+            )
+            if path is not None:
+                return self._smooth_path(path)
+        return None
+
+    def try_direct_path(
+        self, pt1: _RRTState, pt2: _RRTState
+    ) -> Optional[list[_RRTState]]:
+        """Attempt to plan a direct path from pt1 to pt2, returning None if collision-
+        free path can be found."""
+        path = [pt1]
+        for newpt in self._extend_fn(pt1, pt2):
+            if self._collision_fn(newpt):
+                return None
+            path.append(newpt)
+        return path
+
+    def _rrt_connect(
+        self,
+        pt1: _RRTState,
+        goal_sampler: Callable[[], _RRTState] | None = None,
+        goal_fn: Callable[[_RRTState], bool] | None = None,
+        sample_goal_eps: float = 0.0,
+    ) -> Optional[list[_RRTState]]:
+        root = _RRTNode(pt1)
+        nodes = [root]
+
+        for _ in range(self._num_iters):
+            # Sample the goal with a small probability, otherwise randomly
+            # choose a point.
+            sample_goal = self._rng.random() < sample_goal_eps
+            if sample_goal:
+                assert goal_sampler is not None
+                samp = goal_sampler()
+            else:
+                samp = self._sample_fn(pt1)
+            min_key = functools.partial(self._get_pt_dist_to_node, samp)
+            nearest = min(nodes, key=min_key)
+            reached_goal = False
+            for newpt in self._extend_fn(nearest.data, samp):
+                if self._collision_fn(newpt):
+                    break
+                nearest = _RRTNode(newpt, parent=nearest)
+                nodes.append(nearest)
+            else:
+                reached_goal = sample_goal
+            # Check goal_fn if defined
+            if reached_goal or goal_fn is not None and goal_fn(nearest.data):
+                path = nearest.path_from_root()
+                return [node.data for node in path]
+        return None
+
+    def _get_pt_dist_to_node(self, pt: _RRTState, node: _RRTNode[_RRTState]) -> float:
+        return self._distance_fn(pt, node.data)
+
+    def _smooth_path(self, path: list[_RRTState]) -> list[_RRTState]:
+        assert len(path) > 2
+        for _ in range(self._smooth_amt):
+            i = self._rng.integers(0, len(path) - 1)
+            j = self._rng.integers(0, len(path) - 1)
+            if abs(i - j) <= 1:
+                continue
+            if j < i:
+                i, j = j, i
+            shortcut = list(self._extend_fn(path[i], path[j]))
+            if len(shortcut) < j - i and all(
+                not self._collision_fn(pt) for pt in shortcut
+            ):
+                path = path[: i + 1] + shortcut + path[j + 1 :]
+        return path
+
+
+class BiRRT(RRT[_RRTState]):
+    """Bidirectional rapidly-exploring random tree."""
+
+    def query_to_goal_fn(
+        self,
+        start: _RRTState,
+        goal_fn: Callable[[_RRTState], bool],
+        goal_sampler: Callable[[], _RRTState] | None = None,
+        sample_goal_eps: float = 0.0,
+    ) -> Optional[list[_RRTState]]:
+        raise NotImplementedError("Can't query to goal function using BiRRT")
+
+    def _rrt_connect(
+        self,
+        pt1: _RRTState,
+        goal_sampler: Callable[[], _RRTState] | None = None,
+        goal_fn: Callable[[_RRTState], bool] | None = None,
+        sample_goal_eps: float = 0.0,
+    ) -> Optional[list[_RRTState]]:
+        # goal_fn and sample_goal_eps are unused
+        assert goal_sampler is not None
+        pt2 = goal_sampler()
+        root1, root2 = _RRTNode(pt1), _RRTNode(pt2)
+        nodes1, nodes2 = [root1], [root2]
+
+        for _ in range(self._num_iters):
+            if len(nodes1) > len(nodes2):
+                nodes1, nodes2 = nodes2, nodes1
+            samp = self._sample_fn(pt1)
+            min_key1 = functools.partial(self._get_pt_dist_to_node, samp)
+            nearest1 = min(nodes1, key=min_key1)
+            for newpt in self._extend_fn(nearest1.data, samp):
+                if self._collision_fn(newpt):
+                    break
+                nearest1 = _RRTNode(newpt, parent=nearest1)
+                nodes1.append(nearest1)
+            min_key2 = functools.partial(self._get_pt_dist_to_node, nearest1.data)
+            nearest2 = min(nodes2, key=min_key2)
+            for newpt in self._extend_fn(nearest2.data, nearest1.data):
+                if self._collision_fn(newpt):
+                    break
+                nearest2 = _RRTNode(newpt, parent=nearest2)
+                nodes2.append(nearest2)
+            else:
+                path1 = nearest1.path_from_root()
+                path2 = nearest2.path_from_root()
+                # This is a tricky case to cover.
+                if path1[0] != root1:  # pragma: no cover
+                    path1, path2 = path2, path1
+                assert path1[0] == root1
+                path = path1[:-1] + path2[::-1]
+                return [node.data for node in path]
+        return None
+
+
+class _RRTNode(Generic[_RRTState]):
+    """A node for RRT."""
+
+    def __init__(
+        self, data: _RRTState, parent: Optional[_RRTNode[_RRTState]] = None
+    ) -> None:
+        self.data = data
+        self.parent = parent
+
+    def path_from_root(self) -> list[_RRTNode[_RRTState]]:
+        """Return the path from the root to this node."""
+        sequence = []
+        node: Optional[_RRTNode[_RRTState]] = self
+        while node is not None:
+            sequence.append(node)
+            node = node.parent
+        return sequence[::-1]