Merge branch '8-add-json-backend' into 'main'

Resolve "add json backend"

Closes #8

See merge request devel/qubo!9

Author: Vaibhavnath-Jha

README.md

@@ -172,6 +172,9 @@ uv sync --group dev
 ```
 The tests can then be run via `pytest tests\test_qubo.py`
 
+## Utility
+For integrating external solvers not natively supported by GAMSPy, you can export the formulated Q matrix and pass the resulting solution vector back as a JSON file with the json "backend". The package will then automatically map this external binary solution to your original model variables.
+
 ## GAMS Version
 
 The original tool was developed for the GAMS modeling language. While this repository now focuses on the GAMSPy (Python) implementation, the classic GAMS version remains available in the GAMS subfolder.

gamspy_qubo/src/gamspy_qubo/backend/__init__.py

@@ -1,5 +1,6 @@
 from gamspy_qubo.backend.base import baseBackend
 from gamspy_qubo.backend.dwave import DwaveBackend
 from gamspy_qubo.backend.kipu import KipuBackend
+from gamspy_qubo.backend.load_json import JsonBackend
 
-__all__ = ["baseBackend", "DwaveBackend", "KipuBackend"]
+__all__ = ["baseBackend", "DwaveBackend", "KipuBackend", "JsonBackend"]

gamspy_qubo/src/gamspy_qubo/backend/dwave.py

@@ -34,7 +34,7 @@ def solve(self, *args, **kwargs) -> pd.DataFrame:
         ut_mat *= multiplier
         matrix_dict = {}
         rows, cols = ut_mat.nonzero()
-        for i, j in zip(rows, cols):
+        for i, j in zip(rows, cols, strict=True):
             matrix_dict[(self.q_variables[i], self.q_variables[j])] = ut_mat[i, j]
 
         dimod = importlib.import_module("dimod")

gamspy_qubo/src/gamspy_qubo/backend/kipu.py

@@ -61,7 +61,7 @@ def solve(self, *args, **kwargs) -> pd.DataFrame:
         ut_mat *= multiplier
         problem = {}
         rows, cols = ut_mat.nonzero()
-        for i, j in zip(rows, cols):
+        for i, j in zip(rows, cols, strict=True):
             if i == j:
                 problem[f"({i},)"] = ut_mat[i, j]  # diagonal terms
             else:

gamspy_qubo/src/gamspy_qubo/backend/load_json.py

@@ -0,0 +1,35 @@
+import json
+
+import pandas as pd
+
+from gamspy_qubo.backend import baseBackend
+
+
+class JsonBackend(baseBackend):
+    """
+    A custom backend that reads a pre-solved QUBO solution from a JSON file.
+    """
+
+    def __init__(self, q_matrix, q_variables, q_constant, sense):
+        super().__init__(q_matrix, q_variables, q_constant, sense)
+
+    def solve(self, json_path="solution.json", *args, **kwargs) -> pd.DataFrame:
+        with open(json_path, "r") as f:
+            sol_dict = json.load(f)
+
+        results = []
+        # q_variables holds the QUBO binary indices (e.g., 'b1', 'b2')
+        for var in self.q_variables:
+            # Match the variable name to the JSON keys, defaulting to 0.0 if not found
+            val = sol_dict.get(var, 0.0)
+            results.append({"i": var, "level": float(val)})
+
+        df = pd.DataFrame(results)
+
+        # Provide safe default bounds for the binary variables
+        df["marginal"] = 0.0
+        df["lower"] = 0.0
+        df["upper"] = 1.0
+        df["scale"] = 1.0
+
+        return df

gamspy_qubo/src/gamspy_qubo/qubo.py

@@ -6,12 +6,13 @@
 from gamspy.exceptions import GamspyException, ValidationError
 
 from gamspy_qubo import _utils
-from gamspy_qubo.backend import DwaveBackend, KipuBackend
+from gamspy_qubo.backend import DwaveBackend, JsonBackend, KipuBackend
 
 LOG_LEVEL_DICT = {0: log.WARN, 1: log.INFO, 2: log.DEBUG}
 SUPPORTED_QUANTUM_BACKENDS = [
     "dwave",
     "kipu",
+    "json",
 ]  # append this list when adding new quantum backend
 
 
@@ -595,7 +596,7 @@ def write_qubowl(self) -> None:
         non_zero_values = self.Q[non_zero_indices]
         with open(f"QMat_{self._modelName}.qs", "w") as fp:
             fp.write(f"{self.Q.shape[0]} {len(non_zero_values)} {self.Qconst}\n")
-            for i, j, value in zip(*non_zero_indices, non_zero_values):
+            for i, j, value in zip(*non_zero_indices, non_zero_values, strict=True):
                 if value != 0:
                     fp.write(f"{i + 1} {j + 1} {value}\n")
 
@@ -655,8 +656,14 @@ def solve(self, *args, **kwargs) -> pd.DataFrame | None:
             optimized_variable_values = self._q_container["x"].records
         elif self._backend in SUPPORTED_QUANTUM_BACKENDS:
             q_vars: pd.Series = self._q_container["qi"].records["uni"]
-            _initialize = {"dwave": DwaveBackend, "kipu": KipuBackend}
-            _backend: DwaveBackend | KipuBackend = _initialize[self._backend](
+            _initialize = {
+                "dwave": DwaveBackend,
+                "kipu": KipuBackend,
+                "json": JsonBackend,
+            }
+            _backend: DwaveBackend | KipuBackend | JsonBackend = _initialize[
+                self._backend
+            ](
                 q_matrix=self.Q,
                 q_variables=q_vars,
                 q_constant=self.Qconst,