Documentation for MFML-4-QC#

MFML-4-QC is a Python package for Multifidelity Machine Learning in Quantum Chemistry. It provides an in built, Numba-accelerated Kernel Ridge Regression backend, dynamic active learning, and automated interfaces to quantum chemistry engines like ORCA.

API Reference#

mfml_qc

MFML-4-QC: A Python package for Multifidelity Machine Learning in Quantum Chemistry.

Representations#

mfml_qc.representations.compute_flat_coulomb(Z: ndarray, R: ndarray) → ndarray[source]#

Computes the 1D flattened unsorted Coulomb matrix (diagonal + upper triangle) using ultra-fast compiled C loops.

Parameters:
  • Z (np.ndarray) – 1D array of nuclear charges (shape: N,)

  • R (np.ndarray) – 2D array of Cartesian coordinates (shape: N, 3)

Returns:

1D array of flattened Coulomb matrix features.

Return type:

np.ndarray

mfml_qc.representations.generate_coulomb_matrices(xyz_filepath: str, save_path: str | None = None) → ndarray[source]#

Extracts geometries from a concatenated XYZ file and generates flattened, unsorted Coulomb matrices for the entire dataset.

The Coulomb matrix \(C\) is a global structural representation defined as:

\[\begin{split}C_{ij} = \begin{cases} 0.5 Z_i^{2.4} & \text{for } i = j \\ \frac{Z_i Z_j}{||\mathbf{R}_i - \mathbf{R}_j||_2} & \text{for } i \neq j \end{cases}\end{split}\]

where \(Z_i\) is the atomic number and \(\mathbf{R}_i\) is the Cartesian coordinate of atom \(i\). This function flattens the upper triangle (including the diagonal) into a 1D vector.

Parameters:
  • xyz_filepath (str) – Path to the source .xyz file.

  • save_path (str, optional) – If provided, saves the output array to this filepath as a .npy file (e.g., ‘data/CH3Cl_CM.npy’).

Returns:

A 2D array of shape (n_geometries, n_features) containing the flattened Coulomb matrices.

Return type:

np.ndarray

Raises:
  • FileNotFoundError – If the specified XYZ file does not exist.

  • ValueError – If the XYZ file is empty, or if geometries within the trajectory have inconsistent numbers of atoms.

mfml_qc.representations.parse_trajectory(filepath: str) → list[source]#

Reads a concatenated XYZ file entirely in memory, avoiding slow disk I/O.

Parameters:

filepath (str) – Path to the concatenated .xyz file.

Returns:

A list where each element is a tuple of (nuclear_charges, coordinates).

Return type:

list of tuples

Data Loaders & Utilities#

mfml_qc.datasets.load_benzene_data(data_dir: str | None = None) → Dict[str, Any][source]#

Helper utility to load and parse the built-in Benzene trajectory dataset.

This function reads the pre-computed energy and time cost CSV files, and either loads the cached Coulomb matrices or generates them dynamically from the provided XYZ trajectory file.

Parameters:

data_dir (str, optional) – Path to the benzene data directory. If None, it dynamically resolves the path relative to the installed package’s directory (assuming the standard ‘data/benzene’ repository layout). Default is None.

Returns:

A dictionary containing the parsed dataset components:

  • 'X_CM' (np.ndarray): Flattened Coulomb matrices (shape: 15000, 36).

  • 'energies' (np.ndarray): Raw energies extracted from the CSV data.

  • 'timecosts' (np.ndarray): Time costs extracted from the CSV data.

  • 'columns' (list of str): List of string names corresponding to each column.

Return type:

dict

Raises:

FileNotFoundError – If the required ‘energies.csv’ file is not found at the resolved path, indicating the data has not been downloaded or placed correctly.

mfml_qc.datasets.load_nitrophenol_data(data_dir: str | None = None) → Dict[str, Any][source]#

Load and parse the built-in QeMFi nitrophenol dataset.

The QeMFi dataset contains multifidelity electronic structure properties for 15,000 MD geometries of nitrophenol at 5 SCF fidelity levels (STO-3G, 3-21G, 6-31G, def2-SVP, def2-TZVP).

Reference: Vinod et al., J. Chem. Phys. (2024).

Parameters:

data_dir (str, optional) – Path to the nitrophenol data directory. If None, resolves the path relative to the installed package’s directory (assuming the standard ‘data/nitrophenol’ repository layout). Default is None.

Returns:

A dictionary containing the parsed dataset components:

  • 'R' (np.ndarray): Cartesian coordinates, shape (15000, 15, 3).

  • 'Z' (np.ndarray): Atomic numbers, shape (15,).

  • 'SCF' (np.ndarray): SCF energies at 5 fidelities, shape (15000, 5).

  • 'DPe' (np.ndarray): Electronic dipole moments, shape (15000, 5, 3).

  • 'X_CM' (np.ndarray): Flattened Coulomb matrices, shape (15000, 120).

  • 'fidelities' (list of str): Fidelity level names.

  • 'ID' (np.ndarray, optional): WS22 geometry indices, shape (15000,).

Return type:

dict

Raises:

FileNotFoundError – If the required data file is not found at the resolved path.

mfml_qc.utils.build_hierarchy_arrays(data_train: ndarray, hierarchy_cols: list) → tuple[source]#

Extracts valid subsets and mean-centers energies across a fidelity hierarchy.

