MPSCF

MPSCF is a GPU-accelerated MCPB workflow for building bonded metal-site force fields. It replaces the Gaussian QM stages with PySCF/GPU4PySCF and produces geometry, Hessian, RESP, frcmod, mol2, and tleap-ready files from one command.

Workflow

flowchart LR
    A[Protein / complex PDB] --> B[Step 1<br/>MCPB model building]
    B --> C[Step 2<br/>GPU geometry + Hessian]
    B --> D[Step 3<br/>GPU RESP]
    C --> E[Step 4<br/>Seminario frcmod]
    D --> F[Step 5<br/>RESP mol2 + tleap]
    E --> F
    F --> G[Amber topology]

    style C fill:#76b900,color:#fff
    style D fill:#76b900,color:#fff

Loading

Step	Main task	Main output
1	Build small/large MCPB models	.com, .in, PDB and mol2 templates
2	Geometry optimization and analytical Hessian	optimized XYZ, Hessian, optional fchk
3	Two-stage constrained RESP	charges, optional fchk
4	Seminario or modified Seminario fitting	_mcpbpy.frcmod
5	Write RESP mol2 and leap input	_mcpbpy.pdb, _tleap.in

Highlights

• GPU4PySCF 1.8 DF-DFT SCF, analytical gradients, and Hessians.
• Multi-GPU topology-aware reduction, dynamic Hessian grid scheduling, and memory-aware CPHF batching through optional gpu.json.
• Closed-shell RKS and open-shell UKS selection from molecular spin.
• Native two-stage RESP with MCPB-style charge/equivalence constraints.
• Complete Gaussian-compatible fchk output without installing MOKIT.
• Optional metal-complex scoring and ligand-pose correction.
• Per-stage GPU memory and utilization curves for performance diagnosis.

Quick start

Run the complete bonded workflow

mpscf input.pdb output_H.pdb \
  --metal-charge ZN:2 \
  --step1 --step2 --step3 --step4 --step5 \
  --json scf_params.json \
  --gpu-json gpu.json

Generate the final Amber topology after the workflow finishes:

tleap -s -f <group_name>_tleap.in

Run one stage from an existing MCPB .in file

Run these commands in a directory containing exactly one .in file:

mpscf --step2 --json scf_params.json --gpu-json gpu.json  # opt + Hessian
mpscf --step3 --json scf_params.json                       # RESP
mpscf --step4 --json scf_params.json                       # frcmod
mpscf --step5 --json scf_params.json                       # mol2 + tleap

Prepare a nonbonded metal model

mpscf input.pdb output_H.pdb --step1 --nb

--nb is a step-1-only path. It removes detected ligands from the prepared PDB and writes a simple ff19SB/OPC tleap input.

Installation

Validated stack: Python 3.11, PySCF 2.14.0, GPU4PySCF 1.8.0, CuPy 13.4.1, CUDA 12.x, OpenMM 8.4.0, pyMSMT 22, and AmberTools.

Create the validated environment

conda create -n gpu4pyscf python=3.11
conda activate gpu4pyscf

conda install -c conda-forge \
  numpy=1.26.4 openmm=8.4.0 pdbfixer=1.12 pymsmt=22.0 ambertools

pip install \
  gpu4pyscf-cuda12x==1.8.0 \
  gpu4pyscf-libxc-cuda12x==0.8.1 \
  pyscf==2.14.0 cupy-cuda12x==13.4.1 cutensor-cu12==2.2.0 \
  basis-set-exchange==0.11 pyscf-dispersion==1.5.0 geometric==1.1 \
  "packaging~=24.0"

git clone https://github.com/KeithTab/MPSCF.git
cd MPSCF
python -m pip install --no-deps --no-build-isolation -e .

Install optional MetalloDock dependencies

pip install -r mpscf/eval/requirements-cu121.txt

This optional runtime is needed only when metal_complex_eval.is_metal_ligand_complex is enabled.

In mixed Conda/PyPI CUDA environments, MPSCF automatically supplies the active Conda CUDA header path when CuPy cannot locate vector_types.h.

Configuration

MPSCF uses two JSON files:

• scf_params.json controls chemistry, convergence, workflow stages, outputs, and profiling.
• gpu.json opts into MPSCF's GPU4PySCF 1.8 memory/scaling layer. Omit --gpu-json to use the native GPU4PySCF schedule.

Minimal SCF configuration

