Vector MFML for Dipole Moments#

Now we move on to an example of creating an MFML model for vector properties. This example trains a 5-fidelity MFML model using VectorKRR to directly predict electronic dipole moment vectors (3 Cartesian components) for nitrophenol from the QeMFi dataset.

We will compares the vector MFML against 3 independent scalar MFML models (one per dipole component) to check if the vector MFML does add any improvement at all.

Imports#

[1]:
import numpy as np
import matplotlib.pyplot as plt

from mfml_qc.datasets import load_nitrophenol_data
from mfml_qc.representations import compute_flat_coulomb
from mfml_qc.mfml import ModelMFML
from mfml_qc.utils import top_down_subsetting
from mfml_qc.vector_krr import CoupledVectorKRR
from mfml_qc.vector_mfml import VectorMFML
from mfml_qc.rpr import RPRVectorKRR

Load and Split Data#

We use the QeMFi nitrophenol dataset with 5 SCF fidelity levels. The first 12,000 geometries form the training pool; the remaining 3,000 are held out for testing against the highest-fidelity dipole vectors.

[2]:
dataset = load_nitrophenol_data()
R = dataset["R"]
Z = dataset["Z"]
X_CM = dataset["X_CM"]
DPe = dataset["DPe"]  # (15000, 5, 3)

N_TRAIN = 12000
N_TEST = 3000
NUM_FIDS = 5

X_train_parent_cm = X_CM[:N_TRAIN]
X_test_cm = X_CM[N_TRAIN : N_TRAIN + N_TEST]
X_train_parent_flat = R[:N_TRAIN].reshape(N_TRAIN, -1)
X_test_flat = R[N_TRAIN : N_TRAIN + N_TEST].reshape(N_TEST, -1)
DPe_train = DPe[:N_TRAIN]
DPe_test_ref = DPe[N_TRAIN : N_TRAIN + N_TEST, -1, :]

Build Hierarchy for Vector Targets#

We construct the multi-fidelity hierarchy manually since build_hierarchy_arrays expects scalar targets. Each fidelity level’s dipole vectors are mean-centred independently.

[3]:
y_trains = np.zeros(NUM_FIDS, dtype=object)
indexes = np.zeros(NUM_FIDS, dtype=object)
means = np.zeros((NUM_FIDS, 3))

for i in range(NUM_FIDS):
    vals = DPe_train[:, i, :]
    means[i] = np.mean(vals, axis=0)
    y_trains[i] = vals - means[i]
    indexes[i] = np.column_stack([np.arange(N_TRAIN), np.arange(N_TRAIN)])

n_trains_target = [
    4096,
    2048,
    1024,
    512,
    256,
]  # 256 at target fidelity 4096 at the lowest
subset_y_trains, subset_indexes = top_down_subsetting(
    y_trains, indexes, n_trains_target, seed=42
)

Train Vector MFML#

A single VectorKRR instance is passed as the base_estimator. ModelMFML deep-copies it for each of the 2N−1 = 9 sub-models. Prediction uses the default MFML sub-model summation because ModelMFML.predict works on scalar outputs.

[4]:
base_model = CoupledVectorKRR(
    kernel_type="gaussian",
    sigma=250.0,
    reg=1e-10,
    val_fraction=0.15,
    max_opt_iter=500,
)
base_model = RPRVectorKRR(base_model, Z, compute_flat_coulomb)

mfml_model = VectorMFML(base_estimator=base_model)
mfml_model.train(
    X_train_parent=X_train_parent_flat,
    y_trains=subset_y_trains,
    indexes=subset_indexes,
)

DPe_pred = mfml_model.predict(X_test_flat) + means[-1]

Scalar MFML Baseline#

For comparison, we train 3 independent scalar MFML models — one per Cartesian component of the dipole moment. With the isotropic kernel this is mathematically equivalent to the vector formulation, but requires managing 3 separate model objects.

[5]:
DPe_pred_scalar = np.zeros((N_TEST, 3))

