{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "\n# Autodifferentiable Force Prediction with MFML\nIn the previous examples we used a KRR variant that worked for\nproperties which were scalar. However, in many cases, one is interested\nin the use of models that can predict vector valued properties such\nas forces or molecular dipole moments. The next set of examples will demonstrate\na few additions to the MFML-4-QC package that enable us to do this.\n\nThis example demonstrates how to predict molecular forces as the negative\ngradient of MFML-predicted energies, computed via automatic differentiation\n(backpropagation through the Coulomb matrix descriptor and kernel evaluation).\n\nWe will use the QeMFi nitrophenol dataset (5 SCF fidelities) for training. However, since the QeMFi dataset\ndoes not contain any forces for the molecules, we will\ncompare predicted forces against DFT reference forces from the WS22 dataset.\nWhile this is not a compeltely correct comparison, we note that the QeMFi dataset\nis carved out as a subset of the WS22 dataset. Both use DFT for computations.\nFor an example, this is merely to show functionality.\nIn practice, you can also run a single fidelity KRR model with\nautodifferentiation for the forces.\n\nRequirements: PyTorch (``pip install torch``).\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Imports\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "import os\nimport numpy as np\nimport matplotlib.pyplot as plt\n\nfrom mfml_qc.datasets import load_nitrophenol_data\nfrom mfml_qc.mfml import ModelMFML\nfrom mfml_qc.utils import build_hierarchy_arrays, top_down_subsetting\nfrom mfml_qc.autodiff import (\n DifferentiableMFML,\n generate_coulomb_matrix,\n predict_energies_and_forces,\n)\n\nHA_TO_KCAL = 627.509\n\n# Path to WS22 dataset (not part of mfml_qc \u2014 download separately).\n# Here we load from a local instance\nWS22_PATH = path = os.path.expanduser(\"~/Datasets/WS22/ws22_nitrophenol.npz\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Load Data\nQeMFi provides multifidelity SCF energies (among other properties) for 15,000 geometries.\nWS22 provides DFT reference forces for the same geometries since QeMFi is a subset of the WS22 dataset.\nThe ``ID`` array in QeMFi indexes directly into WS22, so forces\ncan be looked up for the same molecular configurations.\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "dataset = load_nitrophenol_data() # QeMFi dataset is included\nR = dataset[\"R\"] # (15000, 15, 3)\nZ = dataset[\"Z\"] # (15,)\nX_CM = dataset[\"X_CM\"] # (15000, 120)\nSCF = dataset[\"SCF\"] # (15000, 5) \u2014 energies in Hartrees\n\nif not os.path.exists(WS22_PATH):\n raise FileNotFoundError(\n f\"WS22 dataset not found at '{WS22_PATH}'. \"\n \"Set WS22_PATH to the location of ws22_nitrophenol.npz.\"\n )\nws22 = np.load(WS22_PATH)\nws22_ids = dataset[\"ID\"]\nF_ref_all = ws22[\"F\"][ws22_ids] # (15000, 15, 3)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Train/Test Split and Hierarchy\nWe use 12,000 geometries for training and 3,000 for testing. The\nmultifidelity hierarchy is built from the 5 SCF energy columns with\na scaling factor of 2.\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "N_TRAIN = 12000\nN_TEST = 3000\n\nX_train = X_CM[:N_TRAIN]\nX_test = X_CM[N_TRAIN : N_TRAIN + N_TEST]\nR_test = R[N_TRAIN : N_TRAIN + N_TEST]\nF_ref = F_ref_all[N_TRAIN : N_TRAIN + N_TEST]\n\ndata_train = np.column_stack([np.arange(N_TRAIN), SCF[:N_TRAIN]])\nhierarchy_cols = [1, 2, 3, 4, 5] # lowest fidelity is stored first in QeMFi\ny_trains, indexes, means = build_hierarchy_arrays(data_train, hierarchy_cols)\n\nn_trains_target = [\n 1024,\n 512,\n 256,\n 128,\n 64,\n] # 64 at the highest fidelity, 1024 at the lowest.\nsubset_y_trains, subset_indexes = top_down_subsetting(\n y_trains, indexes, n_trains_target, seed=42\n)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Train a standard MFML Model\nA standard MFML model is trained using the built-in KRR with a Gaussian\nkernel. This produces 2N-1 = 9 sub-models across 5 fidelity levels.\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "mfml_model = ModelMFML(kernel=\"gaussian\", sigma=250.0, reg=1e-10, p_bar=True)\nmfml_model.train(\n X_train_parent=X_train,\n y_trains=subset_y_trains,\n indexes=subset_indexes,\n)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Wrap in Autodiff Evaluator and Predict Forces\nThe trained MFML model is wrapped in a ``DifferentiableMFML`` evaluator,\nwhich stores the sub-model weights as PyTorch buffers. For each test\ngeometry, the Coulomb matrix is computed differentiably, the energy is\npredicted, and forces are obtained as ``F = -\u2207E`` via backpropagation.\n\nPredicted energies are un-centered using the highest-fidelity mean, and\nforces are converted from Ha/\u00c5 to kcal/mol/\u00c5.\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "evaluator = DifferentiableMFML.from_mfml_model(mfml_model)\n\npred_energies, pred_forces = predict_energies_and_forces(\n evaluator, R_test, Z, descriptor_fn=generate_coulomb_matrix\n)\n\npred_energies += means[-1]\npred_forces *= HA_TO_KCAL" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Evaluate\nWe compute the energy MAE against the highest-fidelity SCF values,\nthe force magnitude MAE, and the mean cosine similarity of force\nvectors against WS22 DFT reference forces.\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "energy_mae = np.mean(np.abs(pred_energies - SCF[N_TRAIN : N_TRAIN + N_TEST, -1]))\n\nforce_mag_pred = np.linalg.norm(pred_forces.reshape(-1, 3), axis=-1)\nforce_mag_ref = np.linalg.norm(F_ref.reshape(-1, 3), axis=-1)\nforce_mag_mae = np.mean(np.abs(force_mag_pred - force_mag_ref))\n\ndot = np.sum(pred_forces.reshape(-1, 3) * F_ref.reshape(-1, 3), axis=-1)\ndenom = np.maximum(force_mag_pred * force_mag_ref, 1e-12)\ncos_sim = np.clip(dot / denom, -1.0, 1.0)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Plot\nWe will look at the energy parity, force magnitude parity, and a\nhistogram of per-atom force cosine similarities.\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "fig, (ax1, ax2, ax3) = plt.subplots(1, 3, figsize=(15, 4))\n\nax1.scatter(SCF[N_TRAIN : N_TRAIN + N_TEST, -1], pred_energies, s=2, alpha=0.3)\nlims = [\n SCF[N_TRAIN : N_TRAIN + N_TEST, -1].min(),\n SCF[N_TRAIN : N_TRAIN + N_TEST, -1].max(),\n]\nax1.plot(lims, lims, \"r--\")\nax1.set_xlabel(\"True Energy (Ha)\")\nax1.set_ylabel(\"Predicted Energy (Ha)\")\nax1.set_title(f\"Energy Parity (MAE: {energy_mae:.6f} Ha)\")\n\nax2.scatter(force_mag_ref, force_mag_pred, s=1, alpha=0.1)\nlims = [0, max(force_mag_ref.max(), force_mag_pred.max())]\nax2.plot(lims, lims, \"r--\")\nax2.set_xlabel(\"|F| Reference (kcal/mol/\u00c5)\")\nax2.set_ylabel(\"|F| Predicted (kcal/mol/\u00c5)\")\nax2.set_title(f\"Force Magnitude (MAE: {force_mag_mae:.2f})\")\n\nax3.hist(cos_sim, bins=80, edgecolor=\"none\", alpha=0.7)\nax3.set_xlabel(\"Cosine Similarity\")\nax3.set_ylabel(\"Count\")\nax3.set_title(f\"Force Direction (mean cos: {np.mean(cos_sim):.4f})\")\n\nplt.tight_layout()\nplt.show()" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.10.22" } }, "nbformat": 4, "nbformat_minor": 0 }