gaspersic/Gymnasium
1
0
Fork 0
mirror of https://github.com/Farama-Foundation/Gymnasium.git synced 2025-07-30 13:28:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update URL links and Space documentation summaries (#18)

Browse Source
This commit is contained in:
Manuel Goulão
2022-09-16 14:00:12 +01:00
committed by GitHub
parent 4d61477b7c
commit 2f8002f2bd
13 changed files with 125 additions and 86 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/README.md
View File

@@ -1,6 +1,6 @@
# Gymnasium-docs
This folder contains the documentation for [Gymnasium](https://github.com/Farama-Foundation/gymnasium).
This folder contains the documentation for [Gymnasium](https://github.com/Farama-Foundation/Gymnasium).
If you are modifying a non-environment page or an atari environment page, please PR this repo. Otherwise, follow the steps below:

89
docs/api/spaces.md
View File

@@ -1,5 +1,13 @@
# Spaces
```{toctree}
:hidden:
spaces/fundamental
spaces/composite
spaces/utils
```
```{eval-rst}
.. autoclass:: gymnasium.spaces.Space
```
@@ -28,77 +36,30 @@ Each space implements the following functions:
## Fundamental Spaces
### Box
```{eval-rst}
.. autoclass:: gymnasium.spaces.Box
.. currentmodule:: gymnasium.spaces
.. automethod:: is_bounded
.. automethod:: sample
```
### Discrete
```{eval-rst}
.. autoclass:: gymnasium.spaces.Discrete
.. automethod:: sample
```
### MultiBinary
```{eval-rst}
.. autoclass:: gymnasium.spaces.MultiBinary
.. automethod:: sample
```
### MultiDiscrete
```{eval-rst}
.. autoclass:: gymnasium.spaces.MultiDiscrete
.. automethod:: sample
```
### Text
```{eval-rst}
.. autoclass:: gymnasium.spaces.Text
.. automethod:: sample
```
* :py:class:`Box` - Supports continuous (and discrete) vectors or matrices, used for vector observations, images, etc
* :py:class:`Discrete` - Supports a single discrete number of values with an optional start for the values
* :py:class:`MultiDiscrete` - Supports single or matrices of binary values, used for holding down a button or if an agent has an object
* :py:class:`MultiBinary` - Supports multiple discrete values with multiple axes, used for controller actions
* :py:class:`Text` - Supports strings, used for passing agent messages, mission details, etc
```
## Composite Spaces
### Dict
```{eval-rst}
.. autoclass:: gymnasium.spaces.Dict
.. automethod:: sample
```
### Graph
```{eval-rst}
.. autoclass:: gymnasium.spaces.Graph
.. automethod:: sample
* :py:class:`Dict` - Supports a dictionary of keys and subspaces, used for a fixed number of unordered spaces
* :py:class:`Tuple` - Supports a tuple of subspaces, used for multiple for a fixed number of ordered spaces
* :py:class:`Sequence` - Supports a variable number of instances of a single subspace, used for entities spaces or selecting a variable number of actions
* :py:class:`Graph` - Supports graph based actions or observations with discrete or continuous nodes and edge values.
```
### Sequence
## Utils
```{eval-rst}
.. autoclass:: gymnasium.spaces.Sequence
.. automethod:: sample
```
### Tuple
```{eval-rst}
.. autoclass:: gymnasium.spaces.Tuple
.. automethod:: sample
```
* :py:class:`utils.flatdim` - The number of dimensions the flattened space will contain
* :py:class:`utils.flatten_space` - Flattens a space for which the `flattened` space instances will contain
* :py:class:`utils.flatten` - Flattens an instance of a space that is contained within the flattened version of the space
* :py:class:`utils.unflatten` - The reverse of the `flatten_space` function
```

33
docs/api/spaces/composite.md Normal file
View File

@@ -0,0 +1,33 @@
# Composite Spaces
## Dict
```{eval-rst}
.. autoclass:: gymnasium.spaces.Dict
.. automethod:: sample
```
## Tuple
```{eval-rst}
.. autoclass:: gymnasium.spaces.Tuple
.. automethod:: sample
```
## Sequence
```{eval-rst}
.. autoclass:: gymnasium.spaces.Sequence
.. automethod:: sample
```
## Graph
```{eval-rst}
.. autoclass:: gymnasium.spaces.Graph
.. automethod:: sample
```

46
docs/api/spaces/fundamental.md Normal file
View File

@@ -0,0 +1,46 @@
---
title: Fundamental Spaces
---
# Fundamental Spaces
## Box
```{eval-rst}
.. autoclass:: gymnasium.spaces.Box
.. automethod:: is_bounded
.. automethod:: sample
```
## Discrete
```{eval-rst}
.. autoclass:: gymnasium.spaces.Discrete
.. automethod:: sample
```
## MultiBinary
```{eval-rst}
.. autoclass:: gymnasium.spaces.MultiBinary
.. automethod:: sample
```
## MultiDiscrete
```{eval-rst}
.. autoclass:: gymnasium.spaces.MultiDiscrete
.. automethod:: sample
```
## Text
```{eval-rst}
.. autoclass:: gymnasium.spaces.Text
.. automethod:: sample
```

0
docs/api/spaces_utils.md → docs/api/spaces/utils.md
View File

2
docs/api/wrappers.md
View File

@@ -51,7 +51,7 @@ There are three common things you might want a wrapper to do:
Such wrappers can be easily implemented by inheriting from `ActionWrapper`, `ObservationWrapper`, or `RewardWrapper` and implementing the
respective transformation. If you need a wrapper to do more complicated tasks, you can inherit from the `Wrapper` class directly.
The code that is presented in the following sections can also be found in
the [gymnasium-examples](https://github.com/Farama-Foundation/gymnasium-examples) repository
the [gym-examples](https://github.com/Farama-Foundation/gym-examples) repository
## ActionWrapper
If you would like to apply a function to the action before passing it to the base environment,

10
docs/content/environment_creation.md
View File

@@ -17,7 +17,7 @@ pip install -e .
## Subclassing gymnasium.Env
Before learning how to create your own environment you should check out [the documentation of Gymnasium's API](https://gymnasium.farama.org/content/api/).
Before learning how to create your own environment you should check out [the documentation of Gymnasium's API](/api/core).
We will be concerned with a subset of gym-examples that looks like this:
@@ -56,7 +56,7 @@ where the blue dot is the agent and the red square represents the target.
Let us look at the source code of `GridWorldEnv` piece by piece:
### Declaration and Initialization
Our custom environment will inherit from the abstract class `gymnasium.Env`. You shouldn't forget to add the `metadata` attribute to you class.
Our custom environment will inherit from the abstract class `gymnasium.Env`. You shouldn't forget to add the `metadata` attribute to your class.
There, you should specify the render-modes that are supported by your environment (e.g. `"human"`, `"rgb_array"`, `"ansi"`)
and the framerate at which your environment should be rendered. Every environment should support`None` as render-mode; you don't need to add it in the metadata.
In `GridWorldEnv`, we will support the modes "rgb_array" and "human" and render at 4 FPS.
@@ -307,7 +307,7 @@ register(
The environment ID consists of three components, two of which are optional: an optional namespace (here: `gym_examples`), a mandatory name (here: `GridWorld`) and an optional but recommended version (here: v0). It might have also been registered as `GridWorld-v0` (the recommended approach), `GridWorld` or `gym_examples/GridWorld`, and the appropriate ID should then be used during environment creation.
The keyword argument `max_episode_steps=300` will ensure that GridWorld environments that are instantiated via `gymnasium.make`
will be wrapped in a `TimeLimit` wrapper (see [the wrapper documentation](https://www.gymlibrary.dev/pages/wrappers/index)
will be wrapped in a `TimeLimit` wrapper (see [the wrapper documentation](/api/wrappers)
for more information). A done signal will then be produced if the agent has reached the target *or* 300 steps have been
executed in the current episode. To distinguish truncation and termination, you can check `info["TimeLimit.truncated"]`.
@@ -372,7 +372,7 @@ also perfectly fine (but remember to add wrappers as well!).
Oftentimes, we want to use different variants of a custom environment, or we want to
modify the behavior of an environment that is provided by Gymnasium or some other party.
Wrappers allow us to do this without changing the environment implementation or adding any boilerplate code.
Check out the [wrapper documentation](https://www.gymlibrary.dev/content/wrappers/) for details on how to
Check out the [wrapper documentation](/api/wrappers/) for details on how to
use wrappers and instructions for implementing your own.
In our example, observations cannot be used directly in learning code because they are dictionaries.
However, we don't actually need to touch our environment implementation to fix this! We can simply add
@@ -389,7 +389,7 @@ print(wrapped_env.reset()) # E.g. [3 0 3 3], {}
Wrappers have the big advantage that they make environments highly modular. For instance, instead of flattening the
observations from GridWorld, you might only want to look at the relative position of the target and the agent.
In the section on [ObservationWrappers](https://www.gymlibrary.dev/content/wrappers/#observationwrapper) we have implemented
In the section on [ObservationWrappers](/api/wrappers/#observationwrapper) we have implemented
a wrapper that does this job. This wrapper is also available in gym-examples:
```python

5
docs/index.md
View File

@@ -12,7 +12,7 @@ lastpage:
:width: 500
```
**The Gymnasium interface is simple, pythonic, and capable of representing general RL problems:**
**Gymnasium is a maintained fork of OpenAI’s Gym library. The Gymnasium interface is simple, pythonic, and capable of representing general RL problems:**
```{code-block} python
@@ -41,7 +41,6 @@ content/basic_usage
api/core
api/spaces
api/spaces_utils
api/wrappers
api/vector
api/utils
@@ -71,7 +70,7 @@ content/vectorising
:hidden:
:caption: Development
Github <https://github.com/Farama-Foundation/gymnasium>
Github <https://github.com/Farama-Foundation/Gymnasium>
Donate <https://farama.org/donations>
```

8
gymnasium/utils/env_checker.py
View File

@@ -258,7 +258,7 @@ def check_env(env: gymnasium.Env, warn: bool = None, skip_render_check: bool = F
This is an invasive function that calls the environment's reset and step.
This is particularly useful when using a custom environment.
Please take a look at https://www.gymlibrary.dev/content/environment_creation/
Please take a look at https://gymnasium.farama.org/content/environment_creation/
for more information about the API.
Args:
@@ -271,7 +271,7 @@ def check_env(env: gymnasium.Env, warn: bool = None, skip_render_check: bool = F
assert isinstance(
env, gymnasium.Env
), "The environment must inherit from the gymnasium.Env class. See https://www.gymlibrary.dev/content/environment_creation/ for more info."
), "The environment must inherit from the gymnasium.Env class. See https://gymnasium.farama.org/content/environment_creation/ for more info."
if env.unwrapped is not env:
logger.warn(
@@ -281,13 +281,13 @@ def check_env(env: gymnasium.Env, warn: bool = None, skip_render_check: bool = F
# ============= Check the spaces (observation and action) ================
assert hasattr(
env, "action_space"
), "The environment must specify an action space. See https://www.gymlibrary.dev/content/environment_creation/ for more info."
), "The environment must specify an action space. See https://gymnasium.farama.org/content/environment_creation/ for more info."
check_action_space(env.action_space)
check_space_limit(env.action_space, "action")
assert hasattr(
env, "observation_space"
), "The environment must specify an observation space. See https://www.gymlibrary.dev/content/environment_creation/ for more info."
), "The environment must specify an observation space. See https://gymnasium.farama.org/content/environment_creation/ for more info."
check_observation_space(env.observation_space)
check_space_limit(env.observation_space, "observation")

4
gymnasium/wrappers/env_checker.py
View File

@@ -19,11 +19,11 @@ class PassiveEnvChecker(gymnasium.Wrapper):
assert hasattr(
env, "action_space"
), "The environment must specify an action space. https://www.gymlibrary.dev/content/environment_creation/"
), "The environment must specify an action space. https://gymnasium.farama.org/content/environment_creation/"
check_action_space(env.action_space)
assert hasattr(
env, "observation_space"
), "The environment must specify an observation space. https://www.gymlibrary.dev/content/environment_creation/"
), "The environment must specify an observation space. https://gymnasium.farama.org/content/environment_creation/"
check_observation_space(env.observation_space)
self.checked_reset = False

2
setup.py
View File

@@ -86,7 +86,7 @@ setup(
},
python_requires=">=3.6",
tests_require=extras["testing"],
url="https://www.gymlibrary.dev/",
url="https://gymnasium.farama.org/",
version=VERSION,
zip_safe=False,
)

6
tests/utils/test_env_checker.py
View File

@@ -244,15 +244,15 @@ def test_check_reset_options():
[
[
"Error",
"The environment must inherit from the gymnasium.Env class. See https://www.gymlibrary.dev/content/environment_creation/ for more info.",
"The environment must inherit from the gymnasium.Env class. See https://gymnasium.farama.org/content/environment_creation/ for more info.",
],
[
GenericTestEnv(action_space=None),
"The environment must specify an action space. See https://www.gymlibrary.dev/content/environment_creation/ for more info.",
"The environment must specify an action space. See https://gymnasium.farama.org/content/environment_creation/ for more info.",
],
[
GenericTestEnv(observation_space=None),
"The environment must specify an observation space. See https://www.gymlibrary.dev/content/environment_creation/ for more info.",
"The environment must specify an observation space. See https://gymnasium.farama.org/content/environment_creation/ for more info.",
],
],
)

4
tests/wrappers/test_passive_env_checker.py
View File

@@ -35,7 +35,7 @@ def test_passive_checker_wrapper_warnings(env):
[
(
GenericTestEnv(action_space=None),
"The environment must specify an action space. https://www.gymlibrary.dev/content/environment_creation/",
"The environment must specify an action space. https://gymnasium.farama.org/content/environment_creation/",
),
(
GenericTestEnv(action_space="error"),
@@ -43,7 +43,7 @@ def test_passive_checker_wrapper_warnings(env):
),
(
GenericTestEnv(observation_space=None),
"The environment must specify an observation space. https://www.gymlibrary.dev/content/environment_creation/",
"The environment must specify an observation space. https://gymnasium.farama.org/content/environment_creation/",
),
(
GenericTestEnv(observation_space="error"),