Skip to content

API: Среды

envs

GridWorldEnv

Bases: Env

Среда-сетка для задач обучения с подкреплением.

Среда представляет собой двумерную сетку размером h*w, окруженную стенами. Внутри сетки могут располагаться препятствия и одна клетка-цель. Пол может иметь разные цвета (типы), задаваемые параметром n_colors.

Attributes:

Name Type Description
h int

Высота внутренней сетки (без стен).
w int

Ширина внутренней сетки (без стен).
n_colors int

Количество типов пола (0 до n_colors-1).
pos_goal ndarray

Позиция цели в координатах внутренней сетки.
start_pos Union[Tuple[int, int], ndarray]

Начальная позиция агента или распределение вероятностей.
see_obstacle bool

Определяет, видны ли препятствия при наблюдении.
render_mode Optional[str]

Режим отрисовки ('human' или 'rgb_array').
obstacle_mask ndarray

Булева маска препятствий размером (h, w).
feature_wall int

Значение признака для стен в векторе наблюдений.
feature_obstacle int

Значение признака для препятствий.
feature_goal int

Значение признака для цели.
grid ndarray

Внутренняя сетка размером (h+2, w+2) с границами-стенами.
agent_pos ndarray

Текущая позиция агента в координатах сетки со стенами.
see_pos ndarray

Позиция, которую "видит" агент для наблюдений.
seed int

Зерно для генерации среды, для возможности повторно сгенерировать карту.
step_reward float

Награда/штраф за обычный шаг (по умолчанию 0.0).
goal_reward float

Награда за достижение цели (по умолчанию 1.0).
Action Space

Пространство действий — дискретное с 4 направлениями:

  • 0: вверх ( [-1, 0] )
  • 1: вправо ( [ 0, 1] )
  • 2: вниз ( [ 1, 0] )
  • 3: влево ( [ 0, -1] )
Observation Space

Пространство наблюдений — вещественный вектор размерности (n_colors + 3), закодированный как one-hot вектор, где 3 дополнительных признака соответствуют стене, препятствию и цели.

\[\text{shape} = (\text{n_{colors}} + 3,)\]
Reward

По умолчанию: - Награда goal_reward (1.0) при достижении цели (клетки GOAL), - Награда step_reward (0.0) в остальных случаях.

Можно включить shaping, задав отрицательный step_reward (например, -0.01, чтобы поощрять быстрый путь).

Episode Termination

Эпизод завершается, когда агент достигает клетки с целью или же когда превышено выделенное количество шагов на эпизодов (по умолчанию берется w*h)

reset 

reset(seed=None, options=None)

Перезапуск среды.

seed
  • передаётся в super().reset(seed=seed) → инициализирует self.np_random;
  • используется в _init_grid ТОЛЬКО если self.seed is None и карта ещё не сохранена.
Возвращает

obs: np.ndarray shape (obs_dim,) info: {}

step 

step(action)

Выполняет одно действие в среде.

Награда
  • self.step_reward за обычный шаг;
  • self.goal_reward при достижении цели.

GridWorldMnistEnv

Bases: GridWorldEnv

Вариант GridWorld, где наблюдение кодируется случайным изображением из MNIST по "цифре", соответствующей типу клетки.

Соответствие следующее:

  • пол цвета c (0 .. n_colors-1) -> цифра c;
  • стена -> цифра 7;
  • препятствие -> цифра 8;
  • цель -> цифра 9.
Ограничения
  • изображение вырезается как центр-кроп из 28x28 MNIST до размера image_size x image_size (image_size >= 12).
Наблюдение
  • если flatten=True: obs.shape = (image_size * image_size,)
  • иначе: obs.shape = (image_size, image_size)
Параметр step_reward наследуется от GridWorldEnv
  • по умолчанию 0.0;
  • можно задать отрицательное значение, чтобы ускорить достижение цели.

reset 

reset(seed=None, options=None)

Перезапуск среды.

render_map 

render_map()

Визуализация поля.

digit_render_mode
  • "text" : цветные тайлы + напечатанные цифры;
  • "mnist": поле из MNIST-изображений (мозаика), агент поверх.

