# instadeepai/poppy architecture

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

- Interactive diagram: https://gitdiagram.com/instadeepai/poppy
- Repository: https://github.com/instadeepai/poppy

## Overview

##### Project Type and Purpose
- The project is an implementation of a reinforcement learning method called “Poppy” designed for solving combinatorial optimization problems (e.g., TSP, CVRP, Knapsack) using a population of RL agents.
- The README indicates that the project uses JAX for hardware-accelerated training and adopts a two-phase training pipeline (a single agent followed by a population) with experiments and evaluation routines.
- The central purpose is to improve exploration in NP-hard optimization by training diverse agent populations with different decoders.

##### Analyzing the File Structure
- Top-Level Organization:
- Files like .dockerignore, Dockerfiles in the “docker” directory, and Makefile indicate that the project has a containerized deployment environment.
- The “experiments” directory contains scripts for training, validation, and different configuration files (using Hydra) which detail various experiment setups.
- The “poppy” directory is the core library. It includes:
∘ “environments”: Different subdirectories for the combinatorial challenges (cvrp, knapsack, tsp) with individual environment definitions, utilities, and types.
∘ “networks”: Architecture components for different problems.
∘ “trainers”: Contains the training logic (including specialized trainer for “slowrl” validation) and standard training routines.
∘ “utils”: Contains utility functions like logging, checkpointing, and metrics.
- The presence of configuration subdirectories and setup.py indicates a modular design with a clear separation between experiment configuration (in “experiments”) and the core business logic (in “poppy”).

##### Using the README for Additional Insights
- The README outlines the two-phase training methodology:
- Phase 1: Training a single-decoder – indicated by a “pomo” objective.
- Phase 2: Training a population of decoders – indicated by “poppy” or “poppy_with_pomo_baseline” objectives.
- Detailed parameter definitions in the configuration examples guide how the training is orchestrated and point to configuration components managed by Hydra.

a. Main Components to Include:
- Docker & Deployment Environment: Represent both local and TPU-specific Docker images.
- Experiments Module:
- Training Pipeline: Scripts like experiments/train.py.
- Evaluation Modules: scripts for greedy evaluation (validate.py) and stochastic sampling (slowrl_validate.py).
- Configuration Files: Folder “experiments/config” holding various experiment setups for different problem specifications.
- Core Library (Poppy):
- Environments: Module for various combinatorial problem definitions.
- Networks: Modules defining neural network architectures for each problem.
- Trainers: Training routines, including slow RL validation logic.
- Utilities: Checkpointing, data management, logging, metrics.
- External Dependencies: JAX (as the core ML framework) and Hydra (for configuration management).

b. Relationships and Interactions:
- The Docker container encapsulates the entire environment, ensuring consistency across hardware (TPU, CPU, or GPU).
- Entry points for training and evaluation (inside experiments) depend on configuration parameters which are defined externally (Hydra configurations).
- The training scripts call into the “poppy” core library, which then leverages the “environments”, “networks”, and “trainers” modules.
- Data flows from configuration files to training processes, then through model training (utilizing poppy/networks and poppy/trainers) and finally, performance results/logs flow out via utilities.

c. Architectural Patterns and Principles:
- Modular design: Clear separation between experiment orchestration and core algorithm implementations.
- Two-phase Training Pipeline: Emphasize first training a baseline (single-decoder) followed by multi-decoder population training.
- Use of containerization to handle dependency and deployment issues.
- Clean separation of concerns evident in the directory structure (e.g., “experiments” vs. “poppy”).
- Leverage a configuration management system (Hydra) for flexibility in experiment settings.