Parameters:
  • data_train (np.ndarray) – The training data array containing all fidelities.

  • hierarchy_cols (list of int) – Column indices for the fidelities, ordered from lowest to highest.

Returns:

(y_trains, indexes, means) where y_trains and indexes are object arrays formatted for the ModelMFML, and means are the centering offsets.

Return type:

tuple

mfml_qc.utils.property_differences(file_paths: list)[source]#

Helper utility to parse and align nested multi-fidelity datasets from raw text files.

This function loads data from multiple fidelities and builds a strict nested index mapping. Crucially, it returns the full property values for each level (not the physical deltas), along with index arrays mapping each higher-fidelity sample back to its corresponding baseline geometry ID.

Parameters:

file_paths (list of str) – List of exact file paths to the energy/property files. Each file should be formatted with 2 columns: [timestamp/ID, property_value]. The list MUST be ordered from the lowest fidelity (baseline) to the highest.

Returns:

A tuple containing (energy_array, index_array):

  • energy_array (np.ndarray): A 1D object array of length num_fidelities. Each element is a 1D NumPy float array of the extracted property values for that fidelity.

  • index_array (np.ndarray): A 1D object array of length num_fidelities. Each element is a 2D NumPy integer array of shape (N, 2). The columns represent [baseline_row_index, current_fidelity_row_index].

Return type:

tuple

Raises:

FileNotFoundError – If the baseline file (the first path in file_paths) cannot be located.

mfml_qc.utils.top_down_subsetting(y_trains: ndarray, indexes: ndarray, n_trains_target: list, seed: int = 42) → tuple[source]#

Function to produce nested subsets of data from a multifidelity dataset where sample selection is carried out from the highest fidelity to the lowest.

Parameters:
  • y_trains (np.ndarray) – The full target properties array.

  • indexes (np.ndarray) – The full mapping indexes array.

  • n_trains_target (list of int) – Target number of samples for each fidelity (lowest to highest).

  • seed (int, optional) – Random state seed for shuffling. Defaults to 42.

Returns:

(subset_y_trains, subset_indexes) ready for MFML training.

Return type:

tuple

Kernel Ridge Regression#

class mfml_qc.krr.KRR(kernel_type: str = 'matern', sigma: float = 100.0, nu: float = 1.5, p: float = 1.0, q: float = 1.0, reg: float = 1e-10)[source]#

Bases: object

Kernel Ridge Regression (KRR) model.

This class implements a lightweight, pure-NumPy KRR solver tailored for the ultra-fast Numba-compiled kernels provided in this module.

predict(X_test: ndarray) → ndarray[source]#

Predicts target values for the given test data.

Parameters:

X_test (np.ndarray) – The testing feature data matrix.

Returns:

The predicted target values.

Return type:

np.ndarray

Raises:

ValueError – If the model has not been trained yet.

train(X_train: ndarray, y_train: ndarray)[source]#

Fits the Kernel Ridge Regression model to the training data.

Parameters:
  • X_train (np.ndarray) – The training feature data matrix.

  • y_train (np.ndarray) – The training target data array.

mfml_qc.krr.gaussian_kernel_asymmetric(X_train: ndarray, X_test: ndarray, sigma: float = 100.0) → ndarray[source]#

Function to generate the asymmetric Gaussian kernel matrix for a given kernel width, \(\sigma\). The Gaussian kernel matrix entry for some \(x_i \in X_{test}, x_j \in X_{train}\) is computed as:

\[K(x_i,x_j) := \exp\left(\frac{-||x_i - x_j||_2^2}{2\sigma^2}\right)\]
Parameters:
  • X_train (np.ndarray) – The first matrix of input features (e.g., training set).

  • X_test (np.ndarray) – The second matrix of input features (e.g., test set).

  • sigma (float, optional) – The kernel width parameter. The default is 100.0.

Returns:

K – Asymmetric Gaussian kernel matrix for given inputs X_train and X_test.

Return type:

np.ndarray

mfml_qc.krr.gaussian_kernel_symmetric(X: ndarray, sigma: float = 100.0) → ndarray[source]#

Function to generate the symmetric Gaussian kernel matrix for a given kernel width, \(\sigma\). The Gaussian kernel matrix entry for some \(x_i, x_j\) is computed as:

\[K(x_i,x_j) := \exp\left(\frac{-||x_i - x_j||_2^2}{2\sigma^2}\right)\]
Parameters:
  • X (np.ndarray) – The matrix of input features.

  • sigma (float, optional) – The kernel width parameter. The default is 100.0.

Returns:

K – Symmetric Gaussian kernel matrix for given input X.

Return type:

np.ndarray

mfml_qc.krr.laplacian_kernel_asymmetric(X_train: ndarray, X_test: ndarray, sigma: float = 100.0) → ndarray[source]#

Function to generate the asymmetric Laplacian kernel matrix for a given kernel width, \(\sigma\). The Laplacian kernel matrix entry for some \(x_i \in X_{test}, x_j \in X_{train}\) is computed as:

\[K(x_i,x_j) := \exp\left(\frac{-||x_i - x_j||_1}{\sigma}\right)\]
Parameters:
  • X_train (np.ndarray) – The first matrix of input features (e.g., training set).

  • X_test (np.ndarray) – The second matrix of input features (e.g., test set).

  • sigma (float, optional) – The kernel width parameter. The default is 100.0.

Returns:

K – Asymmetric Laplacian kernel matrix for given inputs X_train and X_test.

