Metadata-Version: 2.4
Name: qutip-sampler
Version: 0.1.1
Summary: Quantum annealing sampler using QuTiP sesolve
Project-URL: Source Code, https://github.com/shunta0213/qutip-sampler
Project-URL: Bug Tracker, https://github.com/shunta0213/qutip-sampler/issues
Author-email: shunta0213 <contact@sprshunt.com>
License: MIT
Keywords: dimod,ising,optimization,quantum annealing,quantum computing,qubo,qutip
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.13
Requires-Dist: dimod>=0.12.21
Requires-Dist: numpy>=2.4.3
Requires-Dist: qutip>=5.2.3
Description-Content-Type: text/markdown

# qutip-sampler

A [dimod](https://github.com/dwavesystems/dimod)-compatible quantum annealing sampler backed by [QuTiP](https://qutip.org/) `sesolve`.

It maps an Ising / QUBO problem onto a transverse-field Ising Hamiltonian, evolves the ground state via a linear annealing schedule, and draws bitstring samples from the final quantum state.

## Installation

```bash
pip install qutip-sampler
```

## Quick start

```python
import dimod
from qutip_sampler import QuTipSampler

# SPIN (Ising) problem
bqm = dimod.BinaryQuadraticModel({'a': -1.0, 'b': -1.0}, {('a', 'b'): 0.5}, 0.0, 'SPIN')
result = QuTipSampler().sample(bqm, num_reads=100, seed=42)
print(result.first.sample)   # e.g. {'a': 1, 'b': 1}

# Ising directly
result = QuTipSampler().sample_ising({'a': -1.0}, {('a', 'b'): 0.5}, num_reads=50)

# QUBO
Q = {('x', 'x'): -1.0, ('y', 'y'): -1.0, ('x', 'y'): 0.5}
result = QuTipSampler().sample_qubo(Q, num_reads=50, seed=0)
print(result.first.sample)   # e.g. {'x': 1, 'y': 1}
```

## Parameters

| Parameter | Default | Description |
|-----------|---------|-------------|
| `anneal_time` | `10.0` | Total annealing time *T* passed to `sesolve` |
| `n_steps` | `200` | Number of time steps in the annealing schedule |
| `num_reads` | `100` | Number of bitstring samples drawn from the final state |
| `seed` | `None` | RNG seed for reproducible sampling |

`anneal_time` and `n_steps` can be set at construction time or overridden per call.

## How it works

1. Collect all variables from the problem and sort them.
2. Build the Ising Hamiltonian `H_ising = Σ hᵢ σᵢᶻ + Σ Jᵢⱼ σᵢᶻ σⱼᶻ`.
3. Build the transverse-field Hamiltonian `H_T = −Σ σᵢˣ`, whose ground state is `|+⟩⊗ⁿ`.
4. Evolve `H(t) = (1 − t/T) H_T + (t/T) H_ising` from `t=0` to `t=T` using QuTiP `sesolve`.
5. Sample bitstrings from the probability distribution `|ψ(T)|²`.

## License

MIT
