# sarkarsaswata/booster_soccer_showdown architecture

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

- Interactive diagram: https://gitdiagram.com/sarkarsaswata/booster_soccer_showdown
- Repository: https://github.com/sarkarsaswata/booster_soccer_showdown

## Overview

##### Project type and purpose
- This is a robotics competition framework and research toolkit, combining:
- Teleoperation interface (“booster_control/”)
- Motion replay & analysis tools (“mimic/”)
- Imitation Learning algorithms (“imitation_learning/”)
- Reinforcement Learning training scripts (“training_scripts/”)
- It integrates MuJoCo environments via the SAI client, supports data collection, offline imitation, and online policy learning (DDPG).

##### File structure
- Top-level packages:
- booster_control/: keyboard teleop scripts + utilities
- mimic/: forward kinematics & visualization, assets (MuJoCo XML & meshes)
- imitation_learning/: agent implementations (BC, IQL, GCBC, etc.), data collection & preprocessing, training & evaluation utils, submission stubs
- training_scripts/: standalone DDPG implementation (model, buffer, training loop), main entrypoint, test harness
- Resources/requirements:
- requirements.txt (Python ≥3.10 + MuJoCo, JAX, PyTorch, SAI SDK)
- resources/: competition banner, config files
- External dependencies:
- Hugging Face (datasets & model hosting)
- SAI competition platform (env server & API)

##### README for additional insights
- Describes:
- Teleop usage & commands
- Mimic scripts arguments & workflows
- Training workflow: DDPG model, Preprocessor, SAI client integration
- Test & benchmarking post-training

##### Main components & interactions
a. Components
1. Teleoperation Module
– CLI script: booster_control/teleoperate.py
– Utilities (se3_keyboard, t1_utils)
2. Simulation Environment & Asset Store
– SAI Client ↔ MuJoCo Engine
– mimic/assets/booster_t1 XML + meshes
3. Data Flow & Storage
– Raw motion files (.npz) from Hugging Face
– Local dataset folder / imitation_learning/scripts/collect_data.py
4. Mimic Module
– forward_kinematics.py → computes derived signals
– visualize_data.py → replays motion in viewer
5. Imitation Learning Module
– Agents (bc, iql, gciql, etc.)
– Preprocessor & networks (utils/networks.py, flax_utils.py)
– Training & evaluation scripts (train.py, test.py)
– Submission tools (submission/model.py, model.pt, submit_sai.py)
6. Reinforcement Learning Module
– DDPG model (training_scripts/ddpg.py)
– ReplayBuffer & training loop (training_scripts/training.py)
– Main entrypoint & environment init (training_scripts/main.py)
– Test harness (training_scripts/test.py)
7. External Services
– Hugging Face (dataset & model hub)
– SAI competition API for environment instantiation, watch, benchmark

b. Relationships & data flows
1. Teleop → SAI Client → MuJoCo → live control → optional data recording → raw motion files
2. Raw motion files → Mimic Module → enriched kinematics → npz outputs
3. Raw motion files → Imitation Learning scripts (collect_data.py → preprocessor) → algorithmic agents → trained IL models → submission scripts
4. SAI Client → RL Training main.py → Preprocessor → DDPG Model → environment interaction → ReplayBuffer → training loop → saved RL checkpoint → optional watch/benchmark calls back to SAI
5. All modules may read/write to local disk or remote Hugging Face storage

c. Architectural patterns & design principles
– Modular Python packages, each with clear responsibility
– CLI-driven entrypoints for each workflow (teleop, mimic, IL, RL)
– Use of external services for data/model hosting (Hugging Face) and env access (SAI)
– Separation of concerns: data collection, offline processing, algorithmic training, inference/teleop