Return type:

np.ndarray

mfml_qc.krr.laplacian_kernel_symmetric(X: ndarray, sigma: float = 100.0) → ndarray[source]#

Function to generate the symmetric Laplacian kernel matrix for a given kernel width, \(\sigma\). The Laplacian kernel matrix entry for some \(x_i, x_j\) is computed as:

\[K(x_i,x_j) := \exp\left(\frac{-||x_i - x_j||_1}{\sigma}\right)\]
Parameters:
  • X (np.ndarray) – The matrix of input features.

  • sigma (float, optional) – The kernel width parameter. The default is 100.0.

Returns:

K – Symmetric Laplacian kernel matrix for given input X.

Return type:

np.ndarray

mfml_qc.krr.matern_kernel_asymmetric(X_train: ndarray, X_test: ndarray, sigma: float = 100.0, nu: float = 1.5) → ndarray[source]#

Function to generate the asymmetric Matérn kernel matrix. Supports smoothness parameter \(\nu \in \{0.5, 1.5, 2.5\}\). For example, the Matérn 3/2 (\(\nu=1.5\)) kernel entry for some \(x_i \in X_{test}, x_j \in X_{train}\) is computed as:

\[K(x_i,x_j) := \exp\left(-\frac{\sqrt{3}||x_i - x_j||_2}{\sigma}\right) \left(1 + \frac{\sqrt{3}||x_i - x_j||_2}{\sigma}\right)\]
Parameters:
  • X_train (np.ndarray) – The first matrix of input features (e.g., training set).

  • X_test (np.ndarray) – The second matrix of input features (e.g., test set).

  • sigma (float, optional) – The kernel width parameter. The default is 100.0.

  • nu (float, optional) – The smoothness parameter. Supported values are 0.5, 1.5, and 2.5. The default is 1.5.

Returns:

K – Asymmetric Matérn kernel matrix for given inputs X_train and X_test.

Return type:

np.ndarray

mfml_qc.krr.matern_kernel_symmetric(X: ndarray, sigma: float = 100.0, nu: float = 1.5) → ndarray[source]#

Function to generate the symmetric Matérn kernel matrix. Supports smoothness parameter \(\nu \in \{0.5, 1.5, 2.5\}\). For example, the Matérn 3/2 (\(\nu=1.5\)) kernel entry for some \(x_i, x_j\) is computed as:

\[K(x_i,x_j) := \exp\left(-\frac{\sqrt{3}||x_i - x_j||_2}{\sigma}\right) \left(1 + \frac{\sqrt{3}||x_i - x_j||_2}{\sigma}\right)\]
Parameters:
  • X (np.ndarray) – The matrix of input features.

  • sigma (float, optional) – The kernel width parameter. The default is 100.0.

  • nu (float, optional) – The smoothness parameter. Supported values are 0.5, 1.5, and 2.5. The default is 1.5.

Returns:

K – Symmetric Matérn kernel matrix for the given input X.

Return type:

np.ndarray

mfml_qc.krr.wasserstein_kernel_asymmetric(X_train: ndarray, X_test: ndarray, sigma: float = 100.0, p: float = 1.0, q: float = 1.0) → ndarray[source]#

Function to generate the asymmetric Wasserstein kernel matrix based on 1D representations.

The Wasserstein kernel matrix entry for some \(x_i \in X_{test}, x_j \in X_{train}\) is computed as:

\[K(x_i,x_j) := \exp\left(-\frac{W_p(x_i, x_j)^q}{\sigma}\right)\]

where \(W_p\) is the 1-dimensional Wasserstein distance between the sorted features. The \(p\)-Wasserstein distance between two 1D distributions with CDFs \(F_a\) and \(F_b\) is computed as:

\[W_p(a, b) = \left( \int_{-\infty}^{\infty} |F_a(x) - F_b(x)|^p dx \right)^{1/p}\]
Parameters:
  • X_train (np.ndarray) – The first matrix of input features (e.g., training set).

  • X_test (np.ndarray) – The second matrix of input features (e.g., test set).

  • sigma (float, optional) – The kernel width parameter. The default is 100.0.

  • p (float, optional) – The power parameter for the CDF difference. The default is 1.0.

  • q (float, optional) – The outer exponent parameter. The default is 1.0.

Returns:

K – Asymmetric Wasserstein kernel matrix.

Return type:

np.ndarray

mfml_qc.krr.wasserstein_kernel_symmetric(X: ndarray, sigma: float = 100.0, p: float = 1.0, q: float = 1.0) → ndarray[source]#

Function to generate the symmetric Wasserstein kernel matrix based on 1D representations.

The Wasserstein kernel matrix entry for some \(x_i, x_j\) is computed as:

\[K(x_i,x_j) := \exp\left(-\frac{W_p(x_i, x_j)^q}{\sigma}\right)\]

where \(W_p\) is the 1-dimensional Wasserstein distance between the sorted features. The \(p\)-Wasserstein distance between two 1D distributions with CDFs \(F_a\) and \(F_b\) is computed as:

\[W_p(a, b) = \left( \int_{-\infty}^{\infty} |F_a(x) - F_b(x)|^p dx \right)^{1/p}\]
Parameters:
  • X (np.ndarray) – The matrix of input features.

  • sigma (float, optional) – The kernel width parameter. The default is 100.0.

  • p (float, optional) – The power parameter for the CDF difference. The default is 1.0.

  • q (float, optional) – The outer exponent parameter. The default is 1.0.

