Metadata-Version: 2.4
Name: gymDSM
Version: 2.0.0
Summary: gymDSM (Didactically Supercharged Mod): a small library that provides didactically enhanced Gymnasium environments (e.g., a MountainCar variant whose render color shows the last action).
Home-page: https://github.com/DanielSaromo/gymDSM
Author: Daniel Saromo
Author-email: danielsaromo@gmail.com
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: gymnasium>=1.0
Requires-Dist: numpy
Provides-Extra: render
Requires-Dist: gymnasium[classic-control]; extra == "render"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# gymDSM
gymDSM (Didactically Supercharged Mod): A modified version of [Gymnasium](https://gymnasium.farama.org/) (the maintained successor of OpenAI Gym).

## What is gymDSM?
**gymDSM** is a small Python package that provides **didactically enhanced** (teaching-friendly) variants of classic [Gymnasium](https://gymnasium.farama.org/) environments.

### MountainCar

At the moment, gymDSM focuses on **MountainCar** with a small (but important) visual modification: the car’s color reflects the **last action** taken:
- `0` (push left)  → red  
- `1` (no push)    → blue  
- `2` (push right) → green  

The goal is to make it easier to understand what an agent is doing while interacting with the environment.

Everything else (physics, rewards, observation/action spaces, seeding, the 200-step time limit, and the `goal_velocity` parameter) is **identical** to Gymnasium's [Mountain Car](https://gymnasium.farama.org/environments/classic_control/mountain_car/), because the gymDSM environment subclasses it and only changes the rendering.

## Installation

The library gymDSM is on the [Python Package Index](https://pypi.org/project/gymDSM/ "gymDSM page on PyPI").
To install the library, first install `pip` and then use the command `pip install gymDSM`. Alternatively, you can use `pip install gymdsm`. Remember that pip/PyPI treat distribution names case-insensitively.

This project works with **Gymnasium 1.0 or newer** (tested with Gymnasium 1.0.0 and 1.4.0), which is installed automatically as a dependency.

If you want to use rendering (`render_mode="human"` or `render_mode="rgb_array"`), use the following installation command:

```bash
pip install "gymDSM[render]"
```

(The command above installs `gymnasium[classic-control]`, which brings in the pygame version that your Gymnasium release expects.)

> **Upgrading from gymDSM 1.x (Gym 0.22)?** See [Migrating from gymDSM 1.x](#migrating-from-gymdsm-1x-gym-022) below.

---

## Minimal Working Example (MWE)

### 1) Create the environment using gymDSM.make
This is designed to be easily replaceable with the usual Gymnasium pattern:

```python
import gymDSM

env = gymDSM.make("MountainCar-v0")

obs, info = env.reset(seed=42)
done = False

while not done:
    action = env.action_space.sample()  # random policy
    obs, reward, terminated, truncated, info = env.step(action)
    done = terminated or truncated

env.close()
```

### 2) Render in a window (optional)
In Gymnasium, the render mode is chosen when the environment is created. With `render_mode="human"`, the window is updated automatically on every `reset()` and `step()`, so there is no need to call `env.render()`:

```python
import gymDSM

env = gymDSM.make("MountainCar-v0", render_mode="human")  # requires pygame
obs, info = env.reset(seed=42)

done = False
while not done:
    action = env.action_space.sample()
    obs, reward, terminated, truncated, info = env.step(action)
    done = terminated or truncated

env.close()
```

### 3) Get frames as images (optional)
Use `render_mode="rgb_array"` to get each frame as a NumPy array of shape `(400, 600, 3)`, e.g., to record videos or show them in a Jupyter notebook:

```python
import gymDSM

env = gymDSM.make("MountainCar-v0", render_mode="rgb_array")  # requires pygame
obs, info = env.reset(seed=42)
obs, reward, terminated, truncated, info = env.step(2)  # push right

frame = env.render()  # the car is green in this frame
env.close()
```

## Behavior and supported environments

For now, only Gymnasium's [Mountain Car](https://gymnasium.farama.org/environments/classic_control/mountain_car/) environment is supported.

- If you call:
  ```python
  env = gymDSM.make("MountainCar-v0")
  ```
  gymDSM will try to create the gymDSM MountainCar variant (with action-based colors).

- If `env_id` is not supported by gymDSM, or if creating the gymDSM version fails for any reason, `gymDSM.make(...)` falls back to:
  ```python
  gymnasium.make(env_id, ...)
  ```
  using the standard Gymnasium environment (a warning is shown if the gymDSM version failed).

- Importing gymDSM also registers the colored environment in Gymnasium under the ID `ColoredActionMountainCar-v0`, so it can be used with plain Gymnasium too (e.g., with vectorized environments or RL libraries that call `gymnasium.make` internally):
  ```python
  import gymnasium as gym
  import gymDSM  # registers "ColoredActionMountainCar-v0"

  env = gym.make("ColoredActionMountainCar-v0", render_mode="rgb_array")
  ```

## Migrating from gymDSM 1.x (Gym 0.22)

gymDSM 2.0 follows the [Gymnasium API](https://gymnasium.farama.org/introduction/migration_guide/). If you have code written for gymDSM 1.x, update it as follows:

| gymDSM 1.x (Gym 0.22) | gymDSM 2.x (Gymnasium) |
|---|---|
| `obs = env.reset()` | `obs, info = env.reset(seed=None)` |
| `obs, reward, done, info = env.step(a)` | `obs, reward, terminated, truncated, info = env.step(a)`<br>`done = terminated or truncated` |
| `env.render()` / `env.render(mode="rgb_array")` | `gymDSM.make(..., render_mode="human")` or `render_mode="rgb_array"`, then `env.render()` (no arguments) |
| `env.seed(42)` | `env.reset(seed=42)` |
| `import gym` | `import gymnasium as gym` |

`terminated` is `True` when the car reaches the flag; `truncated` is `True` when the 200-step time limit is reached.

## License and Acknowledgments

**gymDSM** is an independent open-source project that originates from a fork of OpenAI Gym and is now built on top of Gymnasium. This project is **not** affiliated with or endorsed by OpenAI or the Farama Foundation. gymDSM is developed for research and educational purposes. It builds upon the foundation laid by the OpenAI Gym and Gymnasium libraries, and we acknowledge and thank the original OpenAI Gym authors, the Farama Foundation, and all contributors for their pioneering work.

gymDSM, the original OpenAI Gym, and Gymnasium are released under the MIT License. We have retained the original project's MIT licensing for gymDSM, ensuring that any use or distribution of this fork complies with the same terms. Please see the `LICENSE` file in this repository for the full text of the MIT License.
