Q2MM

Quantum-guided molecular mechanics force field optimization.

Q2MM optimizes molecular mechanics (MM) force field parameters by minimizing the difference between MM-calculated properties and quantum mechanics (QM) reference data. It is designed for building transition state force fields (TSFFs) that enable rapid virtual screening of enantioselective catalysts.

📖 Documentation

Why Q2MM?

• Hessian-informed initialization — QFUERZA extracts bond and angle force constants directly from QM Hessians, providing excellent starting parameters before optimization begins.
• Open-source backends — first-class support for OpenMM and Psi4 alongside commercial packages (Gaussian, Schrödinger, Tinker).
• Clean, modular architecture — format-agnostic data models (ForceField, Q2MMMolecule) decouple algorithms from file formats.
• Modern optimization — powered by scipy.optimize with L-BFGS-B, Nelder-Mead, trust-region, and Levenberg-Marquardt methods.
• Transition state support — negative force constants, torsion parameters, and proper eigenvalue handling for saddle-point geometries.

Quick Start

pip install "q2mm[openmm,optimize]"   # OpenMM backend + scipy optimizer

Pre-release: the current version is an alpha. Add --pre to any install command (e.g. pip install --pre "q2mm[openmm,optimize]") if a stable release hasn't been published yet.

GPU acceleration: OpenMM CUDA works on Linux, WSL2, and native Windows. For the full GPU stack (JAX CUDA + JAX-MD), use Linux or WSL2. See the Platform Support guide for details.

For development, clone the repo and install in editable mode:

pip install -e ".[dev]"

from q2mm.optimizers.objective import ReferenceData, ObjectiveFunction
from q2mm.optimizers.scipy_opt import ScipyOptimizer
from q2mm.models.seminario import qfuerza_fresh
from q2mm.backends.mm import OpenMMEngine

# 1. Load QM reference data and molecule from a Gaussian checkpoint
ref, mol = ReferenceData.from_fchk("ts-optimized.fchk", bond_tolerance=1.4)

# 2. Build the initial force field from the QM Hessian (QFUERZA)
ff = qfuerza_fresh(mol, au_hessian=True)

# 3. Set up the objective function and optimize
engine = OpenMMEngine()
obj = ObjectiveFunction(ff, engine, [mol], ref)
result = ScipyOptimizer(method="L-BFGS-B").optimize(obj)

print(result.summary())

ReferenceData.from_fchk() auto-extracts bond lengths and angles from the QM geometry. You can also use from_gaussian() for .log files, or from_molecule() for maximum control. See the Tutorial for the full workflow including frequencies, eigenmatrix data, and multi-molecule fits.

Supported Backends

Backend	Type	License
OpenMM	MM	MIT
JAX	MM	Apache 2.0
JAX-MD	MM	Apache 2.0
Tinker	MM	Free (academic)
Psi4	QM	BSD-3
Gaussian	QM	Commercial
Schrödinger	QM/MM	Commercial

License

MIT. See LICENSE.

Contributing

See CONTRIBUTING.md for development setup, testing with Docker, and submitting changes.