qcs 0.26.1

# This file is automatically generated by pyo3_stub_gen
# ruff: noqa: E501, F401

import builtins
import collections.abc
import datetime
import typing
from qcs_sdk import QcsSdkError
from qcs_sdk.client import QCSClient
from qcs_sdk.qpu import MemoryValues

@typing.final
class APIExecutionOptions:
    r"""
    Options available when executing a job on a QPU, particular to the execution service's API.
    
    This is a conventent alias for [`InnerApiExecutionOptions`] which provides a builder.
    
    Use [`Default`] to get a reasonable set of defaults, or start with [`ApiExecutionOptionsBuilder`]
    to build a custom set of options.
    """
    @property
    def bypass_settings_protection(self) -> builtins.bool:
        r"""
        Get the configured `bypass_settings_protection` value.
        """
    @property
    def timeout(self) -> typing.Optional[QpuApiDuration]:
        r"""
        Get the configured `timeout` value.
        
        Note, this is the timeout while running a job; the job will be evicted from
        the hardware once this time has elapsed.
        
        If unset, the job's estimated duration will be used;
        if the job does not have an estimated duration, the default
        timeout is selected by the service.
        
        The service may also enforce a maximum value for this field.
        """
    def __new__(cls, bypass_settings_protection: builtins.bool = False, timeout: typing.Optional[datetime.timedelta] = None) -> APIExecutionOptions: ...
    def __repr__(self) -> builtins.str:
        r"""
        Implements `__repr__` for Python in terms of the Rust
        [`Debug`](std::fmt::Debug) implementation.
        """
    @staticmethod
    def builder() -> APIExecutionOptionsBuilder:
        r"""
        Get an [`ExecutionOptionsBuilder`] that can be used to build a custom [`ExecutionOptions`].
        """
    @staticmethod
    def default() -> APIExecutionOptions: ...

@typing.final
class APIExecutionOptionsBuilder:
    r"""
    Builder for [`ApiExecutionOptions`](struct.ApiExecutionOptions.html).
    """
    @property
    def bypass_settings_protection(self) -> typing.Never:
        r"""
        DO NOT CALL THIS METHOD.
        
        `mypy` requires write-only properties to have a getter,
        but this method is not actually available at runtime.
        """
    @bypass_settings_protection.setter
    def bypass_settings_protection(self, value: builtins.bool) -> None: ...
    @property
    def timeout(self) -> typing.Never:
        r"""
        DO NOT CALL THIS METHOD.
        
        `mypy` requires write-only properties to have a getter,
        but this method is not actually available at runtime.
        """
    @timeout.setter
    def timeout(self, value: typing.Optional[QpuApiDuration]) -> None: ...
    def __new__(cls) -> APIExecutionOptionsBuilder: ...
    def build(self) -> APIExecutionOptions: ...
    @staticmethod
    def default() -> APIExecutionOptionsBuilder: ...

class BuildOptionsError(QpuApiError):
    r"""
    Errors building execution options.
    """
    ...

class ConnectionStrategy:
    r"""
    The connection strategy to use when submitting and retrieving jobs from a QPU.
    """
    def __getnewargs__(self) -> tuple[str] | tuple[()]: ...
    def __repr__(self) -> builtins.str:
        r"""
        Implements `__repr__` for Python in terms of the Rust
        [`Debug`](std::fmt::Debug) implementation.
        """
    @staticmethod
    def default() -> ConnectionStrategy: ...
    def get_endpoint_id(self) -> builtins.str: ...
    @typing.final
    class DirectAccess(ConnectionStrategy):
        r"""
        Connect directly to the default endpoint, bypassing the gateway. Should only be used when you
        have direct network access and an active reservation.
        """
        __match_args__ = ()
        def __getitem__(self, key: builtins.int) -> typing.Any: ...
        def __len__(self) -> builtins.int: ...
        def __new__(cls) -> ConnectionStrategy.DirectAccess: ...
    
    @typing.final
    class EndpointAddress(ConnectionStrategy):
        r"""
        Connect directly to a specific endpoint by its gRPC address, bypassing the gateway.
        
        Should only be used when you have direct network access.
        """
        __match_args__ = ("_0",)
        @property
        def _0(self) -> builtins.str: ...
        def __getitem__(self, key: builtins.int) -> typing.Any: ...
        def __len__(self) -> builtins.int: ...
        def __new__(cls, _0: builtins.str) -> ConnectionStrategy.EndpointAddress: ...
        
    @typing.final
    class EndpointId(ConnectionStrategy):
        r"""
        Connect directly to a specific endpoint using its ID.
        """
        __match_args__ = ("_0",)
        @property
        def _0(self) -> builtins.str: ...
        def __getitem__(self, key: builtins.int) -> typing.Any: ...
        def __len__(self) -> builtins.int: ...
        def __new__(cls, _0: builtins.str) -> ConnectionStrategy.EndpointId: ...
    
    @typing.final
    class Gateway(ConnectionStrategy):
        r"""
        Connect through the publicly accessible gateway.
        """
        __match_args__ = ()
        def __getitem__(self, key: builtins.int) -> typing.Any: ...
        def __len__(self) -> builtins.int: ...
        def __new__(cls) -> ConnectionStrategy.Gateway: ...
    

