matgpr

Gaussian Process Regression tools for materials informatics, with first-class support for physics-informed mean functions.

matgpr is an early-stage research package for building reproducible GPR workflows on materials datasets. The 0.2.x line focuses on clean data preparation utilities, scikit-learn and GPyTorch GPR models, uncertainty-aware prediction, Bayesian optimization, and flexible physics-informed mean-function APIs.

The importable package is matgpr. Python 3.10 or newer is required.

matgpr is currently an active-development 0.x package. Pin release tags or commit hashes for reproducible research workflows, and see docs/versioning.md for the API-stability and versioning policy.

Repository Description

Gaussian Process Regression toolkit for materials informatics, including physics-informed mean functions and uncertainty-aware prediction.

Highlights

• Data cleaning, feature preprocessing, train/test splitting, and quick reports.
• Native estimator missing-value policies with auditable reports for rejected, dropped, or imputed rows.
• Optional-dependency helpers with clear install messages for advanced fingerprinting backends.
• Deterministic fingerprint caching and failed-row reports for repeated featurization workflows.
• Optional matminer Magpie composition descriptors through MagpieCompositionFeaturizer and helper functions.
• Scikit-learn GPR helpers for baseline models and kernel search.
• GPyTorch exact GPR with ARD kernels, target standardization, and predictive uncertainty.
• Learned heteroscedastic GPR with a residual noise GP for input-dependent observation uncertainty.
• Exact multitask GPR for complete or sparse multi-property materials datasets with learned inter-task covariance, shared/task-specific/known sparse noise, and scikit-learn-style wrappers.
• Multi-fidelity GPR for simulation-plus-experiment workflows, including a delta correction model and an initial two-level co-kriging model with a learned autoregressive coefficient.
• Scikit-learn-compatible estimators and featurizers for pipelines, grid search, and reusable validation workflows.
• PhysicsInformedMean for combining mechanistic equations with learned GP residuals.
• Reusable physics equation templates for Arrhenius, Arrhenius linear growth, square-root-time, linear growth, linear-parabolic growth, power-law, Hall-Petch, free-volume, and rule-of-mixtures mean functions.
• Physics-aware kernels, including Tanimoto similarity for molecular and polymer fingerprints and element-fraction kernels for inorganic compositions plus structure-feature kernels for crystal descriptors.
• Target transforms for positive, bounded, standardized, and physics-residual modeling workflows, with materials-property presets for common target types.
• Soft physics-constraint anchors for known limits and monotonic trends through virtual observations.
• Exact RBF derivative-constrained GPR for slope-informed physics trends.
• Physics-aware observation-noise profiles for mixed-source, replicate, and heteroscedastic datasets.
• Validation APIs for train/test evaluation, cross-validation summaries, and configurable learning curves.
• Candidate-generation helpers for finite chemistry, composition, formulation, and processing-condition pools.
• Candidate-pool diagnostics for descriptor completeness, duplicate keys, numeric feature coverage, and categorical search-space coverage.
• Optional BoTorch Bayesian optimization helpers for single- and multi-objective finite materials candidate pools, known observation noise, feasibility constraints, trust regions, duplicate avoidance, and diverse or sequential next-experiment batches.
• BO recommendation audit summaries for acquisition scores, posterior uncertainty, feasibility, trust-region, duplicate, and batch-selection decisions.
• Multi-objective finite-pool selection with Pareto-front and weighted scalarization utilities.
• Closed-loop experiment logging and restart state for BO recommendations, selected experiments, measured observations, pending candidates, and campaign summaries.
• Lightweight finite-pool BO benchmarks for comparing acquisition strategies, physics-prior scores, model scores, and random baselines on known outcomes.
• BO visualization helpers for benchmark traces, regret curves, and closed-loop campaign progress.
• Uncertainty diagnostics for coverage, calibration, NLPD, standardized residuals, and uncertainty-error trends.
• Plotting and metrics utilities for parity plots, learning curves, PCA, and regression quality checks.

Suggested Workflow

