deepracer 0.1.0__tar.gz

deepracer-0.1.0/LICENSE

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

deepracer-0.1.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: deepracer
+Version: 0.1.0
+Summary: A Gymnasium wrapper for the AWS DeepRacer simulator
+Author-email: Uzair Akbar <uzairakbar025@gmail.com>
+Project-URL: Homepage, https://uzairakbar.github.com/deepracer/
+Project-URL: Repository, https://github.com/uzairakbar/deepracer
+Project-URL: Documentation, https://uzairakbar.github.com/deepracer/
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Requires-Dist: gymnasium
+Requires-Dist: pyzmq
+Requires-Dist: msgpack
+Requires-Dist: msgpack_numpy
+Requires-Dist: loguru
+Requires-Dist: docker
+Requires-Dist: pyyaml
+Provides-Extra: dev
+Requires-Dist: ruff>=0.15; extra == "dev"
+Requires-Dist: mypy>=1.14; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pre-commit>=4; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Requires-Dist: bump-my-version; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Requires-Dist: pymdown-extensions>=10; extra == "docs"
+Dynamic: license-file
+
+# DeepRacer Gym
+
+[![PyPI](https://img.shields.io/pypi/v/deepracer?logo=pypi&logoColor=white)](https://pypi.org/project/deepracer/)
+[![Downloads](https://img.shields.io/pepy/dt/deepracer?logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI%2BPHBhdGggZmlsbD0id2hpdGUiIGQ9Ik01LDIwSDE5VjE4SDVNMTksOUgxNVYzSDlWOUg1TDEyLDE2TDE5LDlaIi8%2BPC9zdmc%2B&label=downloads)](https://pepy.tech/project/deepracer)
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue?logo=python&logoColor=white)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/github/license/uzairakbar/deepracer?logo=opensourceinitiative&logoColor=white)](LICENSE)
+[![Tests](https://img.shields.io/github/actions/workflow/status/uzairakbar/deepracer/test.yml?branch=develop&logo=githubactions&logoColor=white&label=tests)](https://github.com/uzairakbar/deepracer/actions/workflows/test.yml)
+[![Coverage](https://img.shields.io/codecov/c/github/uzairakbar/deepracer?branch=develop&logo=pytest&logoColor=white)](https://codecov.io/gh/uzairakbar/deepracer)
+[![Docker Pulls](https://img.shields.io/docker/pulls/uzairakbar/deepracer-test?logo=docker&logoColor=white&label=pulls)](https://hub.docker.com/r/uzairakbar/deepracer-test)
+[![DOI](https://zenodo.org/badge/1297933489.svg)](https://zenodo.org/badge/latestdoi/1297933489)
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/uzairakbar/deepracer/main/docs/deepracer.gif" alt="DeepRacer" width="200">
+</p>
+
+A [Gymnasium](https://gymnasium.farama.org/) wrapper for the
+[AWS DeepRacer](https://github.com/aws-deepracer-community/deepracer-for-cloud)
+simulator. Each `deepracer-v0` environment automatically launches its own
+containerized simulator (Docker/Podman/Apptainer), then exposes it through the standard `gymnasium` API.
+
+## Install
+
+Requirements:
+- Python 3.12+
+- Linux (tested on Ubuntu 20.04+), macOS, or Windows (via WSL2)
+- A container runtime: Docker, Podman, or Apptainer (e.g. for rootless runs on HPC)
+- Sufficient hardware resources (recommended ~3 CPUs, ~6 GB RAM per environment)
+
+```bash
+pip install deepracer
+```
+
+## Quick Start
+
+```python
+import gymnasium as gym
+import deepracer
+
+env = gym.make("deepracer-v0")      # starts a simulator service on demand
+
+observation, info = env.reset()
+
+observation, reward, terminated, truncated, info = env.step(
+    env.action_space.sample()
+)
+
+env.close()                         # stops + removes the simulator service
+```
+
+See the [full documentation](https://uzairakbar.com/deepracer/) for details.

deepracer-0.1.0/README.md

@@ -0,0 +1,50 @@
+# DeepRacer Gym
+
+[![PyPI](https://img.shields.io/pypi/v/deepracer?logo=pypi&logoColor=white)](https://pypi.org/project/deepracer/)
+[![Downloads](https://img.shields.io/pepy/dt/deepracer?logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI%2BPHBhdGggZmlsbD0id2hpdGUiIGQ9Ik01LDIwSDE5VjE4SDVNMTksOUgxNVYzSDlWOUg1TDEyLDE2TDE5LDlaIi8%2BPC9zdmc%2B&label=downloads)](https://pepy.tech/project/deepracer)
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue?logo=python&logoColor=white)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/github/license/uzairakbar/deepracer?logo=opensourceinitiative&logoColor=white)](LICENSE)
+[![Tests](https://img.shields.io/github/actions/workflow/status/uzairakbar/deepracer/test.yml?branch=develop&logo=githubactions&logoColor=white&label=tests)](https://github.com/uzairakbar/deepracer/actions/workflows/test.yml)
+[![Coverage](https://img.shields.io/codecov/c/github/uzairakbar/deepracer?branch=develop&logo=pytest&logoColor=white)](https://codecov.io/gh/uzairakbar/deepracer)
+[![Docker Pulls](https://img.shields.io/docker/pulls/uzairakbar/deepracer-test?logo=docker&logoColor=white&label=pulls)](https://hub.docker.com/r/uzairakbar/deepracer-test)
+[![DOI](https://zenodo.org/badge/1297933489.svg)](https://zenodo.org/badge/latestdoi/1297933489)
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/uzairakbar/deepracer/main/docs/deepracer.gif" alt="DeepRacer" width="200">
+</p>
+
+A [Gymnasium](https://gymnasium.farama.org/) wrapper for the
+[AWS DeepRacer](https://github.com/aws-deepracer-community/deepracer-for-cloud)
+simulator. Each `deepracer-v0` environment automatically launches its own
+containerized simulator (Docker/Podman/Apptainer), then exposes it through the standard `gymnasium` API.
+
+## Install
+
+Requirements:
+- Python 3.12+
+- Linux (tested on Ubuntu 20.04+), macOS, or Windows (via WSL2)
+- A container runtime: Docker, Podman, or Apptainer (e.g. for rootless runs on HPC)
+- Sufficient hardware resources (recommended ~3 CPUs, ~6 GB RAM per environment)
+
+```bash
+pip install deepracer
+```
+
+## Quick Start
+
+```python
+import gymnasium as gym
+import deepracer
+
+env = gym.make("deepracer-v0")      # starts a simulator service on demand
+
+observation, info = env.reset()
+
+observation, reward, terminated, truncated, info = env.step(
+    env.action_space.sample()
+)
+
+env.close()                         # stops + removes the simulator service
+```
+
+See the [full documentation](https://uzairakbar.com/deepracer/) for details.

deepracer-0.1.0/client/deepracer/__init__.py

@@ -0,0 +1,60 @@
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _version
+
+from gymnasium.envs.registration import register
+
+try:
+    __version__ = _version("deepracer")
+except PackageNotFoundError:  # running from a source tree without an install
+    __version__ = "0.0.0"
+
+register(id="deepracer-v0", entry_point="deepracer.envs:DeepracerGymEnv")
+
+
+def close(env, cache: bool | None = None):
+    """Close a (possibly gym.make-wrapped) DeepRacer env, overriding its cache flag.
+
+    The container's fate is normally the env's `cache` flag (set at gym.make), and a
+    plain `env.close()` already honors it through the wrapper. Use this helper (or
+    `env.unwrapped.close(cache=…)`) only to *override* that decision at close time —
+    e.g. `deepracer.close(env, cache=False)` to force-stop a cache=True env.
+    """
+    env.unwrapped.close(cache=cache)
+
+
+def shutdown_all():
+    """Stop every DeepRacer container this process is managing, including any
+    kept warm. Call when you are completely done (or to reclaim warm
+    containers)."""
+    from deepracer.service.manager import SimulationManager
+
+    if SimulationManager._instance is not None:
+        SimulationManager._instance.shutdown_all()
+
+
+def running() -> list[str]:
+    """Names of DeepRacer simulators currently running on this host (across any
+    kernels/processes). Handy to see what is up before/after your work."""
+    import shutil
+    import subprocess
+
+    from deepracer.service.spec import LABEL_NS
+
+    names: list[str] = []
+    for engine in ("podman", "docker"):
+        if shutil.which(engine) is None:
+            continue
+        result = subprocess.run(
+            [
+                engine,
+                "ps",
+                "--filter",
+                f"label={LABEL_NS}.managed=true",
+                "--format",
+                "{{.Names}}",
+            ],
+            capture_output=True,
+            text=True,
+        )
+        names += [n for n in result.stdout.split() if n]
+    return names

deepracer-0.1.0/client/deepracer/clean.py

@@ -0,0 +1,75 @@
+"""Maintenance CLI for removing orphaned DeepRacer sims.
+
+    python -m deepracer.clean
+
+Removes managed Docker/Podman containers, DeepRacer Apptainer instances,
+per-instance overlays, and stale Apptainer logs. Best-effort and idempotent.
+"""
+
+import glob
+import json
+import os
+import shutil
+import subprocess
+
+from deepracer.service.spec import LABEL_NS
+
+
+def _run(argv):
+    return subprocess.run(argv, capture_output=True, text=True)
+
+
+def _clean_oci(binary: str) -> None:
+    if shutil.which(binary) is None:
+        return
+    result = _run([binary, "ps", "-aq", "--filter", f"label={LABEL_NS}.managed=true"])
+    ids = [i for i in result.stdout.split() if i]
+    for cid in ids:
+        _run([binary, "rm", "-f", cid])  # -f stops then removes
+    print(f"{binary}: removed {len(ids)} managed container(s).")
+
+
+def _clean_apptainer() -> None:
+    if shutil.which("apptainer") is None:
+        return
+    result = _run(["apptainer", "instance", "list", "--json"])
+    try:
+        instances = json.loads(result.stdout).get("instances", [])
+    except Exception:
+        instances = []
+    names = [
+        i["instance"]
+        for i in instances
+        if str(i.get("instance", "")).startswith("deepracer-")
+    ]
+    for name in names:
+        _run(["apptainer", "instance", "stop", name])
+    for overlay in glob.glob("/tmp/deepracer_*"):
+        shutil.rmtree(overlay, ignore_errors=True)
+    # Apptainer never rotates its per-instance logs; they accumulate forever and
+    # a stale FATAL: line poisons a later start of the same name (the backend
+    # clears these per-name on start, but sweep leftovers here too).
+    log_base = os.path.expanduser("~/.apptainer/instances/logs")
+    logs = glob.glob(os.path.join(log_base, "*", "*", "deepracer-*.out")) + glob.glob(
+        os.path.join(log_base, "*", "*", "deepracer-*.err")
+    )
+    for path in logs:
+        try:
+            os.remove(path)
+        except OSError:
+            pass
+    print(
+        f"apptainer: stopped {len(names)} instance(s), cleared overlays + "
+        f"{len(logs)} stale log file(s)."
+    )
+
+
+def main() -> None:
+    for binary in ("docker", "podman"):
+        _clean_oci(binary)
+    _clean_apptainer()
+    print("Done.")
+
+
+if __name__ == "__main__":
+    main()

deepracer-0.1.0/client/deepracer/defaults/__init__.py

@@ -0,0 +1,58 @@
+# Packaged default configs (agent_params.json, environment_params.yaml,
+# reward_function.py) and the frozen track list (tracks.txt), so the package
+# works from any cwd without the repo's top-level configs/ directory.
+import importlib.resources as resources
+import json
+
+
+def _read(name: str) -> str:
+    return resources.files("deepracer.defaults").joinpath(name).read_text()
+
+
+def default_agent_config() -> dict:
+    return json.loads(_read("agent_params.json"))
+
+
+def default_track_config() -> dict:
+    import yaml  # pyyaml
+
+    return yaml.safe_load(_read("environment_params.yaml"))
+
+
+def resolve_agent_config(config: dict | None = None) -> dict:
+    """shallow merge agent config with packaged defaults"""
+    if config is None:
+        return default_agent_config()
+    if isinstance(config, dict):
+        return {**default_agent_config(), **config}
+    raise TypeError(
+        f"agent_config must be a dict or None, got {type(config).__name__}."
+    )
+
+
+def resolve_track_config(config: dict | None = None) -> dict:
+    """shallow merge track config with packaged defaults"""
+    if config is None:
+        return default_track_config()
+    if isinstance(config, dict):
+        return {**default_track_config(), **config}
+    raise TypeError(
+        f"track_config must be a dict or None, got {type(config).__name__}."
+    )
+
+
+def default_reward_function():
+    """The packaged default reward function (used when the caller passes none).
+
+    Prefer a repo-local ``configs.reward_function`` if importable (back-compat
+    with the current project layout); otherwise fall back to the packaged copy.
+    Loaded lazily so importing the package never depends on cwd.
+    """
+    try:
+        from configs.reward_function import reward_function
+
+        return reward_function
+    except Exception:
+        namespace: dict = {}
+        exec(_read("reward_function.py"), namespace)
+        return namespace["reward_function"]

deepracer-0.1.0/client/deepracer/defaults/agent_params.json

@@ -0,0 +1,28 @@
+{
+    "action_space": [
+        {
+            "steering_angle": 30,
+            "speed": 0.6
+        },
+        {
+            "steering_angle": 15,
+            "speed": 0.6
+        },
+        {
+            "steering_angle": 0,
+            "speed": 0.6
+        },
+        {
+            "steering_angle": -15,
+            "speed": 0.6
+        },
+        {
+            "steering_angle": -30,
+            "speed": 0.6
+        }
+    ],
+    "sensor": ["STEREO_CAMERAS", "LIDAR"],
+    "neural_network": "DEEP_CONVOLUTIONAL_NETWORK_SHALLOW",
+    "action_space_type": "discrete",
+    "version": "6"
+}

deepracer-0.1.0/client/deepracer/defaults/environment_params.yaml

@@ -0,0 +1,22 @@
+WORLD_NAME:                           "reInvent2019_wide"
+CHANGE_START_POSITION:                "true"
+ALTERNATE_DRIVING_DIRECTION:          "true"
+NUMBER_OF_OBSTACLES:                  "0"
+IS_OBSTACLE_BOT_CAR:                  "false"
+RANDOMIZE_OBSTACLE_LOCATIONS:         "true"
+# OBJECT_POSITIONS:
+#     - 0.1690708037909166, -1
+#     - 0.2638102569075569, 1
+#     - 0.4072827740044651, -1
+#     - 0.5804718430735435, 1
+#     - 0.6937442410812812, -1
+#     - 0.7864867324330095, 1
+IS_LANE_CHANGE:                       "false"
+LOWER_LANE_CHANGE_TIME:               "3.0"
+UPPER_LANE_CHANGE_TIME:               "5.0"
+LANE_CHANGE_DISTANCE:                 "1.0"
+NUMBER_OF_BOT_CARS:                   "0"
+MIN_DISTANCE_BETWEEN_BOT_CARS:        "2.0"
+RANDOMIZE_BOT_CAR_LOCATIONS:          "true"
+BOT_CAR_SPEED:                        "0.2"
+ENABLE_DOMAIN_RANDOMIZATION:          "false"

deepracer-0.1.0/client/deepracer/defaults/reward_function.py

@@ -0,0 +1,25 @@
+def reward_function(params):
+    """
+    Example of rewarding the agent to follow center line
+    """
+
+    # Read input parameters
+    track_width = params["track_width"]
+    distance_from_center = params["distance_from_center"]
+
+    # Calculate 3 markers that are at varying distances away from the center line
+    marker_1 = 0.1 * track_width
+    marker_2 = 0.25 * track_width
+    marker_3 = 0.5 * track_width
+
+    # Give higher reward if the car is closer to center line and vice versa
+    if distance_from_center <= marker_1:
+        reward = 1.0
+    elif distance_from_center <= marker_2:
+        reward = 0.5
+    elif distance_from_center <= marker_3:
+        reward = 0.1
+    else:
+        reward = 1e-3  # likely crashed/ close to off track
+
+    return float(reward)

deepracer-0.1.0/client/deepracer/defaults/tracks.txt

@@ -0,0 +1,127 @@
+2022_april_open
+2022_april_open_ccw
+2022_april_open_cw
+2022_april_pro
+2022_april_pro_ccw
+2022_april_pro_cw
+2022_august_open
+2022_august_open_ccw
+2022_august_open_cw
+2022_august_pro
+2022_august_pro_ccw
+2022_august_pro_cw
+2022_july_open
+2022_july_pro
+2022_july_pro_ccw
+2022_july_pro_cw
+2022_june_open
+2022_june_open_ccw
+2022_june_open_cw
+2022_june_pro
+2022_june_pro_ccw
+2022_june_pro_cw
+2022_march_open
+2022_march_open_ccw
+2022_march_open_cw
+2022_march_pro
+2022_march_pro_ccw
+2022_march_pro_cw
+2022_may_open
+2022_may_open_ccw
+2022_may_open_cw
+2022_may_pro
+2022_may_pro_ccw
+2022_may_pro_cw
+2022_october_open
+2022_october_open_ccw
+2022_october_open_cw
+2022_october_pro
+2022_october_pro_ccw
+2022_october_pro_cw
+2022_reinvent_champ_ccw
+2022_reinvent_champ_cw
+2022_september_open
+2022_september_open_ccw
+2022_september_open_cw
+2022_september_pro
+2022_september_pro_ccw
+2022_september_pro_cw
+2022_summit_speedway
+2022_summit_speedway_ccw
+2022_summit_speedway_cw
+2022_summit_speedway_mini
+2024_reinvent_champ_ccw
+2024_reinvent_champ_cw
+Albert
+AmericasGeneratedInclStart
+Aragon
+arctic_open
+arctic_open_ccw
+arctic_open_cw
+arctic_pro
+arctic_pro_ccw
+arctic_pro_cw
+Austin
+AWS_track
+Belille
+Bowtie_track
+caecer_gp
+caecer_loop
+Canada_Training
+China_track
+dubai_open
+dubai_open_ccw
+dubai_open_cw
+dubai_pro
+FS_June2020
+hamption_open
+hamption_pro
+July_2020
+jyllandsringen_open
+jyllandsringen_open_ccw
+jyllandsringen_open_cw
+jyllandsringen_pro
+jyllandsringen_pro_ccw
+jyllandsringen_pro_cw
+LGSWide
+Mexico_track
+Monaco
+Monaco_building
+morgan_open
+morgan_pro
+New_York_Track
+Oval_track
+penbay_open
+penbay_open_ccw
+penbay_open_cw
+penbay_pro
+penbay_pro_ccw
+penbay_pro_cw
+red_star_open
+red_star_pro
+red_star_pro_ccw
+red_star_pro_cw
+reInvent2019_track
+reInvent2019_track_ccw
+reInvent2019_track_cw
+reInvent2019_wide
+reInvent2019_wide_ccw
+reInvent2019_wide_cw
+reInvent2019_wide_mirrored
+reinvent_base
+reinvent_carpet
+reinvent_concrete
+reinvent_wood
+Singapore
+Singapore_building
+Singapore_f1
+Spain_track
+Spain_track_f1
+Straight_track
+thunder_hill_open
+thunder_hill_pro
+thunder_hill_pro_ccw
+thunder_hill_pro_cw
+Tokyo_Training_track
+Vegas_track
+Virtual_May19_Train_track

deepracer-0.1.0/client/deepracer/envs/__init__.py

@@ -0,0 +1,3 @@
+from deepracer.envs.env import DeepracerGymEnv
+
+__all__ = ["DeepracerGymEnv"]