Metadata-Version: 2.4
Name: ascent-science-sqa
Version: 0.2.0
Summary: Path-integral simulated quantum annealing for the Ascent Science SDK
Author: Ascent Science
License-Expression: LicenseRef-Proprietary
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: ascent-science<0.10,>=0.9.4

# Ascent Science SQA plugin

This package implements simulated quantum annealing (SQA) with the standard
Suzuki--Trotter path-integral mapping, single-spin Metropolis moves, and
optional imaginary-time world-line cluster updates. It is
a classical simulation of a transverse-field Ising model; it does not use a
quantum processor.

For development from this repository, install the core SDK and plugin in editable mode:

```bash
python -m pip install -e ./sdk-python -e ./sdk-plugins/sqa
```

Install the `0.2.0` release with
`python -m pip install ascent-science-sqa==0.2.0`.

```python
import ascent

solver = ascent.quantum.SimulatedQuantumAnnealing(
    trotter_slices=32,
    sweeps=500,
    beta=5.0,
    gamma_start=5.0,
    gamma_end=0.01,
    num_reads=8,
    update_mode="hybrid",
    seed=42,
)

# Minimize x.T Q x for x in {0, 1}^n.
result = solver.solve_qubo([
    [-2.0, 1.0],
    [1.0, -2.0],
])
print(result.best_solution, result.best_value)
```

For an Ising model, `solve_ising(J, fields=h)` minimizes
`s.T @ J @ s + h.T @ s + offset`, with spins in `{-1, +1}`. For a canonical
problem object use `solver.solve(QuboProblem(...))` or
`solver.solve(IsingProblem(...))`.

SQA is stochastic and does not prove optimality. Results therefore have status
`FEASIBLE` (or `TIME_LIMIT` if a supplied `SolveOptions` limit is reached).

`update_mode="hybrid"` combines local moves with Swendsen--Wang world-line
cluster moves. In addition to the monotone best-so-far `history`, metrics expose
instantaneous and mean replica energy, reduced effective action, magnetization,
slice alignment, per-sweep acceptance, and per-read best values. These traces
use Monte Carlo sweeps, not real quantum-hardware time.

## Build a release

Use the same release flow as the ACO plugin:

```bash
sh scripts/build-release.sh
```

The wheel, source archive, and `SHA256SUMS` are written to `dist/`. If the
default Python does not provide a recent setuptools/build installation, select
another interpreter with `ASCENT_SQA_BUILD_PYTHON=/path/to/python`.
