Skip to main content

Qsimkit - Quantum Simulation Toolkit

License PyPI version Release

⚠️ Disclaimer: This package is still under active development. APIs may change, and features are being continuously improved. Use in production with caution.

A Python package for quantum simulation with error bounds and Trotterization tools. Built on Qiskit and OpenFermion.

Features

  • Hamiltonians: Spin lattice models (nearest-neighbor, power-law, IQP) and fermionic systems
  • Trotter Formulas: First, second, and high-order product formulas with JAX acceleration
  • Error Bounds: Analytical and numerical bounds for Trotter error analysis
  • States: Entangled states (GHZ, W) and random states
  • Channels: Quantum noise channels and transformations
  • Utilities: Binary search for optimal Trotter steps, plotting tools

Installation

From PyPI

pip install qsimkit

From source (for development)

git clone https://github.com/Jue-Xu/Qsimkit.git
cd Qsimkit
pip install -e .

Requirements

  • Python >= 3.10
  • Core: numpy, scipy, qiskit, matplotlib
  • Optional: jax/jaxlib (GPU acceleration), openfermion (fermionic systems)

Note: The package includes heavy dependencies (qiskit, openfermion). Installation may take a few minutes.

Quick Start

import qsimkit
from qsimkit.spin import Nearest_Neighbour_1d
from qsimkit.trotter import pf
from qsimkit.bounds import tight_bound

# Create a spin Hamiltonian
H = Nearest_Neighbour_1d(n=4, Jx=1.0, Jy=1.0, Jz=1.0, hx=0.5)
h_list = H.ham  # Get Hamiltonian terms

# Compute Trotter approximation
t = 1.0  # Evolution time
r = 100  # Number of Trotter steps
U_approx = pf(h_list, t, r, order=2)

# Estimate error bound
error = tight_bound(h_list, order=2, t=t, r=r, type='spectral')
print(f"Error bound: {error}")

Usage Examples

1. Hamiltonian Models

from qsimkit import spin, fermion

# Nearest-neighbor 1D spin chain
nn_chain = spin.Nearest_Neighbour_1d(
    n=10,           # 10 qubits
    Jx=1.0,         # X coupling
    Jy=1.0,         # Y coupling
    Jz=1.0,         # Z coupling
    hx=0.5,         # X field
    pbc=False       # Open boundary
)

# Get Hamiltonian in different groupings
h_parity = nn_chain.ham_par  # Parity grouping
h_xyz = nn_chain.ham_xyz      # XYZ grouping

# 2D lattice
lattice_2d = spin.Nearest_Neighbour_2d(nx=4, ny=4, Jx=1.0, Jy=1.0, Jz=1.0)

# Cluster Ising model
cluster = spin.Cluster_Ising(n=8, J=1.0, g=0.5)

2. Trotter Methods

from qsimkit.trotter import pf, pf_high

# First-order Trotter
U1 = pf(h_list, t=1.0, r=50, order=1)

# Second-order Trotter (symmetric)
U2 = pf(h_list, t=1.0, r=50, order=2)

# High-order Trotter (4th, 6th, 8th order)
U4 = pf_high(h_list, t=1.0, r=50, order=4)
U6 = pf_high(h_list, t=1.0, r=50, order=6)

# With JAX acceleration (if available)
U2_jax = pf(h_list, t=1.0, r=50, order=2, use_jax=True)

3. Error Bounds

from qsimkit.bounds import (
    tight_bound,
    analytic_bound,
    interference_bound,
    lc_tail_bound
)

# Tight commutator-based bound
error = tight_bound(h_list, order=2, t=1.0, r=100, type='spectral')

# Analytical bound
error_analytic = analytic_bound(H=h_list, k=1, t=1.0, r=100)

# Two-term interference bound (Layden 2022)
if len(h_list) == 2:
    bound, e1, e2, e3 = interference_bound(h_list, t=1.0, r=100)

4. Finding Optimal Trotter Steps

todo

Package Structure

qsimkit/
├── spin.py           # Spin Hamiltonian models
├── fermion.py        # Fermionic Hamiltonians
├── states.py         # Quantum states (GHZ, W, random)
├── trotter.py        # Trotter-Suzuki product formulas
├── bounds.py         # Error bound calculations
├── measure.py        # Operators (commutator, norm, etc.)
├── channel.py        # Quantum channels
├── utils.py          # Utility functions
└── plot_config.py    # Plotting configuration

Documentation

More examples and tutorials: https://jue-xu.github.io/cookbook-quantum-simulation

Citation

todo

Development

Running Tests

pytest tests/

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

Apache License 2.0 - see LICENSE file for details.

Contact

Metadata

Release files for qsimkit 0.1.15

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for qsimkit 0.1.15
File Size Uploaded Provenance Actions
qsimkit-0.1.15.tar.gz 969.1 kB Without provenance Details for qsimkit-0.1.15.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for qsimkit 0.1.15
File Interpreter ABI Platform Actions
qsimkit-0.1.15-py3-none-any.whl Python 3 none any Details for qsimkit-0.1.15-py3-none-any.whl

Total release size: 1.8 MB

Release files / qsimkit-0.1.15.tar.gz

Download URL qsimkit-0.1.15.tar.gz
Size 969.1 kB
Tags Source
SHA-256 checksum
How to use checksums
41f10119a4a1a8f3e2a71f25c3fbe2b554a87965c0349dd8ab16bda48368152f
BLAKE2b-256 checksum
How to use checksums
2ec72b3f188168fa75f749f064753dec57cea4b72e90f4df232428f6c93abf05
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.7

Release files / qsimkit-0.1.15-py3-none-any.whl

Download URL qsimkit-0.1.15-py3-none-any.whl
Size 844.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5974693761f2d543fb2984e4a5c35a18358caba323302547e8bfa709b4f6b04d
BLAKE2b-256 checksum
How to use checksums
e2ab34b77f834e85fea287560bfd9220df38104a2fe5ce574b1c26262681b1b6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.7

Security for qsimkit 0.1.15

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

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