Returns:

K – Symmetric Wasserstein kernel matrix.

Return type:

np.ndarray

Quantum Chemistry Oracles#

class mfml_qc.oracles.base.QuantumEngine[source]#

Bases: ABC

Abstract interface for quantum chemistry orcale engines. Defines the lifecycle of a single calculation. Any new QC software connector must inherit from this class and implement its abstract methods.

abstract cleanup(work_dir: str)[source]#

Removes temporary/scratch files to save disk space.

This method is called automatically by evaluate if clean=True. It should safely attempt to delete massive or unnecessary files (like wavefunctions, heavy integrals, or checkpoint files) while leaving the main output log intact.

Parameters:

work_dir (str) – The directory where the calculation was executed.

evaluate(geometry: str | tuple, fidelity_params: Dict[str, Any], work_dir: str, clean=True, return_outs=True) → Dict[str, Any][source]#

The main method called by the Active Learning loop. This method handles the entire lifecycle of a quantum chemistry calculation: generating the input, running the engine, parsing the results, and optionally cleaning up scratch files.

Parameters:
  • geometry (str or tuple) – The molecular geometry. Can be a filepath to an XYZ file (str) or a tuple of (Z, R) coordinate arrays.

  • fidelity_params (dict) – A dictionary of engine-specific parameters for this fidelity level (e.g., basis set, functional, convergence criteria).

  • work_dir (str) – The directory where temporary input/output files should be written.

  • clean (bool, optional) – If True, calls the cleanup method after parsing to delete heavy scratch/temporary files. Default is True.

  • return_outs (bool, optional) – If True, returns the parsed results dictionary. Default is True.

Returns:

A dictionary of parsed properties (e.g., energies, gradients, success flag) if return_outs is True. Otherwise, returns None.

Return type:

dict or None

abstract generate_input(geometry: str | tuple, fidelity_params: Dict[str, Any], work_dir: str) → str[source]#

Generates the software-specific input file for the QC engine.

Parameters:
  • geometry (str or tuple) – The molecular geometry (XYZ filepath or coordinate arrays).

  • fidelity_params (dict) – Parameters specifying the level of theory (basis, functional, etc.).

  • work_dir (str) – The directory where the input file should be created.

Returns:

The absolute or relative path to the generated input file.

Return type:

str

abstract parse_output(output_file: str) → Dict[str, Any][source]#

Parses the output file to extract chemical properties.

Parameters:

output_file (str) – The path to the primary output file returned by run_calculation.

Returns:

A dictionary containing the extracted properties. MUST contain at least a ‘success’: bool key indicating if the calculation terminated normally without crashing.

Return type:

dict

abstract run_calculation(input_file: str, work_dir: str) → str[source]#

Executes the quantum chemistry program.

This method should handle subprocess calls, error catching for crashes, and environment variable setup required by the QC engine.

Parameters:
  • input_file (str) – The path to the input file generated by generate_input.

  • work_dir (str) – The directory where the calculation is being executed.

Returns:

The path to the primary output/log file generated by the engine.

Return type:

str

class mfml_qc.oracles.orca.OrcaEngine(orca_path: str = '/bin/orca', properties_to_extract: Dict[str, str] | None = None)[source]#

Bases: QuantumEngine

Custom quantum chemistry engine for ORCA calculations. This engine handles the generation of ORCA input files, execution of the ORCA binary via subprocess, and provides a simple parsing of the resulting output files including energies, gradients, and TD-DFT spectra.

cleanup(work_dir: str)[source]#

Removes temporary/scratch files generated by ORCA to save disk space.

Parameters:

work_dir (str) – The directory where the calculation was executed.

generate_input(geometry: str | tuple, fidelity_params: Dict[str, Any], work_dir: str) → str[source]#

Generates the ORCA input file (.inp) from geometry and fidelity parameters.

Parameters:
  • geometry (str or tuple) – The molecular geometry (XYZ filepath or coordinate arrays).

  • fidelity_params (dict) – Parameters specifying the calculation (e.g., method, basis, charge, multiplicity, nprocs, maxcore, optional_tags, custom_blocks, EnGrad, template_file).

  • work_dir (str) – The directory where the input file should be created.

Returns:

The path to the generated ORCA input file.

Return type:

str

parse_output(output_file: str, parse_gradients=False, parse_spectra=False) → Dict[str, Any][source]#

Parses the ORCA output file to extract chemical properties. This is a very bare minimum and rather specific extractor. Ideally one can use any custom parser once the .out file is generated by the previous step.

Parameters:
  • output_file (str) – The path to the primary ORCA output file.

  • parse_gradients (bool, optional) – Flag to enable parsing of the .engrad file. Defaults to False.

  • parse_spectra (bool, optional) – Flag to enable parsing of the TD-DFT absorption spectrum table. Defaults to False.

Returns:

A dictionary containing the extracted properties (e.g., ‘success’, ‘energy’, ‘gradients’, ‘tddft_spectrum’).

Return type:

dict

run_calculation(input_file: str, work_dir: str) → str[source]#

Executes the ORCA quantum chemistry program.

Parameters:
  • input_file (str) – The path to the input file generated by generate_input.

  • work_dir (str) – The directory where the calculation is being executed.

Returns:

The path to the generated ORCA output file (.out).

