Operator classes (#2631)

This PR introduces general operator classes in C++. Existing spin ops are not yet replaced, and integration with dynamics will follow in a separate PR.

Author: bettinaheim

.devcontainer/devcontainer.json

@@ -241,7 +241,7 @@
 				"C_Cpp.inlayHints.referenceOperator.enabled": false,
 				"C_Cpp.doxygen.generateOnType": false,
 				"C_Cpp.default.cStandard": "c17",
-				"C_Cpp.default.cppStandard": "c++20",
+				"C_Cpp.default.cppStandard": "c++17",
 				"C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools",
 				"C_Cpp.default.compileCommands": "${workspaceFolder}/build/compile_commands.json",
 				"C_Cpp.default.includePath": [

.github/workflows/config/spelling_allowlist.txt

@@ -193,6 +193,7 @@ discoverable
 discretization
 discretize
 discretized
+eigenbasis
 eigensolver
 eigensolvers
 eigenstate
@@ -202,6 +203,7 @@ eigenvalues
 eigenvector
 eigenvectors
 endian
+endianness
 enqueue
 enqueues
 enqueuing

cmake/Modules/CMakeLists.txt

@@ -11,6 +11,7 @@ set(CONFIG_FILES
   CUDAQEmDefaultConfig.cmake
   CUDAQNloptConfig.cmake
   CUDAQSpinConfig.cmake
+  CUDAQOperatorConfig.cmake
   CUDAQConfig.cmake
   CUDAQEnsmallenConfig.cmake
   CUDAQPlatformDefaultConfig.cmake

cmake/Modules/CUDAQConfig.cmake

@@ -14,6 +14,9 @@ list(APPEND CMAKE_MODULE_PATH "${CUDAQ_CMAKE_DIR}")
 set (CUDAQSpin_DIR "${CUDAQ_CMAKE_DIR}")
 find_dependency(CUDAQSpin REQUIRED)
 
+set (CUDAQOperator_DIR "${CUDAQ_CMAKE_DIR}")
+find_dependency(CUDAQOperator REQUIRED)
+
 set (CUDAQCommon_DIR "${CUDAQ_CMAKE_DIR}")
 find_dependency(CUDAQCommon REQUIRED)
 

cmake/Modules/CUDAQEmDefaultConfig.cmake

@@ -11,6 +11,9 @@ get_filename_component(CUDAQ_EM_CMAKE_DIR "${CMAKE_CURRENT_LIST_FILE}" PATH)
 set (CUDAQSpin_DIR "${CUDAQ_EM_CMAKE_DIR}")
 find_dependency(CUDAQSpin REQUIRED)
 
+set (CUDAQOperator_DIR "${CUDAQ_EM_CMAKE_DIR}")
+find_dependency(CUDAQOperator REQUIRED)
+
 set (CUDAQCommon_DIR "${CUDAQ_EM_CMAKE_DIR}")
 find_dependency(CUDAQCommon REQUIRED)
 

cmake/Modules/CUDAQOperatorConfig.cmake

@@ -0,0 +1,13 @@
+# ============================================================================ #
+# Copyright (c) 2022 - 2025 NVIDIA Corporation & Affiliates.                   #
+# All rights reserved.                                                         #
+#                                                                              #
+# This source code and the accompanying materials are made available under     #
+# the terms of the Apache License 2.0 which accompanies this distribution.     #
+# ============================================================================ #
+
+get_filename_component(CUDAQ_CMAKE_DIR "${CMAKE_CURRENT_LIST_FILE}" PATH)
+
+if(NOT TARGET cudaq::cudaq-operator)
+  include("${CUDAQ_CMAKE_DIR}/CUDAQOperatorTargets.cmake")
+endif()

cmake/Modules/CUDAQPlatformDefaultConfig.cmake

@@ -11,6 +11,9 @@ get_filename_component(CUDAQ_CMAKE_DIR "${CMAKE_CURRENT_LIST_FILE}" PATH)
 set (CUDAQEmDefault_DIR "${CUDAQ_CMAKE_DIR}")
 find_dependency(CUDAQEmDefault REQUIRED)
 
+set (CUDAQOperator_DIR "${CUDAQ_CMAKE_DIR}")
+find_dependency(CUDAQOperator REQUIRED)
+
 set (CUDAQSpin_DIR "${CUDAQ_CMAKE_DIR}")
 find_dependency(CUDAQSpin REQUIRED)
 

cmake/Modules/NVQIRConfig.cmake.in

@@ -12,6 +12,7 @@ include(CMakeFindDependencyMacro)
 get_filename_component(PARENT_DIRECTORY ${NVQIR_CMAKE_DIR} DIRECTORY)
 
 find_dependency(CUDAQSpin REQUIRED HINTS "${PARENT_DIRECTORY}/cudaq")
+find_dependency(CUDAQOperator REQUIRED HINTS "${PARENT_DIRECTORY}/cudaq")
 find_dependency(CUDAQCommon REQUIRED HINTS "${PARENT_DIRECTORY}/cudaq")
 find_package(fmt QUIET)
 if (NOT fmt_FOUND)

python/cudaq/operator/definitions.py

@@ -16,7 +16,7 @@
 
 
 # Operators as defined here (watch out of differences in convention):
-# https://www.dynamiqs.org/python_api/utils/operators/sigmay.html
+# https://www.dynamiqs.org/stable/python_api/utils/operators/create.html
 class operators:
 
     class matrices:

runtime/cudaq/CMakeLists.txt

@@ -40,7 +40,7 @@ if (CUDA_FOUND)
     PRIVATE .)
 
   target_link_libraries(${LIBRARY_NAME}
-    PUBLIC dl cudaq-spin cudaq-common cudaq-nlopt cudaq-ensmallen
+    PUBLIC dl cudaq-spin cudaq-operator cudaq-common cudaq-nlopt cudaq-ensmallen
     PRIVATE nvqir fmt::fmt-header-only CUDA::cudart_static)
 
   target_compile_definitions(${LIBRARY_NAME} PRIVATE CUDAQ_HAS_CUDA)
@@ -52,7 +52,7 @@ else()
     PRIVATE .)
 
   target_link_libraries(${LIBRARY_NAME}
-    PUBLIC dl cudaq-spin cudaq-common cudaq-nlopt cudaq-ensmallen
+    PUBLIC dl cudaq-spin cudaq-operator cudaq-common cudaq-nlopt cudaq-ensmallen
     PRIVATE nvqir fmt::fmt-header-only)
 endif()
 
@@ -61,6 +61,7 @@ add_subdirectory(algorithms)
 add_subdirectory(platform)
 add_subdirectory(builder)
 add_subdirectory(domains)
+add_subdirectory(dynamics)
 
 install(TARGETS ${LIBRARY_NAME} EXPORT cudaq-targets DESTINATION lib)
 

runtime/cudaq/dynamics/CMakeLists.txt

@@ -0,0 +1,49 @@
+# ============================================================================ #
+# Copyright (c) 2022 - 2025 NVIDIA Corporation & Affiliates.                   #
+# All rights reserved.                                                         #
+#                                                                              #
+# This source code and the accompanying materials are made available under     #
+# the terms of the Apache License 2.0 which accompanies this distribution.     #
+# ============================================================================ #
+
+set(LIBRARY_NAME cudaq-operator)
+set (CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wno-ctad-maybe-unsupported")
+set(INTERFACE_POSITION_INDEPENDENT_CODE ON)
+
+set(CUDAQ_OPS_SRC
+  callback.cpp
+  scalar_operators.cpp 
+  spin_operators.cpp
+  boson_operators.cpp
+  fermion_operators.cpp
+  matrix_operators.cpp 
+  product_operators.cpp 
+  operator_sum.cpp 
+  handler.cpp
+  schedule.cpp
+  helpers.cpp
+)
+
+add_library(${LIBRARY_NAME} SHARED ${CUDAQ_OPS_SRC})
+set_property(GLOBAL APPEND PROPERTY CUDAQ_RUNTIME_LIBS ${LIBRARY_NAME})
+target_compile_definitions(${LIBRARY_NAME} PRIVATE -DCUDAQ_INSTANTIATE_TEMPLATES)
+
+target_include_directories(${LIBRARY_NAME} 
+    PUBLIC 
+       $<BUILD_INTERFACE:${CMAKE_SOURCE_DIR}/runtime>
+       $<BUILD_INTERFACE:${CMAKE_SOURCE_DIR}/tpls/eigen>
+       $<INSTALL_INTERFACE:include>
+    PRIVATE .)
+
+set (OPERATOR_DEPENDENCIES "")
+list(APPEND OPERATOR_DEPENDENCIES fmt::fmt-header-only)
+add_openmp_configurations(${LIBRARY_NAME} OPERATOR_DEPENDENCIES)
+
+target_link_libraries(${LIBRARY_NAME} PRIVATE ${OPERATOR_DEPENDENCIES})
+
+install(TARGETS ${LIBRARY_NAME} EXPORT cudaq-operator-targets DESTINATION lib)
+
+install(EXPORT cudaq-operator-targets
+        FILE CUDAQOperatorTargets.cmake
+        NAMESPACE cudaq::
+        DESTINATION lib/cmake/cudaq)