ProMaya Setup Guide

This guide provides step-by-step instructions for setting up the ProMaya environment and getting started with the framework. The pipeline relies heavily on PyTorch Geometric, external bioinformatics tools, and protein language models.

System Requirements

CPU

Multi-core processor (8+ cores recommended) for rapid memory-mapping and multi-threaded data extraction.

RAM

â‰¥32 GB minimum, 64 GB+ recommended for full dataset training.

32 GB+

GPU

NVIDIA GPU with 16GB+ VRAM (RTX 3090, A100, V100) for HGT and ProtTrans embeddings.

CUDA 11.8+

Environment Setup

We recommend using Conda to cleanly isolate the deep learning dependencies from system Python.

1. Create the Environment

Clone the repository and create the Conda environment. ProMaya provides a CPU base environment and an optional GPU overlay.

# Navigate to the project directory
cd /path/to/promaya

# Create the base environment from YAML (CPU-compatible)
conda env create -f environment.yml

# Activate the environment
conda activate promaya

2. Enable NVIDIA GPU Acceleration

If you are running on a Linux or Windows machine with an NVIDIA GPU, apply the GPU overlay to ensure PyTorch and PyTorch Geometric are correctly compiled with CUDA 11.8:

# Linux/Windows NVIDIA systems only
conda env update -n promaya -f environment.gpu.yml

warning "macOS Users" Do not run the GPU overlay on macOS. Apple Silicon users should rely on the base CPU environment.

3. Verify PyTorch & PyG

It is crucial that PyTorch Geometric is correctly installed with CUDA support to enable the Heterogeneous Graph Transformer (HGT) module.

python -c "import torch; print(f'PyTorch: {torch.__version__} | CUDA: {torch.cuda.is_available()}')"
python -c "import torch_geometric; print(f'PyG Version: {torch_geometric.__version__}')"

External Tools Installation

ProMaya utilizes several standard structural bioinformatics tools to compute its multimodal features. These must be installed and accessible in your system PATH.

DSSP (Secondary Structure)

Used for computing residue-level solvent accessibility and secondary structure codes.

sudo apt-get update
sudo apt-get install dssp

MSMS (Molecular Surface)

Used for triangulating the solvent-excluded surface and generating the Point Cloud features.

mkdir -p ~/tools/msms
cd ~/tools/msms
wget http://mgltools.scripps.edu/downloads/tarballs/msms_i86_64Linux2_2.6.1.tar.gz
tar -xzf msms_i86_64Linux2_2.6.1.tar.gz
echo 'export PATH=$PATH:~/tools/msms' >> ~/.bashrc
source ~/.bashrc

PSI-BLAST (PSSM Generation)

Required for generating Position-Specific Scoring Matrices (PSSMs) as evolutionary features.

# Install BLAST+
sudo apt-get install ncbi-blast+

# Download UniRef90 database (Large ~30GB compressed)
mkdir -p ~/databases/uniref90 && cd ~/databases/uniref90
wget ftp://ftp.uniprot.org/pub/databases/uniprot/uniref/uniref90/uniref90.fasta.gz
gunzip uniref90.fasta.gz
makeblastdb -in uniref90.fasta -dbtype prot -out uniref90

info "Configuration Note" Remember to update config/config.yaml to point to your uniref90 database path.

Quick Start (ProtTrans Caching)

The ProtTrans-T5-XL-UniRef50 model is a massive 3B-parameter language model. It is highly recommended to cache it locally before running the pipeline.

from transformers import T5Tokenizer, T5EncoderModel
import os

cache_dir = "./cache/prottrans"
os.makedirs(cache_dir, exist_ok=True)

print("Downloading ProtTrans model (this may take a while)...")
tokenizer = T5Tokenizer.from_pretrained(
    "Rostlab/prot_t5_xl_uniref50",
    cache_dir=cache_dir
)
model = T5EncoderModel.from_pretrained(
    "Rostlab/prot_t5_xl_uniref50",
    cache_dir=cache_dir
)
print("âœ“ ProtTrans model downloaded successfully")

Next: Review the Architecture Overview to understand how these features flow through the network.