@typing.final
class ExecutionOptions:
    r"""
    Options available when executing a job on a QPU.
    
    Use [`Default`] to get a reasonable set of defaults, or start with [`ExecutionOptionsBuilder`]
    to build a custom set of options.
    """
    @property
    def api_options(self) -> typing.Optional[APIExecutionOptions]: ...
    @property
    def connection_strategy(self) -> ConnectionStrategy:
        r"""
        The [`ConnectionStrategy`] to use to establish a connection to the QPU.
        """
    @property
    def timeout_seconds(self) -> typing.Optional[builtins.float]: ...
    def __eq__(self, other: builtins.object) -> builtins.bool: ...
    def __getnewargs__(self) -> tuple[ConnectionStrategy, typing.Optional[datetime.timedelta], typing.Optional[APIExecutionOptions]]: ...
    def __new__(cls, connection_strategy: ConnectionStrategy = ..., timeout: typing.Optional[datetime.timedelta] = ..., api_options: typing.Optional[APIExecutionOptions] = None) -> ExecutionOptions: ...
    def __repr__(self) -> builtins.str:
        r"""
        Implements `__repr__` for Python in terms of the Rust
        [`Debug`](std::fmt::Debug) implementation.
        """
    @staticmethod
    def builder() -> ExecutionOptionsBuilder: ...
    @staticmethod
    def default() -> ExecutionOptions: ...

@typing.final
class ExecutionOptionsBuilder:
    r"""
    Builder for [`ExecutionOptions`](struct.ExecutionOptions.html).
    """
    @property
    def api_options(self) -> typing.Never:
        r"""
        DO NOT CALL THIS METHOD.
        
        `mypy` requires write-only properties to have a getter,
        but this method is not actually available at runtime.
        """
    @api_options.setter
    def api_options(self, value: typing.Optional[APIExecutionOptions]) -> None: ...
    @property
    def connection_strategy(self) -> typing.Never:
        r"""
        DO NOT CALL THIS METHOD.
        
        `mypy` requires write-only properties to have a getter,
        but this method is not actually available at runtime.
        """
    @connection_strategy.setter
    def connection_strategy(self, value: ConnectionStrategy) -> None: ...
    @property
    def timeout_seconds(self) -> typing.Never:
        r"""
        DO NOT CALL THIS METHOD.
        
        `mypy` requires write-only properties to have a getter,
        but this method is not actually available at runtime.
        """
    @timeout_seconds.setter
    def timeout_seconds(self, value: typing.Optional[builtins.float]) -> None: ...
    def __new__(cls) -> ExecutionOptionsBuilder: ...
    def build(self) -> ExecutionOptions: ...
    @staticmethod
    def default() -> ExecutionOptionsBuilder: ...

@typing.final
class ExecutionResult:
    r"""
    Execution readout data from a particular memory location.
    """
    @property
    def data(self) -> builtins.list[builtins.int] | builtins.list[builtins.complex]:
        r"""
        The result data for all shots by the particular memory location.
        """
    @property
    def dtype(self) -> builtins.str:
        r"""
        The type of the result data (as a `numpy` `dtype`).
        """
    @property
    def shape(self) -> builtins.list[builtins.int]:
        r"""
        The shape of the result data.
        """
    def __getnewargs__(self) -> tuple[builtins.list[builtins.int] | builtins.list[builtins.complex]]: ...
    def __new__(cls, register: typing.Sequence[builtins.int] | typing.Sequence[builtins.complex]) -> ExecutionResult: ...
    @staticmethod
    def from_register(register: typing.Sequence[builtins.int] | typing.Sequence[builtins.complex]) -> ExecutionResult:
        r"""
        Build an `ExecutionResult` from a `Register`.
        """

