Skip to main content

Multifidelity Machine Learning for Quantum Chemistry (MFML-4-QC)

License: MIT Code style: black

MFML-4-QC is an open-source library that enables multifidelity machine learning for quantum chemical systems. While the multifidelity methods are model-architecture agnostic, this library provides a lightweight, ultra-fast Numba-compiled Kernel Ridge Regression (KRR) setup as the primary architecture. Users can seamlessly integrate their own custom ML models (e.g., from scikit-learn) and directly interface with quantum chemistry engines like ORCA and PySCF for automated data generation and active learning.

Key Features

  • Ultra-Fast Kernels: Compute Matern, Gaussian, Laplacian, and Wasserstein kernels efficiently using JIT-compiled C-loops via Numba.
  • In-Memory Representations: Generate flattened Coulomb Matrices directly from .xyz trajectories without slow disk I/O.
  • Flexible ML Architectures: Use the built-in KRR or drop in any scikit-learn compatible estimator (e.g., RandomForestRegressor, MLPRegressor).
  • Quantum Chemistry Oracles: Abstract interfaces to automatically generate inputs, execute runs, and parse outputs from engines like ORCA and PySCF.
  • Automatic Differentiation: Differentiable PyTorch wrappers for trained KRR and MFML models, enabling automatic force prediction via backpropagation.
  • Vector-Valued Learning: Vector KRR (isotropic and coupled) and Vector MFML for directly learning vector properties such as dipole moments.
  • RPR Frame Canonicalisation: Rotate-Predict-Rotate canonicalisation for improved equivariance of vector property predictions.

Installation (v1.5.0)

Prerequisites: Python 3.10 or higher. It is best to install within a fresh conda environment to avoid dependency clashes.

Installing from PyPI

Users can directly install the package from PyPI using the pip call.

# Create and activate a fresh conda environment
conda create -n mfmlenv python=3.10 -y
conda activate mfmlenv

# Install the package
pip install mfml-4-qc

Install Directly From Source

You can also directly download the GitHub repo and install the package from there.

# Clone the repository
git clone https://github.com/vivinvinod/mfml-qc.git

# Create and activate a fresh conda environment
conda create -n mfmlenv python=3.10 -y
conda activate mfmlenv

# Install the package
pip install .

Additional Dependencies

If you plan to use the built-in PySCFEngine oracle, you can install the package with the optional PySCF dependency. (Note: PySCF can be a heavy dependency, which is why it is kept optional).

pip install .[pyscf]

If you plan to use the automatic differentiation features, install with the optional PyTorch dependency:

pip install .[torch]

To run the ORCAEngine you will need to install ORCA. See the official ORCA manual for details on how to do so.

Developer Installation

If you are beta testing, modifying the source code, or want to build the local documentation, install the package in "editable" mode (-e) with the [dev] flag. This installs testing tools (pytest, black etc) and the Sphinx documentation stack:

pip install -e .[dev]

Documentation and Examples

MFML-4-QC comes with a comprehensive documentation site that includes detailed API references and tutorials. An inbuilt 15 picosecond MD-trajectory of benzene is also provided as an inbuilt dataset for preliminary exploration of the package.

You can view the documentation at https://vivinvinod.github.io/mfml-4-qc/. To view the documentation locally, go to docs/build/html/ and open index.html in a browser of your choice. You can also browse the raw tutorial scripts directly in the examples/ directory of the code repository.

Metadata

Release files for mfml-4-qc 1.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mfml-4-qc 1.5.0
File Size Uploaded Provenance Actions
mfml_4_qc-1.5.0.tar.gz 42.3 kB Without provenance Details for mfml_4_qc-1.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mfml-4-qc 1.5.0
File Interpreter ABI Platform Actions
mfml_4_qc-1.5.0-py3-none-any.whl Python 3 none any Details for mfml_4_qc-1.5.0-py3-none-any.whl

Total release size: 83.6 kB

Release files / mfml_4_qc-1.5.0.tar.gz

Download URL mfml_4_qc-1.5.0.tar.gz
Size 42.3 kB
Tags Source
SHA-256 checksum
How to use checksums
f7be17819fefa98a67f02f60cc4ae7b577dee8736c65cfe0df799c44123b4631
BLAKE2b-256 checksum
How to use checksums
d5f7c4e8710cd699b32951ce7c1b5b1967ddc5e6df35ea18cc6404fbdbbb5393
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.22

Release files / mfml_4_qc-1.5.0-py3-none-any.whl

Download URL mfml_4_qc-1.5.0-py3-none-any.whl
Size 41.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
97a3c4a83e6a2ba972420b7d6b97dbb735e4d14b299587473254bf8d0150b4c9
BLAKE2b-256 checksum
How to use checksums
665a5e1801b4a4d3d11ddb1493f7f38f454bfaa48e0c90815d36d2bbfa8e9caf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.22

Security for mfml-4-qc 1.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.5.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page