Release History

Releases follow the major.minor.micro scheme recommended by PEP440, where

  • major increments denote a change that may break API compatibility with previous major releases

  • minor increments add features but do not break API compatibility

  • micro increments represent bugfix releases or improvements in documentation

Current development

API-breaking changes

  • PR #1760: Removes the private, unused ParameterHandler._OPENMMTYPE attribute.

Behavior changes

Bugfixes

  • PR #1778: Ensures SD data tags are preserved in Molecule.from_openeye if the input is of type oechem.OEGraphMol.

New features

  • PR #1775: Re-exports openff.units.unit and Quantity at openff.toolkit.unit and Quantity.

Improved documentation and warnings

0.14.5

Bugfixes

  • PR #1740: Updates for Mypy 1.6.

  • PR #1749: Updates versioneer for Python 3.12 compatibility.

  • PR #1756: Fixes issue #1739, where virtual sites would be double-created under some circumstances.

New features

  • PR #1731: Suppot SMIRNOFF vdW version 0.5.

Improved documentation and warnings

  • PR #1747: Warns if a SMILES with full atom mappings is passed to Moleucle.from_smiles, which does not use the atom map for atom ordering (Molecule.from_mapped_smiles does).

  • PR #1743: Uses a longer stride in OpenMM DCD reporter in the toolkit showcase and should better utilize GPU resources, if available.

  • PR #1744: Updates the virtual site notebook to use new Interchange behavior.

0.14.4

Behavior changes

  • PR #1705: Do not raise warning when allow_undefined_stereo=True.

  • PR #1695: ChemicalEnvironmentParsingError is now raised when an underlying toolkit fails to parse a SMARTS/SMIRKS pattern it is given during substructure matching.

  • PR #1716: Adds deprecation warnings to Molecule.from_polymer_pdb, Molecule.from_pdb_and_smiles, and RDKitToolkitWrapper.from_pdb_and_smiles instead pointing users toward Topology.from_pdb.

Bugfixes

  • PR #1726: Fix error message in setting scale12, scale13, and scale15 attributes.

  • PR #1728: Adds support for loading deprotonated cysteine (sometimes labeled as “CYM”) residues in Topology.from_pdb

New features

  • PR #1733: Makes NAGLToolkitWrapper and its associated module public.

  • PR #1698: Makes openff.toolkit.utils.toolkit_registry.toolkit_registry_manager public.

  • PR #1662: Adds hierarchy scheme iterators to Topology, i.e. Topology.residues, when schemes of the same iterator name are defines on all constituent Molecules.

  • PR #1700: Use openff-nagl v0.3.0.

  • PR #1623: Adds Topology.visualize.

Improved documentation and warnings

  • PR #1709: Update molecule cookbook to use the maximally capable Topology.from_pdb in lieu of the more limited Molecule.from_pdb_and_smiles and Molecule.from_polymer_pdb.

  • PR #1719: Remove out-of-date and unused examples/environment.yaml and various examples updates.

0.14.3

Bugfixes

  • PR #1689: Fixes #1688 in which automatic up-conversion of version 0.3 of vdWHandler created via the Python API errored out if method was not specified.

  • PR #1690: Fixes a circular-import bug that occurs when attempting to print a “no cheminformatics toolkits available” warning.

0.14.2

Behavior changes

  • PR #1679: Version 0.3 <vdW> sections of OFFXML files will automatically be up-converted (in memory) to version 0.4 according to the recomendations provided in OFF-EP 0008.

New features

  • PR #1631: Adds support for Python 3.11.

0.14.1

API-breaking changes

  • PR #1664: Removes ChemicalEnvironment and the entire openff.toolkit.typing.chemistry submodule, which was deprecated in 0.12.0.

Behavior changes

  • PR #1675: Makes InChI parsing failures more informative and gives them their own exception type, InChIParseError.

New features

  • PR #1627: (beta release of major new feature by @connordavel) Adds experimental support for custom substructure loading in Topology.from_pdb, via the _custom_substructures keyword argument. This will be added to the public API (by removing the leading underscore) in a future feature release, but is available for testing now. This feature should allow for easier loading of modified amino acids, nucleic acids, and other polymers.

Bugfixes

  • PR #1662: Fixes issue #1660 by forbidding the registration of HierarchySchemes with iterator names that conflict with existing Molecule attributes.

  • PR #1667: A more helpful exception is now raised when Topology.from_openmm is given an OpenMM Topology with virtual sites.

Examples updated

  • PR #1671: Re-rendered all examples using RDKit+AmberTools backend, and using most recent version of OFF Toolkit.

Improved documentation and warnings

0.14.0

API-breaking changes

  • PR #1649: Removes tests and associated modules from the public API.

  • PR #1508: Removes the return_topology kwawrg from ForceField.create_openmm_system which was deprecated in version 0.11.0. To access the Topology that results from parametrization, call ForceField.create_interchange and access the .topology attribute of the returned Interchange object.

  • PR #1506: Removes several classes and properties in the topology submodule that were deprecated in version 0.11.0.

Behavior changes

  • PR #1652: Fixes issue #1642 by making AmberToolsToolkitWrapper thread-safe (previously AmberToolsToolkitWrapper.assign_partial_charges and assign_fractional_bond_orders were not)

Bugfixes

  • PR #1654: Fixes issue #1653, where a test that expected RDKit to fail began returning an error when RDKit became able to generate conformers for octahedral molecules.

Improved documentation and warnings

  • PR #1572: Improved installation guide in line with ecosystem docs.

