# agi-brain/xuance architecture

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

- Interactive diagram: https://gitdiagram.com/agi-brain/xuance
- Repository: https://github.com/agi-brain/xuance

## Overview

##### Project Type and Purpose
- XuanCe is a full‐featured, open‐source Python library for Deep Reinforcement Learning (DRL) and Multi‐Agent RL (MARL).
- It provides:
- A unified API (xuance.get_runner) for training/testing agents.
- Modular implementations of dozens of single‐agent and multi‐agent algorithms.
- Adapters for three DL backends: PyTorch, TensorFlow2, MindSpore.
- Environment wrappers for Gymnasium, PettingZoo, MuJoCo, etc.
- Hyperparameter tuning, logging (TensorBoard, wandb), parallel & distributed training.

##### High‐Level File‐Structure Analysis
- Top level:
- setup.py, README, examples/, docs/, tests/
- xuance/ – core library package
- xuance/ subpackages:
- common – shared utilities (memory buffers, tuning tools, stats)
- configs – YAML default configs per algorithm/environment
- environment – single & multi‐agent environment wrappers & vector envs
- {mindspore, tensorflow, torch} – per‐backend Agents, Learners, Policies, Runners, Representations, Utils
- __init__.py – entry point exposing get_runner, etc.
- examples/ – runnable scripts demonstrating usage per algorithm
- tests/ – framework‐specific and tuning tests

##### README Insights
- Describes supported algorithms, environments, features.
- Emphasizes modularity, extensibility, multi‐backend compatibility.
- Shows example code: calling get_runner(method, env, env_id, is_test) → runner.run()
- Mentions external services: TensorBoard, wandb, mpi4py.

##### Main Components and Relationships
- User/API Layer:
- User code or example script → calls xuance.get_runner()
- Runner Factory:
- Reads method, env, config → instantiates a Runner object from appropriate backend subpackage.
- Config Loader:
- Merges YAML defaults (xuance/configs and docs/_static/configs) with user overrides.
- Environment Module:
- SingleAgentEnv / MultiAgentEnv (gymnasium, PettingZoo, custom envs)
- VectorEnv orchestrates multiple envs in parallel (dummy or subprocess).
- Agent Abstraction:
- Holds representation (MLP/CNN/RNN), policy (categorical/deterministic/gaussian), memory buffer.
- Learner Abstraction:
- Implements update logic: sample from memory, compute losses, backprop through chosen backend.
- Common Tools:
- Memory buffers (replay, prioritized, on‐policy), tuning tools, statistic tools.
- Hyperparameter Tuner:
- Interfaces with tuning_tools/hyperparameters and external services (WandB, TensorBoard).
- Backend Adapters:
- torch/, tensorflow/, mindspore/ subpackages each implement Agents/Learners/Runners with framework‐specific code.
- Logging & Visualization:
- Logs metrics to local files for TensorBoard, optionally pushes to WandB.
- External Services:
- mpi4py for distributed training, Gym/PettingZoo for environments, DL frameworks.

##### Architectural Patterns & Design Principles
- Factory Pattern: get_runner selects Runner class based on method and backend.
- Strategy Pattern: Agent+Learner pair encapsulates algorithm strategy.
- Adapter Pattern: Separate per‐backend code under torch/, tensorflow/, mindspore/.
- Layered Architecture: clear separation between:
1) API/Runner
2) Config management
3) Environment layer
4) Algorithm core (Agent & Learner)
5) Backend glue
6) Logging & tuning
- Modular & Pluggable: new algorithms, new envs, new backends can be added by following existing package structure.

