openforcefield/openforcefield: 0.6.0 Library Charges

0.6.0

This release adds support for a new SMIRKS-based charge assignment method, Library Charges. The addition of more charge assignment methods opens the door for new types of experimentation, but also introduces several complex behaviors and failure modes. Accordingly, we have made changes to the charge assignment infrastructure to check for cases when partial charges do not sum to the formal charge of the molecule, or when no charge assignment method is able to generate charges for a molecule. More detailed explanations of the new errors that may be raised and keywords for overriding them are in the "Behavior Changed" section below.

With this release, we update test_forcefields/tip3p.offxml to be a working example of assigning LibraryCharges. However, we do not provide any force field files to assign protein residue LibraryCharges. If you are interested in translating an existing protein FF to SMIRNOFF format or developing a new one, please feel free to contact us on the Issue tracker or open a Pull Request.

A richer version of these release notes with live links to API documentation is available on our ReadTheDocs page

See our installation instructions.

Please report bugs, request features, or ask questions through our issue tracker.

Please note that there may still be some changes to the API prior to a stable 1.0.0 release.

• PR #433 : Closes Issue #25 by adding initial support for the LibraryCharges tag in the SMIRNOFF specification using LibraryChargeHandler. For a molecule to have charges assigned using Library Charges, all of its atoms must be covered by at least one LibraryCharge. If an atom is covered by multiple LibraryCharge s, then the last LibraryCharge matched will be applied (per the hierarchy rules in the SMIRNOFF format).

  This functionality is thus able to apply per-residue charges similar to those in traditional protein force fields. At this time, there is no concept of "residues" or "fragments" during parametrization, so it is not possible to assign charges to some atoms in a molecule using LibraryCharge s, but calculate charges for other atoms in the same molecule using a different method. To assign charges to a protein, LibraryCharges SMARTS must be provided for the residues and protonation states in the molecule, as well as for any capping groups and post-translational modifications that are present.

  It is valid for LibraryCharge SMARTS to partially overlap one another. For example, a molecule consisting of atoms A-B-C connected by single bonds could be matched by a SMIRNOFF LibraryCharges section containing two LibraryCharge SMARTS: A-B and B-C. If listed in that order, the molecule would be assigned the A charge from the A-B LibraryCharge element and the B and C charges from the B-C element. In testing, these types of partial overlaps were found to frequently be sources of undesired behavior, so it is recommended that users define whole-molecule LibraryCharge SMARTS whenever possible.

• PR #455 : Addresses #393 by adding ParameterHandler.attribute_is_cosmetic and ParameterType.attribute_is_cosmetic, which return True if the provided attribute name is defined for the queried object but does not correspond to an allowed value in the SMIRNOFF spec.

• PR #433 : If a molecule can not be assigned charges by any charge-assignment method, an openforcefield.typing.engines.smirnoff.parameters.UnassignedMoleculeChargeException will be raised. Previously, creating a system without either ToolkitAM1BCCHandler or the charge_from_molecules keyword argument to ForceField.create_openmm_system would produce a system where the molecule has zero charge on all atoms. However, given that we will soon be adding more options for charge assignment, it is important that failures not be silent. Molecules with zero charge can still be produced by setting the Molecule.partial_charges array to be all zeroes, and including the molecule in the charge_from_molecules keyword argument to create_openmm_system.
• PR #433 : Due to risks introduced by permitting charge assignment using partially-overlapping LibraryCharge s, the toolkit will now raise a openforcefield.typing.engines.smirnoff.parameters.NonIntegralMoleculeChargeException if the sum of partial charges on a molecule are found to be more than 0.01 elementary charge units different than the molecule's formal charge. This exception can be overridden by providing the allow_nonintegral_charges=True keyword argument to ForceField.create_openmm_system.

• PR #430 : Added test for Wiberg Bond Order implemented in OpenEye Toolkits. Test molecules taken from DOI:10.5281/zenodo.3405489 . Added by @sukanyasasmal .

• PR #431 : Fixes an issue where ToolkitWrapper objects would improperly search for functionality in the GLOBAL_TOOLKIT_REGISTRY, even though a specific ToolkitRegistry was requested for an operation.
• PR #439 : Fixes Issue #438 <https://github.com/openforcefield/openforcefield/issues/438>_, by replacing call to NetworkX Graph.node with call to Graph.nodes, per 2.4 migration guide.

• PR #433 : Updates the previously-nonfunctional test_forcefields/tip3p.offxml to a functional state by updating it to the SMIRNOFF 0.3 specification, and specifying atomic charges using the LibraryCharges tag.