@typing.final
class ExecutionResults:
    r"""
    Execution readout data for all memory locations.
    """
    @property
    def buffers(self) -> builtins.dict[builtins.str, ExecutionResult]:
        r"""
        The readout results of execution, mapping a published filter node to its data.
        
        See `TranslationResult.ro_sources` which provides the mapping from the filter node name
        to the name of the memory declaration in the source program.
        """
    @property
    def execution_duration_microseconds(self) -> typing.Optional[builtins.int]:
        r"""
        The time spent executing the program.
        """
    @property
    def memory(self) -> builtins.dict[builtins.str, MemoryValues]:
        r"""
        The final state of memory for parameters that were read from and written to during
        the execution of the program.
        """
    def __new__(cls, buffers: typing.Mapping[builtins.str, ExecutionResult], memory: typing.Mapping[builtins.str, MemoryValues], execution_duration_microseconds: typing.Optional[builtins.int] = None) -> ExecutionResults: ...

@typing.final
class QpuApiDuration:
    r"""
    The duration of an API call.
    """
    @property
    def nanos(self) -> builtins.int: ...
    @property
    def seconds(self) -> builtins.int: ...
    def __new__(cls, seconds: builtins.int, nanos: builtins.int) -> QpuApiDuration: ...

class QpuApiError(QcsSdkError):
    r"""
    Errors that can occur while attempting to establish a connection to the QPU.
    """
    ...

class SubmissionError(QpuApiError):
    r"""
    Errors that may occur when submitting a program for execution.
    """
    ...

def cancel_job(job_id: builtins.str, quantum_processor_id: typing.Optional[builtins.str] = None, client: typing.Optional[QCSClient] = None, execution_options: typing.Optional[ExecutionOptions] = None) -> None:
    r"""
    Cancel a job that has yet to begin executing.
    
    This action is *not* atomic, and will attempt to cancel a job even if it cannot be cancelled. A
    job can be cancelled only if it has not yet started executing.
    
    Success response indicates only that the request was received. Cancellation is not guaranteed,
    as it is based on job state at the time of cancellation, and is completed on a best effort
    basis.
    
    :param job_id: The job ID to cancel.
    :param quantum_processor_id: The quantum processor to execute the job on. This parameter is required unless using the ``ConnectionStrategy.endpoint_id()`` or ``ConnectionStrategy.endpoint_address()`` execution option.
    :param client: The ``Qcs`` client to use.
    :param execution_options: The ``ExecutionOptions`` to use.
    """

def cancel_job_async(job_id: builtins.str, quantum_processor_id: typing.Optional[builtins.str] = None, client: typing.Optional[QCSClient] = None, execution_options: typing.Optional[ExecutionOptions] = None) -> collections.abc.Awaitable[None]:
    r"""
    Cancel a job that has yet to begin executing.
    
    This action is *not* atomic, and will attempt to cancel a job even if it cannot be cancelled. A
    job can be cancelled only if it has not yet started executing.
    
    Success response indicates only that the request was received. Cancellation is not guaranteed,
    as it is based on job state at the time of cancellation, and is completed on a best effort
    basis.
    
    :param job_id: The job ID to cancel.
    :param quantum_processor_id: The quantum processor to execute the job on. This parameter is required unless using the ``ConnectionStrategy.endpoint_id()`` or ``ConnectionStrategy.endpoint_address()`` execution option.
    :param client: The ``Qcs`` client to use.
    :param execution_options: The ``ExecutionOptions`` to use.
    """

def cancel_jobs(job_ids: typing.Sequence[builtins.str], quantum_processor_id: typing.Optional[builtins.str] = None, client: typing.Optional[QCSClient] = None, execution_options: typing.Optional[ExecutionOptions] = None) -> None:
    r"""
    Cancel all given jobs that have yet to begin executing.
    
    This action is *not* atomic, and will attempt to cancel every job even when some jobs cannot be
    cancelled. A job can be cancelled only if it has not yet started executing.
    
    Success response indicates only that the request was received. Cancellation is not guaranteed,
    as it is based on job state at the time of cancellation, and is completed on a best effort
    basis.
    
    :param job_ids: The job IDs to cancel.
    :param quantum_processor_id: The quantum processor to execute the job on. This parameter is required unless using the ``ConnectionStrategy.endpoint_id()`` or ``ConnectionStrategy.endpoint_address()`` execution option.
    :param client: The ``Qcs`` client to use.
    :param execution_options: The ``ExecutionOptions`` to use.
    """

