Metadata-Version: 2.4
Name: q2m3
Version: 0.3.0
Summary: Quantum-Classical Hybrid QM/MM Framework POC with QPE for Early Fault-Tolerant Quantum Computers
Author-email: Ye Jun <yjmaxpayne@hotmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/yjmaxpayne/q2m3
Project-URL: Documentation, https://github.com/yjmaxpayne/q2m3#readme
Project-URL: Bug Tracker, https://github.com/yjmaxpayne/q2m3/issues
Keywords: quantum computing,quantum chemistry,QM/MM,QPE,PySCF,PennyLane
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyscf>=2.0.0
Requires-Dist: pennylane>=0.44.0
Requires-Dist: numpy>=2.0.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: tqdm>=4.65.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.0.0
Provides-Extra: sqd
Requires-Dist: ffsim>=0.0.83; extra == "sqd"
Requires-Dist: qiskit-addon-sqd>=0.12.1; extra == "sqd"
Provides-Extra: geometry
Requires-Dist: pyscf>=2.14.0; extra == "geometry"
Requires-Dist: pyscf-dispersion>=1.3.0; extra == "geometry"
Requires-Dist: geometric>=1.1; extra == "geometry"
Provides-Extra: dmrg
Requires-Dist: block2>=0.5.4; extra == "dmrg"
Requires-Dist: mkl<=2024.2.2; (sys_platform == "linux" and platform_machine == "x86_64") and extra == "dmrg"
Requires-Dist: intel-openmp; (sys_platform == "linux" and platform_machine == "x86_64") and extra == "dmrg"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.6.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: pre-commit>=4.0.0; extra == "dev"
Requires-Dist: commitizen>=4.10.0; extra == "dev"
Requires-Dist: ipython>=8.0.0; extra == "dev"
Requires-Dist: jupyter>=1.0.0; extra == "dev"
Requires-Dist: notebook>=6.5.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: babel>=2.13; extra == "docs"
Requires-Dist: jieba>=0.42.1; extra == "docs"
Requires-Dist: sphinx>=8.0.0; extra == "docs"
Requires-Dist: furo>=2024.8.6; extra == "docs"
Requires-Dist: sphinx-copybutton>=0.5.2; extra == "docs"
Requires-Dist: sphinxcontrib-mermaid>=1.0.0; extra == "docs"
Provides-Extra: gpu
Requires-Dist: pennylane-lightning[gpu]>=0.44.0; extra == "gpu"
Requires-Dist: cupy-cuda12x>=12.0.0; extra == "gpu"
Requires-Dist: jax[cuda12]>=0.4.0; extra == "gpu"
Provides-Extra: catalyst
Requires-Dist: pennylane-catalyst>=0.14.0; extra == "catalyst"
Requires-Dist: pennylane-lightning>=0.44.0; extra == "catalyst"
Provides-Extra: solvation
Requires-Dist: q2m3[catalyst]; extra == "solvation"
Requires-Dist: jax>=0.4.20; extra == "solvation"
Requires-Dist: jaxlib>=0.4.20; extra == "solvation"
Provides-Extra: viz
Requires-Dist: py3dmol>=2.0.0; extra == "viz"
Requires-Dist: ase>=3.22.0; extra == "viz"
Requires-Dist: nglview>=3.0.0; extra == "viz"
Dynamic: license-file

# q2m3: A Hybrid Quantum-Classical QM/MM Simulation Framework

[English](README.md) | [简体中文](README_CN.md)

<p align="center">
  <img src="doc/source/_static/logo.svg" alt="q2m3 logo" width="360">
</p>

[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Documentation](https://github.com/yjmaxpayne/q2m3/actions/workflows/docs.yml/badge.svg)](https://github.com/yjmaxpayne/q2m3/actions/workflows/docs.yml)
[![Docs](https://img.shields.io/badge/docs-latest-blue)](https://yjmaxpayne.github.io/q2m3/)
[![codecov](https://codecov.io/gh/yjmaxpayne/q2m3/graph/badge.svg)](https://codecov.io/gh/yjmaxpayne/q2m3)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20114945.svg)](https://doi.org/10.5281/zenodo.20114945)
[![PennyLane](https://img.shields.io/badge/PennyLane-%3E%3D0.44.0-01A982)](https://pennylane.ai/)
[![Catalyst](https://img.shields.io/badge/Catalyst-%3E%3D0.14.0-01A982)](https://github.com/PennyLaneAI/catalyst)
[![PySCF](https://img.shields.io/badge/PySCF-%3E%3D2.0.0-blue)](https://pyscf.org/)

q2m3 is a research framework for hybrid quantum-classical QM/MM
(quantum mechanics / molecular mechanics). It connects PySCF molecular models
to PennyLane quantum algorithms and resource estimates.

The project is an alpha proof of concept. Its small-system checks do not
establish production chemistry accuracy. Read each example's assumptions before
interpreting its results.

## Install

q2m3 requires Python 3.11+. To use the library, install it in a virtual environment:

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install q2m3
```

To run examples, use a source checkout with [uv](https://docs.astral.sh/uv/getting-started/installation/):

```bash
git clone https://github.com/yjmaxpayne/q2m3.git
cd q2m3
uv sync
```

Each example guide lists its optional dependencies and execution commands.

## Examples and documentation

Start with the [example guide](examples/README.md).
Choose a chapter for runnable examples, inputs, outputs, and scientific limits.

| Topic | Guide |
| --- | --- |
| Quantum phase estimation (QPE) | [QPE examples](examples/qpe/README.md) |
| Sample-based quantum diagonalization (SQD) | [SQD examples](examples/sqd/README.md) |
| QM/MM and solvation | [QM/MM examples](examples/qmmm/README.md) |
| Fragment interactions | [Fragment examples](examples/fragments/README.md) |
| Quantum resource estimates | [Resource examples](examples/resources/README.md) |
| Compilation and runtime | [Performance examples](examples/performance/README.md) |

See the [documentation site](https://yjmaxpayne.github.io/q2m3/) for tutorials,
model assumptions, and API references.

## Development, citation, and license

See the [development guide](doc/source/development.rst) for tests, code checks,
and documentation builds. Follow the [contribution notes](doc/source/development.rst#contribution-notes).
Do not commit generated outputs.

For research use, cite the release that produced your results.
[CITATION.cff](CITATION.cff) contains the citation metadata.
q2m3 uses the [MIT License](LICENSE).
