How a4bio/pifold works
Project type and purpose
• PiFold is an open-source research tool (Python library + CLI) for protein inverse folding (“given a 3D protein backbone, predict a sequence that will fold into it”).
• It’s not a web or full-stack app, but a scientific/ML pipeline with components for data loading, feature construction, GNN-based modeling, training, evaluation, and fixed-backbone design.
File structure
• Top level:
• main.py & parser.py – CLI entry point and argument parsing
• API/ – data‐loading, featurization, recording, utility routines
• methods/ – core model definitions (PiGNN layers), training scheduler, ProDesign legacy code
• utils/ – orchestration helpers (experiment setup, logging, simulation design)
• assets/ – paper PDF and framework/result screenshots
• example/ – sample input PDB file
• Look for patterns:
• API handles “I/O → feature → batch” pipeline
• methods encapsulate “model architecture → forward pass → loss”
• main.py glues API + methods + utils into end-to-end runs
• parser.py isolates CLI interface from implementation
README for additional insights
• Describes high-level framework: input (protein structure) → residue featurizer (virtual atoms + learned features) → PiGNN layers (node/edge/global contexts) → one-shot sequence decoder → evaluation on CATH, TS50, TS500.
• Mentions ablations, benchmarking, fixed backbone design use-case.
1. CLI Layer
– main.py & parser.py (argument parsing, run modes: train / design / benchmark)
2. Data Layer (API)
– Dataset loaders: CATH, TS datasets (cath_dataset.py, ts_dataset.py)
– Dataloaders (dataloader.py, dataloader_gtrans.py)
– Featurizer (featurizer.py)
– Recorder & utils (recorder.py, utils.py)
3. Model Layer (methods)
– BaseMethod abstraction (base_method.py)
– PiGNN modules (prodesign_module.py, prodesign_model.py)
– Optim scheduler & training loop (optim_scheduler.py, utils.py)
4. Utility Layer (utils)
– Experiment orchestration & logging (main_utils.py)
– Simulation/design‐specific helpers (simdesign_utils.py)
5. External Dependencies & Data
– PyTorch / TorchGeometric (implied)
– CATH, TS50/TS500 datasets
– Example PDB files
– CLI → Parser → Experiment config
– CLI uses API.DataLayer to load and batch data
– API.Featurizer → emits graph representations to ModelLayer
– ModelLayer (PiGNN) → outputs logits/sequence predictions
– OptimScheduler → updates ModelLayer parameters
– Recorder & Utils capture metrics, save checkpoints
– CLI triggers evaluation on held-out TS datasets; fixed-backbone design path reads a PDB, runs forward only
c. Architectural patterns & design principles:
– Layered architecture (CLI / Data / Model / Utils)
– Modular design: clear separation of concerns (I/O vs. computation vs. orchestration)
– Abstract base class (BaseMethod) for easy swapping or extending methods
– One-shot generation pattern (non-autoregressive inference)
d. Key technologies & libraries:
– Python 3.x
– PyTorch (+ TorchGeometric for GNN layers)
– NumPy, SciPy for feature ops
– Click or argparse for CLI (parser.py)
– Standard ML tooling (logging, checkpointing)