ascent-science-sqa 0.1.0__tar.gz

ascent_science_sqa-0.1.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: ascent-science-sqa
+Version: 0.1.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 and single-spin Metropolis 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
+```
+
+After the `0.1.0` package is published, it can instead be installed with
+`python -m pip install ascent-science-sqa==0.1.0`.
+
+```python
+import ascent
+
+solver = ascent.quantum.SimulatedQuantumAnnealing(
+    trotter_slices=32,
+    sweeps=500,
+    beta=5.0,
+    gamma_start=5.0,
+    gamma_end=0.01,
+    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).
+
+## 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`.

ascent_science_sqa-0.1.0/README.md

@@ -0,0 +1,55 @@
+# Ascent Science SQA plugin
+
+This package implements simulated quantum annealing (SQA) with the standard
+Suzuki--Trotter path-integral mapping and single-spin Metropolis 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
+```
+
+After the `0.1.0` package is published, it can instead be installed with
+`python -m pip install ascent-science-sqa==0.1.0`.
+
+```python
+import ascent
+
+solver = ascent.quantum.SimulatedQuantumAnnealing(
+    trotter_slices=32,
+    sweeps=500,
+    beta=5.0,
+    gamma_start=5.0,
+    gamma_end=0.01,
+    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).
+
+## 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`.

ascent_science_sqa-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ascent-science-sqa"
+version = "0.1.0"
+description = "Path-integral simulated quantum annealing for the Ascent Science SDK"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "LicenseRef-Proprietary"
+dependencies = ["ascent-science>=0.9.4,<0.10"]
+authors = [{name = "Ascent Science"}]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Typing :: Typed",
+]
+
+[project.entry-points."ascent.algorithms"]
+sqa = "ascent_science_sqa:register"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["ascent_science_sqa*"]

ascent_science_sqa-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ascent_science_sqa-0.1.0/src/ascent_science_sqa/__init__.py

