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 8, 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:
Newer release available (0.0.7)

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 8, 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

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.5.tar.gz (68.4 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.5-cp312-abi3-win_amd64.whl (412.8 kB view details)

Uploaded CPython 3.12+Windows x86-64

qkrylov-0.0.5-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (256.5 kB view details)

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

qkrylov-0.0.5-cp312-abi3-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl (242.0 kB view details)

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

qkrylov-0.0.5-cp312-abi3-macosx_14_0_arm64.whl (366.8 kB view details)

Uploaded CPython 3.12+macOS 14.0+ ARM64

qkrylov-0.0.5-cp311-cp311-win_amd64.whl (415.0 kB view details)

Uploaded CPython 3.11Windows x86-64

qkrylov-0.0.5-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (260.3 kB view details)

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

qkrylov-0.0.5-cp311-cp311-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl (245.7 kB view details)

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

qkrylov-0.0.5-cp311-cp311-macosx_14_0_arm64.whl (369.0 kB view details)

Uploaded CPython 3.11macOS 14.0+ ARM64

File details

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

File metadata

  • Download URL: qkrylov-0.0.5.tar.gz
  • Upload date:
  • Size: 68.4 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.5.tar.gz
Algorithm Hash digest
SHA256 f41c4453e805cc6c237e6cb7a15cdf920c6923909b0377d5206b54f7c378ccd8
MD5 c6893f66c576d4fb25b2f0dc28a94e1e
BLAKE2b-256 f0d9103b7a5e0cfd06ed232dd20702b8d66a35a3904ecad8c12d1248190643e6

See more details on using hashes here.

Provenance

The following attestation bundles were made for qkrylov-0.0.5.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.5-cp312-abi3-win_amd64.whl.

File metadata

  • Download URL: qkrylov-0.0.5-cp312-abi3-win_amd64.whl
  • Upload date:
  • Size: 412.8 kB
  • 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.5-cp312-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 2deed9f2e60bcc1a6e8d6f88c86f207b9913b1dda15b2bca284b30a06c055e17
MD5 5fc6bbca68c748d2fe2dfb59ef3cd75f
BLAKE2b-256 50f5a6e2da47862a2fbbf3eb4e0d8b042e0e05985166fa21eca6587d5d6f9359

See more details on using hashes here.

Provenance

The following attestation bundles were made for qkrylov-0.0.5-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.5-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for qkrylov-0.0.5-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 f529f088aee5a47eac140c4e0f4c2768c8b53f11dbaf1bf34d2c3b1ec9c9d76d
MD5 9922f0bb6417e341dd18e187914dc465
BLAKE2b-256 9fa06092d7f95d5ce2b63b3a7264ba15a3c316169182e8d210b489fb09ad3d6b

See more details on using hashes here.

Provenance

The following attestation bundles were made for qkrylov-0.0.5-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.5-cp312-abi3-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for qkrylov-0.0.5-cp312-abi3-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 29bb91dd616efe0fc3b0cc794c42c1481366daefb421c47337305fe4875b1a8a
MD5 c1b191ba12e48e1bb93e7c11d709bae7
BLAKE2b-256 67731aa4c7d817ce3cacc96dd6c94ffac487c89433d72e4275aa0e0cec426b74

See more details on using hashes here.

Provenance

The following attestation bundles were made for qkrylov-0.0.5-cp312-abi3-manylinux_2_26_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.5-cp312-abi3-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for qkrylov-0.0.5-cp312-abi3-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 836797430bdd959aafe1633328d520c6c4c9074292b4d9abd542e59955818ac8
MD5 5b78a8ec8525c3b49ac71601239a4046
BLAKE2b-256 c3b37385a6ca0bdf6c05f76e858b575af5ba417e1ffa41eaf8daa8fce83374d4

See more details on using hashes here.

Provenance

The following attestation bundles were made for qkrylov-0.0.5-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.5-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: qkrylov-0.0.5-cp311-cp311-win_amd64.whl
  • Upload date:
  • Size: 415.0 kB
  • 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.5-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 b0ea9122b88357ac49ccda44486aab0fab60dcb38fe7be311d14a72424d06a94
MD5 1de54717eda4b0d69eae3af610987601
BLAKE2b-256 c0e732f2ff88acec8f294578856206804e3ea4261d38163a834c91bf6a1108ce

See more details on using hashes here.

Provenance

The following attestation bundles were made for qkrylov-0.0.5-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.5-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for qkrylov-0.0.5-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 870c2fb806a3cc2a07b978ad3dcbe956a449f651cc1e90fb04d6fbcd19f6f535
MD5 6e40e44b3502bb7d37975080677f2b8b
BLAKE2b-256 a33875aca634bcdc929f809db84bc0569722f65c1550cb2eed29f5b1a0302875

See more details on using hashes here.

Provenance

The following attestation bundles were made for qkrylov-0.0.5-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.5-cp311-cp311-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for qkrylov-0.0.5-cp311-cp311-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 4a9f7b489ceefca68999c5e54c3492db4bcf10c60f97376ad21d92da70dfa679
MD5 10e86837afaa514a4dcb2010fd398efa
BLAKE2b-256 5bd1c708aef4448a02f5e45f42f5582be6335c5420f0f574eef4a439809e5453

See more details on using hashes here.

Provenance

The following attestation bundles were made for qkrylov-0.0.5-cp311-cp311-manylinux_2_26_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.5-cp311-cp311-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for qkrylov-0.0.5-cp311-cp311-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 e99cda5eb1d7bb32fea7f54b68633d582cb88ed6772c7850ec3980113955bc3d
MD5 1f8b06450613105dd0e5ad0cc52043b1
BLAKE2b-256 2b6ee0d03ae9ba05ca2b64ce49736bcdd6ce46853cc517493a2f06fc3efa1117

See more details on using hashes here.

Provenance

The following attestation bundles were made for qkrylov-0.0.5-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

0.0.7

9 files

0.0.6

9 files

This release

0.0.5 This release

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