# vita-epfl/crowdnav architecture

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

- Interactive diagram: https://gitdiagram.com/vita-epfl/crowdnav
- Repository: https://github.com/vita-epfl/crowdnav

## Overview

##### Project Type and Purpose
- This is a research‐oriented deep reinforcement learning framework for crowd‐aware robot navigation (no GUI/web front-end).
- It comprises two main packages:
- crowd_sim: a Gym-style crowd simulation environment (with RVO2 dynamics)
- crowd_nav: training/testing code for multiple RL policies (CADRL, LSTM-RL, SARL, etc.)

##### High-level Components
a. Simulation Environment (crowd_sim/)
- envs/crowd_sim.py: core simulator stepping through time
- envs/policy/*.py: built-in human navigation policies (e.g., ORCA, linear)
- envs/utils: state/action/human/robot abstractions & helper functions
b. Policy Implementations (crowd_nav/policy/)
- cadrl.py, lstm_rl.py, sarl.py, multi_human_rl.py: RL policy classes
- policy_factory.py: Factory pattern to instantiate policies by name
c. Configuration Loader (crowd_nav/configs/)
- env.config: environment hyperparams (crowd size, noise, time step)
- policy.config: network/policy hyperparams
- train.config: training loop settings (learning rate, batch size, episodes)
d. Training & Evaluation Scripts (crowd_nav/)
- train.py: orchestrates RL training
e. Utility Modules (crowd_nav/utils/)
- explorer.py: handles exploration strategy (ε-greedy)
- memory.py: replay buffer management
- trainer.py: main RL loop, backpropagation, logging
- plot.py: post-hoc learning curve visualization

##### Interactions and Data Flow
1. train.py
- Loads train.config, policy.config, env.config
- Instantiates Environment via crowd_sim API and Policy via policy_factory
- Instantiates Memory & Explorer
- Calls Trainer.run_training():
- for each episode:
– Reset env → initial state
– Loop over timesteps:
- Policy.compute_action(state) → action
- env.step(action) → next_state, reward, done
- Memory.store(transition)
- Explorer.adjust_epsilon()
- Trainer.learn_from(memory) (samples batch, updates policy network)
- Logs metrics to output.log
2. test.py
- Similar but no learning: loads a saved model, runs episodes, optionally visualizes trajectories
3. plot.py
- Reads output.log → plots loss/return curves

##### Key Architectural Patterns & Design Principles
- Modular separation: simulation vs. learning vs. config vs. policies
- Factory pattern to select policies by string key
- Config‐driven behavior without code changes
- Use of standard Gym API for env.step/reset
- Replay buffer decoupled from main loop for easy swapping (e.g., prioritized replay)

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Dependency
    PythonRVO2["Python-RVO2"]:::external

    %% Subgraphs
    subgraph "Infrastructure Layer"
        direction TB
        EnvService["Env Service\n(crowd_sim/envs/crowd_sim.py)"]:::infra
        subgraph "Simulation Policies"
            direction TB
            PolicyBase["Policy Base\n(policy.py)"]:::infra
            PolicyFactorySim["Policy Factory\n(policy_factory.py)"]:::infra
            Linear["Linear Policy\n(linear.py)"]:::infra
            ORCA["ORCA Policy\n(orca.py)"]:::infra
        end
        subgraph "Sim Utils"
            direction TB
            Action["action.py"]:::infra
            Agent["agent.py"]:::infra
            Human["human.py"]:::infra
            Info["info.py"]:::infra
            Robot["robot.py"]:::infra
            State["state.py"]:::infra
            UtilsSim["utils.py"]:::infra
        end
    end

    subgraph "Configuration Manager" 
        direction TB
        EnvConfig["env.config"]:::config
        PolicyConfig["policy.config"]:::config
        TrainConfig["train.config"]:::config
    end

    subgraph "CLI Scripts"
        direction TB
        TrainScript["train.py"]:::script
        TestScript["test.py"]:::script
    end

    subgraph "Learning Layer"
        direction TB
        subgraph "Policy Implementations"
            direction TB
            CADRL["cadrl.py"]:::learning
            LSTMRL["lstm_rl.py"]:::learning
            SARL["sarl.py"]:::learning
            MultiHuman["multi_human_rl.py"]:::learning
            PolicyFactoryRL["policy_factory.py"]:::learning
        end
        subgraph "Utilities"
            direction TB
            Explorer["explorer.py"]:::utils
            Memory["memory.py"]:::utils
            Trainer["trainer.py"]:::learning
            Plotter["plot.py"]:::utils
        end
        Logger["Logger\n(output.log)"]:::storage
    end

    %% Connections
    PythonRVO2 --> EnvService
    EnvConfig --> TrainScript
    PolicyConfig --> TrainScript
    TrainConfig --> TrainScript

    EnvConfig --> EnvService
    PolicyConfig --> PolicyFactoryRL
    TrainConfig --> Trainer

    TrainScript --> EnvService
    TrainScript --> PolicyFactoryRL
    TrainScript --> Trainer

    TestScript --> PolicyFactoryRL
    TestScript --> EnvService

    EnvService -->|state| CADRL
    EnvService -->|state| LSTMRL
    EnvService -->|state| SARL
    EnvService -->|state| MultiHuman

    CADRL -->|action| EnvService
    LSTMRL -->|action| EnvService
    SARL -->|action| EnvService
    MultiHuman -->|action| EnvService

    Trainer --> Memory
    Trainer --> Explorer
    Trainer --> PolicyFactoryRL
    Trainer --> Logger

    Memory -->|batch| Trainer
    Logger --> Plotter

    TestScript -->|--visualize| Plotter

    %% Click Events
    click EnvService "https://github.com/vita-epfl/crowdnav/blob/master/crowd_sim/envs/crowd_sim.py"
    click Linear "https://github.com/vita-epfl/crowdnav/blob/master/crowd_sim/envs/policy/linear.py"
    click ORCA "https://github.com/vita-epfl/crowdnav/blob/master/crowd_sim/envs/policy/orca.py"
    click PolicyBase "https://github.com/vita-epfl/crowdnav/blob/master/crowd_sim/envs/policy/policy.py"
    click PolicyFactorySim "https://github.com/vita-epfl/crowdnav/blob/master/crowd_sim/envs/policy/policy_factory.py"
    click Action "https://github.com/vita-epfl/crowdnav/blob/master/crowd_sim/envs/utils/action.py"
    click Agent "https://github.com/vita-epfl/crowdnav/blob/master/crowd_sim/envs/utils/agent.py"
    click Human "https://github.com/vita-epfl/crowdnav/blob/master/crowd_sim/envs/utils/human.py"
    click Info "https://github.com/vita-epfl/crowdnav/blob/master/crowd_sim/envs/utils/info.py"
    click Robot "https://github.com/vita-epfl/crowdnav/blob/master/crowd_sim/envs/utils/robot.py"
    click State "https://github.com/vita-epfl/crowdnav/blob/master/crowd_sim/envs/utils/state.py"
    click UtilsSim "https://github.com/vita-epfl/crowdnav/blob/master/crowd_sim/envs/utils/utils.py"
    click CADRL "https://github.com/vita-epfl/crowdnav/blob/master/crowd_nav/policy/cadrl.py"
    click LSTMRL "https://github.com/vita-epfl/crowdnav/blob/master/crowd_nav/policy/lstm_rl.py"
    click SARL "https://github.com/vita-epfl/crowdnav/blob/master/crowd_nav/policy/sarl.py"
    click MultiHuman "https://github.com/vita-epfl/crowdnav/blob/master/crowd_nav/policy/multi_human_rl.py"
    click PolicyFactoryRL "https://github.com/vita-epfl/crowdnav/blob/master/crowd_nav/policy/policy_factory.py"
    click EnvConfig "https://github.com/vita-epfl/crowdnav/blob/master/crowd_nav/configs/env.config"
    click PolicyConfig "https://github.com/vita-epfl/crowdnav/blob/master/crowd_nav/configs/policy.config"
    click TrainConfig "https://github.com/vita-epfl/crowdnav/blob/master/crowd_nav/configs/train.config"
    click TrainScript "https://github.com/vita-epfl/crowdnav/blob/master/crowd_nav/train.py"
    click TestScript "https://github.com/vita-epfl/crowdnav/blob/master/crowd_nav/test.py"
    click Explorer "https://github.com/vita-epfl/crowdnav/blob/master/crowd_nav/utils/explorer.py"
    click Memory "https://github.com/vita-epfl/crowdnav/blob/master/crowd_nav/utils/memory.py"
    click Trainer "https://github.com/vita-epfl/crowdnav/blob/master/crowd_nav/utils/trainer.py"
    click Plotter "https://github.com/vita-epfl/crowdnav/blob/master/crowd_nav/utils/plot.py"

    %% Styles
    classDef infra fill:#D0E8FF,stroke:#005B96,color:#003f6b
    classDef learning fill:#D5F5E3,stroke:#28B463,color:#117A65
    classDef config fill:#FDEBD0,stroke:#DC7633,color:#7E5109
    classDef utils fill:#F2F4F4,stroke:#ABB2B9,color:#566573
    classDef script fill:#E8DAEF,stroke:#9B59B6,color:#6C3483
    classDef storage fill:#FCF3CF,stroke:#F4D03F,color:#7D6608
    classDef external fill:#E8F8F5,stroke:#17A589,color:#0E6655
```
