MCPB4PYSCF

# MPSCF <p align="center"> <img src="pic/main.png" alt="MPSCF workflow" width="760" /> </p> <p align="center"> <a href="https://github.com/KeithTab/MPSCF/releases"><img alt="Release" src="https://img.shields.io/github/v/release/KeithTab/MPSCF?display_name=tag&amp;sort=semver" /></a> <a href="https://github.com/KeithTab/MPSCF/commits/dev"><img alt="Last commit" src="https://img.shields.io/github/last-commit/KeithTab/MPSCF/dev" /></a> <img alt="Python" src="https://img.shields.io/badge/Python-3.11-3776AB?logo=python&logoColor=white" /> <img alt="GPU4PySCF" src="https://img.shields.io/badge/GPU4PySCF-1.8.0-76B900?logo=nvidia&logoColor=white" /> <a href="LICENSE"><img alt="License" src="https://img.shields.io/github/license/KeithTab/MPSCF" /></a> </p> 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 ```mermaid 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 ``` | 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`](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 <details open> <summary><strong>Run the complete bonded workflow</strong></summary> ```bash 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: ```bash tleap -s -f <group_name>_tleap.in ``` </details> <details> <summary><strong>Run one stage from an existing MCPB <code>.in</code> file</strong></summary> Run these commands in a directory containing exactly one `.in` file: ```bash 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 ``` </details> <details> <summary><strong>Prepare a nonbonded metal model</strong></summary> ```bash 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. </details> ## 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. <details open> <summary><strong>Create the validated environment</strong></summary> ```bash 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 . ``` </details> <details> <summary><strong>Install optional MetalloDock dependencies</strong></summary> ```bash pip install -r mpscf/eval/requirements-cu121.txt ``` This optional runtime is needed only when `metal_complex_eval.is_metal_ligand_complex` is enabled. </details> > 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`](scf_params.json) controls chemistry, convergence, workflow stages, outputs, and profiling. - [`gpu.json`](gpu.json) opts into MPSCF's GPU4PySCF 1.8 memory/scaling layer. Omit `--gpu-json` to use the native GPU4PySCF schedule. <details open> <summary><strong>Minimal SCF configuration</strong></summary> ```json { "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" } ``` </details> <details> <summary><strong>Multi-GPU performance configuration</strong></summary> ```json { "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. </details> <details> <summary><strong>GPU memory/utilization profiling</strong></summary> Add these fields to `scf_params.json`: ```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. </details> ## Multi-GPU execution ```mermaid 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] ``` 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 <details> <summary><strong>Enable scoring and ligand-pose correction</strong></summary> ```json { "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`. </details> ## Outputs <details open> <summary><strong>Core files</strong></summary> | 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. </details> ## MCPB input Step 1 writes the `.in` file automatically. Standalone steps auto-detect it in the current directory. A minimal file looks like this: ```text 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`](scf_params.json) and [`gpu.json`](gpu.json) as complete configuration examples. - See [`mpscf/lib/README.md`](mpscf/lib/README.md) for the GPU4PySCF 1.8 compatibility boundary. ## License Released under the [MIT License](LICENSE).