Feature enhancement and bug fixes

README.md

@@ -1,38 +1,78 @@
 # Shimming Tutorial
 
-This repository contains supplementary code for the tutorial [Calibration refinement in quantum annealing](https://arxiv.org/abs/2304.10352).
+This repository contains supplementary code for
+Tutorial: Calibration refinement in quantum annealing
+https://doi.org/10.3389/fcomp.2023.1238988
 
 Install the dependencies with
 ```bash
-# Python version 3.10
+# Python version 3.13
 pip install -r requirements.txt
 ```
 
+Code examples demonstrate orbits for selected models (executed locally),
+calculation of embeddings (exectued locally),
+and iterative shimming results for several models (executed by default on
+Leap-hosted Quantum Processing Units).
 
-## Orbit preliminaries
+Each example has configurable parameters. See the main() function
+documentation in each module for a description of parameters. This includes
+the flexbility to modify the model, target processor, or embedding
+heuristic for increased performance. To reduce the total number
+of iterations (programmings, thence QPU access time) or learning rate(s).
+
+## Orbit examples (run locally)
+
+For generation of Figure 4
 ```
 python -m example0_1_orbits
 ```
 
+For generation of Figure 9
+```
+python -m example2_1_frustrated_loop_orbits
+```
+
+For generation of Figure 11
+```
+python -m example2_3_buckyball_orbits
+```
+
+For generation of orbits related to Figures 13-16
+```
+python -m example3_1_tafm_get_orbits
+```
+
 ## Ferromagnetic loop example
+For generation of Figure 6: **Balancing qubits in a FM chain with flux-bias offsets**. <br>
+Requires 300 sequential QPU-job submissions.
 ```
 python -m example1_1_fm_loop_balancing
+```
+For generation of **Balancing qubits and couplers in a FM chain with flux-bias offsets and coupler adjustments** related to Figure 7. <br>
+Requires 300 sequential QPU-job submissions.
+```
 python -m example1_2_fm_loop_correlations
 ```
 
 ## Frustrated loop example
+For generation of Figure 10: **Shimming a frustrated loop**. <br>
+Requires 300 sequential QPU-job submissions.
 ```
-python -m example2_1_frustrated_loop_orbits
 python -m example2_2_frustrated_loop_anneal
 ```
 
-## Buckyball example
-```
-python -m example2_3_buckyball_orbits
-```
+## Triangular antiferromagnet example
+For generation of the following figures:
+- Figure 13: **Shimming an embedded cylindrical triangular antiferromagnet**. <br>
+- Figure 14: **Shimming an isotropic, infinite triangular antiferromagnet**. <br>
+- Figure 15: **Shimming an isotropic, infinite triangular antiferromagnet, starting with halved boundary couplers**. <br>
+- Figure 16: **Complex order parameter ψ**. <br>
 
-## Triangular Antiferromagnet example
+Generation of embeddings may require several minutes.
+Data is collected in 3 blocks each requiring 800 sequential QPU-job submissions.
+One figure is presented per block (interrupting data collection until the
+figure is closed); along with one summary figure.
 ```
-python -m example3_1_tafm_get_orbits
 python -m example3_2_tafm_forward_anneal
 ```

requirements.txt

@@ -1,12 +1,4 @@
-networkx==2.8.8
-numpy==1.24.1
-dimod==0.12.3
 pynauty==2.8.6
-matplotlib==3.6.3
-tikzplotlib==0.10.1
-dwave-networkx==0.8.13
-dwave-system==1.18.0
-dwave-ocean-sdk==6.3.0
-minorminer==0.2.11
+matplotlib==3.9.2
+dwave-ocean-sdk==8.0.1
 tqdm==4.64.1
-pydantic < 2.0

tutorial_code/embed_loops.py

@@ -13,27 +13,61 @@
 # limitations under the License.
 #
 import os
-
 import dimod
+import warnings
 import numpy as np
 
-from dwave.system.samplers import DWaveSampler
+from dwave.system.testing import MockDWaveSampler
+
+from minorminer.utils.parallel_embeddings import (
+    find_sublattice_embeddings,
+    embeddings_to_array,
+    lattice_size,
+)
 
-from helpers.embedding_helpers import raster_embedding_search
+from minorminer.utils.feasibility import (
+    embedding_feasibility_filter,
+    lattice_size_lower_bound,
+)
 
 
-def embed_loops(L, try_to_load=True, raster_breadth=2):
-    """Embed loops of length L
+def embed_loops(
+    sampler: MockDWaveSampler,
+    L: int,
+    use_cache: bool = True,
+    **kwargs,
+) -> np.ndarray:
+    """Embeds a ring of length L.
 
     Args:
-        L (int): chain length
-        try_to_load (bool, optional): Flag for loading from cached data. Defaults to True.
-        raster_breadth (int, optional): breadth parameter for raster embedding search. Defaults to 2.
+        sampler (int): DWaveSampler for which to embed
+        L (int): lattice length
+        use_cache (bool, default=True): When True, embeddings are
+            saved to and loaded from a local directory whenever
+            possible. If writing to a directory is not possible
+            a warning is thrown.
 
-    Returns:
-        numpy.ndarray: a matrix of embeddings
+        Returns:
+        np.ndarray: An matrix of embeddings
     """
-    sampler = DWaveSampler()  # As configured
+    if not isinstance(L, int):
+        raise ValueError(f"'L' must be an integer. Received type {type(L).__name__}.")
+    if L <= 0:
+        raise ValueError(f"'L' must be a positive integer. Received {L}.")
+
+    if not isinstance(use_cache, bool):
+        raise ValueError(
+            f"'use_cache' must be a boolean. Received type {type(use_cache).__name__}."
+        )
+
+    solver_name = sampler.properties["chip_id"]  # sampler.solver.name
+    cache_filename = f"cached_embeddings/{solver_name}_L{L:04d}_embeddings_cached.txt"
+
+    if use_cache and os.path.exists(cache_filename):
+        embeddings = np.loadtxt(cache_filename, dtype=int)
+        print(f"Loaded {cache_filename}")
+        return embeddings
+
     bqm = dimod.BinaryQuadraticModel(
         vartype="SPIN",
     )
@@ -42,29 +76,70 @@ def embed_loops(L, try_to_load=True, raster_breadth=2):
     G = dimod.to_networkx_graph(bqm)
     A = sampler.to_networkx_graph()
 
-    cache_filename = (
-        f"cached_embeddings/{sampler.solver.name}__L{L:04d}_embeddings_cached.txt"
+    if not embedding_feasibility_filter(S=G, T=A):
+        raise ValueError(f"Embedding {G} on {A} is infeasible")
+    sublattice_size = kwargs.pop(
+        "sublattice_size",
+        min(lattice_size_lower_bound(S=G, T=A) + 1, lattice_size(T=A)),
+    )
+
+    if not isinstance(sublattice_size, int) or sublattice_size <= 0:
+        raise ValueError(
+            f"'sublattice_size' must be a positive integer. Received {sublattice_size}."
+        )
+
+    print(
+        "Creating embeddings may take several minutes."
+        "\nTo accelerate the process a smaller lattice (L) might be "
+        "considered and/or the search restricted to max_num_emb=1."
     )
-    if try_to_load:
+    max_num_emb = kwargs.pop("max_num_emb", G.number_of_nodes()//A.number_of_nodes())
+    embedder_kwargs = {"timeout": kwargs.pop("timeout", 10)}
+    embeddings = embeddings_to_array(
+        find_sublattice_embeddings(
+            S=G,
+            T=A,
+            sublattice_size=sublattice_size,
+            max_num_emb=max_num_emb,
+            embedder_kwargs=embedder_kwargs,
+            **kwargs,
+        ),
+        node_order=sorted(G.nodes()),
+        as_ndarray=True,
+    )
+
+    if embeddings.size == 0:
+        raise ValueError(
+            "No feasible embeddings found. "
+            "\nModifying the source (lattice) and target "
+            "(processor), or find_sublattice_embeddings arguments "
+            "such as timeout may resolve the issue."
+        )
+
+    if use_cache:
         try:
-            embeddings = np.loadtxt(cache_filename, dtype=int)
-            print(f"Loaded embedding from file {cache_filename}")
-            return embeddings
-        except (ValueError, FileNotFoundError) as e:
-            print(f"Failed to load {cache_filename} with `np.loadtxt`")
-            print("Error:", e)
-            print("Finding embedding via raster embedding search instead.")
-    embeddings = raster_embedding_search(A, G, raster_breadth=raster_breadth)
-
-    os.makedirs("cached_embeddings/", exist_ok=True)
-    np.savetxt(cache_filename, embeddings, fmt="%d")
+            os.makedirs("cached_embeddings/", exist_ok=True)
+            np.savetxt(cache_filename, embeddings, fmt="%d")
+        except:
+            warnings.warn("Embedding cache files could not be created")
 
     return embeddings
 
 
-def main():
-    L = 8  # Length of chain to embed
-    embeddings = embed_loops(L, raster_breadth=2)
+def main(max_num_emb=None):
+    from time import perf_counter
+
+    L = 2048  # L=2048 anticipate ~ 2.5 seconds on i7
+    sampler = MockDWaveSampler(topology_type="pegasus", topology_shape=[16])
+    t0 = perf_counter()
+    embeddings = embed_loops(
+        sampler=sampler, L=L, max_num_emb=max_num_emb, use_cache=False
+    )
+    t1 = perf_counter() - t0
+    if embeddings.size >= 1:
+        print(f"Loop {L} embedding successfully found in {t1} seconds")
+    else:
+        print(f"Something is wrong, {L}x{L} embedding not found")
 
 
 if __name__ == "__main__":