# shuijing725/crowdnav_prediction_attngraph architecture

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

- Interactive diagram: https://gitdiagram.com/shuijing725/crowdnav_prediction_attngraph
- Repository: https://github.com/shuijing725/crowdnav_prediction_attngraph

## Overview

##### Project Type and Purpose
- This is a research codebase for robot crowd navigation using model-free RL.
- It integrates:
- A crowd simulator (`crowd_sim/`)
- Human trajectory predictors (GST, constant‐velocity, truth) via `gst_updated/`
- An RL training and inference framework using PPO (`rl/`)
- Policy modules and configuration (`crowd_nav/`)
- Top‐level scripts (`train.py`, `test.py`, `plot.py`)
- Purpose: learn and evaluate robot navigation policies that are intention-aware by predicting human trajectories and embedding them in an attention‐based interaction graph.

##### File Structure
- Top-level directories:
- `crowd_nav/` – config definitions and policy factory modules
- `crowd_sim/` – Gym‐style environment implementations for various simulation modes
- `gst_updated/` – standalone inference code for the Gumbel Social Transformer trajectory predictor
- `rl/` – PPO algorithm, network architectures, vectorized env wrappers, logging
- `trained_models/` – pretrained checkpoints and config for quick testing
- Scripts and entrypoints:
- `arguments.py`, `train.py`, `test.py`, `plot.py`, auxiliary scripts (`collect_data.py`, `figures/`)
- Build/deploy artifacts:
- Requirements (`requirements.txt`)
- External dependencies: PyTorch, OpenAI Baselines, Python-RVO2

##### README Insights
- The project uses a modular design: environment ←→ predictor ←→ policy ←→ RL trainer
- Configurations are loaded from `crowd_nav/configs/config.py` and `arguments.py`
- Multiple “predict_method” modes: ‘inferred’, ‘const_vel’, ‘truth’, ‘none’
- Env names map to Gym IDs: `CrowdSimPredRealGST-v0`, `CrowdSimPred-v0`, `CrowdSimVarNum-v0`

