EricBoi/watmeoh-mlmm

Water–methanol ML/MM potential (watmeoh)

A PhysNet student distilled from PET-OMol-L for liquid water, liquid methanol and their mixtures. It is run as an ML/MM hybrid in mmml with jax-md. Two variants are covered:

• Without polarisation: ML monomers and switched ML dimers, plus a CGenFF/TIP3P MM tail.
• With polarisation: the same, plus an induced-dipole many-body term (Thole-damped dipoles on the fixed MM charges).

Status: research checkpoints, public release v1.0 (14 Oct 2026), CC-BY-4.0. Read the caveats before use.

Files

path	what
ml/wm_omol_l_A_cap1_mdaug_ft_ep59.json	recommended student: fine-tune 1 (+112 k PET-labelled structures from real MD: crash windows, hot molecules, O–H stretches), epoch 59, validation force MAE 0.143 kcal mol⁻¹ Å⁻¹. Portable JSON, EMA weights.
ml/wm_omol_l_A_cap1_ep53.json	original student (validation force MAE 0.099). It breaks water O–H bonds in long MD (3 of 4 seeds within 1 ns); kept for reference only.
pol/pol_params_v1.json	production induced-dipole parameters: 6 polarisabilities (water O/H, methanol O, hydroxyl H, methyl C, methyl H) and Thole a, fitted to the PET many-body energies of 960 n-mers (3–16 molecules). Held-out RMSE 0.61 kcal mol⁻¹ per cluster (3.9 without the term).
pol/pol_params_pet_refit.json	experimental refit against PET forces and cohesive energies on 84 periodic liquid boxes. It improves cohesive energies (0.105 → 0.067 kcal mol⁻¹ per molecule) but barely the forces (1.742 → 1.725), and worsens the n-mers (0.62 → 0.71). Not used in any production run.
mm/boxes/{water_900,methanol_399,mix_x050_573}/	CHARMM PSF/CRD + box.json: 30.0 Å boxes at the experimental density, started from equilibrated classical TIP3P/CGenFF frames.
settings.json	code commit, required fixes, hybrid switching, MD defaults and environment variables.
examples/run_mlmm.sh	NVT run of a shipped box with or without the dipole term.
tests/expected.json, tests/reference_geometries.npz	expected student energies on the S66 water/methanol dimers and their monomers for both checkpoints, and the dipole energy of an equilibrated x = 0.5 frame (tests/pol_frame_x050.npz); python tests/check_expected.py checks them (--write regenerates).

How to run

1. Check out mmml at perf/mlmm-jaxmd (commit in settings.json; it must include 77bfd87c0, the TIP3P LJ parser fix).
2. examples/run_mlmm.sh mm/boxes/water_900 10, or with polarisation: examples/run_mlmm.sh mm/boxes/water_900 10 pol. That second form sets MMML_POL_PARAMS=pol/pol_params_v1.json.
3. Recommended environment: MMML_ML_DTYPE=float32 XLA_PYTHON_CLIENT_PREALLOCATE=false JAX_DEFAULT_MATMUL_PRECISION=highest, dt 0.5 fs, --jaxmd-molpair-mm --ml-dimer-cap-auto 1.15.
4. Box size: the 11 Å ML/MM switching needs L ≳ 29.9 Å with methanol (L/2 > switch end + 2 × molecular extent). NpT works but is slower and can compress a 30 Å box below that limit; use ≥ 38 Å for NpT.

What it reproduces (300 K, experimental density unless noted)

quantity	experiment	TIP3P / CGenFF	ML/MM	ML/MM + dipoles
water ΔGsolv (kcal mol⁻¹)	−6.33	−6.30	−8.66	−12.7
water ΔHvap (kcal mol⁻¹)	10.51	10.40	10.59	13.66
methanol ΔGsolv	−4.85	−4.47	−4.77	running
methanol ΔHvap	8.95	8.79	8.19	10.13
water O–O g(r) peak (Å / height)	2.80 / 2.57	2.79 / 2.80	2.99 / 2.39	2.71 / 3.00
water D, one 30 Å box (10⁻⁹ m² s⁻¹)	2.41	4.67	6.53	0.49
x = 0.5 Dwater, extrapolated to infinite box	1.34	–	3.72	–

"ML/MM" here is the recommended student with the water-LJ fix. The full table, with sources and tolerances, is the project score card.

Against the teacher, on 120 PET-labelled periodic liquid boxes:

• With dipoles, the cohesive energy per molecule matches PET to within 0.1 kcal mol⁻¹ at every composition. Without them it is 1–2 kcal mol⁻¹ too weak.
• With dipoles, energy against density follows PET within about 0.5 kcal mol⁻¹ per molecule (water slightly overshoots). Without them the student resists compression 2–4 kcal mol⁻¹ per molecule more than PET.
• Net force per molecule: MAE 1.40 kcal mol⁻¹ Å⁻¹ without dipoles, 1.14 with (PET's mean is 3.31).
• On relaxed liquid-cut clusters (3–16 molecules), the student underbinds by 1.3 kcal mol⁻¹ per molecule; with dipoles the error is −0.4 kcal mol⁻¹ in total over a cluster (0.55 kcal mol⁻¹ per molecule MAE).

Caveats

• With dipoles the model is faithful to PET, not to experiment. Its liquid overbinds (ΔH_vap +3.1 kcal mol⁻¹ for water) because the teacher does. Without dipoles, water ΔH_vap agrees with experiment only by error cancellation.
• Both variants miss solvation entropy. For water, TΔS_solv is about −1.3 kcal mol⁻¹ against −3.6 experimentally. Without dipoles the liquid is under-structured and about 3× too fast; with dipoles it is too structured and about 5× too slow.
• The water-LJ parser bug: runs before mmml 77bfd87c0 had no TIP3P LJ in the MM tail. This changes ΔH_vap by about 0.3 kcal mol⁻¹ and the pressure by about −1,200 atm.
• Holes remain outside the training data, for example strongly stretched or compressed geometries. The original student dissociates water in long MD; the recommended one ran 5.2 ns over 4 seeds without a crash.
• NpT is slow (no molecule-pair MM fast path), and on RTX 30xx/40xx/50xx JAX_DEFAULT_MATMUL_PRECISION=highest is needed for minimisation.
• Licences: this repository is CC-BY-4.0 (LICENSE); the teacher PET-OMol-L and sampler PET-MAD-XS are third-party (lab-cosmo/upet, BSD-3-Clause) and are not redistributed; see NOTICE.md for attribution.