qcs 0.27.0

# This file is automatically generated by pyo3_stub_gen
# ruff: noqa: E501, F401, F403, F405
r"""
An interface to Rigetti [Quantum Cloud Services](https://docs.rigetti.com/qcs/) (QCS).

These APIs allow users to compile and run Quil programs on Rigetti quantum processors.
Internally, it is powered by the [QCS Rust SDK](https://github.com/rigetti/qcs-sdk-rust).

This package is still in development and breaking changes should be expected between minor versions.
"""

import builtins
import collections.abc
import datetime
import enum
import numpy
import numpy.typing
from qcs_sdk._qcs_sdk.compiler import quilc
from qcs_sdk._qcs_sdk.qpu import api
from qcs_sdk._qcs_sdk.qpu import translation
import typing
from qcs_sdk import _tracing_subscriber
from . import client
from . import compiler
from . import diagnostics
from . import qpu
from . import qvm

__all__ = [
    "ExeParameter",
    "Executable",
    "ExecutionData",
    "ExecutionError",
    "JobHandle",
    "QcsSdkError",
    "RegisterData",
    "RegisterMap",
    "RegisterMapItemsIter",
    "RegisterMapKeysIter",
    "RegisterMapValuesIter",
    "RegisterMatrix",
    "RegisterMatrixConversionError",
    "Service",
    "__version__",
    "_gather_diagnostics",
    "_tracing_subscriber",
    "client",
    "compiler",
    "diagnostics",
    "qpu",
    "qvm",
    "reset_logging",
]

__version__: typing.Final[builtins.str]

@typing.final
class ExeParameter:
    r"""
    Program execution parameters.

    Note: The validity of parameters is not checked until execution.
    """
    @property
    def index(self) -> builtins.int: ...
    @index.setter
    def index(self, value: builtins.int) -> None: ...
    @property
    def name(self) -> builtins.str: ...
    @name.setter
    def name(self, value: builtins.str) -> None: ...
    @property
    def value(self) -> builtins.float: ...
    @value.setter
    def value(self, value: builtins.float) -> None: ...
    def __new__(cls, name: builtins.str, index: builtins.int, value: builtins.float) -> ExeParameter: ...

