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.

0.4.0 Performance optimizations and support for SMIRNOFF 0.3 specification

0.4.0

This update contains performance enhancements that significantly reduce the time to create OpenMM systems for topologies containing many molecules via ForceField.create_openmm_system.

This update also introduces the SMIRNOFF 0.3 specification. The spec update is the result of discussions about how to handle the evolution of data and parameter types as further functional forms are added to the SMIRNOFF spec.

We provide methods to convert SMIRNOFF 0.1 and 0.2 forcefields written with the XML serialization (.offxml) to the SMIRNOFF 0.3 specification. These methods are called automatically when loading a serialized SMIRNOFF data representation written in the 0.1 or 0.2 specification. This functionality allows the toolkit to continue to read files containing SMIRNOFF 0.2 spec force fields, and also implements backwards-compatibility for SMIRNOFF 0.1 spec force fields.

WARNING: The SMIRNOFF 0.1 spec did not contain fields for several energy-determining parameters that are exposed in later SMIRNOFF specs. Thus, when reading SMIRNOFF 0.1 spec data, the toolkit must make assumptions about the values that should be added for the newly-required fields. The values that are added include 1-2, 1-3 and 1-5 scaling factors, cutoffs, and long-range treatments for nonbonded interactions. Each assumption is printed as a warning during the conversion process. Please carefully review the warning messages to ensure that the conversion is providing your desired behavior.

SMIRNOFF 0.3 specification updates

• The SMIRNOFF 0.3 spec introduces versioning for each individual parameter section, allowing asynchronous updates to the features of each parameter class. The top-level SMIRNOFF tag, containing information like aromaticity_model, Author, and Date, still has a version (currently 0.3). But, to allow for independent development of individual parameter types, each section (such as Bonds, Angles, etc) now has its own version as well (currently all 0.3).
• All units are now stored in expressions with their corresponding values. For example, distances are now stored as 1.526*angstrom, instead of storing the unit separately in the section header.
• The current allowed value of the potential field for ProperTorsions and ImproperTorsions tags is no longer charmm, but is rather k*(1+cos(periodicity*theta-phase)). It was pointed out to us that CHARMM-style torsions deviate from this formula when the periodicity of a torsion term is 0, and we do not intend to reproduce that behavior.
• SMIRNOFF spec documentation has been updated with tables of keywords and their defaults for each parameter section and parameter type. These tables will track the allowed keywords and default behavior as updated versions of individual parameter sections are released.

Performance improvements and bugfixes

• PR #329: Performance improvements when creating systems for topologies with many atoms.
• PR #347: Fixes bug in charge assignment that occurs when charges are read from file, and reference and charge molecules have different atom orderings.

New features

