Don't serialize the states of intermediate variables

.circleci/config.yml

@@ -9,7 +9,7 @@ commands:
     parameters:
       cibw-version:
         type: string
-        default: 3.4.1  # latest as of April 2026
+        default: 4.2.0  # latest as of August 2026
     steps:
       - run:
           name: run cibuildwheel
@@ -30,7 +30,7 @@ environment: &global-environment
 jobs:
   python-linux:
     docker:
-      - image: cimg/python:3.13  # just need a version that can install cibuildwheel
+      - image: cimg/python:3.13  # need a version that can install cibuildwheel and that has docker
 
     environment:
       <<: *global-environment
@@ -57,7 +57,7 @@ jobs:
 
   python-linux-debug:
     docker:
-      - image: cimg/python:3.10
+      - image: python:3.10
 
     steps:
       - checkout
@@ -92,7 +92,6 @@ jobs:
           name: test with installed package
           command: |
             . env/bin/activate
-            pip install --group test
             cd tests/
             python -Werror -m unittest
 
@@ -127,7 +126,7 @@ jobs:
 
   python-sdist:
     docker:
-      - image: cimg/python:3.10
+      - image: python:3.10
 
     steps:
       - checkout
@@ -154,9 +153,7 @@ jobs:
     parameters:
       python-version:
         type: string
-      dependency-versions:
-        type: string
-      optional-dependency-versions:
+      wheel-tag:
         type: string
 
     docker:
@@ -167,23 +164,49 @@ jobs:
       - attach_workspace:
           at: dist
       - run:
-          name: install package with dependencies
+          name: test with latest required dependencies
           command: |
             python -m venv env
             . env/bin/activate
             pip install pip --upgrade
-            pip install --upgrade --only-binary=:all: \
-              << parameters.dependency-versions >>
-            pip install dwave-optimization --no-index -f dist/ --no-deps --force-reinstall
-      - run: *run-tests
+            pip install dist/dwave*optimization-*-<< parameters.wheel-tag >>-*.whl
+            cd tests/
+            python -Werror -m unittest
+            rm -r ../env
       - run:
-          name: install optional dependencies
+          name: test with latest optional dependencies
           command: |
+            python -m venv env
             . env/bin/activate
-            pip install --upgrade --only-binary=:all: \
-              << parameters.dependency-versions >> \
-              << parameters.optional-dependency-versions >> \
-      - run: *run-tests
+            pip install pip --upgrade
+            pip install "$(echo dist/dwave*optimization-*-<< parameters.wheel-tag >>-*.whl)[all]"
+            cd tests/
+            python -Werror -m unittest
+            rm -r ../env
+      - run:
+          name: test with oldest required dependencies
+          command: |
+            python -m venv env
+            . env/bin/activate
+            pip install pip --upgrade
+            pip install \
+              --group dependencies-oldest \
+              dist/dwave*optimization-*-<< parameters.wheel-tag >>-*.whl
+            cd tests/
+            python -Werror -m unittest
+            rm -r ../env
+      - run:
+          name: test with oldest optional dependencies
+          command: |
+            python -m venv env
+            . env/bin/activate
+            pip install pip --upgrade
+            pip install \
+              --group dependencies-all-oldest \
+              dist/dwave*optimization-*-<< parameters.wheel-tag >>-*.whl
+            cd tests/
+            python -Werror -m unittest
+            rm -r ../env
 
   cpp-gcc:
     parameters:
@@ -377,15 +400,13 @@ workflows:
       - python-dependencies:
           name: python-dependencies-oldest
           python-version: "3.10"
-          dependency-versions: numpy==1.21.3
-          optional-dependency-versions: dimod==0.12.0 scikit-learn==1.6.0
+          wheel-tag: cp310-cp310
           requires:
             - python-linux
       - python-dependencies:
           name: python-dependencies-latest
