Metadata-Version: 2.4
Name: qsimkit
Version: 0.1.14
Summary: Quantum Simulation Toolkit - Error bounds and Trotterization tools
Author-email: Jue XU <xujue@connect.hku.hk>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Jue-Xu/Qsimkit
Project-URL: Repository, https://github.com/Jue-Xu/Qsimkit
Project-URL: Documentation, https://jue-xu.github.io/cookbook-quantum-simulation
Classifier: Programming Language :: Python :: 3
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: qiskit>=1.0.2
Requires-Dist: qiskit-aer>=0.17.2
Requires-Dist: jaxlib>=0.6.2
Requires-Dist: jax>=0.6.2
Requires-Dist: openfermion>=1.5.1
Requires-Dist: openfermionpyscf>=0.5
Requires-Dist: matplotlib>=3.8.2
Requires-Dist: numpy>=1.23.5
Requires-Dist: pandas>=2.2.2
Requires-Dist: scipy>=1.12.0
Requires-Dist: colorspace>=1.0.0
Requires-Dist: multiprocess>=0.70.16
Dynamic: license-file

# Qsimkit - Quantum Simulation Toolkit

[![License](https://img.shields.io/github/license/Jue-Xu/Qsimkit.svg?style=popout-square)](https://opensource.org/licenses/Apache-2.0)
[![PyPI version](https://badge.fury.io/py/qsimkit.svg)](https://badge.fury.io/py/qsimkit)
[![Release](https://img.shields.io/github/v/release/jue-xu/Qsimkit?include_prereleases)](https://github.com/Jue-Xu/Qsimkit/releases)

> **⚠️ 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](https://www.ibm.com/quantum/qiskit) and [OpenFermion](https://github.com/quantumlib/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
```bash
pip install qsimkit
```

### From source (for development)
```bash
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

```python
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

```python
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

```python
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

```python
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](https://jue-xu.github.io/cookbook-quantum-simulation)

## Citation
todo


## Development

### Running Tests
```bash
pytest tests/
```

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

## License

Apache License 2.0 - see [LICENSE](LICENSE) file for details.

## Contact

- Author: Jue Xu
- Email: xujue@connect.hku.hk
- GitHub: [@Jue-Xu](https://github.com/Jue-Xu)
