First pass of support for C++ operators

.devcontainer/devcontainer.json

@@ -241,9 +241,9 @@
 				"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.compileCommands": "${workspaceFolder}/build/debug/compile_commands.json",
 				"C_Cpp.default.includePath": [
 					"${workspaceFolder}/**",
 					"${CUDAQ_INSTALL_PREFIX}/**",

.github/workflows/config/spelling_allowlist.txt

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

.github/workflows/publishing.yml

@@ -839,7 +839,7 @@ jobs:
                   fi; \
               done`
 
-          rm -rf examples applications targets && mv github-repo/docs/sphinx/examples examples && mv github-repo/docs/sphinx/applications applications && mv github-repo/docs/sphinx/targets targets
+          rm -rf examples applications targets snippets && mv github-repo/docs/sphinx/examples examples && mv github-repo/docs/sphinx/applications applications && mv github-repo/docs/sphinx/targets targets && mv github-repo/docs/sphinx/snippets/python snippets
           mv github-repo/docs/notebook_validation.py .
           GITHUB_STEP_SUMMARY=$GITHUB_STEP_SUMMARY \
           bash github-repo/scripts/validate_container.sh $backends_to_test | tee /tmp/validation.out

.github/workflows/python_wheels.yml

@@ -260,7 +260,9 @@ jobs:
             done
 
       - name: Run Python MPI tests
-        if: matrix.os_image == 'redhat/ubi9:9.2'
+        # Temporary disabling this test for the bug bash
+        # matrix.os_image == 'redhat/ubi9:9.2'
+        if: false
         uses: ./.github/actions/run-in-docker
         with:
           image: wheel_validation:local

CMakeLists.txt

@@ -151,6 +151,9 @@ endif()
 if(NOT CUTENSORNET_ROOT)
   SET(CUTENSORNET_ROOT "$ENV{CUQUANTUM_INSTALL_PREFIX}")
 endif()
+if(NOT CUDENSITYMAT_ROOT)
+  SET(CUDENSITYMAT_ROOT "$ENV{CUQUANTUM_INSTALL_PREFIX}")
+endif()
 if(NOT CUTENSOR_ROOT)
   SET(CUTENSOR_ROOT "$ENV{CUTENSOR_INSTALL_PREFIX}")
 endif()

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)

docker/build/devdeps.ext.Dockerfile

@@ -181,7 +181,3 @@ ENV CUTENSOR_INSTALL_PREFIX="$CUTENSOR_INSTALL_PREFIX"
 ENV CUTENSOR_ROOT="$CUTENSOR_INSTALL_PREFIX"
 ENV LD_LIBRARY_PATH="$CUTENSOR_INSTALL_PREFIX/lib:$LD_LIBRARY_PATH"
 ENV CPATH="$CUTENSOR_INSTALL_PREFIX/include:$CPATH"
-
-# Active MPI support for the cuTensorNet library
-RUN cd "$CUQUANTUM_INSTALL_PREFIX/distributed_interfaces/" && source activate_mpi_cutn.sh
-ENV CUTENSORNET_COMM_LIB="$CUQUANTUM_INSTALL_PREFIX/distributed_interfaces/libcutensornet_distributed_interface_mpi.so"

docs/sphinx/examples/cpp/dynamics/cavity_qed.cpp

@@ -0,0 +1,144 @@
+/*******************************************************************************
+ * 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.    *
+ ******************************************************************************/
+
+// Compile and run with:
+// ```
+// nvq++ --target dynamics cavity_qed.cpp -o a.out && ./a.out
+// ```
+
+#include "cudaq/algorithms/evolve.h"
+#include "cudaq/dynamics_integrators.h"
+#include "cudaq/operators.h"
+#include "export_csv_helper.h"
+#include <cudaq.h>
+
+int main() {
+
+  // Dimension of our composite quantum system:
+  // subsystem 0 (atom) has 2 levels (ground and excited states).
+  // subsystem 1 (cavity) has 10 levels (Fock states, representing photon number
+  // states).
+  std::map<int, int> dimensions{{0, 2}, {1, 10}};
+
+  // For the cavity subsystem 1
+  // We create the annihilation (a) and creation (a+) operators.
+  // These operators lower and raise the photon number, respectively.
+  auto a = cudaq::boson_operator::annihilate(1);
+  auto a_dag = cudaq::boson_operator::create(1);
+
+  // For the atom subsystem 0
+  // We create the annihilation (sm) and creation (sm_dag) operators.
+  // These operators lower and raise the excitation number, respectively.
+  auto sm = cudaq::boson_operator::annihilate(0);
+  auto sm_dag = cudaq::boson_operator::create(0);
+
+  // Number operators
+  // These operators count the number of excitations.
+  // For the atom (subsytem 0) and the cavity (subsystem 1) they give the
+  // population in each subsystem.
+  auto atom_occ_op = cudaq::matrix_operator::number(0);
+  auto cavity_occ_op = cudaq::matrix_operator::number(1);
+
+  // Hamiltonian
+  // The hamiltonian models the dynamics of the atom-cavity (cavity QED) system
+  // It has 3 parts:
+  // 1. Caity energy: 2 * pi * photon_number_operator -> energy proportional to
+  // the number of photons.
+  // 2. Atomic energy: 2 * pi * atom_number_operator -> energy proportional to
+  // the atomic excitation.
+  // 3. Atomic-cavity interaction: 2 * pi * 0.25 * (sm * a_dag + sm_dag * a) ->
+  // represents the exchange of energy between the atom and the cavity. It is
+  // analogous to the Jaynes-Cummings model in cavity QED.
+  auto hamiltonian = (2 * M_PI * cavity_occ_op) + (2 * M_PI * atom_occ_op) +
+                     (2 * M_PI * 0.25 * (sm * a_dag + sm_dag * a));
+
+  // Build the initial state
+  // Atom (sub-system 0) in ground state.
+  // Cavity (sub-system 1) has 5 photons (Fock space).
+  // The overall Hilbert space is 2 * 10 = 20.
+  const int num_photons = 5;
+  std::vector<std::complex<double>> initial_state_vec(20, 0.0);
+  // The index is chosen such that the atom is in the ground state while the
+  // cavity is in the Fock state with 5 photons.
+  initial_state_vec[dimensions[0] * num_photons] = 1;
+
+  // Define a time evolution schedule
+  // We define a time grid from 0 to 10 (in arbitray time units) with 201 time
+  // steps This schedule is used by the integrator to simulate the dynamics.
+  const int num_steps = 201;
+  auto steps = cudaq::linspace(0.0, 10.0, num_steps);
+  cudaq::Schedule schedule(steps);
+
+  // Create a CUDA quantum state
+  // The initial state is converted into a quantum state object for evolution.
+  auto rho0 = cudaq::state::from_data(initial_state_vec);
+
+  // Numerical integrator
+  // Here we choose a Runge-Kutta method for time evolution.
+  // dt defines the time step for the numerical integration, and order 4
+  // indicates a 4th order method.
+  std::shared_ptr<cudaq::RungeKuttaIntegrator> integrator =
+      std::make_shared<cudaq::RungeKuttaIntegrator>();
+  integrator->dt = 0.01;
+  integrator->order = 4;
+
+  // Evolve without collapse operators
+  // This evolution is ideal (closed system) dynamics governed solely by the
+  // Hamiltonian. The expectation values of the observables (cavity photon
+  // number and atom excitation probability) are recorded.
+  cudaq::evolve_result evolve_result =
+      cudaq::evolve(hamiltonian, dimensions, schedule, rho0, integrator, {},
+                    {cavity_occ_op, atom_occ_op}, true);
+
+  // Adding dissipation
+  // To simulate a realistic scenario, we introduce decay (dissipation).
+  // Here, the collapse operator represents photon loss from the cavity.
+  constexpr double decay_rate = 0.1;
+  auto collapse_operator = std::sqrt(decay_rate) * a;
+  // Evolve with the collapse operator to incorporate the effect of decay.
+  cudaq::evolve_result evolve_result_decay =
+      cudaq::evolve(hamiltonian, dimensions, schedule, rho0, integrator,
+                    {collapse_operator}, {cavity_occ_op, atom_occ_op}, true);
+
+  // Lambda to extract expectation values for a given observable index
+  // Here, index 0 corresponds to the cavity photon number and index 1
+  // corresponds to the atom excitation probability.
+  auto get_expectation = [](int idx,
+                            const auto &result) -> std::vector<double> {
+    std::vector<double> expectations;
+
+    auto all_exps = result.get_expectation_values().value();
+    for (auto exp_vals : all_exps) {
+      expectations.push_back((double)exp_vals[idx]);
+    }
+    return expectations;
+  };
+
+  // Retrieve expectation values from both the ideal and decaying evolutions.
+  auto ideal_result0 = get_expectation(0, evolve_result);
+  auto ideal_result1 = get_expectation(1, evolve_result);
+  auto decay_result0 = get_expectation(0, evolve_result_decay);
+  auto decay_result1 = get_expectation(1, evolve_result_decay);
+
+  // Export the results to CSV files
+  // "cavity_qed_ideal_result.csv" contains the ideal evolution results.
+  // "cavity_qed_decay_result.csv" contains the evolution results with cavity
+  // decay.
+  export_csv("cavity_qed_ideal_result.csv", "time", steps,
+             "cavity_photon_number", ideal_result0,
+             "atom_excitation_probability", ideal_result1);
+  export_csv("cavity_qed_decay_result.csv", "time", steps,
+             "cavity_photon_number", decay_result0,
+             "atom_excitation_probability", decay_result1);
+
+  std::cout << "Simulation complete. The results are saved in "
+               "cavity_qed_ideal_result.csv "
+               "and cavity_qed_decay_result.csv files."
+            << std::endl;
+  return 0;
+}