-          python-version: "3.14"
-          dependency-versions: numpy
-          optional-dependency-versions: dimod scikit-learn
+          python-version: "3.14"  # As of August 11 2026, dimod, sklearn, scipy don't have 3.15 wheels
+          wheel-tag: cp312-abi3
           requires:
             - python-linux
       - cpp-gcc:

dwave/optimization/__init__.pxd

@@ -1,4 +1,4 @@
-# Copyright 2023 D-Wave Systems Inc.
+# Copyright 2023 D-Wave
 #
 #    Licensed under the Apache License, Version 2.0 (the "License");
 #    you may not use this file except in compliance with the License.

dwave/optimization/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2023 D-Wave Systems Inc.
+# Copyright 2023 D-Wave
 #
 #    Licensed under the Apache License, Version 2.0 (the "License");
 #    you may not use this file except in compliance with the License.

dwave/optimization/_build/_version.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 
-# Copyright 2024 D-Wave Inc.
+# Copyright 2024 D-Wave
 #
 #    Licensed under the Apache License, Version 2.0 (the "License");
 #    you may not use this file except in compliance with the License.

dwave/optimization/_model.pxd

@@ -1,6 +1,6 @@
 # cython: auto_pickle=False
 
-# Copyright 2024 D-Wave Inc.
+# Copyright 2024 D-Wave
 #
 #    Licensed under the Apache License, Version 2.0 (the "License");
 #    you may not use this file except in compliance with the License.

dwave/optimization/_model.pyi

@@ -1,4 +1,4 @@
-# Copyright 2024 D-Wave Systems Inc.
+# Copyright 2024 D-Wave
 #
 #    Licensed under the Apache License, Version 2.0 (the "License");
 #    you may not use this file except in compliance with the License.

dwave/optimization/_model.pyx

@@ -1,4 +1,4 @@
-# Copyright 2024 D-Wave Inc.
+# Copyright 2024 D-Wave
 #
 #    Licensed under the Apache License, Version 2.0 (the "License");
 #    you may not use this file except in compliance with the License.
@@ -26,6 +26,7 @@ import zipfile
 import numpy as np
 
 from cpython cimport Py_buffer
+from cpython.pycapsule cimport PyCapsule_GetPointer, PyCapsule_New
 from cpython.ref cimport PyObject
 from cython.operator cimport dereference as deref, preincrement as inc
 from cython.operator cimport typeid
@@ -91,10 +92,14 @@ cdef object symbol_from_ptr(_Graph model, cppNode* node_ptr):
         # IndexError would be returned by .at()
         raise RuntimeError("given pointer cannot be cast to a known node type") from None
 
-    # In order to get nice polymorphism, it's much easier to pass the dispatch
-    # through Python, so we construct a generic Symbol holding the pointer and then
-    # construct the specific symbol from it.
-    return cls._from_symbol(Symbol.from_ptr(model, node_ptr))
+    # We'll use a PyCapsule to pass a node pointer through the Python layer so
+    # that we can let `cls` determine the type.
+
+    # Even though PyCapsule_New returns a PyObject*, Cython automatically makes
+    # it an object (with appropriate refcounting) so that's nice.
+    cap = PyCapsule_New(node_ptr, 'Node*', NULL)
+
+    return cls._from_ptr(model, cap)
 
 
 cdef class _Graph:
@@ -1129,12 +1134,6 @@ cdef class Symbol:
         self.node_ptr = node_ptr
         self.expired_ptr = node_ptr.expired_ptr()
 