def cancel_jobs_async(job_ids: typing.Sequence[builtins.str], quantum_processor_id: typing.Optional[builtins.str] = None, client: typing.Optional[QCSClient] = None, execution_options: typing.Optional[ExecutionOptions] = None) -> collections.abc.Awaitable[None]:
    r"""
    Cancel all given jobs that have yet to begin executing.
    
    This action is *not* atomic, and will attempt to cancel every job even when some jobs cannot be
    cancelled. A job can be cancelled only if it has not yet started executing.
    
    Success response indicates only that the request was received. Cancellation is not guaranteed,
    as it is based on job state at the time of cancellation, and is completed on a best effort
    basis.
    
    :param job_ids: The job IDs to cancel.
    :param quantum_processor_id: The quantum processor to execute the job on. This parameter is required unless using the ``ConnectionStrategy.endpoint_id()`` or ``ConnectionStrategy.endpoint_address()`` execution option.
    :param client: The ``Qcs`` client to use.
    :param execution_options: The ``ExecutionOptions`` to use.
    """

def retrieve_results(job_id: builtins.str, quantum_processor_id: typing.Optional[builtins.str] = None, client: typing.Optional[QCSClient] = None, execution_options: typing.Optional[ExecutionOptions] = None) -> ExecutionResults:
    r"""
    Fetches execution results for the given QCS Job ID.
    
    :param job_id: The ID of the job to retrieve results for.
    :param quantum_processor_id: The ID of the quantum processor the job ran on. This field is required, unless being used with the ``ConnectionStrategy.endpoint_id()`` or ``ConnectionStrategy.endpoint_address()`` execution option.
    :param client: The ``Qcs`` client to use. Creates one using environment configuration if unset - see https://docs.rigetti.com/qcs/references/qcs-client-configuration
    :param execution_options: The ``ExecutionOptions`` to use.
    
    :returns: Results from execution.
    
    :raises LoadClientError: If there is an issue loading the QCS Client configuration.
    :raises QpuApiError: If there was a problem retrieving the results.
    """

def retrieve_results_async(job_id: builtins.str, quantum_processor_id: typing.Optional[builtins.str] = None, client: typing.Optional[QCSClient] = None, execution_options: typing.Optional[ExecutionOptions] = None) -> collections.abc.Awaitable[ExecutionResults]:
    r"""
    Fetches execution results for the given QCS Job ID.
    
    :param job_id: The ID of the job to retrieve results for.
    :param quantum_processor_id: The ID of the quantum processor the job ran on. This field is required, unless being used with the ``ConnectionStrategy.endpoint_id()`` or ``ConnectionStrategy.endpoint_address()`` execution option.
    :param client: The ``Qcs`` client to use. Creates one using environment configuration if unset - see https://docs.rigetti.com/qcs/references/qcs-client-configuration
    :param execution_options: The ``ExecutionOptions`` to use.
    
    :returns: Results from execution.
    
    :raises LoadClientError: If there is an issue loading the QCS Client configuration.
    :raises QpuApiError: If there was a problem retrieving the results.
    """

def submit(program: builtins.str, patch_values: typing.Mapping[builtins.str, typing.Sequence[builtins.float]], quantum_processor_id: typing.Optional[builtins.str] = None, client: typing.Optional[QCSClient] = None, execution_options: typing.Optional[ExecutionOptions] = None) -> builtins.str:
    r"""
    Submits an executable `program` to be run on the specified QPU.
    
    :param program: An executable program (see ``qcs_sdk.qpu.translation.translate``).
    :param patch_values: A mapping of symbols to their desired values (see ``build_patch_values``).
    :param quantum_processor_id: The ID of the quantum processor to run the executable on.
        This field is required, unless being used with the ``ConnectionStrategy.endpoint_id()``
        or ``ConnectionStrategy.endpoint_address()`` execution option.
    :param client: The ``Qcs`` client to use.
        Creates one using environment configuration if unset.
        See https://docs.rigetti.com/qcs/references/qcs-client-configuration for more information.
    :param execution_options: The ``ExecutionOptions`` to use.
        If the connection strategy option used is ``ConnectionStrategy.endpoint_id("endpoint_id")``
        or ``ConnectionStrategy.endpoint_address("http://some_endpoint_address")``,
        then direct access to "endpoint_id" overrides the ``quantum_processor_id`` parameter.
    
    :returns: The ID of the submitted job which can be used to fetch results.
    
    :raises LoadClientError: If there is an issue loading the QCS Client configuration.
    :raises SubmissionError: If there was a problem submitting the program for execution.
    """