for c in range(3):
    y_trains_c = np.zeros(NUM_FIDS, dtype=object)
    means_c = np.zeros(NUM_FIDS)
    for i in range(NUM_FIDS):
        vals = DPe_train[:, i, c]
        means_c[i] = np.mean(vals)
        y_trains_c[i] = vals - means_c[i]

    subset_y_c, subset_idx_c = top_down_subsetting(
        y_trains_c, indexes, n_trains_target, seed=42
    )

    mfml_c = ModelMFML(kernel="gaussian", sigma=250.0, reg=1e-10, p_bar=False)
    mfml_c.train(
        X_train_parent=X_train_parent_cm,
        y_trains=subset_y_c,
        indexes=subset_idx_c,
    )
    preds_c = mfml_c.predict(X_test=X_test_cm, optimiser="default") + means_c[-1]
    DPe_pred_scalar[:, c] = preds_c

Evaluate#

We compute component-wise MAE, overall MAE, and cosine similarity between predicted and reference dipole vectors.

[6]:
def evaluate(pred, true):
    comp_mae = np.mean(np.abs(pred - true), axis=0)
    overall = np.mean(np.abs(pred - true))
    mag_p, mag_t = np.linalg.norm(pred, axis=-1), np.linalg.norm(true, axis=-1)
    dot = np.sum(pred * true, axis=-1)
    cos_sim = np.clip(dot / np.maximum(mag_p * mag_t, 1e-12), -1.0, 1.0)
    return comp_mae, overall, cos_sim


comp_vec, mae_vec, cos_vec = evaluate(DPe_pred, DPe_test_ref)
comp_sca, mae_sca, cos_sca = evaluate(DPe_pred_scalar, DPe_test_ref)

Comparison Plot#

Three-panel figure: dipole magnitude parity (left), component-wise MAE bar chart (centre), and cosine similarity histograms (right).

[7]:
fig, (ax1, ax2, ax3) = plt.subplots(1, 3, figsize=(16, 5))

mag_true = np.linalg.norm(DPe_test_ref, axis=-1)
mag_vec = np.linalg.norm(DPe_pred, axis=-1)
mag_sca = np.linalg.norm(DPe_pred_scalar, axis=-1)

ax1.scatter(
    mag_true,
    mag_sca,
    s=2,
    alpha=0.35,
    color="#ff7f0e",
    label=f"Scalar MFML (MAE: {np.mean(np.abs(mag_sca - mag_true)):.4f})",
)
ax1.scatter(
    mag_true,
    mag_vec,
    s=2,
    alpha=0.35,
    color="#1f77b4",
    label=f"Vector MFML (MAE: {np.mean(np.abs(mag_vec - mag_true)):.4f})",
)
lims = [
    min(mag_true.min(), mag_sca.min(), mag_vec.min()),
    max(mag_true.max(), mag_sca.max(), mag_vec.max()),
]
ax1.plot(lims, lims, "r--", lw=1.5)
ax1.set_xlabel("True |μ| (Debye)")
ax1.set_ylabel("Predicted |μ| (Debye)")
ax1.set_title("Dipole Magnitude Parity")
ax1.legend(markerscale=5, fontsize=8)

comp_labels = ["μ_x", "μ_y", "μ_z", "Overall"]
vec_maes = list(comp_vec) + [mae_vec]
sca_maes = list(comp_sca) + [mae_sca]
x_pos = np.arange(len(comp_labels))
w = 0.35
ax2.bar(x_pos - w / 2, vec_maes, w, label="Vector MFML", color="#1f77b4")
ax2.bar(x_pos + w / 2, sca_maes, w, label="Scalar MFML", color="#ff7f0e")
ax2.set_xticks(x_pos)
ax2.set_xticklabels(comp_labels)
ax2.set_ylabel("MAE (Debye)")
ax2.set_title("Component-wise MAE")
ax2.legend(fontsize=8)

ax3.hist(
    cos_sca,
    bins=60,
    color="#ff7f0e",
    edgecolor="none",
    alpha=0.5,
    label=f"Scalar (mean: {np.mean(cos_sca):.4f})",
)
ax3.hist(
    cos_vec,
    bins=60,
    color="#1f77b4",
    edgecolor="none",
    alpha=0.5,
    label=f"Vector (mean: {np.mean(cos_vec):.4f})",
)
ax3.set_xlabel("Cosine Similarity")
ax3.set_ylabel("Count")
ax3.set_title("Directional Alignment")
ax3.legend(fontsize=8)

plt.tight_layout()
plt.show()
../_images/auto_examples_12_vector_mfml_dipole_14_0.png