Merge branch 'main' into 0.14_python_notebooks_fix

Author: sacpis

.github/pre-commit/spelling_allowlist.txt

@@ -90,6 +90,7 @@ OpenSUSE
 Ou
 POSIX
 PSIRT
+PTSBE
 Pasqal
 Pauli
 Paulis

docs/CMakeLists.txt

@@ -17,7 +17,7 @@
 #   LAUNCH_COMMAND <COMMAND>: the command to launch the test (e.g., mpirun)
 function(add_nvqpp_test TEST_NAME SOURCE_LOCATION)
   cmake_parse_arguments(PARSED_ARGS "" "TARGET;LABELS;SOURCE_DIR;LAUNCH_COMMAND;APPLICATION_ARGS;TARGET_OPTION" "" ${ARGN})
-  set(NVQPP_COMPILE_ARGS "--library-mode ")
+  set(NVQPP_COMPILE_ARGS "--library-mode -I${CMAKE_SOURCE_DIR}/runtime/include")
   if(PARSED_ARGS_TARGET)
     set(NVQPP_COMPILE_ARGS "${NVQPP_COMPILE_ARGS} --target ${PARSED_ARGS_TARGET}")
     if (PARSED_ARGS_TARGET_OPTION)
@@ -65,6 +65,13 @@ add_nvqpp_test(QuickStart_default quick_start.cpp SOURCE_DIR ${CMAKE_CURRENT_SOU
 add_nvqpp_test(FirstObserve using/first_observe.cpp SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/sphinx/snippets/cpp)
 add_nvqpp_test(FirstSample using/first_sample.cpp SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/sphinx/snippets/cpp)
 add_nvqpp_test(Timing using/time.cpp SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/sphinx/snippets/cpp APPLICATION_ARGS "10")
+
+set(PTSBE_CPP_SNIPPET_DIR ${CMAKE_CURRENT_SOURCE_DIR}/sphinx/snippets/cpp/using/examples/ptsbe)
+add_nvqpp_test(PTSBE_BellDepol bell_circuit_under_depol_noise.cpp SOURCE_DIR ${PTSBE_CPP_SNIPPET_DIR})
+add_nvqpp_test(PTSBE_InspectData inspect_execution_data.cpp SOURCE_DIR ${PTSBE_CPP_SNIPPET_DIR})
+add_nvqpp_test(PTSBE_SamplingStrategies sampling_strategies.cpp SOURCE_DIR ${PTSBE_CPP_SNIPPET_DIR})
+add_nvqpp_test(PTSBE_ShotAllocation shot_allocation.cpp SOURCE_DIR ${PTSBE_CPP_SNIPPET_DIR})
+
 if (CUDENSITYMAT_ROOT AND CUDA_FOUND) 
   add_nvqpp_test(Dynamics_Snippets using/backends/dynamics.cpp SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/sphinx/snippets/cpp/ TARGET dynamics LABELS gpu_required)  
   add_nvqpp_test(Dynamics_State_Batching_Snippets using/backends/dynamics_state_batching.cpp SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/sphinx/snippets/cpp/ TARGET dynamics LABELS gpu_required)  
@@ -135,6 +142,13 @@ if (CUDAQ_ENABLE_PYTHON)
   endfunction()
 
   add_pycudaq_test(Intro intro.py)
+
+  set(PTSBE_PY_SNIPPET_DIR ${CMAKE_CURRENT_SOURCE_DIR}/sphinx/snippets/python/using/examples/ptsbe)
+  add_pycudaq_test(PTSBE_BellDepol bell_circuit_under_depol_noise.py SOURCE_DIR ${PTSBE_PY_SNIPPET_DIR})
+  add_pycudaq_test(PTSBE_InspectData inspect_execution_data.py SOURCE_DIR ${PTSBE_PY_SNIPPET_DIR})
+  add_pycudaq_test(PTSBE_SamplingStrategies sampling_strategies.py SOURCE_DIR ${PTSBE_PY_SNIPPET_DIR})
+  add_pycudaq_test(PTSBE_ShotAllocation shot_allocation.py SOURCE_DIR ${PTSBE_PY_SNIPPET_DIR})
+
   if (CUDA_FOUND)
     add_pycudaq_test(EvolveDynamics using/backends/dynamics.py LABELS gpu_required SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/sphinx/snippets/python)
     add_pycudaq_test(EvolveDynamicsStateBatching using/backends/dynamics_state_batching.py LABELS gpu_required SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/sphinx/snippets/python)

docs/sphinx/api/api.rst

@@ -1,10 +1,11 @@
 Code documentation
 ******************
-
+.. |:spellcheck-disable:| replace:: \
 .. toctree::
   :caption: CUDA-Q API
   :maxdepth: 1
 
   C++ API <languages/cpp_api.rst>
   Python API <languages/python_api.rst>
-  Quantum Operations <default_ops.rst>
+  Quantum Operations <default_ops.rst>
+.. |:spellcheck-enable:| replace:: \

docs/sphinx/api/languages/cpp_api.rst

@@ -120,10 +120,6 @@ Common
 .. doxygenclass:: cudaq::sample_result
     :members:
 
-.. _classcudaq_1_1ptsbe_1_1sample__result:
-
-**cudaq::`ptsbe`::sample_result** — Result type returned by ``ptsbe::sample()``, extending `cudaq::sample_result` with optional execution data (trace and per-trajectory info). See ``PTSBESampleResult.h`` and ``PTSBEExecutionData.h``.
-
 .. doxygenstruct:: cudaq::sample_options
     :members:
 
@@ -190,12 +186,12 @@ Noise Modeling
     it is automatically (and silently) stripped from any programs submitted to
     hardware targets.
 
-    :tparam Channel: A subtype of :cpp:class:`cudaq::kraus_channel` that
+    :`tparam` Channel: A subtype of :cpp:class:`cudaq::kraus_channel` that
         implements/defines the desired noise mechanisms as Kraus channels (e.g.
         :cpp:class:`cudaq::depolarization2`). If you want to use a custom
         :cpp:class:`cudaq::kraus_channel` (i.e. not built-in to CUDA-Q), it must
         first be registered *outside the kernel* with
-        :cpp:func:`cudaq::noise_model::register_channel`, like this:
+        `:cpp:func:cudaq::noise_model::register_channel`, like this:
 
         .. code-block:: cpp
 
@@ -218,7 +214,7 @@ Noise Modeling
             cudaq::noise_model noise;
             noise.register_channel<my_custom_kraus_channel_subtype>();
 
-    :param args: The precise argument pack depend on the concrete `Channel` being
+    :`param` `args`: The precise argument pack depend on the concrete `Channel` being
         used. The arguments are a concatenated list of parameters and targets.
         For example, to apply a 2-qubit depolarization channel, which has
         `num_parameters = 1` and `num_targets = 2`, one would write the call
@@ -414,3 +410,101 @@ Namespaces
 .. doxygenfunction:: cudaq::orca::sample(std::vector<std::size_t> &input_state, std::vector<std::size_t> &loop_lengths, std::vector<double> &bs_angles, std::vector<double> &ps_angles, int n_samples = 10000, std::size_t qpu_id = 0)
 .. doxygenfunction:: cudaq::orca::sample_async(std::vector<std::size_t> &input_state, std::vector<std::size_t> &loop_lengths, std::vector<double> &bs_angles, int n_samples = 10000, std::size_t qpu_id = 0)
 .. doxygenfunction:: cudaq::orca::sample_async(std::vector<std::size_t> &input_state, std::vector<std::size_t> &loop_lengths, std::vector<double> &bs_angles, std::vector<double> &ps_angles, int n_samples = 10000, std::size_t qpu_id = 0)
+
+PTSBE
+=====
+
+The ``cudaq::ptsbe`` namespace implements Pre-Trajectory Sampling with Batch
+Execution (PTSBE). For a conceptual overview and usage tutorial see
+:doc:`../../using/examples/ptsbe`.
+
+.. doxygennamespace:: cudaq::ptsbe
+    :desc-only:
+
+Sampling Functions
+-------------------
+
+.. doxygenfunction:: cudaq::ptsbe::sample(const cudaq::noise_model &noise, std::size_t shots, QuantumKernel &&kernel, Args &&...args)
+.. doxygenfunction:: cudaq::ptsbe::sample(const sample_options &options, QuantumKernel &&kernel, Args &&...args)
+.. doxygenfunction:: cudaq::ptsbe::sample_async(const cudaq::noise_model &noise, std::size_t shots, QuantumKernel &&kernel, Args &&...args)
+.. doxygenfunction:: cudaq::ptsbe::sample_async(const sample_options &options, QuantumKernel &&kernel, Args &&...args)
+
+----
+
+Options
+--------
+
+.. doxygenstruct:: cudaq::ptsbe::sample_options
+    :members:
+
+.. doxygenstruct:: cudaq::ptsbe::PTSBEOptions
+    :members:
+
+----
+
+Result Type
+------------
+
+.. doxygenclass:: cudaq::ptsbe::sample_result
+    :members:
+
+----
+
+Trajectory Sampling Strategies
+--------------------------------
+
+.. doxygenstruct:: cudaq::ptsbe::detail::NoisePoint
+    :members:
+
+.. doxygenclass:: cudaq::ptsbe::PTSSamplingStrategy
+    :members:
+
+.. doxygenclass:: cudaq::ptsbe::ProbabilisticSamplingStrategy
+    :members:
+
+.. doxygenclass:: cudaq::ptsbe::OrderedSamplingStrategy
+    :members:
+
+.. doxygenclass:: cudaq::ptsbe::ExhaustiveSamplingStrategy
+    :members:
+
+.. doxygentypedef:: cudaq::ptsbe::TrajectoryPredicate
+
+.. doxygenclass:: cudaq::ptsbe::ConditionalSamplingStrategy
+    :members:
+
+----
+
+Shot Allocation Strategy
+-------------------------
+
+See :ref:`ptsbe-shot-allocation` for full API details.
+
+----
+
+Execution Data
+---------------
+
+.. doxygentypedef:: cudaq::ptsbe::PTSBETrace
+
+.. doxygenstruct:: cudaq::ptsbe::PTSBEExecutionData
+    :members:
+
+.. doxygenstruct:: cudaq::ptsbe::TraceInstruction
+    :members:
+
+.. doxygenenum:: cudaq::ptsbe::TraceInstructionType
+
+----
+
+Trajectory and Selection Types
+--------------------------------
+
+.. doxygenclass:: cudaq::KrausTrajectoryBuilder
+    :members:
+
+.. doxygenstruct:: cudaq::KrausTrajectory
+    :members:
+
+.. doxygenstruct:: cudaq::KrausSelection
+    :members:

docs/sphinx/api/languages/python_api.rst

@@ -95,7 +95,7 @@ Backend Configuration
     it is automatically (and silently) stripped from any programs submitted to
     hardware targets.
 
-    :param error_type: A subtype of :class:`cudaq.KrausChannel` that
+    :`param` error_type: A subtype of :class:`cudaq.KrausChannel` that
         implements/defines the desired noise mechanisms as Kraus channels (e.g.
         :class:`cudaq.Depolarization2`). If you want to use a custom
         :class:`cudaq.KrausChannel` (i.e. not built-in to CUDA-Q), it must
@@ -126,7 +126,7 @@ Backend Configuration
             noise = cudaq.NoiseModel()
             noise.register_channel(CustomNoiseChannel)
 
-    :param parameters: The precise argument pack depend on the concrete
+    :`param` parameters: The precise argument pack depend on the concrete
         :class:`cudaq.KrausChannel` being used. The arguments are a concatenated
         list of parameters and targets.  For example, to apply a 2-qubit
         depolarization channel, which has `num_parameters = 1` and `num_targets =
@@ -137,7 +137,7 @@ Backend Configuration
             q, r = cudaq.qubit(), cudaq.qubit()
             cudaq.apply_noise(cudaq.Depolarization2, 0.1, q, r)
 
-    :param targets: The target qubits on which to apply the noise
+    :`param` targets: The target qubits on which to apply the noise
 
 
 .. automethod:: cudaq::initialize_cudaq
@@ -299,8 +299,8 @@ Optimizers
 
    Run the optimization procedure.
 
-   :param dimensions: The number of parameters to optimize
-   :param function: The objective function to minimize
+   :`param` dimensions: The number of parameters to optimize
+   :`param` function: The objective function to minimize
    :returns: tuple of (optimal_value, optimal_parameters)
 
 .. py:method:: requires_gradients() -> bool
@@ -417,3 +417,81 @@ ORCA Submodule
 =============================
 
 .. automethod:: cudaq.orca::sample
+
+PTSBE Submodule
+=============================
+
+.. _ptsbe_api:
+
+The ``cudaq.ptsbe`` submodule implements Pre-Trajectory Sampling with Batch
+Execution (PTSBE). For a conceptual overview and usage tutorial see
+:doc:`../../using/examples/ptsbe`.
+
+Sampling Functions
+-------------------
+
+.. autofunction:: cudaq.ptsbe.sample
+
+.. autofunction:: cudaq.ptsbe.sample_async
+
+----
+
+Result Type
+------------
+
+.. autoclass:: cudaq.ptsbe.PTSBESampleResult
+    :members:
+
+----
+
+Trajectory Sampling Strategies
+--------------------------------
+
+.. autoclass:: cudaq.ptsbe.PTSSamplingStrategy
+    :members:
+
+.. autoclass:: cudaq.ptsbe.ProbabilisticSamplingStrategy
+    :members:
+
+.. autoclass:: cudaq.ptsbe.OrderedSamplingStrategy
+    :members:
+
+.. autoclass:: cudaq.ptsbe.ExhaustiveSamplingStrategy
+    :members:
+
+----
+
+Shot Allocation Strategy
+-------------------------
+
+.. autoclass:: cudaq.ptsbe.ShotAllocationStrategy
+    :members:
+
+.. autoclass:: cudaq.ptsbe.ShotAllocationType
+    :members:
+
+----
+
+Execution Data
+---------------
+
+.. autoclass:: cudaq.ptsbe.PTSBEExecutionData
+    :members:
+
+.. autoclass:: cudaq.ptsbe.TraceInstruction
+    :members:
+
+.. autoclass:: cudaq.ptsbe.TraceInstructionType
+    :members:
+
+----
+
+Trajectory and Selection Types
+--------------------------------
+
+.. autoclass:: cudaq.ptsbe.KrausTrajectory
+    :members:
+
+.. autoclass:: cudaq.ptsbe.KrausSelection
+    :members:
+