Metadata-Version: 2.4
Name: quadlib
Version: 0.1.0
Summary: QuaDLib: Quantum Dynamics Library for Research, Development and Education
Author-email: Oriol Vendrell <oriol.vendrell@uni-heidelberg.de>, Sudip Sasmal <sudipsasmal.chem@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://gitlab.com/tc-heidelberg/quadlib
Project-URL: Repository, https://gitlab.com/tc-heidelberg/quadlib
Project-URL: Issues, https://gitlab.com/tc-heidelberg/quadlib/-/issues
Keywords: quantum dynamics,MCTDH,tensor decomposition,DVR,wavepacket propagation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Provides-Extra: plot
Requires-Dist: matplotlib; extra == "plot"
Provides-Extra: jupyter
Requires-Dist: matplotlib; extra == "jupyter"
Requires-Dist: jupyterlab; extra == "jupyter"
Requires-Dist: ipykernel; extra == "jupyter"
Requires-Dist: jupytext; extra == "jupyter"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# QuaDLib

Quantum Dynamics Library for Research, Development and Education.

QuaDLib is a pure-Python library for quantum dynamics, built on NumPy
and SciPy. It serves as a test bed for methods development and as a
teaching tool; the tree-tensor-network (ML-MCTDH) methods it is meant
to host are not implemented yet.

## What works

- Primitive bases: sine, exponential and harmonic-oscillator DVRs
  (`Sindvr`, `Expdvr`, `HOdvr`), boson, spin-1/2, angular momentum and
  discrete bases (`Boson`, `Spin`, `Jbasis`, `Discrete`).
- Sum-of-products operators (`SOP`), with their full dense or sparse
  matrix representation.
- Numerically exact propagation of a full wavefunction tensor
  (`WfnExact`, `quadlib.propagation.propagate_exact`), either by
  integrating the TDSE with the SOP right-hand side (`solver='zvode'`)
  or with `scipy.sparse.linalg.expm_multiply` on the sparse Hamiltonian
  matrix (`solver='expm'`). The second is faster and exact to machine
  precision as long as the sparse matrix fits in memory; operators with
  dense matrices on several degrees of freedom in one term favour the
  first.
- CPD wavefunctions (`WfnCPD`): norm, overlaps, reduced densities,
  expectation values, and propagation of the coefficient vector with
  frozen single-particle functions (`propagate_cpd_A`).
- Bath discretization of spectral densities (`quadlib.tools.bath`),
  correlation-function spectra and Fourier transforms
  (`quadlib.tools.spectra`).
- Reading the autocorrelation function of an existing Heidelberg MCTDH
  run directory (`Rundirectory`).

## Experimental

`quadlib.experimental` holds unfinished or known-incorrect code and is
not imported by `quadlib`: the tree data structures (`Node`, `Tree`,
`Pdof`), placeholders for the MCTDH equations of motion, and the coupled
CPD equations of motion.
`quadlib.legacy` keeps older utilities that the library does not use.

## Installation

Python 3.10 or later. NumPy and SciPy are the only required dependencies.

```bash
pip install quadlib
```

Extras:

```bash
pip install "quadlib[plot]"      # matplotlib, for the plotting helpers
pip install "quadlib[jupyter]"   # JupyterLab and jupytext, for the notebooks
```

From source:

```bash
git clone https://gitlab.com/tc-heidelberg/quadlib.git
cd quadlib
pip install -e ".[plot,dev]"     # dev adds pytest and ruff
```

or a specific release without cloning:

```bash
pip install git+https://gitlab.com/tc-heidelberg/quadlib.git@v0.1.0
```

## Tests and examples

```bash
pytest               # fast tests
pytest -m slow       # long reference tests (about one minute)
ruff check           # linter
```

Worked examples are in `docs/notebooks` (jupytext format):
`spin_boson_example.py` (exact propagation of a spin-boson model),
`td-cpd_example.md` (CPD wavefunction), and `bath_tests.md` (bath
discretization).

## Development

Day-to-day development happens in a private repository within the group. This
repository carries tagged releases, so its history is one commit per release
rather than a record of development. Bug reports and questions are welcome
through the issue tracker.

## Authors

- Oriol Vendrell, oriol.vendrell@uni-heidelberg.de,
  [ORCID 0000-0003-4629-414X](https://orcid.org/0000-0003-4629-414X)
- Sudip Sasmal, sudipsasmal.chem@gmail.com

MIT License. See `CITATION.cff` for how to cite.
