Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

espaloma: Extensible Surrogate Potential Optimized by Message-passing Algorithms 🍹

CI Total alerts Language grade: Python docs stable

Source code for Wang Y, Fass J, and Chodera JD "End-to-End Differentiable Construction of Molecular Mechanics Force Fields."



Paper Abstract

Molecular mechanics (MM) potentials have long been a workhorse of computational chemistry. Leveraging accuracy and speed, these functional forms find use in a wide variety of applications in biomolecular modeling and drug discovery, from rapid virtual screening to detailed free energy calculations. Traditionally, MM potentials have relied on human-curated, inflexible, and poorly extensible discrete chemical perception rules atom types for applying parameters to small molecules or biopolymers, making it difficult to optimize both types and parameters to fit quantum chemical or physical property data. Here, we propose an alternative approach that uses graph neural networks to perceive chemical environments, producing continuous atom embeddings from which valence and nonbonded parameters can be predicted using invariance-preserving layers. Since all stages are built from smooth neural functions, the entire process---spanning chemical perception to parameter assignment---is modular and end-to-end differentiable with respect to model parameters, allowing new force fields to be easily constructed, extended, and applied to arbitrary molecules. We show that this approach is not only sufficiently expressive to reproduce legacy atom types, but that it can learn and extend existing molecular mechanics force fields, construct entirely new force fields applicable to both biopolymers and small molecules from quantum chemical calculations, and even learn to accurately predict free energies from experimental observables.


  • espaloma/ core code for graph-parametrized potential energy functions.
    • graphs/ data objects that contain various level of information we need.
      • base modules for graphs.
      • provide APIs to various molecular modelling toolkits.
      • simplest graph representation of a molecule.
      • graph representation of a molecule that contains information regarding membership of lower-level nodes to higher-level nodes.
      • graph representation of a molecule with all parameters needed for energy evaluation.
    • nn/ neural network models that facilitates translation between graphs.
      • API to dgl models for atom-level message passing.
    • mm/ molecular mechanics functionalities for energy evaluation.
      • i/ energy terms used in Class-I force field.
        • bond energy
        • angle energy
        • torsion energy
        • nonbonded energy
      • ii/ energy terms used in Class-II force field.
        • coupling terms
        • higher order polynomials.

Example: Deploy espaloma 0.2.0 pretrained force field to arbitrary MM system

# imports
import os
import torch
import espaloma as esp

# grab pretrained model
if not os.path.exists(""):

# define or load a molecule of interest via the Open Force Field toolkit
from openff.toolkit.topology import Molecule
molecule = Molecule.from_smiles("CN1C=NC2=C1C(=O)N(C(=O)N2C)C")

# create an Espaloma Graph object to represent the molecule of interest
molecule_graph = esp.Graph(molecule)

# apply a trained espaloma model to assign parameters
espaloma_model = torch.load("")

# create an OpenMM System for the specified molecule
openmm_system = esp.graphs.deploy.openmm_system_from_graph(molecule_graph)

Using espaloma to parameterize small molecules in relative free energy calculations

An example of using espaloma to parameterize small molecules in relative alchemical free energy calculations is provided in the scripts/perses-benchmark/ directory.


This software is licensed under MIT license.


Copyright (c) 2020, Chodera Lab at Memorial Sloan Kettering Cancer Center and Authors: Authors: