src.plangym.videogames.atari

src.plangym.videogames.atari#

Implement the plangym API for Atari environments.

Classes#

`AtariEnv`	Create an environment to play OpenAI gym Atari Games that uses AtariALE as the emulator.
`AtariPyEnvironment`	Create an environment to play OpenAI gym Atari Games that uses AtariPy as the emulator.

Functions#

ale_to_ram(ale)

Return the ram of the ale emulator.

Module Contents#

src.plangym.videogames.atari.ale_to_ram(ale)[source]#

Return the ram of the ale emulator.

Return type:: numpy.ndarray

class src.plangym.videogames.atari.AtariEnv(name, frameskip=5, episodic_life=False, autoreset=True, delay_setup=False, remove_time_limit=True, obs_type='rgb', mode=0, difficulty=0, repeat_action_probability=0.0, full_action_space=False, render_mode='rgb_array', possible_to_win=False, wrappers=None, array_state=True, clone_seeds=False, **kwargs)[source]#

Bases: plangym.videogames.env.VideogameEnv

Create an environment to play OpenAI gym Atari Games that uses AtariALE as the emulator.

Parameters:

name (str) – Name of the environment. Follows standard gym syntax conventions.
frameskip (int) – Number of times an action will be applied for each step in dt.
episodic_life (bool) – Return end = True when losing a life.
autoreset (bool) – Restart environment when reaching a terminal state.
delay_setup (bool) – If True do not initialize the gym.Environment and wait for setup to be called later.
remove_time_limit (bool) – If True, remove the time limit from the environment.
obs_type (str) – One of {“rgb”, “ram”, “grayscale”}.
mode (int) – Integer or string indicating the game mode, when available.
difficulty (int) – Difficulty level of the game, when available.
repeat_action_probability (float) – Repeat the last action with this probability.
full_action_space (bool) – Wheter to use the full range of possible actions or only those available in the game.
render_mode (str | None) – One of {None, “human”, “rgb_aray”}.
possible_to_win (bool) – It is possible to finish the Atari game without getting a terminal state that is not out of bounds or does not involve losing a life.
wrappers (Iterable[plangym.core.wrap_callable] | None) – Wrappers that will be applied to the underlying OpenAI env. Every element of the iterable can be either a gym.Wrapper or a tuple containing (gym.Wrapper, kwargs).
array_state (bool) – Whether to return the state of the environment as a numpy array.
clone_seeds (bool) – Clone the random seed of the ALE emulator when reading/setting the state. False makes the environment stochastic.

Example:

>>> env = plangym.make(name="ALE/MsPacman-v5", difficulty=2, mode=1)
>>> state, obs, info = env.reset()
>>>
>>> states = [state.copy() for _ in range(10)]
>>> actions = [env.action_space.sample() for _ in range(10)]
>>>
>>> data = env.step_batch(states=states, actions=actions)
>>> new_states, observs, rewards, ends, truncateds,infos = data

STATE_IS_ARRAY = True#

clone_seeds#

_mode#

_difficulty#

_repeat_action_probability#

_full_action_space#

DEFAULT_OBS_TYPE#

property ale#

Return the ``ale`` interface of the underlying :class:`gym.Env`.

Example:

>>> env = AtariEnv(name="ALE/MsPacman-v5", obs_type="ram")
>>> type(env.ale)
<class 'ale_py._ale_py.ALEInterface'>

property mode: int#

Return the selected game mode for the current environment.

Return type:: int

property difficulty: int#

Return the selected difficulty for the current environment.

Return type:: int

property repeat_action_probability: float#

Probability of repeating the same action after input.

Return type:: float

property full_action_space: bool#

If True the action space correspond to all possible actions in the Atari emulator.

Return type:: bool

property observation_space: gymnasium.spaces.Space#

Return the observation_space of the environment.

Return type:: gymnasium.spaces.Space

static _get_default_obs_type(name, obs_type)[source]#

Return the observation type of the internal Atari gym environment.

Return type:: str

get_lifes_from_info(info)[source]#

Return the number of lives remaining in the current game.

Parameters:: info (dict[str, Any])
Return type:: int

get_image()[source]#

Return a numpy array containing the rendered view of the environment.