##### Main Components & Interactions
1. Crowd Simulator
- Modules under `crowd_sim/envs/`
- Supplies observations (agent positions, goals) and accepts robot actions
2. Human Trajectory Predictor
- GST model: code under `gst_updated/src/gumbel_social_transformer/`
- Outputs predicted future trajectories
3. Policy Network & PPO Trainer
- Networks: `rl/networks/`
- PPO logic: `rl/ppo/ppo.py`
4. Config & Policy Factory
- `crowd_nav/configs/config.py`, `crowd_nav/policy/policy_factory.py`
- Instantiates ORCA, Social Force, SRNN policies or GST-aware graph policy
5. Script Orchestrator
- `train.py`: loads configs, builds env, runs RL training loop
- `test.py`: loads checkpoint, runs evaluation loops, optionally visualizes
- `plot.py`: consumes training logs to generate learning curves
6. Data Stores
- Checkpoints & logs: `trained_models/…`, `gst_updated/results/…`, tensorboard events
1. Config → Environment & Predictor & Trainer
2. Environment → (observations) → Predictor (if `predict_method='inferred'`)
3. Predictor → (predicted trajectories) → Obs Augmentation
4. Augmented Obs → Policy Network → Action
5. Action → Environment.step() → next Obs, Reward, Done
6. Trainer ↔ Policy Network (gradient updates)
7. Trainer → Checkpoint files → `trained_models/`
8. `test.py` loads Checkpoint → runs same loop (Env → Policy → Action)
9. `plot.py` reads logs → outputs figures
c. Architectural Patterns & Principles:
- Modular separation: prediction, simulation, policy, training
- Factory pattern for selecting policies (`policy_factory.py`)
- Wrapper pattern for vectorized envs (`rl/vec_env/`, `rl/networks/shmem_vec_env.py`)
- Config-driven behavior (all parameters centralized in config files)
d. Key Technologies & Frameworks:
- PyTorch for networks & GST inference
- OpenAI Baselines for PPO implementation
- Python-RVO2 for ORCA human dynamics
- Gym‐style interface for simulation
- TensorBoard for logging (`events.out.tfevents`)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Orchestration Layer
    subgraph "Orchestration Layer"
        direction TB
        Train["train.py"]:::orches
        Test["test.py"]:::orches
        Plot["plot.py"]:::orches
        Args["arguments.py"]:::orches
        Collect["collect_data.py"]:::orches
    end

    %% Configuration & Factory
    subgraph "Configuration & Policy Factory"
        direction TB
        Config["config.py"]:::config
        Factory["policy_factory.py"]:::config
        ORCA["orca.py"]:::config
        SF["social_force.py"]:::config
        SRNN["srnn.py"]:::config
    end

    %% Prediction Layer
    subgraph "Prediction Layer"
        direction TB
        GSTModel["GST Predictor Service"]:::core
        PredWrapper["Interface Multi-Env Wrapper"]:::core
        PredScripts["Predictor Experiment Scripts"]:::orches
    end

    %% Simulation Layer
    subgraph "Simulation Layer"
        direction TB
        EnvCore["CrowdSimEnv (Gym)"]:::core
        EnvUtils["Simulator Utilities"]:::core
    end

    %% Learning Layer
    subgraph "Learning Layer"
        direction TB
        PPO["PPO Trainer"]:::core
        Networks["Network Architectures"]:::core
        VecEnv["Vectorized Env Wrappers"]:::core
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        Checkpoints["Pretrained Models & Checkpoints"]:::data
        GSTResults["GST Predictor Results"]:::data
        Requirements["Requirements"]:::data
    end

    %% Relationships
    Train -->|loads| Args
    Train -->|loads| Config
    Train -->|builds| EnvCore
    Train -->|selects predictor| GSTModel
    Train -->|uses wrapper| PredWrapper
    Train -->|invokes| PPO
    Train -->|writes| Checkpoints
    Test -->|loads| Checkpoints
    Test -->|runs loop| EnvCore
    Test -->|optional visualize| Plot
    PredScripts -->|generate trajectories| GSTResults
    Config -->|instantiates| Factory
    Factory -->|produces| ORCA
    Factory -->|produces| SF
    Factory -->|produces| SRNN
    EnvCore -->|supplies obs| GSTModel
    GSTModel -->|outputs preds| EnvCore
    EnvCore -->|observations| Networks
    Networks -->|action| EnvCore
    PPO -->|updates| Networks
    VecEnv -->|parallel envs| EnvCore
    PPO -->|optimizes| Networks
    Plot -->|reads logs| Checkpoints

    %% Click Events
    click EnvCore "https://github.com/shuijing725/crowdnav_prediction_attngraph/tree/main/crowd_sim/envs/"
    click EnvUtils "https://github.com/shuijing725/crowdnav_prediction_attngraph/tree/main/crowd_sim/envs/utils/"
    click GSTModel "https://github.com/shuijing725/crowdnav_prediction_attngraph/tree/main/gst_updated/src/gumbel_social_transformer/"
    click PredScripts "https://github.com/shuijing725/crowdnav_prediction_attngraph/tree/main/gst_updated/scripts/experiments/"
    click PredWrapper "https://github.com/shuijing725/crowdnav_prediction_attngraph/blob/main/gst_updated/scripts/wrapper/crowd_nav_interface_multi_env_parallel.py"
    click PPO "https://github.com/shuijing725/crowdnav_prediction_attngraph/blob/main/rl/ppo/ppo.py"
    click Networks "https://github.com/shuijing725/crowdnav_prediction_attngraph/tree/main/rl/networks/"
    click VecEnv "https://github.com/shuijing725/crowdnav_prediction_attngraph/tree/main/rl/vec_env/"
    click Config "https://github.com/shuijing725/crowdnav_prediction_attngraph/blob/main/crowd_nav/configs/config.py"
    click Factory "https://github.com/shuijing725/crowdnav_prediction_attngraph/blob/main/crowd_nav/policy/policy_factory.py"
    click ORCA "https://github.com/shuijing725/crowdnav_prediction_attngraph/blob/main/crowd_nav/policy/orca.py"
    click SF "https://github.com/shuijing725/crowdnav_prediction_attngraph/blob/main/crowd_nav/policy/social_force.py"
    click SRNN "https://github.com/shuijing725/crowdnav_prediction_attngraph/blob/main/crowd_nav/policy/srnn.py"
    click Checkpoints "https://github.com/shuijing725/crowdnav_prediction_attngraph/tree/main/trained_models/"
    click GSTResults "https://github.com/shuijing725/crowdnav_prediction_attngraph/tree/main/gst_updated/results/"
    click Requirements "https://github.com/shuijing725/crowdnav_prediction_attngraph/blob/main/requirements.txt"

    %% Styles
    classDef core fill:#BBDEFB,stroke:#333,stroke-width:1px
    classDef config fill:#C8E6C9,stroke:#333,stroke-width:1px
    classDef orches fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef data fill:#E0E0E0,stroke:#333,stroke-width:1px
```
