BDF QM/MM Toolkit

bdfqmmm is a Python toolkit for building BDF-based QM/MM workflows.

The Python package name is bdfqmmm; the command line entry point is:

bdf-qmmm

Development

For this source tree, local development and example validation are done in the hpc conda environment. Before running bdfqmmm examples or tests, check that Python resolves to the expected environment:

conda run -n hpc python -c "import sys; print(sys.executable)"

The expected executable is:

/opt/miniconda3/envs/hpc/bin/python

Install the project as a normal local wheel in that environment:

conda run -n hpc python -m pip install .

Editable installs are useful for pure-Python development, but they do not place the bundled pDynamo runtime on the installed package import path in the current local environment. Use a normal install before validating installed bdf-qmmm examples.

Check the command line interface:

conda run -n hpc bdf-qmmm --help

Installation

From PyPI

Install the latest release from PyPI:

python3 -m pip install bdfqmmm

Install a specific release:

python3 -m pip install bdfqmmm==0.1.6

From Gitee

Install the latest source code from the Gitee repository:

python3 -m pip install git+https://gitee.com/jgaolab/bdfqmmm.git

Install a specific tagged release from Gitee:

python3 -m pip install git+https://gitee.com/jgaolab/bdfqmmm.git@v0.1.6

To clone and install manually:

git clone https://gitee.com/jgaolab/bdfqmmm.git
cd bdfqmmm
python3 -m pip install .

From a Source Checkout

Install from a source checkout:

python3 -m pip install .

Build Requirements

By default this builds the bundled pDynamo runtime and the bundled DL-FIND optimizer with CMake and installs them into the wheel alongside bdfqmmm. The pDynamo build uses the bundled BLAS/LAPACK code and disables OpenMP by default to keep source installs portable.

Source installs require working C/C++ and Fortran compilers. On macOS, install Xcode Command Line Tools and a Fortran compiler such as gfortran or flang. On Ubuntu or Debian, install the Linux native prerequisites with:

sudo apt-get install build-essential gfortran libblas-dev liblapack-dev

Fedora and RHEL-family systems can use:

sudo dnf install gcc gcc-c++ gcc-gfortran blas-devel lapack-devel

The source build checks for the Linux compilers before starting and CMake automatically detects BLAS/LAPACK. Missing dependencies produce an error with the corresponding package-manager commands. Python build dependencies such as CMake and Cython are declared in pyproject.toml and are installed automatically by pip when build isolation is enabled.

For a non-standard BLAS/LAPACK installation, provide separate linker and CMake overrides. For example, an LP64 OpenBLAS installation under /opt/openblas can be selected with:

export BDFQMMM_DLFIND_MATH_LINK_ARGS="-L/opt/openblas/lib -Wl,-rpath,/opt/openblas/lib -lopenblas"
export BDFQMMM_MOLDEN2RESP_CMAKE_ARGS="-DEXT_MATHLIB=/opt/openblas/lib/libopenblas.so"
export LD_LIBRARY_PATH="/opt/openblas/lib:${LD_LIBRARY_PATH:-}"
python3 -m pip install .

Use an LP64 BLAS/LAPACK build. DL-FIND's BDF-facing callback integers are 8 bytes, but its BLAS/LAPACK adapter deliberately passes 32-bit c_int dimensions. An ILP64 library is therefore not ABI-compatible with this build.

Extra CMake options can be passed with:

BDFQMMM_PDYNAMO_CMAKE_ARGS="-DPDYNAMO_USE_OPENMP=ON" python3 -m pip install .
BDFQMMM_DLFIND_CMAKE_ARGS="-DENABLE_MPI=OFF" python3 -m pip install .

For a quick Python-only install during documentation or CLI development:

BDFQMMM_SKIP_PDYNAMO_BUILD=1 BDFQMMM_SKIP_DLFIND_BUILD=1 python3 -m pip install .

This mode does not install pDynamo or DL-FIND and should not be used for production QM/MM workflows.

BDF Configuration

After installing bdfqmmm, record the bdfrc file generated by the BDF installation:

bdf-qmmm config set-bdfrc /path/to/bdfrc

Show the resolved BDF runtime configuration:

bdf-qmmm config show

Validate the configured paths:

bdf-qmmm config check

The default user configuration file is:

~/.config/bdfqmmm/config.toml

Configuration priority is:

environment variables > bdfqmmm config file > bdfrc values

Supported environment variables are BDFHOME, BDF_TMPDIR, BDF_MPIRUN, BDF_MPIROOT, BDFRC, and BDFQMMM_CONFIG.

QM/MM Input Files

The first general-purpose runner uses two text files:

qmmm.toml        # system, QM/MM regions, job type, output
bdf-method.inp   # BDF method template

Generate starter files with:

bdf-qmmm init my-qmmm-job

A minimal qmmm.toml looks like:

