# farama-foundation/gymnasium architecture

> Architecture diagram of the GitHub repository farama-foundation/gymnasium, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/farama-foundation/gymnasium
- Repository: https://github.com/farama-foundation/gymnasium

## Overview

##### Main Components
- Core API Layer
– gymnasium/core.py: defines the `Env` interface, `make()`, `register()`, `EnvSpec`, etc.
– gymnasium/registration.py: maintains the environment registry.
- Environment Implementations
– gymnasium/envs/…: folders for classic_control, box2d, mujoco, toy_text, atari (third-party).
– Each env module implements `Env` subclasses, assets, rendering, physics-engine bindings.
- Space Definitions
– Describes state/action spaces for environments.
- Vectorization
– gymnasium/vector: AsyncVectorEnv, SyncVectorEnv, shared-memory utils.
– Enables parallel/multi-process rollouts.
- Wrappers
– gymnasium/wrappers + gymnasium/wrappers/vector: pre/post processors for observations, actions, rewards, rendering.
- Utilities
– gymnasium/utils: seeding, recording, performance checks, conversions, passive/environment checker, video save.
- External Engine Integrations
– Box2D (PyGame-based physics), MuJoCo (mujoco-py bindings), Atari (ALE emulator), JAX (functional environments), Torch conversions.
- CLI / Packaging
– bin/docker_entrypoint, Dockerfiles: containerization.
– setup.py / pyproject.toml: packaging/publishing.
- Documentation & Tutorials
- Testing & CI/CD
– tests/: unit/integration tests for every component.
– .github/workflows: pre-commit, pytest, docs-build, PyPI publish.

##### Relationships and Data Flows
- User Code → Gymnasium API → Registration → Environment Instance →
- (Action) → Wrapper Chain → (Action) → Underlying Env Implementation → Physics/RL Engine →
- (Observation/Reward) ← Wrapper Chain ← Underlying Env.
- VectorEnv multiplexes multiple Env Instances, merging/separating batched obs/actions via shared memory or IPC.
- Spaces are referenced by both API and Env Implementations to validate inputs/outputs.
- Utils modules are invoked at various points (seeding at reset, recording during step, environment checker on make).
- CI/CD pipeline monitors code, runs tests, builds docs, publishes to PyPI; docs-build uses docs/_scripts for asset generation.

