General Documents (#2)

* docs: README

* Update documentation for new repository and usage changes

Updated all documentation references from 'lgcyaxi' to 'radar-lab' GitHub organization. Improved installation, quick start, and FAQ instructions to reflect new repository URLs, updated command examples, and clarified environment setup steps. Replaced architecture diagram and fixed links to external resources. Cleaned up and reorganized FAQ and troubleshooting sections for clarity.

* Refactor and reorganize MARL documentation

Removed outdated and redundant MARL development and overview documents, consolidating content into a new architecture file at docs/marl/architecture.md. Updated references throughout the documentation to point to the new architecture location. Cleaned up related links and removed phase-specific development status sections from user-facing docs. Added /archived_docs to .gitignore.

* Add TD3 MARL config and update docs for intersection scenarios

Added a new TD3-based multi-agent RL configuration for high-density intersection scenarios at configs/marl/intersection_td3.yaml. Expanded the MARL quick-start documentation with detailed usage, agent types, and algorithm configuration examples. Updated installation instructions to include an optional pre-built maps package. Adjusted pixi commands to use intersection_rule_based as the default for quick tests.

* Refactor MARL docs, update configs, and remove old guides

Removed outdated MARL algorithm and training documentation, significantly revised the architecture and changelog docs to reflect the new 3-layer system, agent types, RL algorithms, and traffic management. Updated mkdocs.yml to hide removed pages, and bumped dependency versions in pixi configs to 0.1.0-alpha. This prepares the documentation and configuration for the new MARL foundation release.

Author: lgcyaxi

.gitignore

@@ -152,4 +152,5 @@ ready*
 
 !/recordings/*.json
 /checkpoints/*/*episode_*.*
-/checkpoints/*/latest_checkpoint.*
+/checkpoints/*/latest_checkpoint.*
+/archived_docs

README.md

@@ -50,23 +50,21 @@ Check our [documentation](#) for detailed architecture and MARL integration.
 
 ## Get Started
 
- ![teaser](docs/images/platoon_joining_2lanefree_complete.gif)
+ ![teaser](docs/images/MARL-rule-based-simulation.gif)
 
 ### Users Guide
 
-* [Overview](#)
-* [Installation](#)
-* [Quick Start](#)
-* [Logic Flow](#)
-* [Traffic Generation](#)
+* [Overview](https://radar-lab.github.io/OpenCDA-MARL/)
+* [Installation](https://radar-lab.github.io/OpenCDA-MARL/installation/)
+* [Quick Start](https://radar-lab.github.io/OpenCDA-MARL/quick-start/)
 
 Note: We continuously improve the performance of OpenCDA-MARL. Currently, it is mainly tested in our customized maps. However, we <strong>DO NOT </strong> guarantee the same level of robustness in other maps. We will update the documentation and the maps in the future.
 
 ### Developer Guide
 
-* [Class Design](#)
+* [Class Design](https://radar-lab.github.io/OpenCDA-MARL/architecture/)
 * [Customize Your Algorithms](#)
-* [API Reference](#) <br>
+* [API Reference](https://radar-lab.github.io/OpenCDA-MARL/api/opencda-marl/overview/) <br>
 
 ### Contributing
 

configs/marl/intersection_td3.yaml

@@ -0,0 +1,130 @@
+# Extend fields - only these fields will extend instead of replace
+_extend_fields:
+  - "world.seed" # Add to base seed for variation
+
+description: |-
+  TD3 configuration for 4-way intersection with HIGH traffic density.
+  Twin Delayed DDPG with continuous action space for speed control.
+  This scenario focuses on intersection navigation under heavy congestion.
+
+# Demonstrate seed extension - adds variation to base seed
+world:
+  seed: 5 # This will be ADDED to default.yaml seed (11) = 16 total
+
+spectator:
+  preset: "intersection_bird_eye"
+
+meta:
+  # available scenario types: intersection
+  scenario_type: "intersection"
+  town: "intersection_12_lane_fixed"
+  # custom xodr path for this scenario
+  # xodr_path: "opencda_marl/assets/maps/intersection.xodr"
+
+# minimal scenario configuration
+scenario:
+  simulation:
+    max_steps: 2400 # 2 minute = 20fps * 60s * 2
+    max_episodes: 100
+  traffic:
+    # Traffic mode: 'record', 'replay', or 'live'
+    mode: "replay"
+    replay_file: "recordings/lite_2minL.json"
+    #replay_file: "recordings/quick_test.json"
+    base_speed: 45.0 # km/h base speed for vehicles
+    active_junctions: [4]
+
+    planner:
+      distance: 5.0 # base spacing (m)
+      spawn_offset: 7 # multiples of safe_distance upstream
+      dest_offset: 7 # multiples of safe_distance downstream
+      spawn_z_lift: 0.3 # small lift to avoid ground collision
+      wp_step: 1.0 # stepping granularity along lanes (m)
+      allow_uturn: false
+      visualize:
+        entry_wp: false
+        exit_wp: false
+        spawn_wp: false
+        dest_wp: false
+        route_line: false
+        junction_center: true
+        bbox: false
+        extent_box: true
+        text: true
+        life_time: 10.0
+
+agents:
+  debug: false
+  agent_type: "marl"
+
+  marl:
+    # Base VanillaAgent parameters
+    debug: false
+    max_speed: 65 # Maximum speed for the agent (km/h)
+    emergency_param: 0.4
+    ignore_traffic_light: true
+    collision_time_ahead: 1.5
+    local_planner:
+      trajectory_update_freq: 5
+      debug: false
+      debug_trajectory: false # Keep trajectory clean for RL
+
+MARL:
+  # Algorithm selection: q_learning, td3, sac, ppo, dqn
+  algorithm: "td3"
+
+  state_dim: 9 # Auto-calculated from custom features (9D total)
+  action_dim: 1 # Continuous speed control
+
+  # TD3 Algorithm Configuration (Multi-Agent)
+  td3:
+    # Feature configuration (9D total)
+    features:
+      rel_x: 1                        # Relative X to intersection
+      rel_y: 1                        # Relative Y to intersection
+      position_x: 1                   # Absolute X position
+      position_y: 1                   # Absolute Y position
+      lane_position: 1                # Lane position (0=intersection, 1=left, 2=middle, 3=right)
+      heading_angle: 1                # Vehicle orientation (radians)
+      dist_to_intersection: 1         # Distance to intersection
+      dist_to_front_vehicle: 1        # Distance to front vehicle
+      waypoint_buffer: 1              # Waypoint count (0-50 range)
+
+    # LSTM conflict encoder (from ITS_Sim architecture)
+    conflict_encoder:
+      type: "LSTM"
+      input_size: 9                   # From custom features (auto-calculated)
+      hidden_size: 256                # LSTM hidden dimension
+      num_layers: 1                   # LSTM layers
+
+    # Motion planner architecture (from AdvRAIM)
+    motion_planner:
+      num_layers: 5
+      input_dim: [265, 1024, 1024, 512, 256]    # First: 9 + 256 = 265
+      output_dim: [1024, 1024, 512, 256, 1]      # Final output: 1 (action)
+
+    # Learning rates - reduced for stable training
+    learning_rate_actor: 1e-3         # Actor learning rate (stable learning)
+    learning_rate_critic: 1e-3        # Critic learning rate (stable convergence)
+
+    # TD3 hyperparameters
+    tau: 0.01                         # Soft update parameter for target networks (2x faster updates)
+    discount: 0.99                    # Discount factor (gamma)
+    policy_noise: 0.2                 # Noise added to target policy during critic update
+    noise_clip: 0.3                   # Range to clip target policy noise
+    exploration_noise: 0.5            # Maximum noise for aggressive speed exploration (±21 km/h)
+    policy_freq: 2                    # Delayed policy updates (update actor every 2 critic updates)
+
+    # Training parameters
+    batch_size: 512                   # Training batch size (large for stable gradients)
+    memory_size: 300000               # Replay buffer size (large for diverse experience)
+    min_memory_size: 25000            # Minimum transitions before training starts
+    save_frequency: 1000              # Save model every N episodes
+    eval_frequency: 500               # Evaluate policy every N episodes
+
+  # Training configuration
+  training:
+    load_model: false                 # Load pre-trained model if available
+    model_dir: "models/td3/"          # Model save directory
+    enable_wandb: false               # Weights & Biases logging
+    wandb_project: "opencda_marl"     # WandB project name

dependencies/pixi/pixi_Linux_ROCm.toml

@@ -3,7 +3,7 @@ authors = ["AXIBA <leolihao@arizona.edu>"]
 channels = ["conda-forge", "pytorch", "nvidia"]
 name = "OpenCDA"
 platforms = ["linux-64"]
-version = "0.1.0"
+version = "0.1.0-alpha"
 
 [system-requirements]
 cuda = "12.8"

dependencies/pixi/pixi_winCUDA.toml

@@ -3,7 +3,7 @@ authors = ["AXIBA <leolihao@arizona.edu>"]
 channels = ["conda-forge", "pytorch", "nvidia"]
 name = "OpenCDA"
 platforms = ["win-64"]
-version = "0.1.0"
+version = "0.1.0-alpha"
 
 [system-requirements]
 cuda = "12.8"

dependencies/pixi/pixi_winRTX5090.toml

@@ -3,7 +3,7 @@ authors = ["AXIBA <leolihao@arizona.edu>"]
 channels = ["conda-forge", "pytorch", "nvidia"]
 name = "OpenCDA"
 platforms = ["win-64"]
-version = "0.1.0"
+version = "0.1.0-alpha"
 
 [system-requirements]
 cuda = "12.8"

docs/about.md

@@ -19,17 +19,19 @@ Dr. Liu Bo (Associate Professor @ UA):
 
 Lihao Guo (Ph.D. Student @ UA):
 
-- Project Lead and OpenCDA-MARL System Architect
+- Project Lead
+- OpenCDA-MARL System Architect
 - MARL Algorithm Development
 - [Homepage](https://www.lgcyaxi.net/)
 - [Linkedin](https://www.linkedin.com/in/lgcyaxi)
 
 Jiahao Tang (Ph.D. Student @ UA):
 
-- Maps
-- [Linkedin](https://www.linkedin.com/in/xu-han-12851a64/)
+- Rule-based Agent Configuration
+- [Linkedin](https://www.linkedin.com/in/jiahaotang1997/)
 
 Louis Liu (Volunteer Student @ University High School):
 
 - Map Development
-- SUMO Co-Simulation
+- Simulation Testing
+- [Linkedin](https://www.linkedin.com/in/louisliu2/)

docs/api/opencda-marl/map_manager.md

@@ -464,10 +464,4 @@ The `MARLMapManager` extends OpenCDA's map management with MARL-specific feature
     - **Complementary**: MARL manager for spawn planning, OpenCDA for perception
     - **Consistent**: Both use CARLA map data and OpenCDA utilities
     - **Flexible**: Can use MARL spawns with OpenCDA vehicles
-    - **Scalable**: Junction-based approach works for any map size
-
-## Related Documentation
-
-- **[OpenCDA Map Manager](../opencda/overview.md)**: Core rasterization and perception utilities
-- **[MARL Overview](../../marl/overview.md)**: MARL framework documentation  
-- **[OpenCDA Integration](../../opencda/core.md)**: Integration patterns with OpenCDA
+    - **Scalable**: Junction-based approach works for any map size

docs/api/opencda-marl/overview.md

@@ -361,37 +361,4 @@ for vehicle in vehicles:
 
     # Interactive CLI mode
     python opencda.py -t intersection -v 0.9.15 --marl --interactive
-    ```
-
-## Development Status
-
-=== "✅ Phase 1: Foundation (95% Complete)"
-
-    - **✅ Complete**: Core architecture, scenario system, environment interface, GUI
-    - **🔄 Remaining**: Vehicle adapter, enhanced configuration, testing framework
-
-=== "🔄 Phase 2: Agent Integration (Next)"
-
-    - **Priority**: Vehicle adapter implementation
-    - **Planned**: RL algorithm integration (PPO, MADDPG)
-    - **Goal**: End-to-end training pipeline
-
-=== "📋 Phase 3: Advanced MARL (Future)"
-
-    - Multi-agent algorithms with communication
-    - Distributed training infrastructure
-    - Advanced coordination mechanisms
-
-=== "📋 Phase 4: Research Extensions (Future)"
-
-    - Experiment management tools
-    - Benchmark scenarios and metrics
-    - Performance analysis and visualization
-
-**Related Documentation**
-
-- **[Coordinator API](coordinator.md)**: Central orchestration and execution modes
-- **[Scenario API](scenario.md)**: Template-based scenario generation and management  
-- **[Map Adapter API](adapters/map_adapter.md)**: OpenCDA-MARL map integration bridge
-- **[Implementation Guide](../../marl/implementation.md)**: Step-by-step development guide
-- **[Phase 1 Setup](../../marl/dev/phase1_setup.md)**: Current foundation status
+    ```