class_docstr: An environment runner to collect data from vectorized gymnasium environments.
class_docstr_tok: ["An","environment","runner","to","collect","data","from","vectorized","gymnasium","environments","."]
docstr: Runs and returns a sample (n timesteps or m episodes) on the environment(s).
  
  Timesteps or episodes are counted in total (across all vectorized
  sub-environments). For example, if self.num_envs=2 and num_timesteps=10, each
  sub-environment will be sampled for 5 steps. If self.num_envs=3 and
  num_episodes=30, each sub-environment will be sampled for 10 episodes.
  
  Args:
      num_timesteps: The number of timesteps to sample from the environment(s).
          Note that only exactly one of `num_timesteps` or `num_episodes` must be
          provided.
      num_episodes: The number of full episodes to sample from the environment(s).
          Note that only exactly one of `num_timesteps` or `num_episodes` must be
          provided.
      explore: Indicates whether to utilize exploration when picking actions.
      random_actions: Whether to only use random actions. If True, the value of
          `explore` is ignored.
      force_reset: Whether to reset the environment(s) before starting to sample.
          If False, will still reset the environment(s) if they were left in
          a terminated or truncated state during previous sample calls.
      with_render_data: If True, will record rendering images per timestep
          in the returned Episodes. This data can be used to create video
          reports.
          TODO (sven): Note that this is only supported for runnign with
           `num_episodes` yet.
  
  Returns:
      A tuple consisting of a) list of Episode instances that are done and
      b) list of Episode instances that are still ongoing.
code: def sample(
      self,
      *,
      num_timesteps: int = None,
      num_episodes: int = None,
      explore: bool = True,
      random_actions: bool = False,
      with_render_data: bool = False,
  ) -> Tuple[List[SingleAgentEpisode], List[SingleAgentEpisode]]:
      """Runs and returns a sample (n timesteps or m episodes) on the environment(s).
  
      Timesteps or episodes are counted in total (across all vectorized
      sub-environments). For example, if self.num_envs=2 and num_timesteps=10, each
      sub-environment will be sampled for 5 steps. If self.num_envs=3 and
      num_episodes=30, each sub-environment will be sampled for 10 episodes.
  
      Args:
          num_timesteps: The number of timesteps to sample from the environment(s).
              Note that only exactly one of `num_timesteps` or `num_episodes` must be
              provided.
          num_episodes: The number of full episodes to sample from the environment(s).
              Note that only exactly one of `num_timesteps` or `num_episodes` must be
              provided.
          explore: Indicates whether to utilize exploration when picking actions.
          random_actions: Whether to only use random actions. If True, the value of
              `explore` is ignored.
          force_reset: Whether to reset the environment(s) before starting to sample.
              If False, will still reset the environment(s) if they were left in
              a terminated or truncated state during previous sample calls.
          with_render_data: If True, will record rendering images per timestep
              in the returned Episodes. This data can be used to create video
              reports.
              TODO (sven): Note that this is only supported for runnign with
               `num_episodes` yet.
  
      Returns:
          A tuple consisting of a) list of Episode instances that are done and
          b) list of Episode instances that are still ongoing.
      """
      # If no execution details are provided, use self.config.
      if num_timesteps is None and num_episodes is None:
          if self.config.batch_mode == "truncate_episodes":
              num_timesteps = (
                  self.config.rollout_fragment_length * self.num_envs
              )
          else:
              num_episodes = self.num_envs
  
      # Sample n timesteps.
      if num_timesteps is not None:
          return self._sample_timesteps(
              num_timesteps=num_timesteps,
              explore=explore,
              random_actions=random_actions,
              force_reset=False,
          )
      # Sample n episodes.
      else:
          # `_sample_episodes` returns only one list (with completed episodes)
          # return empty list for incomplete ones.
          return (
              self._sample_episodes(
                  num_episodes=num_episodes,
                  explore=explore,
                  random_actions=random_actions,
                  with_render_data=with_render_data,
              ),
              [],
          )
  
imports: from collections import defaultdict
  from functools import partial
  from typing import List, Tuple
  import gymnasium
  import numpy
  import tree
  from ray.rllib.algorithms.algorithm_config import AlgorithmConfig
  from ray.rllib.core.models.base import STATE_IN, STATE_OUT
  from ray.rllib.env.env_runner import EnvRunner
  from ray.rllib.env.wrappers.atari_wrappers import NoopResetEnv, MaxAndSkipEnv
  from ray.rllib.env.wrappers.dm_control_wrapper import DMCEnv
  from ray.rllib.env.utils import _gym_env_creator
  from ray.rllib.evaluation.metrics import RolloutMetrics
  from ray.rllib.policy.sample_batch import DEFAULT_POLICY_ID, SampleBatch
  from ray.rllib.utils.annotations import override
  from ray.rllib.utils.framework import try_import_tf
  from ray.rllib.env.single_agent_episode import SingleAgentEpisode
  from ray.rllib.utils.numpy import one_hot
  from ray.tune.registry import ENV_CREATOR, _global_registry
label_desc: Use image node_id 2 for calling the DreamerV3EnvRunner obj's underlying member method code with example usage: obj.sample() and returns: self, self,  list