@typing.final
class Executable:
    r"""
    A builder interface for executing Quil programs on QVMs and QPUs.

    # Example

    This example executes a program on a QVM, specified by the `qvm_url` in the `QCSClient`:

    ```python
    from qcs_sdk import Executable
    from qcs_sdk.client import QCSClient
    from qcs_sdk.qvm import QVMClient

    PROGRAM = r'''
    DECLARE ro BIT[2]

    H 0
    CNOT 0 1

    MEASURE 0 ro[0]
    MEASURE 1 ro[1]
    '''

    async def run():
        client = QVMClient.new_http(QCSClient.load().qvm_url)
        result = await Executable(PROGRAM, shots=4).execute_on_qvm_async()
        let data = result.result_data
                            .to_register_map()
                            .expect("should convert to readout map")
                            .get_register_matrix("ro")
                            .expect("should have data in ro")
                            .as_integer()
                            .expect("should be integer matrix")
                            .to_owned();

        // In this case, we ran the program for 4 shots, so we know the number of rows is 4.
        assert_eq!(data.nrows(), 4);
        for shot in data.rows() {
            // Each shot will contain all the memory, in order, for the vector (or "register") we
            // requested the results of. In this case, "ro" (the default).
            assert_eq!(shot.len(), 2);
            // In the case of this particular program, we know ro[0] should equal ro[1]
            assert_eq!(shot[0], shot[1]);
        }

    def main():
        import asyncio
        asyncio.run(run())

        # "ro" is the only source read from by default if you don't specify `registers`.

        # We first convert the readout data to a ``RegisterMap`` to get a mapping of registers
        # (ie. "ro") to a [`RegisterMatrix`], `M`, where M[`shot`][`index`] is the value for
        # the memory offset `index` during shot `shot`.
        # There are some programs where QPU readout data does not fit into a [`RegisterMap`], in
        # which case you should build the matrix you need from [`QpuResultData`] directly. See
        # the [`RegisterMap`] documentation for more information on when this transformation
        # might fail.
    ```
    """
    def __new__(
        cls,
        quil: builtins.str,
        /,
        registers: typing.Sequence[builtins.str] = [],
        parameters: typing.Sequence[ExeParameter] = [],
        shots: typing.Optional[builtins.int] = None,
        quilc_client: typing.Optional[quilc.QuilcClient] = None,
        compiler_options: typing.Optional[quilc.CompilerOpts] = None,
    ) -> Executable: ...
    def execute_on_qpu(
        self,
        quantum_processor_id: builtins.str,
        endpoint_id: typing.Optional[builtins.str] = None,
        translation_options: typing.Optional[translation.TranslationOptions] = None,
        execution_options: typing.Optional[api.ExecutionOptions] = None,
    ) -> ExecutionData:
        r"""
        Compile the program and execute it on a QPU, waiting for results.

        :param `endpoint_id`: execute the compiled program against an explicitly provided endpoint.
            If `None`, the default endpoint for the given `quantum_processor_id` is used.

        :raises `ExecutionError`: If the job fails to execute.
        """
    def execute_on_qpu_async(
        self,
        quantum_processor_id: builtins.str,
        endpoint_id: typing.Optional[builtins.str] = None,
        translation_options: typing.Optional[translation.TranslationOptions] = None,
        execution_options: typing.Optional[api.ExecutionOptions] = None,
    ) -> collections.abc.Awaitable[ExecutionData]:
        r"""
        Compile the program and execute it on a QPU, waiting for results
        (async analog of `Executable.execute_on_qpu`).

        :param `endpoint_id`: execute the compiled program against an explicitly provided endpoint.
            If `None`, the default endpoint for the given `quantum_processor_id` is used.

        :raises `ExecutionError`: If the job fails to execute.
        """
    def execute_on_qvm(self, client: qvm.QVMClient) -> ExecutionData:
        r"""
        Execute on a QVM which is accessible via the provided client.

        :raises `ExecutionError`: If the job fails to execute.
        """
    def execute_on_qvm_async(self, client: qvm.QVMClient) -> collections.abc.Awaitable[ExecutionData]:
        r"""
        Execute on a QVM which is accessible via the provided client
        (async analog of ``Executable.execute_on_qvm``).

        :raises `ExecutionError`: If the job fails to execute.
        """
    def retrieve_results(self, job_handle: JobHandle) -> ExecutionData:
        r"""
        Wait for the results of a job to complete.

        :raises `ExecutionError`: If the job fails to execute.
        """
    def retrieve_results_async(self, job_handle: JobHandle) -> collections.abc.Awaitable[ExecutionData]:
        r"""
        Wait for the results of a job to complete
        (async analog of `Executable.retrieve_results`).

        :raises `ExecutionError`: If the job fails to execute.
        """
    def submit_to_qpu(
        self,
        quantum_processor_id: builtins.str,
        endpoint_id: typing.Optional[builtins.str] = None,
        translation_options: typing.Optional[translation.TranslationOptions] = None,
        execution_options: typing.Optional[api.ExecutionOptions] = None,
    ) -> JobHandle:
        r"""
        Compile the program and execute it on a QPU, without waiting for results.

        :param `endpoint_id`: execute the compiled program against an explicitly provided endpoint.
            If `None`, the default endpoint for the given `quantum_processor_id` is used.

        :raises `ExecutionError`: If the job fails to execute.
        """
    def submit_to_qpu_async(
        self,
        quantum_processor_id: builtins.str,
        endpoint_id: typing.Optional[builtins.str] = None,
        translation_options: typing.Optional[translation.TranslationOptions] = None,
        execution_options: typing.Optional[api.ExecutionOptions] = None,
    ) -> collections.abc.Awaitable[JobHandle]:
        r"""
        Compile the program and execute it on a QPU, without waiting for results
        (async analog of `Executable.submit_to_qpu`).

        :param `endpoint_id`: execute the compiled program against an explicitly provided endpoint.
            If `None`, the default endpoint for the given `quantum_processor_id` is used.

        :raises `ExecutionError`: If the job fails to execute.
        """

@typing.final
class ExecutionData:
    r"""
    The result of executing an [`Executable`](crate::Executable)
    """
    @property
    def duration(self) -> typing.Optional[datetime.timedelta]:
        r"""
        The time it took to execute the program on the QPU, not including any network or queueing
        time. If paying for on-demand execution, this is the amount you will be billed for.

        This will always be `None` for QVM execution.
        """
    @property
    def result_data(self) -> qvm.QVMResultData | qpu.QPUResultData:
        r"""
        The [`ResultData`] that was read from the [`Executable`](crate::Executable).
        """
    def __eq__(self, other: builtins.object, /) -> builtins.bool: ...
    def __getnewargs__(self) -> tuple[qvm.QVMResultData | qpu.QPUResultData, typing.Optional[datetime.timedelta]]: ...
    def __new__(
        cls, result_data: qvm.QVMResultData | qpu.QPUResultData, duration: typing.Optional[datetime.timedelta] = None
    ) -> ExecutionData:
        r"""
        Create `ExecutionData` from `ResultData` and an optional `duration`.
        """

class ExecutionError(QcsSdkError):
    r"""
    Errors which can occur when executing a program.
    """

    ...