d. Key technologies/frameworks
– Python ≥3.10
– MuJoCo via SAI client
– JAX & Flax (imitation_learning)
– PyTorch (via jax2torch conversion script & RL training)
– SAI SDK (env instantiation, watch, benchmark)
– Hugging Face Datasets & Model Hub

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Teleoperation Module
    subgraph "Teleoperation Module"
        direction TB
        Teleop["teleoperate.py"]:::teleop
        SE3["se3_keyboard.py"]:::teleop
        T1Utils["t1_utils.py"]:::teleop
    end

    %% Simulation Environment & Asset Store
    subgraph "Simulation & Assets"
        direction TB
        SAIClient["SAI Client"]:::external
        MuJoCo["MuJoCo Engine"]:::external
        subgraph "Assets"
            direction TB
            BoosterXML["booster_t1.xml"]:::mimic
            BoosterLowerXML["booster_lower_t1.xml"]:::mimic
            Meshes["meshes/"]:::mimic
            CommonScene["scene.xml"]:::mimic
            CommonSites["mimic_sites.xml"]:::mimic
        end
    end

    %% Data Flow & Storage
    subgraph "Data Storage"
        direction TB
        LocalDisk["Local Disk"]:::data
        HuggingFaceStore["Hugging Face"]:::external
        CollectData["collect_data.py"]:::il
    end

    %% Mimic Module
    subgraph "Mimic Module"
        direction TB
        ForwardKin["forward_kinematics.py"]:::mimic
        Visualize["visualize_data.py"]:::mimic
    end

    %% Imitation Learning Module
    subgraph "Imitation Learning Module"
        direction TB
        BC["bc.py"]:::il
        IQL["iql.py"]:::il
        GCBC["gcbc.py"]:::il
        GCIQL["gciql.py"]:::il
        HIQL["hiql.py"]:::il
        Preprocessor["preprocessor.py"]:::il
        Jax2Torch["jax2torch.py"]:::il
        TrainIL["train.py"]:::il
        TestIL["test.py"]:::il
        Networks["networks.py"]:::il
        FlaxUtils["flax_utils.py"]:::il
        ILModel["model.py"]:::il
        SubmitSAI["submit_sai.py"]:::il
        ModelPT["model.pt"]:::il
    end

    %% Reinforcement Learning Module
    subgraph "Reinforcement Learning Module"
        direction TB
        MainRL["main.py"]:::rl
        DDPG["ddpg.py"]:::rl
        TrainingRL["training.py"]:::rl
        TestRL["test.py"]:::rl
    end

    %% External Services
    SAI_API["SAI Competition API"]:::external
    HFCloud["Hugging Face Datasets & Hub"]:::external

    %% Connections
    Teleop -->|Control| SAIClient
    SAIClient -->|Simulate| MuJoCo
    Teleop -->|Record| LocalDisk
    LocalDisk -->|Raw .npz| ForwardKin
    ForwardKin -->|Enriched .npz| LocalDisk
    LocalDisk -->|Raw .npz| CollectData
    CollectData --> Preprocessor
    Preprocessor --> BC & IQL & GCBC & GCIQL & HIQL
    BC & IQL & GCBC & GCIQL & HIQL --> TrainIL
    TrainIL --> ILModel
    ILModel --> SubmitSAI
    SubmitSAI --> SAI_API

    SAIClient -->|Env Init| MainRL
    MainRL --> DDPG
    DDPG --> TrainingRL
    TrainingRL --> LocalDisk
    TrainingRL -->|Checkpoint| LocalDisk
    TrainingRL --> TestRL
    TestRL --> SAI_API

    LocalDisk --> HFCloud
    HFCloud --> CollectData
    HFCloud -->|Model Hosting| ILModel

    %% Click Events - Teleoperation
    click Teleop "https://github.com/sarkarsaswata/booster_soccer_showdown/blob/main/booster_control/teleoperate.py"
    click SE3 "https://github.com/sarkarsaswata/booster_soccer_showdown/blob/main/booster_control/se3_keyboard.py"
    click T1Utils "https://github.com/sarkarsaswata/booster_soccer_showdown/blob/main/booster_control/t1_utils.py"

    %% Click Events - Simulation Assets
    click BoosterXML "https://github.com/sarkarsaswata/booster_soccer_showdown/blob/main/mimic/assets/booster_t1/booster_t1.xml"
    click BoosterLowerXML "https://github.com/sarkarsaswata/booster_soccer_showdown/blob/main/mimic/assets/booster_t1/booster_lower_t1.xml"
    click Meshes "https://github.com/sarkarsaswata/booster_soccer_showdown/tree/main/mimic/assets/booster_t1/meshes/"
    click CommonScene "https://github.com/sarkarsaswata/booster_soccer_showdown/blob/main/mimic/assets/common/scene.xml"
    click CommonSites "https://github.com/sarkarsaswata/booster_soccer_showdown/blob/main/mimic/assets/common/mimic_sites.xml"

    %% Click Events - Data Storage
    click CollectData "https://github.com/sarkarsaswata/booster_soccer_showdown/blob/main/imitation_learning/scripts/collect_data.py"

    %% Click Events - Mimic Module
    click ForwardKin "https://github.com/sarkarsaswata/booster_soccer_showdown/blob/main/mimic/forward_kinematics.py"
    click Visualize "https://github.com/sarkarsaswata/booster_soccer_showdown/blob/main/mimic/visualize_data.py"

    %% Click Events - Imitation Learning Module
    click BC "https://github.com/sarkarsaswata/booster_soccer_showdown/blob/main/imitation_learning/agents/bc.py"
    click IQL "https://github.com/sarkarsaswata/booster_soccer_showdown/blob/main/imitation_learning/agents/iql.py"
    click GCBC "https://github.com/sarkarsaswata/booster_soccer_showdown/blob/main/imitation_learning/agents/gcbc.py"
    click GCIQL "https://github.com/sarkarsaswata/booster_soccer_showdown/blob/main/imitation_learning/agents/gciql.py"
    click HIQL "https://github.com/sarkarsaswata/booster_soccer_showdown/blob/main/imitation_learning/agents/hiql.py"
    click Preprocessor "https://github.com/sarkarsaswata/booster_soccer_showdown/blob/main/imitation_learning/scripts/preprocessor.py"
    click Jax2Torch "https://github.com/sarkarsaswata/booster_soccer_showdown/blob/main/imitation_learning/scripts/jax2torch.py"
    click TrainIL "https://github.com/sarkarsaswata/booster_soccer_showdown/blob/main/imitation_learning/train.py"
    click TestIL "https://github.com/sarkarsaswata/booster_soccer_showdown/blob/main/imitation_learning/test.py"
    click Networks "https://github.com/sarkarsaswata/booster_soccer_showdown/blob/main/imitation_learning/utils/networks.py"
    click FlaxUtils "https://github.com/sarkarsaswata/booster_soccer_showdown/blob/main/imitation_learning/utils/flax_utils.py"
    click ILModel "https://github.com/sarkarsaswata/booster_soccer_showdown/blob/main/imitation_learning/submission/model.py"
    click SubmitSAI "https://github.com/sarkarsaswata/booster_soccer_showdown/blob/main/imitation_learning/submission/submit_sai.py"
    click ModelPT "https://github.com/sarkarsaswata/booster_soccer_showdown/blob/main/imitation_learning/submission/model.pt"

    %% Click Events - Reinforcement Learning Module
    click MainRL "https://github.com/sarkarsaswata/booster_soccer_showdown/blob/main/training_scripts/main.py"
    click DDPG "https://github.com/sarkarsaswata/booster_soccer_showdown/blob/main/training_scripts/ddpg.py"
    click TrainingRL "https://github.com/sarkarsaswata/booster_soccer_showdown/blob/main/training_scripts/training.py"
    click TestRL "https://github.com/sarkarsaswata/booster_soccer_showdown/blob/main/training_scripts/test.py"

    %% Styles
    classDef teleop fill:#98FB98,stroke:#2E8B57,stroke-width:2px
    classDef mimic fill:#ADD8E6,stroke:#1E90FF,stroke-width:2px
    classDef il fill:#FFA500,stroke:#FF8C00,stroke-width:2px
    classDef rl fill:#DDA0DD,stroke:#9370DB,stroke-width:2px
    classDef data fill:#D3D3D3,stroke:#696969,stroke-width:2px
    classDef external fill:#F0E68C,stroke:#B8860B,stroke-width:2px,nodeShape:cloud
```
