PyQED

PyQED is open-source research software for light--matter interactions, quantum dynamics, spectroscopy, open quantum systems, and electronic-structure workflows. The project combines reusable Python APIs with executable research examples and validation paths.

• Project website: https://pyqed.org/
• Documentation: https://docs.pyqed.org/
• Source: https://github.com/binggu56/pyqed
• Issue tracker: https://github.com/binggu56/pyqed/issues

Project status

PyQED is active research software. Interfaces and numerical workflows have different maturity levels, and some are experimental. Consult the capability status before selecting a method for production work. A passing example or benchmark is evidence for the documented case, not a guarantee for every model or parameter regime.

Installation

Install a published release from PyPI:

python -m pip install pyqed

For the current development tree:

git clone https://github.com/binggu56/pyqed.git
cd pyqed
python -m pip install -e .

Standard installations use the tested pure-Python fallbacks. To compile the optional native accelerators from a source checkout, use a supported C/C++ toolchain and opt in explicitly:

PYQED_BUILD_EXTENSIONS=1 python -m pip install .

Use documentation from the same release or commit as the installed code. See the installation guide for verification and optional-dependency guidance.

Five-minute calculation

This native, small-basis RHF calculation does not require PySCF:

from pyqed.qchem import Molecule

mol = Molecule(
    atom="H 0 0 0; H 0 0 0.74",
    unit="angstrom",
    basis="sto-3g",
)
mol.build(driver="builtin", eri="auto")
mf = mol.RHF().run()

print("converged:", mf.converged)
print("RHF energy:", mf.e_tot)

Continue with the quickstart and the examples gallery.

Development

Run focused tests from the repository root:

PYTHONPATH=. python -m pytest tests/test_rhf.py -q

Build the documentation with warnings treated as errors:

python -m pip install -r docs/requirements.txt
python -m sphinx -W --keep-going -b html docs/source /tmp/pyqed-docs

Read CONTRIBUTING.md before proposing changes. Scientific changes should include a focused test or reproducible benchmark and document units, conventions, dependencies, and references.

Citing PyQED

Use the metadata in CITATION.cff and record the exact PyQED release or Git commit used. The archived software has two DOI forms:

• all PyQED versions: https://doi.org/10.5281/zenodo.21316543;
• exact v0.2.0 archive: https://doi.org/10.5281/zenodo.21316544.

Use the version-specific DOI when citing v0.2.0, and use the all-versions DOI when you want a citation that resolves to the latest archived release. Also cite the project paper:

Yujuan Xie, Xiaotong Zhu, and Bing Gu, “PyQED: A Python Framework for Ab Initio Geometric Quantum Dynamics,” Chinese Journal of Chemical Physics (2026), https://doi.org/10.1063/1674-0068/cjcp2510161.

The article DOI is distinct from both software-archive DOIs. See the citation guide for method-citation and reproducibility guidance.

License

PyQED is distributed under the MIT License. See LICENSE.