Image is a three-dimensional array interpreted as an RGB image with channels (Height, Width, RGB). Ignores wrappers as it loads the screen directly from the emulator.

Example:

>>> env = AtariEnv(name="ALE/MsPacman-v5", obs_type="ram")
>>> img = env.get_image()
>>> img.shape
(210, 160, 3)

Return type:: numpy.ndarray

get_ram()[source]#

Return a numpy array containing the content of the emulator’s RAM.

The RAM is a vector array interpreted as the memory of the emulator.

Example:

>>> env = AtariEnv(name="ALE/MsPacman-v5", obs_type="grayscale")
>>> ram = env.get_ram()
>>> ram.shape, ram.dtype
((128,), dtype('uint8'))

Return type:: numpy.ndarray

init_gym_env()[source]#

Initialize the gym.Env` instance that the Environment is wrapping.

Return type:: gymnasium.Env

get_state()[source]#

Recover the internal state of the simulation.

If clone seed is False the environment will be stochastic. Cloning the full state ensures the environment is deterministic.

Example:

>>> env = AtariEnv(name="Qbert-v0")
>>> env.get_state() 
array([<ale_py._ale_py.ALEState object at 0x...>, None],
      dtype=object)

>>> env = AtariEnv(name="Qbert-v0", array_state=False)
>>> env.get_state() 
<ale_py._ale_py.ALEState object at 0x...>

Return type:: numpy.ndarray

set_state(state)[source]#

Set the internal state of the simulation.

Parameters:: state (numpy.ndarray) – Target state to be set in the environment.
Return type:: None

Example:

>>> env = AtariEnv(name="Qbert-v0")
>>> state, obs, info = env.reset()
>>> new_state, obs, reward, end, tru, info = env.step(env.sample_action(), state=state)
>>> assert not (state == new_state).all()
>>> env.set_state(state)
>>> (state == env.get_state()).all()
np.True_

step_with_dt(action, dt=1)[source]#

Step the environment dt times.

Take dt simulation steps and make the environment evolve in multiples of self.frameskip for a total of dt * self.frameskip steps.

Parameters:

action (numpy.ndarray | int | float) – Chosen action applied to the environment.
dt (int) – Consecutive number of times that the action will be applied.

Returns:

If state is None return (observs, reward, terminal, info) else returns (new_state, observs, reward, terminal, info)

Example:

>>> env = AtariEnv(name="Pong-v0")
>>> obs = env.reset(return_state=False)
>>> obs, reward, end, truncated, info = env.step_with_dt(env.sample_action(), dt=7)
>>> assert not end

clone(**kwargs)[source]#

Return a copy of the environment.

Return type:: plangym.videogames.env.VideogameEnv

class src.plangym.videogames.atari.AtariPyEnvironment(name, frameskip=5, episodic_life=False, autoreset=True, delay_setup=False, remove_time_limit=True, obs_type='rgb', mode=0, difficulty=0, repeat_action_probability=0.0, full_action_space=False, render_mode='rgb_array', possible_to_win=False, wrappers=None, array_state=True, clone_seeds=False, **kwargs)[source]#

Bases: AtariEnv

Create an environment to play OpenAI gym Atari Games that uses AtariPy as the emulator.

Parameters:

name (str)
frameskip (int)
episodic_life (bool)
autoreset (bool)
delay_setup (bool)
remove_time_limit (bool)
obs_type (str)
mode (int)
difficulty (int)
repeat_action_probability (float)
full_action_space (bool)
render_mode (str | None)
possible_to_win (bool)
wrappers (Iterable[plangym.core.wrap_callable] | None)
array_state (bool)
clone_seeds (bool)

get_state()[source]#

Recover the internal state of the simulation.

If clone seed is False the environment will be stochastic. Cloning the full state ensures the environment is deterministic.

Return type:: numpy.ndarray

set_state(state)[source]#

Set the internal state of the simulation.

Parameters:: state (numpy.ndarray) – Target state to be set in the environment.
Returns:: None
Return type:: None

get_ram()[source]#

Return a numpy array containing the content of the emulator’s RAM.

The RAM is a vector array interpreted as the memory of the emulator.

Return type:: numpy.ndarray