Source code for mfml_qc.vector_mfml

"""
MFML for vector-valued properties.

Provides ``VectorMFML``, a multi-fidelity wrapper that trains and predicts
vector targets (e.g., dipole moments) using the Single-Grid Combination
Technique (SGCT). Uses any duck-typed vector estimator (VectorKRR,
CoupledVectorKRR, RPRVectorKRR) as the sub-model.

Also provides ``DifferentiableVectorMFML`` (requires PyTorch) for
differentiable inference pipelines.

Note: ``ModelMFML.predict`` assumes scalar outputs, so ``VectorMFML``
implements its own SGCT prediction over d-dimensional vectors.
"""

import copy
import numpy as np
from .utils import top_down_subsetting


[docs] class VectorMFML: """ Multi-Fidelity Machine Learning for vector-valued properties. Trains 2N-1 sub-models (N upper + N-1 lower) following the SGCT scheme and predicts d-dimensional vectors. Parameters ---------- base_estimator : object A model instance with ``.train(X, Y)`` and ``.predict(X)`` methods. Will be deep-copied for each sub-model. E.g., ``VectorKRR``, ``CoupledVectorKRR``, or ``RPRVectorKRR``. """ def __init__(self, base_estimator): self.base_estimator = base_estimator self.models = None self.nfids = None self.sub_Y_mean = None
[docs] def train(self, X_train_parent, y_trains, indexes, n_trains_target=None, seed=42): """ Train the MFML vector model. Parameters ---------- X_train_parent : np.ndarray, shape (N_parent, D) Feature matrix for the full parent (lowest fidelity) training set. For RPR models, these are flattened coordinates (N, N_atoms*3). For non-RPR models, these are pre-computed descriptors. y_trains : np.ndarray of object, length num_fids Each element is (N_i, d) array of mean-centered vector targets at fidelity i. indexes : np.ndarray of object, length num_fids Each element is (N_i, 2) array of [baseline_idx, level_idx] mappings. n_trains_target : list of int, optional Target number of training samples per fidelity (lowest to highest). If None, uses all available samples. seed : int Random seed for subsetting. """ self.nfids = len(y_trains) n_sub = 2 * self.nfids - 1 if n_trains_target is not None: subset_y, subset_idx = top_down_subsetting( y_trains, indexes, n_trains_target, seed=seed ) else: subset_y, subset_idx = y_trains, indexes # Build sub-model training data sub_X = [] sub_Y = [] self.sub_Y_mean = [] # Upper sub-models: fidelity i targets on fidelity i subset for i in range(self.nfids): idx_i = subset_idx[i][:, 0] Y_i = ( subset_y[i][subset_idx[i][:, 1]] if subset_y[i].ndim > 1 else subset_y[i] ) # Re-index: subset_idx maps into the original arrays # For direct indexing into X_train_parent we use baseline indices sub_X.append(X_train_parent[idx_i]) m_i = np.mean(Y_i, axis=0) if Y_i.ndim > 1 else np.mean(Y_i) sub_Y.append(Y_i - m_i) self.sub_Y_mean.append(m_i) # Lower sub-models: fidelity i targets on fidelity i+1 subset for i in range(self.nfids - 1): idx_ip1 = subset_idx[i + 1][:, 0] # Need fidelity i targets for the samples that are in fidelity i+1's subset # These samples exist in fidelity i's data; find them via baseline index fid_i_map = {row[0]: row[1] for row in subset_idx[i]} level_indices = [fid_i_map[b] for b in idx_ip1 if b in fid_i_map] Y_lower = subset_y[i][level_indices] m_i = np.mean(Y_lower, axis=0) if Y_lower.ndim > 1 else np.mean(Y_lower) sub_X.append(X_train_parent[idx_ip1]) sub_Y.append(Y_lower - m_i) self.sub_Y_mean.append(m_i) # Train all sub-models self.models = [] for s in range(n_sub): model_s = copy.deepcopy(self.base_estimator) model_s.train(sub_X[s], sub_Y[s]) self.models.append(model_s)
[docs] def predict(self, X_test): """ Predict vector targets using SGCT combination. Parameters ---------- X_test : np.ndarray, shape (M, D) Test feature matrix (descriptors or flattened coordinates for RPR). Returns ------- np.ndarray, shape (M, d) Predicted vectors (un-centered). """ if self.models is None: raise ValueError("Model not trained. Call .train() first.") # Get output dimension from first sub-model prediction pred_0 = self.models[0].predict(X_test) M = pred_0.shape[0] d = pred_0.shape[1] if pred_0.ndim > 1 else 1 result = np.zeros((M, d)) # Upper: sum predictions + means for i in range(self.nfids): pred = self.models[i].predict(X_test) result += pred + self.sub_Y_mean[i] # Lower: subtract predictions + means for i in range(self.nfids - 1): pred = self.models[self.nfids + i].predict(X_test) result -= pred + self.sub_Y_mean[self.nfids + i] return result
# ============================================================ # Differentiable evaluator (requires PyTorch) # ============================================================ try: import torch from .vector_krr import DifferentiableVectorKRR
[docs] class DifferentiableVectorMFML(torch.nn.Module): """ Differentiable MFML evaluator for vector properties. Wraps 2N-1 ``DifferentiableVectorKRR`` sub-models and applies SGCT arithmetic on d-dimensional prediction vectors. Parameters ---------- sub_models : list of DifferentiableVectorKRR nfids : int """ def __init__(self, sub_models, nfids): super().__init__() self.sub_models = torch.nn.ModuleList(sub_models) self.nfids = nfids
[docs] @classmethod def from_vector_mfml(cls, vector_mfml_model): """Construct from a trained ``VectorMFML`` instance.""" nfids = vector_mfml_model.nfids sub_models = [ DifferentiableVectorKRR.from_vector_krr(m) for m in vector_mfml_model.models ] return cls(sub_models=sub_models, nfids=nfids)
[docs] def forward(self, X_test): """ Parameters ---------- X_test : torch.Tensor, shape (1, D) Returns ------- torch.Tensor, shape (d,) """ sub_preds = torch.stack([m(X_test) for m in self.sub_models]) upper = torch.sum(sub_preds[: self.nfids], dim=0) lower = torch.sum(sub_preds[self.nfids :], dim=0) return upper - lower
except ImportError: pass