Update libraries for cudaq::spin_op breaking changes (#134)

This PR includes the required CUDA-QX changes that must be applied once
NVIDIA/cuda-quantum#2710 (from CUDA-Q) lands.

For that PR, most of the breaking changes are in C++, but a few Python
tests needed to be updated as well. Python changes will likely be coming
in the near future.

Note that this change actually removes more code than it adds. This is
primarily due to updates in the test code.

Here is a summary of the changes in this PR.

1. Update CMakeLists.txt files to link against `cudaq-operator` instead
of `cudaq-spin` because `cuda-spin` was removed.
2. Make use of `cudaq::spin_op_term` (a product term) where appropriate.
I currently left all the public QEC API's to use `spin_op` (a sum term),
but we may choose to update them to simply `spin_op_term` in the near
future. That would be a CUDA-QX breaking change if we do.
3. Since the new operators no longer store degrees that had implicit
`I`'s in them, we must now clarify whether we want `I` in the terms. For
QEC, this means that we will sometimes use something like
`cudaq::spin_op_term identity(0, get_num_data_qubits())`, but for
Solvers, we have eliminated all implicit `I`'s.
4. Use `get_pauli_word()` instead of `to_string(false)`.
5. Use `evaluate_coefficient()` instead of `get_coefficient()`.
6. Use `.trim()` to remove 0-cofficient terms and `.canonicalize()` to
remove `I` operations from terms. (These new helper functions help
reduce boiler-plate code.)
7. For default-constructed `cudaq::spin_op` objects, clarify whether you
want them to be initialized to the neutral sum term (i.e. 0 =
`spin_op::empty()`) or the neutral product term (i.e. 1 =
`spin_op::identity()`).
8. Change `for_each_term()` to use iterators like `for (const auto &term
: hamiltonian)`.
9. As needed, update code to reflect that `get_qubit_count()` now only
returns the number of _actual_ degrees used in the operator rather than
the "highest degree + 1" that used to be returned. If needed, make use
of the new `min_degree()` and `max_degree()` methods instead.
10. For canned test data, update to use the new serialization format (as
retrieved by `get_data_representation()`).
11. For test data comparisons, be sure to call `canonicalize` on the
test data and/or truth data as necessary in order to ensure correct
comparisons.
12. Don't use `get_raw_data()` anymore.

---------

Signed-off-by: Ben Howe <[email protected]>

Author: bmhowe23

.cudaq_version

@@ -1,6 +1,6 @@
 {
   "cudaq": {
     "repository": "NVIDIA/cuda-quantum",
-    "ref": "3ac999f0e34a2e84989c6fc80418f93feec6784f"
+    "ref": "c53f77436f306f19e412015049dfafb7ae80a690"
   }
 }

.github/workflows/scripts/build_cudaq.sh

@@ -115,8 +115,8 @@ index 7b7541d..2261334 100644
      if (NOT Python_FOUND)
        message(FATAL_ERROR "find_package(Python) not run?")
      endif()
--    target_link_libraries(cudaq-pyscf PRIVATE Python::Python pybind11::pybind11 cudaq-chemistry cudaq-spin cudaq cudaq-py-utils)
-+    target_link_libraries(cudaq-pyscf PRIVATE Python::Module pybind11::pybind11 cudaq-chemistry cudaq-spin cudaq cudaq-py-utils)
+-    target_link_libraries(cudaq-pyscf PRIVATE Python::Python pybind11::pybind11 cudaq-chemistry cudaq-operator cudaq cudaq-py-utils)
++    target_link_libraries(cudaq-pyscf PRIVATE Python::Module pybind11::pybind11 cudaq-chemistry cudaq-operator cudaq cudaq-py-utils)
  endif()
  install(TARGETS cudaq-pyscf DESTINATION lib/plugins)'
 

libs/qec/lib/CMakeLists.txt

@@ -43,7 +43,7 @@ target_link_libraries(${LIBRARY_NAME}
   PUBLIC 
     cudaqx-core
     cudaq::cudaq 
-    cudaq::cudaq-spin
+    cudaq::cudaq-operator
   PRIVATE
     cudaq::cudaq-common
 )

libs/qec/lib/codes/repetition.cpp

@@ -1,5 +1,5 @@
-/****************************************************************-*- C++ -*-****
- * Copyright (c) 2024 NVIDIA Corporation & Affiliates.                         *
+/*******************************************************************************
+ * Copyright (c) 2024 - 2025 NVIDIA Corporation & Affiliates.                  *
  * All rights reserved.                                                        *
  *                                                                             *
  * This source code and the accompanying materials are made available under    *
@@ -31,17 +31,19 @@ repetition::repetition(const heterogeneous_map &options) : code() {
   operation_encodings.insert(std::make_pair(operation::prep0, prep0));
   operation_encodings.insert(std::make_pair(operation::prep1, prep1));
 
+  // "IIII..." (identity term for each data qubit)
+  cudaq::spin_op_term identity(0, get_num_data_qubits());
+
   // Default Stabilizers should be Zi-1 Zi
   for (std::size_t i = 1; i < get_num_data_qubits(); i++) {
-    m_stabilizers.push_back(cudaq::spin::i(get_num_data_qubits() - 1) *
-                            cudaq::spin::z(i - 1) * cudaq::spin::z(i));
+    m_stabilizers.push_back(identity * cudaq::spin::z(i - 1) *
+                            cudaq::spin::z(i));
   }
 
   // Default Logical Observable is ZI...I
   // This class is only for Z basis experiments
   // so there is no X observable included.
-  cudaq::spin_op Lz = cudaq::spin::z(0);
-  Lz = Lz * cudaq::spin::i(get_num_data_qubits() - 1);
+  cudaq::spin_op Lz = cudaq::spin::z(0) * identity;
 
   m_pauli_observables.push_back(Lz);
 

libs/qec/lib/decoders/plugins/example/CMakeLists.txt

@@ -33,7 +33,7 @@ target_link_libraries(${MODULE_NAME}
   PUBLIC
     cudaqx-core
     cudaq::cudaq
-    cudaq::cudaq-spin
+    cudaq::cudaq-operator
   PRIVATE
     cudaq::cudaq-common
     cudaq-qec

libs/qec/lib/stabilizer_utils.cpp

@@ -11,9 +11,8 @@ namespace cudaq::qec {
 // Sort the stabilizers by the occurrence of 'Z' first, then by 'X'.
 // An earlier occurrence is considered "less".
 // Example: a = "ZZX", b = "XXZ" -> a < b
-static bool spinOpComparator(const cudaq::spin_op &a, const cudaq::spin_op &b) {
-  auto astr = a.to_string(false);
-  auto bstr = b.to_string(false);
+static bool spinOpComparatorStr(const std::string &astr,
+                                const std::string &bstr) {
   auto zIdxA = astr.find_first_of("Z");
   auto zIdxB = bstr.find_first_of("Z");
   if (zIdxA == std::string::npos) {
@@ -32,6 +31,12 @@ static bool spinOpComparator(const cudaq::spin_op &a, const cudaq::spin_op &b) {
   return zIdxA < zIdxB;
 }
 
+static bool spinOpComparator(const cudaq::spin_op &a, const cudaq::spin_op &b) {
+  auto astr = a.begin()->get_pauli_word();
+  auto bstr = b.begin()->get_pauli_word();
+  return spinOpComparatorStr(astr, bstr);
+}
+
 static bool isStabilizerSorted(const std::vector<cudaq::spin_op> &ops) {
   return std::is_sorted(ops.begin(), ops.end(), spinOpComparator);
 }
@@ -49,43 +54,36 @@ to_parity_matrix(const std::vector<cudaq::spin_op> &stabilizers,
   if (stabilizers.empty())
     return cudaqx::tensor<uint8_t>();
 
-  // Stabilizers must be sorted prior to use, but they are "const" into this
-  // function. First check to see if they are already sorted, and if so, proceed
-  // without making any copies. Otherwise make a copy, sort the copy, and make
-  // the downstream code use the sorted copy.
-  const std::vector<cudaq::spin_op> *p_stabilizers = &stabilizers;
-  std::vector<cudaq::spin_op> stabilizers_copy; // only use if necessary
-  if (!isStabilizerSorted(stabilizers)) {
-    // Make a copy and sort them
-    stabilizers_copy = stabilizers;
-    sortStabilizerOps(stabilizers_copy);
-    p_stabilizers = &stabilizers_copy;
-  }
+  std::vector<std::string> stab_strings;
+  for (auto &s : stabilizers)
+    stab_strings.emplace_back(s.begin()->get_pauli_word());
+  std::sort(stab_strings.begin(), stab_strings.end(), spinOpComparatorStr);
 
+  auto numQubits = stab_strings[0].size();
+  auto numStabilizers = stab_strings.size();
   if (type == stabilizer_type::XZ) {
-    auto numQubits = (*p_stabilizers)[0].num_qubits();
-    cudaqx::tensor<uint8_t> t({p_stabilizers->size(), 2 * numQubits});
+    cudaqx::tensor<uint8_t> t({numStabilizers, 2 * numQubits});
     // Start by counting the number of Z spin_ops
     std::size_t numZRows = 0;
-    for (auto &op : *p_stabilizers)
-      if (op.to_string(false).find("Z") != std::string::npos)
+    for (const auto &op_str : stab_strings)
+      if (op_str.find("Z") != std::string::npos)
         numZRows++;
       else
         break;
 
     // Need to shift Z bits left
     for (std::size_t row = 0; row < numZRows; row++) {
       for (std::size_t i = numQubits; i < 2 * numQubits; i++) {
-        if ((*p_stabilizers)[row].get_raw_data().first[0][i])
+        if (stab_strings[row][i - numQubits] == 'Z')
           t.at({row, i - numQubits}) = 1;
       }
     }
 
-    auto numXRows = p_stabilizers->size() - numZRows;
+    auto numXRows = numStabilizers - numZRows;
 
     for (std::size_t row = 0; row < numXRows; row++) {
       for (std::size_t i = 0; i < numQubits; i++) {
-        if ((*p_stabilizers)[numZRows + row].get_raw_data().first[0][i])
+        if (stab_strings[numZRows + row][i] == 'X')
           t.at({numZRows + row, i + numQubits}) = 1;
       }
     }
@@ -94,11 +92,10 @@ to_parity_matrix(const std::vector<cudaq::spin_op> &stabilizers,
   }
 
   if (type == stabilizer_type::Z) {
-    auto numQubits = (*p_stabilizers)[0].num_qubits();
     // Start by counting the number of Z spin_ops
     std::size_t numZRows = 0;
-    for (auto &op : *p_stabilizers)
-      if (op.to_string(false).find("Z") != std::string::npos)
+    for (const auto &op_str : stab_strings)
+      if (op_str.find("Z") != std::string::npos)
         numZRows++;
       else
         break;
@@ -109,32 +106,31 @@ to_parity_matrix(const std::vector<cudaq::spin_op> &stabilizers,
     cudaqx::tensor<uint8_t> ret({numZRows, numQubits});
     for (std::size_t row = 0; row < numZRows; row++) {
       for (std::size_t i = numQubits; i < 2 * numQubits; i++) {
-        if ((*p_stabilizers)[row].get_raw_data().first[0][i])
+        if (stab_strings[row][i - numQubits] == 'Z')
           ret.at({row, i - numQubits}) = 1;
       }
     }
 
     return ret;
   }
 
-  auto numQubits = (*p_stabilizers)[0].num_qubits();
   // Start by counting the number of Z spin_ops
   std::size_t numZRows = 0;
-  for (auto &op : *p_stabilizers)
-    if (op.to_string(false).find("Z") != std::string::npos)
+  for (const auto &op_str : stab_strings)
+    if (op_str.find("Z") != std::string::npos)
       numZRows++;
     else
       break;
 
-  auto numXRows = p_stabilizers->size() - numZRows;
+  auto numXRows = numStabilizers - numZRows;
 
   if (numXRows == 0)
     return cudaqx::tensor<uint8_t>();
 
   cudaqx::tensor<uint8_t> ret({numXRows, numQubits});
   for (std::size_t row = 0; row < numXRows; row++) {
     for (std::size_t i = 0; i < numQubits; i++) {
-      if ((*p_stabilizers)[numZRows + row].get_raw_data().first[0][i])
+      if (stab_strings[numZRows + row][i] == 'X')
         ret.at({row, i}) = 1;
     }
   }

libs/qec/python/bindings/type_casters.h

@@ -1,5 +1,5 @@
-/*******************************************************************************
- * Copyright (c) 2022 - 2023 NVIDIA Corporation & Affiliates.                  *
+/****************************************************************-*- C++ -*-****
+ * Copyright (c) 2022 - 2025 NVIDIA Corporation & Affiliates.                  *
  * All rights reserved.                                                        *
  *                                                                             *
  * This source code and the accompanying materials are made available under    *
@@ -23,14 +23,14 @@ struct type_caster<cudaq::spin_op> {
       return false;
     auto data = src.attr("serialize")().cast<std::vector<double>>();
     auto numQubits = src.attr("get_qubit_count")().cast<std::size_t>();
-    value = cudaq::spin_op(data, numQubits);
+    value = cudaq::spin_op(data);
     return true;
   }
 
   static handle cast(cudaq::spin_op v, return_value_policy /*policy*/,
                      handle /*parent*/) {
     py::object tv_py = py::module::import("cudaq").attr("SpinOperator")(
-        v.getDataRepresentation(), v.num_qubits()); // Construct new python obj
+        v.get_data_representation()); // Construct new python obj
     return tv_py.release();
   }
 };

