deep-learning-robotics 0.0.1__py3-none-any.whl

deep_learning_robotics-0.0.1.dist-info/METADATA

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: deep-learning-robotics
+Version: 0.0.1
+Summary: Fast 2D robotics and MAPF environments for deep-learning-core.
+Project-URL: Homepage, https://github.com/Blazkowiz47/dl-robotics
+Project-URL: Repository, https://github.com/Blazkowiz47/dl-robotics
+Project-URL: Issues, https://github.com/Blazkowiz47/dl-robotics/issues
+Author-email: blazkowiz47 <sushrutpatwardhan@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 blazkowiz47
+        
+        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.
+        
+License-File: LICENSE
+Keywords: deep-reinforcement-learning,mapf,path-finding,robotics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: deep-learning-core<0.1,>=0.0.27
+Requires-Dist: gymnasium<2,>=1.3
+Requires-Dist: imageio-ffmpeg>=0.5
+Requires-Dist: imageio>=2.34
+Requires-Dist: numpy
+Requires-Dist: opencv-python-headless
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.12; extra == 'dev'
+Requires-Dist: twine>=6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# deep-learning-robotics
+
+Fast, reproducible 2D robotics environments for
+[`deep-learning-core`](https://github.com/Blazkowiz47/dl-core).
+
+## Install
+
+```bash
+pip install deep-learning-robotics
+```
+
+Version `0.0.1` requires `deep-learning-core>=0.0.27,<0.1`.
+
+## What's New in 0.0.1?
+
+- validated grid scenarios with walls, actor starts, and per-actor goals
+- preallocated batched world state for position, velocity, acceleration,
+  reached goals, path length, makespan, and sum of costs
+- simultaneous exclusive-cell physics covering boundaries, walls, vertex
+  conflicts, edge swaps, and moves into stationary actors
+- scalar and native vector Gymnasium environments registered as
+  `robotics_mapf` and `robotics_mapf_vector`
+- centralized joint actions compatible with dl-core DQN and PPO
+- semantic channel observations containing walls, actors, goals, velocity, and
+  acceleration
+- headless RGB rendering plus direct GIF and MP4 episode output
+- exact A*, Dijkstra, and BFS utilities for static single-agent shortest paths,
+  plus deterministic DFS for reachability and debugging
+- a `robotics` episode manager for collision, completion, makespan,
+  sum-of-costs, path-length, trajectory, and media artifacts
+
+## Environment Configuration
+
+Import `dl_robotics` once to register its environments, then use normal
+dl-core configuration:
+
+```yaml
+environment:
+  name: robotics_mapf_vector
+  num_envs: 16
+  scenario:
+    name: crossing
+    width: 7
+    height: 7
+    max_steps: 40
+    walls: [[3, 1], [3, 5]]
+    starts: [[1, 1], [5, 5]]
+    goals: [[5, 5], [1, 1]]
+  rewards:
+    step: -0.01
+    progress: 0.1
+    collision: -0.25
+    goal: 1.0
+    success: 5.0
+  render:
+    cell_size: 48
+    show_grid: true
+
+episode_managers:
+  robotics:
+    capture_phases: [evaluation]
+    capture_every_n_episodes: 1
+    max_captured_episodes: 20
+    media_format: both
+    fps: 8
+```
+
+Each actor chooses one of `stay`, `up`, `right`, `down`, or `left`. The
+centralized environment encodes all actor choices into one
+`Discrete(5 ** num_agents)` joint action, with actor zero stored in the least
+significant base-5 digit. This is intentionally aimed at small cooperative
+MAPF problems; larger or decentralized systems should use a future multi-agent
+policy API instead of an exponentially growing joint action.
+
+The image observation is suitable for DQN and PPO. dl-core's tabular
+Q-learning trainer requires a `Discrete` observation space, so it is not
+compatible with this first image-observation environment.
+
+The observation is a float32 tensor with shape `[7, height, width]`: walls,
+actor identity, goal identity, row/column velocity, and row/column acceleration.
+Episode info exposes `is_success`, collision counts, reached agents, makespan,
+sum of costs, and total path length for episode managers and experiment
+tracking. `collisions` and its typed variants describe the latest step;
+`episode_collisions` and its typed variants retain the episode totals.
+
+## Rendering and Episode Artifacts
+
+`environment.render()` returns RGB `uint8` arrays without opening a display:
+`[height, width, 3]` for the scalar environment and
+`[num_envs, height, width, 3]` for the vector environment.
+
+The `robotics` episode manager includes dl-core's standard episode metrics and
+trajectory capture, so it should be used in place of the `standard` manager.
+For selected phases and episode intervals it stores the complete compressed
+trajectory and optionally a GIF, MP4, or both. It also emits
+`robotics/collisions`, typed collision counts, reached fraction, makespan,
+sum of costs, and path length through normal callback and tracker flows.
+
+Media files can also be created directly:
+
+```python
+from dl_robotics import write_animation
+
+write_animation("episode.gif", frames, fps=8)
+write_animation("episode.mp4", frames, fps=8)
+```
+
+## Interaction Rules
+
+`GridWorldBatch` owns numerical state, while `InteractionRule` owns how proposed
+movements interact. `ExclusiveCellRule` provides MAPF-safe defaults. A custom
+rule instance can be supplied as `environment.interaction_rule` when an
+environment is created programmatically, without changing scenario definitions
+or RL adapters. Serializable rule registries are planned for a later release.
+
+The first version uses vectorized geometry and preallocated state arrays, with
+small per-world conflict-resolution loops where agent dependencies require
+them. It does not model continuous rigid-body dynamics, ROS, Gazebo, or 3D
+simulation.
+
+## Shortest-Path Baselines
+
+Use A* for efficient exact planning on the unit-cost grid, or Dijkstra when a
+heuristic-free reference is useful:
+
+```python
+from dl_robotics import (
+    GridScenario,
+    astar_path,
+    bfs_path,
+    dfs_path,
+    dijkstra_path,
+)
+
+scenario = GridScenario(
+    width=5,
+    height=5,
+    starts=((0, 0), (4, 4)),
+    goals=((4, 4), (0, 0)),
+    walls=((1, 2), (3, 2)),
+)
+
+astar = astar_path(scenario, scenario.starts[0], scenario.goals[0])
+dijkstra = dijkstra_path(scenario, scenario.starts[1], scenario.goals[1])
+bfs = bfs_path(scenario, scenario.starts[0], scenario.goals[0])
+dfs = dfs_path(scenario, scenario.starts[1], scenario.goals[1])
+```
+
+Paths include both endpoints and use four-direction movement around static
+walls. Their move count is therefore `len(path) - 1`. A*, Dijkstra, and BFS
+return shortest paths on this unweighted grid. DFS returns the first
+depth-first route and does not guarantee optimality. Traversal ties use the
+fixed up, right, down, left order. The exact planners provide per-agent lower
+bounds and deterministic evaluation baselines; independently planned paths can
+still have vertex or edge conflicts and are not, by themselves, a multi-agent
+path-finding solver.

deep_learning_robotics-0.0.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+dl_robotics/__init__.py,sha256=sd0gA7c3Wdu6KJm67SjJXKRWv1hbuUloRhI7XCF0HTk,921
+dl_robotics/environment.py,sha256=8A9Y851yHQUf0KAkW5haVpvHv4BQiDP1KQ-mu-dffYs,15931
+dl_robotics/episode_manager.py,sha256=UmcTr7fXerwVWZn6MhajA2peJ0KhgX7y7NEx36SbVxI,5410
+dl_robotics/planning.py,sha256=qMIIe2BXCwdpkT4L194OIoS0lAcSIFVUyWE4PLjtBV0,7205
+dl_robotics/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+dl_robotics/rendering.py,sha256=po55qfUE6XLIejIe-ty3okfgb5fdJGPAupMw--kHL44,8366
+dl_robotics/scenario.py,sha256=iaImWxMu4-KoCf9PWuIkj0kvUelm5kqERpALWNCK9-M,5694
+dl_robotics/world.py,sha256=mSXHwW0sA28hJeZSObj8jQDDejeL0YmaO41qOOlRXX4,12736
+deep_learning_robotics-0.0.1.dist-info/METADATA,sha256=d4RVjyh4O7DPhpFybrCs1jXgfcXph_EiS87WkL775Z8,8289
+deep_learning_robotics-0.0.1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+deep_learning_robotics-0.0.1.dist-info/licenses/LICENSE,sha256=f-Pa3PzxMhIId4zEb_aOWHbL2bBV__jf67OWdRDh0t0,1069
+deep_learning_robotics-0.0.1.dist-info/RECORD,,

deep_learning_robotics-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

deep_learning_robotics-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 blazkowiz47
+
+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.
+

dl_robotics/__init__.py

@@ -0,0 +1,38 @@
+"""Fast 2D robotics environments for deep-learning-core."""
+
+from .environment import GridMAPFEnvironment, GridMAPFVectorEnvironment
+from .episode_manager import RoboticsEpisodeManager
+from .planning import (
+    GridPath,
+    PathNotFoundError,
+    astar_path,
+    bfs_path,
+    dfs_path,
+    dijkstra_path,
+)
+from .rendering import GridRenderer, write_animation
+from .scenario import Coordinate, GridScenario
+from .world import ExclusiveCellRule, GridWorldBatch, InteractionRule, StepEvents
+
+__version__ = "0.0.1"
+
+__all__ = [
+    "Coordinate",
+    "ExclusiveCellRule",
+    "GridMAPFEnvironment",
+    "GridMAPFVectorEnvironment",
+    "GridPath",
+    "GridRenderer",
+    "GridScenario",
+    "GridWorldBatch",
+    "InteractionRule",
+    "PathNotFoundError",
+    "RoboticsEpisodeManager",
+    "StepEvents",
+    "__version__",
+    "astar_path",
+    "bfs_path",
+    "dfs_path",
+    "dijkstra_path",
+    "write_animation",
+]