PyTDSCF

PyTDSCF is a Python package for high-dimensional wave-packet dynamics simulations based on tensor train.

Features

Multiple MPO Types for Hamiltonian Representation

You can use various types of Matrix Product Operators (MPO) as Hamiltonians:

• Symbolic MPO

  $$\sum_{i=1}^{k} \frac{\hat{Q}_i^2}{2} \Rightarrow\left[\begin{array}{cc} 1 & \frac{\hat{Q}_1^2}{2} \end{array}\right]\left[\begin{array}{cc} 1 & \frac{\hat{Q}_2^2}{2} \\\ 0 & 1 \end{array}\right] \ldots\left[\begin{array}{cc} 1 & \frac{\hat{Q}_{k-1}^2}{2} \\\ 0 & 1 \end{array}\right]\left[\begin{array}{l} \frac{\hat{Q}_k^2}{2} \\\ 1 \end{array}\right]$$

• Grid-based MPO

  $$\hat{T} + \sum_{i} V_{i} + \sum_{i< j} V_{ij} + \sum_{i< j< k} V_{ijk} + \cdots$$

• Neural network MPO

  $$\underset{\{W\}}{\mathrm{argmin}} \sum_{\left\{n_i\right\}, E \in \mathcal{D}}\left|W_{n_1}^{n_1^{\prime}} W_{n_2}^{n_2^{\prime}} \cdots W_{n_k}^{n_k^{\prime}}-E_{n_1 n_2 \cdots n_k}^{n_1^{\prime} n_2^{\prime} \cdots n_k^{\prime}}\right|$$

Flexible Basis Sets

Support for various basis types:

• Boson states $|n\rangle$
• DVR grid states $|x\rangle$
• Spin states $|s\rangle$
• Exciton states $|e\rangle$
• ... (whatever)

Simulation Capabilities

PyTDSCF enables large-dimensional system simulations for:

• Vibrational ground state calculations
• Autocorrelation functions
• IR spectroscopy
• Nonadiabatic population dynamics
• Time-dependent expectation values
• Non-Markovian open quantum dynamics
• Reduced density matrix analysis
• Liouville space dissipation
• And more...

Performance Features

• GPU acceleration through JAX for large-scale calculations
• Parallel execution for ab initio potential energy surface calculations

Documentation

Comprehensive documentation is available here!

References

• Kurashige, Yuki. "Matrix product state formulation of the multiconfiguration time-dependent Hartree theory." The Journal of Chemical Physics 149.19 (2018): 194114.

  • Time evolution algorithm of MPS
  • Population dynamics

• Hino, Kentaro, and Yuki Kurashige. "Matrix Product State Formulation of the MCTDH Theory in Local Mode Representations for Anharmonic Potentials." Journal of Chemical Theory and Computation 18.6 (2022): 3347-3356.

  • Spectroscopy
  • Anharmonic potential
  • Local mode vibration

• Hino, Kentaro, and Yuki Kurashige. "Encoding a Many-body Potential Energy Surface into a Grid-Based Matrix Product Operator." Journal of Chemical Theory and Computation 20.9 (2024): 3839-3849.)

  • Grid-based MPO
  • DVR-MPS
  • nMR

• Hino, Kentaro, and Yuki Kurashige. "Neural network matrix product operator: A multi-dimensionally integrable machine learning potential." Physical Review Research 7.2 (2025): 023217.

  • Neural network MPO

• Hino, Kentaro, et al. "Introduction to modeling radical pair quantum spin dynamics with tensor networks." The Journal of Chemical Physics 164.8 (2026).

  • Liouville space (MPDO) / LPTN / Monte Carlo wavefunction
  • Spin basis
  • Radical pair
  • Benchmarking for bond dimension > 1000

Installation

Recommended: Install from Source using uv

We recommend installing pytdscf from source using uv:

$ git clone https://github.com/QCLovers/PyTDSCF.git
$ cd PyTDSCF
$ uv version
uv 0.5.4 (c62c83c37 2024-11-20)
$ uv sync --all-extras

This will install all dependencies including development tools. If you only need runtime dependencies, use uv sync --no-dev.

You can then run pytdscf using:

$ uv run python xxx.py

Or activate the virtual environment:

$ source .venv/bin/activate
$ python
>>> import pytdscf

For Jupyter notebook tutorials:

$ uv run jupyter lab

Alternative: Install via pip

The easiest way to install pytdscf is using pip:

Prepare Python 3.10 or later and execute:

$ python -m venv pytdscf-env
$ source pytdscf-env/bin/activate
$ pip install git+https://github.com/QCLovers/PyTDSCF

GPU Support

pytdscf works on both CPU and GPU. For large-scale batch processing or complex models, we recommend using GPU. See also JAX's GPU support.

1. Ensure the latest NVIDIA driver is installed:

   $ /usr/local/cuda/bin/nvcc -V
   nvcc: NVIDIA (R) Cuda compiler driver
   Copyright (c) 2005-2024 NVIDIA Corporation
   Built on Wed_Apr_17_19:19:55_PDT_2024
   Cuda compilation tools, release 12.5, V12.5.40
   Build cuda_12.5.r12.5/compiler.34177558_0

2. Install GPU-supported JAX in your virtual environment:

   $ uv pip install -U "jax[cuda13]"
   $ uv run python -c "import jax; print(jax.default_backend())"
   'gpu'

Testing

$ cd tests/build
$ uv run pytest ..

Development

We welcome feedback and pull requests. For developers, install pre-commit hooks including ruff formatting and linting, mypy type checking, pytest testing, and more:

$ uv run pre-commit install
$ git add .
$ uv run pre-commit

Important: Fix any issues before pushing!

We welcome feedback and pull requests.

Getting Started

See the quick-start example in our documentation or explore the test directory for examples.