Multifidelity Machine Learning for Quantum Chemistry (MFML-4-QC)
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.