[system]
format = "amber"
topology = "system.parm7"
coordinates = "system.rst7"
disable_symmetry = true

[qm_region]
selection = ":BPH"

[active_region]
selection = "(qm :< 8.0) & ~qm"

[mm_region]
coupling = "RC Coupling"

[bdf]
template = "bdf-method.inp"

[job]
type = "energy"
minimizer = "lbfgs"

[output]
directory = "qmmm_output"
prefix = "qmmm"

DL-FIND transition-state/path jobs are available through explicit job types:

[job]
type = "dlfind_prfo"       # or dlfind_dimer / dlfind_neb
minimizer = "dlfind_lbfgs"

[dlfind]
# dimer: mode = [...]
# NEB: endpoint = [...] or endpoint_file = "product.rst7"

See docs/dlfind-ts-path-qmmm.md for the first P-RFO, dimer and NEB input snippets and current reachability-fixture caveats. The existing water example also includes example/1qmmm_water/qmmm-dlfind-prfo.toml as a small DL-FIND/P-RFO interface smoke input. It is useful for checking the runner path, not as a chemically meaningful transition-state example. Compact Amber-backed TS/path examples are also available under example/5dlfind_ts_path, covering NH3 P-RFO, NH3 dimer, and an HCN/HNC-style same-shell NEB fixture.

The planned selection language is ChimeraX-like, with common Amber mask compatibility and selected VMD-like aliases. Recommended examples are:

:BPH
/A:30
(:BPH :< 8.0) & ~:BPH
(qm :< 8.0) & ~qm

The current implementation still supports the legacy forms:

range:431-451
list:431,432,433
file:active_atoms.txt

The full supported selection format is recorded in docs/selection-language.md. Validate the text input without loading pDynamo:

bdfqmmm currently expects an already parameterized Amber system. If your starting point is a Gromacs or NAMD/CHARMM system, convert it to Amber prmtop/rst7 first; see docs/system-conversion.md.

bdf-qmmm check qmmm.toml

Validate atom-index bounds by also reading the molecular system:

bdf-qmmm check --load-system qmmm.toml

Inspect resolved regions and write human-readable summary/PDB files:

bdf-qmmm inspect qmmm.toml
bdf-qmmm inspect qmmm.toml --pymol
bdf-qmmm inspect qmmm.toml --render-image
bdf-qmmm inspect qmmm.toml --vmd
bdf-qmmm inspect qmmm.toml --reaction-center 123,124,208 \
  --min-boundary-bonds 4 --charged-group-cutoff 4.0 \
  --check-link-atom-clashes --link-clash-scale 0.70 \
  --report-json qmmm_region_check.json

The inspection output is written below [output].directory/inspection/ by default and includes selection_summary.txt, qm_region.pdb, active_region.pdb, inactive_region.pdb, and boundary_quality.txt. The boundary-quality report checks covalent cuts, functional-group integrity, reaction-center topological distance, nearby charged MM groups, and optional predicted link-H steric clashes without changing the QM selection. See docs/qmmm-boundary-quality.md. --pymol also writes regions.pml. --render-image writes the script and then runs a local pymol -cq render to produce regions.png. --vmd writes a full-system regions.pdb plus regions.vmd.tcl; in VMD, load the Tcl script with:

source regions.vmd.tcl

Run the calculation:

bdf-qmmm run qmmm.toml

Supported first-pass job types are energy, opt, alternating_opt, tddft_energy, and tddft_opt. For simple ground-state jobs without a BDF template, [bdf] keywords = "GB3LYP:6-31g" can be used instead.

Project Layout

bdfqmmm/
├── src/
│   └── bdfqmmm/        # BDF QM/MM toolkit source code
├── external/
│   └── pdynamo2/       # Vendored pDynamo2 runtime source and parameters
├── tests/              # Lightweight package tests only
├── docs/
└── pyproject.toml

Third-party packages that are checked into this repository should live under external/. Project-owned Python code should stay under src/bdfqmmm/.

Project-owned code should follow the readability and error-handling guidelines in docs/engineering-guidelines.md. In particular, cross-language bridge code should have clear comments around callback flow, units, ownership, and error propagation.

Project direction and continuation notes are tracked in docs/roadmap.md and docs/project-status.md. Architectural decisions are recorded in docs/adr/.

Large QM/MM examples, BDF examples, functional tests, benchmarks, trajectories, and reference outputs should live in a separate repository such as bdfqmmm-tests.

License

Project-owned bdfqmmm code is licensed under the MIT License.

This source distribution also bundles third-party pDynamo2 code under external/pdynamo2, which remains under its original license terms, including CeCILL v2 and LGPL-3.0-or-later notices in selected bundled sources. See LICENSE, THIRD_PARTY_NOTICES.md, and external/pdynamo2/Licence_CeCILL_V2-en.txt.