Examples updated

  • PR #1644: Streamlines several examples by using Interchange.to_openmm_simulation.

  • PR #1651: Fix broken links in several examples.

  • PR #1648: Update examples to use Topology.from_pdb and other small cleanups.

0.13.2

Bugfixes

  • PR #1640: Fixes issue #1633 in which some force field attributes were erroneously parsed as Quantity objects and issue #1635 in which OpenFF 2.1.0 (“Sage”) could not be loaded with Pint 0.22.

Improved documentation and warnings

  • PR #1636 and PR #1643: Make the Molecule Cookbook and Molecule.from_qcschema docstring only pull down QCF records with fully defined stereo.

0.13.1

Behavior changes

  • PR #1619: Fixes silent error #1618, by making partial_charges.setter more comprehensive in type and shape checking.

Bugfixes

  • PR #1617: Fixes #1616, by converting NAGL charges to float and converting partial_charges to float before converting to_openeye()

  • PR #1622: Fixes #1621 and #1346 in which some file-loading methods would fail on pathlib.Path.

0.13.0

New features

  • PR #1567: Allows setting Molecule.name in Molecule.from_smiles, from_inchi, from_polymer_pdb, and from_pdb_and_smiles.

  • PR #1565: Adds Topology.from_pdb.

Behavior changes

  • PR #1569: Several instances of Exception being raised are now replaced with other exceptions being raised.

  • PR #1577: Drops support for Python 3.8, following NEP-29.

Bugfixes

  • PR #1589: Fixes Issue #1579, where Molecule.from_polymer_pdb could not handle NH2 caps at C termini.

  • PR #1591: Fixes #1563, where from_rdkit would sometimes raise an error about radicals if a molecule using a non-MDL aromaticity model was provided.

Improved documentation and warnings

  • PR #1564: Improve documentation of conformer selection in Molecule.assign_partial_charges()

  • PR #1574: Fix class method signature rendering throughout API docs

  • PR #1584: Update some outdated docstrings and add some annotations.

Examples updates

  • PR #1575: The Toolkit Showcase example has been simplified via use of Topology.from_pdb

0.12.1

New features

  • PR #1502: Adds Gasteiger charge computation using the RDKit backend.

  • PR #1498: Molecule.remap() now supports partial mappings with the partial argument.

  • PR #1528: Topology.box_vectors are can now be set with openmm.unit.Quantitys, which are internally converted.

Behavior changes

  • PR #1498: New, more complete, and more descriptive errors for Molecule.remap().

  • PR #1525: Some unreleased force fields previously accessible from "openff/toolkit/data/test_forcefields/" are no longer implicitly available to the ForceField constructor.

  • PR #1545: Replaced the logic that sorts HierarchyElements with dedicated code in the OpenFF Toolkit instead of relying on deprecated features in the packaging module.

Bugfixes

  • PR #1543: Fixes a bug in which plugins are not loaded if a ForceField is constructed prior without plugins.

Improved documentation and warnings

  • PR #1498: Improved documentation for Molecule.remap(), Molecule.from_smiles(), and Molecule.from_mapped_smiles(), emphasizing the relationships between these methods. In particular, the documentation now clearly states that from_smiles() will not reorder atoms based on SMILES atom mapping.

  • PR #1525: Improves reporting failures when loading force fields.

  • PR #1513: Improves error messages and documentation around supported aromaticity models (currently only “OEAroModel_MDL”).

0.12.0

New features

  • PR #1484: A positions argument has been added to Topology.from_openmm() and Topology.from_mdtraj(), which allows the topology’s positions to be set more conveniently.

  • PR #1468: Track which ParameterHandlers are loaded as plugins.

Behavior changes

  • PR #1481: Removes compute_partial_charges_am1bcc, which was deprecated in 0.11.0.

  • PR #1466: Replaces the use of collections.OrderedDict throughout the toolkit with the built-in dict. attach_units, detach_units, and extract_serialized_units_from_dict have been removed from openff.toolkit.utils.utils.

  • PR #1472: Removes ParameterHandler._VALENCE_TYPE and the same attribute of its subclasses, which were previously not used. Also deprecates ChemicalEnvironment and, by extension, the openff.toolkit.typing.chemistry submodule.

Bugfixes

  • PR #1476: Fixes #1475 by also registering a ParameterHandler’s class when calling ForceField.register_parameter_handler.

  • PR #1480: Fixes #1479 by requiring that Atom.atomic_number is a positive integer.

  • PR #1494: Fixes #1493 in which some OFFXML file contents were parsed to unit.Quantity objects despite not representing physical quantities.

Improved documentation and warnings

  • PR #1484: The docstrings for Topology.from_openmm() and Topology.from_mdtraj() have been improved.

  • PR #1483: Simplified and clarified errors and warnings related to undefined stereochemistry with RDKit.

0.11.4 Bugfix release

Behavior changes

  • PR #1462: Makes residue numbers added by Molecule.perceive_residues strings (previously they were ints), to match the behavior of Topology.from_openmm and other hierarchy info-setting methods.

Bugfixes

  • PR #1459: Fixes #1430, where Topology.from_openmm would mis-assign atom names (and probably also hierarchy metadata as well).

  • PR #1462: Fixes #1461, where the default Molecule.residues iterator wouldn’t sort by residue number correctly when residue information was added by Molecule.perceive_residues.

0.11.3 Bugfix release

  • PR #1460: Disables error causing Issue #1432, where Molecule.from_polymer_pdb would sometimes issue stereochemistry errors when reading valid PDBs using the RDKit backend.

Bugfixes

  • PR #1436: Fix a small bug introduced in 0.11.2, where running with OpenEye installed but not licensed could lead to a crash.

  • PR #1444: Update for pint 0.20.

