quadlib 0.1.0__tar.gz

quadlib-0.1.0/CITATION.cff

@@ -0,0 +1,26 @@
+cff-version: 1.2.0
+title: quadlib
+message: >-
+  If you use this software, please cite it using the
+  metadata from this file.
+type: software
+authors:
+  - given-names: Oriol
+    family-names: Vendrell
+    email: oriol.vendrell@uni-heidelberg.de
+    affiliation: Heidelberg University
+    orcid: 'https://orcid.org/0000-0003-4629-414X'
+  - given-names: Sudip
+    family-names: Sasmal
+    email: sudipsasmal.chem@gmail.com
+repository-code: 'https://gitlab.com/tc-heidelberg/quadlib'
+abstract: >-
+  QuaDLib: Quantum Dynamics Library for Research,
+  Development and Education: a pure-Python library providing
+  utilities for quantum dynamics.  It is intended for
+  research, development, and educational use and builds on
+  established numerical libraries.
+license: MIT
+# version and date-released are stamped at release time by tools/publish.sh
+version: 0.1.0
+date-released: '2026-10-06'

quadlib-0.1.0/HEADER

@@ -0,0 +1,4 @@
+# QuaDLib: QUAntum Dynamics LIBrary for research and methods development
+# Copyright (C) 2018-2026, The Theoretical Chemistry Group, Heidelberg University
+#
+# This software is licensed under the MIT License (https://spdx.org/licenses/MIT.html)

quadlib-0.1.0/LICENSE

@@ -0,0 +1,19 @@
+Copyright (C) 2018-2026 The Theoretical Chemistry Group, Heidelberg University
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

quadlib-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+# The test suite lives outside the package, so name it explicitly for the sdist:
+# it lets downstream packagers run the suite against the released source.
+recursive-include tests *.py
+include CITATION.cff HEADER

quadlib-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+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.

quadlib-0.1.0/README.md

@@ -0,0 +1,97 @@
+# 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.

quadlib-0.1.0/pyproject.toml

