Function sample_async

python/cudaq/runtime/sample.py:198–267

Asynchronously sample the state of the provided kernel `decorator` at the specified number of circuit executions (`shots_count`). When targeting a quantum platform with more than one QPU, the optional `qpu_id` allows for control over which QPU to enable. Will return a future whose r

(decorator,
                 *args,
                 shots_count=1000,
                 explicit_measurements=False,
                 noise_model=None,
                 qpu_id=0)

@trace.traced
def sample_async(decorator,
                 *args,
                 shots_count=1000,
                 explicit_measurements=False,
                 noise_model=None,
                 qpu_id=0):
    """
    Asynchronously sample the state of the provided kernel `decorator` at the
    specified number of circuit executions (`shots_count`). When targeting a
    quantum platform with more than one QPU, the optional `qpu_id` allows for
    control over which QPU to enable. Will return a future whose results can be
    retrieved via `future.get()`.

    Args:
      kernel (:class:`Kernel`): The :class:`Kernel` to execute `shots_count`
          times on the QPU.
      *arguments (Optional[Any]): The concrete values to evaluate the kernel
          function at. Leave empty if the kernel doesn't accept any arguments.
      shots_count (Optional[int]): The number of kernel executions on the
          QPU. Defaults to 1000. Key-word only.
      explicit_measurements (Optional[bool]): A flag to indicate whether or not
          to concatenate measurements in execution order for the returned
          sample result.
      noise_model (Optional[`NoiseModel`]): The optional :class:`NoiseModel`
          to add noise to the kernel execution on the simulator. Defaults to
          an empty noise model.
      `qpu_id` (Optional[int]): The optional identification for which QPU
          on the platform to target. Defaults to zero. Key-word only.

    Returns:
      :class:`AsyncSampleResult`: A dictionary containing the measurement count
          results for the :class:`Kernel`.
    """
    kernel = decorator
    if not isa_kernel_decorator(decorator):
        decorator = mk_decorator(decorator)
    if decorator.formal_arity() != len(args):
        raise RuntimeError(
            "Invalid number of arguments passed to sample_async. " +
            str(len(args)) + " given and " + str(decorator.formal_arity()) +
            " expected.")
    if (not isinstance(shots_count, int)) or (shots_count < 0):
        raise RuntimeError(
            "Invalid `shots_count`. Must be a non-negative number.")
    if (decorator.return_type and
            decorator.return_type != decorator.get_none_type()):
        raise RuntimeError("The `sample_async` API only supports kernels that "
                           "return None (void). Consider using `run_async` for "
                           "kernels that return values.")
    target = cudaq_runtime.get_target()
    num_qpus = target.num_qpus()
    if qpu_id >= num_qpus:
        raise ValueError(f"qpu_id ({qpu_id}) exceeds the number of available "
                         f"QPUs ({num_qpus}).")

    if noise_model:
        if target.is_remote():
            raise ValueError("Noise model is not supported on hardware QPU.")