Examples updates

  • PR #1447: Fixed units of tolerance used in OpenMM minimization in Toolkit Showcase example notebook (from @ziyuanzhao2000)

Improved documentation and warnings

  • PR #1442: Doctests added to CI, leading to numerous fixed docstrings and examples therein.

Miscellaneous

  • PR #1413: Remove some large and unused data files from the test suite.

  • PR #1434: Remove dependency on typing_extensions.

0.11.2 Bugfix release

Behavior changes

  • PR #1421: Allow Molecule.from_rdkit() to load D- and F- block radicals, which cannot have implicit hydrogens.

Bug fixes

  • PR #1417: Ensure the properties dict is copied when a Molecule is.

Improved documentation and warnings

  • PR #1426: A warning about OpenEye Toolkits being unavailable is only emitted when they are installed but the license file is not found.

0.11.1 Minor release forbidding loading radicals

Behavior changes

  • PR #1398: Updates the Bond.bond_order setter to only accept int values.

  • PR #1236: from_rdkit and from_openeye now raise an RadicalsNotSupportedError when loading radicals. It’s not clear that the OpenFF Toolkit was ever safely handling radicals - they appear to be the root cause of many instances of unintended hydrogen addition and other connection table changes. If this change affects a workflow that was previously working correctly, please let us know on this issue so we can refine this behavior.

Examples changed

  • PR #1236: examples/check_dataset_parameter_coverage has been deprecated.

Bug fixes

  • PR #1400: Fixes a bug where Molecule.from_pdb_and_smiles could incorrectly order coordinates.

  • PR #1404: Support default hierarchy schemes in outputs of Molecule.from_pdb_and_smiles() and Topology.from_openmm()

0.11.0 Major release adding support for proteins and refactoring the Topology class.

Migration guide

New Molecule.from_polymer_pdb() method for loading proteins from PDB files

The Toolkit now supports loading protein PDB files through the Molecule.from_polymer_pdb() class method. For now, PDB files must consist of only a single protein molecule composed only of the 20 standard amino acids, their common protonated and deprotonated conjugates, and the N-methyl and acetyl caps.

Important API points re-exported from openff.toolkit

A number of commonly used API points have been re-exported from the package root. This should make using the Toolkit simpler for most people. The previous API points remain available. These API points are lazy-loaded so that parts of the toolkit can still be loaded without loading the entire code-base.

The most important of these are the ForceField, Molecule, and Topology classes:

- from openff.toolkit.typing.engines.smirnoff import ForceField
- from openff.toolkit.topology import Molecule, Topology
+ from openff.toolkit import ForceField, Molecule, Topology

A number of other useful API points are also available through this mechanism:

- from openff.toolkit.typing.engines.smirnoff import get_available_force_fields
- from openff.toolkit.utils.toolkits import (
-     GLOBAL_TOOLKIT_REGISTRY,
-     AmberToolsToolkitWrapper,
-     BuiltInToolkitWrapper,
-     OpenEyeToolkitWrapper,
-     RDKitToolkitWrapper,
-     ToolkitRegistry,
- )
+ from openff.toolkit import (
+     get_available_force_fields,
+     GLOBAL_TOOLKIT_REGISTRY,
+     AmberToolsToolkitWrapper,
+     BuiltInToolkitWrapper,
+     OpenEyeToolkitWrapper,
+     RDKitToolkitWrapper,
+     ToolkitRegistry,
+ )

The topology, typing, and utils modules can also be lazy loaded after importing only the top-level module:

- import openff.toolkit.topology
+ import openff.toolkit
  atom = openff.toolkit.topology.Atom()

Units

The use of OpenMM units has been replaced by the new OpenFF Units package, based on Pint.

Import the unit registry provided by openff-units:

from openff.units import unit

Create a unit.Quantity object:

value = unit.Quantity(1.0, unit.nanometer)  # or 1.0 * unit.nanometer

Inspect the value and unit of this quantity:

print(value.magnitude)  # or value.m
# 1.0
print(value.units)
# <Unit('nanometer')>

Convert to compatible units:

converted = value.to(unit.angstrom)
print(converted)
# 10.0 <Unit('angstrom')>

Report the value in compatible units:

print(value.m_as(unit.angstrom))  # Note that value.magnitude_as() does not exist
# 10.0 <Unit('angstrom')>

Convert to and from OpenMM quantities:

from openff.units.openmm import to_openmm, from_openmm
value_openmm = to_openmm(value)
print(value_openmm)
# Quantity(value=1.0, unit=nanometer)
print(type(value_openmm))
# 1.0 <Unit('nanometer')>
value_roundtrip = from_openmm(value_openmm)
print(value_roundtrip)
# 1.0 <Unit('nanometer')>

Breaking change: Removal of openff.toolkit.utils.check_units_are_compatible()

The openff.toolkit.utils.check_units_are_compatible() function has been removed. Use openff.units.Quantity.is_compatible_with() and openff.units.openmm.from_openmm() instead:

- check_units_are_compatible("length", length, openmm.unit.angstrom)
+ from_openmm(length).is_compatible_with(openff.units.unit.angstrom)

Breaking change: Interchange now responsible for system parametrization

Code for applying parameters to topologies has been removed from the Toolkit. This is now the responsibility of OpenFF Interchange. This change improves support for working with parametrized systems (through the Interchange class), and adds support for working with simulation engines other than OpenMM.

The ForceField.create_interchange() method has been added, and the ForceField.create_openmm_system() method now uses Interchange under the hood.

As part of this change, the UnsupportedKeywordArgumentsError has been removed; passing unknown arguments to create_openmm_system now raises a TypeError, as is normal in Python.

