0.8.2 Bugfix release

0.8.2 Bugfix release

WARNING: This release was later found to contain a major bug (#807) and produces incorrect energies.

For the complete release notes, please see our documentation

• PR #786: Fixes Issue #785 where RDKitToolkitWrapper would sometimes expect stereochemistry to be defined for non-stereogenic bonds when loading from SDF.
• PR #786: Fixes an issue where using the Molecule copy constructor (newmol = Molecule(oldmol)) would result in the copy sharing the same .properties dict as the original (as in, changes to the .properties dict of the copy would be reflected in the original).
• PR #789: Fixes a regression noted in Issue #788 where creating vdWHandler.vdWType or setting sigma or rmin_half using quantities represented as strings resulted in an error.

For help getting the OpenFF Toolkit running, 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.

0.8.1 Bugfix and minor feature release

0.8.1 Bugfix and minor feature release

WARNING: This release was later found to contain a major bug (#807) and produces incorrect energies.

For the complete release notes, please see our documentation

This minor release is intended to provide timely access to recent minor features and bugfixes.

For help getting the OpenFF Toolkit running, 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.

0.8.0 Virtual Sites and Bond Interpolation

0.8.0 Virtual Sites and Bond Interpolation

For the complete release notes, please see our documentation

This release adds our largest feature yet, SMARTS-based creation of VirtualSites (also known as off-center charges), as well as functionality to handle bond parameter interpolation based on partial bond orders.

For help getting the OpenFF Toolkit running, 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.

0.7.2 Bugfix and minor feature release

0.7.2

This minor release is intended to provide timely access to recent minor features and bugfixes.

A richer, more thorough 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.

New features

• PR #662: Adds aromaticity_model of ForceField and .TAGNAME of ParameterHandler as public attributes.
• PR #675: adds .toolkit_version to ToolkitWrapper and .registered_toolkit_versions to ToolkitRegistry.
• PR #696: Exposes a setter for ForceField.aromaticity_model
• PR #685: Adds a custom __hash__ function to ForceField

Behavior changed

• PR #684: Changes ToolkitRegistry to return an empty registry when initialized with no arguments, i.e. ToolkitRegistry() and makes the register_imported_toolkit_wrappers argument private.
• PR #711: The setter for Topology.box_vectors now infers box vectors (a 3x3 matrix) when box lengths (a 3x1 array) are passed, assuming an orthogonal box.
• PR #648: Removes the utils.structure module, which was deprecated in 0.2.0.
• PR #670: Makes the Topology returned by create_openmm_system contain the partial charges and partial bond orders (if any) assigned during parameterization.

Bugfixes

• PR #715: Closes Issue #475, where writing a PDB file using the OpenEye backend sometimes rearranged the order of the atoms by pushing the hydrogens to the bottom (Fix contributed by @pavankum)

0.7.1 OETK2020 Compatibility and Minor Update

0.7.1

This is the first of our patch releases on our new planned monthly release schedule.

Detailed release notes are below, but the major new features of this release are updates for compatibility with the new 2020 OpenEye Toolkits release, the get_available_force_fields function, and the disregarding of pyrimidal nitrogen stereochemistry in molecule isomorphism checks.

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.

Behavior changed

• PR #646: Checking for Molecule equality using the == operator now disregards all pyrimidal nitrogen stereochemistry by default. To re-enable, use Molecule.{is|are}_isomorphic with the strip_pyrimidal_n_atom_stereo=False keyword argument.
• PR #646: Adds an optional toolkit_registry keyword argument to Molecule.are_isomorphic, which identifies the toolkit that should be used to search for pyrimidal nitrogens.

Bugfixes

• PR #647: Updates OpenEyeToolkitWrapper for 2020.0.4 OpenEye Toolkit behavior/API changes.
• PR #646: Fixes a bug where Molecule.chemical_environment_matches was not able to accept a ChemicalEnvironment object as a query.
• PR #634: Fixes a bug in which calling RDKitToolkitWrapper.from_file directly would not load files correctly if passed lowercase file_format. Note that this bug did not occur when calling Molecule.from_file.
• PR #631: Fixes a bug in which calling unit_to_string returned None when the unit is dimensionless. Now "dimensionless" is returned.
• PR #630: Closes issue #629 in which the wrong exception is raised when attempting to instantiate a ForceField from an unparsable string.

New features

• PR #632: Adds ForceField.registered_parameter_handlers
• PR #614: Adds ToolkitRegistry.deregister_toolkit to de-register registered toolkits, which can include toolkit wrappers loaded into GLOBAL_TOOLKIT_REGISTRY by default.
• PR #656: Adds a new allowed am1elf10 option to the OpenEye implementation of assign_partial_charges which calculates the average partial charges at the AM1 level of theory using conformers selected using the ELF10 method.
• PR #643: Adds openforcefield.typing.engines.smirnoff.forcefield.get_available_force_fields, which returns paths to the files of force fields available through entry point plugins.

0.7.0 Charge Increment Model, Proper Torsion interpolation, and new Molecule methods

0.7.0 - Charge Increment Model, Proper Torsion interpolation, and new Molecule methods

This is a relatively large release, motivated by the idea that changing existing functionality is bad so we shouldn't do it too often, but when we do change things we should do it all at once.

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.

Here's a brief rundown of what changed, migration tips, and what to search for in the full release notes to find more details and workarounds:

• To provide more consistent partial charges for a given molecule, existing conformers are now disregarded by default by Molecule.assign_partial_charges. Instead, new conformers are generated for use in semiempirical calculations. Search for use_conformers.
• Formal charges are now always returned as simtk.unit.Quantity objects, with units of elementary charge. To convert them to integers, use from simtk import unit and atom.formal_charge.value_in_unit(unit.elementary_charge) or mol.total_charge.value_in_unit(unit.elementary_charge). Search atom.formal_charge.
• The OpenFF Toolkit now automatically reads and writes partial charges in SDF files. Search for atom.dprop.PartialCharges.
• The OpenFF Toolkit now has different behavior for handling multi-molecule and multi-conformer SDF files. Search multi-conformer.
• The OpenFF Toolkit now distinguishes between partial charges that are all-zero and partial charges that are unknown. Search partial_charges = None.
• Topology.to_openmm now assigns unique atoms names by default. Search ensure_unique_atom_names.
• Molecule equality checks are now done by graph comparison instead of SMILES comparison. Search Molecule.are_isomorphic.
• The ChemicalEnvironment module was almost entirely removed, as it is an outdated duplicate of some Chemper functionality. Search ChemicalEnvironment.
• TopologyMolecule.topology_particle_start_index has been removed from the TopologyMolecule API, since atoms and virtualsites are no longer contiguous in the Topology particle indexing system. Search topology_particle_start_index.
• compute_wiberg_bond_orders has been renamed to assign_fractional_bond_orders.

There are also a number of new features, such as:

• Support for ChargeIncrementModel sections in force fields.
• Support for ProperTorsion k interpolation in force fields using fractional bond orders.
• Support for AM1-Mulliken, Gasteiger, and other charge methods using the new assign_partial_charges methods.
• Support for AM1-Wiberg bond order calculation using either the OpenEye or RDKit/AmberTools backends and the new assign_fractional_bond_orders methods
• Initial (limited) interoperability with QCArchive, via Molecule.to_qcschema and from_qcschema.
• A Molecule.visualize method.
• Several additional Molecule methods, including state enumeration and mapped SMILES creation.

For details of these changes and in-depth descriptions please see the full release notes.

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.

New features

• 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.

Behavior changed

• 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.

Tests added

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

Bugfixes

• 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.

Files modified

• 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.

0.5.1 Adding the parameter coverage example notebook

0.5.1

This release contains a new notebook example, check_parameter_coverage.ipynb, which loads sets of molecules, checks whether they are parameterizable, and generates reports of chemical motifs that are not. It also fixes several simple issues, improves warnings and docstring text, and removes unused files.

The parameter coverage example notebook goes hand-in-hand with the release candidate of our initial force field, openff-1.0.0-RC1.offxml, which will be temporarily available until the official force field release is made in October. Our goal in publishing this notebook alongside our first major refitting is to allow interested users to check whether there is parameter coverage for their molecules of interest. If the force field is unable to parameterize a molecule, this notebook will generate reports of the specific chemistry that is not covered. We understand that many organizations in our field have restrictions about sharing specific molecules, and the outputs from this notebook can easily be cropped to communicate unparameterizable chemistry without revealing the full structure.

The force field release candidate is in our new refit force field package, openforcefields. This package is now a part of the Open Force Field Toolkit conda recipe, along with the original smirnoff99Frosst line of force fields.

Once the openforcefields conda package is installed, you can load the release candidate using:

ff = ForceField('openff-1.0.0-RC1.offxml')

The release candidate will be removed when the official force field, openff-1.0.0.offxml, is released in early October.

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.

Example added

• PR #419: Adds an example notebook check_parameter_coverage.ipynb which shows how to use the toolkit to check a molecule dataset for missing parameter coverage, and provides functionality to output tagged SMILES and 2D drawings of the unparameterizable chemistry.

New features

• PR #419: Unassigned valence parameter exceptions now include a list of tuples of TopologyAtom which were unable to be parameterized (exception.unassigned_topology_atom_tuples) and the class of the ParameterHandler that raised the exception (exception.handler_class).
• PR #425: Implements @trevorgokey 's suggestion from Issue #411, which enables pickling of ForceFields and ParameterHandlers. Note that, while XML representations of ForceFields are stable and conform to the SMIRNOFF specification, the pickled ForceFields that this functionality enables are not guaranteed to be compatible with future toolkit versions.

Improved documentation and warnings

• PR #425 : Addresses Issue #410 by having toolkit warnings clearly print Warning: at the beginning of each warning message and adding clearer language to the warning produced when the OpenEye Toolkits can not be loaded.
• PR #425: Addresses Issue #421 by adding type/shape information to all Molecule partial charge and conformer docstrings.
• PR #425: Addresses Issue #407 by providing a more extensive explanation of why we don't use RDKit's mol2 parser for molecule input.

Bugfixes

• PR #419: Fixes Issue #417 and Issue #418, where RDKitToolkitWrapper.from_file would disregard the allow_undefined_stereo kwarg and skip the first molecule when reading a SMILES file.

Files removed

• PR #425: Addresses Issue #424 by deleting the unused files openforcefield/typing/engines/smirnoff/gbsaforces.py and openforcefield/tests/test_smirnoff.py. gbsaforces.py was only used internally and test_smirnoff.py tested unsupported functionality from before the 0.2.0 release.

0.5.0 GBSA support and quality-of-life improvements

0.5.0

This release adds support for the GBSA tag in the SMIRNOFF specification. Currently, the HCT, OBC1, and OBC2 models (corresponding to AMBER keywords igb=1, 2, and 5, respectively) are supported, with the OBC2 implementation being the most flexible. Unfortunately, systems produced using these keywords are not yet transferable to other simulation packages via ParmEd, so users are restricted to using OpenMM to simulate systems with GBSA.

OFFXML files containing GBSA parameter definitions are available, and can be loaded in addition to existing parameter sets (for example, with the command ForceField('test_forcefields/smirnoff99Frosst.offxml', 'test_forcefields/GBSA_OBC1-1.0.offxml')). A manifest of new SMIRNOFF-format GBSA files is below.

Several other user-facing improvements have been added, including easier access to indexed attributes, which are now accessible as torsion.k1, torsion.k2, etc. (the previous access method torsion.k still works as well). More details of the new features and several bugfixes are listed below.

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.

New features

• PR #363: Implements openforcefield.typing.engines.smirnoff.parameters.GBSAHandler, which supports the GBSA tag in the SMIRNOFF specification. Currently, only GBSAHandlers with gb_model="OBC2" support setting non-default values for the surface_area_penalty term (default 5.4*calories/mole/angstroms**2), though users can zero the SA term for OBC1 and HCT models by setting sa_model="None". No model currently supports setting solvent_radius to any value other than 1.4*angstroms. Files containing experimental SMIRNOFF-format implementations of HCT, OBC1, and OBC2 GBSA models are included with this release (see below). Additional details of these models, including literature references, are available on the SMIRNOFF specification page.
  • WARNING: The current release of ParmEd can not transfer GBSA models produced by the Open Force Field Toolkit to other simulation packages. These GBSA forces are currently only computable using OpenMM.
• PR #363: When using openforcefield.topology.Topology.to_openmm(), periodic box vectors are now transferred from the Open Force Field Toolkit Topology into the newly-created OpenMM Topology.
• PR #377: Single indexed parameters in openforcefield.typing.engines.smirnoff.parameters.ParameterHandler and openforcefield.typing.engines.smirnoff.parameters.ParameterType can now be get/set through normal attribute syntax in addition to the list syntax.
• PR #394: Include element and atom name in error output when there are missing valence parameters during molecule parameterization.

Bugfixes

• PR #385: Fixes Issue #346 by having OpenEyeToolkitWrapper.compute_partial_charges_am1bcc fall back to using standard AM1-BCC if AM1-BCC ELF10 charge generation raises an error about "trans COOH conformers"
• PR #399: Fixes issue where openforcefield.typing.engines.smirnoff.forcefield.ForceField constructor would ignore parameter_handler_classes kwarg.
• PR #400: Makes link-checking tests retry three times before failing.

Files added

• PR #363: Adds test_forcefields/GBSA_HCT-1.0.offxml, test_forcefields/GBSA_OBC1-1.0.offxml, and test_forcefields/GBSA_OBC2-1.0.offxml, which are experimental implementations of GBSA models. These are primarily used in validation tests against OpenMM's models, and their version numbers will increment if bugfixes are necessary.

0.4.1 Bugfix Release

0.4.1

This update fixes several toolkit bugs that have been reported by the community. Details of these bugfixes are provided below.

It also refactors how ParameterType and ParameterHandler store their attributes, by introducing ParameterAttribute and IndexedParameterAttribute. These new attribute-handling classes provide a consistent backend which should simplify manipulation of parameters and implementation of new handlers.

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.

Bug fixes

• PR #329: Fixed a bug where the two BondType parameter attributes k and length were treated as indexed attributes. (per the SMIRNOFF spec, k and length values that correspond to specific bond orders will be indexed under k_bondorder1, k_bondorder2, etc when implemented in the future)
• PR #329: Fixed a bug that allowed setting indexed attributes to single values instead of strictly lists.
• PR #370: Fixed a bug in the API where BondHandler, ProperTorsionHandler, and ImproperTorsionHandler exposed non-functional indexed parameters.
• PR #351: Fixes Issue #344, in which the main FrozenMolecule constructor and several other Molecule-construction functions ignored or did not expose the allow_undefined_stereo keyword argument.
• PR #351: Fixes a bug where a molecule which previously generated a SMILES using one cheminformatics toolkit returns the same SMILES, even though a different toolkit (which would generate a different SMILES for the molecule) is explicitly called.
• PR #354: Fixes the error message that is printed if an unexpected parameter attribute is found while loading data into a ForceField (now instructs users to specify allow_cosmetic_attributes instead of permit_cosmetic_attributes)
• PR #364: Fixes Issue #362 by modifying OpenEyeToolkitWrapper.from_smiles and RDKitToolkitWrapper.from_smiles to make implicit hydrogens explicit before molecule creation. These functions also now raise an error if the optional keyword hydrogens_are_explicit=True but the SMILES are interpreted by the backend cheminformatics toolkit as having implicit hydrogens.
• PR #371: Fixes error when reading early SMIRNOFF 0.1 spec files enclosed by a top-level SMIRFF tag.
  • Note: The enclosing SMIRFF tag is present only in legacy files. Since developing a formal specification, the only acceptable top-level tag value in a SMIRNOFF data structure is SMIRNOFF.

Code enhancements

• PR #329: ParameterType was refactored to improve its extensibility. It is now possible to create new parameter types by using the new descriptors ParameterAttribute and IndexedParameterAttribute.
• PR #357: Addresses Issue #356 by raising an informative error message if a user attempts to load an OpenMM topology which is probably missing connectivity information.

Force fields added

• PR #368: Temporarily adds test_forcefields/smirnoff99frosst_experimental.offxml to address hierarchy problems, redundancies, SMIRKS pattern typos etc., as documented in issue #367. Will ultimately be propagated to an updated forcefield in the openforcefield/smirnoff99frosst repo.
• PR #371: Adds test_forcefields/smirff99Frosst_reference_0_1_spec.offxml, a SMIRNOFF 0.1 spec file enclosed by the legacy SMIRFF tag. This file is used in backwards-compatibility testing.