Metadata-Version: 2.4
Name: mfml-4-qc
Version: 1.0.0
Summary: A Multifidelity Machine Learning framework for Quantum Chemistry
Author-email: Vivin Vinod <vinod@uni-wuppertal.de>
Project-URL: Homepage, https://github.com/vivinvinod/mfml-4-qc
Project-URL: Repository, https://github.com/vivinvinod/mfml-4-qc.git
Project-URL: Bug Tracker, https://github.com/vivinvinod/mfml-4-qc/issues
Project-URL: Documentation, https://vivinvinod.github.io/mfml-4-qc/index.html
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.0.0
Requires-Dist: numba>=0.60.0
Requires-Dist: tqdm>=4.60.0
Requires-Dist: matplotlib
Requires-Dist: scikit-learn>=1.0.0
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Provides-Extra: pyscf
Requires-Dist: pyscf>=2.0.0; extra == "pyscf"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: sphinx; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: nbsphinx; extra == "dev"
Requires-Dist: memory_profiler; extra == "dev"
Requires-Dist: sphinx-gallery; extra == "dev"
Requires-Dist: pydata-sphinx-theme; extra == "dev"
Requires-Dist: pyparsing; extra == "dev"
Dynamic: license-file

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

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/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 Matérn, 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.

## Installation (v1.0.0)
**Prerequisites:** Python 3.10 or higher. It is best to install within a fresh `conda` environment to avoid dependency clashes.

### Installing from PyPI
Once a stable version is released, users can directly install the pakcage from PyPI using the `pip` call.
```bash
# 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.
```bash
# Clone the repository
git clone https://github.com/vivinvinod/mfml-4-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).

```bash
pip install .[pyscf]
```

To run the `ORCAEngine` you will need to install ORCA. See the [official ORCA manual](https://www.faccts.de/docs/orca/6.1/manual/contents/quickstartguide/installation.html) 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:

```bash
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.
