Fix issue #105: test.ipynb fails on fresh setup due to missing pretrained weights and grid artifacts

[iamsarvrath]

Fix issue #105: test.ipynb fails on fresh setup due to missing pretrained weights and grid artifacts

Problem

When running test.ipynb on a fresh environment, the notebook fails with FileNotFoundError when attempting to load pretrained artifacts that are not present in the repository. The README did not document where these files should be obtained from, whether they are pretrained or generated locally, or what steps a new user should follow to run test.ipynb end-to-end.

Solution

This PR addresses the issue by:

1. Adding a file validation cell in test.ipynb that checks for all required files before attempting to load them
2. Providing clear, actionable error messages when files are missing
3. Updating the README with comprehensive documentation on prerequisites and how to obtain required files

Changes Made

test.ipynb

• Added import: Added import os to support file path operations
• Added validation cell (Cell 4): New setup cell that:
  • Defines GRID_MATRICES_DIR = 'grid_matrices' to fix the undefined variable error
  • Checks for all required grid matrix files in grid_matrices/ directory:
    • scatter_to_log_128.pt
    • forward_from_log_128.pt
    • scatter_from_log_128.pt
    • sparse_grid_fracs_euclid_backward.pt
  • Checks for pretrained weights: vdl_weights.pt
  • Provides clear error messages with instructions if files are missing:
    • For grid matrices: Lists which notebooks can regenerate them
    • For pretrained weights: Explains how to train the model or obtain from repository releases
• Updated file loading (Cell 7): Modified all torch.load() calls to use os.path.join(GRID_MATRICES_DIR, ...) for correct path resolution to the grid_matrices/ subdirectory

README.md

• Added new section: "Running test.ipynb" with:
  • List of all required files and their expected locations
  • Instructions for obtaining vdl_weights.pt:
    • Training command: python train.py --exp-name vdl
    • Alternative: Download from repository releases (if available)
  • Instructions for regenerating grid matrices:
    • create_log_grid.ipynb → generates scatter_to_log_128.pt
    • create_log_forward_grid.ipynb → generates forward_from_log_128.pt
    • create_log_crop_grid.ipynb → generates scatter_from_log_128.pt
    • create_backward_grid.ipynb → generates sparse_grid_fracs_euclid_backward.pt
  • Quick start guide for running the notebook

Expected Behavior After This Fix

New contributors will now:

• See clear, informative error messages if required files are missing
• Understand exactly which files are needed and where to find them
• Have step-by-step instructions to obtain or generate all prerequisites
• Be able to successfully run test.ipynb after following the documented setup steps

Testing

• The validation cell properly checks for all required files
• Error messages are clear and actionable
• File paths correctly resolve to grid_matrices/ subdirectory
• No changes to existing functionality when all files are present

Related Issue

Fixes #105

[kunalsanga]

Thanks for the thorough fix and clear documentation!

The setup cell and README updates address the issue perfectly and will make
test.ipynb much more accessible for new contributors.

Really appreciate you taking this up so quickly.