<liclass="toctree-l1 has-children"><aclass="reference internal"href="../../environments/toy_text/">Toy Text</a><inputclass="toctree-checkbox"id="toctree-checkbox-6"name="toctree-checkbox-6"role="switch"type="checkbox"/><labelfor="toctree-checkbox-6"><divclass="visually-hidden">Toggle navigation of Toy Text</div><iclass="icon"><svg><usehref="#svg-arrow-right"></use></svg></i></label><ul>
<liclass="toctree-l2"><aclass="reference internal"href="../../tutorials/gymnasium_basics/environment_creation/">Make your own custom environment</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="../../tutorials/gymnasium_basics/vector_envs_tutorial/">Training A2C with Vector Envs and Domain Randomization</a></li>
</ul>
</li>
<liclass="toctree-l1 has-children"><aclass="reference internal"href="../../tutorials/training_agents/">Training Agents</a><inputclass="toctree-checkbox"id="toctree-checkbox-9"name="toctree-checkbox-9"role="switch"type="checkbox"/><labelfor="toctree-checkbox-9"><divclass="visually-hidden">Toggle navigation of Training Agents</div><iclass="icon"><svg><usehref="#svg-arrow-right"></use></svg></i></label><ul>
<liclass="toctree-l2"><aclass="reference internal"href="../../tutorials/training_agents/reinforce_invpend_gym_v26/">Training using REINFORCE for Mujoco</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="../../tutorials/training_agents/blackjack_tutorial/">Solving Blackjack with Q-Learning</a></li>
<liclass="toctree-l1"><aclass="reference external"href="https://github.com/Farama-Foundation/Gymnasium/blob/main/docs/README.md">Contribute to the Docs</a></li>
<spanclass="sig-prename descclassname"><spanclass="pre">gymnasium.utils.seeding.</span></span><spanclass="sig-name descname"><spanclass="pre">np_random</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">seed</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">int</span><spanclass="w"></span><spanclass="p"><spanclass="pre">|</span></span><spanclass="w"></span><spanclass="pre">None</span></span><spanclass="w"></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="w"></span><spanclass="default_value"><spanclass="pre">None</span></span></em><spanclass="sig-paren">)</span><spanclass="sig-return"><spanclass="sig-return-icon">→</span><spanclass="sig-return-typehint"><spanclass="pre">tuple</span><spanclass="p"><spanclass="pre">[</span></span><spanclass="pre">np.random.Generator</span><spanclass="p"><spanclass="pre">,</span></span><spanclass="w"></span><spanclass="pre">int</span><spanclass="p"><spanclass="pre">]</span></span></span></span><aclass="reference internal"href="../../_modules/gymnasium/utils/seeding/#np_random"><spanclass="viewcode-link"><spanclass="pre">[source]</span></span></a><aclass="headerlink"href="#gymnasium.utils.seeding.np_random"title="Link to this definition">¶</a></dt>
<dd><p>Returns a NumPy random number generator (RNG) along with seed value from the inputted seed.</p>
<p>If <codeclass="docutils literal notranslate"><spanclass="pre">seed</span></code> is <codeclass="docutils literal notranslate"><spanclass="pre">None</span></code> then a <strong>random</strong> seed will be generated as the RNG’s initial seed.
This randomly selected seed is returned as the second value of the tuple.</p>
<p>This function is called in <aclass="reference internal"href="../env/#gymnasium.Env.reset"title="gymnasium.Env.reset"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">reset()</span></code></a> to reset an environment’s initial RNG.</p>
<spanclass="sig-prename descclassname"><spanclass="pre">gymnasium.utils.env_checker.</span></span><spanclass="sig-name descname"><spanclass="pre">check_env</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">env</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><aclass="reference internal"href="../env/#gymnasium.Env"title="gymnasium.core.Env"><spanclass="pre">Env</span></a></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">warn</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">bool</span><spanclass="w"></span><spanclass="p"><spanclass="pre">|</span></span><spanclass="w"></span><spanclass="pre">None</span></span><spanclass="w"></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="w"></span><spanclass="default_value"><spanclass="pre">None</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">skip_render_check</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">bool</span></span><spanclass="w"></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="w"></span><spanclass="default_value"><spanclass="pre">False</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">skip_close_check</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">bool</span></span><spanclass="w"></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="w"></span><spanclass="default_value"><spanclass="pre">False</span></span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../../_modules/gymnasium/utils/env_checker/#check_env"><spanclass="viewcode-link"><spanclass="pre">[source]</span></span></a><aclass="headerlink"href="#gymnasium.utils.env_checker.check_env"title="Link to this definition">¶</a></dt>
<dd><p>Check that an environment follows Gymnasium’s API.</p>
<p>To ensure that an environment is implemented “correctly”, <codeclass="docutils literal notranslate"><spanclass="pre">check_env</span></code> checks that the <aclass="reference internal"href="../env/#gymnasium.Env.observation_space"title="gymnasium.Env.observation_space"><codeclass="xref py py-attr docutils literal notranslate"><spanclass="pre">observation_space</span></code></a> and <aclass="reference internal"href="../env/#gymnasium.Env.action_space"title="gymnasium.Env.action_space"><codeclass="xref py py-attr docutils literal notranslate"><spanclass="pre">action_space</span></code></a> are correct.
Furthermore, the function will call the <aclass="reference internal"href="../env/#gymnasium.Env.reset"title="gymnasium.Env.reset"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">reset()</span></code></a>, <aclass="reference internal"href="../env/#gymnasium.Env.step"title="gymnasium.Env.step"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">step()</span></code></a> and <aclass="reference internal"href="../env/#gymnasium.Env.render"title="gymnasium.Env.render"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">render()</span></code></a> functions with a variety of values.</p>
<p>We highly recommend users call this function after an environment is constructed and within a project’s continuous integration to keep an environment update with Gymnasium’s API.</p>
<li><p><strong>env</strong>– Environment to use for playing.</p></li>
<li><p><strong>transpose</strong>– If this is <codeclass="docutils literal notranslate"><spanclass="pre">True</span></code>, the output of observation is transposed. Defaults to <codeclass="docutils literal notranslate"><spanclass="pre">True</span></code>.</p></li>
<li><p><strong>fps</strong>– Maximum number of steps of the environment executed every second. If <codeclass="docutils literal notranslate"><spanclass="pre">None</span></code> (the default),
<codeclass="docutils literal notranslate"><spanclass="pre">env.metadata["render_fps""]</span></code> (or 30, if the environment does not specify “render_fps”) is used.</p></li>
<li><p><strong>zoom</strong>– Zoom the observation in, <codeclass="docutils literal notranslate"><spanclass="pre">zoom</span></code> amount, should be positive float</p></li>
<li><p><strong>callback</strong>–<p>If a callback is provided, it will be executed after every step. It takes the following input:</p>
<ul>
<li><p>obs_t: observation before performing action</p></li>
<li><p>obs_tp1: observation after performing action</p></li>
<li><p>action: action that was executed</p></li>
<li><p>rew: reward that was received</p></li>
<li><p>terminated: whether the environment is terminated or not</p></li>
<li><p>truncated: whether the environment is truncated or not</p></li>
<li><p>info: debug info</p></li>
</ul>
</p></li>
<li><p><strong>keys_to_action</strong>–<p>Mapping from keys pressed to action performed.
Different formats are supported: Key combinations can either be expressed as a tuple of unicode code
points of the keys, as a tuple of characters, or as a string where each character of the string represents
one key.
For example if pressing ‘w’ and space at the same time is supposed
to trigger action number 2 then <codeclass="docutils literal notranslate"><spanclass="pre">key_to_action</span></code> dict could look like this:</p>
<p>If <codeclass="docutils literal notranslate"><spanclass="pre">None</span></code>, default <codeclass="docutils literal notranslate"><spanclass="pre">key_to_action</span></code> mapping for that environment is used, if provided.</p>
</p></li>
<li><p><strong>seed</strong>– Random seed used when resetting the environment. If None, no seed is used.</p></li>
<li><p><strong>noop</strong>– The action used when no key input has been entered, or the entered key combination is unknown.</p></li>
<li><p><strong>wait_on_player</strong>– Play should wait for a user action</p></li>
<p>Above code works also if the environment is wrapped, so it’s particularly useful in
verifying that the frame-level preprocessing does not render the game
unplayable.</p>
<p>If you wish to plot real time statistics as you play, you can use
<aclass="reference internal"href="#gymnasium.utils.play.PlayPlot"title="gymnasium.utils.play.PlayPlot"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">PlayPlot</span></code></a>. Here’s a sample code for plotting the reward
<emclass="property"><spanclass="pre">class</span><spanclass="w"></span></em><spanclass="sig-prename descclassname"><spanclass="pre">gymnasium.utils.play.</span></span><spanclass="sig-name descname"><spanclass="pre">PlayPlot</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">callback</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">Callable</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">horizon_timesteps</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">int</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">plot_names</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">list</span><spanclass="p"><spanclass="pre">[</span></span><spanclass="pre">str</span><spanclass="p"><spanclass="pre">]</span></span></span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../../_modules/gymnasium/utils/play/#PlayPlot"><spanclass="viewcode-link"><spanclass="pre">[source]</span></span></a><aclass="headerlink"href="#gymnasium.utils.play.PlayPlot"title="Link to this definition">¶</a></dt>
<dd><p>Provides a callback to create live plots of arbitrary metrics when using <aclass="reference internal"href="#gymnasium.utils.play.play"title="gymnasium.utils.play.play"><codeclass="xref py py-func docutils literal notranslate"><spanclass="pre">play()</span></code></a>.</p>
<dlclass="simple">
<dt>This class is instantiated with a function that accepts information about a single environment transition:</dt><dd><ulclass="simple">
<li><p>obs_t: observation before performing action</p></li>
<li><p>obs_tp1: observation after performing action</p></li>
<li><p>action: action that was executed</p></li>
<li><p>rew: reward that was received</p></li>
<li><p>terminated: whether the environment is terminated or not</p></li>
<li><p>truncated: whether the environment is truncated or not</p></li>
<li><p>info: debug info</p></li>
</ul>
</dd>
</dl>
<p>It should return a list of metrics that are computed from this data.
For instance, the function may look like this:</p>
<p><aclass="reference internal"href="#gymnasium.utils.play.PlayPlot"title="gymnasium.utils.play.PlayPlot"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">PlayPlot</span></code></a> provides the method <aclass="reference internal"href="#gymnasium.utils.play.PlayPlot.callback"title="gymnasium.utils.play.PlayPlot.callback"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">callback()</span></code></a> which will pass its arguments along to that function
and uses the returned values to update live plots of the metrics.</p>
<p>Typically, this <aclass="reference internal"href="#gymnasium.utils.play.PlayPlot.callback"title="gymnasium.utils.play.PlayPlot.callback"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">callback()</span></code></a> will be used in conjunction with <aclass="reference internal"href="#gymnasium.utils.play.play"title="gymnasium.utils.play.play"><codeclass="xref py py-func docutils literal notranslate"><spanclass="pre">play()</span></code></a> to see how the metrics evolve as you play:</p>
<emclass="property"><spanclass="pre">class</span><spanclass="w"></span></em><spanclass="sig-prename descclassname"><spanclass="pre">gymnasium.utils.play.</span></span><spanclass="sig-name descname"><spanclass="pre">PlayableGame</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">env</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><aclass="reference internal"href="../env/#gymnasium.Env"title="gymnasium.Env"><spanclass="pre">Env</span></a></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">keys_to_action</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">dict</span><spanclass="p"><spanclass="pre">[</span></span><spanclass="pre">tuple</span><spanclass="p"><spanclass="pre">[</span></span><spanclass="pre">int</span><spanclass="p"><spanclass="pre">,</span></span><spanclass="w"></span><spanclass="p"><spanclass="pre">...</span></span><spanclass="p"><spanclass="pre">]</span></span><spanclass="p"><spanclass="pre">,</span></span><spanclass="w"></span><spanclass="pre">int</span><spanclass="p"><spanclass="pre">]</span></span><spanclass="w"></span><spanclass="p"><spanclass="pre">|</span></span><spanclass="w"></span><spanclass="pre">None</span></span><spanclass="w"></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="w"></span><spanclass="default_value"><spanclass="pre">None</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">zoom</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">float</span><spanclass="w"></span><spanclass="p"><spanclass="pre">|</span></span><spanclass="w"></span><spanclass="pre">None</span></span><spanclass="w"></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="w"></span><spanclass="default_value"><spanclass="pre">None</span></span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../../_modules/gymnasium/utils/play/#PlayableGame"><spanclass="viewcode-link"><spanclass="pre">[source]</span></span></a><aclass="headerlink"href="#gymnasium.utils.play.PlayableGame"title="Link to this definition">¶</a></dt>
<dd><p>Wraps an environment allowing keyboard inputs to interact with the environment.</p>
<spanclass="sig-name descname"><spanclass="pre">process_event</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">event</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">Event</span></span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../../_modules/gymnasium/utils/play/#PlayableGame.process_event"><spanclass="viewcode-link"><spanclass="pre">[source]</span></span></a><aclass="headerlink"href="#gymnasium.utils.play.PlayableGame.process_event"title="Link to this definition">¶</a></dt>
<dd><p>Processes a PyGame event.</p>
<p>In particular, this function is used to keep track of which buttons are currently pressed
and to exit the <aclass="reference internal"href="#gymnasium.utils.play.play"title="gymnasium.utils.play.play"><codeclass="xref py py-func docutils literal notranslate"><spanclass="pre">play()</span></code></a> function when the PyGame window is closed.</p>
<emclass="property"><spanclass="pre">class</span><spanclass="w"></span></em><spanclass="sig-prename descclassname"><spanclass="pre">gymnasium.utils.ezpickle.</span></span><spanclass="sig-name descname"><spanclass="pre">EzPickle</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o"><spanclass="pre">*</span></span><spanclass="n"><spanclass="pre">args</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">Any</span></span></em>, <emclass="sig-param"><spanclass="o"><spanclass="pre">**</span></span><spanclass="n"><spanclass="pre">kwargs</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">Any</span></span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../../_modules/gymnasium/utils/ezpickle/#EzPickle"><spanclass="viewcode-link"><spanclass="pre">[source]</span></span></a><aclass="headerlink"href="#gymnasium.utils.ezpickle.EzPickle"title="Link to this definition">¶</a></dt>
<dd><p>Objects that are pickled and unpickled via their constructor arguments.</p>
<p>When this object is unpickled, a new <codeclass="docutils literal notranslate"><spanclass="pre">Dog</span></code> will be constructed by passing the provided furcolor and tailkind into the constructor.
However, philosophers are still not sure whether it is still the same dog.</p>
<p>This is generally needed only for environments which wrap C/C++ code, such as MuJoCo and Atari.</p>
<p>Uses the <codeclass="docutils literal notranslate"><spanclass="pre">args</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">kwargs</span></code> from the object’s constructor for pickling.</p>
</dd></dl>
</section>
<sectionid="save-rendering-videos">
<h2>Save Rendering Videos<aclass="headerlink"href="#save-rendering-videos"title="Link to this heading">¶</a></h2>
<li><p><strong>frames</strong> (<em>List</em><em>[</em><em>RenderFrame</em><em>]</em>) – A list of frames to compose the video.</p></li>
<li><p><strong>video_folder</strong> (<em>str</em>) – The folder where the recordings will be stored</p></li>
<li><p><strong>episode_trigger</strong>– Function that accepts an integer and returns <codeclass="docutils literal notranslate"><spanclass="pre">True</span></code> iff a recording should be started at this episode</p></li>
<li><p><strong>step_trigger</strong>– Function that accepts an integer and returns <codeclass="docutils literal notranslate"><spanclass="pre">True</span></code> iff a recording should be started at this step</p></li>
<li><p><strong>video_length</strong> (<em>int</em>) – The length of recorded episodes. If it isn’t specified, the entire episode is recorded.
Otherwise, snippets of the specified length are captured.</p></li>
<li><p><strong>name_prefix</strong> (<em>str</em>) – Will be prepended to the filename of the recordings.</p></li>
<li><p><strong>episode_index</strong> (<em>int</em>) – The index of the current episode.</p></li>
<li><p><strong>step_starting_index</strong> (<em>int</em>) – The step index of the first frame.</p></li>
<li><p><strong>save_logger</strong>– If to log the video saving progress, helpful for long videos that take a while, use “bar” to enable.</p></li>
<li><p><strong>**kwargs</strong>– The kwargs that will be passed to moviepy’s ImageSequenceClip.
You need to specify either fps or duration.</p></li>
<spanclass="sig-prename descclassname"><spanclass="pre">gymnasium.utils.save_video.</span></span><spanclass="sig-name descname"><spanclass="pre">capped_cubic_video_schedule</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">episode_id</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">int</span></span></em><spanclass="sig-paren">)</span><spanclass="sig-return"><spanclass="sig-return-icon">→</span><spanclass="sig-return-typehint"><spanclass="pre">bool</span></span></span><aclass="reference internal"href="../../_modules/gymnasium/utils/save_video/#capped_cubic_video_schedule"><spanclass="viewcode-link"><spanclass="pre">[source]</span></span></a><aclass="headerlink"href="#gymnasium.utils.save_video.capped_cubic_video_schedule"title="Link to this definition">¶</a></dt>
<dd><p>The default episode trigger.</p>
<p>This function will trigger recordings at the episode indices <spanclass="math notranslate nohighlight">\(\{0, 1, 4, 8, 27, ..., k^3, ..., 729, 1000, 2000, 3000, ...\}\)</span></p>
<spanclass="sig-prename descclassname"><spanclass="pre">gymnasium.utils.step_api_compatibility.</span></span><spanclass="sig-name descname"><spanclass="pre">step_api_compatibility</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">step_returns</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">TerminatedTruncatedStepType</span><spanclass="w"></span><spanclass="p"><spanclass="pre">|</span></span><spanclass="w"></span><spanclass="pre">DoneStepType</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">output_truncation_bool</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">bool</span></span><spanclass="w"></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="w"></span><spanclass="default_value"><spanclass="pre">True</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">is_vector_env</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">bool</span></span><spanclass="w"></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="w"></span><spanclass="default_value"><spanclass="pre">False</span></span></em><spanclass="sig-paren">)</span><spanclass="sig-return"><spanclass="sig-return-icon">→</span><spanclass="sig-return-typehint"><spanclass="pre">TerminatedTruncatedStepType</span><spanclass="w"></span><spanclass="p"><spanclass="pre">|</span></span><spanclass="w"></span><spanclass="pre">DoneStepType</span></span></span><aclass="reference internal"href="../../_modules/gymnasium/utils/step_api_compatibility/#step_api_compatibility"><spanclass="viewcode-link"><spanclass="pre">[source]</span></span></a><aclass="headerlink"href="#gymnasium.utils.step_api_compatibility.step_api_compatibility"title="Link to this definition">¶</a></dt>
<dd><p>Function to transform step returns to the API specified by <codeclass="docutils literal notranslate"><spanclass="pre">output_truncation_bool</span></code>.</p>
<p>Done (old) step API refers to <aclass="reference internal"href="../env/#gymnasium.Env.step"title="gymnasium.Env.step"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">step()</span></code></a> method returning <codeclass="docutils literal notranslate"><spanclass="pre">(observation,</span><spanclass="pre">reward,</span><spanclass="pre">done,</span><spanclass="pre">info)</span></code>
Terminated Truncated (new) step API refers to <aclass="reference internal"href="../env/#gymnasium.Env.step"title="gymnasium.Env.step"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">step()</span></code></a> method returning <codeclass="docutils literal notranslate"><spanclass="pre">(observation,</span><spanclass="pre">reward,</span><spanclass="pre">terminated,</span><spanclass="pre">truncated,</span><spanclass="pre">info)</span></code>
<li><p><strong>step_returns</strong> (<em>tuple</em>) – Items returned by <aclass="reference internal"href="../env/#gymnasium.Env.step"title="gymnasium.Env.step"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">step()</span></code></a>. Can be <codeclass="docutils literal notranslate"><spanclass="pre">(obs,</span><spanclass="pre">rew,</span><spanclass="pre">done,</span><spanclass="pre">info)</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">(obs,</span><spanclass="pre">rew,</span><spanclass="pre">terminated,</span><spanclass="pre">truncated,</span><spanclass="pre">info)</span></code></p></li>
<li><p><strong>output_truncation_bool</strong> (<em>bool</em>) – Whether the output should return two booleans (new API) or one (old) (<codeclass="docutils literal notranslate"><spanclass="pre">True</span></code> by default)</p></li>
<li><p><strong>is_vector_env</strong> (<em>bool</em>) – Whether the <codeclass="docutils literal notranslate"><spanclass="pre">step_returns</span></code> are from a vector environment</p></li>
<ddclass="field-even"><p><strong>step_returns</strong> (<em>tuple</em>) – Depending on <codeclass="docutils literal notranslate"><spanclass="pre">output_truncation_bool</span></code>, it can return <codeclass="docutils literal notranslate"><spanclass="pre">(obs,</span><spanclass="pre">rew,</span><spanclass="pre">done,</span><spanclass="pre">info)</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">(obs,</span><spanclass="pre">rew,</span><spanclass="pre">terminated,</span><spanclass="pre">truncated,</span><spanclass="pre">info)</span></code></p>
</dd>
</dl>
<pclass="rubric">Example</p>
<p>This function can be used to ensure compatibility in step interfaces with conflicting API. E.g. if env is written in old API,
wrapper is written in new API, and the final step output is desired to be in old API.</p>
<spanclass="sig-prename descclassname"><spanclass="pre">gymnasium.utils.step_api_compatibility.</span></span><spanclass="sig-name descname"><spanclass="pre">convert_to_terminated_truncated_step_api</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">step_returns</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">DoneStepType</span><spanclass="w"></span><spanclass="p"><spanclass="pre">|</span></span><spanclass="w"></span><spanclass="pre">TerminatedTruncatedStepType</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">is_vector_env</span></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="default_value"><spanclass="pre">False</span></span></em><spanclass="sig-paren">)</span><spanclass="sig-return"><spanclass="sig-return-icon">→</span><spanclass="sig-return-typehint"><spanclass="pre">TerminatedTruncatedStepType</span></span></span><aclass="reference internal"href="../../_modules/gymnasium/utils/step_api_compatibility/#convert_to_terminated_truncated_step_api"><spanclass="viewcode-link"><spanclass="pre">[source]</span></span></a><aclass="headerlink"href="#gymnasium.utils.step_api_compatibility.convert_to_terminated_truncated_step_api"title="Link to this definition">¶</a></dt>
<dd><p>Function to transform step returns to new step API irrespective of input API.</p>
<li><p><strong>step_returns</strong> (<em>tuple</em>) – Items returned by <aclass="reference internal"href="../env/#gymnasium.Env.step"title="gymnasium.Env.step"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">step()</span></code></a>. Can be <codeclass="docutils literal notranslate"><spanclass="pre">(obs,</span><spanclass="pre">rew,</span><spanclass="pre">done,</span><spanclass="pre">info)</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">(obs,</span><spanclass="pre">rew,</span><spanclass="pre">terminated,</span><spanclass="pre">truncated,</span><spanclass="pre">info)</span></code></p></li>
<li><p><strong>is_vector_env</strong> (<em>bool</em>) – Whether the <codeclass="docutils literal notranslate"><spanclass="pre">step_returns</span></code> are from a vector environment</p></li>
<spanclass="sig-prename descclassname"><spanclass="pre">gymnasium.utils.step_api_compatibility.</span></span><spanclass="sig-name descname"><spanclass="pre">convert_to_done_step_api</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">step_returns</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">TerminatedTruncatedStepType</span><spanclass="w"></span><spanclass="p"><spanclass="pre">|</span></span><spanclass="w"></span><spanclass="pre">DoneStepType</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">is_vector_env</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">bool</span></span><spanclass="w"></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="w"></span><spanclass="default_value"><spanclass="pre">False</span></span></em><spanclass="sig-paren">)</span><spanclass="sig-return"><spanclass="sig-return-icon">→</span><spanclass="sig-return-typehint"><spanclass="pre">DoneStepType</span></span></span><aclass="reference internal"href="../../_modules/gymnasium/utils/step_api_compatibility/#convert_to_done_step_api"><spanclass="viewcode-link"><spanclass="pre">[source]</span></span></a><aclass="headerlink"href="#gymnasium.utils.step_api_compatibility.convert_to_done_step_api"title="Link to this definition">¶</a></dt>
<dd><p>Function to transform step returns to old step API irrespective of input API.</p>
<li><p><strong>step_returns</strong> (<em>tuple</em>) – Items returned by <aclass="reference internal"href="../env/#gymnasium.Env.step"title="gymnasium.Env.step"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">step()</span></code></a>. Can be <codeclass="docutils literal notranslate"><spanclass="pre">(obs,</span><spanclass="pre">rew,</span><spanclass="pre">done,</span><spanclass="pre">info)</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">(obs,</span><spanclass="pre">rew,</span><spanclass="pre">terminated,</span><spanclass="pre">truncated,</span><spanclass="pre">info)</span></code></p></li>
<li><p><strong>is_vector_env</strong> (<em>bool</em>) – Whether the <codeclass="docutils literal notranslate"><spanclass="pre">step_returns</span></code> are from a vector environment</p></li>
</ul>
</dd>
</dl>
</dd></dl>
</section>
<sectionid="runtime-performance-benchmark">
<h2>Runtime Performance benchmark<aclass="headerlink"href="#runtime-performance-benchmark"title="Link to this heading">¶</a></h2>
<p>Sometimes is neccary to measure your environment’s runtime performance, and ensure no performance regressions take place.
These tests require manual inspection of its outputs:</p>
<spanclass="sig-prename descclassname"><spanclass="pre">gymnasium.utils.performance.</span></span><spanclass="sig-name descname"><spanclass="pre">benchmark_step</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">env</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><aclass="reference internal"href="../env/#gymnasium.Env"title="gymnasium.core.Env"><spanclass="pre">Env</span></a></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">target_duration</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">int</span></span><spanclass="w"></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="w"></span><spanclass="default_value"><spanclass="pre">5</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">seed</span></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="default_value"><spanclass="pre">None</span></span></em><spanclass="sig-paren">)</span><spanclass="sig-return"><spanclass="sig-return-icon">→</span><spanclass="sig-return-typehint"><spanclass="pre">float</span></span></span><aclass="reference internal"href="../../_modules/gymnasium/utils/performance/#benchmark_step"><spanclass="viewcode-link"><spanclass="pre">[source]</span></span></a><aclass="headerlink"href="#gymnasium.utils.performance.benchmark_step"title="Link to this definition">¶</a></dt>
<dd><p>A benchmark to measure the runtime performance of step for an environment.</p>
<spanclass="sig-prename descclassname"><spanclass="pre">gymnasium.utils.performance.</span></span><spanclass="sig-name descname"><spanclass="pre">benchmark_init</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">env_lambda</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">Callable</span><spanclass="p"><spanclass="pre">[</span></span><spanclass="p"><spanclass="pre">[</span></span><spanclass="p"><spanclass="pre">]</span></span><spanclass="p"><spanclass="pre">,</span></span><spanclass="w"></span><aclass="reference internal"href="../env/#gymnasium.Env"title="gymnasium.core.Env"><spanclass="pre">Env</span></a><spanclass="p"><spanclass="pre">]</span></span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">target_duration</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">int</span></span><spanclass="w"></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="w"></span><spanclass="default_value"><spanclass="pre">5</span></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">seed</span></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="default_value"><spanclass="pre">None</span></span></em><spanclass="sig-paren">)</span><spanclass="sig-return"><spanclass="sig-return-icon">→</span><spanclass="sig-return-typehint"><spanclass="pre">float</span></span></span><aclass="reference internal"href="../../_modules/gymnasium/utils/performance/#benchmark_init"><spanclass="viewcode-link"><spanclass="pre">[source]</span></span></a><aclass="headerlink"href="#gymnasium.utils.performance.benchmark_init"title="Link to this definition">¶</a></dt>
<dd><p>A benchmark to measure the initialization time and first reset.</p>
<spanclass="sig-prename descclassname"><spanclass="pre">gymnasium.utils.performance.</span></span><spanclass="sig-name descname"><spanclass="pre">benchmark_render</span></span><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n"><spanclass="pre">env</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><aclass="reference internal"href="../env/#gymnasium.Env"title="gymnasium.core.Env"><spanclass="pre">Env</span></a></span></em>, <emclass="sig-param"><spanclass="n"><spanclass="pre">target_duration</span></span><spanclass="p"><spanclass="pre">:</span></span><spanclass="w"></span><spanclass="n"><spanclass="pre">int</span></span><spanclass="w"></span><spanclass="o"><spanclass="pre">=</span></span><spanclass="w"></span><spanclass="default_value"><spanclass="pre">5</span></span></em><spanclass="sig-paren">)</span><spanclass="sig-return"><spanclass="sig-return-icon">→</span><spanclass="sig-return-typehint"><spanclass="pre">float</span></span></span><aclass="reference internal"href="../../_modules/gymnasium/utils/performance/#benchmark_render"><spanclass="viewcode-link"><spanclass="pre">[source]</span></span></a><aclass="headerlink"href="#gymnasium.utils.performance.benchmark_render"title="Link to this definition">¶</a></dt>
<dd><p>A benchmark to measure the time of render().</p>
<p>Note: does not work with <cite>render_mode=’human’</cite>
:param env: the environment to benchmarked (Note: must be renderable).
:param target_duration: the duration of the benchmark in seconds (note: it will go slightly over it).</p>
