Migration Guide

Migration Guide#

This guide helps you migrate from the old development setup to the new pip-installable Clay package.

What Changed?#

Clay Foundation Model is now available as a proper Python package called claymodel. This means:

  • ✅ Easy installation: pip install git+https://github.com/Clay-foundation/model.git

  • ✅ Clean imports: from claymodel.module import ClayMAEModule

  • ✅ Better distribution: No need to clone the entire repository for inference

Import Changes#

Before (Old)#

# Old development imports
from src.datamodule import ClayDataModule
from src.module import ClayMAEModule
from src.model import ClayMAEEncoder

After (New)#

# New package imports
from claymodel.datamodule import ClayDataModule
from claymodel.module import ClayMAEModule
from claymodel.model import ClayMAEEncoder

Installation Methods#

For Development & Training#

If you need to train models or contribute to development:

# Clone repository
git clone https://github.com/Clay-foundation/model.git
cd model

# Create environment
mamba env create --file environment.yml
mamba activate claymodel

# Install in development mode
pip install -e .

Code Migration Examples#

Loading Pretrained Models#

# Before
import sys
sys.path.append('path/to/model/src')
from module import ClayMAEModule

# After
from claymodel.module import ClayMAEModule

Generating Embeddings#

# Before
from src.module import ClayMAEModule

# After
from claymodel.module import ClayMAEModule

# Usage is the same
model = ClayMAEModule.load_from_checkpoint("clay-v1.5.ckpt")
embeddings = model.encoder(chips, timestamps, wavelengths)

Training Workflows#

Training workflows require the full development environment:

# Before
from src.datamodule import ClayDataModule
from src.module import ClayMAEModule

# After (development install)
from claymodel.datamodule import ClayDataModule
from claymodel.module import ClayMAEModule

Jupyter Notebooks#

All tutorial notebooks have been updated to use the new imports:

  • ✅ docs/tutorials/embeddings.ipynb

  • ✅ docs/tutorials/reconstruction.ipynb

  • ✅ docs/tutorials/wall-to-wall.ipynb

  • ✅ docs/tutorials/inference.ipynb

Troubleshooting#

Import Errors#

If you see ModuleNotFoundError: No module named 'claymodel':

  1. Ensure you’ve installed the package: pip install git+https://github.com/Clay-foundation/model.git

  2. Restart your Python kernel/session

  3. Check installation: pip list | grep claymodel

Old Notebooks#

If you have old notebooks with from src imports:

  1. Replace from src. with from claymodel.

  2. Ensure claymodel is installed

  3. Update any hardcoded paths

Development Setup#

For development work, you still need the full repository:

git clone https://github.com/Clay-foundation/model.git
cd model
mamba env create --file environment.yml
mamba activate claymodel
pip install -e .

Benefits of Migration#

  • Easier deployment: No need to manage source paths

  • Cleaner environments: Proper dependency management

  • Better portability: Code works across different setups

  • Professional packaging: Follows Python packaging best practices

Need Help?#

Contents