Release History
Releases follow the major.minor.micro
scheme recommended by PEP440, where
major
increments denote a change that may break API compatibility with previousmajor
releasesminor
increments add features but do not break API compatibilitymicro
increments represent bugfix releases or improvements in documentation
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
andMolecule.n_rings
. To find rings in a molecule, directly use a cheminformatics toolkit after usingMolecule.to_rdkit
orMolecule.to_openeye
.Atom.is_in_ring
andBond.is_in_ring
are now methods, not properties.
Behaviors changed and bugfixes
PR #1171: Failure of
Molecule.apply_elf_conformer_selection()
due to excluding all available conformations (Issue #428) now provides a better error. Themake_carboxylic_acids_cis
argument (False
by default) has been added toMolecule.generate_conformers()
to mitigate a common cause of this error. By setting this argument toTrue
in internal use of this method, trans carboxylic acids are no longer generated inMolecule.assign_partial_charges()
andMolecule.assign_fractional_bond_orders()
methods (though users may still pass trans conformers in, they’ll just be pruned by ELF methods). This should work around most instances of the OpenEye Omega bug where trans carboxylic acids are more common than they should be.
Improved documentation and warnings
PR #1172: Adding discussion about constraints to the FAQ
PR #1173: Expand on the SMIRNOFF section of the toolkit docs
PR #855: Refactors
Atom.is_in_ring
andBond.is_in_ring
to use corresponding functionality in OpenEye and RDKit wrappers.
0.10.2 Bugfix release
API-breaking changes
PR #1118:
Molecule.to_hill_formula
is now a class method and no longer accepts input of NetworkX graphs.
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 thematch
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 useMolecule.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 lowercaseNone
.PR #1149:
TopologyAtom
,TopologyBond
, andTopologyVirtualSite
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 recommendedimportlib_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
andMessageException
, 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 aValueError
will be raised. This mirrors the behavior ofMolecule.assign_partial_charges
.PR #1050: Conformer generation failures in
OpenEyeToolkitWrapper.generate_conformers
, andRDKitToolkitWrapper.generate_conformers
now each raiseopenff.toolkit.utils.exceptions.ConformerGenerationError
if conformer generation fails. The same behavior occurs inMolecule.generate_conformers
, but only when thetoolkit_registry
argument is aToolkitWrapper
, not when it is aToolkitRegistry
.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 theMolecule.to_rdkit()
method have theNoImplicit
property set toTrue
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
, andTopology.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’srdkit
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 feedsQCElemental.Molecule
an empty list for theconnectivity
field; now feedsNone
.
Tests updated
PR #1017: Ensures that OpenEye-only CI builds really do lack both AmberTools and RDKit.
Improved documentation and warnings
0.10.0 Improvements for force field fitting
Behaviors changed
PR #1021: Renames
openff.toolkit.utils.exceptions.ParseError
toopenff.toolkit.utils.exceptions.SMILESParseError
to avoid a conflict with an identically-named exception in the SMIRNOFF XML parsing code.PR #1021: Renames and moves
openff.toolkit.typing.engines.smirnoff.forcefield.ParseError
toopenff.toolkit.utils.exceptions.SMIRNOFFParseError
. ThisParseError
is deprecated and will be removed in a future release.
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()
andOEAtomBase.SetName()
methods, rather that the non-standardOEAtomBase.GetData("name")
andOEAtomBase.SetData("name", name)
.PR #1007: Resolves Issue #456 by adding the
normalize_partial_charges
(default isTrue
) keyword argument toMolecule.assign_partial_charges
,AmberToolsToolkitWrapper.assign_partial_charges
,
OpenEyeToolkitWrapper.assign_partial_charges
,RDKitToolkitWrapper.assign_partial_charges
, andBuiltInToolkitWrapper.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 runningcreate_openmm_system
.PR #954: Adds
LibraryChargeType.from_molecule
which returns aLibraryChargeType
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 theNonbondedForce
is set to the cutoff of thevdWHandler
when it and aElectrostatics
handler are present in the force field.PR #850:
OpenEyeToolkitWrapper.is_available
now returnsTrue
if any OpenEye tools are licensed (and installed). This allows, i.e, use of functionality that requiresOEChem
without having anOEOmega
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
FrozenMolecule.compute_virtual_site_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
Adding virtual sites via the
Molecule
API now have defaults forsigma
,epsilon
, andcharge_increment
set to 0 with appropriate units, rather thanNone
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()
andto_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 byForceField.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 APIPR #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 asfrom_file()
.from_smiles()
now raises anopenff.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. Simplyconda install -c conda-forge openff-toolkit-examples
and then run theopenff-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
PR #762:
Molecule.from_rdkit
now converts implicit hydrogens into explicit hydrogens by default. This change may affectRDKitToolkitWrapper/Molecule.from_smiles
,from_mapped_smiles
,from_file
,from_file_obj
,from_inchi
, andfrom_qcschema
. This new behavior can be disabled using thehydrogens_are_explicit=True
keyword argument tofrom_smiles
, or loading the molecule into the desired explicit protonation state in RDKit, then callingfrom_rdkit
on the RDKit molecule withhydrogens_are_explicit=True
.PR #894: Calls to
Molecule.from_openeye
,Molecule.from_rdkit
,Molecule.from_smiles
,OpenEyeToolkitWrapper.from_smiles
, andRDKitToolkitWrapper.from_smiles
will now load atom maps into the the resultingMolecule's
offmol.properties['atom_map']
field, even if not all atoms have map indices assigned.PR #904:
TopologyAtom
objects now have an element getterTopologyAtom.element
.
Bugfixes
PR #891: Calls to
Molecule/OpenEyeToolkitWrapper.from_openeye
no longer mutate the input OE molecule.PR #897: Fixes enumeration of stereoisomers for molecules with already defined stereochemistry using
RDKitToolkitWrapper.enumerate_stereoisomers
.PR #859: Makes
RDKitToolkitWrapper.enumerate_tautomers
actually use themax_states
keyword argument during tautomer generation, which will reduce resource use in some cases.
Improved documentation and warnings
PR #862: Clarify that
System
objects produced by the toolkit are OpenMMSystem
s in anticipation of forthcoming OpenFFSystem
s. 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.
0.9.1 - Minor feature and bugfix release
New features
PR #839: Add support for computing WBOs from multiple conformers using the AmberTools and OpenEye toolkits, and from ELF10 conformers using the OpenEye toolkit wrapper.
PR #832: Expose ELF conformer selection through the
Molecule
API via a newapply_elf_conformer_selection
function.PR #831: Expose ELF conformer selection through the OpenEye wrapper.
PR #790: Fixes Issue #720 where qcschema roundtrip to/from results in an error due to missing cmiles entry in attributes.
PR #793: Add an initial ELF conformer selection implementation which uses RDKit.
PR #799: Closes Issue #746 by adding
Molecule.smirnoff_impropers
,Molecule.amber_impropers
,TopologyMolecule.smirnoff_impropers
,TopologyMolecule.amber_impropers
,Topology.smirnoff_impropers
, andTopology.amber_impropers
.PR #847: Instances of
ParameterAttribute
documentation can now specify their docstrings with the optionaldocstring
argument to the__init__()
method.PR #827: The setter for
Topology.box_vectors
now infers box vectors when box lengths are pass as a list of length 3.
Behavior changed
PR #802: Fixes Issue #408. The 1-4 scaling factor for electrostatic interactions is now properly set by the value specified in the force field. Previously it fell back to a default value of 0.83333. The toolkit may now produce slightly different energies as a result of this change.
PR #839: The average WBO will now be returned when multiple conformers are provided to
assign_fractional_bond_orders
usinguse_conformers
.PR #816: Force field file paths are now loaded in a case-insensitive manner.
Bugfixes
PR #849: Changes
create_openmm_system
so that it no longer uses the conformers on existing reference molecules (if present) to calculate Wiberg bond orders. Instead, new conformers are always generated during parameterization.
Improved documentation and warnings
PR #838: Corrects spacing of “forcefield” to “force field” throughout documentation. Fixes Issue #112.
PR #846: Corrects dead links throughout release history. Fixes Issue #835.
PR #847: Documentation now compiles with far fewer warnings, and in many cases more correctly. Additionally,
ParameterAttribute
documentation no longer appears incorrectly in classes where it is used. Fixes Issue #397.
0.9.0 - Namespace Migration
This release marks the transition from the old openforcefield
branding over to its new
identity as openff-toolkit
. This change has been made to better represent the role of the
toolkit, and highlight its place in the larger Open Force Field (OpenFF) ecosystem.
From version 0.9.0
onwards the toolkit will need to be imported as import openff.toolkit.XXX
and
from openff.toolkit import XXX
.
API-breaking changes
PR #803: Migrates
openforcefield
imports toopenff.toolkit
.
0.8.4 - Minor feature and bugfix release
This release is intended to be functionally identical to 0.9.1. The only difference is that it uses the “openforcefield” namespace.
This release is a final patch for the 0.8.X
series of releases of the toolkit, and also marks the last
version of the toolkit which will be imported as import openforcefield.XXX
/ from openforcefield import XXX
.
From version 0.9.0
onwards the toolkit will be importable only as import openff.toolkit.XXX
/
from openff.toolkit import XXX
.
Note This change will also be accompanied by a renaming of the package from openforcefield
to openff-toolkit
,
so users need not worry about accidentally pulling in a version with changed imports. Users will have to explicitly
choose to install the openff-toolkit
package once released which will contain the breaking import changes.
0.8.3 - Major bugfix release
This release fixes a critical bug in van der Waals parameter assignment.
This release is also a final patch for the 0.8.X
series of releases of the toolkit, and also marks the last
version of the toolkit which will be imported as import openforcefield.XXX
/ from openforcefield import XXX
.
From version 0.9.0
onwards the toolkit will be importable only as import openff.toolkit.XXX
/
from openff.toolkit import XXX
.
Note This change will also be accompanied by a renaming of the package from openforcefield
to openff-toolkit
,
so users need not worry about accidentally pulling in a version with changed imports. Users will have to explicitly
choose to install the openff-toolkit
package once released which will contain the breaking import changes.
Bugfixes
PR #808: Fixes Issue #807, which tracks a major bug in the interconversion between a vdW
sigma
andrmin_half
parameter.
New features
0.8.2 - Bugfix release
WARNING: This release was later found to contain a major bug, Issue #807, and produces incorrect energies.
Bugfixes
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 settingsigma
orrmin_half
using Quantities represented as strings resulted in an error.
0.8.1 - Bugfix and minor feature release
WARNING: This release was later found to contain a major bug, Issue #807, and produces incorrect energies.
API-breaking changes
PR #757: Renames
test_forcefields/smirnoff99Frosst.offxml
totest_forcefields/test_forcefield.offxml
to avoid confusion with any of the ACTUAL released FFs in the smirnoff99Frosst linePR #751: Removes the optional
oetools=("oechem", "oequacpac", "oeiupac", "oeomega")
keyword argument fromOpenEyeToolkitWrapper.is_available
, as there are no special behaviors that are accessed in the case of partially-licensed OpenEye backends. The new behavior of this method is the same as if the default value above is always provided.
Behavior Changed
PR #583: Methods such as
Molecule.from_rdkit
andMolecule.from_openeye
, which delegate their internal logic toToolkitRegistry
functions, now guarantee that they will return an object of the correct type when being called onMolecule
-derived classes. Previously, running these constructors using subclasses ofFrozenMolecule
would not return an instance of that subclass, but rather just an instance of aMolecule
.PR #753:
ParameterLookupError
is now raised when passing toParameterList.index
a SMIRKS pattern not found in the parameter list.
New features
PR #751: Adds
LicenseError
, a subclass ofToolkitUnavailableException
which is raised when attempting to add a cheminformaticsToolkitWrapper
for a toolkit that is installed but unlicensed.PR #730: Adds
Topology.is_periodic
.PR #753: Adds
ParameterHandler.__getitem__
to look up individualParameterType
objects.
Bugfixes
PR #745: Fixes bug when serializing molecule with conformers to JSON.
PR #750: Fixes a bug causing either
sigma
orrmin_half
to sometimes be missing onvdWHandler.vdWType
objects.PR #756: Fixes bug when running
vdWHandler.create_force
using avdWHandler
that was initialized using the API.PR #776: Fixes a bug in which the
Topology.from_openmm
andTopology.from_mdtraj
methods would dangerously allowunique_molecules=None
.PR #777:
RDKitToolkitWrapper
now outputs the full warning message whenallow_undefined_stereo=True
(previously the description of which stereo was undefined was squelched)
0.8.0 - Virtual Sites
Major Feature: Support for the SMIRNOFF VirtualSite tag
This release implements the SMIRNOFF virtual site specification. The implementation enables support
for models using off-site charges, including 4- and 5-point water models, in addition to lone pair
modeling on various functional groups. The primary focus was on the ability to parameterize a
system using virtual sites, and generating an OpenMM system with all virtual sites present and
ready for evaluation. Support for formats other than OpenMM has not be implemented in this release,
but may come with the appearance of the OpenFF system object. In addition to implementing the
specification, the toolkit Molecule
objects now
allow the creation and manipulation of virtual sites.
This change is documented in the Virtual sites page of the user guide.
Minor Feature: Support for the 0.4 ChargeIncrementModel tag
To allow for more convenient fitting of ChargeIncrement
parameters, it is now possible to specify one less
charge_increment
value than there are tagged atoms in a ChargeIncrement
’s smirks
. The missing
charge_increment
value will be calculated at parameterization-time to make the sum of
the charge contributions from a ChargeIncrement
parameter equal to zero.
Since this change allows for force fields that are incompatible with
the previous specification, this new style of ChargeIncrement
must specify a ChargeIncrementModel
section version of 0.4
. All 0.3
-compatible ChargeIncrement
parameters are compatible with
the 0.4
ChargeIncrementModel
specification.
More details and examples of this change are available in The ChargeIncrementModel tag in the SMIRNOFF specification
New features
PR #726: Adds support for the 0.4 ChargeIncrementModel spec, allowing for the specification of one fewer
charge_increment
values than there are tagged atoms in thesmirks
, and automatically assigning the final atom an offsetting charge.PR #548: Adds support for the
VirtualSites
tag in the SMIRNOFF specificationPR #548: Adds
replace
andall_permutations
kwarg toPR #548: Adds
orientations
toPR #548: Adds
PR #705: Adds interpolation based on fractional bond orders for harmonic bonds. This includes interpolation for both the force constant
k
and/or equilibrium bond distancelength
. This is accompanied by a bump in the<Bonds>
section of the SMIRNOFF spec (but not the entire spec).PR #718: Adds
.rings
and.n_rings
toMolecule
and.is_in_ring
toAtom
andBond
Bugfixes
PR #682: Catches failures in
Molecule.from_iupac
instead of silently failing.PR #743: Prevents the non-bonded (vdW) cutoff from silently falling back to the OpenMM default of 1 nm in
Forcefield.create_openmm_system
and instead sets its to the value specified by the force field.PR #737: Prevents OpenEye from incidentally being used in the conformer generation step of
AmberToolsToolkitWrapper.assign_fractional_bond_orders
.
Behavior changed
PR #705: Changes the default values in the
<Bonds>
section of the SMIRNOFF spec tofractional_bondorder_method="AM1-Wiberg"
andpotential="(k/2)*(r-length)^2"
, which is backwards-compatible with and equivalent topotential="harmonic"
.
Examples added
PR #548: Adds a virtual site example notebook to run an OpenMM simulation with virtual sites, and compares positions and potential energy of TIP5P water between OpenFF and OpenMM force fields.
API-breaking changes
PR #548: Methods
Molecule.add_trivalent_lone_pair_virtual_site
now only accept a list of atoms, not a list of integers, to define to parent atoms
PR #548: Removes
outOfPlaneAngle
fromPR #548: Removes
inPlaneAngle
fromTrivalentLonePairVirtualSite
PR #548: Removes
weights
from
Tests added
PR #548: Adds test for
The virtual site parameter handler
TIP5P water dimer energy and positions
Adds tests to for virtual site/particle indexing/counting
0.7.2 - Bugfix and minor feature release
New features
PR #662: Adds
.aromaticity_model
ofForceField
and.TAGNAME
ofParameterHandler
as public attributes.PR #667 and PR #681 linted the codebase with
black
andisort
, respectively.PR #675 adds
.toolkit_version
toToolkitWrapper
and.registered_toolkit_versions
toToolkitRegistry
.PR #696 Exposes a setter for
ForceField.aromaticity_model
PR #685 Adds a custom
__hash__
function toForceField
Behavior changed
PR #684: Changes
ToolkitRegistry
to return an empty registry when initialized with no arguments, i.e.ToolkitRegistry()
and makes theregister_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 #649: Makes SMARTS searches stereochemistry-specific (if stereo is specified in the SMARTS) for both OpenEye and RDKit backends. Also ensures molecule aromaticity is re-perceived according to the ForceField’s specified aromaticity model, which may overwrite user-specified aromaticity on the
Molecule
PR #648: Removes the
utils.structure
module, which was deprecated in 0.2.0.PR #670: Makes the
Topology
returned bycreate_openmm_system
contain the partial charges and partial bond orders (if any) assigned during parameterization.PR #675 changes the exception raised when no
antechamber
executable is found fromIOError
toAntechamberNotFoundError
PR #696 Adds an
aromaticity_model
keyword argument to theForceField
constructor, which defaults toDEFAULT_AROMATICITY_MODEL
.
Bugfixes
PR #715: Closes issue Issue #475 writing a “PDB” file using OE backend rearranges the order of the atoms by pushing the hydrogens to the bottom.
PR #649: Prevents 2020 OE toolkit from issuing a warning caused by doing stereo-specific smarts searches on certain structures.
PR #724: Closes issue Issue #502 Adding a utility function Topology.to_file() to write topology and positions to a “PDB” file using openmm backend for pdb file write.
Tests added
0.7.1 - OETK2020 Compatibility and Minor Update
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.
Behavior changed
PR #646: Checking for
Molecule
equality using the==
operator now disregards all pyrimidal nitrogen stereochemistry by default. To re-enable, useMolecule.{is|are}_isomorphic
with thestrip_pyrimidal_n_atom_stereo=False
keyword argument.PR #646: Adds an optional
toolkit_registry
keyword argument toMolecule.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 aChemicalEnvironment
object as a query.PR #634: Fixes a bug in which calling
RDKitToolkitWrapper.from_file
directly would not load files correctly if passed lowercasefile_format
. Note that this bug did not occur when callingMolecule.from_file
.PR #631: Fixes a bug in which calling
unit_to_string
returnedNone
when the unit is dimensionless. Now"dimensionless"
is returned.PR #630: Closes issue Issue #629 in which the wrong exception is raised when attempting to instantiate a
ForceField
from an unparsable string.
New features
PR #614: Adds
ToolkitRegistry.deregister_toolkit
to de-register registered toolkits, which can include toolkit wrappers loaded intoGLOBAL_TOOLKIT_REGISTRY
by default.PR #656: Adds a new allowed
am1elf10
option to the OpenEye implementation ofassign_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
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.
Here’s a brief rundown of what changed, migration tips, and how to find more details in the full release notes below:
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 foruse_conformers
.Formal charges are now always returned as
simtk.unit.Quantity
objects, with units of elementary charge. To convert them to integers, usefrom simtk import unit
andatom.formal_charge.value_in_unit(unit.elementary_charge)
ormol.total_charge.value_in_unit(unit.elementary_charge)
. Searchatom.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. Searchensure_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. SearchChemicalEnvironment
.TopologyMolecule.topology_particle_start_index
has been removed from theTopologyMolecule
API, since atoms and virtualsites are no longer contiguous in theTopology
particle indexing system. Searchtopology_particle_start_index
.compute_wiberg_bond_orders
has been renamed toassign_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
assign_fractional_bond_orders
methods.Initial (limited) interoperability with QCArchive, via
Molecule.to_qcschema
andfrom_qcschema
.A
Molecule.visualize
method.Several additional
Molecule
methods, including state enumeration and mapped SMILES creation.
Major Feature: Support for the SMIRNOFF ChargeIncrementModel tag
The ChargeIncrementModel tag in the SMIRNOFF specification provides analagous functionality to AM1-BCC, except that instead of AM1-Mulliken charges, a number of different charge methods can be called, and instead of a fixed library of two-atom charge corrections, an arbitrary number of SMIRKS-based, N-atom charge corrections can be defined in the SMIRNOFF format.
The initial implementation of the SMIRNOFF ChargeIncrementModel
tag accepts keywords for version
,
partial_charge_method
, and number_of_conformers
. partial_charge_method
can be any string, and it is
up to the ToolkitWrapper
’s compute_partial_charges
methods to understand what they mean. For
geometry-independent partial_charge_method
choices, number_of_conformers
should be set to zero.
SMIRKS-based parameter application for ChargeIncrement
parameters is different than other SMIRNOFF sections.
The initial implementation of ChargeIncrementModelHandler
follows these rules:
an atom can be subject to many
ChargeIncrement
parameters, which combine additively.a
ChargeIncrement
that matches a set of atoms is overwritten only if anotherChargeIncrement
matches the same group of atoms, regardless of order. This overriding follows the normal SMIRNOFF hierarchy.
To give a concise example, what if a molecule A-B(-C)-D
were being parametrized, and the force field
defined ChargeIncrement
SMIRKS in the following order?
[A:1]-[B:2]
[B:1]-[A:2]
[A:1]-[B:2]-[C:3]
[*:1]-[B:2](-[*:3])-[*:4]
[D:1]-[B:2](-[*:3])-[*:4]
In the case above, the ChargeIncrement from parameters 1 and 4 would NOT be applied to the molecule, since another parameter matching the same set of atoms is specified further down in the parameter hierarchy (despite those subsequent matches being in a different order).
Ultimately, the ChargeIncrement contributions from parameters 2, 3, and 5 would be summed and applied.
It’s also important to identify a behavior that these rules were written to avoid: if not for the
“regardless of order” clause in the second rule, parameters 4 and 5 could actually have been applied six and two times,
respectively (due to symmetry in the SMIRKS and the use of wildcards). This situation could also arise as a result
of molecular symmetry. For example, a methyl group could match the SMIRKS [C:1]([H:2])([H:3])([H:4])
six ways
(with different orderings of the three hydrogen atoms), but the user would almost certainly not intend for the charge
increments to be applied six times. The “regardless of order” clause was added specifically to address this.
In short, the first time a group of atoms becomes involved in a ChargeIncrement
together, the OpenMM System
gains a new
parameter “slot”. Only another ChargeIncrement
which applies to the exact same group of atoms (in any order) can
take over the “slot”, pushing the original ChargeIncrement
out.
Major Feature: Support for ProperTorsion k value interpolation
Chaya Stern’s work
showed that we may be able to produce higher-quality proper torsion parameters by taking into
account the “partial bond order” of the torsion’s central bond. We now have the machinery to compute AM1-Wiberg
partial bond orders for entire molecules using the assign_fractional_bond_orders
methods of either OpenEyeToolkitWrapper
or AmberToolsToolkitWrapper
. The thought is that, if some simple electron population analysis shows
that a certain aromatic bond’s order is 1.53, maybe rotations about that bond can be described well by interpolating
53% of the way between the single and double bond k values.
Full details of how to define a torsion-interpolating SMIRNOFF force fields are available in the ProperTorsions section of the SMIRNOFF specification.
Behavior changed
PR #508: In order to provide the same results for the same chemical species, regardless of input conformation,
Molecule
assign_partial_charges
,compute_partial_charges_am1bcc
, andassign_fractional_bond_orders
methods now default to ignore input conformers and generate new conformer(s) of the molecule before running semiempirical calculations. Users can override this behavior by specifying the keyword argumentuse_conformers=molecule.conformers
.PR #281: Closes Issue #250 by adding support for partial charge I/O in SDF. The partial charges are stored as a property in the SDF molecule block under the tag
<atom.dprop.PartialCharge>
.PR #281: If a
Molecule
’spartial_charges
attribute is set toNone
(the default value), callingto_openeye
will now produce a OE molecule with partial charges set tonan
. This would previously produce an OE molecule with partial charges of 0.0, which was a loss of information, since it wouldn’t be clear whether the original OFFMol’s partial charges were REALLY all-zero as opposed toNone
. OpenEye toolkit wrapper methods such asfrom_smiles
andfrom_file
now produce OFFMols withpartial_charges = None
when appropriate (previously these would produce OFFMols with all-zero charges, for the same reasoning as above).PR #281:
Molecule
to_rdkit
now sets partial charges on the RDAtom’sPartialCharges
property (this was previously set on thepartial_charges
property). If theMolecule
’s partial_charges attribute isNone
, this property will not be defined on the RDAtoms.PR #281: Enforce the behavior during SDF I/O that a SDF may contain multiple molecules, but that the OFF Toolkit does not assume that it contains multiple conformers of the same molecule. This is an important distinction, since otherwise there is ambiguity around whether properties of one entry in a SDF are shared among several molecule blocks or not, or how to resolve conflicts if properties are defined differently for several “conformers” of chemically-identical species (More info here). If the user requests the OFF Toolkit to write a multi-conformer
Molecule
to SDF, only the first conformer will be written. For more fine-grained control of writing properties, conformers, and partial charges, consider usingMolecule.to_rdkit
orMolecule.to_openeye
and using the functionality offered by those packages.PR #281: Due to different constraints placed on the data types allowed by external toolkits, we make our best effort to preserve
Molecule
properties
when converting molecules to other packages, but users should be aware that no guarantee of data integrity is made. The only data format for keys and values in the property dict that we will try to support through a roundtrip to another toolkit’s Molecule object isstring
.PR #574: Removed check that all partial charges are zero after assignment by
quacpac
when AM1BCC used for charge assignment. This check fails erroneously for cases in which the partial charge assignments are correctly all zero, such as forN#N
. It is also an unnecessary check given thatquacpac
will reliably indicate when it has failed to assign charges.PR #597: Energy-minimized sample systems with Parsley 1.1.0.
PR #558: The
Topology
particle indexing system now ordersTopologyVirtualSites
after all atoms.PR #469: When running
Topology.to_openmm
, unique atom names are generated if the provided atom names are not unique (overriding any existing atom names). This uniqueness extends only to atoms in the same molecule. To disable this behavior, set the kwargensure_unique_atom_names=False
.PR #472:
Molecule.__eq__
now uses the newMolecule.are_isomorphic
to perform the similarity checking.PR #472: The
Topology.from_openmm
andTopology.add_molecule
methods now use theMolecule.are_isomorphic
method to match molecules.PR #551: Implemented the
ParameterHandler.get_parameter
function (would previously returnNone
).
API-breaking changes
PR #471: Closes Issue #465.
atom.formal_charge
andmolecule.total_charge
now returnsimtk.unit.Quantity
objects instead of integers. To preserve backward compatibility, the setter foratom.formal_charge
can accept either asimtk.unit.Quantity
or an integer.PR #601: Removes almost all of the previous
ChemicalEnvironment
API, since this entire module was simply copied from Chemper several years ago and has fallen behind on updates. Currently onlyChemicalEnvironment.get_type
,ChemicalEnvironment.validate
, and an equivalent classmethodChemicalEnvironment.validate_smirks
remain. Also, please comment on this GitHub issue if you HAVE been using the previous extra functionality in this module and would like us to prioritize creation of a Chemper conda package.PR #558: Removes
TopologyMolecule.topology_particle_start_index
, since theTopology
particle indexing system now ordersTopologyVirtualSites
after all atoms.TopologyMolecule.atom_start_topology_index
andTopologyMolecule.virtual_particle_start_topology_index
are still available to access the appropriate values in the respective topology indexing systems.PR #508:
OpenEyeToolkitWrapper.compute_wiberg_bond_orders
is nowOpenEyeToolkitWrapper.assign_fractional_bond_orders
. Thecharge_model
keyword is nowbond_order_model
. The allowed values of this keyword have changed fromam1
andpm3
toam1-wiberg
andpm3-wiberg
, respectively.PR #508:
Molecule.compute_wiberg_bond_orders
is nowMolecule.assign_fractional_bond_orders
.PR #595: Removed functions
openforcefield.utils.utils.temporary_directory
andopenforcefield.utils.utils.temporary_cd
and replaced their behavior withtempfile.TemporaryDirectory()
.
New features
PR #471: Closes Issue #208 by implementing support for the
ChargeIncrementModel
tag in the SMIRNOFF specification.PR #471: Implements
Molecule.assign_partial_charges
, which calls one of the newly-implementedOpenEyeToolkitWrapper.assign_partial_charges
, andAmberToolsToolkitWrapper.assign_partial_charges
.strict_n_conformers
is a optional boolean keyword argument indicating whether anIncorrectNumConformersError
should be raised if an invalid number of conformers is supplied during partial charge calculation. For example, if two conformers are supplied, butpartial_charge_method="AM1BCC"
is also set, then there is no clear use for the second conformer. The previous behavior in this case was to raise a warning, and to preserve that behavior,strict_n_conformers
defaults to a value ofFalse
.PR #471: Adds keyword argument
raise_exception_types
(default:[Exception]
) toToolkitRegistry.call
. The default value will provide the previous OpenFF Toolkit behavior, which is that the first ToolkitWrapper that can provide the requested method is called, and it either returns on success or raises an exception. This new keyword argument allows the ToolkitRegistry to ignore certain exceptions, but treat others as fatal. Ifraise_exception_types = []
, the ToolkitRegistry will attempt to call each ToolkitWrapper that provides the requested method and if none succeeds, a singleValueError
will be raised, with text listing the errors that were raised by each ToolkitWrapper.PR #601: Adds
RDKitToolkitWrapper.get_tagged_smarts_connectivity
andOpenEyeToolkitWrapper.get_tagged_smarts_connectivity
, which allow the use of either toolkit for smirks/tagged smarts validation.PR #600: Adds
ForceField.__getitem__
to look upParameterHandler
objects based on their string names.PR #508: Adds
AmberToolsToolkitWrapper.assign_fractional_bond_orders
.PR #469: The
Molecule
class addsMolecule.has_unique_atom_names
andMolecule.has_unique_atom_names
.PR #472: Adds to the
Molecule
classMolecule.are_isomorphic
andMolecule.is_isomorphic_with
andMolecule.hill_formula
andMolecule.to_hill_formula
andMolecule.to_qcschema
andMolecule.from_qcschema
andMolecule.from_mapped_smiles
andMolecule.from_pdb_and_smiles
andMolecule.canonical_order_atoms
andMolecule.remap
Note
The to_qcschema method accepts an extras dictionary which is passed into the validated qcelemental.models.Molecule object.
PR #506: The
Molecule
class addsMolecule.find_rotatable_bonds
PR #521: Adds
Molecule.to_inchi
andMolecule.to_inchikey
andMolecule.from_inchi
Warning
InChI was not designed as an molecule interchange format and using it as one is not recommended. Many round trip tests will fail when using this format due to a loss of information. We have also added support for fixed hydrogen layer nonstandard InChI which can help in the case of tautomers, but overall creating molecules from InChI should be avoided.
PR #529: Adds the ability to write out to XYZ files via
Molecule.to_file
Both single frame and multiframe XYZ files are supported. Note reading from XYZ files will not be supported due to the lack of connectivity information.PR #535: Extends the the API for the
Molecule.to_smiles
to allow for the creation of cmiles identifiers through combinations of isomeric, explicit hydrogen and mapped smiles, the default settings will return isomeric explicit hydrogen smiles as expected.Warning
Atom maps can be supplied to the properties dictionary to modify which atoms have their map index included, if no map is supplied all atoms will be mapped in the order they appear in the
Molecule
.PR #563: Adds
test_forcefields/ion_charges.offxml
, givingLibraryCharges
for monatomic ions.PR #543: Adds 3 new methods to the
Molecule
class which allow the enumeration of molecule states. These areMolecule.enumerate_tautomers
,Molecule.enumerate_stereoisomers
,Molecule.enumerate_protomers
Warning
Enumerate protomers is currently only available through the OpenEye toolkit.
PR #573: Adds
quacpac
error output toquacpac
failure inMolecule.compute_partial_charges_am1bcc
.PR #560: Added visualization method to the the Molecule class.
PR #620: Added the ability to register parameter handlers via entry point plugins. This functionality is accessible by initializing a
ForceField
with theload_plugins=True
keyword argument.PR #582: Added fractional bond order interpolation Adds return_topology kwarg to
Forcefield.create_openmm_system
, which returns the processed topology along with the OpenMMSystem
whenTrue
(defaultFalse
).
Tests added
PR #558: Adds tests ensuring that the new Topology particle indexing system are properly implemented, and that TopologyVirtualSites reference the correct TopologyAtoms.
PR #469: Added round-trip SMILES test to add coverage for
Molecule.from_smiles
.PR #469: Added tests for unique atom naming behavior in
Topology.to_openmm
, as well as tests of theensure_unique_atom_names=False
kwarg disabling this behavior.PR #472: Added tests for
Molecule.hill_formula
andMolecule.to_hill_formula
for the various supported input types.PR #472: Added round-trip test for
Molecule.from_qcschema
andMolecule.to_qcschema
.PR #472: Added tests for
Molecule.is_isomorphic_with
andMolecule.are_isomorphic
with various levels of isomorphic graph matching.PR #472: Added toolkit dependent tests for
Molecule.canonical_order_atoms
due to differences in the algorithms used.PR #472: Added a test for
Molecule.from_mapped_smiles
using the molecule from issue #412 to ensure it is now fixed.PR #472: Added a test for
Molecule.remap
, this also checks for expected error when the mapping is not complete.PR #472: Added tests for
Molecule.from_pdb_and_smiles
to check for a correct combination of smiles and PDB and incorrect combinations.PR #509: Added test for
Molecule.chemical_environment_matches
to check that the complete set of matches is returned.PR #509: Added test for
Forcefield.create_openmm_system
to check that a protein system can be created.PR #506: Added a test for the molecule identified in issue #513 as losing aromaticity when converted to rdkit.
PR #506: Added a verity of toolkit dependent tests for identifying rotatable bonds while ignoring the user requested types.
PR #521: Added toolkit independent round-trip InChI tests which add coverage for
Molecule.to_inchi
andMolecule.from_inchi
. Also added coverage for bad inputs andMolecule.to_inchikey
.PR #529: Added to XYZ file coverage tests.
PR #563: Added LibraryCharges parameterization test for monatomic ions in
test_forcefields/ion_charges.offxml
.PR #543: Added tests to assure that state enumeration can correctly find molecules tautomers, stereoisomers and protomers when possible.
PR #573: Added test for
quacpac
error output forquacpac
failure inMolecule.compute_partial_charges_am1bcc
.PR #579: Adds regression tests to ensure RDKit can be be used to write multi-model PDB files.
PR #582: Added fractional bond order interpolation tests, tests for
ValidatedDict
.
Bugfixes
PR #558: Fixes a bug where
TopologyVirtualSite.atoms
would not correctly applyTopologyMolecule
atom ordering on top of the reference molecule ordering, in cases where the same molecule appears multiple times, but in a different order, in the same Topology.Issue #460: Creates unique atom names in
Topology.to_openmm
if the existing ones are not unique. The lack of unique atom names had been causing problems in workflows involving downstream tools that expect unique atom names.Issue #448: We can now make molecules from mapped smiles using
Molecule.from_mapped_smiles
where the order will correspond to the indeing used in the smiles. Molecules can also be re-indexed at any time using theMolecule.remap
.Issue #462: We can now instance the
Molecule
from a QCArchive entry record instance or dictionary representation.Issue #412: We can now instance the
Molecule
usingMolecule.from_mapped_smiles
. This resolves an issue caused by RDKit considering atom map indices to be a distinguishing feature of an atom, which led to erroneous definition of chirality (as otherwise symmetric substituents would be seen as different). We anticipate that this will reduce the number of times you need to typeallow_undefined_stereo=True
when processing molecules that do not actually contain stereochemistrty.Issue #513: The
Molecule.to_rdkit
now re-sets the aromaticity model after sanitizing the molecule.Issue #500: The
Molecule.find_rotatable_bonds
has been added which returns a list of rotatableBond
instances for the molecule.Issue #491: We can now parse large molecules without hitting a match limit cap.
Issue #474: We can now convert molecules to InChI and InChIKey and from InChI.
Issue #523: The
Molecule.to_file
method can now correctly write toMOL
files, in line with the supported file type list.Issue #568: The
Molecule.to_file
can now correctly write multi-model PDB files when using the RDKit backend toolkit.
Examples added
PR #591 and PR #533: Adds an example notebook and utility to compute conformer energies. This example is made to be reverse-compatible with the 0.6.0 OpenFF Toolkit release.
PR #472: Adds an example notebook QCarchive_interface.ipynb which shows users how to instance the
Molecule
from a QCArchive entry level record and calculate the energy using RDKit through QCEngine.
0.6.0 - Library Charges
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 explanation 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.
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 oneLibraryCharge
. If an atom is covered by multipleLibraryCharge
s, then the lastLibraryCharge
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 atomsA-B-C
connected by single bonds could be matched by a SMIRNOFFLibraryCharges
section containing twoLibraryCharge
SMARTS:A-B
andB-C
. If listed in that order, the molecule would be assigned theA
charge from theA-B
LibraryCharge
element and theB
andC
charges from theB-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-moleculeLibraryCharge
SMARTS whenever possible.PR #455: Addresses Issue #393 by adding
ParameterHandler.attribute_is_cosmetic
andParameterType.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 eitherToolkitAM1BCCHandler
or thecharge_from_molecules
keyword argument toForceField.create_openmm_system
would produce an OpenMMSystem
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 theMolecule.partial_charges
array to be all zeroes, and including the molecule in thecharge_from_molecules
keyword argument tocreate_openmm_system
.PR #433: Due to risks introduced by permitting charge assignment using partially-overlapping
LibraryCharge
s, the toolkit will now raise aopenforcefield.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 theallow_nonintegral_charges=True
keyword argument toForceField.create_openmm_system
.
Tests added
PR #430: Added test for Wiberg Bond Order implemented in OpenEye Toolkits. Molecules taken from DOI:10.5281/zenodo.3405489 . Added by Sukanya Sasmal.
PR #569: Added round-trip tests for more serialization formats (dict, YAML, TOML, JSON, BSON, messagepack, pickle). Note that some are unsupported, but the tests raise the appropriate error.
Bugfixes
PR #431: Fixes an issue where
ToolkitWrapper
objects would improperly search for functionality in theGLOBAL_TOOLKIT_REGISTRY
, even though a specificToolkitRegistry
was requested for an operation.PR #439: Fixes Issue #438, by replacing call to NetworkX
Graph.node
with call toGraph.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 theLibraryCharges
tag.
0.5.1 - Adding the parameter coverage example notebook
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.
Complete details about this release are below.
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 theParameterHandler
that raised the exception (exception.handler_class
).PR #425: Implements Trevor Gokey’s suggestion from Issue #411, which enables pickling of
ForceFields
andParameterHandlers
. Note that, while XML representations ofForceField
s are stable and conform to the SMIRNOFF specification, the pickledForceField
s that this functionality enables are not guaranteed to be compatible with future toolkit versions.
Improved documentation and warnings
PR #425: Addresses Issue #410, by explicitly having toolkit warnings print
Warning:
at the beginning of each warning, 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 theallow_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
andopenforcefield/tests/test_smirnoff.py
.gbsaforces.py
was only used internally andtest_smirnoff.py
tested unsupported functionality from before the 0.2.0 release.
0.5.0 - GBSA support and quality-of-life improvements
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.
New features
PR #363: Implements
GBSAHandler
, which supports the GBSA tag in the SMIRNOFF specification. Currently, only GBSAHandlers withgb_model="OBC2"
support setting non-default values for thesurface_area_penalty
term (default5.4*calories/mole/angstroms**2
), though users can zero the SA term forOBC1
andHCT
models by settingsa_model="None"
. No model currently supports settingsolvent_radius
to any value other than1.4*angstroms
. Files containing experimental SMIRNOFF-format implementations ofHCT
,OBC1
, andOBC2
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
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
ParameterHandler
andParameterType
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
ForceField
constructor would ignoreparameter_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
, andtest_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
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.
Bug fixes
PR #329: Fixed a bug where the two
BondType
parameter attributesk
andlength
were treated as indexed attributes. (k
andlength
values that correspond to specific bond orders will be indexed underk_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
, andImproperTorsionHandler
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 theallow_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 specifyallow_cosmetic_attributes
instead ofpermit_cosmetic_attributes
)PR #364: Fixes Issue #362 by modifying
OpenEyeToolkitWrapper.from_smiles
andRDKitToolkitWrapper.from_smiles
to make implicit hydrogens explicit before molecule creation. These functions also now raise an error if the optional keywordhydrogens_are_explicit=True
but the SMILES are interpreted by the backend cheminformatic 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 descriptorsParameterAttribute
andIndexedParameterAttribute
.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 force field in theopenforcefield/smirnoff99frosst
repo.PR #371: Adds
test_forcefields/smirff99Frosst_reference_0_1_spec.offxml
, a SMIRNOFF 0.1 spec file enclosed by the legacySMIRFF
tag. This file is used in backwards-compatibility testing.
0.4.0 - Performance optimizations and support for SMIRNOFF 0.3 specification
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 force fields 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 likearomaticity_model
,Author
, andDate
, still has a version (currently 0.3). But, to allow for independent development of individual parameter types, each section (such asBonds
,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 forProperTorsions
andImproperTorsions
tags is no longercharmm
, but is ratherk*(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
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 aForceField
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 aForceField
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
andParameterType
add_cosmetic_attribute
anddelete_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
andDate
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
andForceField.to_file
have had the default value of theirdiscard_cosmetic_attributes
kwarg set to False.ParameterHandler
andParameterType
constructors now expect theversion
kwarg (per the SMIRNOFF spec change above) This requirement can be skipped by providing the kwargskip_version_check=True
ParameterHandler
andParameterType
functions no longer handleX_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 theopenforcefield/smirnoff99Frosst
repository in the coming weeks.ParameterType
._SMIRNOFF_ATTRIBS
is nowParameterType
._REQUIRED_SPEC_ATTRIBS
, to better parallel the structure of theParameterHandler
class.ParameterType
._OPTIONAL_ATTRIBS
is nowParameterType
._OPTIONAL_SPEC_ATTRIBS
, to better parallel the structure of theParameterHandler
class.Added class-level dictionaries
ParameterHandler
._DEFAULT_SPEC_ATTRIBS
andParameterType
._DEFAULT_SPEC_ATTRIBS
.
0.3.0 - API Improvements
Several improvements and changes to public API.
New features
PR #292: Implement
Topology.to_openmm
and removeToolkitRegistry.toolkit_is_available
PR #322: Install directories for the lookup of OFFXML files through the entry point group
openforcefield.smirnoff_forcefield_directory
. TheForceField
class doesn’t search in thedata/forcefield/
folder anymore (now renameddata/test_forcefields/
), but only indata/
.
API-breaking Changes
Bugfixes
PR #327: Fix units in tip3p.offxml (note that this file is still 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 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
This release modifies an example to show how to parameterize a solvated system, cleans up backend code, and makes several improvements to the README.
Bugfixes
0.2.1 - Bugfix release
This release features various documentation fixes, minor bugfixes, and code cleanup.
Bugfixes
0.2.0 - Initial RDKit support
This version of the toolkit introduces many new features on the way to a 1.0.0 release.
New features
Major overhaul, resulting in the creation of the SMIRNOFF 0.2 specification and its XML representation
Updated API and infrastructure for reference SMIRNOFF
ForceField
implementationImplementation 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 force field representationsIntroduction of
Molecule
andTopology
classes for representing molecules and biomolecular systemsNew
ToolkitWrapper
interface to RDKit, OpenEye, and AmberTools toolkits, managed byToolkitRegistry
API improvements to more closely follow PEP8 guidelines
Improved documentation and examples
0.1.0
This is an early preview release of the 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
Treatment of improper torsions
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.