API: Вспомогательные функции
utils
Вспомогательные функции для GridWorld.
Содержит: - generate_walls — генерация маски препятствий; - save_episode_gif — запись GIF по одному эпизоду.
generate_walls
generate_obstacle_mask
Генерирует булеву матрицу препятствий 'obstacle_mask' размера '(h, w)' c заданной долей 'True' (препятствий) и гарантированным путём между двумя точками при движении по 4‑связности (вверх/вниз/влево/вправо).
Путь обеспечивается тем, что между 'start' и 'goal' строится простая монотонная "манхэттенская" траектория, и клетки этой траектории никогда не помечаются как препятствия.
Координаты 'start' и 'goal' задаются в системе внутренних клеток маски: '(row, col)' в диапазоне '[0, h-1] × [0, w-1]'.
Parameters
int
Высота маски (количество строк).
w : int Ширина маски (количество столбцов). obstacle_ratio : float Желаемая доля препятствий (значений True) в [0.0, 1.0]. Фактическая доля может быть чуть меньше, так как клетки пути не могут быть препятствиями. start : Tuple[int, int] Начальная точка пути (row, col). goal : Tuple[int, int] Конечная точка пути (row, col). rng : np.random.Generator, optional Генератор случайных чисел. Если None — создаётся новый.
Returns
np.ndarray Булева матрица формы '(h, w)', где 'True' — препятствие.
save_episode_gif
Сохраняет GIF одного эпизода, визуализируя поведение агента в среде 'env' с использованием политики из 'model'.
Функция пошагово выполняет эпизод, делая шаги в среде на основе действий, предсказанных моделью, и сохраняет каждый кадр в анимированное GIF-изображение. Поддерживаются как обычные, так и векторизованные среды (несколько параллельных сред), а также модели с рекуррентными архитектурами (например, LSTMs/GRUs).
Поддерживаемые типы моделей: - Модели с методом 'act_greedy' (например, A2CAgent, DRQNLightning). - Модели с атрибутом 'net' (например, 'DQNAgent'). - "Чистые" PyTorch-модели, выводящие логиты действий.
Поддерживаемые типы сред: - 'GridWorldEnv' с методом 'render_map()'. - Векторизованные среды с '_render_map(return_rgb_array=True)'. - Любые среды, реализующие 'render()' и возвращающие массив изображения.
Аргументы
env: Среда Gym/Gymnasium. Должна поддерживать 'reset()' и 'step()'. model: Модель или агент, способный предсказывать действия. filename (str): Имя файла для сохранения GIF (по умолчанию "episode.gif"). fps (int): Частота кадров в GIF (по умолчанию 2 кадра в секунду). max_frames (int): Максимальное количество кадров в эпизоде. hold_last (int): Сколько раз продублировать последний кадр при успехе.
Возвращает
bool: 'True', если хотя бы одно состояние 'terminated=True' было встретено. 'False', если эпизод завершился по 'truncated' или 'max_frames'.
Исключения
RuntimeError: Если не удалось создать ни одного кадра. AttributeError: Если среда не поддерживает ни один из методов визуализации. ValueError: Если размерности наблюдений не соответствуют ожидаемым.