Skip to main content

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.

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.6.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.6-cp312-abi3-win_amd64.whl (2.7 MB view details)

Uploaded CPython 3.12+Windows x86-64

qkrylov-0.0.6-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.6-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.6-cp312-abi3-macosx_14_0_arm64.whl (2.1 MB view details)

Uploaded CPython 3.12+macOS 14.0+ ARM64

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

Uploaded CPython 3.11Windows x86-64

qkrylov-0.0.6-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.6-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.6-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.6.tar.gz.

File metadata

  • Download URL: qkrylov-0.0.6.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.6.tar.gz
Algorithm Hash digest
SHA256 70c0c12a64fbcd15008ea174813e3e1bd08bf59158daf75fb26390da2b0e2a94
MD5 fae93fc691cce0e0d0135281695720e6
BLAKE2b-256 5ca3ceae1efd2b42902634ee1e06cf0f5d00324c30d00f6f1b528e755bcef935

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: qkrylov-0.0.6-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.6-cp312-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 4d6286ce836b194d0ddb53134677c9b17215236d735f627b63383a380cc048f8
MD5 417f7be2daec46d872aa5fee6cdc7cfe
BLAKE2b-256 cf0411ef5c3c5a694c005dff37ec8a1ef7299f06e09e474c560b4b75fc127124

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for qkrylov-0.0.6-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 e0d6e4ec1f53dcbd7013bd030bf050acc9093f78c8cd675014b227c99f4e50e6
MD5 7d085f6dbcaa3cb08c7a0a9ecdd57bce
BLAKE2b-256 793b2e230ec46cf324a56346144ae03627804f9eb7eeeaa193fc3568ea5b04e3

See more details on using hashes here.

Provenance

The following attestation bundles were made for qkrylov-0.0.6-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.6-cp312-abi3-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for qkrylov-0.0.6-cp312-abi3-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 044f10b2c4130ac9be898d3365d7aacc03a12d3e8c8665f9d12e170d13c5bebf
MD5 c0518ba873972de6ce78645270ed7a58
BLAKE2b-256 4ab14169723106a430c2a754f902a8a166b39cced8796b55f43131e6bb224545

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for qkrylov-0.0.6-cp312-abi3-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 ad3336336e9a3950e0435f893bfd34d7832d3a6dc3c1ba2aa40824981bdfbf34
MD5 a8dcb23c579ea4d5a47aaf6bde449592
BLAKE2b-256 e365cc1a81a95ecb98e6b3ab6de2787a7dc92e45cfb82685894d0f0749fb9155

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: qkrylov-0.0.6-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.6-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 13e909ab95f239d4ec6a76a9caf7af6ebff5f5583f53031b2bd1b66bf91bc07f
MD5 1f711117d9317f276babef19b08b1890
BLAKE2b-256 02344750d1ee2f18ca5318bd18eb01001f5e9b3550c8e8cfed7529feb4f209d8

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for qkrylov-0.0.6-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 c2c0e0eb84e6298b91a7789713be95a12382dd7c0660c2eb038b2e5b1d1930ba
MD5 06d05cba41a43474e648d7ad45a66dc8
BLAKE2b-256 c4cc26e3c8551c367ca962a06755d9aa7d2058dbc93bea620e7b472f48a99ffa

See more details on using hashes here.

Provenance

The following attestation bundles were made for qkrylov-0.0.6-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.6-cp311-cp311-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for qkrylov-0.0.6-cp311-cp311-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 bfa22fc087651ea2808f2527d0ca3ef605b996966b3d57c8ef73fcba2836fd83
MD5 653120c416ec0e43045655c97aa1782d
BLAKE2b-256 938269010cf58bc3bf4d2fb8b36e011cf02eb6d0cc3dd9584d95a8623954a59c

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for qkrylov-0.0.6-cp311-cp311-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 260b19b7e7ffcd02b8dbc7479fdb4661da87192c55495673dca298b7e8e4e043
MD5 ce52a7b54763563631b49902857fc770
BLAKE2b-256 bf171cf946d232304f474215af63e04d84430b0b0b9a7dd87ced578f777f0fab

See more details on using hashes here.

Provenance

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

This release

0.0.6 This release

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