@typing.final
class JobHandle:
    r"""
    The result of submitting a job to a QPU.

    Used to retrieve the results of a job.
    """
    @property
    def job_id(self) -> builtins.str:
        r"""
        Unique ID associated with a single job execution.
        """
    @property
    def readout_map(self) -> builtins.dict[builtins.str, builtins.str]:
        r"""
        The readout map from "source readout memory locations"
        to the "filter pipeline node" which publishes the data.
        """

class QcsSdkError(builtins.Exception):
    r"""
    Base exception type for errors raised by this package.
    """

    ...

class RegisterData:
    r"""
    Data resulting from [`Executable::execute_on_qvm`](`crate::Executable::execute_on_qvm`)

    This represents a single vector (or "register") of typed memory across some number of shots.
    The register corresponds to the usage of a `DECLARE` instruction in Quil, and the name of that
    register should be provided with [`Executable::read_from`](`crate::Executable::read_from`).

    There is a variant of this enum for each type of data that a register could hold. The register
    is represented as a 2-dimensional array `M` where the value `M[shot_number][memory_index]`
    represents the value at `memory_index` for `shot_number`.

    # Usage

    Typically, you will be interacting with this data through the [`crate::ResultData`] of an
    [`crate::ExecutionData`] returned after running a program. In those cases, you'll probably
    want to convert it to a readout map using [`crate::ResultData.to_register_map()`]. This
    will give you each register in the form of a [`crate::RegisterMatrix`] which is similar
    but backed by an [`ndarray::Array2`] and more convenient for working with matrices.

    If you are interacting with [`RegisterData`] directly, then you should already know what type of data it _should_
    have, so you can  use the [`mod@enum_as_inner`] methods (e.g. [`RegisterData::into_i8`]) in order to
    convert any variant type to its inner data.
    """
    def __getnewargs__(
        self,
    ) -> tuple[
        builtins.list[builtins.list[builtins.int]]
        | builtins.list[builtins.list[builtins.float]]
        | builtins.list[builtins.list[builtins.complex]]
    ]: ...
    def __new__(
        cls,
        inner: typing.Sequence[typing.Sequence[builtins.int]]
        | typing.Sequence[typing.Sequence[builtins.float]]
        | typing.Sequence[typing.Sequence[builtins.complex]],
    ) -> RegisterData: ...
    def as_ndarray(self) -> numpy.ndarray:
        r"""
        Return the inner values as a 2D Numpy ``ndarray``.
        """
    def inner(
        self,
    ) -> (
        builtins.list[builtins.list[builtins.int]]
        | builtins.list[builtins.list[builtins.float]]
        | builtins.list[builtins.list[builtins.complex]]
    ): ...
    @typing.final
    class Complex32(RegisterData):
        r"""
        Results containing complex numbers.
        """

        __match_args__ = ("_0",)
        @property
        def _0(self) -> builtins.list[builtins.list[builtins.complex]]: ...
        def __getitem__(self, key: builtins.int, /) -> typing.Any: ...
        def __len__(self) -> builtins.int: ...
        def __new__(cls, _0: typing.Sequence[typing.Sequence[builtins.complex]]) -> RegisterData.Complex32: ...

    @typing.final
    class F64(RegisterData):
        r"""
        Corresponds to the Quil `REAL` type.
        """

        __match_args__ = ("_0",)
        @property
        def _0(self) -> builtins.list[builtins.list[builtins.float]]: ...
        def __getitem__(self, key: builtins.int, /) -> typing.Any: ...
        def __len__(self) -> builtins.int: ...
        def __new__(cls, _0: typing.Sequence[typing.Sequence[builtins.float]]) -> RegisterData.F64: ...

    @typing.final
    class I16(RegisterData):
        r"""
        Corresponds to the Quil `INTEGER` type.
        """

        __match_args__ = ("_0",)
        @property
        def _0(self) -> builtins.list[builtins.list[builtins.int]]: ...
        def __getitem__(self, key: builtins.int, /) -> typing.Any: ...
        def __len__(self) -> builtins.int: ...
        def __new__(cls, _0: typing.Sequence[typing.Sequence[builtins.int]]) -> RegisterData.I16: ...

    @typing.final
    class I8(RegisterData):
        r"""
        Corresponds to the Quil `BIT` or `OCTET` types.
        """

        __match_args__ = ("_0",)
        @property
        def _0(self) -> builtins.list[builtins.list[builtins.int]]: ...
        def __getitem__(self, key: builtins.int, /) -> typing.Any: ...
        def __len__(self) -> builtins.int: ...
        def __new__(cls, _0: typing.Sequence[typing.Sequence[builtins.int]]) -> RegisterData.I8: ...