{
  "basis": "def2-svp",
  "auxbasis": "def2-svp-jkfit",
  "xc": "tpssh",
  "device": "auto",
  "cuda_visible_devices": "0,1,2,3",
  "max_cycle": 300,
  "conv_tol": 1e-8,
  "grid_level": 5,
  "maxsteps": 30,
  "hessian": true,
  "hessian_device": "gpu",
  "output_dir": "outputs",
  "write_fchk": true,
  "ff_method": "modseminario"
}

Multi-GPU performance configuration

{
  "gradient_vram_budget_fraction": 0.90,
  "hessian_vram_budget_fraction": 0.70,
  "cphf_subspace_frac": 0.50,
  "cache_xc_kernel": true,
  "cache_xc_kernel_per_device": true,
  "multi_gpu_reduction": "auto",
  "topology_aware": true,
  "topology_reorder_devices": true,
  "hessian_dynamic_grid": true,
  "hessian_grid_chunks_per_device": 2,
  "gradient_overlap_xc_jk": true
}

multi_gpu_reduction: "auto" uses NCCL when available and otherwise reduces inside P2P-connected GPU groups before crossing PCIe/NUMA boundaries. Every optimization has a native fallback for compatibility and CUDA OOM recovery.

GPU memory/utilization profiling

Add these fields to scf_params.json:

{
  "gpu_memory_profile": true,
  "gpu_memory_profile_interval": 0.5,
  "gpu_memory_profile_output": "outputs/gpu_profile"
}

The profiler writes sample/event CSV files, a JSON summary, and an SVG curve. The summary includes phase durations, per-GPU utilization, active fraction, and device-balance diagnostics.

Multi-GPU execution

flowchart TB
    T[CUDA_VISIBLE_DEVICES] --> R[Topology-aware logical GPU 0]
    R --> P1[P2P group A]
    R --> P2[P2P group B]

    Q[Dynamic Hessian grid queue] --> G0[GPU 0]
    Q --> G1[GPU 1]
    Q --> G2[GPU 2]
    Q --> G3[GPU 3]

    G0 --> P1
    G1 --> P1
    G2 --> P2
    G3 --> P2
    P1 --> C{Collective}
    P2 --> C
    C -->|NCCL available| N[NCCL reduction]
    C -->|Fallback| H[Hierarchical P2P reduction]

Loading

GPU4PySCF still owns the numerical DF/Hessian kernels. MPSCF changes only the surrounding workspace limits, response caching, task distribution, and cross-device reduction. The integration is version-checked for GPU4PySCF >=1.8.0,<1.9.0.

Optional metal-complex evaluation

Enable scoring and ligand-pose correction

{
  "metal_complex_eval": {
    "is_metal_ligand_complex": true,
    "correct_ligand_pose": true,
    "ligand_resname": "LIG",
    "num_poses": 20,
    "refine_method": "mmff94s",
    "restrain_metal_donors": true,
    "failure_policy": "error"
  }
}

The input pose remains a candidate. Generated poses must pass configured metal-donor and steric checks before they can replace it. CCD topology is used when available; private ligands can be supplied through ligand_file.

Outputs

Core files

Stage	Files
Optimization	{gname}_small_opt.xyz, .gradient.npy, .json
Hessian	{gname}_small_fc.hessian.npy, .txt, .json, optional .fchk
RESP	{gname}_large_mk.resp_charges.npy, .txt, .json, optional .fchk
frcmod	{gname}_mcpbpy_pre.frcmod, {gname}_mcpbpy.frcmod
Leap	metal-site .mol2, {gname}_mcpbpy.pdb, {gname}_tleap.in
Profiling	sample/event .csv, summary .json, memory curve .svg

The fchk writer includes coordinates, basis/ECP metadata, orbital energies, MO coefficients, and total/spin density matrices for Gaussian-compatible wavefunction analysis.

MCPB input

Step 1 writes the .in file automatically. Standalone steps auto-detect it in the current directory. A minimal file looks like this:

group_name      1okl
ion_ids         260
ion_mol2files   ZN.mol2
original_pdb    1okl_H.pdb
force_field     ff19SB
water_model     opc
cut_off         2.8

More detail

• Run mpscf --help for command-line options.
• Use the checked-in scf_params.json and gpu.json as complete configuration examples.
• See mpscf/lib/README.md for the GPU4PySCF 1.8 compatibility boundary.

License

Released under the MIT License.