Return type:

str

class mfml_qc.oracles.pyscf.PySCFEngine(python_executable: str = '/home/vvinod/miniforge3/envs/mfmlenv/bin/python')[source]#

Bases: QuantumEngine

Implementation for the PySCF library as the quantum chemsitry engine. This script is untested and is under works.

cleanup(work_dir: str)[source]#

Removes PySCF generated scripts and temp files.

generate_input(geometry: str | tuple, fidelity_params: Dict[str, Any], work_dir: str) → str[source]#

Generates the software-specific input file for the QC engine.

Parameters:
  • geometry (str or tuple) – The molecular geometry (XYZ filepath or coordinate arrays).

  • fidelity_params (dict) – Parameters specifying the level of theory (basis, functional, etc.).

  • work_dir (str) – The directory where the input file should be created.

Returns:

The absolute or relative path to the generated input file.

Return type:

str

parse_output(output_file: str) → Dict[str, Any][source]#

Parses the output file to extract chemical properties.

Parameters:

output_file (str) – The path to the primary output file returned by run_calculation.

Returns:

A dictionary containing the extracted properties. MUST contain at least a ‘success’: bool key indicating if the calculation terminated normally without crashing.

Return type:

dict

run_calculation(input_file: str, work_dir: str) → str[source]#

Executes the quantum chemistry program.

This method should handle subprocess calls, error catching for crashes, and environment variable setup required by the QC engine.

Parameters:
  • input_file (str) – The path to the input file generated by generate_input.

  • work_dir (str) – The directory where the calculation is being executed.

Returns:

The path to the primary output/log file generated by the engine.

Return type:

str

Multifidelity Machine Learning#

class mfml_qc.mfml.ModelMFML(reg: float = 1e-09, kernel: str = 'matern', sigma: float = 715.0, nu: float = 1.5, p: float = 1.0, q: float = 1.0, p_bar: bool = False, base_estimator: object | None = None)[source]#

Bases: object

The Multi-Fidelity Machine Learning (MFML) model.

This class carries out the training and prediction of MFML models. It supports both standard MFML and the optimzied MFML (o-MFML) models which are data-adaptive combinations of the sub-models.

predict(X_test: ndarray, X_val: ndarray | None = None, y_test: ndarray | None = None, y_val: ndarray | None = None, optimiser: str = 'default', **optargs)[source]#

Predicts target values using the trained multifidelity ensemble.

Supports standard Single-Grid Combination Technique (SGCT) arithmetic or advanced machine-learned combinations (o-MFML) using a validation set.

Parameters:
  • X_test (np.ndarray) – The testing feature matrix.

  • X_val (np.ndarray, optional) – Validation feature matrix, required if using an advanced optimizer.

  • y_test (np.ndarray, optional) – True target values for the test set. If provided, computes MAE and RMSE and saves them to the model object.

  • y_val (np.ndarray, optional) – True target values for the validation set, required if using an advanced optimizer.

  • optimiser (str, optional) – The combination strategy to use. Options include: ‘default’ (SGCT), ‘OLS’, ‘LRR’, ‘LASSO’, ‘MLPR’, ‘KRR’, or ‘CompKRR’. Defaults to ‘default’.

  • **optargs (dict) – Additional hyperparameters to pass to the chosen optimizer model.

Returns:

The final predicted target values for the test set.

Return type:

np.ndarray

train(X_train_parent: ndarray, file_paths: list | None = None, y_trains: ndarray | None = None, indexes: ndarray | None = None, shuffle: bool = False, n_trains: ndarray | None = None, seed: int = 0)[source]#

Multifidelity data extraction and training of the sub-models.

Parameters:
  • X_train_parent (np.ndarray) – The complete feature matrix corresponding to the baseline (lowest fidelity) data.

  • file_paths (list of str, optional) – List of paths to property files ordered from lowest to highest fidelity. Required if y_trains and indexes are not provided.

  • y_trains (np.ndarray, optional) – Precomputed object array of target properties for each fidelity.

  • indexes (np.ndarray, optional) – Precomputed object array of nested mapping indexes.

  • shuffle (bool, optional) – If True, randomly shuffles the selected nested subsets. Defaults to False.

  • n_trains (np.ndarray, optional) – Array specifying the target number of training samples for each fidelity.

  • seed (int, optional) – Random seed for shuffling. Defaults to 0.

Raises:

ValueError – If neither precomputed arrays (y_trains, indexes) nor file_paths are provided.

Active Learning#

mfml_qc.active_learning.ensemble_variance(base_estimator: object, X_pool: ndarray, X_train: ndarray, y_train: ndarray, n_ensemble: int = 5, train_size: float = 0.85) → ndarray[source]#

Computes Ensemble-based uncertainty quantification.

Estimates uncertainty by training an ensemble of models on random subsets (85%) of the training data and computing the variance of their predictions.

Parameters:
  • base_estimator (object) – The base machine learning model to use for the ensemble.

  • X_pool (np.ndarray) – The pool feature matrix to evaluate.

  • X_train (np.ndarray) – The complete training feature matrix.

  • y_train (np.ndarray) – The complete training target array.

  • n_ensemble (int, optional) – The number of models to include in the ensemble. Defaults to 5.

  • train_size (float, optional) – The fraction of training data to use for the ensemble of models. Default is 85 (that is 85%).

Returns:

A 1D array of ensemble standard deviations for the pool data.

