Practical overview
When it fits
Use the repository when you want to inspect or adapt a research workflow for protein conformation sampling, structure-data preparation, or model training rather than access a hosted generation interface.
Who it is for
- Protein-structure researchers exploring conformation-generation methods.
- Developers prototyping experiments with discrete representations and sequence-conditioned structure models.
Documented uses
- Generate protein conformation samples from an input target using an ESMDiff checkpoint.
- Inpaint masked positions using pretrained ESM3 through the documented sampling script.
- Preprocess PDB/mmCIF structures and compute VQ-VAE encodings for training.
- Fine-tune protein language models for task-specific conformation-generation experiments.
Requirements & limits
The README requires a Hugging Face account, acceptance of the ESM3-open non-commercial license, and a read-permission API key to download ESM3 weights. It describes the repository code and ESMDiff model as available for non-commercial use; ESM3 components follow the Biohub/ESM license.
- The README documents Python 3.10 installation with Conda and pip, and identifies PyTorch, PyTorch Lightning, and Hydra in the stack.
- Inference examples require an input target and checkpoint; the ESMDiff checkpoint is linked separately for download.
- Training examples use encoded structure data, while structure downloading and preprocessing are optional when suitable data is already available.
- The README directs users to the analysis directory for evaluation details.
Check current requirements in the official documentation. Source-based guidance does not mean OpenViST has run or independently tested this project.
Install Esmdiff and configure ESM3-open
Set up the local Python environment and configure access to ESM3-open weights.
Before you start
- Conda
- Python 3.10
- A Hugging Face account
- Acceptance of the ESM3-open non-commercial license and a read-permission Hugging Face API key
Steps
Create and activate the Python 3.10 Conda environment.
Install the repository requirements and install the package locally.
Accept the ESM3-open license on Hugging Face and obtain a read-permission API key.
Use the documented Hugging Face login flow to configure access.
Expected outcome
A locally installed project environment with Hugging Face access configured for ESM3-open weights.
Guide limitations
- The README states that ESM3 weights require license acceptance and a Hugging Face account.
- ESM3-related components are subject to the Biohub/ESM license; the repository describes its code and ESMDiff model as non-commercial.
Prepare structure data for model training
Preprocess PDB/mmCIF structures and compute encodings that the training examples use.
Before you start
- The Esmdiff repository installed in a Python environment
- PDB structure files, or the optional PDB database download
- Biopython 1.79 for the documented mmCIF parsing stage
Steps
Optionally download the PDB mmCIF database using the repository script.
Preprocess mmCIF files into per-chain structures with the documented preprocessing script.
Return Biopython to version 1.84 for main usage, as directed in the README.
Run the encoding script on processed structures or on a PDB dataset to create VQ-VAE encodings.
Expected outcome
Preprocessed structure data and encoded files suitable for the repository’s documented training data paths.
Guide limitations
- Downloading and preprocessing the whole PDB database is optional; the README also shows encoding a dataset of PDB files already on hand.
- Biopython 1.79 is specified for mmCIF parsing, followed by a return to 1.84 for main usage.
Sources & review
Source record details
- Source availability
- Active
- Sources checked
- 18 October 2026
- Original website title
- lujiarui/esmdiff · Official homepage title · retained in its source language