Getting Started

This page covers installation and a quick sanity check. For a full parameterization walkthrough, see the Tutorial.

Installation

Requirements

Python 3.10 or newer is required.

From PyPI (recommended)

pip install q2mm                   # core package
pip install "q2mm[openmm]"         # with OpenMM backend
pip install "q2mm[jax]"            # with JAX backend + optax optimizers
pip install "q2mm[jax-md]"         # with JAX-MD backend (periodic, PBC)
pip install "q2mm[amber]"          # with parmed (AMBER support)
pip install "q2mm[all]"            # all optional dependencies

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

GPU setup

For GPU setup instructions (CUDA, WSL2, verification commands), see Platform Support.

From source (for development)

git clone https://github.com/ericchansen/q2mm.git
cd q2mm
pip install -e ".[dev]"            # editable install with dev tools

---

QM/MM backends

Q2MM can interface with several quantum-mechanical and molecular-mechanics engines. Install the ones your workflow requires:

Backend	Type	License	Install
OpenMM	MM	MIT	pip install openmm
JAX-MD	MM	Apache-2.0	pip install "q2mm[jax-md]" (Linux/macOS/WSL2)
Psi4	QM	BSD-3 (open source)	conda install psi4 -c conda-forge
Tinker	MM	Free (academic)	download
Gaussian	QM	Commercial	Site license
Jaguar (Schrödinger)	QM	Commercial	Site license (Schrödinger Suite)

Tip

You only need the backends relevant to your project — Q2MM will skip unavailable engines gracefully.

---

Quick example

A minimal script that reads QM reference data from the included example files. Clone the repository first to access the example data:

git clone https://github.com/ericchansen/q2mm.git
cd q2mm

from q2mm.io import GaussLog, load_mm3_fld
from q2mm.models import Q2MMMolecule

# Parse a Gaussian log for the QM Hessian (matrix of energy second derivatives)
log = GaussLog("examples/ethane/TS.log")
structure = log.structures[0]
print(f"Atoms: {structure.num_atoms}, Hessian shape: {structure.hess.shape}")

# Load an XYZ geometry into the unified molecule model
mol = Q2MMMolecule.from_xyz("examples/sn2-test/qm-reference/ch3f-optimized.xyz")
print(f"Q2MMMolecule atoms: {mol.n_atoms}")

# Load an MM3 force field
ff = load_mm3_fld("examples/rh-enamide/mm3.fld")
print(f"Bonds: {len(ff.bonds)}, Angles: {len(ff.angles)}")

---

Package structure

q2mm/
├── io/            # File format I/O (Gaussian, Jaguar, MM3, MOL2, AMBER, etc.)
├── backends/      # QM/MM engine integrations (OpenMM, Tinker, JAX, Psi4)
├── diagnostics/   # Benchmarking and convergence analysis
├── models/        # Molecule/force-field models + QFUERZA estimation
└── optimizers/    # Objective functions, scoring, and scipy-based optimization

Next steps

1. Follow the Tutorial for a complete parameterization walkthrough
2. Read Theory & Methods to understand the pipeline
3. See Platform Support for GPU and backend setup