@typing.final
class RegisterMap:
    r"""
    A mapping of a register name (ie. "ro") to a [`RegisterMatrix`] containing the values for the
    register.
    """
    def __contains__(self, key: builtins.str) -> builtins.bool: ...
    def __getitem__(self, item: builtins.str) -> RegisterMatrix: ...
    def __iter__(self) -> RegisterMapKeysIter: ...
    def __len__(self) -> builtins.int: ...
    def get(
        self, key: builtins.str, default: typing.Optional[RegisterMatrix] = None
    ) -> typing.Optional[RegisterMatrix]: ...
    def get_register_matrix(self, register_name: builtins.str) -> typing.Optional[RegisterMatrix]:
        r"""
        Get the `RegisterMatrix` for the given register.

        Returns `None` if the register doesn't exist.
        """
    def items(self) -> RegisterMapItemsIter: ...
    def keys(self) -> RegisterMapKeysIter: ...
    def values(self) -> RegisterMapValuesIter: ...

@typing.final
class RegisterMapItemsIter:
    def __iter__(self) -> RegisterMapItemsIter: ...
    def __next__(self) -> tuple[builtins.str, RegisterMatrix]: ...

@typing.final
class RegisterMapKeysIter:
    def __iter__(self) -> RegisterMapKeysIter: ...
    def __next__(self) -> builtins.str: ...

@typing.final
class RegisterMapValuesIter:
    def __iter__(self) -> RegisterMapValuesIter: ...
    def __next__(self) -> RegisterMatrix: ...

class RegisterMatrix:
    r"""
    A 2-dimensional matrix of register values.

    Each variant corresponds to the possible data types a register can contain.
    """
    def to_ndarray(self) -> typing.Any:
        r"""
        Get the `RegisterMatrix` as Numpy ``ndarray``.
        """
    @typing.final
    class Complex(RegisterMatrix):
        r"""
        Complex numbered register.
        """

        __match_args__ = ("_0",)
        @property
        def _0(self) -> numpy.typing.NDArray[numpy.complex128]: ...
        def __getitem__(self, key: builtins.int, /) -> typing.Any: ...
        def __len__(self) -> builtins.int: ...
        def __new__(cls, _0: numpy.typing.NDArray[numpy.complex128]) -> RegisterMatrix.Complex: ...

    @typing.final
    class Integer(RegisterMatrix):
        r"""
        Integer register.
        """

        __match_args__ = ("_0",)
        @property
        def _0(self) -> numpy.typing.NDArray[numpy.int64]: ...
        def __getitem__(self, key: builtins.int, /) -> typing.Any: ...
        def __len__(self) -> builtins.int: ...
        def __new__(cls, _0: numpy.typing.NDArray[numpy.int64]) -> RegisterMatrix.Integer: ...

    @typing.final
    class Real(RegisterMatrix):
        r"""
        Real numbered register.
        """

        __match_args__ = ("_0",)
        @property
        def _0(self) -> numpy.typing.NDArray[numpy.float64]: ...
        def __getitem__(self, key: builtins.int, /) -> typing.Any: ...
        def __len__(self) -> builtins.int: ...
        def __new__(cls, _0: numpy.typing.NDArray[numpy.float64]) -> RegisterMatrix.Real: ...

class RegisterMatrixConversionError(QcsSdkError):
    r"""
    Error that may occur when building a `RegisterMatrix` from execution data.
    """

    ...

@typing.final
class Service(enum.Enum):
    r"""
    The external services that this SDK may connect to. Used to differentiate between networking
    issues in [`Error::Connection`].
    """

    QUILC = ...
    r"""
    The open source [`quilc`](https://github.com/quil-lang/quilc) compiler.
    
    This compiler must be running before calling [`Executable::execute_on_qpu`] unless the
    [`Executable::compile_with_quilc`] option is set to `false`. By default, it's assumed that
    this is running on `tcp://localhost:5555`, but this can be overridden via
    `[profiles.<profile_name>.applications.pyquil.quilc_url]` in your `.qcs/settings.toml` file.
    """
    QVM = ...
    r"""
    The open source [`qvm`](https://github.com/quil-lang/qvm) simulator.
    
    This simulator must be running before calling [`Executable::execute_on_qvm`]. By default,
    it's assumed that this is running on `http://localhost:5000`, but this can be overridden via
    `[profiles.<profile_name>.applications.pyquil.qvm_url]` in your `.qcs/settings.toml` file.
    """
    QCS = ...
    r"""
    The connection to [`QCS`](https://docs.rigetti.com/qcs/), the API for authentication,
    QPU lookup, and translation.
    
    You should be able to reach this service as long as you have a connection to the internet.
    """
    QPU = ...
    r"""
    The connection to the QPU itself. You can only connect to the QPU from an authorized network
    (like QCS JupyterLab).
    """

def _gather_diagnostics() -> builtins.str: ...
def reset_logging() -> None:
    r"""
    Reset all caches for logging configuration within this library,
    allowing the most recent Python-side changes to be applied.

    See <https://docs.rs/pyo3-log/latest/pyo3_log/> for more information.
    """