1. Clean the dataframe with normalize_column_names, replace_missing_placeholders, drop_duplicate_rows, and optional filter_iqr_outliers.
2. Separate the target from features with separate_features_target, then make train/test sets with split_train_test.
3. Add materials descriptors with CompositionFeaturizer, MagpieCompositionFeaturizer, StructureFeaturizer, SmilesFeaturizer, PolymerSmilesFeaturizer, or the lower-level fingerprint helpers.
4. Identify column types with identify_feature_types and build a transformer with build_preprocessor.
5. Choose a kernel, including TanimotoKernel for molecular or polymer fingerprints, ElementFractionKernel for elemental composition vectors, or StructureFeatureKernel for crystal-structure descriptors.
6. Optionally transform targets with make_materials_target_transform, LogTargetTransform, BoundedTargetTransform, StandardizedTargetTransform, or PhysicsResidualTransform.
7. Optionally add physics-derived virtual observations with KnownLimitConstraint, MonotonicTrendConstraint, and append_virtual_observations.
8. For known slope information, fit derivative-constrained models with DerivativeObservationSet, MonotonicDerivativeConstraint, and fit_derivative_constrained_gpr.
9. Optionally build per-row observation noise with SourceNoiseModel, ReplicateNoiseModel, FeatureNoiseModel, and combine_noise_profiles.
10. Optionally learn input-dependent noise with fit_heteroscedastic_gpr when residual variance changes across the materials space.
11. Optionally start from a reusable physics equation template with summarize_physics_equation_templates, search_physics_equation_templates, and get_physics_equation_template.
12. Train other models with MatGPRRegressor, PhysicsInformedGPRRegressor, build_sklearn_gpr_model, lower-level fit_gpytorch_gpr, MultitaskGPRRegressor, SparseMultitaskGPRRegressor, fit_multitask_gpytorch_gpr, or fit_sparse_multitask_gpytorch_gpr for multi-property targets.
13. Evaluate models with evaluate_train_test_split, evaluate_multitask_train_test_split, evaluate_sparse_multitask_train_test_split, evaluate_cokriging_train_test_split, cross_validate_regressor, learning_curve, cokriging_learning_curve, regression_metrics, train_test_regression_metrics, summarize_multitask_predictions, or summarize_sparse_multitask_predictions.
14. Visualize results with plot_parity, plot_learning_curve, plot_uncertainty_calibration, plot_uncertainty_vs_error, plot_distribution, plot_correlation_matrix, BO progress plots, or the PCA plotting helpers.
15. Optionally build and audit finite candidate pools, rank next experiments with Bayesian optimization, summarize recommendation audits, and log closed-loop campaigns.

Documentation

• A MkDocs site can be built locally with python -m mkdocs serve after installing matgpr with the docs extra.
• docs/quickstart.md shows the compact path from standard GPR to physics-informed GPR.
• docs/example_cards.md links to dataset cards and model cards for the public examples.
• docs/benchmark_summary.md summarizes public example benchmark gates, citation expectations, and standards for contributing new PI-GPR examples.
• docs/matgpr_user_guide.md provides a practical user guide for cleaning data, generating materials fingerprints, training standard and physics-informed GPR models, introducing custom physics equations, analyzing model performance, and saving artifacts.
• docs/physics_informed_gpr.md explains how physics equations enter the GP mean function and what users should report for PI-GPR models.
• docs/pi_gpr_guarantees.md clarifies what PI-GPR does and does not guarantee.
• docs/multitask_gpr.md explains correlated multitask GPR APIs for complete and sparse multi-property materials datasets.
• docs/multifidelity_gpr.md explains delta multi-fidelity GPR for simulation-plus-experiment workflows.
• docs/multifidelity_design.md records the planned co-kriging and multi-level fidelity model design.
• docs/sparse_multitask_walkthrough.md provides a compact sparse multitask workflow for incomplete multi-property target matrices.
• docs/sparse_multitask_noise_design.md explains shared, task-specific, and known per-observation sparse multitask noise.
• docs/fingerprinting_options.md explains available fingerprinting backends, when to use each option, which dependencies are core versus optional, and how to implement them in matgpr workflows.
• docs/versioning.md explains the active-development status, API-stability policy, and how to pin releases or commits for reproducible workflows.
• docs/release_checklist.md defines the release gate for v0.2.0 and later 0.x releases.
• docs/pypi_readiness.md records the PyPI readiness audit and remaining upload blockers.

Versioning And API Stability

Current version: 0.2.0.

matgpr follows semantic-versioning conventions in spirit, but minor 0.x releases may include breaking API changes while the package is still being shaped. For publications, benchmarks, and production workflows, install from a release tag or exact commit instead of the moving main branch:

python3 -m pip install "matgpr[examples] @ git+https://github.com/harikrishna-chem/matgpr.git@v0.2.0"

Record the matgpr version or commit hash, Python version, and dependency lock file alongside any published benchmark results.