The following classes and methods have been removed from openff.toolkit.typing.engines.smirnoff.parameters:

  • NonintegralMoleculeChargeException

  • NonbondedMethod

  • ParameterHandler.assign_parameters()

  • ParameterHandler.postprocess_system()

  • ParameterHandler.check_partial_bond_orders_from_molecules_duplicates()

  • ParameterHandler.assign_partial_bond_orders_from_molecules()

In addition, the ParameterHandler.create_force() method has been deprecated and its functionality has been removed. It will be removed in a future release.

The return_topology argument of create_openmm_system has also been deprecated, and will be removed in 0.12.0. To create an OpenMM topology, use Interchange:

- omm_sys, off_top = force_field.create_openmm_system(
-     topology,
-     return_topology=True,
- )
- omm_top = off_top.to_openmm()
+ interchange = force_field.create_interchange(topology)
+ omm_sys = interchange.to_openmm(combine_nonbonded_forces=True)
+ omm_top = interchange.to_openmm_topology()

If you need access to the modified OpenFF topology for some other reason, create an Interchange and retrieve it there:

- omm_sys, off_top = force_field.create_openmm_system(
-     topology,
-     return_topology=True,
- )
+ interchange = force_field.create_interchange(topology)
+ off_top = interchange.topology
+ omm_sys = interchange.to_openmm(combine_nonbonded_forces=True)

Breaking change: Topology molecule representation

Topology objects now store complete copies of their constituent Molecule objects, rather than using simplified classes specific to Topology. This dramatically simplifies the code base and allows the use of the full Molecule API on molecules inside topologies.

The following classes have been removed:

  • TopologyAtom (use Atom instead)

  • TopologyBond (use Bond instead)

  • TopologyMolecule (use Molecule instead)

The following properties have been deprecated and will be removed in a future release:

In addition, the Topology.identical_molecule_groups property has been added, to facilitate iterating over copies of isomorphic molecules in a Topology.

Breaking change: Removed virtual site handling from topologies

To maintain a clear distinction between a model and the chemistry it represents, virtual site handling has been removed from the Toolkit’s Topology and Molecule classes. Virtual site support remains in the force field side of the toolkit, but creating virtual sites for particular molecules is now the responsibility of OpenFF Interchange. This allows the same Topology to be used for force fields that use different virtual sites; for example, a topology representing a solvated protein might be parametrized separately with a 3-point and 4-point water model.

As part of this change, the distinction between Atom and Particle is deprecated. The Particle class will be removed in a future release.

The following classes have been removed:

  • BondChargeVirtualSite

  • DivalentLonePairVirtualSite

  • MonovalentLonePairVirtualSite

  • TrivalentLonePairVirtualSite

  • VirtualParticle

  • VirtualSite

  • TopologyVirtualParticle

  • TopologyVirtualSite

The following methods and properties have been removed:

  • Atom.add_virtual_site()

  • Atom.virtual_sites

  • FrozenMolecule.compute_virtual_site_positions_from_conformer()

  • FrozenMolecule.compute_virtual_site_positions_from_atom_positions()

  • FrozenMolecule.n_virtual_sites

  • FrozenMolecule.n_virtual_particles

  • FrozenMolecule.virtual_sites()

  • Molecule.add_bond_charge_virtual_site()

  • Molecule.add_monovalent_lone_pair_virtual_site()

  • Molecule.add_divalent_lone_pair_virtual_site()

  • Molecule.add_trivalent_lone_pair_virtual_site()

  • Molecule.add_bond_charge_virtual_site()

  • Topology.n_topology_virtual_sites

  • Topology.topology_virtual_sites

  • Topology.virtual_site()

  • Topology.add_particle()

The following properties have been deprecated and will be removed in a future release:

Atom metadata and hierarchy schemes for iterating over residues, chains, etc.

The new Atom.metadata attribute is a dictionary that can store arbitrary metadata. Atom metadata commonly includes residue names, residue sequence numbers, chain identifiers, and other metadata that is not essential to the functioning of the Toolkit. Metadata can then be passed on when a Molecule is converted to another package; see Molecule conversion to other packages.

Metadata can also support iteration through the HierarchyScheme class. A hierarchy scheme is defined by some uniqueness criteria. Iterating over the scheme iterates over groups of atoms that have identical metadata values for the defined uniqueness criteria. For more information, see the API docs for HierarchyScheme and its related methods.

Breaking change: Removed Topology.charge_model and Topology.fractional_bond_order_model

Due to flaws in previous versions of the OFF Toolkit, these properties never had an effect on the assigned parameters. To resolve this bug and maintain a clear distinction between a model and the chemistry it represents, the Topology.charge_model and Topology.fractional_bond_order_model properties have been removed. Charge models and FBOs are now the responsibility of the ForceField.

Breaking change: Removed Atom.element

Atom.element has been removed to reduce our dependency on OpenMM for core functions:

- atomic_number = atom.element.atomic_number
+ atomic_number = atom.atomic_number
- atom_mass = atom.element.mass
+ atom_mass = atom.mass
- atom_elem_symbol = atom.element.symbol
+ atom_elem_symbol = atom.symbol

Topology.to_file()

The Topology.to_file() method has been significantly revised, including three breaking changes.

Breaking change: filename argument renamed file

The filename argument has been renamed file, and now supports file-like objects in addition to file names:

-  topology.to_file(filename="out.pdb", positions=xyz)
+  topology.to_file(file="out.pdb", positions=xyz)

Breaking change: Atom names guaranteed unique per residue by default

