Metadata-Version: 2.4
Name: pyqed
Version: 0.3.0
Summary: Electronic structure, quantum dynamics, and spectroscopy in Python
Author-email: Bing Gu <gubing@westlake.edu.cn>
License-Expression: MIT
Project-URL: Homepage, https://pyqed.org
Project-URL: Documentation, https://docs.pyqed.org
Project-URL: Repository, https://github.com/binggu56/pyqed
Project-URL: Issues, https://github.com/binggu56/pyqed/issues
Project-URL: Changelog, https://github.com/binggu56/pyqed/blob/master/HISTORY.rst
Keywords: quantum chemistry,quantum dynamics,spectroscopy,molecular quantum electrodynamics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: <3.14,>=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: numpy>=2.0
Requires-Dist: opt-einsum>=3.3
Requires-Dist: periodictable>=1.7
Requires-Dist: scipy>=1.13
Provides-Extra: analysis
Requires-Dist: matplotlib>=3.8; extra == "analysis"
Provides-Extra: accelerators
Requires-Dist: numba>=0.59; extra == "accelerators"
Requires-Dist: psutil>=5.9; extra == "accelerators"
Provides-Extra: md
Requires-Dist: ase>=3.23; extra == "md"
Requires-Dist: h5py>=3.10; extra == "md"
Requires-Dist: openmm>=8.1; extra == "md"
Provides-Extra: mace
Requires-Dist: ase>=3.23; extra == "mace"
Requires-Dist: mace-torch>=0.3.13; extra == "mace"
Provides-Extra: ml
Requires-Dist: jax>=0.4.26; extra == "ml"
Requires-Dist: scikit-learn>=1.4; extra == "ml"
Requires-Dist: tensorly>=0.8; extra == "ml"
Requires-Dist: tntorch>=1.1.2; extra == "ml"
Requires-Dist: torch>=2.2; extra == "ml"
Provides-Extra: torch
Requires-Dist: torch>=2.2; extra == "torch"
Provides-Extra: plot
Requires-Dist: matplotlib>=3.8; extra == "plot"
Provides-Extra: pyscf
Requires-Dist: pyscf>=2.5; extra == "pyscf"
Provides-Extra: ued
Requires-Dist: h5py>=3.10; extra == "ued"
Provides-Extra: docs
Requires-Dist: Sphinx<9,>=7.3; extra == "docs"
Requires-Dist: roman>=4.1; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
Provides-Extra: test
Requires-Dist: build>=1.2; extra == "test"
Requires-Dist: matplotlib>=3.8; extra == "test"
Requires-Dist: numba>=0.59; extra == "test"
Requires-Dist: pyscf>=2.5; extra == "test"
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: twine>=5; extra == "test"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

PyQED
=====

.. image:: https://img.shields.io/pypi/v/pyqed.svg
   :target: https://pypi.org/project/pyqed/
   :alt: PyPI release

.. image:: https://readthedocs.org/projects/pyqed/badge/?version=latest
   :target: https://docs.pyqed.org/
   :alt: Documentation status

.. image:: https://img.shields.io/badge/license-MIT-blue.svg
   :target: https://github.com/binggu56/pyqed/blob/main/LICENSE
   :alt: MIT license

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 <https://docs.pyqed.org/en/latest/capabilities.html>`_ 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:

.. code-block:: bash

   python -m pip install pyqed

For the current ``bg`` development branch:

.. code-block:: bash

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

Published releases provide platform wheels containing the production qchem
accelerators. Source installs build the same required accelerators by default
and therefore need a supported C/C++ toolchain. Verify an installation with:

.. code-block:: bash

   python -m pyqed.qchem.check_install

The slow pure-Python integral implementation is an explicit reference/debug
mode; see the installation guide for its source-build and runtime settings.

Use documentation from the same release or commit as the installed code.  See
the `installation guide <https://docs.pyqed.org/en/latest/installation.html>`_
for verification and optional-dependency guidance.

Five-minute calculation
-----------------------

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

.. code-block:: python

   from pyqed.qchem import Molecule

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

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

Continue with the `quickstart
<https://docs.pyqed.org/en/latest/quickstart.html>`_ and the `examples gallery
<https://docs.pyqed.org/en/latest/examples.html>`_.

Lattice-gauge pilot
-------------------

``pyqed.lgt`` contains a one-dimensional Schwinger-model pilot with compact
quantum links and Wilson-line-dressed Fourier-DVR hopping.  The alternating
matter/link MPS represents every local Gauss law as a component of one
additive vector quantum number, so the symmetric DMRG calculation needs no
finite penalty.  Reproduce the ED/MPS comparison and scaling figures with:

.. code-block:: bash

   PYTHONPATH=. python examples/lgt/alternating_wilson_dvr_mps.py

The channel-targeted real-time calculation extracts ``M_V`` and ``M_S``
without a multiroot state-averaged sweep:

.. code-block:: bash

   PYTHONPATH=. python examples/lgt/channel_targeted_mv_ms_mps.py

The Gauss-resolved MPO is rounded sector by sector before DMRG/TDVP, avoiding
the redundant sum-of-products bond without mixing gauge sectors.  For the
larger ``N=7`` physical-ED flux-convergence reference, run:

.. code-block:: bash

   PYTHONPATH=. python examples/lgt/dynamical_schwinger_dvr.py --npts 7

Development
-----------

Run focused tests from the repository root:

.. code-block:: bash

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

Build the documentation with warnings treated as errors:

.. code-block:: bash

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

Read `CONTRIBUTING.md
<https://github.com/binggu56/pyqed/blob/main/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.  No project DOI is asserted until one appears in an archived
release.  See the `citation guide
<https://docs.pyqed.org/en/latest/citing.html>`_ for a reproducibility
checklist.

License
-------

PyQED is distributed under the MIT License.  See ``LICENSE``.
