# opendilab/lightzero architecture

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

- Interactive diagram: https://gitdiagram.com/opendilab/lightzero
- Repository: https://github.com/opendilab/lightzero

## Overview

##### Project Type and Purpose
- LightZero is an algorithm toolkit/library for reinforcement learning using MCTS (with a focus on algorithms like AlphaZero, MuZero, EfficientZero, among others).
- The toolkit is aimed at researchers and practitioners who want to train and benchmark various MCTS+RL algorithms, quickly switch between environments, and understand how algorithm components interact.
- The README emphasizes modularity, efficiency, clarity, and support for multiple environments (board games, Atari, continuous control tasks, etc.). It also displays performance benchmarks and research paper documentation.

##### File Structure
- The top-level directories include:
- “lzero” (the core algorithm code) which contains subdirectories for agents, configurations, and model definitions.
- “docs” for documentation, tutorials, and API references.
- “zoo” which houses a variety of experimental environments along with configuration files for benchmark tests.
- Within “lzero”, you see modules like “agent”, “model”, “policy”, “mcts” (and its submodules “ctree” [C++ implementation] and “ptree”), “envs”, “config”, and “worker”. This is a strong indicator of the high modular design based on the separation of concerns (i.e., clearly divided responsibilities for model definition, decision making, tree search, and environment interaction).
- Configuration files (like setup.py, Dockerfile, Makefile) and CI/CD workflows in “.github/workflows” show support for automated testing/deployment.

##### Main Components and Their Interactions
- Core Modules:
- Model: Responsible for defining network architectures (found in lzero/model).
- Policy: Contains the learning, collecting, and evaluation strategy (lzero/policy).
- MCTS: Implemented as two parts:
- Python-based tree search (ptree inside lzero/mcts/ptree),
- C++ and cython accelerated search (ctree inside lzero/mcts/ctree).
- Agent: Orchestrates the interaction between the model, policy, and MCTS (lzero/agent).
- Worker: May handle data collection and evaluation in parallel (lzero/worker).
- Utility Modules:
- Config: For managing algorithm configuration (lzero/agent/config and lzero/config).
- Environments: Wrappers and tests for varied tasks (lzero/envs and zoo/… directories).
- External & Cross-cutting Concerns:
- Documentation & Benchmarking: “docs”, “assets”, and “zoo” directories also interact with the core modules.
- Deployment & Testing: Docker configuration, GitHub workflows, and CI tests ensure production-readiness.
- Integration with PyTorch and C++ modules for efficient computation.

##### Architectural Patterns and Design Principles
- Modularity & Layering: The design follows clear separation where each module (Model, Policy, MCTS, Agent, Config, Worker) is its own component, interacting through clearly defined interfaces.
- Heterogeneous Computing: Notice the integration of Python with C++ (via cython in “ctree”) to accelerate MCTS computations.
- Extensibility: With many configurations and environment adapters provided (as seen in the “zoo” directory), the system is designed to be extended for new environments and algorithm variations.

- Clear component labels (e.g., “Model”, “Policy”, “Agent”, “MCTS – Python”, “MCTS – C++”, “Config”, “Environment Wrappers”).
– From the Environment (zoo/config/envs) to Agent.
– From Agent to Policy and Model.
– From MCTS to Policy (feedback loop), and back to Agent.
– From Config components to all modules indicating external configuration propagation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Inputs
    subgraph "External Inputs"
        ENV1["Environment Wrappers"]:::env
        ENV2["Experimental Environments"]:::env
    end

    %% Documentation
    subgraph "Documentation"
        DOCS["Docs & Tutorials"]:::doc
        ASSETS["Assets & Visuals"]:::doc
    end

    %% Supporting Modules
    subgraph "Supporting Modules"
        CONFIG["Configuration"]:::support
        WORKER["Worker"]:::support
    end

    %% Core Modules
    subgraph "Core Modules"
        MODEL["Model"]:::core
        POLICY["Policy"]:::core
        MCTS_PY["MCTS - Python"]:::core
        MCTS_CPP["MCTS - C++"]:::core
    end

    %% Central Orchestrator
    AGENT["Agent"]:::support

    %% Connections from External Inputs to Agent
    ENV1 -->|"feed"| AGENT
    ENV2 -->|"feed"| AGENT

    %% Configuration flows into key modules
    CONFIG -->|"set"| AGENT
    CONFIG -->|"set"| MODEL
    CONFIG -->|"set"| POLICY
    CONFIG -->|"set"| MCTS_PY
    CONFIG -->|"set"| MCTS_CPP
    CONFIG -->|"set"| WORKER

    %% Agent invokes core modules
    AGENT -->|"invoke"| MODEL
    AGENT -->|"invoke"| POLICY
    AGENT -->|"invoke"| MCTS_PY
    AGENT -->|"invoke"| MCTS_CPP

    %% Worker sends data to Agent
    WORKER -->|"data"| AGENT

    %% Feedback loop from MCTS to Policy
    MCTS_PY -->|"feedback"| POLICY
    MCTS_CPP -->|"feedback"| POLICY

    %% Optional connection: Documentation influences Configuration
    DOCS ---|"guide"| CONFIG
    ASSETS ---|"reference"| CONFIG

    %% Styling Classes
    classDef core fill:#f6d5b5,stroke:#333,stroke-width:2px;
    classDef support fill:#b5d3f6,stroke:#333,stroke-width:2px;
    classDef env fill:#d5f6b5,stroke:#333,stroke-width:2px;
    classDef doc fill:#f6b5d5,stroke:#333,stroke-width:2px;

    %% Click Events for Component Mapping
    click MODEL "https://github.com/opendilab/lightzero/tree/main/lzero/model"
    click POLICY "https://github.com/opendilab/lightzero/tree/main/lzero/policy"
    click MCTS_PY "https://github.com/opendilab/lightzero/tree/main/lzero/mcts/ptree"
    click MCTS_CPP "https://github.com/opendilab/lightzero/tree/main/lzero/mcts/ctree"
    click AGENT "https://github.com/opendilab/lightzero/tree/main/lzero/agent"
    click WORKER "https://github.com/opendilab/lightzero/tree/main/lzero/worker"
    click CONFIG "https://github.com/opendilab/lightzero/tree/main/lzero/config"
    click ENV1 "https://github.com/opendilab/lightzero/tree/main/lzero/envs"
    click ENV2 "https://github.com/opendilab/lightzero/tree/main/zoo"
    click DOCS "https://github.com/opendilab/lightzero/tree/main/docs"
    click ASSETS "https://github.com/opendilab/lightzero/tree/main/assets"
```