Return type:

np.ndarray

mfml_qc.active_learning.gpr_variance(X_train: ndarray, X_pool: ndarray, kernel_type: str = 'matern', sigma: float = 100.0, reg: float = 1e-09, nu: float = 1.5, p: float = 1.0, q: float = 1.0) → ndarray[source]#

Computes the exact analytical predictive variance for a set of pool geometries.

Because the predictive variance in Gaussian Process Regression (or Kernel Ridge Regression) depends strictly on the spatial distribution of the feature data and the kernel, it is completely independent of the target properties or model weights.

The predictive variance for a set of pool points \(x_*\) is given by:

\[\mathbb{V}[x_*] = k(x_*, x_*) - k(X, x_*)^T (K(X, X) + \lambda I)^{-1} k(X, x_*)\]
Parameters:
  • X_train (np.ndarray) – The training feature matrix \(X\).

  • X_pool (np.ndarray) – The pool feature matrix containing the points to evaluate \(x_*\).

  • kernel_type (str, optional) – The type of kernel to use (‘matern’, ‘gaussian’, ‘laplacian’, or ‘wasserstein’). Defaults to ‘matern’.

  • sigma (float, optional) – The kernel width parameter. Defaults to 100.0.

  • reg (float, optional) – The regularization parameter (\(\lambda\)). Defaults to 1e-9.

  • nu (float, optional) – Smoothness parameter for the Matérn kernel. Defaults to 1.5.

  • p (float, optional) – Power parameter for the Wasserstein kernel. Defaults to 1.0.

  • q (float, optional) – Outer exponent parameter for the Wasserstein kernel. Defaults to 1.0.

Returns:

A 1D array of computed predictive variances for each point in the pool.

Return type:

np.ndarray

mfml_qc.active_learning.lfab(base_estimator: object, X_pool: ndarray, y_pool_low: ndarray, X_train: ndarray, y_train_low: ndarray) → ndarray[source]#

Computes Low Fidelity as Bias (LFaB) uncertainty quantification.

Estimates uncertainty by using the absolute prediction error of a model trained on low-fidelity data. Areas where the low-fidelity surrogate struggles are assumed to be areas of high uncertainty.

The LFaB error for a set of pool points \(x_*\) is computed as:

\[LFaB[x_*] = \left\lvert \hat{P}^{low}_{ML} - P^{low}_{ref} \right\rvert\]

where \(\hat{P}^{low}_{ML}\) is the low-fidelity prediction of the ML model and \(P^{low}_{ref}\) is the reference low-fidelity value.

Parameters:
  • base_estimator (object) – The machine learning model to train on the baseline data.

  • X_pool (np.ndarray) – The pool feature matrix to evaluate.

  • y_pool_low (np.ndarray) – The low-fidelity target data corresponding to the pool geometries.

  • X_train (np.ndarray) – The training feature matrix.

  • y_train_low (np.ndarray) – The low-fidelity target data corresponding to the training geometries.

Returns:

A 1D array of absolute prediction errors on the low-fidelity baseline.

Return type:

np.ndarray

Vectorized Models#

Vector-valued Kernel Ridge Regression.

Provides two estimators for learning vector-valued targets (e.g., dipole moments):

  • VectorKRR: Isotropic kernel K(x,x’) = k(x,x’) I_d. Equivalent to d independent scalar KRRs with a shared regularisation parameter. Uses a single Cholesky factorisation solved against all d right-hand sides.

  • CoupledVectorKRR: Separable kernel K(x,x’) = k(x,x’) T, where T is a d×d positive semidefinite output covariance matrix, learnable via Nelder-Mead on validation MSE. T is parameterised as L L^T (Cholesky factor, d(d+1)/2 free parameters). Efficient solve via eigendecomposition of the scalar kernel.

Both classes expose .train(X, Y) / .predict(X) for duck-type compatibility with ModelMFML’s base_estimator interface.

Also provides DifferentiableVectorKRR, a frozen PyTorch evaluator for inference in differentiable pipelines.

class mfml_qc.vector_krr.CoupledVectorKRR(kernel_type='gaussian', sigma=100.0, nu=1.5, p=1.0, q=1.0, reg=1e-10, val_fraction=0.15, max_opt_iter=200)[source]#

Bases: object

Vector KRR with learnable output covariance T = L L^T.

Training procedure:
  1. Split data into train/val

  2. Eigendecompose training kernel (computed once)

  3. Optimise T via Nelder-Mead on validation MSE

  4. Re-solve on full training data with optimal T

Parameters:
  • kernel_type (str) – One of ‘gaussian’, ‘matern’, ‘laplacian’, ‘wasserstein’.

  • sigma (float) – Kernel width parameter.

  • nu (float) – Matern smoothness parameter.

  • p (float) – Wasserstein power parameter.

  • q (float) – Wasserstein outer exponent.

  • reg (float) – Tikhonov regularisation.

  • val_fraction (float) – Fraction of training data held out for T optimisation.

  • max_opt_iter (int) – Maximum Nelder-Mead iterations for T optimisation.

predict(X_test)[source]#

Predict vector targets.

Parameters:

X_test (np.ndarray, shape (M, D))

Return type:

np.ndarray, shape (M, d)

train(X_train, Y_train)[source]#

Train with T optimisation.

Parameters:
  • X_train (np.ndarray, shape (N, D))

  • Y_train (np.ndarray, shape (N, d) or (N,))

