# sunnywist/dpct architecture

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

- Interactive diagram: https://gitdiagram.com/sunnywist/dpct
- Repository: https://github.com/sunnywist/dpct

## Overview

##### Project Type and Purpose
- DPCT is a research-oriented reinforcement-learning pipeline built on PRIMAL2.
- It consists of three phases: environment generation, distributed training, and distributed simulation.
- It integrates Python controllers, C/C++/Cython path-planning libraries, and leverages CUDA/GPU and Ray/Horovod for distribution.

##### File Structure
Top-level folders and files reveal three major subsystems:
- DPCT/
- Core Python modules: Runner.py, TrainDriver.py, SimulateWithRayDriver.py, Worker.py
- Env generators: Env_Builder.py, Map_Generator.py, TestGenerator.py, TestingEnv.py
- RL components: ACNet.py, Observer_Builder.py, PRIMAL2_Env.py, PRIMAL2_Observer*.py
- Config abstractions under PyConfigs/ and configs/
- Bash scripts (train.sh, simulate.sh, both_train_simulate.sh, generate_envs.sh)
- DPCT/astarlib3 and DPCT/od_mstar3
- Native extensions for A* and OD-M* planning (C, Cython, C++).
- envs/
- Raw map generation tools (Generate_Raw_Map, Envs_Reseter, etc.)
- scripts and config directories: requirements.txt, configs/*.yaml, cpp_setup.sh.

##### README Insights
- Describes a conda/CUDA setup, installation of TensorFlow with Horovod, and bash-driven entry points: generate_envs.sh, train.sh, simulate.sh.
- References PRIMAL2, confirming a multi-agent RL use case.

##### Main Components
a. Environment Generation Layer
- Raw Map Generators (envs/*.py)
- DPCT/Map_Generator.py and Env_Builder.py
- Configs: generator.yaml, GeneratorConfig.py
- Outputs: Serialized environment definitions
b. Training Layer
- TrainDriver.py orchestrates multiple Worker.py processes (Ray/Horovod)
- ACNet.py (neural network model)
- Observer modules (PRIMAL2_Observer*)
- Configs: train.yaml, TrainConfig.py
- Underlying GPU cluster (CUDA) and distributed framework (Ray, Horovod)
c. Simulation Layer
- SimulateWithRayDriver.py and Runner.py
- Worker.py re-used for rollout collection
- Configs: simulate.yaml, SimulateConfig.py
d. Native Path-Planning Services
- astarlib3 (A* via Cython)
- od_mstar3 (OD-M* via C++/Cython)
- interface.py in od_mstar3 used by Python controllers
e. Configuration and Orchestration
- Centralized config directory (configs/) plus PyConfigs/ abstraction
- Bash scripts as high-level entry points

##### Relationships and Data Flow
- Start: User invokes bash script → loads configs → calls Python entry point
- Env generation writes map files → consumed by Training layer
- Training driver dispatches Workers → each calls Cython planners via astarlib3/od_mstar3 for step simulation → collects rollouts → updates ACNet model
- Simulation driver replays trained model in new environments → aggregates metrics

##### Architectural Patterns & Design Principles
- Pipeline pattern: sequential phases (Generate → Train → Simulate)
- Modular design: clear separation of concerns (env, model, planner, orchestration)
- Distributed actor model: Ray + Horovod for parallel workers
- Native acceleration: C/C++ extensions for compute-intensive planning

##### Final Advice
- Be exhaustive: represent every DPCT/*.py and envs/*.py cluster by function rather than listing each file.
- Orchestration and data flow clearly.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Config & Orchestration"
        scripts_s["generate_envs.sh"]:::config
        scripts_t["train.sh"]:::config
        scripts_s2["simulate.sh"]:::config
        scripts_b["both_train_simulate.sh"]:::config
        scripts_cpp["cpp_setup.sh"]:::config
        configs_dir["configs/"]:::config
        pyconfigs_dir["DPCT/PyConfigs/"]:::config
    end

    subgraph "Environment Generation Layer"
        gen_raw["Raw Map Generators"]:::pythonControllers
        map_gen["Map_Generator.py"]:::pythonControllers
        env_builder["Env_Builder.py"]:::pythonControllers
        gen_yaml["generator.yaml"]:::config
        gen_pyconfig["GeneratorConfig.py"]:::config
    end

    subgraph "Training Layer"
        train_driver["TrainDriver.py"]:::distributed
        train_worker["Worker.py"]:::distributed
        acnet["ACNet.py"]:::pythonControllers
        obs_builder["Observer_Builder.py"]:::pythonControllers
        primal_env["PRIMAL2_Env.py"]:::pythonControllers
        primal_obs["PRIMAL2_Observer*.py"]:::pythonControllers
        train_yaml["train.yaml"]:::config
        train_pyconfig["TrainConfig.py"]:::config
    end

    subgraph "Simulation Layer"
        sim_driver["SimulateWithRayDriver.py"]:::distributed
        runner["Runner.py"]:::distributed
        sim_worker["Worker.py"]:::distributed
        sim_yaml["simulate.yaml"]:::config
        sim_pyconfig["SimulateConfig.py"]:::config
    end

    subgraph "Native Path-Planning Services"
        astar["astarlib3/"]:::native
        od_mstar["od_mstar3/"]:::native
        od_interface["interface.py"]:::native
    end

    %% Orchestration flows
    scripts_s --> gen_yaml
    scripts_s --> gen_pyconfig
    scripts_s --> env_builder
    gen_yaml --> env_builder
    gen_pyconfig --> env_builder
    gen_raw --> env_builder
    map_gen --> env_builder
    env_builder -->|"env definitions"| train_driver

    scripts_t --> train_yaml
    scripts_t --> train_pyconfig
    scripts_t --> train_driver
    train_yaml --> train_driver
    train_pyconfig --> train_driver
    train_driver -->|dispatch| train_worker
    train_worker -->|"sim step"| astar
    train_worker -->|"sim step"| od_interface
    od_interface --> od_mstar
    train_worker --> train_driver
    train_driver -->|"model params"| sim_driver

    scripts_s2 --> sim_yaml
    scripts_s2 --> sim_pyconfig
    scripts_s2 --> sim_driver
    sim_yaml --> sim_driver
    sim_pyconfig --> sim_driver
    sim_driver -->|dispatch| sim_worker
    sim_worker -->|"sim step"| astar
    sim_worker -->|"sim step"| od_interface
    sim_worker --> sim_driver

    both --> scripts_b
    scripts_cpp --> astar
    scripts_cpp --> od_mstar

    %% Config directories
    configs_dir --> gen_yaml
    configs_dir --> train_yaml
    configs_dir --> sim_yaml
    pyconfigs_dir --> gen_pyconfig
    pyconfigs_dir --> train_pyconfig
    pyconfigs_dir --> sim_pyconfig

    %% Click Events
    click env_builder "https://github.com/sunnywist/dpct/blob/main/DPCT/Env_Builder.py"
    click map_gen "https://github.com/sunnywist/dpct/blob/main/DPCT/Map_Generator.py"
    click gen_raw "https://github.com/sunnywist/dpct/blob/main/envs/Generate_Raw_Map.py"
    click gen_raw "https://github.com/sunnywist/dpct/blob/main/envs/Generate_Raw_Map_Randomly.py"
    click gen_raw "https://github.com/sunnywist/dpct/blob/main/envs/GenerateRawMapSelect.py"
    click gen_raw "https://github.com/sunnywist/dpct/blob/main/envs/Envs_Reseter.py"
    click gen_yaml "https://github.com/sunnywist/dpct/blob/main/configs/generator.yaml"
    click gen_pyconfig "https://github.com/sunnywist/dpct/blob/main/DPCT/PyConfigs/GeneratorConfig.py"

    click train_driver "https://github.com/sunnywist/dpct/blob/main/DPCT/TrainDriver.py"
    click train_worker "https://github.com/sunnywist/dpct/blob/main/DPCT/Worker.py"
    click acnet "https://github.com/sunnywist/dpct/blob/main/DPCT/ACNet.py"
    click obs_builder "https://github.com/sunnywist/dpct/blob/main/DPCT/Observer_Builder.py"
    click primal_env "https://github.com/sunnywist/dpct/blob/main/DPCT/PRIMAL2_Env.py"
    click primal_obs "https://github.com/sunnywist/dpct/blob/main/DPCT/PRIMAL2_Observer.py"
    click primal_obs "https://github.com/sunnywist/dpct/blob/main/DPCT/PRIMAL2_ObserverPlan1.py"
    click train_yaml "https://github.com/sunnywist/dpct/blob/main/configs/train.yaml"
    click train_pyconfig "https://github.com/sunnywist/dpct/blob/main/DPCT/PyConfigs/TrainConfig.py"

    click sim_driver "https://github.com/sunnywist/dpct/blob/main/DPCT/SimulateWithRayDriver.py"
    click runner "https://github.com/sunnywist/dpct/blob/main/DPCT/Runner.py"
    click sim_worker "https://github.com/sunnywist/dpct/blob/main/DPCT/Worker.py"
    click sim_yaml "https://github.com/sunnywist/dpct/blob/main/configs/simulate.yaml"
    click sim_pyconfig "https://github.com/sunnywist/dpct/blob/main/DPCT/PyConfigs/SimulateConfig.py"

    click astar "https://github.com/sunnywist/dpct/tree/main/DPCT/astarlib3/"
    click od_mstar "https://github.com/sunnywist/dpct/tree/main/DPCT/od_mstar3/"
    click od_interface "https://github.com/sunnywist/dpct/blob/main/DPCT/od_mstar3/interface.py"

    click configs_dir "https://github.com/sunnywist/dpct/tree/main/configs/"
    click pyconfigs_dir "https://github.com/sunnywist/dpct/tree/main/DPCT/PyConfigs/"
    click scripts_s "https://github.com/sunnywist/dpct/blob/main/generate_envs.sh"
    click scripts_t "https://github.com/sunnywist/dpct/blob/main/train.sh"
    click scripts_s2 "https://github.com/sunnywist/dpct/blob/main/simulate.sh"
    click scripts_b "https://github.com/sunnywist/dpct/blob/main/both_train_simulate.sh"
    click scripts_cpp "https://github.com/sunnywist/dpct/blob/main/cpp_setup.sh"

    classDef pythonControllers fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef native fill:#C2F0C2,stroke:#333,stroke-width:1px
    classDef distributed fill:#FFE4B5,stroke:#333,stroke-width:1px
    classDef config fill:#F0F0F0,stroke:#333,stroke-width:1px
```
