# xiong5heng/gopt architecture

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

- Interactive diagram: https://gitdiagram.com/xiong5heng/gopt
- Repository: https://github.com/xiong5heng/gopt

## Overview

##### Project Type and Purpose
- GOPT is a research codebase that implements a deep‐reinforcement‐learning (DRL) solution for online 3D bin‐packing.
- It uses a custom “Packing” environment and a Transformer‐based policy network, built on top of PyTorch and the Tianshou RL library.

##### File Structure
- Top‐level scripts:
- ts_train.py – starts training
- ts_test.py – runs evaluation and optional rendering
- arguments.py, tools.py – parsing command lines, helper routines
- model.py – defines the Transformer policy
- masked_a2c.py / masked_ppo.py – wrappers for specific algorithms
- mycollector.py – custom data collector for Tianshou
- render.py – visualization code
- Configuration:
- cfg/config.yaml & cfg/default.yaml – all hyperparameters (env name, bin size, learning rates)
- Custom Environment:
- Vendored Tianshou library:
- tianshou/… – data buffers, policies, trainers, utilities

##### Key Technologies and Layers
- Configuration layer (YAML files + arguments.py)
- Environment layer (envs/Packing)
- Policy/model layer (model.py + Tianshou policy classes)
- Data collection & replay buffers (mycollector.py + tianshou/data/buffer)
- Trainer layer (tianshou/trainer + ts_train.py)
- Evaluation & rendering (ts_test.py + render.py)
- External frameworks: PyTorch, Tianshou, optional Ray for parallel envs

##### Main Components and Their Interactions
a. Configuration Loader
- Reads cfg/config.yaml
- Feeds parameters to environment, model, trainer
b. Environment Component
- Wraps into Tianshou Gym-style envs
c. Policy (Transformer)
- model.py defines architecture
- Uses features from env (bin state, item state)
d. Data Collector
- mycollector.py interacts policy and env to gather experiences
- Sends data to Tianshou’s replay buffer
e. Replay Buffer & Sampling
- tianshou/data/buffer handles prioritized or standard buffer
f. Trainer
- tianshou/trainer/onpolicy or offpolicy updates the policy
g. Evaluation & Rendering
- ts_test.py runs episodes with trained policy
- render.py shows 3D packing sequence
h. Scripts
- ts_train.py ties config → env → collector → trainer
- ts_test.py ties config → env → policy → renderer