d. Relevant Technologies, Frameworks, or Libraries:
- JAX: Main computation and hardware acceleration framework.
- Docker: For containerized environments.
- Hydra: Used for configuration management.
- Auxiliary Python tools such as Flake8 for style guidelines, pre-commit configurations, and standard logging utilities.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Docker Environment Subgraph
    subgraph "Docker Environment"
        D1["Local Dockerfile"]:::docker
        D2["TPU Dockerfile"]:::docker
        D3["Local Environment Config"]:::docker
        D4["TPU Environment Config"]:::docker
    end

    %% Experiment Orchestrator Subgraph
    subgraph "Experiment Orchestrator"
        E1["Train Script"]:::orchestrator
        E2["Validate Script"]:::orchestrator
        E3["SlowRL Validate Script"]:::orchestrator
        E4["Experiment Configurations"]:::orchestrator
    end

    %% Core Library: Poppy Subgraph
    subgraph "Core Library: Poppy"
        %% Environments Subsystem
        subgraph "Environments Subsystem"
            P1["Environments Directory"]:::poppy
            P2["CVRP Environment"]:::poppy
            P3["Knapsack Environment"]:::poppy
            P4["TSP Environment"]:::poppy
            P5["Shared Env: poppy_env.py"]:::poppy
        end
        %% Networks Subsystem
        subgraph "Networks Subsystem"
            P6["Networks Directory"]:::poppy
            P7["Network Modules (base, cvrp, knapsack, tsp)"]:::poppy
        end
        %% Trainers Subsystem
        subgraph "Trainers Subsystem"
            P8["Trainers Directory"]:::poppy
            P9["Trainer Scripts (trainer.py, validation.py, slowrl_validation.py)"]:::poppy
        end
        %% Utilities Subsystem
        subgraph "Utilities Subsystem"
            P10["Utilities Directory"]:::poppy
            P11["Utility Files (checkpoint.py, data.py, logger.py, metrics.py, sampler.py, utils.py)"]:::poppy
        end
    end

    %% External Dependencies Subgraph
    subgraph "External Dependencies"
        JAX["JAX Framework"]:::external
        Hydra["Hydra Config Manager"]:::external
    end

    %% Connections
    %% Docker Environment encapsulates the entire system
    D1 -->|"deploys"| E1
    D2 -->|"deploys"| E1
    D3 -->|"deploys"| E4
    D4 -->|"deploys"| E4

    %% Experiment Orchestrator to Core Library interactions
    E1 -->|"triggers training"| P1
    E2 -->|"triggers evaluation"| P1
    E3 -->|"triggers slowRL evaluation"| P8
    E4 ---|"provides configuration"| Hydra

    %% Within Core Library: Poppy internal flow
    P1 -->|"initializes"| P5
    P1 -->|"feeds data to"| P7
    P7 -->|"activates training"| P9
    P9 -->|"logs outputs to"| P11

    %% External Dependencies supporting training
    JAX -->|"accelerates"| P7

    %% Styling
    classDef docker fill:#f9e79f,stroke:#d35400,stroke-width:2px;
    classDef orchestrator fill:#aed6f1,stroke:#2471a3,stroke-width:2px;
    classDef poppy fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef external fill:#fadbd8,stroke:#c0392b,stroke-width:2px;

    %% Click Events for Docker Environment
    click D1 "https://github.com/instadeepai/poppy/blob/main/docker/local.Dockerfile"
    click D2 "https://github.com/instadeepai/poppy/blob/main/docker/tpu.Dockerfile"
    click D3 "https://github.com/instadeepai/poppy/blob/main/docker/environment_local.yml"
    click D4 "https://github.com/instadeepai/poppy/blob/main/docker/environment_tpu.yml"

    %% Click Events for Experiment Orchestrator
    click E1 "https://github.com/instadeepai/poppy/blob/main/experiments/train.py"
    click E2 "https://github.com/instadeepai/poppy/blob/main/experiments/validate.py"
    click E3 "https://github.com/instadeepai/poppy/blob/main/experiments/slowrl_validate.py"
    click E4 "https://github.com/instadeepai/poppy/tree/main/experiments/config"

    %% Click Events for Poppy Environments Subsystem
    click P1 "https://github.com/instadeepai/poppy/tree/main/poppy/environments"
    click P2 "https://github.com/instadeepai/poppy/tree/main/poppy/environments/cvrp"
    click P3 "https://github.com/instadeepai/poppy/tree/main/poppy/environments/knapsack"
    click P4 "https://github.com/instadeepai/poppy/tree/main/poppy/environments/tsp"
    click P5 "https://github.com/instadeepai/poppy/blob/main/poppy/environments/poppy_env.py"

    %% Click Events for Poppy Networks Subsystem
    click P6 "https://github.com/instadeepai/poppy/tree/main/poppy/networks"
    click P7 "https://github.com/instadeepai/poppy/tree/main/poppy/networks"

    %% Click Events for Poppy Trainers Subsystem
    click P8 "https://github.com/instadeepai/poppy/tree/main/poppy/trainers"
    click P9 "https://github.com/instadeepai/poppy/tree/main/poppy/trainers"

    %% Click Events for Poppy Utilities Subsystem
    click P10 "https://github.com/instadeepai/poppy/tree/main/poppy/utils"
    click P11 "https://github.com/instadeepai/poppy/tree/main/poppy/utils"
```
