GitHub - ruihong04/OverhangTower: An interactive block-stacking environment for studying how sequential physical planning adapt under cognitive resource constraints. (original) (raw)

Overhang Tower: Resource-Rational Adaptation in Sequential Physical Planning

CogSci 2026

Codebase structure

The repository contains:

1. The core Overhang Tower environment and physics utilities.
2. A human behavioral experiment app (interactive_env).
3. Computational planning models (neural_planning) with interchangeable planning policies and stability predictors.
4. A visual heuristic model pipeline (heuristic_models) trained from generated tower states.

.
├── tower_core.py                  # Overhang Tower state, physics simulator, reward
├── tower_generator_random.py      # Random stable tower generation
├── tower_generator_bruteforce.py  # Brute-force search for near-optimal towers (data/bruteforce/*)
├── render_heuristic_dataset.py    # Build image shards for CNN heuristic training
├── heuristic_models/
│   ├── model.py                   # CNN backbones + preprocessing
│   ├── inference.py               # Checkpoint loading and batched inference
│   ├── dataset.py                 # Metadata-based dataset loader
│   └── train.py                   # Heuristic model training
├── neural_planning/
│   ├── cli.py                     # Main planning/evaluation entry
│   ├── planners.py                # Planning policies (myopic/deliberative)
│   ├── scorers.py                 # Stability scorers (CNN / GT / IPE / mixed)
│   ├── proposers.py               # Action proposal
├── interactive_env/
     ├── server.py                  # Human experiment web server

Setup

Install python dependencies.

pip install -r requirements.txt

Install redis for task queue.

sudo apt install redis-server nginx apache2-utils -y sudo systemctl enable redis-server sudo systemctl start redis-server

For visual heustics model training, you need to install pytorch,torchvision and timm.

pip install torch torchvision timm

Usage

1) Generate tower states

Generate random rollouts (used for heuristic model data):

python tower_generator_random.py
--config_path data/train_configs_n6_100.npy
--num_tasks 100
--target_towers 200
--save_dir data/random/train

Generate brute-force near-optimal towers (typically for practice ground-truth):

python tower_generator_bruteforce.py
--config_path data/practice_configs_n6_3.npy
--num_tasks 3
--save_dir data/bruteforce/practice
--grid_step 0.1
--num_workers 8

2) Render heuristic training images

Create image shards from generated towers.npz files:

python render_heuristic_dataset.py
--config_paths data/train_configs_n6_100.npy
--tower_output_dirs data/random/train
--training_samples 200000
--num_split 8
--split_idx 0
--out_dir data/heuristic/train

Run this command for all split_idx values (0..num_split-1), then combine:

python utils/combine_shards.py --root_dir data/heuristic/train

After combining, data/heuristic/train should contain:

• images/
• metadata.npz
• labels.npy

3) Train the visual heuristic model

python -m heuristic_models.train
--data_root data/heuristic/train
--output_dir outputs/heuristic/resnet50
--model resnet50_pretrained
--epochs 10
--batch_size 128

4) Run neural planning experiments

With CNN scorer:

python -m neural_planning
--config_path data/formal_configs_n6_40.npy
--out_dir outputs/neural_planning
--num_tests 100
--algo d_greedy
--depth 2
--scorer cnn
--checkpoint outputs/heuristic/resnet50/best.pt

With IPE scorer:

python -m neural_planning
--config_path data/formal_configs_n6_40.npy
--out_dir outputs/neural_planning_prob
--num_tests 100
--algo d_greedy
--depth 2
--scorer prob
--sigma 0.03
--prob_k 50

5) Launch the human experiment server

interactive_env/server.py loads practice/formal configs and serves the web UI.

cd interactive_env python server.py
--config_path ../data/formal_configs_n6_40.npy
--practice_config_path ../data/practice_configs_n6_3.npy
--host 127.0.0.1
--port 5000

Then open http://127.0.0.1:5000.

Notes:

1. Redis must be running before starting the server.
2. Ground-truth lookup for the practice "Show Near-Optimal Solution" button defaults to:data/bruteforce/practice/<task_uuid>/...

Citation

@inproceedings{shen2026overhangtower,
  title={Overhang Tower: Resource-Rational Adaptation in Sequential Physical Planning},
  author={Shen, Ruihong and Li, Shiqian and Zhu, Yixin},
  booktitle={Proceedings of the Annual Meeting of the Cognitive Science Society (CogSci)},
  year={2026},
}