Skip to content

A project (and object) for storing, manipulating, and converting molecular mechanics data.


Notifications You must be signed in to change notification settings


Repository files navigation

OpenFF Interchange

Test status CI Status status
Code quality pre-commit Codecov coverage
Latest release GitHub release (latest by date including pre-releases)
User support Documentation Status Discussions

A project (and object) for storing, manipulating, and converting molecular mechanics data.


Documentation for Interchange, including examples, a brief user guide, release history, and API docs, is available on the OpenFF website. Example notebooks are rendered online among examples from other projects in the OpenFF ecosysytem docs

How to cite

Please cite Interchange using the Zenodo record of the latest release or the version that was used. The BibTeX reference of the latest release can be found here.


Recent versions of the OpenFF Toolkit (0.11.0+, released August 2022) install Interchange by default through its conda package.

Interchange can also be installed manually via conda (or mamba):

conda install openff-interchange -c conda-forge

Getting started

The Iterchange object serves primarily as a container object for parametrized data. It can currently take in SMIRNOFF or Foyer force fields and chemical topologies prepared via the OpenFF Toolkit. The resulting object stores parametrized data and provides APIs for export to common formats.

from openff.toolkit import ForceField, Molecule
from openff.units import unit

from openff.interchange import Interchange

# Use the OpenFF Toolkit to generate a molecule object from a SMILES pattern
molecule = Molecule.from_smiles("CCO")

# Generate a conformer to be used as atomic coordinates

# Convert this molecule to a topology
topology = molecule.to_topology()

# Define periodicity via box vectors
topology.box_vectors = unit.Quantity([4, 4, 4], unit.nanometer)

# Load OpenFF 2.0.0 "Sage"
sage = ForceField("openff-2.0.0.offxml")

# Create an Interchange object
out = Interchange.from_smirnoff(force_field=sage, topology=topology)

# Convert the Interchnage object to an OpenMM System
system = out.to_openmm()

# or write to GROMACS files

# or store as JSON
json_blob = out.json()

For more information, please consult the full documentation.

For more examples specific to Interchange, navigate to the examples/ directory.

Please note that this software in an early and experimental state without a stable API or guarantees of long-term stability.


Copyright (c) 2020, Open Force Field Initiative


The source code of Interchange is hosted on GitHub and is available under the MIT license (see the file LICENSE). Some parts inherit from code distributed under other licenses, as detailed in LICENSE-3RD-PARTY.


Project based on the Computational Molecular Science Python Cookiecutter version 1.2.