deepracer 0.1.0__py3-none-any.whl

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/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/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/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/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/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/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/envs/__init__.py

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

deepracer/envs/env.py

@@ -0,0 +1,228 @@
+import os
+import weakref
+from collections.abc import Callable
+
+import gymnasium as gym
+import matplotlib.pyplot as plt
+import numpy as np
+from gymnasium import spaces
+from loguru import logger
+
+from deepracer.defaults import (
+    default_reward_function,
+    resolve_agent_config,
+    resolve_track_config,
+)
+from deepracer.envs.utils import (
+    make_action_space,
+    make_observation_space,
+    num_channels,
+)
+from deepracer.gym_adapter import DeepracerGymAdapter
+from deepracer.service.spec import DEFAULT_IMAGE
+
+# validate_configs is imported lazily in __init__ to avoid an import cycle
+# (service.validate -> envs.utils -> envs.__init__ -> this module).
+
+
+type ActionType = int | np.ndarray | list[float]
+HOST: str = "127.0.0.1"
+DEFAULT_PORT: int = 8888
+
+
+def _default_port() -> int:
+    """Port for the connect-only (manage_container=False) path: GYM_PORT env, else
+    a per-user hash (back-compat with the bash scripts), else DEFAULT_PORT."""
+    if "GYM_PORT" in os.environ:
+        try:
+            return int(os.environ["GYM_PORT"])
+        except ValueError:
+            pass
+    try:
+        from deepracer.service.identity import current_user, string_to_port
+
+        return string_to_port(current_user())
+    except Exception:
+        return DEFAULT_PORT
+
+
+def _release(manager, handle, keep_warm):
+    """Module-level finalizer target (must not hold a ref to the env instance).
+    Honors the env's cache flag: a forgotten close() / GC on a cache=True env
+    keeps it warm (reaped at process exit by shutdown_all), else stops+removes."""
+    try:
+        manager.release(handle, keep_warm=keep_warm)
+    except Exception:
+        pass
+
+
+class DeepracerGymEnv(gym.Env):
+    metadata = {"render_modes": ["rgb_array", "human"], "render_fps": 30}
+
+    def __init__(
+        self,
+        agent_config: dict | None = None,
+        track_config: dict | None = None,
+        reward_function: Callable | None = None,
+        world_name: str | None = None,
+        evaluation: bool = False,
+        render_mode: str = "rgb_array",
+        image: str | None = None,
+        cpus: float = 3.0,
+        memory: str = "6g",
+        cache: bool = False,
+        manage_container: bool = True,
+        host: str = HOST,
+        port: int | None = None,
+        **kwargs,
+    ):
+        super().__init__(**kwargs)
+        self.render_mode = render_mode
+
+        agent_config = resolve_agent_config(agent_config)
+        track_config = resolve_track_config(track_config)
+        # Non-eval world_name replaces WORLD_NAME; eval mode passes EVAL_WORLD_NAME.
+        if world_name and not evaluation:
+            track_config = {**track_config, "WORLD_NAME": world_name}
+        from deepracer.service.validate import validate_configs
+
+        validate_configs(
+            agent_config,
+            track_config,
+            world_name=world_name,
+            evaluation=evaluation,
+        )
+
+        self.action_space, self._action_metadata = make_action_space(agent_config)
+        self.observation_space, self._observation_metadata = make_observation_space(
+            agent_config
+        )
+        self.reward_function = (
+            reward_function
+            if reward_function is not None
+            else default_reward_function()
+        )
+
+        self._cache = cache
+        self._manager = None
+        self._handle = None
+        self._finalizer = None
+        self._closed = False
+
+        if manage_container:
+            from deepracer.service.manager import SimulationManager
+
+            self._manager = SimulationManager.instance()
+            self._handle = self._manager.acquire(
+                agent_config=agent_config,
+                track_config=track_config,
+                image=image or DEFAULT_IMAGE,
+                cpus=cpus,
+                memory=memory,
+                evaluation=evaluation,
+                world_name=world_name,
+            )
+            connect_port = self._handle.port
+            # Safety net for a forgotten close(); the documented API is close().
+            self._finalizer = weakref.finalize(
+                self,
+                _release,
+                self._manager,
+                self._handle,
+                self._cache,
+            )
+        else:
+            connect_port = port if port is not None else _default_port()
+
+        logger.info(f"Using port {connect_port} for deepracer server.")
+
+        if isinstance(self.action_space, spaces.Discrete):
+            action_space_type = "discrete"
+        elif isinstance(self.action_space, spaces.Box):
+            action_space_type = "continuous"
+        self.deepracer_adapter = DeepracerGymAdapter(
+            action_space_type, host=host, port=connect_port
+        )
+
+    def reset(self, **kwargs):
+        super().reset(**kwargs)
+        observation, info = self.deepracer_adapter.env_reset()
+        return observation, info
+
+    def step(self, action: ActionType):
+        assert self.action_space.contains(action), (
+            f"Infeasible action. Action space does not containr {action}."
+        )
+
+        observation, terminated, truncated, info = self.deepracer_adapter.send_action(
+            action
+        )
+        reward = self.reward_function(info["reward_params"])
+        return observation, reward, terminated, truncated, info
+
+    def render(self, mode="rgb_array"):
+        observation, _, _, _ = self.deepracer_adapter._parse_response(
+            self.deepracer_adapter.response
+        )
+        measurement = None
+        for sensor in observation:
+            if "CAMERA" in sensor:
+                measurement = observation[sensor]
+
+        if measurement is None:
+            raise ValueError(
+                f"Cannot render output of sensors {list(observation.keys())}."
+            )
+
+        channels = num_channels(measurement)
+        if channels == 2:
+            # stereo camera
+            measurement = np.hstack((measurement[0, :, :], measurement[1, :, :]))
+
+        channels = num_channels(measurement)
+        if channels == 1:
+            # greyscale image
+            measurement = np.stack(3 * (measurement,), axis=-1)
+        elif channels == 3:
+            # front facing camera
+            measurement = measurement.transpose(1, 2, 0)
+
+        if mode == "human":
+            plt.imshow(np.asarray(measurement))
+            plt.axis("off")
+        elif mode == "rgb_array":
+            return np.asarray(measurement)
+
+    def close(self, cache: bool | None = None):
+        """Close the ZMQ client and release the sim container. Idempotent.
+
+        The container's fate is the env's `cache` flag (set at gym.make): with
+        cache=True it is kept warm so a later env in *this same process* with a
+        matching config re-attaches (faster boot); with cache=False (default) it
+        is stopped and removed. A warm container does NOT survive process exit.
+        Pass cache=… here only to override the constructor value at close time.
+
+        Because `cache` is a constructor argument, gym.make forwards it, so a
+        plain `env.close()` (through the gym.make wrapper) honors it — no
+        `.unwrapped` needed. The override path still needs the unwrapped env:
+        `deepracer.close(env, cache=False)` or `env.unwrapped.close(cache=…)`.
+        """
+        if self._closed:
+            return
+        self._closed = True
+        try:
+            self.deepracer_adapter.zmq_client.socket.close()
+        except Exception:
+            pass
+        if self._manager is not None and self._handle is not None:
+            use_cache = self._cache if cache is None else cache
+            if self._finalizer is not None:
+                self._finalizer.detach()
+            self._manager.release(self._handle, keep_warm=use_cache)
+        super().close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()