class mfml_qc.vector_krr.DifferentiableVectorKRR(X_train_np, alphas_np, kernel_type='gaussian', sigma=100.0, nu=1.5, p=1.0, q=1.0)[source]#

Bases: Module

Frozen PyTorch evaluator for vector-valued KRR.

Pre-solved alphas are stored as buffers (not learnable parameters). Useful as a building block in differentiable pipelines.

Parameters:
  • X_train_np (np.ndarray, shape (N, D))

  • alphas_np (np.ndarray, shape (N, d))

  • kernel_type (str)

  • sigma (float)

  • nu (float)

  • p (float)

  • q (float)

forward(X_test)[source]#
Parameters:

X_test (torch.Tensor, shape (1, D))

Return type:

torch.Tensor, shape (d,)

classmethod from_vector_krr(model)[source]#

Construct from a trained VectorKRR or CoupledVectorKRR.

class mfml_qc.vector_krr.VectorKRR(kernel_type='gaussian', sigma=100.0, nu=1.5, p=1.0, q=1.0, reg=1e-10)[source]#

Bases: object

Vector-valued KRR with isotropic separable kernel k(x,x’) I_d.

Parameters:
  • kernel_type (str) – One of ‘gaussian’, ‘matern’, ‘laplacian’, ‘wasserstein’.

  • sigma (float) – Kernel width parameter.

  • nu (float) – Matern smoothness parameter (0.5, 1.5, or 2.5).

  • p (float) – Wasserstein power parameter.

  • q (float) – Wasserstein outer exponent.

  • reg (float) – Tikhonov regularisation parameter.

predict(X_test)[source]#

Predict vector targets for test features.

Parameters:

X_test (np.ndarray, shape (M, D))

Return type:

np.ndarray, shape (M, d)

train(X_train, Y_train)[source]#

Solve the vector KRR system.

Parameters:
  • X_train (np.ndarray, shape (N, D)) – Training feature matrix.

  • Y_train (np.ndarray, shape (N, d) or (N,)) – Vector targets. If 1D, treated as d=1.

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.

class mfml_qc.vector_mfml.DifferentiableVectorMFML(sub_models, nfids)[source]#

Bases: Module

Differentiable MFML evaluator for vector properties.

Wraps 2N-1 DifferentiableVectorKRR sub-models and applies SGCT arithmetic on d-dimensional prediction vectors.

Parameters:
forward(X_test)[source]#
Parameters:

X_test (torch.Tensor, shape (1, D))

Return type:

torch.Tensor, shape (d,)

classmethod from_vector_mfml(vector_mfml_model)[source]#

Construct from a trained VectorMFML instance.

class mfml_qc.vector_mfml.VectorMFML(base_estimator)[source]#

Bases: object

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.

predict(X_test)[source]#

Predict vector targets using SGCT combination.

Parameters:

X_test (np.ndarray, shape (M, D)) – Test feature matrix (descriptors or flattened coordinates for RPR).

Returns:

Predicted vectors (un-centered).

Return type:

np.ndarray, shape (M, d)

train(X_train_parent, y_trains, indexes, n_trains_target=None, seed=42)[source]#

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.

Automatic Differentiation#

Autodifferentiable KRR and MFML evaluators.

Provides differentiable (PyTorch) wrappers around trained KRR and MFML models, enabling energy prediction with automatic force derivation via backpropagation (F = -∇E with respect to atomic coordinates).

Requires PyTorch (optional dependency of mfml_qc).

class mfml_qc.autodiff.DifferentiableKRR(X_train_np, alphas_np, kernel_type='gaussian', sigma=100.0, nu=1.5, p=1.0, q=1.0)[source]#

Bases: Module

Descriptor-agnostic differentiable KRR evaluator.

Takes pre-computed descriptor tensors as input and returns scalar energy predictions. Supports all kernels from mfml_qc.krr: gaussian, matern, laplacian, wasserstein.

Parameters:
  • X_train_np (np.ndarray, shape (N, D)) – Training descriptors.

  • alphas_np (np.ndarray, shape (N,)) – Solved KRR coefficients.

  • kernel_type (str) – Kernel type. One of ‘gaussian’, ‘matern’, ‘laplacian’, ‘wasserstein’.

  • sigma (float) – Kernel width parameter.

  • nu (float) – Matern smoothness parameter (0.5, 1.5, or 2.5).

  • p (float) – Wasserstein power parameter.

  • q (float) – Wasserstein outer exponent.

forward(X_test)[source]#

Predict scalar energy from descriptor tensor.

Parameters:

X_test (torch.Tensor, shape (1, D)) – Descriptor for a single geometry.

Returns:

Predicted energy.

Return type:

torch.Tensor, scalar

classmethod from_krr_model(krr_model)[source]#

Construct from a trained mfml_qc.krr.KRR instance.

Parameters:

krr_model (mfml_qc.krr.KRR) – A trained KRR model.

class mfml_qc.autodiff.DifferentiableMFML(sub_models, nfids, optimiser='default', lcc_optimizer=None)[source]#

Bases: Module

Differentiable MFML evaluator wrapping 2N-1 DifferentiableKRR sub-models.

Supports default SGCT and sklearn-based o-MFML optimizers.

