How gdam90/hyp2nav works
Project Type and Purpose
• This is a research-driven, full-stack RL and simulation project focused on crowd navigation. It implements hyperbolic planning and curiosity mechanisms for efficient and interpretable navigation in crowded environments.
• The objective is to train and evaluate policies (including tree-search based and DQN-style policies) that operate in simulation environments and eventually be used on real robots, with an eye toward low-resource settings and hierarchical decision-making.
Analyzing the File Structure
• Top-level directories include:
• crowd_nav: Contains the main training/testing code, policy implementations (e.g., TD3_rl.py, tree_searchrl.py, various policy submodules, and associated configurations). It also contains ROS interfaces (e.g., ros_node.py, ros_inter.py).
• crowd_sim: Hosts the simulation environment. It defines the environment (in envs/), the simulation dynamics, and simulation-specific policy implementations that likely interact with the main training module.
• src/sgdqn_common: Contains ROS message definitions (for communicating actions, observations, robot and pedestrian states) indicating integration with a messaging or ROS-based ecosystem.
• Others: Utility scripts, shell scripts (e.g., run_experiments_icra.sh), experimental run scripts, and configuration files (configs/icra_benchmark/) which define experimental parameters for various algorithms, including hyperbolic and curiosity settings.
• The presence of configuration directories, experiment scripts, and a variety of policy definitions suggests a modular, component-based design where experimentation is a first-class concern.
Insights from the README
• The README describes the project’s motivation, setup (with dependencies like Python-RVO2, socialforce, geoopt, and wandb), and how to run training and testing.
• The README also emphasizes the use of hyperbolic learning and curiosity modules, so these should be highlighted as key functional modules within the policy portion of the design.
a. Identifying the Main Components:
• Training and Testing Module (crowd_nav):
• Training Scripts: train.py, train_on_server.py.
• Policy Implementations & Models: Located under crowd_nav/policy, including hyperbolic policy models and curiosity modules.
• Configuration Files: Under crowd_nav/configs, which dictate experimental parameters.
• ROS Interfaces: Files like ros_node.py, ros_inter.py, ros_visuals.py, and dummy_ros_simulator.py help bridge real-world sensor data or simulated messages.
• Simulation Environment (crowd_sim):
• Environment Definitions: In crowd_sim/envs (crowd_sim.py) and policy behaviors for simulated agents.
• Extended Utilities: For handling simulation-specific dynamics and real-simulation utilities.
• Communication/Message Layer (src/sgdqn_common):
• ROS message definitions (ActionCmd.msg, ObserveInfo.msg, etc.) illustrate an interface layer between simulation environments and the training module.
• Utility and Support Modules:
• Scripts (shell scripts, publishing goals, etc.) and utilities for visualization and analysis.
b. Determining Relationships and Interactions:
• That the training module interacts with the simulation environment: policies are tested via simulation, and simulation outcomes feed back to design refinement.
• The ROS/message layer (src/sgdqn_common) should be depicted as a shared communication interface between simulation and control components.
• External dependencies or libraries (like Python-RVO2, socialforce, geoopt, wandb) should be indicated as supportive modules that interact with these components.
c. Architectural Patterns and Design Principles:
• Modular Decomposition: Clearly separate simulation (crowd_sim) from learning/training (crowd_nav).
• Configuration-Driven Behavior: Use configuration files (in configs/) to make the system flexible for different experimental setups.
• Use of ROS: Where applicable, indicate the use of ROS nodes and topics for inter-module communications.
• Emphasis on experimentation: Multiple shell scripts and configuration variants suggest a pattern where experimental modules are interchangeable.
d. Relevant Technologies, Frameworks, and Libraries:
• PyTorch for policy training and hyperbolic learning components.
• geoopt for hyperbolic geometry support.
• Python-RVO2 and socialforce to simulate realistic crowd dynamics.
• wandb for experiment tracking.
• ROS (indicated by ROS interfaces and message definitions in src/sgdqn_common).