DOCSEARCHbyAlgolia
Submit Docs

Open Force Field Toolkit

repository·main·Indexed 18 days ago

https://github.com/openforcefield/openff-toolkit

A Python library for developing and applying modern molecular mechanics force fields based on direct chemical perception and the SMIRNOFF specification. It provides tools for parameterizing protein-ligand systems, computing conformer energies, manipulating SMIRNOFF parameters via the ForceField class, and integrating with OpenMM, AMBER, and GROMACS.

Tokens
35.4K
Snippets
92
Records
189
Agent score
64%

What's inside openff-toolkit

  1. What is the Open Force Field toolkit?

    main

    The Open Force Field Toolkit is a Python-based toolkit developed by the Open Force Field Initiative. It is designed for the development and application of modern molecular mechanics force fields using direct chemical perception and rigorous statistical parameterization.

    The toolkit focuses on two primary areas:

    1. Tools for using SMIRKS Native Open Force Field (SMIRNOFF) force fields.
    2. Tools for direct chemical environment perception and manipulation.

    Note on Namespace Migration: Prior to version 0.9.0, the toolkit was named openforcefield and used different import paths. Users on older versions should refer to the v0.9.0 release notes for migration instructions.

  2. Index of OpenFF Toolkit usage examples

    main

    The following example notebooks cover common tasks and advanced workflows using the toolkit and the SMIRNOFF format:

    • System Parameterization & Simulation:

      • toolkit_showcase: Parameterize a protein-ligand system, simulate it, and visualize the results.
      • SMIRNOFF_simulation: Simulate a molecule in the gas phase using the SMIRNOFF format.
      • using_smirnoff_in_amber_or_gromacs: Convert an OpenFF-generated System into AMBER (prmtop/inpcrd) or GROMACS (top/gro) files using the ParmEd library.
      • using_smirnoff_with_amber_protein_forcefield: Combine SMIRNOFF parameters for small molecules with conventional protein force fields using ParmEd.

    • Force Field Manipulation & Inspection:

      • forcefield_modification: Modify force field parameters and evaluate the resulting changes in system energy.
      • inspect_assigned_parameters: Check which parameters are assigned to specific molecules and generate usage statistics.
      • swap_amber_parameters: Replace ligand parameters in an existing AMBER protein-ligand system with OpenFF parameters.

    • Molecular Analysis & Data Integration:

      • conformer_energies: Compute conformer energies for one or more small molecules using a SMIRNOFF force field.
      • QCArchive_interface: Retrieve data from the QCArchive directly into Molecule objects.
      • vsite_showcase: Use SMIRNOFF force field virtual sites (e.g., for sulfur/chlorine ligands or TIP5P water models).

    • Visualization:

      • visualization: Demonstrates the rich representation of Molecule objects within Jupyter Notebooks.

  3. Understand the data used by openff-toolkit

    main

    The openff-toolkit relies on several data categories to support its functionality, including sample force field files, molecule definitions, and reference data for testing. The following data manifests are available within the toolkit's data ecosystem:

    • forcefield: Sample SMIRNOFF .ffxml files covering various chemical spaces/regions.
    • molecules: Specific molecule files used by the toolkit.
    • systems: Systems composed of mixtures of molecules.
    • proteins: PDB files for example proteins.
    • reference_energies: Reference energy values used specifically for regression tests.

  4. Identify SMIRNOFF FFXML test files for `openff.toolkit.typing.engines.smirnoff.forcefield`

    main

    The openff/toolkit/data/test_forcefields/ directory contains various SMIRNOFF FFXML files used for testing the openff.toolkit.typing.engines.smirnoff.forcefield engine. These files include hand-created force fields for specific chemical regions, files designed to reproduce known errors (like AMBER atom typing issues), and experimental files for validating GBSA models against OpenMM implementations.

    Key Test Files:

    • AlkEthOH Region:
      • Frosst_AlkEthOH.offxml: Original hand-created file.
      • Frosst_AlkEthOH_parmAtFrosst.offxml: Includes intentional 'bugs' to reproduce AMBER-style atom typing errors (e.g., missing torsions).
      • Frosst_AlkEthOH_MDL.offxml: Uses the MDL aromaticity model for bond perception.
      • Frosst_AlkEthOH_withIDs: Includes parameter IDs for force field labeler debugging.
    • Benzene/Impropers:
      • benzene_minimal.offxml: Minimal file for testing improper torsions.
    • GBSA Validation (OpenMM comparison):
      • GBSA_HCT-1.0.offxml: Validates against Hawkins-Cramer-Truhlar (AMBER igb=1).
      • GBSA_OBC1-1.0.offxml: Validates against Onufriev-Bashford-Case GB(OBC)I (AMBER igb=2).
      • GBSA_OBC2-1.0.offxml: Validates against Onufriev-Bashford-Case GB(OBC)II (AMBER igb=5).
    • Backwards Compatibility:
      • smirnoff99Frosst_reference_0_1_spec.offxml and smirnoff99Frosst_reference_0_2_spec.offxml: SMIRNOFF 0.1 and 0.2 spec files enclosed in legacy SMIRFF tags.

  5. What is an OpenFF Interchange?

    main
    An OpenFF Interchange represents a Topology that has been successfully parametrized by a ForceField. It is the final object containing all the information necessary to calculate energy or initiate a molecular dynamics (MD) simulation. Interchange objects provide built-in methods to export the parametrized system to various MD simulation engines.

  6. What is an OpenFF Molecule?

    main

    An OpenFF Molecule is a graph representation of a molecule designed to contain sufficient information for unambiguous parametrization.

    To be valid for parametrization, a Molecule must include:

    • Atoms: element (integer), formal_charge (integer), is_aromatic (boolean), and stereochemistry ('R'/'S'/None).
    • Bonds: order (integer), is_aromatic (boolean), and stereochemistry ('E'/'Z'/None).

    Optional Attributes: Attributes like conformers and partial_charges are optional. While not required for system creation, if they are present, the toolkit allows you to use them to override values that would otherwise be generated automatically during parametrization.

    Metadata: Users can store arbitrary metadata in the Molecule.properties dictionary. This data is treated as cosmetic and does not affect the physics or system creation, but it should be preserved during serialization or format conversion.

  8. What is an OpenFF ForceField?

    main
    An OpenFF ForceField is an object generated from an OFFXML file or other SMIRNOFF data sources. It acts as a container for parametrization data. While some top-level SMIRNOFF data is stored directly in the ForceField object, most of the information is managed by several internal ParameterHandler objects.

  9. Understand the core philosophy of the OpenFF Toolkit

    main
    The OpenFF Toolkit's primary purpose is to combine an Open Force Field ForceField and a Topology to create an OpenMM System. An OpenMM System contains all necessary information to compute potential energy, excluding coordinates and (optionally) box vectors. The toolkit uses a modular "plugin" architecture to provide standard interfaces for new features.

  11. Virtual site association and assignment behavior

    main

    As of version 0.10.5, virtual sites (v-sites) are associated with a single 'parent' atom rather than a set of atoms.

    When checking if a v-site has been assigned, the toolkit now only checks the main 'parent' atom. This can affect assignment order: if multiple v-sites match the same parent atom, the one appearing later in the hierarchy will be assigned. For example, if a bond-charge v-site and a monovalent lone pair both match the same oxygen atom, the monovalent lone pair will be assigned to the oxygen, and the bond-charge site will not be assigned to that specific oxygen in that context.

  12. Use validated collections in the OpenFF Toolkit

    main

    The toolkit includes custom collection types in openff.toolkit.utils.collections to ensure data integrity. Use these when you need to maintain collections with specific validation rules:

    • ValidatedList: A list implementation that enforces validation.
    • ValidatedDict: A dictionary implementation that enforces validation.