libs/qec/unittests/backend-specific/stim/test_qec_stim.cpp

@@ -16,7 +16,8 @@
 
 TEST(QECCodeTester, checkRepetitionNoiseStim) {
 
-  auto repetition = cudaq::qec::get_code("repetition", {{"distance", 9}});
+  auto repetition = cudaq::qec::get_code(
+      "repetition", cudaqx::heterogeneous_map{{"distance", 9}});
   {
     cudaq::set_random_seed(13);
     cudaq::noise_model noise;

libs/qec/unittests/test_qec.cpp

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2024 NVIDIA Corporation & Affiliates.                         *
+ * Copyright (c) 2024 - 2025 NVIDIA Corporation & Affiliates.                  *
  * All rights reserved.                                                        *
  *                                                                             *
  * This source code and the accompanying materials are made available under    *
@@ -420,14 +420,15 @@ TEST(QECCodeTester, checkRepetition) {
     // must provide distance
     EXPECT_THROW(cudaq::qec::get_code("repetition"), std::runtime_error);
   }
-  auto repetition = cudaq::qec::get_code("repetition", {{"distance", 9}});
+  auto repetition = cudaq::qec::get_code(
+      "repetition", cudaqx::heterogeneous_map{{"distance", 9}});
 
   {
     auto stabilizers = repetition->get_stabilizers();
 
     std::vector<std::string> actual_stabs;
     for (auto &s : stabilizers)
-      actual_stabs.push_back(s.to_string(false));
+      actual_stabs.push_back(s.begin()->get_pauli_word());
 
     std::vector<std::string> expected_strings = {
         "ZZIIIIIII", "IZZIIIIII", "IIZZIIIII", "IIIZZIIII",
@@ -512,7 +513,8 @@ TEST(QECCodeTester, checkSurfaceCode) {
   }
   {
     // with default stabilizers
-    auto surf_code = cudaq::qec::get_code("surface_code", {{"distance", 3}});
+    auto surf_code = cudaq::qec::get_code(
+        "surface_code", cudaqx::heterogeneous_map{{"distance", 3}});
     cudaqx::tensor<uint8_t> parity = surf_code->get_parity();
     cudaqx::tensor<uint8_t> parity_x = surf_code->get_parity_x();
     cudaqx::tensor<uint8_t> parity_z = surf_code->get_parity_z();
@@ -668,7 +670,8 @@ TEST(QECCodeTester, checkSteaneSPAM) {
 
 TEST(QECCodeTester, checkRepetitionSPAM) {
   // only Z basis for repetition
-  auto repetition = cudaq::qec::get_code("repetition", {{"distance", 9}});
+  auto repetition = cudaq::qec::get_code(
+      "repetition", cudaqx::heterogeneous_map{{"distance", 9}});
   EXPECT_TRUE(noiseless_logical_SPAM_test(*repetition,
                                           cudaq::qec::operation::prep0, 0));
   EXPECT_TRUE(noiseless_logical_SPAM_test(*repetition,
@@ -681,7 +684,8 @@ TEST(QECCodeTester, checkRepetitionSPAM) {
 
 TEST(QECCodeTester, checkSurfaceCodeSPAM) {
   // Must compile with stim for larger distances
-  auto surf_code = cudaq::qec::get_code("surface_code", {{"distance", 3}});
+  auto surf_code = cudaq::qec::get_code(
+      "surface_code", cudaqx::heterogeneous_map{{"distance", 3}});
   EXPECT_TRUE(
       noiseless_logical_SPAM_test(*surf_code, cudaq::qec::operation::prep0, 0));
   EXPECT_TRUE(

libs/solvers/lib/CMakeLists.txt

@@ -46,7 +46,7 @@ target_link_libraries(cudaq-solvers
   PUBLIC
     cudaqx-core
     cudaq::cudaq
-    cudaq::cudaq-spin
+    cudaq::cudaq-operator
   PRIVATE
     cudaq::cudaq-common
     nlohmann_json::nlohmann_json