• PR #311: Several new experimental functions.
  • Adds convert_0_2_smirnoff_to_0_3, which takes a SMIRNOFF 0.2-spec data dict, and updates it to 0.3. This function is called automatically when creating a ForceField from a SMIRNOFF 0.2 spec OFFXML file.
  • Adds convert_0_1_smirnoff_to_0_2, which takes a SMIRNOFF 0.1-spec data dict, and updates it to 0.2. This function is called automatically when creating a ForceField from a SMIRNOFF 0.1 spec OFFXML file.
  • NOTE: The format of the "SMIRNOFF data dict" above is likely to change significantly in the future. Users that require a stable serialized ForceField object should use the output of ForceField.to_string('XML') instead.
  • Adds ParameterHandler and ParameterType add_cosmetic_attribute and delete_cosmetic_attribute functions. Once created, cosmetic attributes can be accessed and modified as attributes of the underlying object (eg. ParameterType.my_cosmetic_attrib = 'blue'). These functions are experimental, and we are interested in feedback on how cosmetic attribute handling could be improved. (See Issue #338). Note that if a new cosmetic attribute is added to an object without using these functions, it will not be recognized by the toolkit and will not be written out during serialization.
  • Values for the top-level Author and Date tags are now kept during SMIRNOFF data I/O. If multiple data sources containing these fields are read, the values are concatenated using "AND" as a separator.

API-breaking changes

• ForceField.to_string and ForceField.to_file have had the default value of their discard_cosmetic_attributes kwarg set to False.
• ParameterHandler and ParameterType constructors now expect the version kwarg (per the SMIRNOFF spec change above). This requirement can be skipped by providing the kwarg skip_version_check=True
• ParameterHandler and ParameterType functions no longer handle X_unit attributes in SMIRNOFF data (per the SMIRNOFF spec change above).
• The scripts in utilities/convert_frosst are now deprecated. This functionality is important for provenance and will be migrated to the openforcefield/smirnoff99Frosst repository in the coming weeks.
• ParameterType._SMIRNOFF_ATTRIBS is now ParameterType ._REQUIRED_SPEC_ATTRIBS, to better parallel the structure of the ParameterHandler class.
• ParameterType._OPTIONAL_ATTRIBS is now ParameterType ._OPTIONAL_SPEC_ATTRIBS, to better parallel the structure of the ParameterHandler class.
• Added class-level dictionaries ParameterHandler._DEFAULT_SPEC_ATTRIBS and ParameterType._DEFAULT_SPEC_ATTRIBS.

0.3.0 API Improvements

0.3.0

This release makes several improvements and changes to public API.

User feedback indicated a need for a Topology.to_openmm() function, which has been created.

We have also added infrastructure to load forcefields using a plugin-like infrastructure from other packages in the environment. In the near future, an independent smirnoff99Frosst package will be available that provides the validated, revision-controlled forcefield series.

Some functionality that was inadvertently exposed in the 0.2.0 release has been removed (for example, the ForceField.to_smirnoff_data method is now private). Other convenience functions have been added, such as ForceField.to_string, as a close substitute for the functionality removed.

Several bugs were fixed and more informative error messages were added. Details of these changes are below.

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 #292 : Implement Topology.to_openmm and remove ToolkitRegistry.toolkit_is_available
• PR #322: Install directories for the lookup of OFFXML files through the entry point group openforcefield.smirnoff_forcefield_directory. The ForceField class doesn't search in the data/forcefield/ folder anymore (now renamed data/test_forcefields/), but only in data/.

API-breaking Changes

• PR #278: Standardize variable/method names
• PR #291: Remove ForceField.load/to_smirnoff_data, add ForceField.to_file/string and ParameterHandler.add_parameters. Change behavior of ForceField.register_X_handler functions.

Bugfixes and Optimizations

• PR #327: Fix units in tip3p.offxml (note that this file is not loadable by current toolkit)
• PR #325: Fix solvent box for provided test system to resolve periodic clashes.
• PR #325: Add informative message containing Hill chemical formula when a molecule can't be matched in Topology.from_openmm.
• PR #325: Provide warning or error message as appropriate when a molecule is missing stereochemistry.
• PR #316: Fix formatting issues in GBSA section of SMIRNOFF spec
• PR #308: Cache molecule SMILES to improve system creation speed
• PR #306: Allow single-atom molecules with all zero coordinates to be converted to OE/RDK mols
• PR #313: Fix issue where constraints are applied twice to constrained bonds

0.2.2 Bugfix Release

0.2.2

This release modifies an example to show how to parameterize a solvated system, cleans up backend code, and makes several improvements to the README.

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.

Bugfixes

• PR #279: Cleanup of unused code/warnings in main package __init__
• PR #259: Update T4 Lysozyme + toluene example to show how to set up solvated systems
• PR #256 and PR #274: Add functionality to ensure that links in READMEs resolve successfully

Bugfix release

0.2.1

This release features various documentation fixes, minor bugfixes, and code cleanup.

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

Bugfixes

• PR #267: Add neglected <ToolkitAM1BCC> tag to the SMIRNOFF 0.2 spec
• PR #258: General cleanup and removal of unused/inaccessible code.
• PR #244: Improvements and typo fixes for BRD4:inhibitor benchmark

Initial RDKit support

0.2.0

This version of the toolkit introduces RDKit support and many new features on the way to a stable 1.0 release.

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

Major new features

• Major overhaul, resulting in the creation of the 0.2 SMIRNOFF specification and its XML representation
• Updated API and infrastructure for reference SMIRNOFF ForceField implementation
• Implementation of modular ParameterHandler classes which process the topology to add all necessary forces to the system..
• Implementation of modular ParameterIOHandler classes for reading/writing different serialized SMIRNOFF forcefield representations
• Introduction of Molecule and Topology classes for representing molecules and biomolecular systems
• New ToolkitWrapper interface to RDKit, OpenEye, and AmberTools cheminformatics toolkits, managed by ToolkitRegistry
• API improvements to more closely follow PEP8 guidelines
• Improved documentation and examples

Version 0.1.0

This is an early preview release of the openforcefield toolkit that matches the functionality described in the preprint describing the SMIRNOFF v0.1 force field format: [DOI]

New features

This release features additional documentation, code comments, and support for automated testing.

Bugfixes

A significant (though currently unused) problem in handling of improper torsions was corrected.
Previously, non-planar impropers did not behave correctly, as six-fold impropers have two potential chiralities.
To remedy this, SMIRNOFF impropers are now implemented as three-fold impropers with consistent chirality.
However, current force fields in the SMIRNOFF format had no non-planar impropers, so this change is mainly aimed at future work.

Version 0.0.4

Most significantly, this release adds a small but nonzero set of LJ parameters to smirnoff99Frosst, as per (soon forthcoming) SMIRNOFF paper draft/discussion. Additional changes are:

• Minor fixes to cyclobutane parameters in smirnoff99Frosst
• Versioneer support
• Documentation via sphinx
• Rename .ffxml files to .offxml to avoid confusion with "normal" OpenMM .ffxml files, which are a totally different format
• Remove wildcard generics from smirnoff99Frosst; add a separate .offxml file with (improved) generics in case anyone wants to use these.

Version 0.0.3

This version:

• Fixes a compatibility issue with updated NetworkX
• Makes extensive updates to documentation
• Adds a considerable number of examples
• Makes OpenMM topologies generated preserve bond order
• Adds monovalent ion parameters
• Changes use of a SMIRKS decorator (R vs x) in smirnoff99Frosst for better consistency with non-OpenEye SMARTS/SMIRKS parsers
• Removes an extra application of OEAssignImplicitHydrogens which could in some cases result in openforcefield changing the protonation state of a molecule

Version 0.0.2

This version:

• Finishes migration of many tools from smarty to openforcefield
• Removes outdated examples and data
• Adds support for tip3p water and constraints, tests for the same; adds water monomers
• Extensively updates documentation
• Updates Jupyter notebooks
• Makes some fixes to chemical environments
• Fixes a bug where vdW parameters for mixtures consisting of multiple references molecules could get scrambled (and adds a test for this)
• Fixes a typo in descring the SMIRNOFF format (formerly SMIRFF) and finishes name change from SMIRFF to SMIRNOFF
• Adds an example of generating a mixed force field for a protein-ligand complex (AMBER protein force field, SMIRNOFF ligand)