{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "\n# RPR Frame Canonicalization for Vector KRR\n\nIn\nJ. Martinka, M. Pederzoli, M. Barbatti, P. O. Dral, J. Pittner,\nA simple approach to rotationally invariant machine learning of a vector quantity,\nJ. Chem. Phys. 161, 174104 (2024). DOI: 10.1063/5.0230176\nthe authors present a simple pre and post processing heuristic to train a KRR model\nfor prediction of challenging vector quantities. This method is called the RPR.\nRPR (Rotate-Predict-Rotate) transforms each geometry into a canonical\ninertia-tensor frame before computing descriptors and rotates the\npredictions back to the lab frame, ensuring equivariant predictions.\n\n\nThis example compares 4 variants for predicting electronic dipole\nmoments, showing how RPR and the learnable coupling matrix from the\nprevious example matrix each contribute. These variants are\n 1. Isotropic VectorKRR (baseline)\n 2. Coupled VectorKRR (learnable output covariance)\n 3. RPR + Isotropic VectorKRR\n 4. RPR + Coupled VectorKRR (spoiler, turns out to be the best).\nIn this example we show these methods for a single fidelity case.\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Imports\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "import numpy as np\nimport matplotlib.pyplot as plt\n\nfrom mfml_qc.datasets import load_nitrophenol_data\nfrom mfml_qc.representations import compute_flat_coulomb\nfrom mfml_qc.vector_krr import VectorKRR, CoupledVectorKRR\nfrom mfml_qc.rpr import RPRVectorKRR" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Load and Split Data\nWe use the highest-fidelity electronic dipole moments from QeMFi\nnitrophenol. Non-RPR models use pre-computed Coulomb matrices; RPR\nmodels take flattened Cartesian coordinates and compute descriptors\ninternally after 'canonical'-ization (it is a funny word).\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "dataset = load_nitrophenol_data()\nR = dataset[\"R\"]\nZ = dataset[\"Z\"]\nX_CM = dataset[\"X_CM\"]\nDPe_hf = dataset[\"DPe\"][:, -1, :]\n\nN_TRAIN = 512\nN_TEST = 3000\nKERNEL = \"gaussian\"\nSIGMA = 250.0\nREG = 1e-10\n\nrng = np.random.RandomState(42)\nperm = rng.permutation(len(DPe_hf))\ntrain_idx, test_idx = perm[:N_TRAIN], perm[N_TRAIN : N_TRAIN + N_TEST]\n\nX_train_cm = X_CM[train_idx]\nX_test_cm = X_CM[test_idx]\nX_train_flat = R[train_idx].reshape(N_TRAIN, -1)\nX_test_flat = R[test_idx].reshape(N_TEST, -1)\nY_train = DPe_hf[train_idx]\nY_test = DPe_hf[test_idx]\nY_mean = np.mean(Y_train, axis=0)\nY_train_c = Y_train - Y_mean" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Train All 4 Models\nWe train four variants to isolate the effect of RPR and the learnable\noutput covariance matrix. Non-RPR models operate on Coulomb matrices directly,\nwhile RPR models carry out canonicalization each geometry first.\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "models = {}\n\nm = VectorKRR(kernel_type=KERNEL, sigma=SIGMA, reg=REG)\nm.train(X_train_cm, Y_train_c)\nmodels[\"Isotropic\"] = m.predict(X_test_cm) + Y_mean\n\nm = CoupledVectorKRR(\n kernel_type=KERNEL, sigma=SIGMA, reg=REG, val_fraction=0.15, max_opt_iter=500\n)\nm.train(X_train_cm, Y_train_c)\nmodels[\"Coupled T\"] = m.predict(X_test_cm) + Y_mean\n\ninner = VectorKRR(kernel_type=KERNEL, sigma=SIGMA, reg=REG)\nm = RPRVectorKRR(inner, Z, compute_flat_coulomb)\nm.train(X_train_flat, Y_train_c)\nmodels[\"RPR+Iso\"] = m.predict(X_test_flat) + Y_mean\n\ninner = CoupledVectorKRR(\n kernel_type=KERNEL, sigma=SIGMA, reg=REG, val_fraction=0.15, max_opt_iter=500\n)\nm_rpr_t = RPRVectorKRR(inner, Z, compute_flat_coulomb)\nm_rpr_t.train(X_train_flat, Y_train_c)\nmodels[\"RPR+Coupled T\"] = m_rpr_t.predict(X_test_flat) + Y_mean" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Evaluate\nFor each model we compute component-wise MAE, overall MAE, cosine\nsimilarity, and mean angular error between predicted and reference\ndipole vectors.\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "def eval_model(name, pred, true):\n comp_mae = np.mean(np.abs(pred - true), axis=0)\n overall = np.mean(np.abs(pred - true))\n mag_p, mag_t = np.linalg.norm(pred, axis=-1), np.linalg.norm(true, axis=-1)\n dot = np.sum(pred * true, axis=-1)\n cos_sim = np.clip(dot / np.maximum(mag_p * mag_t, 1e-12), -1.0, 1.0)\n angle = np.mean(np.degrees(np.arccos(cos_sim)))\n return comp_mae, overall, cos_sim\n\n\nresults = {}\nfor name, pred in models.items():\n results[name] = eval_model(name, pred, Y_test)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Summary Plot\nThe left panel shows component-wise and overall MAE for all four models.\nThe right panel shows the cumulative distribution of cosine similarity,\nindicating how well each model captures dipole direction.\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "names = list(models.keys())\ncolors = plt.cm.viridis(np.linspace(0.15, 0.85, 4))\ncomp_labels = [\"\u03bc_x\", \"\u03bc_y\", \"\u03bc_z\", \"Overall\"]\n\nfig, (ax1, ax2) = plt.subplots(1, 2, figsize=(14, 5))\n\nx = np.arange(len(comp_labels))\nw = 0.18\nfor j, name in enumerate(names):\n vals = list(results[name][0]) + [results[name][1]]\n ax1.bar(x + (j - 1.5) * w, vals, w, label=name, color=colors[j])\nax1.set_xticks(x)\nax1.set_xticklabels(comp_labels)\nax1.set_ylabel(\"MAE (Debye)\")\nax1.set_title(f\"Component-wise MAE (N_train={N_TRAIN})\")\nax1.legend(fontsize=8)\n\nfor j, name in enumerate(names):\n sorted_cos = np.sort(results[name][2])\n cdf = np.arange(1, len(sorted_cos) + 1) / len(sorted_cos)\n ax2.plot(\n sorted_cos,\n cdf,\n label=f\"{name} (mean: {np.mean(results[name][2]):.4f})\",\n color=colors[j],\n lw=1.5,\n )\nax2.set_xlabel(\"Cosine Similarity\")\nax2.set_ylabel(\"CDF\")\nax2.set_title(\"Cumulative Distribution of Cosine Similarity\")\nax2.legend(fontsize=8, loc=\"upper left\")\nax2.set_xlim([0.95, 1.001])\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 }