The default behavior is now to ensure that atom names are unique within a residue, rather than within a molecule. The ensure_unique_atom_names argument has been added to control this behavior. The previous behavior can be achieved by passing True to ensure_unique_atom_names:

- topology.to_file("out.pdb", xyz)
+ topology.to_file("out.pdb", xyz, ensure_unique_atom_names=True)

The ensure_unique_atom_names argument can also take the name of a HierarchyScheme, in which case atom names will be unique within the elements of that scheme (instead of within the atoms of a molecule). If the scheme is missing from a molecule, atom names will be unique within that molecule. The default value of this argument is "residues" to preserve atom names from the PDB.

Breaking change: keepIds argument renamed keep_ids

The keepIds argument has been renamed to the more Pythonic keep_ids. Its behavior and position in the argument list has not changed.

- topology.to_file("out.pdb", xyz, keepIds=True)
+ topology.to_file("out.pdb", xyz, keep_ids=True)

Non-breaking changes

In addition to these breaking changes, the positions argument is now optional. If it is not provided, positions will be taken from the first conformer of each molecule in the topology. If any molecule has no conformers, an error will be raised.

Positions in topologies

The Topology.get_positions() and Topology.set_positions() methods have been added to facilitate working with coordinates in topologies. A topology’s positions are defined by the zeroth conformer of each molecule. If any molecule lacks conformers, the entire topology has no positions.

Parameter types moved out of handler classes

To facilitate their discovery and documentation, re-exports for the ParameterType classes have been added to the openff.toolkit.typing.engines.smirnoff.parameters module. Previously, they were accessible only within their associated ParameterHandler classes. This is not a breaking change.

- from openff.toolkit.typing.engines.smirnoff.parameters import BondHandler
- BondType = BondHandler.BondType
+ from openff.toolkit.typing.engines.smirnoff.parameters import BondType

Breaking change: MissingDependencyError renamed MissingPackageError

The MissingDependencyError exception has been renamed MissingPackageError to better reflect its purpose.

  try:
      ...
- except MissingDependencyError:
+ except MissingPackageError:
      pass

compute_partial_charges_am1bcc() deprecated

The compute_partial_charges_am1bcc() methods of the Molecule, AmberToolsToolkitWrapper and OpenEyeToolkitWrapper classes have been deprecated and will be removed in a future release. Their functionality has been incorporated into assign_partial_charges() for more consistency with other charge generation methods:

- mol.compute_partial_charges_am1bcc()
+ mol.assign_partial_charges(partial_charge_method='am1bcc')

Additional changes and bugfixes

  • PR #1105, PR #1195, PR #1301, PR #1331, PR #1322, PR #1372: Add Molecule.from_polymer_pdb

  • PR #1377: Adds Topology.unique_molecules, which largely replaces Topology.reference_molecules.

  • PR #1313: Fixes Issue #1287, where
    OpenEyeToolkitWrapper.assign_partial_charges didn’t request symmetrized charges when the charge model was set to AM1-Mulliken.

  • PR #1348: Allows pathlib.Path objects to be passed to Molecule.from_file.

  • PR #1276: Removes the use_interchange argument to create_openmm_system. Deletes the create_force and postprocess_system methods of ParameterHandler and other methods related to creating OpenMM systems and forces. This is now handled in Interchange.

  • PR #1303: Deprecates Topology.particles, Topology.n_particles, Topology.particle_index as Molecule objects do not store virtual sites, only atoms.

  • PR #1297: Drops support for Python 3.7, following NEP-29.

  • PR #1194: Adds Topology.__add__, allowing Topology objects to be added together, including added in-place, using the + operator.

  • PR #1277: Adds support for version 0.4 of the <Electrostatics> section of the SMIRNOFF specification.

  • PR #1279: ParameterHandler.version and the .version attribute of its subclasses is now a Version object. Previously it was a string, which is not safe for PEP440-style versioning.

  • PR #1250: Adds support for return_topology in the Interchange code path in create_openmm_system.

  • PR #964: Adds initial implementation of atom metadata dictionaries.

  • PR #1097: Deprecates TopologyMolecule.

  • PR #1097: Topology.from_openmm is no longer guaranteed to maintain the ordering of bonds, but now explicitly guarantees that it maintains the order of atoms (Neither of these ordering guarantees were explicitly documented before, but this may be a change from the previous behavior).

  • PR #1165: Adds the boolean argument use_interchange to create_openmm_system with a default value of False. Setting it to True routes openmm.System creation through Interchange.

  • PR #1192: Add re-exports for core classes to the new openff.toolkit.app module and re-exports for parameter types to the new openff.toolkit.topology.parametertypes module. This does not affect existing paths and gives some new, easier to remember paths to core objects.

  • PR #1198: Ensure the vdW switch width is correctly set and enabled.

  • PR #1213: Removes Topology.charge_model and Topology.fractional_bond_order_model.

  • PR #1140: Adds the Topology.identical_molecule_groups property, which provides a way of grouping the instances of a specific chemical species in the topology.

  • PR #1200: Fixes a bug (Issue #1199) in which library charges were ignored in some force fields, including openff-2.0.0 code name “Sage.” This resulted in the TIP3P partial charges included Sage not being applied correctly in versions 0.10.1 and 0.10.2 of the OpenFF Toolkit. This regression was not present in version 0.10.0 and earlier and therefore is not believed to have any impact on the fitting or benchmarking of the first release of Sage (version 2.0.0). The change causing regression only affected library charges and therefore no other parameter types are believed to be affected.

  • PR #1346: Conformer generation with RDKit will use useRandomCoords=True on a second attempt if the first attempt fails, which sometimes happens with large molecules.

  • PR #1277: Version 0.3 <Electrostatics> sections of OFFXML files will automatically be up-converted (in memory) to version 0.4 according to the recomendations provided in OFF-EP 0005. Note this means the method attribute is replaced by periodic_potential, nonperiodic_potential, and exception_potential.

  • PR #1277: Fixes a bug in which attempting to convert ElectrostaticsHandler.switch_width did nothing.

  • PR #1130: Running unit tests will no longer generate force field files in the local directory.

  • PR #1182: Removes Atom.element, thereby also removing Atom.element.symbol, Atom.element.mass and Atom.element.atomic_number. These are replaced with corresponding properties directly on the Atom class: Atom.symbol, Atom.mass, and Atom.atomic_number.

  • PR #1209: Fixes Issue #1073, where the fractional_bondorder_method kwarg to the BondHandler initializer was being ignored.

  • PR #1214: A long overdue fix for Issue #837! If OpenEye is available, the ToolkitAM1BCCHandler will use the ELF10 method to select conformers for AM1BCC charge assignment.

  • PR #1160: Fixes the bug identified in Issue #1159, in which the order of atoms defining a BondChargeVirtualSite (and possibly other virtual sites types too) might be reversed if the match attribute of the virtual site has a value of "once".

  • PR #1231: Fixes Issue #1181 and Issue #1190, where in rare cases double bond stereo would cause to_rdkit to raise an error. The transfer of double bond stereochemistry from OpenFF’s E/Z representation to RDKit’s local representation is now handled as a constraint satisfaction problem.

  • PR #1368: Adds the Topology.get_positions() and Topology.set_positions() methods for working with topology positions. Positions are represented as the first conformer of each molecule in the topology.

  • PR #1368: Allows setting the ensure_unique_atom_names argument of Topology.to_openmm()to the name of a hierarchy scheme, in which case atom names are guaranteed unique per element of that scheme rather than per molecule. Changes the default value to "residues".

  • PR #1368: Adds the ensure_unique_atom_names argument to the Topology.to_file(), which mimics the same argument in Topology.to_openmm(). Renames the keepIds argument to keep_ids. Renames the filename argument to file and allows a file-like object to be passed instead of a filename. Makes the positions argument optional; if it is not given, positions are take from the first conformer of each molecule in the Topology.

  • PR #1290: Fixes Issue #1216 by adding internal logic to handle the possibility that multiple vsites share the same parent atom, and makes the return value of VirtualSiteHandler.find_matches be closer to the base class.