@@ -0,0 +1,97 @@
+[build-system]
+requires = ["setuptools>=77.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "quadlib"
+version = "0.1.0"
+description = "QuaDLib: Quantum Dynamics Library for Research, Development and Education"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Oriol Vendrell", email = "oriol.vendrell@uni-heidelberg.de"},
+    { name = "Sudip Sasmal", email = "sudipsasmal.chem@gmail.com"}
+]
+requires-python = ">=3.10"
+keywords = [
+    "quantum dynamics",
+    "MCTDH",
+    "tensor decomposition",
+    "DVR",
+    "wavepacket propagation",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Education",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Chemistry",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+
+dependencies = [
+    "numpy",
+    "scipy",
+]
+
+[project.optional-dependencies]
+# the plotting helpers import matplotlib lazily, so it is not a core dependency
+plot = ["matplotlib"]
+jupyter = [
+    "matplotlib",
+    "jupyterlab",
+    "ipykernel",
+    "jupytext",
+]
+dev = ["pytest", "ruff"]
+
+[project.scripts]
+qlb-offset-oper-dof = "quadlib.cli.qlb_offset_oper_dof:main"
+
+[project.urls]
+Homepage = "https://gitlab.com/tc-heidelberg/quadlib"
+Repository = "https://gitlab.com/tc-heidelberg/quadlib"
+Issues = "https://gitlab.com/tc-heidelberg/quadlib/-/issues"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["slow: long-running reference tests (run with -m slow)"]
+addopts = "-m 'not slow'"
+
+# Linter only: `ruff check` (not enforced in CI). The formatter is not
+# adopted; hand-aligned tables are protected in case it is run anyway.
+[tool.ruff]
+target-version = "py310"
+extend-exclude = ["src/quadlib/legacy", "docs/notebooks/legacy"]
+
+[tool.ruff.lint]
+# pinned explicitly so results do not depend on the installed ruff version
+select = ["F", "E4", "E7", "E9", "I", "B", "UP"]
+# style choices kept on purpose: one-line `if x: continue`, short names
+# such as `l`, lambda assignments; zip(strict=) not required
+ignore = ["E701", "E702", "E741", "E731", "B905"]
+
+[tool.ruff.lint.per-file-ignores]
+# notebooks: cells that display a value, imports laid out by hand
+"docs/notebooks/*" = ["B018", "E402", "I001", "F401"]
+# public API grouped by hand in sections; keep that order
+"src/quadlib/__init__.py" = ["I001", "F401"]
+# subpackage __init__ files re-export their public names
+"src/quadlib/*/__init__.py" = ["F401"]
+
+[tool.ruff.format]
+exclude = ["src/quadlib/tools/constants.py"]

quadlib-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

quadlib-0.1.0/src/quadlib/__init__.py

@@ -0,0 +1,39 @@
+# QuaDLib: QUAntum Dynamics LIBrary for research and methods development
+# Copyright (C) 2018-2026, The Theoretical Chemistry Group, Heidelberg University
+#
+# This software is licensed under the MIT License (https://spdx.org/licenses/MIT.html)
+
+import os.path
+
+# -------------------------------------------------------------
+# Make classes available in quadlib's namespace
+from quadlib.wavefunction.wfn_exact import WfnExact
+from quadlib.wavefunction.wfn_cpd import WfnCPD
+
+from quadlib.basis.boson import Boson
+from quadlib.basis.discrete import Discrete
+from quadlib.basis.expdvr import Expdvr
+from quadlib.basis.hodvr import HOdvr
+from quadlib.basis.sindvr import Sindvr
+from quadlib.basis.spin import Spin
+from quadlib.basis.jbasis import Jbasis
+
+from quadlib.operator.sop import SumOfProducts
+from quadlib.operator.sop import SumOfProducts as SOP
+from quadlib.operator.sop import OpType
+
+from quadlib.hdmctdh.rundirectory import Rundirectory
+#from quadlib.hdmctdh.mctdh_runner import MctdhRunner
+
+# -------------------------------------------------------------
+# Make submodules available
+import quadlib.tools.constants as cons
+import quadlib.tools.linalg as linalg
+import quadlib.tools.spectra as spectra
+import quadlib.tools.bath as bath
+import quadlib.tools.tensor as tensor
+import quadlib.wavefunction.wfn_exact as exactwfn
+
+import quadlib.propagation as propagation
+
+QDLPATH = os.path.dirname(__file__)

quadlib-0.1.0/src/quadlib/basis/__init__.py

@@ -0,0 +1,60 @@
+# QuaDLib: QUAntum Dynamics LIBrary for research and methods development
+# Copyright (C) 2018-2026, The Theoretical Chemistry Group, Heidelberg University
+#
+# This software is licensed under the MIT License (https://spdx.org/licenses/MIT.html)
+
+"""
+Primitive basis classes.
+
+Every basis class in this subpackage exposes at minimum the attribute `n`
+(the dimension of the single-DOF Hilbert space it represents).
+
+DVR (position-space) bases additionally expose `x`, `w`, `xmat`, `dq1`,
+`dq2`, `u`; see the :class:`DVRBasis` Protocol below.
+
+Algebraic bases (Boson, Spin, Jbasis, Discrete) expose the operators
+relevant to their physics with conventional capitalised names
+(``PauliX``, ``Jz``, ``Nop``, ``C``, ``A``, …). The dimension is always
+the lowercase `n`.
+"""
+
+from typing import Protocol, runtime_checkable
+
+import numpy as np
+
+
+@runtime_checkable
+class Basis(Protocol):
+    """Minimum interface every basis class provides."""
+
+    n: int  # dimension of the single-DOF Hilbert space
+
+
+@runtime_checkable
+class DVRBasis(Basis, Protocol):
+    """Position-space (DVR) basis.
+
+    All array attributes are real unless otherwise noted.
+
+    Attributes
+    ----------
+    x : ndarray of shape (n,)
+        DVR grid points.
+    w : ndarray of shape (n,)
+        DVR quadrature weights.
+    xmat : ndarray of shape (n, n)
+        Position operator in the DVR basis, equal to ``np.diag(x)``.
+    dq1 : ndarray of shape (n, n)
+        First-derivative matrix in the DVR basis.
+    dq2 : ndarray of shape (n, n)
+        Second-derivative matrix in the DVR basis.
+    u : ndarray of shape (n, n)
+        FBR → DVR transformation matrix.
+    """
+
+    x: np.ndarray
+    w: np.ndarray
+    xmat: np.ndarray
+    dq1: np.ndarray
+    dq2: np.ndarray
+    u: np.ndarray

quadlib-0.1.0/src/quadlib/basis/boson.py

@@ -0,0 +1,61 @@
+import numpy as np
+
+
+class Boson:
+    """
+    Boson (harmonic oscillator in SQ) basis.
+
+    N -- integer: number of states, counting |0>.
+
+    Notes: the maximum number of particles for a given N is N-1
+
+    """
+
+    def __init__(self, N):
+        """
+        Initialize a boson (harmonic oscillator SQ) basis object
+
+        """
+        if not isinstance(N, (int, np.integer)):
+            raise ValueError('N needs to be an integer\n')
+        self.n = N
+        self.ONE = _ONE(N)      # unit operator as a matrix
+        self.ONE_d = _ONE(N, diag=True) # unit operator as a diagonal oper.
+        self.Nop = _Bnum(N)    # number operator
+        self.Nop_d = _Bnum(N, diag=True) # number operator as a diagonal oper.
+        self.C = _Bc(N)        # creation operator
+        self.A = _Ba(N)        # annihilation operator
+        self.H = np.diag(np.ones(N)*0.5) + self.Nop # Hamiltonian in au.
+
+
+def _ONE(n, diag=False):
+    if diag:
+        return np.ones(n, float)
+    else:
+        return np.diag(np.ones(n, float))
+
+
+def _Bnum(n, diag=False):
+    ln = np.asarray(list(range(0, n)), float)
+    if diag:
+        return ln
+    else:
+        return np.diag(ln)
+
+
+def _Bc(n):
+    bc = np.zeros((n, n), float)
+    for i in list(range(1, n)):
+        bc[i, i-1] = np.sqrt(i)
+    return bc
+
+
+def _Ba(n):
+    ba = np.zeros((n, n), float)
+    for i in list(range(1, n)):
+        ba[i-1, i] = np.sqrt(i)
+    return ba
+
+
+
+

quadlib-0.1.0/src/quadlib/basis/discrete.py

@@ -0,0 +1,71 @@
+import numpy as np
+
+
+class Discrete:
+    """
+    Discrete basis (e.g. to represent electronic-state degrees of freedom).
+
+    N -- integer: number of states, counting |0>.
+
+    Notes: the maximum number of particles for a given N is N-1
+
+    """
+    def __init__(self, N):
+        """
+        Initialize a discrete basis object
+
+        """
+        if not isinstance(N, (int, np.integer)):
+            raise ValueError('N needs to be an integer\n')
+        self.n = N
+        self.ONE = _ONE(N)      # unit operator as a matrix
+        self.ONE_d = _ONE(N, diag=True) # unit operator as a diagonal oper.
+
+
+    def P(self, n, diag=False):
+        """
+        Projector |n><n|
+
+        n -- state number, n <= self.n
+
+        """
+        p = np.zeros((self.n), float)
+        p[n] = 1.0
+        if diag:
+            return p
+        else:
+            return np.diag(p)
+
+
+    def S(self, n, m):
+        """
+        Symmetric operator |n><m| + |m><n|
+
+        n, m -- state number, n, m <= self.n
+
+        """
+        p = np.zeros((self.n, self.n), float)
+        p[n, m] = 1.0
+        p[m, n] = 1.0
+        return p
+
+
+    def Z(self, n, m):
+        """
+        Off-diagonal operator |n><m|
+
+        n, m -- state number, n, m <= self.n
+
+        """
+        p = np.zeros((self.n, self.n), float)
+        p[n, m] = 1.0
+        return p
+
+
+def _ONE(n, diag=False):
+    if diag:
+        return np.ones(n, float)
+    else:
+        return np.diag(np.ones(n, float))
+
+