Tutorial: From ESP to DCMNet

This step-by-step tutorial walks you through computing an ESP for a molecule, exporting a cube, preparing a dataset, and training DCMNet.

Step 1: Compute ESP with GPU4PySCF

python -m mmml.pyscf4gpuInterface.calcs \
  --mol "O 0.000 0.000 0.000; H 0.000 0.757 0.586; H 0.000 -0.757 0.586" \
  --basis def2-tzvp --xc wB97m-v --spin 0 --charge 0 \
  --dens_esp --energy --output water_esp.pkl

Step 2: Export a Gaussian cube

Map the sampled ESP to a rectilinear grid and write water.cube.

# See esp_cube_generation.rst for a complete script
# Adapt paths and grid resolution if needed

Step 3: Prepare a training NPZ

Create the keys expected by DCMNet. For illustration, we fake mono and minimal metadata; for real data, use your reference charges and surface definition.

import numpy as np, pickle
with open("water_esp.pkl", "rb") as f:
    d = pickle.load(f)
# One-sample dataset (natoms = len(d["Z"]))
R = d["R"][None, ...]
Z = d["Z"][None, ...]
N = np.array([[len(d["Z"])]])
esp = d["esp"][None, ...]
vdw_surface = d["esp_grid"][None, ...]  # using ESP grid as surface points
n_grid = np.array([len(d["esp"])])
mono = np.zeros((1, len(d["Z"])))  # placeholder monopoles
np.savez("water_esp_train.npz", R=R, Z=Z, N=N, mono=mono,
         esp=esp, vdw_surface=vdw_surface, n_grid=n_grid)

Step 4: Train DCMNet

python -m mmml.dcmnet.dcmnet.main \
  --data_files ./water_esp_train.npz \
  --n_train 1 --n_valid 0 \
  --num_epochs 200 --batch_size 1 --learning_rate 1e-3 \
  --esp_w 1000 --n_dcm 1 --type default \
  --log_dir ./runs/water_demo --checkpoint_dir ./checkpoints/water_demo

Notes

• For meaningful results, train on many molecules and surfaces; the single-sample demo is for mechanics only.

• Replace the placeholder monopoles with a reference scheme (e.g., RESP, MBIS) if you use the monopole loss.