Examples added

  • PR #1113: Updates the Amber/GROMACS example to use Interchange.

  • PR #1368: Updates the Toolkit showcase with the new polymer handling and Interchange support

Tests updated

  • PR #1188: Add an <Electrostatics> section to the TIP3P force field file used in testing (test_forcefields/tip3p.offxml)

0.10.5 Bugfix release

  • PR #1252: Refactors virtual site support, resolving Issue #1235, Issue #1233, Issue #1222, Issue #1221, and Issue #1206.

    • Attempts to make virtual site handler more resilient through code simplification.

    • Virtual sites are now associated with a particular ‘parent’ atom, rather than with a set of atoms. In particular, when checking if a v-site has been assigned we now only check the main ‘parent’ atom associated with the v-site, rather than all additional orientation atoms. As an example, if a force field contained a bond-charge v-site that matches [O:1]=[C:2] and a monovalent lone pair that matches [O:1]=[C:2]-[*:3] in that order, then only the monovalent lone pair will be assigned to formaldehyde as the oxygen is the main atom that would be associated with both v-sites, and the monovalent lone pair appears later in the hierarchy. This constitutes a behaviour change over previous versions.

    • All v-site exclusion policies have been removed except for ‘parents’ which has been updated to match OFF-EP 0006.

    • checks have been added to enforce that the ‘match’ keyword complies with the SMIRNOFF spec.

    • Molecule virtual site classes no longer store FF data such as epsilon and sigma.

    • Sanity checks have been added when matching chemical environments for v-sites that ensure the environment looks like one of our expected test cases.

    • Fixes di- and trivalent lone pairs mixing the :1 and :2 indices.

    • Fixes trivalent v-site positioning.

    • Correctly splits TopologyVirtualSite and TopologyVirtualParticle so that virtual particles no longer have attributes such as particles, and ensure that indexing methods now work correctly.

0.10.4 Bugfix release

Critical bugfixes

  • PR #1242: Fixes Issue #837. If OpenEye Toolkits are available, ToolkitAM1BCCHandler will use the ELF10 method to select conformers for AM1-BCC charge assignment.

  • PR #1184: Fixes Issue #1181 and Issue #1190, where in rare cases double bond stereochemistry would cause Molecule.to_rdkit to raise an error. The transfer of double bond stereochemistry from OpenFF’s E/Z representation to RDKit’s local representation is now handled as a constraint satisfaction problem.

0.10.3 Bugfix release

Critical bugfixes

  • PR #1200: Fixes a bug (Issue #1199) in which library charges were ignored in some force fields, including openff-2.0.0 code name “Sage.” This resulted in the TIP3P partial charges included Sage not being applied correctly in versions 0.10.1 and 0.10.2 of the OpenFF Toolkit. This regression was not present in version 0.10.0 and earlier and therefore is not believed to have any impact on the fitting or benchmarking of the first release of Sage (version 2.0.0). The change causing the regression only affected library charges and therefore no other parameter types are believed to be affected.

