qkrylov

A modern C++20 framework for matrix-free Krylov methods in quantum many-body physics.

Overview

qkrylov provides a high-performance core for performing exact diagonalization and Krylov-based calculations (like Lanczos and Davidson) without explicitly constructing Hamiltonian matrices. By implementing the matrix-free action $y = Hx$, the library enables the study of much larger Hilbert spaces than traditional matrix-based methods.

Features Completed

  • C++20 Core: Leveraging modern C++ features for performance and safety.
  • Basis Abstraction: Generic basis management with support for symmetry sectors.
  • Supported Models:
    • Spin-Half Systems: Heisenberg, transverse-field Ising, etc.
    • Fermionic Systems: Spinless fermions with Jordan-Wigner phases.
    • Hubbard Models: Interacting electrons with spin conservation.
    • t-J Models: Doped antiferromagnets with no-double-occupancy constraint.
  • Matrix-Free Hamiltonian: Efficient application of operator sums (OpSum) to state vectors.
  • Advanced Solvers:
    • Lanczos: Accurate ground-state energy and Ritz vector calculation.
    • Davidson: Iterative solver for the lowest few eigenpairs.
    • Dynamics: Continued Fraction Lanczos for dynamical structure factor $S(\omega)$ calculations.
  • Multi-Language Scaffolding: Robust Python interface via nanobind.

Build Requirements

  • C++20 compatible compiler (e.g., GCC 11+, Clang 13+, MSVC 19.30+)
  • CMake 3.20+
  • nanobind (install via pip install nanobind)

Quick Start

Build the library and tests

make build

Install Python package

pip install ./bindings/python

Run tests

make test
pytest bindings/python/tests/test_basic.py

C++ Example

#include <qkrylov/basis/spinhalf_basis.hpp>
#include <qkrylov/operators/opsum.hpp>
#include <qkrylov/sites/spinhalf_site.hpp>
#include <qkrylov/hamiltonian/matrix_free_hamiltonian.hpp>
#include <qkrylov/solvers/lanczos.hpp>
#include <iostream>

using namespace qkrylov;

int main() {
    int N = 4;
    auto basis = std::make_shared<SpinHalfBasis>(N);
    auto site = std::make_shared<SpinHalfSite>();

    OpSum os;
    for (int i = 0; i < N - 1; ++i) {
        // Heisenberg interaction: Sz_i Sz_{i+1} + 0.5(Sp_i Sm_{i+1} + Sm_i Sp_{i+1})
        os += {1.0, {{"Sz", i}, {"Sz", i+1}}};
        os += {0.5, {{"Sp", i}, {"Sm", i+1}}};
        os += {0.5, {{"Sm", i}, {"Sp", i+1}}};
    }

    MatrixFreeHamiltonian H(basis, site, os);
    auto result = lanczos_ground_state(H);

    std::cout << "Ground state energy: " << result.energy << std::endl;
    return 0;
}

Python Example

import qkrylov

# 4-site Heisenberg chain
N = 4
basis = qkrylov.SpinHalfBasis(N)
site = qkrylov.SpinHalfSite()

os = qkrylov.OpSum()
for i in range(N - 1):
    # Heisenberg interaction: Sz_i Sz_{i+1} + 0.5(Sp_i Sm_{i+1} + Sm_i Sp_{i+1})
    os += 1.0, "Sz", i, "Sz", i+1
    os += 0.5, "Sp", i, "Sm", i+1
    os += 0.5, "Sm", i, "Sp", i+1

H = qkrylov.MatrixFreeHamiltonian(basis, site, os)
result = qkrylov.lanczos_ground_state(H)

print(f"Ground state energy: {result.energy}")

Things To Be Done (Roadmap)

  • GPU Acceleration: CUDA/HIP support for Hamiltonian application.
  • HDF5 Integration: Efficient storage of large eigenvectors and results.
  • Julia Bindings: Interop via CxxWrap.jl.
  • Finite Temperature: Finite Temperature Lanczos Method (FTLM).

