OpenFF Toolkit 0.9.0+ migration tips

[mattwthompson]

Version 0.9.0 marks this package's transition from the old openforcefield branding over to its new identity as openff-toolkit. This change has been made to better represent the role of the toolkit, and highlight its place in the larger Open Force Field (OpenFF) ecosystem.

The short version of the changes can be found in the release notes. This post documents some more details that users may find helpful in migrating.

Changes to source code

The import path to the Python module has changed. Replace all instances of openforcefield with openff.toolkit, i.e.

Old (0.8.3 and earlier)

from openforcefield.topology import Molecule
from openforcefield.typing.engines.smirnoff import ForceField

New (0.9.0 and newer)

from openff.toolkit.topology import Molecule
from openff.toolkit.typing.engines.smirnoff import ForceField

Creating a new environment

The name of the conda package has changed to openff-toolkit and is now available on the conda-forge channel. The omnia channel does not need to be in the conda configuration, but it should not cause issues if it is.

conda create --name openff-env openff-toolkit -c conda-forge

See the installation docs, which have been updated, for more details.

Updating an existing conda environment

Creating a new environment is recommended. For users who wish to update an existing environment, it is recommended to first uninstall existing packages:

conda uninstall openforcefield openforcefields -c conda-forge

and then install the new package:

conda install openff-toolkit -c conda-forge

Safe imports during the migration

If writing code that needs to work with the "new" and "old" import paths, consider wrapping the import statement up into a try:/except: block

try:
    from openforcefield.topology import Molecule
except ImportError:
    from openff.toolkit.topology import Molecule

# Do things with the Molecule API

This type of logic will allow the class to be imported before and after the namespace migration.

Error messages and their solution

ModuleNotFoundError: No module named 'openforcefield'

Update your imports as shown above.

Encountered problems while solving.
Problem: package openff-toolkit-0.9.0-pyh44b312d_0 has constraint openforcefield 9999999999 conflicting with openforcefield-0.8.3-pyh39e3cac_0

Uninstall openforcefield and openforcefields first, then try to install openff-toolkit again.

[mattwthompson]

I'd like to move this to a Discussion - if nobody objects I will do that in a few days