Parameters:
  • sub_models (list of DifferentiableKRR) – The 2N-1 trained sub-model evaluators.

  • nfids (int) – Number of fidelity levels.

  • optimiser (str) – Combination strategy: ‘default’ (SGCT) or ‘learned’ (sklearn o-MFML).

  • lcc_optimizer (object, optional) – Fitted sklearn estimator for o-MFML combination (OLS, LRR, LASSO, MLPR).

forward(X_test)[source]#

Predict scalar energy from descriptor tensor.

Parameters:

X_test (torch.Tensor, shape (1, D))

Return type:

torch.Tensor, scalar

classmethod from_mfml_model(mfml_model)[source]#

Construct from a trained mfml_qc.mfml.ModelMFML instance.

Parameters:

mfml_model (mfml_qc.mfml.ModelMFML) – A trained MFML model.

mfml_qc.autodiff.generate_coulomb_matrix(coords, charges)[source]#

Differentiable Unsorted Coulomb Matrix generator.

Extracts the diagonal and upper triangle into a 1D flat tensor, matching the feature order of mfml_qc.representations.compute_flat_coulomb.

Parameters:
  • coords (torch.Tensor, shape (N_atoms, 3)) – Atomic coordinates (requires_grad=True for force computation).

  • charges (torch.Tensor, shape (N_atoms,)) – Nuclear charges.

Returns:

Flattened upper-triangular Coulomb matrix.

Return type:

torch.Tensor, shape (N_atoms*(N_atoms+1)//2,)

mfml_qc.autodiff.predict_energies_and_forces(evaluator, test_coords_np, charges_np, descriptor_fn=None)[source]#

Predict energies and forces via autodifferentiation.

For each test geometry, computes the descriptor, predicts the energy, and obtains forces as F = -∇E via backpropagation through the descriptor function and kernel evaluation.

Parameters:
  • evaluator (DifferentiableKRR or DifferentiableMFML) – A trained differentiable evaluator.

  • test_coords_np (np.ndarray, shape (N_mol, N_atoms, 3)) – Test geometries.

  • charges_np (np.ndarray, shape (N_atoms,)) – Nuclear charges.

  • descriptor_fn (callable, optional) – Maps (coords_tensor, charges_tensor) -> (n_features,) tensor. Defaults to generate_coulomb_matrix().

Returns:

  • energies (np.ndarray, shape (N_mol,)) – Predicted energies.

  • forces (np.ndarray, shape (N_mol, N_atoms, 3)) – Predicted forces (negative energy gradient).

RPR#

Rotate-Predict-Rotate (RPR) frame canonicalization for vector-valued KRR.

Provides a per-geometry canonical frame from the inertia tensor and a composable wrapper (RPRVectorKRR) that works with any model exposing .train(X, Y) / .predict(X).

The canonical frame is defined by the principal axes of inertia. Sign ambiguity is resolved using the mass-weighted cubic moment along each axis: s_i = Σ_a m_a (r_a · e_i)^3. This is computed in the molecular frame and is therefore rotationally covariant.

Degeneracy handling:
  • Linear molecules (one eigenvalue ≈ 0): warning emitted, fallback convention based on the heaviest off-axis atom.

  • Symmetric tops (two equal eigenvalues): similar fallback with warning.

Reference: [1] J. Martinka, M. Pederzoli, M. Barbatti, P. O. Dral, J. Pittner, A simple approach to rotationally invariant machine learning of a vector quantity, J. Chem. Phys. 161, 174104 (2024). DOI: 10.1063/5.0230176

class mfml_qc.rpr.RPRVectorKRR(model, Z, descriptor_fn)[source]#

Bases: object

RPR wrapper around any vector-valued model with .train/.predict.

During training, each geometry is canonicalized: descriptors are computed from canonical coordinates, and targets are rotated to the canonical frame. During prediction, predictions in the canonical frame are rotated back to the lab frame.

Parameters:
  • model (object) – Inner model with .train(X, Y) and .predict(X) methods.

  • Z (array-like, shape (N_atoms,)) – Atomic numbers.

  • descriptor_fn (callable) – Maps (Z=atomic_numbers, R=coordinates) to a 1D descriptor array. E.g., mfml_qc.representations.compute_flat_coulomb.

predict(X_test)[source]#

Predict and rotate back to lab frame.

Parameters:

X_test (np.ndarray, shape (M, N_atoms*3)) – Flattened Cartesian coordinates.

Returns:

Predictions in the lab frame.

Return type:

np.ndarray, shape (M, d)

train(X_train, Y_train)[source]#

Train the RPR-wrapped model.

Parameters:
  • X_train (np.ndarray, shape (N, N_atoms*3)) – Flattened Cartesian coordinates.

  • Y_train (np.ndarray, shape (N, d)) – Vector targets in the lab frame.

mfml_qc.rpr.canonicalize(coords, masses, degeneracy_tol=1e-06)[source]#

Compute the RPR canonical frame for a molecular geometry.

Parameters:
  • coords (np.ndarray, shape (N_atoms, 3)) – Cartesian coordinates in the lab frame.

  • masses (np.ndarray, shape (N_atoms,)) – Atomic masses.

  • degeneracy_tol (float) – Relative tolerance for detecting degenerate inertia eigenvalues.

Returns:

  • U (np.ndarray, shape (3, 3)) – Rotation matrix whose columns are the principal axes. Right-handed (det = +1). Sign convention: cubic moment along each axis is non-negative.

  • com (np.ndarray, shape (3,)) – Center of mass.

Indices and tables#