Documentation

Full documentation is available in the docs/ directory. See docs/source/tutorial.md for a comprehensive guide modeled after iTensor.

Project links

Data verified by PyPI on Aug 12, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

2 maintainers

PyPI data
Data sourced directly from PyPI's database.
Avatar for PeithonKing from gravatar.com PeithonKing Avatar for sjp95 from gravatar.com sjp95

Credits

Author: Subhajyoti Pal, Aritra Mukhopadhyay, Pritipriya Dasbehera

GitHub Statistics

Data verified by PyPI on Aug 12, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python >=3.11

Provides Extra

test cuda

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

qkrylov-0.0.7.tar.gz (77.3 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

qkrylov-0.0.7-cp312-abi3-win_amd64.whl (2.7 MB view details)

Uploaded CPython 3.12+Windows x86-64

qkrylov-0.0.7-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (2.2 MB view details)

Uploaded CPython 3.12+manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

qkrylov-0.0.7-cp312-abi3-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl (2.1 MB view details)

Uploaded CPython 3.12+manylinux: glibc 2.27+ ARM64manylinux: glibc 2.28+ ARM64

qkrylov-0.0.7-cp312-abi3-macosx_14_0_arm64.whl (2.1 MB view details)

Uploaded CPython 3.12+macOS 14.0+ ARM64

qkrylov-0.0.7-cp311-cp311-win_amd64.whl (2.7 MB view details)

Uploaded CPython 3.11Windows x86-64

qkrylov-0.0.7-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (2.2 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

qkrylov-0.0.7-cp311-cp311-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl (2.1 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.27+ ARM64manylinux: glibc 2.28+ ARM64

qkrylov-0.0.7-cp311-cp311-macosx_14_0_arm64.whl (2.1 MB view details)

Uploaded CPython 3.11macOS 14.0+ ARM64

File details

Details for the file qkrylov-0.0.7.tar.gz.

File metadata

  • Download URL: qkrylov-0.0.7.tar.gz
  • Upload date:
  • Size: 77.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for qkrylov-0.0.7.tar.gz
Algorithm Hash digest
SHA256 dcfaf0d5c9ce771599e6b72486eb07937c16e208615d529247ac3ebbf80e9977
MD5 7430dca529c5b5d8cc9a89c060a2ecad
BLAKE2b-256 34f436554e3cb2a8528f05958ebc5420004897e6c535a1151697edd9ca0debd8

See more details on using hashes here.

Provenance

The following attestation bundles were made for qkrylov-0.0.7.tar.gz:

Publisher: pypi_publish.yaml on sjp95/qkrylov

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file qkrylov-0.0.7-cp312-abi3-win_amd64.whl.

File metadata

  • Download URL: qkrylov-0.0.7-cp312-abi3-win_amd64.whl
  • Upload date:
  • Size: 2.7 MB
  • Tags: CPython 3.12+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for qkrylov-0.0.7-cp312-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 fe46cb1493f31f83ef6794de5ac75e865a8231cef79cf51f9fbd2ac30bee7419
MD5 a2eccc98ff12067e622389078c43a7e6
BLAKE2b-256 911fd285225a2d9a69df1fc4d840117cd09ca104e9b820d7228b20293e037d4f

See more details on using hashes here.

Provenance

The following attestation bundles were made for qkrylov-0.0.7-cp312-abi3-win_amd64.whl:

Publisher: pypi_publish.yaml on sjp95/qkrylov

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file qkrylov-0.0.7-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for qkrylov-0.0.7-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 f47496d03a5a58789889c26554e3128f647630102ef17b34723cc11784e48660
MD5 bc999993221d140b0929b10061873bc0
BLAKE2b-256 ac58534971b7e8f876eba584a1c60e8ef7af67591fefd9a3290bd59246d68b62

See more details on using hashes here.

Provenance

The following attestation bundles were made for qkrylov-0.0.7-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: pypi_publish.yaml on sjp95/qkrylov

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file qkrylov-0.0.7-cp312-abi3-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for qkrylov-0.0.7-cp312-abi3-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 75dc6016f26d67408c472cbb3313eaf9027543a9a9f3a94678e9ffad591401d5
MD5 79bcef14e80d775b245cda65d1c3dcb0
BLAKE2b-256 8f03e483493c9436ad5a78346a7e5e8236a0b7a990e9ce118e72e0ffebf7103a

See more details on using hashes here.

Provenance

The following attestation bundles were made for qkrylov-0.0.7-cp312-abi3-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl:

Publisher: pypi_publish.yaml on sjp95/qkrylov

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file qkrylov-0.0.7-cp312-abi3-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for qkrylov-0.0.7-cp312-abi3-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 b3a07ae9a832821d2416db84b373da573f7d888adff396c5de6641ec2fe6442b
MD5 bb03c06292ec008d55bdb0ee7d7ffacb
BLAKE2b-256 3422c4c750ae391ccf1848856d0640231d189e45a3e2a33acbe694402ff01819

See more details on using hashes here.

Provenance

The following attestation bundles were made for qkrylov-0.0.7-cp312-abi3-macosx_14_0_arm64.whl:

Publisher: pypi_publish.yaml on sjp95/qkrylov

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file qkrylov-0.0.7-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: qkrylov-0.0.7-cp311-cp311-win_amd64.whl
  • Upload date:
  • Size: 2.7 MB
  • Tags: CPython 3.11, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for qkrylov-0.0.7-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 93b4219afe7777ce9365ac172823a4c81200c275bd857739b5efcff55ef73ec3
MD5 336170d4d8ea0471d6ec7b68bc0aa847
BLAKE2b-256 8e8b55a22d9402b7c4ea403df98c5d8d7fe178ff1205c01f72a223cb62c69aa2

See more details on using hashes here.

Provenance

The following attestation bundles were made for qkrylov-0.0.7-cp311-cp311-win_amd64.whl:

Publisher: pypi_publish.yaml on sjp95/qkrylov

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file qkrylov-0.0.7-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for qkrylov-0.0.7-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 194bf40ccc019ab01ab5ef4c09f72a92eced57940317ed02733f9a454a3228f5
MD5 7dcc92abf98a38e61012aedb0a7e21b2
BLAKE2b-256 ae9c25626a45f013ef66101f85190350f1bfd1f1b0c858c367c72e3481190a2a

See more details on using hashes here.

Provenance

The following attestation bundles were made for qkrylov-0.0.7-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: pypi_publish.yaml on sjp95/qkrylov

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file qkrylov-0.0.7-cp311-cp311-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for qkrylov-0.0.7-cp311-cp311-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 6c196c86fc9c3dc9ad2cd037c46e1024b7e0559097a84add52284efb50790ab1
MD5 3cee538aee21ddd5a995895989a72e71
BLAKE2b-256 66700107d01fb3993853dbcb3686cfcbe0ab838a5e448ac7b11b1d56c94ab846

See more details on using hashes here.

Provenance

The following attestation bundles were made for qkrylov-0.0.7-cp311-cp311-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl:

Publisher: pypi_publish.yaml on sjp95/qkrylov

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file qkrylov-0.0.7-cp311-cp311-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for qkrylov-0.0.7-cp311-cp311-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 ec7ffd88911fa64baf79d63090e87118378940bdbad4457a0da5dc121ae63776
MD5 b7a001aeae99cf616f023539f118be6b
BLAKE2b-256 86cb0255cc7621806e4752908707b7b954f6c86532e3c13832ab5599517ac603

See more details on using hashes here.

Provenance

The following attestation bundles were made for qkrylov-0.0.7-cp311-cp311-macosx_14_0_arm64.whl:

Publisher: pypi_publish.yaml on sjp95/qkrylov

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.0.7 This release

9 files

0.0.6

9 files

0.0.5

9 files

0.0.4

9 files

0.0.3

8 files

0.0.0

8 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page