Repository navigation
Version 2 Install or Updates
Hi! To mamp-ml both more stable and easier to use, I have completely refactored much of the code.
mamp-ml runs three places: in Google Colab (zero install), on a local Linux + NVIDIA GPU box, and on an HPC cluster.
Below covers each path plus how to recover from a broken install.
| You want to… | Run this |
|---|---|
| Try the tool with no install | Open the Colab notebook |
| Install for normal use | pip install git+https://github.com/DanielleMStevens/mamp-ml.git@version2 |
| Install with ESMFold (no ColabFold needed) | pip install "mamp-ml[esmfold] @ git+https://github.com/DanielleMStevens/mamp-ml.git@version2" |
| Install everything (package + ColabFold) | git clone --branch version2 …mamp-ml.git && cd mamp-ml && bash install_software.sh |
| Install for code edits | git clone --branch version2 …mamp-ml.git && cd mamp-ml && pip install -e .[esmfold,dev] |
| Upgrade an existing install | pip install --upgrade --force-reinstall git+https://github.com/DanielleMStevens/mamp-ml.git@version2 |
- Python 3.9 – 3.12
- NVIDIA GPU with CUDA (RTX 3070 or better; A5000+ for big jobs). CPU runs are possible but impractically slow for real workloads
- 16 GB RAM minimum, 16 GB VRAM recommended
- ~10 GB free disk if you install ColabFold locally; ~3 GB without it
Click the Colab badge in the README, upload your spreadsheet, run cells in order. The notebook handles every install step itself, including the JAX version pinning ColabFold needs.
pip install git+https://github.com/DanielleMStevens/mamp-ml.git@version2This gives you the mamp-ml console command, the bundled pretrained checkpoint (mamp_ml_weights.pth, ~33 MB), and every Python dependency. You'll still need ColabFold separately for structure folding — unless you use
the ESMFold backend:
pip install "mamp-ml[esmfold] @ git+https://github.com/DanielleMStevens/mamp-ml.git@version2"
mamp-ml predict input.xlsx --structure esmfold --device cuda ESMFold runs in-process; no separate conda env.
git clone --branch version2 https://github.com/DanielleMStevens/mamp-ml.git
cd mamp-ml
bash install_software.shThis creates a fresh mamp-ml conda env, installs the Python package in editable mode, and auto-detects your OS to run the right ColabFold installer (scripts/install_colabbatch_linux.sh on Linux, …_mac.sh on macOS).
After install:
conda activate mamp-ml
export PATH="$(pwd)/localcolabfold/colabfold-conda/bin:$PATH"
mamp-ml predict input.xlsx --device cuda On a shared cluster where you don't have root or write access to system Python:
# Load whatever Python module your cluster provides (3.9 – 3.12 are all fine)
module load python/3.11
# Clone + install to your user directory
git clone --branch version2 https://github.com/DanielleMStevens/mamp-ml.git
cd mamp-ml
pip install --user -e .
# Or with ESMFold support
pip install --user -e .[esmfold] Then run from a GPU node — adjust to your cluster's scheduler:
# Slurm
srun --gres=gpu:1 --mem=32G mamp-ml predict input.xlsx --device cuda
# Or interactively
salloc --gres=gpu:1 --mem=32G
mamp-ml predict input.xlsx --device cuda If mamp-ml is not found after install, your user pip bin directory isn't on $PATH. Fix:
export PATH="$(python -m site --user-base)/bin:$PATH" Add that line to your ~/.bashrc to make it persistent.
# editable clone
cd mamp-ml
git pull
pip install -e . # re-resolves any new dependencies
# pip install from GitHub
pip install --upgrade --force-reinstall \
git+https://github.com/DanielleMStevens/mamp-ml.git@version2Add --user to either form on an HPC cluster.
If mamp-ml predict fails with an ImportError, the most common culprits and fixes:
# openpyxl too old (pandas 2.x needs >= 3.1.0)
pip install --upgrade "openpyxl>=3.1.0"
# numpy 2.x breaking the scientific stack
pip install "numpy<2"
# torch/transformers drift
pip install --upgrade --force-reinstall \
git+https://github.com/DanielleMStevens/mamp-ml.git@version2# 1. Uninstall the Python package
pip uninstall -y mamp-ml
# 2. Clear pip's cache (forces fresh downloads next time)
pip cache purge
# 3. If you used the conda env, remove it
conda env remove -n mamp-ml
# 4. Reinstall from scratch (pick one path from "Install scenarios")
pip install git+https://github.com/DanielleMStevens/mamp-ml.git@version2 If ColabFold's env got corrupted but the Python package is fine:
cd mamp-ml
rm -rf localcolabfold/ # wipe the broken install
bash scripts/install_colabbatch_linux.sh # or _mac.sh on macOSThis creates a fresh localcolabfold/colabfold-conda/ env without touching the mamp-ml Python package.
If ESMFold or ESM-2 downloads keep stalling or you suspect a corrupt download:
# Default HuggingFace cache
rm -rf ~/.cache/huggingface
# Or wherever HF_HOME points
rm -rf "$HF_HOME" Next mamp-ml predict invocation re-downloads.
# 1. CLI is reachable
mamp-ml --help
# 2. Bundled weights are present
python -c "from mamp_ml.weights import default_weights_path; p = default_weights_path(); assert p.is_file(); print('weights ok:', p)"
# 3. Run a tiny smoke test
mamp-ml prepare-fasta example_data.xlsx /tmp/test.fasta
head /tmp/test.fasta All three succeed → install is healthy.
| Error | Fix |
|---|---|
Pandas requires version '3.1.0' or newer of 'openpyxl' |
pip install --upgrade "openpyxl>=3.1.0" |
jax_cuda12_plugin version 0.7.x is not compatible with the installed jaxlib version 0.5.3 (Colab) |
The notebook's install cell pins jax[cuda12]==0.4.35; re-run that cell so the pin lands before colabfold_batch is |
| invoked | |
command not found: mamp-ml (after pip install --user) |
export PATH="$(python -m site --user-base)/bin:$PATH" |
RuntimeError: CUDA out of memory during folding |
Use --structure esmfold (less memory than ColabFold) or fold one receptor at a time |
urllib.error.HTTPError during ColabFold MSA fetch |
ColabFold's MSA server is rate-limited; wait 10–15 min and retry, or set up local MMseqs2 |
predictions.csv not produced after mamp-ml predict
|
Check that intermediate_files/ready_test_data.csv was created; if so, the ESM-2 inference step failed — scroll up in the log for the real traceback |
ModuleNotFoundError: No module named 'transformers' when using --structure esmfold
|
You installed mamp-ml without the [esmfold] extra — pip install "mamp-ml[esmfold]"
|