@@ -0,0 +1,293 @@
+"""Suzuki--Trotter path-integral simulated quantum annealing.
+
+This is a classical Monte Carlo simulation of a transverse-field Ising model.
+It does not submit work to quantum hardware.
+"""
+
+from __future__ import annotations
+
+import math
+import random
+import time
+
+from ascent.core import (
+    AlgorithmSpec,
+    ExecutionInfo,
+    IsingProblem,
+    QuboProblem,
+    SolveOptions,
+    SolveResult,
+    SolveStatus,
+    SolverIdentity,
+    qubo_to_ising,
+    symmetrize,
+)
+from ascent.plugin_api import register_algorithm, validated_license
+from ascent.usage import tracked_call
+
+__version__ = "0.1.0"
+
+
+def _finite_vector(values, size, name):
+    try:
+        vector = [float(value) for value in values]
+    except (TypeError, ValueError) as error:
+        raise ValueError(f"{name} must contain finite numbers") from error
+    if len(vector) != size or any(not math.isfinite(value) for value in vector):
+        raise ValueError(f"{name} must contain one finite value per variable")
+    return vector
+
+
+class SimulatedQuantumAnnealing:
+    """Minimize Ising or QUBO energy using standard path-integral SQA.
+
+    ``trotter_slices`` controls the Suzuki--Trotter discretization. ``beta`` is
+    the inverse physical temperature and ``gamma_start``/``gamma_end`` define
+    the transverse-field schedule. A result is heuristic and is therefore
+    reported as ``FEASIBLE``, never as a certified optimum.
+    """
+
+    def __init__(
+        self,
+        *,
+        trotter_slices=16,
+        sweeps=200,
+        beta=5.0,
+        gamma_start=5.0,
+        gamma_end=0.01,
+        schedule="geometric",
+        seed=None,
+        user_id=None,
+        sdk_code=None,
+        endpoint=None,
+        license_path=None,
+        timeout=30.0,
+        report_usage=True,
+        validation_mode="cached",
+        **unused,
+    ):
+        if unused:
+            raise TypeError("unsupported SQA parameters: %s" % ", ".join(sorted(unused)))
+        self.trotter_slices = int(trotter_slices)
+        self.sweeps = int(sweeps)
+        self.beta = float(beta)
+        self.gamma_start = float(gamma_start)
+        self.gamma_end = float(gamma_end)
+        self.schedule = str(schedule).lower()
+        self.seed = seed
+        self._validate_parameters()
+        self.endpoint, self.license_user_id, self._usage_reporter = validated_license(
+            endpoint, user_id, sdk_code, license_path, timeout, report_usage, validation_mode
+        )
+
+    def _validate_parameters(self):
+        if self.trotter_slices < 2:
+            raise ValueError("trotter_slices must be at least 2")
+        if self.sweeps < 1:
+            raise ValueError("sweeps must be a positive integer")
+        if not math.isfinite(self.beta) or self.beta <= 0:
+            raise ValueError("beta must be a finite positive number")
+        if not math.isfinite(self.gamma_start) or self.gamma_start <= 0:
+            raise ValueError("gamma_start must be a finite positive number")
+        if not math.isfinite(self.gamma_end) or self.gamma_end <= 0:
+            raise ValueError("gamma_end must be a finite positive number")
+        if self.gamma_start < self.gamma_end:
+            raise ValueError("gamma_start must be greater than or equal to gamma_end")
+        if self.schedule not in {"linear", "geometric"}:
+            raise ValueError("schedule must be 'linear' or 'geometric'")
+
+    def solve(self, problem, *, options=None):
+        if options is not None and not isinstance(options, SolveOptions):
+            raise TypeError("options must be a SolveOptions instance")
+        if isinstance(problem, QuboProblem):
+            return self.solve_qubo(
+                problem.matrix,
+                offset=float(problem.metadata.get("offset", 0.0)),
+                options=options,
+            )
+        if isinstance(problem, IsingProblem):
+            return self.solve_ising(
+                problem.matrix,
+                fields=problem.metadata.get("fields"),
+                offset=float(problem.metadata.get("offset", 0.0)),
+                options=options,
+            )
+        raise TypeError("problem must be a QuboProblem or IsingProblem")
+
+    def solve_qubo(self, qubo, *, offset=0.0, initial_state=None, options=None):
+        coefficients = qubo_to_ising(qubo)
+        initial_spins = None
+        if initial_state is not None:
+            try:
+                bits = list(initial_state)
+            except TypeError as error:
+                raise ValueError("initial_state must contain one 0 or 1 value per variable") from error
+            if any(bit not in (0, 1) for bit in bits):
+                raise ValueError("initial_state must contain one 0 or 1 value per variable")
+            initial_spins = [2 * int(bit) - 1 for bit in bits]
+
+        def execute():
+            result = self._solve_ising(
+                coefficients.couplings,
+                coefficients.fields,
+                float(offset) + coefficients.offset,
+                initial_state=initial_spins,
+                options=options,
+            )
+            spins = result.best_solution
+            bits = [(spin + 1) // 2 for spin in spins]
+            metrics = dict(result.metrics)
+            metrics["best_spins"] = spins
+            return SolveResult(
+                status=result.status,
+                best_solution=bits,
+                best_value=result.best_value,
+                solver=result.solver,
+                runtime_seconds=result.runtime_seconds,
+                history=result.history,
+                metrics=metrics,
+                execution=result.execution,
+            )
+
+        return tracked_call(self._usage_reporter, "sqa", "local", execute)
+
+    def solve_ising(self, couplings, *, fields=None, offset=0.0, initial_state=None, options=None):
+        return tracked_call(
+            self._usage_reporter,
+            "sqa",
+            "local",
+            lambda: self._solve_ising(couplings, fields, offset, initial_state=initial_state, options=options),
+        )
+
+    def _gamma(self, step):
+        if self.sweeps == 1:
+            return self.gamma_end
+        fraction = step / (self.sweeps - 1)
+        if self.schedule == "linear":
+            return self.gamma_start + fraction * (self.gamma_end - self.gamma_start)
+        return self.gamma_start * (self.gamma_end / self.gamma_start) ** fraction
+
+    def _solve_ising(self, couplings, fields, offset, *, initial_state, options):
+        if options is not None and not isinstance(options, SolveOptions):
+            raise TypeError("options must be a SolveOptions instance")
+        started = time.perf_counter()
+        matrix = symmetrize(couplings)
+        size = len(matrix)
+        linear = [0.0] * size if fields is None else _finite_vector(fields, size, "fields")
+        offset = float(offset)
+        if not math.isfinite(offset):
+            raise ValueError("offset must be finite")
+        if initial_state is not None:
+            initial_state = [int(value) for value in initial_state]
+            if len(initial_state) != size or any(value not in {-1, 1} for value in initial_state):
+                raise ValueError("initial_state must contain one -1 or +1 value per variable")
+
+        seed = self.seed if options is None or options.random_seed is None else options.random_seed
+        rng = random.Random(seed)
+        replicas = [
+            list(initial_state) if initial_state is not None else [rng.choice((-1, 1)) for _ in range(size)]
+            for _ in range(self.trotter_slices)
+        ]
+
+        def classical_energy(spins):
+            return offset + sum(linear[i] * spins[i] for i in range(size)) + sum(
+                matrix[i][j] * spins[i] * spins[j]
+                for i in range(size)
+                for j in range(size)
+            )
+
+        energies = [classical_energy(replica) for replica in replicas]
+        best_index = min(range(self.trotter_slices), key=energies.__getitem__)
+        best_spins = replicas[best_index][:]
+        best_value = energies[best_index]
+        history = [best_value]
+        accepted = attempted = 0
+        deadline = None
+        if options is not None and options.time_limit_seconds is not None:
+            deadline = started + options.time_limit_seconds
+
+        completed_sweeps = 0
+        timed_out = False
+        for step in range(self.sweeps):
+            gamma = self._gamma(step)
+            argument = self.beta * gamma / self.trotter_slices
+            temporal_coupling = -0.5 * math.log(max(math.tanh(argument), 1e-300))
+            updates = [(slice_index, spin_index) for slice_index in range(self.trotter_slices) for spin_index in range(size)]
+            rng.shuffle(updates)
+            for slice_index, spin_index in updates:
+                if deadline is not None and time.perf_counter() >= deadline:
+                    timed_out = True
+                    break
+                spins = replicas[slice_index]
+                spin = spins[spin_index]
+                local_field = linear[spin_index] + 2.0 * sum(
+                    matrix[spin_index][other] * spins[other]
+                    for other in range(size)
+                    if other != spin_index
+                )
+                delta_energy = -2.0 * spin * local_field
+                previous_spin = replicas[(slice_index - 1) % self.trotter_slices][spin_index]
+                next_spin = replicas[(slice_index + 1) % self.trotter_slices][spin_index]
+                delta_action = (
+                    self.beta * delta_energy / self.trotter_slices
+                    + 2.0 * temporal_coupling * spin * (previous_spin + next_spin)
+                )
+                attempted += 1
+                if delta_action <= 0.0 or rng.random() < math.exp(-min(delta_action, 745.0)):
+                    spins[spin_index] = -spin
+                    energies[slice_index] += delta_energy
+                    accepted += 1
+                    if energies[slice_index] < best_value:
+                        best_value = energies[slice_index]
+                        best_spins = spins[:]
+            if timed_out:
+                break
+            completed_sweeps += 1
+            history.append(best_value)
+
+        return SolveResult(
+            status=SolveStatus.TIME_LIMIT if timed_out else SolveStatus.FEASIBLE,
+            best_solution=best_spins,
+            best_value=float(best_value),
+            solver=SolverIdentity(
+                "SimulatedQuantumAnnealing",
+                f"ascent-science-sqa {__version__}",
+                "Suzuki-Trotter Monte Carlo",
+            ),
+            runtime_seconds=time.perf_counter() - started,
+            history=tuple(history),
+            metrics={
+                "trotter_slices": self.trotter_slices,
+                "completed_sweeps": completed_sweeps,
+                "beta": self.beta,
+                "gamma_start": self.gamma_start,
+                "gamma_end": self.gamma_end,
+                "schedule": self.schedule,
+                "accepted_moves": accepted,
+                "attempted_moves": attempted,
+                "acceptance_rate": accepted / attempted if attempted else 0.0,
+            },
+            execution=ExecutionInfo(location="local", backend="path-integral-monte-carlo"),
+        )
+
+
+def register():
+    return register_algorithm(
+        category="quantum",
+        exports={"SimulatedQuantumAnnealing": SimulatedQuantumAnnealing},
+        specification=AlgorithmSpec(
+            name="sqa",
+            family="quantum",
+            problem_types=("qubo", "ising"),
+            input_kind="qubo_or_ising",
+            output_kind="binary_or_spin",
+            factory=SimulatedQuantumAnnealing,
+            deterministic=False,
+            supports_initial_solution=True,
+            aliases=("simulated_quantum_annealing",),
+            description="Suzuki-Trotter path-integral simulated quantum annealing.",
+        ),
+    )
+
+
+__all__ = ["SimulatedQuantumAnnealing", "register"]

ascent_science_sqa-0.1.0/src/ascent_science_sqa.egg-info/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: ascent-science-sqa
+Version: 0.1.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 and single-spin Metropolis 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
+```
+
+After the `0.1.0` package is published, it can instead be installed with
+`python -m pip install ascent-science-sqa==0.1.0`.
+
+```python
+import ascent
+
+solver = ascent.quantum.SimulatedQuantumAnnealing(
+    trotter_slices=32,
+    sweeps=500,
+    beta=5.0,
+    gamma_start=5.0,
+    gamma_end=0.01,
+    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).
+
+## 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`.

ascent_science_sqa-0.1.0/src/ascent_science_sqa.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+src/ascent_science_sqa/__init__.py
+src/ascent_science_sqa.egg-info/PKG-INFO
+src/ascent_science_sqa.egg-info/SOURCES.txt
+src/ascent_science_sqa.egg-info/dependency_links.txt
+src/ascent_science_sqa.egg-info/entry_points.txt
+src/ascent_science_sqa.egg-info/requires.txt
+src/ascent_science_sqa.egg-info/top_level.txt

ascent_science_sqa-0.1.0/src/ascent_science_sqa.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ascent_science_sqa-0.1.0/src/ascent_science_sqa.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[ascent.algorithms]
+sqa = ascent_science_sqa:register

ascent_science_sqa-0.1.0/src/ascent_science_sqa.egg-info/requires.txt

@@ -0,0 +1 @@
+ascent-science<0.10,>=0.9.4

ascent_science_sqa-0.1.0/src/ascent_science_sqa.egg-info/top_level.txt

@@ -0,0 +1 @@
+ascent_science_sqa