-    def _deterministic_state(self):
-        """Return ``True`` if the symbol's state is uniquely determined by its
-        predecessors.
-        """
-        return self.node_ptr.deterministic_state()
-
     def equals(self, other):
         """Compare whether two symbols are identical.
 
@@ -1195,17 +1194,11 @@ cdef class Symbol:
         return obj
 
     @classmethod
-    def _from_symbol(cls, Symbol symbol):
-        # Disallow lateral casts or demotions.
-        # This is to prevent, say, an Add to be constructed from a Subtract
-        # There are ways around it, but this method is private anyway so it
-        # should be enough of a discouragement and for safety.
-        if not issubclass(cls, type(symbol)):
-            raise TypeError(f"cannot construct a {cls.__name__} from a {type(symbol).__name__}")
-
-        cdef Symbol obj = cls.__new__(cls)
-        obj.initialize_node(symbol.model, symbol.node_ptr)
-        return obj
+    def _from_ptr(cls, model, capsule):
+        """Create a Symbol from a Python capsule containing a Node pointer."""
+        cdef Symbol sym = cls.__new__(cls)
+        sym.initialize_node(model, <cppNode*>(PyCapsule_GetPointer(capsule, 'Node*')))
+        return sym
 
     @classmethod
     def _from_zipfile(cls, zf, directory, _Graph model, predecessors):
@@ -1681,23 +1674,14 @@ cdef class ArraySymbol(Symbol):
         self.initialize_node(model, array_ptr)
 
     @classmethod
-    def _from_symbol(cls, Symbol symbol):
-        """Construct an ArraySymbol from another Symbol."""
-        # Disallow lateral casts or demotions.
-        # This is to prevent, say, an Add to be constructed from a Subtract
-        # There are ways around it, but this method is private anyway so it
-        # should be enough of a discouragement and for safety.
-        if not issubclass(cls, type(symbol)):
-            raise TypeError(f"cannot construct a {cls.__name__} from a {type(symbol).__name__}")
-
-        # Now try to "promote" the type and raise an error if that fails.
-        cdef cppArrayNode* ptr = dynamic_cast_ptr[cppArrayNode](symbol.node_ptr)
-        if not ptr:
-            raise TypeError(f"given symbol cannot construct a {cls.__name__}")
+    def _from_ptr(cls, model, capsule):
+        cdef ArraySymbol sym = super()._from_ptr(model, capsule)
 
-        cdef ArraySymbol obj = cls.__new__(cls)
-        obj.initialize_arraynode(symbol.model, ptr)
-        return obj
+        sym.array_ptr = dynamic_cast_ptr[cppArrayNode](sym.node_ptr)
+        if not sym.array_ptr:
+            raise TypeError(f"given pointer cannot construct an ArrayNode")
+
+        return sym
 
     # Opt ArraySymbol out of default interoperability with NumPy ufuncs. We then
     # add explicit support with our various __<op>__() and __r<op>__ methods.

dwave/optimization/generators.py

@@ -1,4 +1,4 @@
-# Copyright 2024 D-Wave Inc.
+# Copyright 2024 D-Wave
 #
 #    Licensed under the Apache License, Version 2.0 (the "License");
 #    you may not use this file except in compliance with the License.

dwave/optimization/include/dwave-optimization/array.hpp

@@ -1,4 +1,4 @@
-// Copyright 2023 D-Wave Systems Inc.
+// Copyright 2023 D-Wave
 //
 //    Licensed under the Apache License, Version 2.0 (the "License");
 //    you may not use this file except in compliance with the License.
@@ -347,6 +347,9 @@ struct Update {
     // Return true if the update does nothing - that is old and value are the same.
     bool identity() const { return null() || old == value; }
 
+    // Return the update that would undo the current update
+    Update inverse() const { return Update(index, value, old); }
+
     // Use NaN to represent the "nothing" value used in placements/removals
     static constexpr double nothing = std::numeric_limits<double>::signaling_NaN();
 

dwave/optimization/include/dwave-optimization/graph.hpp

@@ -1,4 +1,4 @@
-// Copyright 2023 D-Wave Systems Inc.
+// Copyright 2023 D-Wave
 //
 //    Licensed under the Apache License, Version 2.0 (the "License");
 //    you may not use this file except in compliance with the License.
@@ -135,6 +135,10 @@ class Graph {
     ArrayNode* objective() noexcept { return objective_ptr_; }
     const ArrayNode* objective() const noexcept { return objective_ptr_; }
 
+    /// Remove the last decision. Must not have any successors or the behavior
+    /// is undefined.
+    void pop_decision();
+
     /// Call propagate on every `Node` in the `Graph`.
     void propagate(State& state) const;
 
@@ -151,6 +155,11 @@ class Graph {
         std::function<bool(const Graph&, State&)> accept = [](const Graph&, State&) { return true; }
     ) const;
 
+    /// Propagate any pending changes to all nodes in the graph and commit them.
+    void propose(State& state) const;
+    // dev note: the name is a bit funny in this case, but we essentially want
+    // an overload for a "default" `sources` and `accept`.
+
     /// Initialize the state of the given node and all predecessors recursively.
     static void recursive_initialize(State& state, const Node* ptr);
     /// Reset the state of the given node and all successors recursively.
@@ -196,6 +205,9 @@ class Graph {
     /// To unset the objective provide nullptr.
     void set_objective(ArrayNode* objective_ptr);
 
+    /// Swap the topological indices of the two given decision nodes.
+    void swap_decisions(DecisionNode* x_ptr, DecisionNode* y_ptr);
+
     /// Sort the nodes topologically. This "locks" the model in that nodes cannot
     /// be added to a topologically sorted model without invalidating the topological
     /// ordering.
@@ -270,10 +282,6 @@ class Node {
     /// Commit any changing updates to the node.
     virtual void commit(State& state) const = 0;
 
-    /// Return true if the node's state is deterministic - that is it's uniquely
-    /// derived from its predecessors. Defaults to `true`, except for decisions.
-    virtual bool deterministic_state() const { return true; }
-
     /// Test whether two nodes are equal. Each node class defines equality for
     /// itself but nodes *must* share the same set of
     /// predecessors (permutations are sometimes allowed) and they *must* be the
@@ -340,12 +348,13 @@ class Node {
     /// Nodes are printable
     friend std::ostream& operator<<(std::ostream& os, const Node& node);
 
-    friend void Graph::topological_sort();
-    friend void Graph::reset_topological_sort();
     template <class NodeType, class... Args>
     friend NodeType* Graph::emplace_node(Args&&...);
     friend ssize_t Graph::remove_redundant_nodes(bool, double);
     friend ssize_t Graph::remove_unused_nodes(bool);
+    friend void Graph::reset_topological_sort();
+    friend void Graph::swap_decisions(DecisionNode* x_ptr, DecisionNode* y_ptr);
+    friend void Graph::topological_sort();
 
  protected:
     // For use by non-dynamic node constructors.
@@ -455,8 +464,12 @@ NodeType* Graph::emplace_node(Args&&... args) {
 class ArrayNode : public Array, public virtual Node {};
 class DecisionNode : public Decision, public virtual Node {
  public:
-    /// Decision nodes by definition do not have a deterministic state.
-    bool deterministic_state() const final { return false; }
+    /// Set the current state to match the one at the time the given checkpoint was created.
+    virtual void assign_from_checkpoint(State& state, checkpoint_type& checkpoint) const = 0;
+    virtual void assign_from_checkpoint(State& state, checkpoint_type&& checkpoint) const = 0;
+
+    /// Get a checkpoint, an IOU that can be used to return the node to its current state.
+    virtual checkpoint_type checkpoint(State& state) const = 0;
 
     /// Decision can only ever be equal to themselves because they are
     /// independent variables.

dwave/optimization/include/dwave-optimization/nodes.hpp

@@ -1,4 +1,4 @@
-// Copyright 2023 D-Wave Systems Inc.
+// Copyright 2023 D-Wave
 //
 //    Licensed under the Apache License, Version 2.0 (the "License");
 //    you may not use this file except in compliance with the License.
@@ -28,5 +28,6 @@
 #include "dwave-optimization/nodes/numbers.hpp"
 #include "dwave-optimization/nodes/quadratic_model.hpp"
 #include "dwave-optimization/nodes/reduce.hpp"
+#include "dwave-optimization/nodes/set_routines.hpp"
 #include "dwave-optimization/nodes/testing.hpp"
 #include "dwave-optimization/nodes/unaryop.hpp"