# yd-kwon/pomo architecture

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

- Interactive diagram: https://gitdiagram.com/yd-kwon/pomo
- Repository: https://github.com/yd-kwon/pomo

## Overview

##### Project Type & Purpose
- The project is a research and production-ready implementation of the POMO (Policy Optimization with Multiple Optima) method for solving combinatorial optimization problems – specifically the Capacitated Vehicle Routing Problem (CVRP) and the Travelling Salesman Problem (TSP).
- The repository contains both “OLD” interactive notebook-based prototypes (from 2020) and a “NEW” Python-based version (from 2021) that is structured for server-side execution.

##### Analyzing the File Structure
- Top-Level Separation: The project is split at the root into NEW_py_ver (the updated, production-oriented version) and OLD_ipynb_ver (the legacy, experimental notebooks).
- Under NEW_py_ver, there are directories for each problem type (CVRP and TSP). In each, there is a “POMO” subfolder that encapsulates the core RL pipeline components – environments (CVRPEnv.py, TSPEnv.py), models (CVRPModel.py, TSPModel.py), trainer and tester scripts, and result (checkpoint) folders.
- There is also a “utils” folder containing helper modules for logging styles and utility functions.
- The OLD_ipynb_ver mirrors a similar separation but uses Jupyter notebooks and an older, more exploratory structure that includes examples for other problems (like knapsack, under POMO_KP).

##### Interpreting the README
- The README explains that the OLD_ipynb_ver contents are the original, interactive versions used for the NeurIPS 2020 paper, while the NEW_py_ver directories offer a cleaner, scalable Python-based refactor.

a. Main Components:
- Problem Modules: Separate modules for CVRP and TSP.
▪ Each module includes a problem definition (e.g., CVRProblemDef.py, TSProblemDef.py).
- POMO Pipeline: For each problem type, structure under POMO includes:
▪ Environment components (CVRPEnv.py, TSPEnv.py) that simulate the problem.
▪ Model components (CVRPModel.py, TSPModel.py) that define the RL network.
▪ Trainer components (CVRPTrainer.py, TSPTrainer.py) that run training loops.
▪ Tester components (CVRPTester.py, TSPTester.py) for evaluation/inference.
▪ Result directories that hold saved checkpoints and logs.
- Utilities: The utils folder provides logging style configurations (JSON styles) and helper functions (utils.py) relevant to visualization or additional processes.

b. Relationships & Interactions:
- How the problem definition modules feed into the environment classes.
- Flow where the environment and model interact during training – for example, the Trainer receives data from the Environment and updates the Model based on the reinforcement learning algorithm.
- Tester to demonstrate the post-training evaluation phase, emphasizing how it uses saved checkpoints.
- That the “NEW_py_ver” structure is the main operational pipeline, with OLD_ipynb_ver illustrating the earlier, more exploratory versions for research validation.

c. Architectural Patterns & Design Principles:
- Separation of Concerns: Distinct modules for environment, model, training, and testing.
- Modularity: Each problem type (CVRP and TSP) is designed as an isolated component within its POMO framework.
- Reusability: Common utilities (e.g., logging style definitions and helper methods) are organized in the utils folder.
- Iterative Pipeline: The workflow follows a clear cycle – problem definition → environment simulation → model training → testing/inference → checkpoint saving.

