Evo 2

The phage_gen/ directory provides a suite of scripts and pipelines for designing, analyzing, and visualizing phage genomes. Key capabilities include:

• Analysis: Competition sequencing analysis, mutation classification (syn/nonsyn/indel/intergenic), genome annotation (ORF prediction and MMseqs2 search), and Shannon diversity analysis.
• Design & Assembly: Automated Gibson assembly fragment design from genome sequences.
• Pipelines: Filtering pipelines for genome design and genetic architecture similarity scoring.
• Visualization: Genome visualization using LoVis4u.
• Data: Access to reference genomes (e.g., PhiX174), AI-generated phage collections (viable and nonviable), and wild/lab-evolved isolates.

The project provides specific Conda environment files for different tasks within the phage design workflow. You can use these to ensure all dependencies are correctly installed for your specific task:

• competition_analysis.yaml: For phage competition sequencing analysis.
• genome_annotator.yaml: For genome annotation tasks.
• genome_design.yaml: For the main genome design pipeline.
• genome_visualization.yaml: For genome visualization.

To evaluate a model other than Evo 2, follow these steps:

1. Use prompts.py to generate the appropriate prompts for the chosen panel.
2. Generate completions using your model.
3. Score the completions using the score_prokaryote or score_eukaryote functions located in scoring.py.

You can run the benchmark for any Evo 2 model using the run_gene_completion.py script. The benchmark is split into two panels: prokaryote and eukaryote.

• Prokaryote / archaea panel: Does not require external tools like exonerate.
• Eukaryote panel: Requires exonerate to be installed for splice-aware scoring.

Each run generates per-generation scores (*_completions.csv) and per-gene summary statistics (*_per_gene_stats.csv).

cd scripts/gene_completion

# Prokaryote / archaea panel (no external tools needed)
python run_gene_completion.py --panel prokaryote --model_name evo2_7b \
    --output_dir out/evo2_7b

# Eukaryote panel (requires exonerate)
python run_gene_completion.py --panel eukaryote --model_name evo2_7b \
    --output_dir out/evo2_7b

You can run Evo 2 in a containerized environment using Docker. Use a volume mount to preserve downloaded models between runs.

1. Build the image: docker build -t evo2 .
2. Run the container: docker run -it --rm --gpus '"device=0"' -v ./huggingface:/root/.cache/huggingface evo2 bash
3. Verify inside the container: python -m evo2.test.test_evo2_generation --model_name evo2_7b

docker build -t evo2 .
docker run -it --rm --gpus '"device=0"' -v ./huggingface:/root/.cache/huggingface evo2 bash

# Inside container:
python -m evo2.test.test_evo2_generation --model_name evo2_7b

If you only need to run the 7B models (evo2_7b, evo2_7b_262k, or evo2_7b_base), you can use a light installation that does not require Transformer Engine or FP8-capable hardware.

Note: A compatible PyTorch must be installed before installing Flash Attention.

# Example: pip install torch==2.7.1 --index-url https://download.pytorch.org/whl/cu128
pip install flash-attn==2.8.0.post2 --no-build-isolation
pip install evo2

For the full installation, which supports all model sizes (including 40B, 20B, and 1B) using FP8 via Transformer Engine on Nvidia Hopper GPUs, follow these steps. It is recommended to use conda for Transformer Engine installation.

Prerequisites:

• CUDA 12.1+ with compatible NVIDIA drivers
• cuDNN 9.3+
• GCC 9+ or Clang 10+ (C++17 support)
• Python 3.11 or 3.12
• A compatible PyTorch version (e.g., 2.6.x or 2.7.x)

conda install -c nvidia cuda-nvcc cuda-cudart-dev
conda install -c conda-forge transformer-engine-torch=2.3.0
pip install flash-attn==2.8.0.post2 --no-build-isolation
pip install evo2

To run the Gene Completion benchmark, you must first install Evo 2 (refer to the main repository README). Additionally, install the following scoring dependencies:

• biopython: Required for protein alignment and translation.
• exonerate: Required only for the Eukaryote panel to handle splice-aware alignment.

pip install biopython            # protein alignment + translation
conda install -c bioconda exonerate   # required for the eukaryote panel only

Use the Evo2 class to load genome models. It automatically handles downloading checkpoints from HuggingFace if they are not found locally.

Key considerations:

• Multi-GPU: For large models like evo2_40b, the model will automatically split across available GPUs. Use CUDA_VISIBLE_DEVICES to control which GPUs are used. Do not call .to(device) manually.
• Acceleration: Set use_kernels=True to enable Vortex's opt-in Triton kernels for Hyena convolutions (HC{S,M,L}). This requires vtx>=1.1.0.
• FP8 Support: Some models require transformer_engine for FP8 input projections. If not installed, the 7b model will fall back to bf16, but larger models may raise an ImportError.

To run the BRCA1 zero-shot prediction notebook, you need to install the following Python packages:

!pip install matplotlib pandas seaborn scikit-learn openpyxl