##### Be Detailed
- Algorithm registration point (method → AlgorithmClass).
- Where configs (YAML) are loaded & applied.
- Multi‐agent vs single‐agent env wrapper difference.
- Parallel env (VectorEnv) and distribution (MPI).
- Per‐backend module boundaries.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Swimlane: API & Factory
    subgraph "API & Factory"
        direction TB
        User["User / Example Script"]:::blue
        API["xuance/__init__.py\n(get_runner)"]:::blue
        RunnerFactory["Runner Factory"]:::blue
    end

    %% Swimlane: Core Library
    subgraph "Core Library"
        direction TB
        ConfigLoader["Config Loader\n(YAML defaults)"]:::green
        subgraph "Environment Module"
            direction TB
            SAEnv["SingleAgentEnv"]:::orange
            MAEnv["MultiAgentEnv"]:::orange
            VecEnv["VectorEnv"]:::orange
        end
        subgraph "Algorithm Core"
            direction TB
            AgentMod["Agent Module"]:::yellow
            LearnerMod["Learner Module"]:::yellow
        end
        subgraph "Common Tools & Memory"
            direction TB
            MemBuf["Memory Buffers"]:::grey
            StatTools["Statistic Tools"]:::grey
        end
    end

    %% Swimlane: Backend Adapters
    subgraph "Backend Adapters"
        direction TB
        TorchAdapter["PyTorch Adapter"]:::red
        TFAdapter["TensorFlow Adapter"]:::red
        MSAdapter["MindSpore Adapter"]:::red
    end

    %% Swimlane: Tools & Services
    subgraph "Tools & Services"
        direction TB
        HPTuner["Hyperparameter Tuner"]:::purple
        Logging["Logging & Visualization"]:::teal
        MPI["mpi4py (Distributed)"]:::pink
    end

    %% Connections
    User -->|calls get_runner| API
    API -->|instantiate runner| RunnerFactory
    RunnerFactory -->|load config| ConfigLoader
    RunnerFactory -->|create env| SAEnv
    RunnerFactory -->|create env| MAEnv
    RunnerFactory -->|create env| VecEnv
    RunnerFactory -->|create agent| AgentMod
    RunnerFactory -->|create learner| LearnerMod

    SAEnv -->|obs| AgentMod
    MAEnv -->|obs| AgentMod
    VecEnv -->|obs batch| AgentMod

    AgentMod -->|store transition| MemBuf
    AgentMod -->|log stats| StatTools

    AgentMod -->|action| SAEnv
    AgentMod -->|action| MAEnv
    AgentMod -->|action| VecEnv

    LearnerMod -->|sample| MemBuf
    LearnerMod -->|update| StatTools
    LearnerMod -->|compute graph| TorchAdapter
    LearnerMod -->|compute graph| TFAdapter
    LearnerMod -->|compute graph| MSAdapter

    RunnerFactory -->|iterate experiments| HPTuner
    HPTuner -->|update config| RunnerFactory

    RunnerFactory -->|log metrics| Logging
    RunnerFactory -->|distributed train| MPI

    %% Click Events
    click API "https://github.com/agi-brain/xuance/blob/master/xuance/__init__.py"
    click RunnerFactory "https://github.com/agi-brain/xuance/tree/master/xuance/torch/runners"
    click ConfigLoader "https://github.com/agi-brain/xuance/tree/master/xuance/configs/"
    click SAEnv "https://github.com/agi-brain/xuance/tree/master/xuance/environment/single_agent_env/"
    click MAEnv "https://github.com/agi-brain/xuance/tree/master/xuance/environment/multi_agent_env/"
    click VecEnv "https://github.com/agi-brain/xuance/tree/master/xuance/environment/vector_envs/"
    click TorchAdapter "https://github.com/agi-brain/xuance/tree/master/xuance/torch/"
    click TFAdapter "https://github.com/agi-brain/xuance/tree/master/xuance/tensorflow/"
    click MSAdapter "https://github.com/agi-brain/xuance/tree/master/xuance/mindspore/"
    click MemBuf "https://github.com/agi-brain/xuance/blob/master/xuance/common/memory_tools.py"
    click StatTools "https://github.com/agi-brain/xuance/blob/master/xuance/common/statistic_tools.py"
    click HPTuner "https://github.com/agi-brain/xuance/blob/master/xuance/common/tuning_tools/tuning_tool.py"

    %% Styles
    classDef blue fill:#AED6F1,stroke:#1F618D,color:#1B2631
    classDef green fill:#ABEBC6,stroke:#1D8348,color:#145A32
    classDef orange fill:#F5CBA7,stroke:#BA4A00,color:#873600
    classDef yellow fill:#FCF3CF,stroke:#B7950B,color:#7D6608
    classDef grey fill:#D5D8DC,stroke:#626567,color:#1C2833
    classDef purple fill:#D7BDE2,stroke:#76448A,color:#4A235A
    classDef teal fill:#A9DFBF,stroke:#117A65,color:#0E6251
    classDef pink fill:#F5B7B1,stroke:#922B21,color:#641E16
    classDef red fill:#F1948A,stroke:#C0392B,color:#78281F
```
