Metadata-Version: 2.4
Name: bdfqmmm
Version: 0.1.6
Summary: BDF QM/MM toolkit
Author: BDF QM/MM Toolkit Developers
License-Expression: MIT AND CECILL-2.0 AND LGPL-3.0-or-later AND Apache-2.0 WITH LLVM-exception AND BSD-3-Clause AND GPL-3.0-or-later WITH GCC-exception-3.1
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
License-File: external/pdynamo2/Licence_CeCILL_V2-en.txt
License-File: external/dl-find/COPYING
License-File: external/dl-find/COPYING.LESSER
License-File: licenses/LLVM-LICENSE.TXT
License-File: licenses/OpenBLAS-LICENSE
License-File: licenses/GCC-COPYING3
License-File: licenses/GCC-COPYING.RUNTIME
Requires-Dist: PyYAML>=6
Requires-Dist: tomli>=2; python_version < "3.11"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Provides-Extra: build
Requires-Dist: build; extra == "build"
Dynamic: license-file

# 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:

```bash
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:

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

The expected executable is:

```text
/opt/miniconda3/envs/hpc/bin/python
```

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

```bash
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:

```bash
conda run -n hpc bdf-qmmm --help
```

## Installation

### From PyPI

Install the latest release from PyPI:

```bash
python3 -m pip install bdfqmmm
```

Install a specific release:

```bash
python3 -m pip install bdfqmmm==0.1.6
```

### From Gitee

Install the latest source code from the Gitee repository:

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

Install a specific tagged release from Gitee:

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

To clone and install manually:

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

### From a Source Checkout

Install from a source checkout:

```bash
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:

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

Fedora and RHEL-family systems can use:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

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

Show the resolved BDF runtime configuration:

```bash
bdf-qmmm config show
```

Validate the configured paths:

```bash
bdf-qmmm config check
```

The default user configuration file is:

```text
~/.config/bdfqmmm/config.toml
```

Configuration priority is:

```text
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:

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

Generate starter files with:

```bash
bdf-qmmm init my-qmmm-job
```

A minimal `qmmm.toml` looks like:

```toml
[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:

```toml
[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`](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`](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`](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:

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

The current implementation still supports the legacy forms:

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

The full supported selection format is recorded in
[`docs/selection-language.md`](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`](docs/system-conversion.md).

```bash
bdf-qmmm check qmmm.toml
```

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

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

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

```bash
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`](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:

```tcl
source regions.vmd.tcl
```

Run the calculation:

```bash
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

```text
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`](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`](docs/roadmap.md) and
[`docs/project-status.md`](docs/project-status.md). Architectural decisions are
recorded in [`docs/adr/`](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`.