API breaking changes

  • PR #855: In earlier versions of the toolkit, we had mistakenly made the assumption that cheminformatics toolkits agreed on the number and membership of rings. However we later learned that this was not true. This PR removes Molecule.rings and Molecule.n_rings. To find rings in a molecule, directly use a cheminformatics toolkit after using Molecule.to_rdkit or Molecule.to_openeye. Atom.is_in_ring and Bond.is_in_ring are now methods, not properties.

Behaviors changed and bugfixes

Behaviors changed and bugfixes

  • PR #1185: Removed length check in ValenceDict and fixed checking the permutations of dihedrals

Improved documentation and warnings

API breaking changes

0.10.2 Bugfix release

API-breaking changes

Behaviors changed and bugfixes

  • PR #1160: Fixes a major bug identified in Issue #1159, in which the order of atoms defining a BondChargeVirtualSite (and possibly other virtual sites types too) might be reversed if the match attribute of the virtual site has a value of "once".

  • PR #1130: Running unit tests will no longer generate force field files in the local directory.

  • PR #1148: Adds a new exception UnsupportedFileTypeError and descriptive error message when attempting to use Molecule.from_file to parse XYZ/.xyz files.

  • PR #1153: Fixes Issue #1152 in which running Molecule.generate_conformers using the OpenEye backend would use the stereochemistry from an existing conformer instead of the stereochemistry from the molecular graph, leading to undefined behavior if the molecule had a 2D conformer.

  • PR #1158: Fixes the default representation of Molecule failing in Jupyter notebooks when NGLview is not installed.

  • PR #1151: Fixes Issue #1150, in which calling Molecule.assign_fractional_bond_orders with all default arguments would lead to an error as a result of trying to lowercase None.

  • PR #1149: TopologyAtom, TopologyBond, and TopologyVirtualSite now properly reference their reference molecule from their .molecule attribute.

  • PR #1155: Ensures big-endian byte order of NumPy arrays when serialized to dictionaries or files formats except JSON.

  • PR #1163: Fixes the bug identified in Issue #1161, which was caused by the use of the deprecated pkg_resources package. Now the recommended importlib_metadata package is used instead.

Breaking changes

  • PR #1118: Molecule.to_hill_formula is now a class method and no longer accepts input of NetworkX graphs.

  • PR #1156: Removes ParseError and MessageException, which has been deprecated since version 0.10.0.

Examples added

  • PR #1113: Updates the Amber/GROMACS example to use Interchange.

0.10.1 Minor feature and bugfix release

Behaviors changed and bugfixes

  • PR #1096: Atom names generated by Molecule.generate_unique_atom_names are now appended with an "x". See the linked issue for more details.

  • PR #1050: In Molecule.generate_conformers, a single toolkit wrapper failing to generate conformers is no longer fatal, but if all wrappers in a registry fail, then a ValueError will be raised. This mirrors the behavior of Molecule.assign_partial_charges.

  • PR #1050: Conformer generation failures in OpenEyeToolkitWrapper.generate_conformers, and RDKitToolkitWrapper.generate_conformers now each raise openff.toolkit.utils.exceptions.ConformerGenerationError if conformer generation fails. The same behavior occurs in Molecule.generate_conformers, but only when the toolkit_registry argument is a ToolkitWrapper, not when it is a ToolkitRegistry.

  • PR #1046: Changes OFFXML output to replace tabs with 4 spaces to standardize representation in different text viewers.

  • PR #1001: RDKit Mol objects created through the Molecule.to_rdkit() method have the NoImplicit property set to True on all atoms. This prevents RDKit from incorrectly adding hydrogen atoms to to molecule.

  • PR #1058: Removes the unimplemented methods ForceField.create_parmed_structure, Topology.to_parmed, and Topology.from_parmed.

  • PR #1065: The example conformer_energies.py script now uses the Sage 2.0.0 force field.

  • PR #1036: SMARTS matching logic for library charges was updated to use only one unique match instead of enumerating all possible matches. This results in faster matching, particularly with larger molecules. No adverse side effects were found in testing, but bad behavior may possibly exist in some unknown cases. Note that the default behavior for other parameter handlers was not updated.

  • PR #1001: Revamped the Molecule.visualize() method’s rdkit backend for more pleasing and idiomatic 2D visualization by default.

  • PR #1087: Fixes Issue #1073 in which Molecule.__repr__ fails if the molecule can not be represented as a SMILES pattern. Now, if SMILES generation fails, the molecule will be described by its Hill formula.

  • PR #1052: Fixes Issue #986 by raising a subclass of AttributeError in _ParameterAttributeHandler.__getattr__

  • PR #1030: Fixes a bug in which the expectations for capitalization for values of bond_order_model attributes and keywords are inconsistent.

  • PR #1101: Fixes a bug in which calling to_qcschema on a molecule with no connectivity feeds QCElemental.Molecule an empty list for the connectivity field; now feeds None.

Tests updated

  • PR #1017: Ensures that OpenEye-only CI builds really do lack both AmberTools and RDKit.

Improved documentation and warnings

  • PR #1065: Example notebooks were updated to use the Sage Open Force Field

  • PR #1062: Rewrote installation guide for clarity and comprehensiveness.

0.10.0 Improvements for force field fitting

Behaviors changed

