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

Representations

mfml_qc.representations.compute_flat_coulomb(Z: ndarray, R: ndarray) → ndarray

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

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

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]

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.utils.build_hierarchy_arrays(data_train: ndarray, hierarchy_cols: list) → tuple

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)

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

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)

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

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)

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

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

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

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

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

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

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

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

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

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)

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]

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

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]

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

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)

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)

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

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]

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

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/mfml/bin/python3.10')

Bases: QuantumEngine

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

cleanup(work_dir: str)

Removes PySCF generated scripts and temp files.

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

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]

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

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)

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)

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)

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

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

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

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

Indices and tables

• Index

• Module Index

• Search Page