src.plangym.videogames.atari ============================ .. py:module:: src.plangym.videogames.atari .. autoapi-nested-parse:: Implement the ``plangym`` API for Atari environments. Classes ------- .. autoapisummary:: src.plangym.videogames.atari.AtariEnv src.plangym.videogames.atari.AtariPyEnvironment Functions --------- .. autoapisummary:: src.plangym.videogames.atari.ale_to_ram Module Contents --------------- .. py:function:: ale_to_ram(ale) Return the ram of the ale emulator. .. py:class:: 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) Bases: :py:obj:`plangym.videogames.env.VideogameEnv` Create an environment to play OpenAI gym Atari Games that uses AtariALE as the emulator. :param name: Name of the environment. Follows standard gym syntax conventions. :param frameskip: Number of times an action will be applied for each step in dt. :param episodic_life: Return ``end = True`` when losing a life. :param autoreset: Restart environment when reaching a terminal state. :param delay_setup: If ``True`` do not initialize the ``gym.Environment`` and wait for ``setup`` to be called later. :param remove_time_limit: If True, remove the time limit from the environment. :param obs_type: One of {"rgb", "ram", "grayscale"}. :param mode: Integer or string indicating the game mode, when available. :param difficulty: Difficulty level of the game, when available. :param repeat_action_probability: Repeat the last action with this probability. :param full_action_space: Wheter to use the full range of possible actions or only those available in the game. :param render_mode: One of {None, "human", "rgb_aray"}. :param possible_to_win: 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. :param wrappers: Wrappers that will be applied to the underlying OpenAI env. Every element of the iterable can be either a :class:`gym.Wrapper` or a tuple containing ``(gym.Wrapper, kwargs)``. :param array_state: Whether to return the state of the environment as a numpy array. :param clone_seeds: 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 .. py:attribute:: STATE_IS_ARRAY :value: True .. py:attribute:: clone_seeds .. py:attribute:: _mode .. py:attribute:: _difficulty .. py:attribute:: _repeat_action_probability .. py:attribute:: _full_action_space .. py:attribute:: DEFAULT_OBS_TYPE .. py: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) .. py:property:: mode :type: int Return the selected game mode for the current environment. .. py:property:: difficulty :type: int Return the selected difficulty for the current environment. .. py:property:: repeat_action_probability :type: float Probability of repeating the same action after input. .. py:property:: full_action_space :type: bool If True the action space correspond to all possible actions in the Atari emulator. .. py:property:: observation_space :type: gymnasium.spaces.Space Return the observation_space of the environment. .. py:method:: _get_default_obs_type(name, obs_type) :staticmethod: Return the observation type of the internal Atari gym environment. .. py:method:: get_lifes_from_info(info) Return the number of lives remaining in the current game. .. py:method:: get_image() 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) .. py:method:: get_ram() 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')) .. py:method:: init_gym_env() Initialize the :class:`gym.Env`` instance that the Environment is wrapping. .. py:method:: get_state() 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() #doctest: +ELLIPSIS array([, None], dtype=object) >>> env = AtariEnv(name="Qbert-v0", array_state=False) >>> env.get_state() #doctest: +ELLIPSIS .. py:method:: set_state(state) Set the internal state of the simulation. :param state: Target state to be set in the environment. 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_ .. py:method:: step_with_dt(action, dt = 1) 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. :param action: Chosen action applied to the environment. :param dt: 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 .. py:method:: clone(**kwargs) Return a copy of the environment. .. py:class:: 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) Bases: :py:obj:`AtariEnv` Create an environment to play OpenAI gym Atari Games that uses AtariPy as the emulator. .. py:method:: get_state() 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. .. py:method:: set_state(state) Set the internal state of the simulation. :param state: Target state to be set in the environment. :returns: None .. py:method:: get_ram() 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.