BAGEL API Overview

BAGEL (Biomolecular Algorithm for Guidance in Energy Landscapes) is a Python library for computational protein design. It finds amino acid sequences that give rise to structures meeting specified design criteria using Monte Carlo optimization.

Architecture

BAGEL follows a modular architecture with these core concepts:

System
  └── State(s)
        ├── Chain(s) → Residue(s)
        └── EnergyTerm(s) → Oracle(s)

System — Top-level container representing the full design task. Contains one or more States.
State — A multimeric collection of Chains with associated EnergyTerms. Multiple states can share chains.
Chain — A monomeric sequence of Residues with mutability controls.
Residue — A single amino acid with a name, index, and mutability flag.
EnergyTerm — A scoring function that evaluates how well a structure meets a design criterion. Each term uses an Oracle to get structural predictions.
Oracle — An algorithm (e.g., ESMFold, ESM-2) that predicts properties from sequence (structure, embeddings).

Optimization Flow

Define your Chains with sequences and mutability
Create States grouping chains with EnergyTerms
Wrap states in a System
Choose a MutationProtocol (Canonical or GrandCanonical)
Run a Minimizer (SimulatedAnnealing, SimulatedTempering) with optional Callbacks

Module Reference

Core

Residue, Chain, State, System — the fundamental data structures.

Energies

EnergyTerm and 15+ built-in scoring functions (pTM, pLDDT, PAE, SASA, etc.).

Minimizers

Monte Carlo, Simulated Annealing, and Simulated Tempering optimizers.

Mutation

Canonical (substitution-only) and GrandCanonical (add/remove/substitute) protocols.

Oracles

Structure prediction (ESMFold) and embedding (ESM-2) oracles.

Callbacks

Logging, early stopping, structure saving, and W&B integration.

Analysis

Post-optimization analysis and visualization tools.

Import Patterns

# Core objects are available at the top level
from bagel import Chain, Residue, State, System

# Submodules for specialized classes
from bagel.energies import PTMEnergy, PLDDTEnergy, PAEEnergy
from bagel.minimizer import SimulatedAnnealing
from bagel.mutation import Canonical, GrandCanonical
from bagel.oracles.folding import ESMFold
from bagel.oracles.embedding import ESM2
from bagel.callbacks import EarlyStopping, WandBLogger, FoldingLogger

Residue

​Architecture

​Optimization Flow

​Module Reference