Module Map

Physics-Informed GPR

Physics-informed models use PhysicsInformedMean. The user supplies:

• an equation callable,
• the feature columns used by that equation,
• optional learnable parameter initial values,
• optional fixed physical constants,
• which learnable parameters should stay positive,
• optional feature scaling information to recover original units.

Example:

import torch

from matgpr import PhysicsInformedMean, fit_gpytorch_gpr


def oxidation_equation(features, parameters):
    temperature_k = features["temperature_c"] + 273.15
    time_min = torch.clamp(features["time_min"], min=1e-8)
    A = parameters["A"]
    Q = parameters["Q"]
    kp = A * torch.exp(-Q / (8.314 * temperature_k))
    return torch.sqrt(torch.clamp(kp * time_min, min=1e-12))


mean_function = PhysicsInformedMean(
    equation=oxidation_equation,
    feature_indices={"temperature_c": 0, "time_min": 1},
    learnable_parameters={"A": 1.0, "Q": 100_000.0},
    positive_parameters=("A", "Q"),
)

result = fit_gpytorch_gpr(
    X_train,
    y_train,
    mean_module=mean_function,
)
prediction = result.predict(X_test)

This replaces hard-coded equation-specific mean classes. New physics equations can be added in notebooks or scripts without changing the library. The older EquationMeanFunction name remains available as a compatibility alias.

For estimator-style workflows, use PhysicsInformedGPRRegressor:

from matgpr import PhysicsInformedGPRRegressor

model = PhysicsInformedGPRRegressor(
    equation=oxidation_equation,
    feature_indices={"temperature_c": 0, "time_min": 1},
    learnable_parameters={"A": 1.0, "Q": 100_000.0},
    positive_parameters=("A", "Q"),
    training_iter=1000,
    verbose=False,
)

model.fit(X_train, y_train)
y_pred, y_std = model.predict(X_test, return_std=True)
learned_parameters = model.learned_physics_parameters_

Installation

From PyPI, after the v0.2.0 release is published:

python3 -m pip install matgpr

For optional example and Bayesian-optimization dependencies:

python3 -m pip install "matgpr[examples,bo]"

From a local checkout:

python3 -m pip install -e .

For development:

python3 -m pip install -e ".[dev,examples,bo]"
python3 -m ruff check matgpr tests scripts
python3 -m pytest
python3 -m build

For documentation:

python3 -m pip install -e ".[docs,examples]"
python3 -m mkdocs serve

For Bayesian optimization:

python3 -m pip install -e ".[bo]"

For optional matminer Magpie descriptors:

python3 -m pip install -e ".[materials-extra]"

Citation

If you use matgpr in a publication, cite the exact release, tag, or commit you used. Citation metadata is available in CITATION.cff; release DOIs are added after Zenodo archives each GitHub release. Individual examples should also cite the original papers and datasets listed in their reports. See docs/benchmark_summary.md for public-example citation and benchmark reporting guidance.

The previous archived release DOI for v0.1.1 is https://doi.org/10.5281/zenodo.21210387. Do not cite that DOI for v0.2.0 unless the analysis used the v0.1.1 release.

License

matgpr is released under the Apache License 2.0. See LICENSE.

Contributing

See CONTRIBUTING.md for development setup, contribution expectations, and licensing details. New physics-informed examples should also follow the benchmark and card standards in docs/benchmark_summary.md.

Examples

Worked examples are available under examples/:

• examples/opv/opv_gpr_modeling.ipynb compares standard GPR with physics-informed GPR models of increasing mean-function complexity.
• examples/solvent_diffusivity/solvent_diffusivity_gpr_modeling.ipynb compares temperature, concentration, and solvent-size physics means.
• Example reports explain the physical rationale, implementation details, validation protocol, and modeling conclusions.
• Each public example includes dataset_card.md and model_card.md files for provenance, features, validation protocol, learned physics terms, intended use, and known limitations.

The public example notebooks include Colab badges. When opened in Colab, they install matgpr[examples] from GitHub and download the matching dataset.pkl from the repository.

Roadmap

• Continue refining published-paper example workflows for materials-informatics users.
• Expand documentation with tutorials, API references, and example equations.
• Add multitask Gaussian-process models.
• Add additional physics-informed model families.
• Expand Bayesian optimization examples for next-experiment selection.

Project Status

This repository is under active development. The public API is being shaped around transparent examples, readable code, and research workflows that other materials scientists can adapt.