Add lattice-utils to dwave-experimental by SebastianGitt · Pull Request #44 · dwavesystems/dwave-experimental

SebastianGitt · 2026-03-13T20:49:49Z

Add a minimal version of LatQA to dwave-experimental as a submodule named lattice-utils. Currently supports examples of a 1D Ising Chain and a 2D dimerized triangular lattice. Tests still need to be added to the pull request.

-move initialization of num_spins to subclass

thisac

Thanks @SebastianGitt! First pass of the lattice submodule.

I'd recommend running a formatter (black) since all of these files are new and there are a few places with incorrect spacing, etc.
I think the saving/loading of embeddings can be refined a bit, but I'll have a closer look at it later.

-added more comprehensive docstrings -fixed formatting issues

…dwave-experimental into add-lattice-utils

…utils

-removed spin reversal transform functionality -uses automorphism module already in dwave-experimental -uses data classes for experiment configs

-removed spin reversal transform functionality -uses automorphism module already in dwave-experimental -uses data classes for experiment configs -formatted using black

andrew-d-king

Looks generally good; I am not able to pore over it in detail but it all seems sensible.

andrew-d-king · 2026-05-15T13:10:12Z

+
+        return sampler_call
+
+    def _format_parameter_list(


Maybe not for this PR, but ultimately I think that a parameter class should be written, with a format parameter (basically sig figs, for float parameters). It's a bit ugly to do it ad hoc, as I've written it.

thisac

Still have experiment module to look at. Re. the tests, it probably makes sense splitting them up into several files collected in a test_lattice_utils folder.

-added progress bars using TQDM -added docstrings to the evaluation methods in observable.py -misc cleanup

…dwave-experimental into add-lattice-utils

jackraymond

Nice job, especially the integration of new automorphism functionality to make the shimming tutorial generalizable.

Some of this code is not lattice specific, I'd prefer it weren't bundled up in a lattice utility. Like embed_bqm (which mirrors a dwave.system) and unembed_bqm (which perhaps is, or should be dwave.system method), bootstrapping, bitstring compression. Ideally we could think how to extract it for more general use.

Examples don't run well, or at all for me. Adding an interface and some additional help messages on what is going on would be great. Perhaps cite papers etc where statistics are used.

There are a lot of magic numbers/methods floating around, if these could be promoted to function arguments and justified that would be great.

Some other naming conventions I found a bit confusing.

-fix failing tests due to updated method signatures with explicit arguments -rename energy_scale to signed_energy_scale

-remove existing examples and replaced with a new 1D chain shimming example -restructure tests into separate files in a new folder -update optimize function to accept custom dimod solvers -expand docstring for ``embed_bqm`` method to explain difference from existing methods in dwave-system -promote ``optimize`` and ``make_networkx_graph`` to public methods

thisac

Looking good so far! A couple of comments and improvements before ready to merge.

One thing that we discussed already: tqdm should be made into an optional dependency. Currently it's required to install.

thisac · 2026-07-06T23:27:51Z

+
+import dimod
+import numpy as np
+from tqdm.auto import tqdm


Didn't we say that we'd make tqdm optional?

thisac · 2026-07-07T00:46:41Z

+            if not quiet:
+                print(f"Loaded {filename} at {datetime.now()}")


For now let's remove print statements from the package. We can think about either adding in logging messages if we really think it's needed, or warnings where reasonable.

thisac · 2026-07-07T00:53:48Z

+        for param_name, param_val in param.items():
+            self.param[param_name] = param_val


Any reason for not doing

Suggested change

for param_name, param_val in param.items():

self.param[param_name] = param_val

self.param.update(param)

thisac · 2026-07-07T00:57:30Z

+        self.sampler = sampler
+        self.reference_energy_sampler = reference_energy_sampler
+        self.reference_energy_sampler_kwargs = reference_energy_sampler_kwargs
+        self.param = dict(vars(config))


vars returns a dict already

Suggested change

self.param = dict(vars(config))

self.param = vars(config)

This is done to return a copy so that future changes to self.param don't affect the config object

Perhaps use

Suggested change

self.param = dict(vars(config))

self.param = vars(config).copy()

instead? Both dict(vars(config)) and vars(config).copy() would just return shallow copies.

thisac · 2026-07-07T01:19:39Z

+                if ignore_shim:
+                    result_fields.remove("shimdata")


Based on docs it sounds like this should maybe be outside the if result_fields is None?

thisac · 2026-07-07T03:50:02Z

+            A numpy array containing the pairwise spin correlations for each coupler.
+        """
+        sample_array = dimod.as_samples(sample_set)[0].astype(float)
+        if len(experiment.inst.edge_list) == 0:


Should work and would in that case be recommended.

Suggested change

if len(experiment.inst.edge_list) == 0:

if not experiment.inst.edge_list:

thisac · 2026-07-07T03:50:22Z

+            A numpy array containing the mean coupler frustration for each edge.
+        """
+        sample_array = dimod.as_samples(sample_set)[0].astype(float)
+        if len(experiment.inst.edge_list) == 0:


Suggested change

if len(experiment.inst.edge_list) == 0:

if not experiment.inst.edge_list:

thisac · 2026-07-07T03:53:02Z

+
+        return energy
+
+    def load(


A few of the methods below are missing complete docstrings (load, save, and update).

thisac · 2026-07-07T03:54:24Z

+        if new_energy < reference_energy:
+            if path is None:
+                path = get_reference_energy_path(bqm, experiment)
+            self.save(path, new_energy, sample, reference_method_string)
+        else:
+            raise ValueError("New energy is not better than reference energy, not updating.")


Minor, but I'd turn this around

Suggested change

if new_energy < reference_energy:

if path is None:

path = get_reference_energy_path(bqm, experiment)

self.save(path, new_energy, sample, reference_method_string)

else:

raise ValueError("New energy is not better than reference energy, not updating.")

if new_energy >= reference_energy:

raise ValueError("New energy is not better than reference energy, not updating.")

if path is None:

path = get_reference_energy_path(bqm, experiment)

self.save(path, new_energy, sample, reference_method_string)

thisac · 2026-07-07T03:56:47Z

+features:
+  - |
+    Add ``dwave.experimental.lattice_utils`` submodule with utilities for
+    constructing lattice graphs (``Chain``, ``Triangular``,
+    ``DimerizedTriangular``, ``EmbeddedLattice``), evaluating physics
+    observables on sample sets, and running shimmed Ising experiments on
+    QPU samplers.


This should probably be split up into several features.

thisac

A few more comments...

thisac · 2026-07-07T17:12:49Z

+        if self.param.get("fast_anneal", False):
+            ret["fast_anneal"] = True
+
+        ret["annealing_time"] = self.param["anneal_time"]


Since elsewhere it seems like either "anneal_schedule" or "anneal_time" can be used, is this also the case here? If not, perhaps add a comment on why.

if "anneal_schedule" in self.param: ... elif "anneal_time" in self.param: ret["annealing_time"] = self.param["anneal_time"]

thisac · 2026-07-07T17:22:11Z

+        for i in range(n - 1):
+            yield (i, i + 1)
+
+        if self.periodic[0] and n > 1:


Should this be n > 2? As it currently stands, when self.dimensions[0] == 2 this would yield both (0, 1) and (1, 0).

Suggested change

if self.periodic[0] and n > 1:

if self.periodic[0] and n > 2:

thisac · 2026-07-07T17:33:47Z

+            if qubit_orbits is not None and coupler_orbits is not None:
+                if len(qubit_orbits) != self.num_spins:
+                    raise ValueError(
+                        f"qubit_orbits must have length {self.num_spins}, got {len(qubit_orbits)}."
+                    )
+                if len(coupler_orbits) != self.num_edges:
+                    raise ValueError(
+                        f"coupler_orbits must have length {self.num_edges}, "
+                        f"got {len(coupler_orbits)}."
+                    )


If either qubit_orbits or coupler_orbits is None, then the other won't be checked (since this states and).

Should these checks be separated into:

if qubit_orbits and len(qubit_orbits) != self.num_spins: raise ValueError( f"qubit_orbits must have length {self.num_spins}, got {len(qubit_orbits)}." )

and

if coupler_orbits and len(coupler_orbits) != self.num_edges: raise ValueError( f"coupler_orbits must have length {self.num_edges}, " f"got {len(coupler_orbits)}." )

thisac · 2026-07-07T18:37:08Z

+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Shimming example for 1D Ising chain."""


Let's also rename this file to just 1D_Ising_chain_shim.py or maybe prefix it with lattice_utils or even put it in a lattice_utils subfolder since there are quite a few more lattice-utils examples incoming, no?

thisac · 2026-07-07T18:37:41Z

+
+from dwave.system import DWaveSampler
+import matplotlib.pyplot as plt
+from matplotlib.colors import to_rgb


Suggested change

from matplotlib.colors import to_rgb

thisac · 2026-07-07T18:38:01Z

+from dwave.experimental.lattice_utils import lattice, experiment, observable
+from dwave.experimental.lattice_utils.utils import bootstrap, confidence_interval


Not used?

Suggested change

from dwave.experimental.lattice_utils import lattice, experiment, observable

from dwave.experimental.lattice_utils.utils import bootstrap, confidence_interval

from dwave.experimental.lattice_utils import lattice, experiment

thisac · 2026-07-07T18:46:41Z

+        self.observables_to_collect = {
+            QubitMagnetization(),
+            CouplerCorrelation(),
+            CouplerFrustration(),
+            SampleEnergy(),
+            BitpackedSpins(),
+            ReferenceEnergy(),
+        }


Actually, does it even make sense having this be a set? Wouldn't a tuple be a more reasonable type? That nulls my other comment about not having to cast this to a set below (although I think not using sets at all here might make more sense).

I agree it doesn't need to be a set, but for certain examples custom observables will be added to this, so it might be less clunky to use a list here instead of having to update the tuple with additional observables

I would probably go for a list in that case.

-make TQDM an optional import -order imports -add some missing docstrings -removed subscript unpacking for Python 3.10 compatibility -updated licenses to 2026

codecov-commenter · 2026-07-21T17:30:09Z

Codecov Report

❌ Patch coverage is 90.44944% with 102 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.74%. Comparing base (703b3cd) to head (2b02cee).
⚠️ Report is 24 commits behind head on main.

Files with missing lines	Patch %	Lines
...xperimental/lattice_utils/experiment/experiment.py	83.67%	64 Missing ⚠️
...wave/experimental/lattice_utils/lattice/lattice.py	89.55%	14 Missing ⚠️
...e/experimental/lattice_utils/lattice/triangular.py	91.95%	7 Missing ⚠️
...xperimental/lattice_utils/observable/observable.py	92.70%	7 Missing ⚠️
...rimental/lattice_utils/lattice/embedded_lattice.py	95.65%	4 Missing ⚠️
...xperimental/lattice_utils/observable/triangular.py	84.00%	4 Missing ⚠️
dwave/experimental/lattice_utils/lattice/chain.py	95.00%	1 Missing ⚠️
dwave/experimental/lattice_utils/utils.py	96.29%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #44      +/-   ##
==========================================
- Coverage   95.38%   92.74%   -2.64%     
==========================================
  Files          13       30      +17     
  Lines         931     1999    +1068     
==========================================
+ Hits          888     1854     +966     
- Misses         43      145     +102

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

SebastianGitt added 2 commits March 13, 2026 13:42

Add lattice-utils to dwave-experimental

7dac34b

Add unit tests

23938bf

-move initialization of num_spins to subclass

thisac reviewed Apr 24, 2026

View reviewed changes

SebastianGitt added 7 commits May 7, 2026 11:08

Improve docstrings and formatting

759eca5

-added more comprehensive docstrings -fixed formatting issues

Improve docstrings and formatting

b6bf8f6

-added more comprehensive docstrings -fixed formatting issues

Merge branch 'add-lattice-utils' of https://github.com/SebastianGitt/…

a5ae37d

…dwave-experimental into add-lattice-utils

Merge remote-tracking branch 'sebastians-fork/main' into add-lattice-…

0aa1bff

…utils

Remove temporary automorphism file and additional cleanup

8122131

-removed spin reversal transform functionality -uses automorphism module already in dwave-experimental -uses data classes for experiment configs

Remove temporary automorphism file and additional cleanup

0ef6a52

-removed spin reversal transform functionality -uses automorphism module already in dwave-experimental -uses data classes for experiment configs -formatted using black

Format using black

ab9348a

SebastianGitt marked this pull request as ready for review May 14, 2026 17:50

andrew-d-king suggested changes May 15, 2026

View reviewed changes

thisac reviewed Jun 3, 2026

View reviewed changes

SebastianGitt added 4 commits June 8, 2026 11:45

Add progress bars and missing docstrings

f364d2d

-added progress bars using TQDM -added docstrings to the evaluation methods in observable.py -misc cleanup

Add progress bars and missing docstrings

06d43bf

-added progress bars using TQDM -added docstrings to the evaluation methods in observable.py -misc cleanup

Merge branch 'add-lattice-utils' of https://github.com/SebastianGitt/…

26381f8

…dwave-experimental into add-lattice-utils

Update default parameters of 1D example

dab4d6d

jackraymond reviewed Jun 9, 2026

View reviewed changes

SebastianGitt added 2 commits June 11, 2026 11:56

Update tests and examples

80c3929

-fix failing tests due to updated method signatures with explicit arguments -rename energy_scale to signed_energy_scale

thisac reviewed Jul 7, 2026

View reviewed changes

Make TQDM optional

2b02cee

-make TQDM an optional import -order imports -add some missing docstrings -removed subscript unpacking for Python 3.10 compatibility -updated licenses to 2026

SebastianGitt force-pushed the add-lattice-utils branch from fd48b6e to 2b02cee Compare July 21, 2026 17:27

		if not quiet:
		print(f"Loaded {filename} at {datetime.now()}")

		for param_name, param_val in param.items():
		self.param[param_name] = param_val

	for param_name, param_val in param.items():
	self.param[param_name] = param_val
	self.param.update(param)

	self.param = dict(vars(config))
	self.param = vars(config).copy()

	if len(experiment.inst.edge_list) == 0:
	if not experiment.inst.edge_list:

	if self.periodic[0] and n > 1:
	if self.periodic[0] and n > 2:

		from dwave.experimental.lattice_utils import lattice, experiment, observable
		from dwave.experimental.lattice_utils.utils import bootstrap, confidence_interval

Uh oh!

Conversation

SebastianGitt commented Mar 13, 2026

Uh oh!

thisac left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

andrew-d-king left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

thisac left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jackraymond left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

thisac left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!