VESPER_CUDA

VESPER is a computational tool using local vector based algorithm that can accurately identify the global and local alignment of cryo-electron microscopy (EM) maps.

VESPER_CUDA is the CUDA accelerated version of VESPER reimplemented in Python.

VESPER Repo: https://github.com/kiharalab/VESPER \

Installation:

Choose one of the following methods to install the python environment for VESPER_CUDA.

Installation

VESPER_CUDA uses uv for Python package management. Python 3.12+ is required.

Direct Installation from GitHub

# Using uv add (recommended, records dependency in pyproject.toml)
uv add git+https://github.com/kiharalab/VESPER_CUDA.git

# Or using pip interface
uv pip install git+https://github.com/kiharalab/VESPER_CUDA.git

Development Installation

Clone the repository and install in editable mode:

git clone https://github.com/kiharalab/VESPER_CUDA.git
cd VESPER_CUDA
uv sync --all-packages --all-extras --dev

Using as a Command-Line Tool

Install VESPER directly as a command-line tool without cloning:

uv tool install git+https://github.com/kiharalab/VESPER_CUDA.git

This makes the vesper command available in your PATH. To update to the latest version:

uv tool upgrade vesper

Manual Installation

Create a virtual environment and install dependencies:

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# or: venv\Scripts\activate  # Windows

# Install VESPER using uv add (recommended over pip)
uv add git+https://github.com/kiharalab/VESPER_CUDA.git

# Or install using pip interface (legacy)
uv pip install git+https://github.com/kiharalab/VESPER_CUDA.git

# Install PyTorch for CUDA acceleration (optional)
uv add torch torchvision torchaudio

Usage

(1) Mode 1: No additional file generation is required. Only the maps used for matching are needed to run the program. ( No secondary structure matching.)

Usage: main.py orig [-h] -a A -b B [-t T] [-T T] [-g G] [-s S] [-A A] [-N N] [-S S] [-M M] [-E E]
---Options---
-h, --help  show this help message and exit
  -a {MAP1 Path}            MAP1.mrc (large)
  -b {MAP2 Path}            MAP2.mrc (small)
  -t {MAP1 Threshold}       Threshold of density map1
  -T {MAP2 Threshold}       Threshold of density map2
  -g {G}                    Bandwidth of the Gaussian filter sigma = 0.5 * G, def=16.0
  -s {Voxel Spacing}        Sampling voxel spacing def=7.0
  -A {Angle Spacing}        Sampling angle spacing def=30.0
  -N {Number}               Refine Top [int] models def=10
  -S                        Show topN models vector representation in PDB format, def=false
  -M {Mode}                 V: Vector Product mode (Default)
                            O: Overlap mode
                            C: Cross Correlation Coefficient
                            P: Pearson Correlation Coefficient
                            L: Laplacian Filtering mode
  -E                        Evaluation mode of the current position, def=false
  -o {Output Path}          Output path for the results, def=results
  -gpu {GPUID}              GPU ID to use, if not present, use CPU
  -nodup                    Remove duplicate positions using heuristics (Optional)
  -pdbin                    Input PDB file for transformation (Optional)
  -ca {Backbone PDB Path}   Query map CA atoms in PDB format for LDP recall reranking only (Optional)
  -ldp {LDP PDB Path}       Local dense point representation for LDP recall reranking only (Optional)
  -c {Thread Count}         Number of threads to use, def=2

(2) Mode 2: Probability maps generated for each secondary structure in both maps used for alignment must be generated using Emap2sec+ first and then converted into .npy format using the interpolation script before running this mode. (With Secondary structure matching.)

Usage: main.py prob [-h] -a A -npa NPA -b B -npb NPB [-t T] [-T T] [-g G] [-s S] [-A A] [-N N] [-S S] [-M M] [-E E]
[-vav VAV] [-vstd VSTD] [-pav PAV] [-pstd PSTD]
---Options---
 -h, --help  show this help message and exit
  -a A          MAP1.mrc (large)
  -npa NPA      Numpy array for Predictions for map 1
  -b B          MAP2.mrc (small)
  -npb NPB      Numpy array for Predictions for map 2
  -alpha ALPHA  The weighting parameter
  -t T          Threshold of density map1
  -T T          Threshold of density map2
  -g G          Bandwidth of the Gaussian filter def=16.0, sigma = 0.5*[value entered]
  -s S          Sampling voxel spacing def=7.0
  -A A          Sampling angle spacing def=30.0
  -N N          Refine Top [int] models def=10
  -S S          Show topN models in PDB format def=false
  -M M          V: vector product mode (default)
                O: overlap mode
                C: Cross Correlation Coefficient Mode
                P: Pearson Correlation Coefficient Mode
                L: Laplacian Filtering Mode
  -E E          Evaluation mode of the current position def=false
  -vav VAV      Pre-computed average for density map
  -vstd VSTD    Pre-computed standard deviation for density map
  -pav PAV      Pre-computed average for probability map
  -pstd PSTD    Pre-computed standard deviation for probability map

Identify the best fitting of two EM maps.

Run VESPER in either probability or original mode.

Output Format:

By default, VESPER_python writes the vector information for each of top 10 models after local refinement into VESPER output. Vector information for the first model starts with two lines like the ones shown below.

Overlap= 0.02156028368794326 76/3525 CC= 0.012639913 PCC= -0.09214708 Scoreplusprob= 0.00019255988782371103 Scoreprobonly= 3.5619823131948194e-05
Score=  58.680508

Score shows the DOT score, which is the summation of dot products of matched vectors between two maps. Scoreplusprob shows the normalized score which is the sum of the normalized dot score as well as the normalized probability dot score. Scoreprobonly represents only the normalized probability dot score.

Visualizing the transformed positions of the query maps.