##### Architectural Patterns
- Factory/Registry for environment creation (gym.make)
- Decorator Pattern for wrappers (wrappers wrap Env subclasses)
- Adapter Pattern for external engine bindings (MuJoCoEnv, Box2DEnv, ALEEnv)
- Parallelism via vectorization (strategy pattern: sync vs. async)
- Modular plugin-style structure: new env families or wrappers drop into `gymnasium/envs` or `gymnasium/wrappers`.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layers
    subgraph "Layer 1: User Application"
        direction TB
        UserApp["User Application"]
    end

    subgraph "Layer 2: Gymnasium API & Registry"
        direction TB
        CoreAPI["Core API\n(gymnasium/core.py)"]:::core
        click CoreAPI "https://github.com/farama-foundation/gymnasium/blob/main/gymnasium/core.py"
        RegistryAPI["Env Registry\n(gymnasium/registration.py)"]:::core
        click RegistryAPI "https://github.com/farama-foundation/gymnasium/blob/main/gymnasium/registration.py"
        EnvRegImpl["Env Registry Impl\n(gymnasium/envs/registration.py)"]:::core
        click EnvRegImpl "https://github.com/farama-foundation/gymnasium/blob/main/gymnasium/envs/registration.py"
    end

    subgraph "Layer 3: Modules" 
        direction TB

        subgraph "Env Families" 
            direction TB
            Classic["Classic Control"]:::envfam
            click Classic "https://github.com/farama-foundation/gymnasium/tree/main/gymnasium/envs/classic_control/"
            Box2D["Box2D"]:::envfam
            click Box2D "https://github.com/farama-foundation/gymnasium/tree/main/gymnasium/envs/box2d/"
            MuJoCo["MuJoCo"]:::envfam
            click MuJoCo "https://github.com/farama-foundation/gymnasium/tree/main/gymnasium/envs/mujoco/"
            ToyText["Toy Text"]:::envfam
            click ToyText "https://github.com/farama-foundation/gymnasium/tree/main/gymnasium/envs/toy_text/"
            Tabular["Tabular"]:::envfam
            click Tabular "https://github.com/farama-foundation/gymnasium/tree/main/gymnasium/envs/tabular/"
            FuncJAX["Functional JAX Env"]:::envfam
            click FuncJAX "https://github.com/farama-foundation/gymnasium/blob/main/gymnasium/envs/functional_jax_env.py"
        end

        subgraph "Wrappers" 
            direction TB
            SingleWrap["Single-Env Wrappers"]:::wrap
            click SingleWrap "https://github.com/farama-foundation/gymnasium/tree/main/gymnasium/wrappers/"
            VecWrap["Vectorized Wrappers"]:::wrap
            click VecWrap "https://github.com/farama-foundation/gymnasium/tree/main/gymnasium/wrappers/vector/"
        end

        subgraph "Vectorization" 
            direction TB
            AsyncEnv["AsyncVectorEnv"]:::wrap
            click AsyncEnv "https://github.com/farama-foundation/gymnasium/blob/main/gymnasium/vector/async_vector_env.py"
            SyncEnv["SyncVectorEnv"]:::wrap
            click SyncEnv "https://github.com/farama-foundation/gymnasium/blob/main/gymnasium/vector/sync_vector_env.py"
            BaseVec["VectorEnv Base"]:::wrap
            click BaseVec "https://github.com/farama-foundation/gymnasium/blob/main/gymnasium/vector/vector_env.py"
            VecUtils["Vector Utils"]:::wrap
            click VecUtils "https://github.com/farama-foundation/gymnasium/tree/main/gymnasium/vector/utils/"
        end

        subgraph "Spaces & Utils"
            direction TB
            Spaces["Spaces\n(gymnasium/spaces/)"]:::util
            click Spaces "https://github.com/farama-foundation/gymnasium/tree/main/gymnasium/spaces/"
            Utils["Utilities\n(gymnasium/utils/)"]:::util
            click Utils "https://github.com/farama-foundation/gymnasium/tree/main/gymnasium/utils/"
        end
    end

    subgraph "Layer 4: External Engine Integrations"
        direction TB
        subgraph Engines 
            direction TB
            MJPyEnv["MuJoCo Py Env"]:::ext
            click MJPyEnv "https://github.com/farama-foundation/gymnasium/blob/main/gymnasium/envs/mujoco/mujoco_py_env.py"
            MJEnv["MuJoCo Env"]:::ext
            click MJEnv "https://github.com/farama-foundation/gymnasium/blob/main/gymnasium/envs/mujoco/mujoco_env.py"
            Box2DEnv["Box2D Env"]:::ext
            click Box2DEnv "https://github.com/farama-foundation/gymnasium/tree/main/gymnasium/envs/box2d/"
            ALE["Atari (ALE)"]:::ext
            click ALE "https://github.com/farama-foundation/gymnasium/tree/main/docs/environments/atari/"
        end
    end

    subgraph "Layer 5: CI/CD & Documentation"
        direction TB
        subgraph CI/CD
            direction TB
            Tests["Tests\n(tests/)"]:::ci
            click Tests "https://github.com/farama-foundation/gymnasium/tree/main/tests/"
            Workflows["GitHub Workflows\n(.github/workflows/)"]:::ci
            click Workflows "https://github.com/farama-foundation/gymnasium/blob/main/.github/workflows/docs-build-dev.yml"
        end
        subgraph Docs
            direction TB
            Conf["Sphinx Config\n(docs/conf.py)"]:::ci
            click Conf "https://github.com/farama-foundation/gymnasium/blob/main/docs/conf.py"
            APIRef["API Docs\n(docs/api/)"]:::ci
            click APIRef "https://github.com/farama-foundation/gymnasium/tree/main/docs/api/"
            EnvsDocs["Env Docs\n(docs/environments/)"]:::ci
            click EnvsDocs "https://github.com/farama-foundation/gymnasium/tree/main/docs/environments/"
            Tutorials["Tutorials\n(docs/tutorials/)"]:::ci
            click Tutorials "https://github.com/farama-foundation/gymnasium/tree/main/docs/tutorials/"
            Scripts["Doc Scripts\n(docs/_scripts/)"]:::ci
            click Scripts "https://github.com/farama-foundation/gymnasium/tree/main/docs/_scripts/"
        end
        subgraph Packaging
            direction TB
            DockerEntry["Docker Entrypoint\n(bin/docker_entrypoint)"]:::ci
            click DockerEntry "https://github.com/farama-foundation/gymnasium/tree/main/bin/docker_entrypoint"
            DockerAll["All Python Dockerfile\n(bin/all-py.Dockerfile)"]:::ci
            click DockerAll "https://github.com/farama-foundation/gymnasium/blob/main/bin/all-py.Dockerfile"
            DockerNec["Minimal Dockerfile\n(bin/necessary-py.Dockerfile)"]:::ci
            click DockerNec "https://github.com/farama-foundation/gymnasium/blob/main/bin/necessary-py.Dockerfile"
            Setup["setup.py\npyproject.toml"]:::ci
            click Setup "https://github.com/farama-foundation/gymnasium/blob/main/setup.py"
        end
    end

    %% Connections
    UserApp -->|"calls"| CoreAPI
    CoreAPI -->|"uses"| RegistryAPI
    RegistryAPI -->|"delegates"| EnvRegImpl
    CoreAPI -->|"validates with"| Spaces
    CoreAPI -->|"invokes"| Utils
    CoreAPI -->|"applies"| SingleWrap
    CoreAPI -->|"applies"| VecWrap
    SingleWrap -->|"wraps"| Classic
    SingleWrap -->|"wraps"| Box2D
    SingleWrap -->|"wraps"| MuJoCo
    VecWrap -->|"wraps"| AsyncEnv
    VecWrap -->|"wraps"| SyncEnv
    AsyncEnv -->|"manages"| Classic
    SyncEnv -->|"manages"| Classic
    CoreAPI -->|"creates"| BaseVec
    BaseVec -->|"uses"| VecUtils

    Classic -->|"adapts to"| Box2DEnv
    Box2D -->|"adapts to"| Box2DEnv
    MuJoCo -->|"adapts to"| MJPyEnv
    MJPyEnv -->|"binding"| MJEnv
    ALE -->|"exposed via"| RegistryAPI

    CoreAPI -->|"vectors via"| AsyncEnv
    CoreAPI -->|"vectors via"| SyncEnv

    CI/CD -->|"runs tests on"| Tests
    CI/CD -->|"builds docs with"| Conf
    CI/CD -->|"publishes to"| Setup

    %% Styles
    classDef core fill:#AED6F1,stroke:#21618C,color:#1B2631
    classDef envfam fill:#ABEBC6,stroke:#1D8348,color:#145A32
    classDef wrap fill:#F5CBA7,stroke:#B9770E,color:#784212
    classDef util fill:#A3E4D7,stroke:#138D75,color:#0E6251
    classDef ext fill:#D2B4DE,stroke:#7D3C98,color:#4A235A
    classDef ci fill:#D5DBDB,stroke:#566573,color:#1C2833
```