d. Technologies and Frameworks:
- The system is developed with Python, with a focus on PyTorch (implied by model checkpoints and file naming such as “checkpoint-xxxx.pt”) for deep RL.
- The structure clearly emphasizes research reproducibility (shown by the legacy notebooks) along with formal deployment (Python scripts in NEW_py_ver).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "NEW_py_ver Production Pipeline"
        subgraph "CVRP Module"
            CVRP_PD["Problem Definition (CVRP)"]:::component
            subgraph "POMO Pipeline"
                CVRP_ENV["Environment (CVRP)"]:::component
                CVRP_MODEL["Model (CVRP)"]:::component
                CVRP_TRAINER["Trainer (CVRP)"]:::component
                CVRP_TESTER["Tester (CVRP)"]:::component
                CVRP_RESULT["Result/Checkpoint Storage"]:::storage
            end
        end
        subgraph "TSP Module"
            TSP_PD["Problem Definition (TSP)"]:::component
            subgraph "POMO Pipeline"
                TSP_ENV["Environment (TSP)"]:::component
                TSP_MODEL["Model (TSP)"]:::component
                TSP_TRAINER["Trainer (TSP)"]:::component
                TSP_TESTER["Tester (TSP)"]:::component
                TSP_RESULT["Result/Checkpoint Storage"]:::storage
            end
        end
        UTIL["Utilities and Helper Functions"]:::utility
    end

    subgraph "Legacy Prototypes"
        LEGACY["OLD_ipynb_ver - Legacy Notebook Prototypes"]:::legacy
    end

    %% CVRP Module Flow
    CVRP_PD -->|"defines"| CVRP_ENV
    CVRP_ENV -->|"interacts"| CVRP_MODEL
    CVRP_ENV -->|"feeds"| CVRP_TRAINER
    CVRP_MODEL -->|"updates"| CVRP_TRAINER
    CVRP_TRAINER -->|"triggers"| CVRP_TESTER
    CVRP_TRAINER -->|"saves"| CVRP_RESULT
    CVRP_TESTER -->|"evaluates"| CVRP_RESULT

    %% TSP Module Flow
    TSP_PD -->|"defines"| TSP_ENV
    TSP_ENV -->|"interacts"| TSP_MODEL
    TSP_ENV -->|"feeds"| TSP_TRAINER
    TSP_MODEL -->|"updates"| TSP_TRAINER
    TSP_TRAINER -->|"triggers"| TSP_TESTER
    TSP_TRAINER -->|"saves"| TSP_RESULT
    TSP_TESTER -->|"evaluates"| TSP_RESULT

    %% Utilities Support
    UTIL ---|"supports"| CVRP_ENV
    UTIL ---|"supports"| CVRP_MODEL
    UTIL ---|"supports"| TSP_ENV
    UTIL ---|"supports"| TSP_MODEL

    %% Legacy Influence
    LEGACY ---|"evolvedTo"| CVRP_PD
    LEGACY ---|"evolvedTo"| TSP_PD

    %% Click Events
    click CVRP_PD "https://github.com/yd-kwon/pomo/blob/master/NEW_py_ver/CVRP/CVRProblemDef.py"
    click TSP_PD "https://github.com/yd-kwon/pomo/blob/master/NEW_py_ver/TSP/TSProblemDef.py"
    click CVRP_ENV "https://github.com/yd-kwon/pomo/blob/master/NEW_py_ver/CVRP/POMO/CVRPEnv.py"
    click CVRP_MODEL "https://github.com/yd-kwon/pomo/blob/master/NEW_py_ver/CVRP/POMO/CVRPModel.py"
    click CVRP_TRAINER "https://github.com/yd-kwon/pomo/blob/master/NEW_py_ver/CVRP/POMO/CVRPTrainer.py"
    click CVRP_TESTER "https://github.com/yd-kwon/pomo/blob/master/NEW_py_ver/CVRP/POMO/CVRPTester.py"
    click CVRP_RESULT "https://github.com/yd-kwon/pomo/tree/master/NEW_py_ver/CVRP/POMO/result"
    click TSP_ENV "https://github.com/yd-kwon/pomo/blob/master/NEW_py_ver/TSP/POMO/TSPEnv.py"
    click TSP_MODEL "https://github.com/yd-kwon/pomo/blob/master/NEW_py_ver/TSP/POMO/TSPModel.py"
    click TSP_TRAINER "https://github.com/yd-kwon/pomo/blob/master/NEW_py_ver/TSP/POMO/TSPTrainer.py"
    click TSP_TESTER "https://github.com/yd-kwon/pomo/blob/master/NEW_py_ver/TSP/POMO/TSPTester.py"
    click TSP_RESULT "https://github.com/yd-kwon/pomo/tree/master/NEW_py_ver/TSP/POMO/result"
    click UTIL "https://github.com/yd-kwon/pomo/tree/master/NEW_py_ver/utils"
    click LEGACY "https://github.com/yd-kwon/pomo/tree/master/OLD_ipynb_ver"

    %% Styles
    classDef component fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef storage fill:#FFEFD5,stroke:#000,stroke-width:1px,stroke-dasharray: 5, 5;
    classDef utility fill:#98FB98,stroke:#000,stroke-width:1px;
    classDef legacy fill:#FFB6C1,stroke:#000,stroke-width:1px,stroke-dasharray: 5, 5;
```