New features and behaviors changed

  • PR #1027: Corrects interconversion of Molecule objects with OEMol objects by ensuring atom names are correctly accessible via the OEAtomBase.GetName() and OEAtomBase.SetName() methods, rather that the non-standard OEAtomBase.GetData("name") and OEAtomBase.SetData("name", name).

  • PR #1007: Resolves Issue #456 by adding the normalize_partial_charges (default is True) keyword argument to Molecule.assign_partial_charges, AmberToolsToolkitWrapper.assign_partial_charges,
    OpenEyeToolkitWrapper.assign_partial_charges, RDKitToolkitWrapper.assign_partial_charges, and BuiltInToolkitWrapper.assign_partial_charges. This adds an offset to each atom’s partial charge to ensure that their sum is equal to the net charge on the molecule (to the limit of a python float’s precision, generally less than 1e-6 electron charge). Note that, because this new behavior is ON by default, it may slightly affect the partial charges and energies of systems generated by running create_openmm_system.

  • PR #954: Adds LibraryChargeType.from_molecule which returns a LibraryChargeType object that will match the full molecule being parameterized, and assign it the same partial charges as are set on the input molecule.

  • PR #923: Adds Molecule.nth_degree_neighbors, Topology.nth_degree_neighbors, TopologyMolecule.nth_degree_neighbors, which returns pairs of atoms that are separated in a molecule or topology by exactly N atoms.

  • PR #917: ForceField.create_openmm_system now ensures that the cutoff of the NonbondedForce is set to the cutoff of the vdWHandler when it and a Electrostatics handler are present in the force field.

  • PR #850: OpenEyeToolkitWrapper.is_available now returns True if any OpenEye tools are licensed (and installed). This allows, i.e, use of functionality that requires OEChem without having an OEOmega license.

  • PR #909: Virtual site positions can now be computed directly in the toolkit. This functionality is accessed through

    • FrozenMolecule.compute_virtual_site_positions_from_conformer

    • VirtualSite.compute_positions_from_conformer

    • VirtualParticle.compute_position_from_conformer

    • FrozenMolecule.compute_virtual_site_positions_from_atom_positions

    • VirtualSite.compute_positions_from_atom_positions

    • VirtualParticle.compute_position_from_atom_positions where the positions can be computed from a stored conformer, or an input vector of atom positions.

    • Tests have been added (TestMolecule.test_*_virtual_site_position) to check for sane behavior. The tests do not directly compare OpenMM position equivalence, but offline tests show that they are equivalent.

    • The helper method VirtualSiteHandler.create_openff_virtual_sites is now public, which returns a modified topology with virtual sites added.

    • Virtual sites now expose the parameters used to create its local frame via the read-only properties

      • VirtualSite.local_frame_weights

      • VirtualSite.local_frame_position

    • Adding virtual sites via the Molecule API now have defaults for sigma, epsilon, and charge_increment set to 0 with appropriate units, rather than None

  • PR #956: Added ForceField.get_partial_charges() to more easily compute the partial charges assigned by a force field for a molecule.

  • PR #1006: Two behavior changes in the SMILES output for to_file() and to_file_obj():

    • The RDKit and OpenEye wrappers now output the same SMILES as to_smiles(). This uses explicit hydrogens rather than the toolkit’s default of implicit hydrogens.

    • The RDKit wrapper no longer includes a header line. This improves the consistency between the OpenEye and RDKit outputs.

Bugfixes

  • PR #1024: Small changes for compatibility with OpenMM 7.6.

  • PR #1003: Fixes Issue #1000, where a stereochemistry warning is sometimes erroneously emitted when loading a stereogenic molecule using Molecule.from_pdb_and_smiles

  • PR #1002: Fixes a bug in which OFFXML files could inadvertently be loaded from subdirectories.

  • PR #969: Fixes a bug in which the cutoff distance of the NonbondedForce generated by ForceField.create_openmm_system was not set to the value specified by the vdW and Electrostatics handlers.

  • PR #909: Fixed several bugs related to creating an OpenMM system with virtual sites created via the Molecule virtual site API

  • PR #1006: Many small fixes to the toolkit wrapper I/O for better error handling, improved consistency between reading from a file vs. file object, and improved consistency between the RDKit and OEChem toolkit wrappers. For the full list see Issue #1005. Some of the more significant fixes are:

    • RDKitToolkitWrapper.from_file_obj() now uses the same structure normaliation as from_file().

    • from_smiles() now raises an openff.toolkit.utils.exceptions.SMILESParsingError if the SMILES could not be parsed.

    • OEChem input and output files now raise an OSError if the file could not be opened.

    • All input file object readers now support file objects open in binary mode.

Examples added

  • PR #763: Adds an introductory example showcasing the toolkit parameterizing a protein-ligand simulation.

  • PR #955: Refreshed the force field modification example

  • PR #934 and conda-forge/openff-toolkit-feedstock#9: Added openff-toolkit-examples Conda package for easy installation of examples and their dependencies. Simply conda install -c conda-forge openff-toolkit-examples and then run the openff-toolkit-examples script to copy the examples suite to a convenient place to run them!

Tests updated

  • PR #963: Several tests modules used functions from test_forcefield.py that created an OpenFF Molecule without a toolkit. These functions are now in their own module so they can be imported directly, without the overhead of going through test_forcefield.

  • PR #997: Several XML snippets in test_forcefield.py that were scattered around inside of classes and functions are now moved to the module level.

0.9.2 Minor feature and bugfix release

New features and behaviors changed

Bugfixes

Improved documentation and warnings

  • PR #862: Clarify that System objects produced by the toolkit are OpenMM Systems in anticipation of forthcoming OpenFF Systems. Fixes Issue #618.

  • PR #863: Documented how to build the docs in the developers guide.

  • PR #870: Reorganised documentation to improve discoverability and allow future additions.

  • PR #871: Changed Markdown parser from m2r2 to MyST for improved documentation rendering.

  • PR #880: Cleanup and partial rewrite of the developer’s guide.

  • PR #906: Cleaner instructions on how to setup development environment.

Earlier releases