stormvogel.extensions.gym_grid
==============================

.. py:module:: stormvogel.extensions.gym_grid

.. autoapi-nested-parse::

   Convert gymnasium grid environments to stormvogel models, and render them as gifs.



Attributes
----------

.. autoapisummary::

   stormvogel.extensions.gym_grid.GRID_ACTION_LABEL_MAP


Functions
---------

.. autoapisummary::

   stormvogel.extensions.gym_grid.gymnasium_grid_to_stormvogel
   stormvogel.extensions.gym_grid.to_coordinate
   stormvogel.extensions.gym_grid.to_state
   stormvogel.extensions.gym_grid.get_target_state
   stormvogel.extensions.gym_grid.to_gymnasium_scheduler
   stormvogel.extensions.gym_grid.gymnasium_render_model_gif


Module Contents
---------------

.. py:data:: GRID_ACTION_LABEL_MAP

.. py:function:: gymnasium_grid_to_stormvogel(env, action_label_map: dict[int, str] = GRID_ACTION_LABEL_MAP)

   Convert a FrozenLake, Taxi, or Cliffwalking gymnasium environment to an explicit stormvogel model.

   :param env: Gymnasium environment.
   :param action_label_map: Mapping from action numbers to action labels.
   :returns: Stormvogel model.


.. py:function:: to_coordinate(s, env)

   Calculate the state's coordinates.

   Work for FrozenLake, Cliffwalking, and Taxi.

   :param s: State index.
   :param env: Gymnasium environment.
   :returns: ``(x, y)`` coordinate tuple.


.. py:function:: to_state(x, y, env)

   Calculate the state index from coordinates.

   Work for FrozenLake, CliffWalking, and Taxi.

   :param x: X coordinate.
   :param y: Y coordinate.
   :param env: Gymnasium environment.
   :returns: State index.


.. py:function:: get_target_state(env)

   Calculate the target state for an environment.

   Work for FrozenLake and Cliffwalking.

   :param env: Gymnasium environment.
   :returns: Target state index.


.. py:function:: to_gymnasium_scheduler(model: stormvogel.model.Model, scheduler: stormvogel.result.Scheduler | Callable[[stormvogel.model.State], stormvogel.model.Action], action_label_map: dict[int, str] = GRID_ACTION_LABEL_MAP) -> Callable[[int], int]

   Convert a stormvogel scheduler to a gymnasium scheduler.

   Intended for models converted via :func:`gymnasium_grid_to_stormvogel`.

   :param model: Stormvogel model.
   :param scheduler: Stormvogel scheduler.
   :param action_label_map: Mapping used in the call to :func:`gymnasium_grid_to_stormvogel`.
   :returns: A callable mapping environment state ids to action numbers.


.. py:function:: gymnasium_render_model_gif(env, gymnasium_scheduler: Callable[[int], int] | None = None, filename: str = 'my_gif', max_length: int = 50, fps: int = 2, loop: int = 0) -> str

   Render a gymnasium model to a gif.

   Use *gymnasium_scheduler* to pick actions; leave as ``None`` for random actions.

   :param env: Gymnasium environment.
   :param gymnasium_scheduler: Function mapping a state number to an action number.
   :param filename: Name of the gif file to save.
   :param max_length: Maximum number of frames to render.
   :param fps: Frames per second for the gif.
   :param loop: Number of times to loop the gif. ``0`` means loop forever.
   :returns: Filesystem path of the saved gif.