def submit_async(program: builtins.str, patch_values: typing.Mapping[builtins.str, typing.Sequence[builtins.float]], quantum_processor_id: typing.Optional[builtins.str] = None, client: typing.Optional[QCSClient] = None, execution_options: typing.Optional[ExecutionOptions] = None) -> collections.abc.Awaitable[builtins.str]:
    r"""
    Submits an executable `program` to be run on the specified QPU.
    
    :param program: An executable program (see ``qcs_sdk.qpu.translation.translate``).
    :param patch_values: A mapping of symbols to their desired values (see ``build_patch_values``).
    :param quantum_processor_id: The ID of the quantum processor to run the executable on.
        This field is required, unless being used with the ``ConnectionStrategy.endpoint_id()``
        or ``ConnectionStrategy.endpoint_address()`` execution option.
    :param client: The ``Qcs`` client to use.
        Creates one using environment configuration if unset.
        See https://docs.rigetti.com/qcs/references/qcs-client-configuration for more information.
    :param execution_options: The ``ExecutionOptions`` to use.
        If the connection strategy option used is ``ConnectionStrategy.endpoint_id("endpoint_id")``
        or ``ConnectionStrategy.endpoint_address("http://some_endpoint_address")``,
        then direct access to "endpoint_id" overrides the ``quantum_processor_id`` parameter.
    
    :returns: The ID of the submitted job which can be used to fetch results.
    
    :raises LoadClientError: If there is an issue loading the QCS Client configuration.
    :raises SubmissionError: If there was a problem submitting the program for execution.
    """

def submit_with_parameter_batch(program: builtins.str, patch_values: typing.Sequence[typing.Mapping[builtins.str, typing.Sequence[builtins.float]]], quantum_processor_id: typing.Optional[builtins.str] = None, client: typing.Optional[QCSClient] = None, execution_options: typing.Optional[ExecutionOptions] = None) -> builtins.list[builtins.str]:
    r"""
    Execute a compiled program on a QPU with multiple sets of ``patch_values``.
    
    This action is *atomic* in that all jobs will be queued, or none of them will. On success, this
    function will return a list of strings where the length and order correspond to the
    ``patch_values`` given. However, note that execution in the order of given patch values is not
    guaranteed. If there is a failure to queue any of the jobs, then none will be queued.
    
    :param program: An executable program (see ``translate``).
    :param patch_values: An iterable containing one or more mapping of symbols to their desired values.
    :param quantum_processor_id: The ID of the quantum processor to run the executable on. This field is required, unless being used with the ``ConnectionStrategy.endpoint_id()`` or ``ConnectionStrategy.endpoint_address()`` execution option.
    :param client: The ``Qcs`` client to use. Creates one using environment configuration if unset - see https://docs.rigetti.com/qcs/references/qcs-client-configuration
    :param execution_options: The ``ExecutionOptions`` to use.
    
    :returns: The IDs of the submitted jobs which can be used to fetch results.
    
    :raises LoadClientError: If there is an issue loading the QCS Client configuration.
    :raises SubmissionError: If there was a problem submitting any of the jobs for execution, or if no ``patch_values`` are given.
    """

def submit_with_parameter_batch_async(program: builtins.str, patch_values: typing.Sequence[typing.Mapping[builtins.str, typing.Sequence[builtins.float]]], quantum_processor_id: typing.Optional[builtins.str] = None, client: typing.Optional[QCSClient] = None, execution_options: typing.Optional[ExecutionOptions] = None) -> collections.abc.Awaitable[builtins.list[builtins.str]]:
    r"""
    Execute a compiled program on a QPU with multiple sets of ``patch_values``.
    
    This action is *atomic* in that all jobs will be queued, or none of them will. On success, this
    function will return a list of strings where the length and order correspond to the
    ``patch_values`` given. However, note that execution in the order of given patch values is not
    guaranteed. If there is a failure to queue any of the jobs, then none will be queued.
    
    :param program: An executable program (see ``translate``).
    :param patch_values: An iterable containing one or more mapping of symbols to their desired values.
    :param quantum_processor_id: The ID of the quantum processor to run the executable on. This field is required, unless being used with the ``ConnectionStrategy.endpoint_id()`` or ``ConnectionStrategy.endpoint_address()`` execution option.
    :param client: The ``Qcs`` client to use. Creates one using environment configuration if unset - see https://docs.rigetti.com/qcs/references/qcs-client-configuration
    :param execution_options: The ``ExecutionOptions`` to use.
    
    :returns: The IDs of the submitted jobs which can be used to fetch results.
    
    :raises LoadClientError: If there is an issue loading the QCS Client configuration.
    :raises SubmissionError: If there was a problem submitting any of the jobs for execution, or if no ``patch_values`` are given.
    """