FluidPlanner

Hierarchical planning via multi-scale reaction-diffusion PDEs.

3 PDE levels with decreasing diffusion rates create a natural temporal hierarchy:

• Level 2 (slow diffusion D=0.01): global plan (quasi-static objective field)
• Level 1 (medium diffusion D=0.05): sub-goals (tactical waypoints)
• Level 0 (fast diffusion D=0.15): local actions (motor commands)

Top-down forcing connects levels: Level 2 injects into Level 1, which injects into Level 0. The hierarchy emerges from diffusion time constants, not from manual design.

Quick Start

pip install -e .

# Train FluidPlanner (hierarchical PDE)
python experiments/train.py --model fluid --epochs 100 --grid-size 16

# Train flat baseline (no hierarchy, same param budget)
python experiments/train.py --model flat --epochs 100 --grid-size 16

# Visualize results
python experiments/serve_viz.py --checkpoint checkpoints/best_fluid.pt
# Open http://localhost:8080

Architecture

Input: Grid (6ch x 16x16) -- walls, key, door, goal, agent, empty
  |
  v
Encoder: Conv2d -> d_model features
  |
  +---> Level 2 PDE (D=0.01, slow)  -- "go to the goal"
  |       | top-down forcing
  +---> Level 1 PDE (D=0.05, medium) -- "get the key first"
  |       | top-down forcing
  +---> Level 0 PDE (D=0.15, fast)   -- "move left"
  |
  v
Action Head: features at agent position -> 4-way action logits

Task

Grid world with key-door-goal mechanics:

1. Navigate to the key (K)
2. Pick it up (automatic on contact)
3. Navigate to the door (D) to unlock it
4. Navigate to the goal (G)

Optimal trajectories generated by A*. Training via imitation learning.

Monitoring

tensorboard --logdir runs/

Key metrics:

• Eval/Solve_Rate: fraction of test mazes solved
• Val/Action_Acc: per-step action prediction accuracy
• Val/Phase_Acc: does the model know which sub-goal it is pursuing?

Visualization Dashboard

The HTML dashboard (serve_viz.py) shows:

• Grid world with agent path (red) vs optimal path (green)
• PDE field activations at all 3 levels (RGB = first 3 feature channels)
• Action probability distribution
• Phase detection (Key / Door / Goal)
• Trajectory comparison (model vs optimal step count)

Relation to FluidWorld

FluidPlanner extends the reaction-diffusion substrate from FluidWorld (video prediction) to hierarchical planning. The core PDE is the same; the innovation is multi-scale temporal separation via diffusion rate hierarchy.

Author

Fabien Polly (Infinition)