platform-lander 0.1.0__tar.gz

platform_lander-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+The MIT License
+
+Copyright (c) 2016 OpenAI
+Copyright (c) 2022 Farama Foundation
+
+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.

platform_lander-0.1.0/MANIFEST.in

@@ -0,0 +1,12 @@
+include README.md
+include LICENSE
+recursive-include src/platform_lander *.py
+recursive-include tests *.py
+recursive-include examples *.py
+prune runs
+global-exclude __pycache__/*
+global-exclude *.py[cod]
+global-exclude .DS_Store
+global-exclude *.pt
+global-exclude *.csv
+global-exclude *.log

platform_lander-0.1.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.1
+Name: platform_lander
+Version: 0.1.0
+Summary: Standalone reusable-booster landing environment for reinforcement learning.
+Author: Andriy Burkov
+License: The MIT License
+        
+        Copyright (c) 2016 OpenAI
+        Copyright (c) 2022 Farama Foundation
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/aburkov/theDRLbook/tree/main/test_environments/platform_lander
+Project-URL: Source, https://github.com/aburkov/theDRLbook/tree/main/test_environments/platform_lander
+Project-URL: Repository, https://github.com/aburkov/theDRLbook
+Keywords: reinforcement-learning,rl,box2d,lander,environment
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: test
+Provides-Extra: train
+License-File: LICENSE
+
+# Platform Lander
+
+A standalone reusable-booster landing environment based on Gymnasium LunarLander v3 physics, but without importing Gymnasium. The task is to land a SpaceX-style booster upright on a moving floating platform. Missing the platform and falling into the ocean, or contacting the platform in a non-vertical position, terminates the episode as failure.
+
+## Install
+
+After the package has been published to PyPI:
+
+```bash
+pip install platform_lander
+```
+
+Before the PyPI release is available, install the same package directly from
+the book repository subdirectory:
+
+```bash
+pip install "platform_lander @ git+https://github.com/aburkov/theDRLbook.git#subdirectory=test_environments/platform_lander"
+```
+
+For local development from this folder:
+
+```bash
+pip install -e .
+```
+
+## Google Colab
+
+Use the same install command in the first notebook cell. Colab usually needs `swig` before Box2D builds:
+
+```python
+!apt-get -qq install swig
+!pip install -q platform_lander
+```
+
+Then import normally:
+
+```python
+from platform_lander import PlatformLander
+
+env = PlatformLander(render_mode="rgb_array", enable_wind=True, wind_power=5.0)
+obs, info = env.reset(seed=0)
+obs, reward, terminated, truncated, info = env.step(2)
+frame = env.render()
+```
+
+Display a rendered frame in Colab:
+
+```python
+import matplotlib.pyplot as plt
+
+plt.imshow(frame)
+plt.axis("off")
+plt.show()
+```
+
+## Local Script
+
+To watch the booster in a local Pygame window, install the package in editable
+mode and run the demo:
+
+```bash
+pip install -e .
+python examples/demo.py
+```
+
+The test file is headless, so running `pytest` or `python tests/test_platform_lander.py`
+will not open an animation window.
+
+To train a discrete policy with the textbook single-trajectory REINFORCE
+algorithm and then show three animated runs:
+
+```bash
+pip install -e ".[train]"
+python vanilla_reinforce.py
+```
+
+The repository also includes incremental REINFORCE variants:
+
+```bash
+python rtg_reinforce.py                                  # vanilla + per-timestep reward-to-go
+python average_reinforcement_baseline_reinforce.py       # reward-to-go + running scalar RTG baseline
+python value_function_baseline_reinforce.py              # reward-to-go + learned value-function baseline
+python batch_reinforce.py                                # vanilla + trajectory batches
+python full_reinforce.py                                 # batches + reward-to-go + selectable scalar baseline
+```
+
+Each training script writes a log, per-episode CSV data, and a checkpoint under
+`runs/` by default, for example `runs/full_reinforce.log`,
+`runs/full_reinforce.csv`, and `runs/full_reinforce.pt`. Override those paths
+with `--log-file`, `--csv-file`, and `--model-file`.
+
+To load the hardcoded `runs/full_reinforce.pt` checkpoint and watch several
+animated policy rollouts:
+
+```bash
+python watch_trained_policy.py
+```
+
+To generate one side-by-side results graph per variant from the saved CSV
+files:
+
+```bash
+python plot_reinforce_results.py
+```
+
+For a quick smoke test without opening the animation window:
+
+```bash
+python vanilla_reinforce.py --episodes 3 --max-steps 20 --no-animation
+```
+
+```python
+from platform_lander import PlatformLander
+
+env = PlatformLander(enable_wind=True, wind_direction=(1, 0.2), wind_power=5.0)
+obs, info = env.reset(seed=0)
+
+for _ in range(1000):
+    action = env.action_space.sample()
+    obs, reward, terminated, truncated, info = env.step(action)
+    if terminated or truncated:
+        print(info)
+        break
+
+env.close()
+```
+
+## API Notes
+
+- `PlatformLander(continuous=False)` uses `Discrete(4)` actions.
+- Actions: `0` no-op, `1` upper-left attitude jet, `2` bottom engine, `3` upper-right attitude jet.
+- `continuous=True` uses a two-value `Box(-1, 1, shape=(2,))` action.
+- Wind is controlled with `enable_wind`, `wind_power`, `wind_direction`, and `set_wind(...)`.
+- The booster has 100 available jet fires by default. After they are exhausted,
+  engine commands have no effect and the booster continues ballistically.
+- The observation includes the fraction of jet fires remaining.
+- The package provides local `Box` and `Discrete` spaces and does not import Gymnasium.
+
+## Publishing
+
+Build the package from this directory:
+
+```bash
+python -m build
+```
+
+Upload the generated `dist/platform_lander-*.tar.gz` and
+`dist/platform_lander-*.whl` files to PyPI with a PyPI account that owns the
+`platform_lander` project name:
+
+```bash
+python -m twine upload dist/*
+```

platform_lander-0.1.0/README.md

@@ -0,0 +1,153 @@
+# Platform Lander
+
+A standalone reusable-booster landing environment based on Gymnasium LunarLander v3 physics, but without importing Gymnasium. The task is to land a SpaceX-style booster upright on a moving floating platform. Missing the platform and falling into the ocean, or contacting the platform in a non-vertical position, terminates the episode as failure.
+
+## Install
+
+After the package has been published to PyPI:
+
+```bash
+pip install platform_lander
+```
+
+Before the PyPI release is available, install the same package directly from
+the book repository subdirectory:
+
+```bash
+pip install "platform_lander @ git+https://github.com/aburkov/theDRLbook.git#subdirectory=test_environments/platform_lander"
+```
+
+For local development from this folder:
+
+```bash
+pip install -e .
+```
+
+## Google Colab
+
+Use the same install command in the first notebook cell. Colab usually needs `swig` before Box2D builds:
+
+```python
+!apt-get -qq install swig
+!pip install -q platform_lander
+```
+
+Then import normally:
+
+```python
+from platform_lander import PlatformLander
+
+env = PlatformLander(render_mode="rgb_array", enable_wind=True, wind_power=5.0)
+obs, info = env.reset(seed=0)
+obs, reward, terminated, truncated, info = env.step(2)
+frame = env.render()
+```
+
+Display a rendered frame in Colab:
+
+```python
+import matplotlib.pyplot as plt
+
+plt.imshow(frame)
+plt.axis("off")
+plt.show()
+```
+
+## Local Script
+
+To watch the booster in a local Pygame window, install the package in editable
+mode and run the demo:
+
+```bash
+pip install -e .
+python examples/demo.py
+```
+
+The test file is headless, so running `pytest` or `python tests/test_platform_lander.py`
+will not open an animation window.
+
+To train a discrete policy with the textbook single-trajectory REINFORCE
+algorithm and then show three animated runs:
+
+```bash
+pip install -e ".[train]"
+python vanilla_reinforce.py
+```
+
+The repository also includes incremental REINFORCE variants:
+
+```bash
+python rtg_reinforce.py                                  # vanilla + per-timestep reward-to-go
+python average_reinforcement_baseline_reinforce.py       # reward-to-go + running scalar RTG baseline
+python value_function_baseline_reinforce.py              # reward-to-go + learned value-function baseline
+python batch_reinforce.py                                # vanilla + trajectory batches
+python full_reinforce.py                                 # batches + reward-to-go + selectable scalar baseline
+```
+
+Each training script writes a log, per-episode CSV data, and a checkpoint under
+`runs/` by default, for example `runs/full_reinforce.log`,
+`runs/full_reinforce.csv`, and `runs/full_reinforce.pt`. Override those paths
+with `--log-file`, `--csv-file`, and `--model-file`.
+
+To load the hardcoded `runs/full_reinforce.pt` checkpoint and watch several
+animated policy rollouts:
+
+```bash
+python watch_trained_policy.py
+```
+
+To generate one side-by-side results graph per variant from the saved CSV
+files:
+
+```bash
+python plot_reinforce_results.py
+```
+
+For a quick smoke test without opening the animation window:
+
+```bash
+python vanilla_reinforce.py --episodes 3 --max-steps 20 --no-animation
+```
+
+```python
+from platform_lander import PlatformLander
+
+env = PlatformLander(enable_wind=True, wind_direction=(1, 0.2), wind_power=5.0)
+obs, info = env.reset(seed=0)
+
+for _ in range(1000):
+    action = env.action_space.sample()
+    obs, reward, terminated, truncated, info = env.step(action)
+    if terminated or truncated:
+        print(info)
+        break
+
+env.close()
+```
+
+## API Notes
+
+- `PlatformLander(continuous=False)` uses `Discrete(4)` actions.
+- Actions: `0` no-op, `1` upper-left attitude jet, `2` bottom engine, `3` upper-right attitude jet.
+- `continuous=True` uses a two-value `Box(-1, 1, shape=(2,))` action.
+- Wind is controlled with `enable_wind`, `wind_power`, `wind_direction`, and `set_wind(...)`.
+- The booster has 100 available jet fires by default. After they are exhausted,
+  engine commands have no effect and the booster continues ballistically.
+- The observation includes the fraction of jet fires remaining.
+- The package provides local `Box` and `Discrete` spaces and does not import Gymnasium.
+
+## Publishing
+
+Build the package from this directory:
+
+```bash
+python -m build
+```
+
+Upload the generated `dist/platform_lander-*.tar.gz` and
+`dist/platform_lander-*.whl` files to PyPI with a PyPI account that owns the
+`platform_lander` project name:
+
+```bash
+python -m twine upload dist/*
+```

platform_lander-0.1.0/examples/demo.py

@@ -0,0 +1,70 @@
+"""Render PlatformLander in a local Pygame window.
+
+Run from the project root with:
+
+    python examples/demo.py
+
+The tests are intentionally headless; this script is for visual inspection.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+SRC = PROJECT_ROOT / "src"
+if str(SRC) not in sys.path:
+    sys.path.insert(0, str(SRC))
+
+from platform_lander import PlatformLander, heuristic  # noqa: E402
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Watch the PlatformLander environment.")
+    parser.add_argument("--policy", choices=["heuristic", "random"], default="heuristic")
+    parser.add_argument("--seed", type=int, default=0)
+    parser.add_argument("--episodes", type=int, default=5)
+    parser.add_argument("--wind", action="store_true", help="Enable wind during the demo.")
+    parser.add_argument("--wind-power", type=float, default=5.0)
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    env = PlatformLander(
+        render_mode="human",
+        enable_wind=args.wind,
+        wind_power=args.wind_power,
+        wind_direction=(1.0, 0.0),
+    )
+
+    try:
+        for episode in range(args.episodes):
+            obs, _ = env.reset(seed=args.seed + episode)
+            total_reward = 0.0
+
+            for step in range(1000):
+                if args.policy == "random":
+                    action = env.action_space.sample()
+                else:
+                    action = heuristic(env, obs)
+
+                obs, reward, terminated, truncated, info = env.step(action)
+                total_reward += reward
+
+                if terminated or truncated:
+                    print(
+                        f"episode={episode} step={step} "
+                        f"reward={total_reward:.1f} info={info}"
+                    )
+                    break
+    finally:
+        env.close()
+
+
+if __name__ == "__main__":
+    main()
+

platform_lander-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "platform_lander"
+version = "0.1.0"
+description = "Standalone reusable-booster landing environment for reinforcement learning."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [{ name = "Andriy Burkov" }]
+keywords = ["reinforcement-learning", "rl", "box2d", "lander", "environment"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "numpy>=1.21",
+    "box2d-py>=2.3.5",
+    "pygame>=2.1",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+train = ["torch>=2"]
+
+[project.urls]
+Homepage = "https://github.com/aburkov/theDRLbook/tree/main/test_environments/platform_lander"
+Source = "https://github.com/aburkov/theDRLbook/tree/main/test_environments/platform_lander"
+Repository = "https://github.com/aburkov/theDRLbook"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools]
+license-files = ["LICENSE"]

platform_lander-0.1.0/setup.cfg

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

platform_lander-0.1.0/src/platform_lander/__init__.py

@@ -0,0 +1,12 @@
+"""Standalone SpaceX-style platform landing environment.
+
+This package is intentionally independent from Gymnasium. It keeps the familiar
+``reset``/``step``/``render`` API and lightweight ``Box``/``Discrete`` spaces so
+it can be used by RL code without importing ``gymnasium``.
+"""
+
+from platform_lander.platform_lander import PlatformLander, heuristic
+from platform_lander.spaces import Box, Discrete
+
+__all__ = ["PlatformLander", "heuristic", "Box", "Discrete"]
+

platform_lander-0.1.0/src/platform_lander/core.py

@@ -0,0 +1,88 @@
+"""Small Gymnasium-compatible core helpers used by :mod:`platform_lander`.
+
+The environment code is adapted from Gymnasium's LunarLander v3, but this file
+contains the minimal runtime support needed to use it without importing
+Gymnasium.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+
+class DependencyNotInstalled(ImportError):
+    """Raised when an optional rendering or physics dependency is missing."""
+
+
+class Error(Exception):
+    """Base package exception."""
+
+
+def np_random(seed: int | None = None) -> tuple[np.random.Generator, int]:
+    """Return a NumPy random generator and the seed used to create it."""
+
+    if seed is not None and not (isinstance(seed, int) and seed >= 0):
+        raise Error(f"Seed must be a non-negative python integer, got {seed!r}")
+
+    seed_seq = np.random.SeedSequence(seed)
+    rng = np.random.Generator(np.random.PCG64(seed_seq))
+    return rng, int(seed_seq.entropy)
+
+
+class Env:
+    """Minimal environment base class with Gymnasium-style seeding."""
+
+    metadata: dict[str, Any] = {"render_modes": []}
+    render_mode: str | None = None
+
+    _np_random: np.random.Generator | None = None
+    _np_random_seed: int | None = None
+
+    def reset(self, *, seed: int | None = None, options: dict | None = None):
+        if seed is not None:
+            self._np_random, self._np_random_seed = np_random(seed)
+
+    @property
+    def np_random(self) -> np.random.Generator:
+        if self._np_random is None:
+            self._np_random, self._np_random_seed = np_random()
+        return self._np_random
+
+    @np_random.setter
+    def np_random(self, value: np.random.Generator) -> None:
+        self._np_random = value
+        self._np_random_seed = -1
+
+    @property
+    def np_random_seed(self) -> int:
+        if self._np_random_seed is None:
+            self._np_random, self._np_random_seed = np_random()
+        return self._np_random_seed
+
+    @property
+    def unwrapped(self):
+        return self
+
+    def close(self) -> None:
+        pass
+
+
+class EzPickle:
+    """Pickle objects by replaying their constructor arguments."""
+
+    def __init__(self, *args: object, **kwargs: object) -> None:
+        self._ezpickle_args = args
+        self._ezpickle_kwargs = kwargs
+
+    def __getstate__(self) -> dict[str, Any]:
+        return {
+            "_ezpickle_args": self._ezpickle_args,
+            "_ezpickle_kwargs": self._ezpickle_kwargs,
+        }
+
+    def __setstate__(self, state: dict[str, Any]) -> None:
+        obj = type(self)(*state["_ezpickle_args"], **state["_ezpickle_kwargs"])
+        self.__dict__.update(obj.__dict__)
+