GymVectorGridWorldEnv

Bases: Env

Векторная GridWorld‑среда на базе gymnasium.vector.SyncVectorEnv.

Внутри
  • n_envs независимых копий одиночной GridWorldEnv;
  • каждую копию создаём отдельной фабрикой env_fn;
  • SyncVectorEnv управляет всем батчем.
ВАЖНО
  • Все под‑среды используют ОДИН И ТОТ ЖЕ seed для генерации карты (пол/препятствия), чтобы карта была идентичной;
  • Карта генерируется ОДИН РАЗ при создании среды и кэшируется;
  • при reset() используется закэшированная карта, гарантируя идентичность карт во всех эпизодах и под-средах.

__init__ 

__init__(n_envs, make_env_kwargs=None, base_seed=None, render_mode=None)

Parameters:

Name Type Description Default
n_envs int

количество копий среды.

 required
make_env_kwargs Optional[dict]

kwargs, которые будут переданы в GridWorldEnv(...) для создания каждой копии среды.

 None
base_seed Optional[int]

базовый сид. Используется для генерации КАРТЫ (map_seed).

 None
render_mode Optional[str]

режим рендера для под‑сред ('human' или 'rgb_array').

 None

reset 

reset(seed=None, options=None)

Сбрасывает ВСЕ под‑среды.

ВАЖНО: карта (цвета пола, препятствия) НЕ перегенерируется при reset(). Используется закэшированная карта, созданная при инициализации среды. Это гарантирует, что все эпизоды проходят на идентичной карте.

seed
  • int → используется для стартовых позиций агентов;
  • sequence[int] длины n_envs → отдельный сид для каждой среды.

step 

step(action)
Векторный шаг
  • action: int → одно действие для всех под‑сред;
  • action: np.ndarray shape (n_envs,) → своё действие для каждой.

render 

render()

Тип рендеринга берётся из исходной среды.

VectorGridWorldEnv

Bases: Env

Векторизованная GridWorld‑среда.

Внутри хранится 'n_envs' независимых копий одиночной среды. На каждый шаг подаётся действие для КАЖДОЙ копии (actions[i]), а на выходе возвращаются массивы по всем под‑средам.

Интерфейс шага:

obs, reward, terminated, truncated, info = env.step(actions)

где:

actions: np.ndarray shape (n_envs,) или скаляр int (бродкастится);

obs:        np.ndarray shape (n_envs, single_obs_dim),
reward:     np.ndarray shape (n_envs,), значения step_reward или goal_reward;
terminated: np.ndarray shape (n_envs,), True если env достигла цели;
truncated:  np.ndarray shape (n_envs,), True если превышен лимит шагов;
info: dict с полями:
    - "reward_per_env":      reward;
    - "terminated_per_env":  terminated;
    - "truncated_per_env":   truncated.

Каждый эпизод под‑среды: - начинается в reset(); - заканчивается, когда агент дошёл до цели или превысил лимит шагов.

Векторная логика (движение, коллизии, награды) реализована целиком через numpy.

Параметры награды
  • step_reward: награда/штраф за обычный шаг (по умолчанию 0.0);
  • goal_reward: награда за достижение цели (по умолчанию 1.0).

reset 

reset(seed=None, options=None)

Сбрасывает ВСЕ n_envs копий среды.

ВАЖНО: карта (цвета пола, препятствия) НЕ перегенерируется при reset(). Используется закэшированная карта, созданная при инициализации среды. Это гарантирует, что все эпизоды проходят на идентичной карте.

Возвращает

obs: np.ndarray shape (n_envs, single_obs_dim) info: dict (пока пустой).

step 

step(actions)

Выполняет один векторизованный шаг.

actions
  • int: одно и то же действие для всех envs;
  • или np.ndarray shape (n_envs,) со своими действиями.
Возвращает

obs: (n_envs, single_obs_dim) reward: (n_envs,) float32 terminated: (n_envs,) bool truncated: (n_envs,) bool info: dict с теми же векторами.

render 

render()

(render_mode='human'), (render_mode='rgb_array').