cs534team3

Team 3 Project for CS 534 in Spring 2026

---

Neural A* Implementation — Bindu

The implementation of Neural A* is based on the official repository: https://github.com/omron-sinicx/neural-astar

Ryo Yonetani et al., "Path Planning using Neural A* Search", ICML 2021.

Neural A* is a data-driven search-based planner that combines a trainable CNN encoder with a differentiable A* search module. It learns from path demonstrations to improve the trade-off between search optimality and efficiency.

---

Setup

Step 1 — Clone the neural-astar source into the project (mirrors VIN branch approach):

# From the repo root, on the NAstar branch
git clone https://github.com/omron-sinicx/neural-astar.git neural-astar

This places the source at neural-astar/ alongside nastar/. All scripts automatically detect and prefer this local clone over the Docker-installed package via sys.path.

Step 2 — Build and enter the Docker container:

docker build -t cs534team3 docker/
docker run --gpus all -it --rm -v $(pwd):/workspace/cs534team3 cs534team3
cd /workspace/cs534team3
source /opt/venv_main/bin/activate

Step 3 — Install the local clone (once inside Docker):

pip install -e neural-astar/

Note: The Docker image already clones and installs neural-astar at /workspace/neural-astar. The local clone (neural-astar/ in this repo) takes priority when running scripts from the repo root, giving you full control over the source without modifying the Docker image.

---

1. Download the Dataset

The neural-astar package ships with a maze dataset at: /workspace/neural-astar/planning-datasets/data/mpd/mazes_032_moore_c8.npz

You can also download the team's forest dataset:

bash download_forest.sh

---

2. Train Neural A*

python nastar/train.py --datafile /workspace/neural-astar/planning-datasets/data/mpd/mazes_032_moore_c8

Key arguments:

Argument	Default	Description
--datafile	(required)	Path to .npz dataset (without extension)
--lr	0.001	Learning rate
--epochs	50	Number of training epochs
--batch_size	100	Batch size
--Tmax	0.25	Max search budget (fraction of map size)
--encoder_input	m+	Input to encoder: m=map, m+=map+goal
--encoder_depth	4	Number of CNN layers
--logdir	model/	Directory to save checkpoints
--seed	1234	Random seed

---

3. Evaluate (Run Inference)

# Evaluate trained Neural A*
python nastar/run.py \
    --datafile /workspace/neural-astar/planning-datasets/data/mpd/mazes_032_moore_c8 \
    --modeldir model \
    --planner na

# Evaluate Vanilla A* baseline
python nastar/run.py \
    --datafile /workspace/neural-astar/planning-datasets/data/mpd/mazes_032_moore_c8 \
    --planner astar

Reported metrics:

• p_opt — fraction of planned paths matching the optimal length
• p_exp — search efficiency: how many fewer nodes expanded vs. vanilla A*
• h_mean — harmonic mean of p_opt and p_exp (primary benchmark metric)

---

4. Visualize Results

python nastar/visualize.py \
    --datafile /workspace/neural-astar/planning-datasets/data/mpd/mazes_032_moore_c8 \
    --modeldir model \
    --num_examples 8 \
    --savedir results

Results are saved to results/example_XXXX.png and a results/summary_grid_*.png.

---

5. Quick Test (Smoke Test)

# No dataset or trained model required
python nastar_test.py

# Also test real data loading
python nastar_test.py --datafile /workspace/neural-astar/planning-datasets/data/mpd/mazes_032_moore_c8

---

Dataset Format

Arrays	Split	Contents
arr_0–arr_3	Train (800)	maps, goals, directions, distances
arr_4–arr_7	Val (100)	maps, goals, directions, distances
arr_8–arr_11	Test (100)	maps, goals, directions, distances

---

Notes

• All scripts use sys.path to prefer the local neural-astar/ clone if present, falling back to the Docker-installed package automatically.
• GPU is recommended for training. CPU works fine for inference and smoke testing.
• No patching of the neural-astar source is needed (the minimal branch is Python 3 compatible).

---

VIN Implementation — Robert

The implementation of VIN is derived from the following GitHub repository: https://github.com/zuoxingdong/VIN_PyTorch_Visdom

Using this VIN implementation as a foundation, several fixes were applied to make it compatible with Python 3 and more recent NumPy/PyTorch versions.

Fixes applied:

• dataset.py: f.items()[0][1][idx] → list(f.items())[0][1][idx] (Python 3 compatibility); added allow_pickle=True to np.load() (modern NumPy requirement)
• VIN.py: Added v = v.unsqueeze(1) to fix (B,H,W) → (B,1,H,W) shape mismatch; updated v.data[0] → v.data[0,0] for 4D tensor indexing
• run.py: loss.data[0] → loss.item() (modern PyTorch compatibility)
• Added CPU/GPU compatibility — runs on CPU if no CUDA device is available (note: ~9 s/epoch on CPU for 8×8 world)
• Replaced visdom with matplotlib for visualisation (visualize.py)

To Run

# 1. Create and activate a virtual environment, install PyTorch, NumPy, matplotlib
# 2. cd into the local vin repo
# 3. Train on 8x8 gridworld:
python run.py --datafile data/gridworld_8x8.npz --imsize 8 --lr 0.005 --epochs 30 --k 10 --batch_size 128

# Or train on 28x28 gridworld:
python run.py --datafile data/gridworld_28x28.npz --imsize 28 --lr 0.003 --epochs 30 --k 36 --batch_size 128

# 4. Visualize results (saved as learned_rewards_values in the same directory):
python visualize.py