- Optional: annotate the scripts (ts_train.py, ts_test.py) that orchestrate each flow

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Configuration Loader
    subgraph "Configuration Loader"
        ConfigYAML["config.yaml"]:::code
        DefaultYAML["default.yaml"]:::code
        Args["arguments.py"]:::code
    end

    %% Environment Component
    subgraph "Environment (envs/Packing)" 
        Env["env.py"]:::code
        Bin["binCreator.py"]:::code
        Box["box.py"]:::code
        Container["container.py"]:::code
        Cut["cutCreator.py"]:::code
        EMS["ems.py"]:::code
        MDCreator["mdCreator.py"]:::code
        Utils["utils.py"]:::code
    end

    %% Policy & Algorithms
    subgraph "Policy & Algorithms"
        Policy["model.py"]:::code
        A2C["masked_a2c.py"]:::code
        PPO["masked_ppo.py"]:::code
    end

    %% Data Collector
    subgraph "Data Collector"
        Collector["mycollector.py"]:::code
    end

    %% Replay Buffer & Sampling
    subgraph "Replay Buffer & Sampling"
        BaseBuf["base.py"]:::data
        Cached["cached.py"]:::data
        HER["her.py"]:::data
        Manager["manager.py"]:::data
        Prio["prio.py"]:::data
        VecBuf["vecbuf.py"]:::data
    end

    %% Trainer
    subgraph "Trainer"
        TrainScript["ts_train.py"]:::code
        OnPolicy["onpolicy.py"]:::code
        OffPolicy["offpolicy.py"]:::code
        Offline["offline.py"]:::code
        TUtils["utils.py"]:::code
        BaseTrainer["base.py"]:::code
    end

    %% Evaluation & Rendering
    subgraph "Evaluation & Rendering"
        TestScript["ts_test.py"]:::code
        Render["render.py"]:::code
    end

    %% Utilities
    Tools["tools.py"]:::code

    %% External Frameworks
    PyTorch["PyTorch"]:::ext
    TianshouLib["Tianshou"]:::ext

    %% Data Store for Checkpoints
    Checkpoint["Model Checkpoints"]:::data

    %% Connections
    ConfigYAML -->|provides params| Env
    DefaultYAML -->|provides params| Env
    Args -->|parses args| TrainScript
    ConfigYAML -->|provides params| Policy
    DefaultYAML -->|provides params| Policy
    ConfigYAML -->|provides params| TrainScript

    TrainScript -->|initializes| Env
    TrainScript -->|initializes| Policy
    TrainScript -->|starts| Collector
    TrainScript -->|starts| OnPolicy
    TrainScript -->|starts| OffPolicy

    Env -->|obs, reward| Collector
    Policy -->|action| Env
    PyTorch -->|computes| Policy
    TianshouLib -->|updates| OnPolicy
    TianshouLib -->|updates| OffPolicy

    Collector -->|stores| BaseBuf
    Collector -->|stores| Cached
    Collector -->|stores| HER
    Collector -->|stores| Manager
    Collector -->|stores| Prio
    Collector -->|stores| VecBuf
    OnPolicy -->|samples| BaseBuf
    OffPolicy -->|samples| BaseBuf
    OnPolicy -->|updates| Policy
    OffPolicy -->|updates| Policy

    Policy -->|saves| Checkpoint
    TestScript -->|loads| Checkpoint
    TestScript -->|uses| Policy
    TestScript -->|runs| Env
    TestScript -->|calls| Render

    Tools -->|helper routines| TrainScript
    Tools -->|helper routines| TestScript

    %% Click Events
    click ConfigYAML "https://github.com/xiong5heng/gopt/blob/main/cfg/config.yaml"
    click DefaultYAML "https://github.com/xiong5heng/gopt/blob/main/cfg/default.yaml"
    click Args "https://github.com/xiong5heng/gopt/blob/main/arguments.py"
    click Env "https://github.com/xiong5heng/gopt/blob/main/envs/Packing/env.py"
    click Bin "https://github.com/xiong5heng/gopt/blob/main/envs/Packing/binCreator.py"
    click Box "https://github.com/xiong5heng/gopt/blob/main/envs/Packing/box.py"
    click Container "https://github.com/xiong5heng/gopt/blob/main/envs/Packing/container.py"
    click Cut "https://github.com/xiong5heng/gopt/blob/main/envs/Packing/cutCreator.py"
    click EMS "https://github.com/xiong5heng/gopt/blob/main/envs/Packing/ems.py"
    click MDCreator "https://github.com/xiong5heng/gopt/blob/main/envs/Packing/mdCreator.py"
    click Utils "https://github.com/xiong5heng/gopt/blob/main/envs/Packing/utils.py"
    click Policy "https://github.com/xiong5heng/gopt/blob/main/model.py"
    click A2C "https://github.com/xiong5heng/gopt/blob/main/masked_a2c.py"
    click PPO "https://github.com/xiong5heng/gopt/blob/main/masked_ppo.py"
    click Collector "https://github.com/xiong5heng/gopt/blob/main/mycollector.py"
    click BaseBuf "https://github.com/xiong5heng/gopt/blob/main/tianshou/data/buffer/base.py"
    click Cached "https://github.com/xiong5heng/gopt/blob/main/tianshou/data/buffer/cached.py"
    click HER "https://github.com/xiong5heng/gopt/blob/main/tianshou/data/buffer/her.py"
    click Manager "https://github.com/xiong5heng/gopt/blob/main/tianshou/data/buffer/manager.py"
    click Prio "https://github.com/xiong5heng/gopt/blob/main/tianshou/data/buffer/prio.py"
    click VecBuf "https://github.com/xiong5heng/gopt/blob/main/tianshou/data/buffer/vecbuf.py"
    click TrainScript "https://github.com/xiong5heng/gopt/blob/main/ts_train.py"
    click OnPolicy "https://github.com/xiong5heng/gopt/blob/main/tianshou/trainer/onpolicy.py"
    click OffPolicy "https://github.com/xiong5heng/gopt/blob/main/tianshou/trainer/offpolicy.py"
    click Offline "https://github.com/xiong5heng/gopt/blob/main/tianshou/trainer/offline.py"
    click TUtils "https://github.com/xiong5heng/gopt/blob/main/tianshou/trainer/utils.py"
    click BaseTrainer "https://github.com/xiong5heng/gopt/blob/main/tianshou/trainer/base.py"
    click TestScript "https://github.com/xiong5heng/gopt/blob/main/ts_test.py"
    click Render "https://github.com/xiong5heng/gopt/blob/main/render.py"
    click Tools "https://github.com/xiong5heng/gopt/blob/main/tools.py"

    %% Styles
    classDef code fill:#D6EAF8,stroke:#1B4F72,color:#154360
    classDef data fill:#D5F5E3,stroke:#145A32,color:#1D8348
    classDef ext fill:#FAD7A0,stroke:#B9770E,color:#A04000
```
