---

name: openff-toolkit description: "Use OpenFF Toolkit for molecule processing, SMIRNOFF force fields, topology/system preparation, and optional chemistry backend troubleshooting." disable-model-invocation: true metadata: disco-role: operating license: MIT

OpenFF Toolkit

Use this repo skill when a task involves the Open Force Field Toolkit (openff.toolkit), especially Molecule, Topology, SMIRNOFF .offxml force fields, toolkit wrappers, parameter assignment, molecule/topology conversion, conformers, charges, PDB handling, OpenMM/Interchange handoff, or force-field troubleshooting.

Read First

• references/package-overview.md summarizes package purpose, install shape, important concepts, and cross-skill workflow order.
• references/troubleshooting.md covers cross-cutting install/import, optional dependency, backend, force-field discovery, and workflow routing failures.
• references/repo-provenance.md records the source snapshot and evidence paths used to create this skill; read it before deciding whether the skill is stale.
• scripts/check_openff_toolkit.py --json checks importability, version, available force fields, core classes, and backend wrapper status in the current Python environment.

Route by Task

Task signal	Use this entry point	Why
Build a molecule from SMILES, mapped SMILES, SDF/MOL/SMI/PDB, RDKit/OpenEye objects, conformers, partial charges, stereochemistry, tautomers, SMARTS, visualization, or molecule graph checks	sub-skills/molecules-and-io/SKILL.md	Focuses on single-molecule API usage and safe IO/validation recipes.
Assemble systems from molecules, load PDB files, handle proteins/HETATM records, manage hierarchy metadata, convert to/from OpenMM/MDTraj, write PDB, add constraints, or prepare topologies for parameterization	sub-skills/topology-and-systems/SKILL.md	Owns multi-molecule Topology workflows and PDB/biopolymer assumptions.
Load or edit .offxml, discover installed OpenFF force fields, inspect/modify SMIRNOFF handlers, label assigned parameters, serialize force fields, create Interchange/OpenMM systems, or troubleshoot SMIRNOFF errors	sub-skills/smirnoff-force-fields/SKILL.md	Owns ForceField and SMIRNOFF parameter workflows.
Choose RDKit/OpenEye/AmberTools/NAGL/BuiltIn wrappers, inspect GLOBAL_TOOLKIT_REGISTRY, control registry precedence, diagnose missing optional dependencies, unsupported formats, or charge method failures	sub-skills/toolkit-backends/SKILL.md	Owns optional backend and registry behavior.

Common Workflow Order

1. Check the environment with scripts/check_openff_toolkit.py --json if importability, force-field discovery, or optional backend availability is uncertain.
2. Create or validate Molecule objects with sub-skills/molecules-and-io/SKILL.md.
3. Build the Topology or load a PDB/system with sub-skills/topology-and-systems/SKILL.md.
4. Load/apply/edit a SMIRNOFF force field with sub-skills/smirnoff-force-fields/SKILL.md.
5. Return to sub-skills/toolkit-backends/SKILL.md when the failure is caused by an unavailable wrapper, unsupported file format, charge method, or registry ordering.

Installation and Import Baseline

Prefer package-manager installation for normal users because OpenFF Toolkit depends on compiled chemistry/simulation packages:

mamba create -n openff-toolkit -c conda-forge openff-toolkit

Minimal import check:

from openff.toolkit import ForceField, Molecule, Topology
from openff.toolkit.utils.toolkits import GLOBAL_TOOLKIT_REGISTRY

molecule = Molecule.from_smiles("CCO")
topology = Topology.from_molecules([molecule])
force_field = ForceField("openff-2.3.0.offxml")
print(molecule.n_atoms, topology.n_molecules, force_field.registered_parameter_handlers)
print(GLOBAL_TOOLKIT_REGISTRY.registered_toolkit_versions)

If ForceField("openff-2.3.0.offxml") fails, inspect available force fields and package installation before changing molecule/topology code.

Safe Defaults

• Use Python versions supported by the installed release; this repository snapshot declares Python >=3.12.
• Prefer conda-forge packages for RDKit, AmberTools, OpenMM, Interchange, OpenFF force fields, and OpenFF units.
• Keep toolkit selection explicit for reproducibility: pass toolkit_registry= or a wrapper when behavior must match RDKit, OpenEye, AmberTools, or BuiltIn paths.
• Treat PDB files as topology/system inputs, not reliable molecule graph sources unless hydrogens, elements, bonds, and unique molecules are known.
• Treat .offxml files as SMIRNOFF force-field sources; preserve originals when troubleshooting version, handler, or parameter errors.

What Not To Do

• Do not assume OpenEye, AmberTools, or NAGL are available just because openff.toolkit imports.
• Do not use a bare PDB file as the only source of small-molecule bond orders; prepare unique_molecules when loading PDB systems.
• Do not mutate GLOBAL_TOOLKIT_REGISTRY globally unless the task explicitly needs process-wide behavior; prefer temporary context managers or explicit arguments.
• Do not route force-field parameter problems to molecule IO only; use the SMIRNOFF sub-skill once molecules/topologies are valid.