qcs 0.27.0

High level interface for running Quil on a QPU
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192

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

import builtins
import collections.abc
from qcs_sdk import _qcs_sdk
import typing
from . import api

__all__ = [
    "QVMClient",
    "QVMError",
    "QVMOptions",
    "QVMResultData",
    "RawQVMReadoutData",
    "api",
    "run",
    "run_async",
]

@typing.final
class QVMClient:
    r"""
    Client used to communicate with QVM.
    """
    @property
    def qvm_url(self) -> builtins.str:
        r"""
        Return the address of the client.
        """
    def __new__(cls) -> QVMClient: ...
    @staticmethod
    def new_http(endpoint: builtins.str) -> QVMClient:
        r"""
        Construct a new QVM client which uses HTTP to communicate with a QVM service.
        """
    @staticmethod
    def new_libquil() -> QVMClient: ...

class QVMError(_qcs_sdk.QcsSdkError):
    r"""
    Errors that can occur when running a Quil program on QVM.
    """

    ...

@typing.final
class QVMOptions:
    r"""
    Options avaialable for running programs on the QVM.
    """
    @property
    def timeout(self) -> typing.Optional[builtins.float]:
        r"""
        The timeout used for requests to the QVM. If set to None, there is no timeout.
        """
    @timeout.setter
    def timeout(self, value: typing.Optional[builtins.float]) -> None:
        r"""
        The timeout used for requests to the QVM. If set to None, there is no timeout.
        """
    def __new__(cls, timeout_seconds: typing.Optional[builtins.float] = None) -> QVMOptions: ...
    def __repr__(self) -> builtins.str:
        r"""
        Implements `__repr__` for Python in terms of the Rust
        [`Debug`](std::fmt::Debug) implementation.
        """
    @staticmethod
    def default() -> QVMOptions:
        r"""
        Get the default set of ``QVMOptions`` used for QVM requests.

        Settings:
            timeout: 30.0 seconds
        """

@typing.final
class QVMResultData:
    r"""
    Encapsulates data returned after running a program on the QVM
    """
    @property
    def memory(self) -> builtins.dict[builtins.str, _qcs_sdk.RegisterData]:
        r"""
        A map of register names (ie. "ro") to a `RegisterData` containing their values.
        """
    def __getnewargs__(self) -> tuple[builtins.dict[builtins.str, _qcs_sdk.RegisterData]]: ...
    def __new__(cls, memory: typing.Mapping[builtins.str, _qcs_sdk.RegisterData]) -> QVMResultData:
        r"""
        Build a ``QVMResultData`` from a mapping of register names to a ``RegisterData`` matrix.
        """
    def __repr__(self) -> builtins.str:
        r"""
        Implements `__repr__` for Python in terms of the Rust
        [`Debug`](std::fmt::Debug) implementation.
        """
    @staticmethod
    def from_memory_map(memory: typing.Mapping[builtins.str, _qcs_sdk.RegisterData]) -> QVMResultData:
        r"""
        Build a [`QvmResultData`] from a mapping of register names to a [`RegisterData`]
        """
    def to_raw_readout_data(self) -> RawQVMReadoutData:
        r"""
        Get a copy of this result data flattened into a ``RawQVMReadoutData``.
        """
    def to_register_map(self) -> _qcs_sdk.RegisterMap:
        r"""
        Convert into a [`RegisterMap`].

        The [`RegisterMatrix`] for each register will be
        constructed such that each row contains all the final values in the register for a single shot.

        # Errors

        Returns a [`RegisterMatrixConversionError`] if the inner execution data for any of the
        registers would result in a jagged matrix.
        This is often the case in programs that use mid-circuit measurement or dynamic control flow,
        where measurements to the same memory reference might occur multiple times in a shot, or be
        skipped conditionally. In these cases, building a rectangular [`RegisterMatrix`] would
        necessitate making assumptions about the data that could skew the data in undesirable ways.
        Instead, it's recommended to manually build a matrix from [`QpuResultData`] that accurately
        selects the last value per-shot based on the program that was run.
        """

@typing.final
class RawQVMReadoutData:
    r"""
    Encapsulates raw data returned from the QVM after executing a program.
    """
    @property
    def memory(self) -> builtins.dict[builtins.str, list]:
        r"""
        The mapping of register names (ie. "ro") to a 2-d list containing the
        values for that register.
        """
    def __repr__(self) -> builtins.str:
        r"""
        Implements `__repr__` for Python in terms of the Rust
        [`Debug`](std::fmt::Debug) implementation.
        """

def run(
    quil: builtins.str,
    shots: builtins.int,
    addresses: typing.Mapping[builtins.str, api.AddressRequest],
    params: typing.Mapping[builtins.str, typing.Sequence[builtins.float]],
    client: QVMClient,
    measurement_noise: typing.Optional[tuple[builtins.float, builtins.float, builtins.float]] = None,
    gate_noise: typing.Optional[tuple[builtins.float, builtins.float, builtins.float]] = None,
    rng_seed: typing.Optional[builtins.int] = None,
    options: typing.Optional[QVMOptions] = None,
) -> QVMResultData:
    r"""
    Runs the given program on the QVM.

    :param quil: A quil program as a string.
    :param shots: The number of times to run the program. Should be a value greater than zero.
    :param addresses: A mapping of memory region names to an ``AddressRequest`` describing what data to get back for that memory region from the QVM at the end of execution.
    :param params: A mapping of memory region names to their desired values.
    :param client: An optional ``QCSClient`` to use. If unset, creates one using the environemnt configuration (see https://docs.rigetti.com/qcs/references/qcs-client-configuration).
    :param options: An optional ``QVMOptions`` to use. If unset, uses ``QVMOptions.default()`` for the request.

    :returns: A ``QVMResultData`` containing the final state of of memory for the requested readouts after the program finished running.

    :raises QVMError: If one of the parameters is invalid, or if there was a problem communicating with the QVM server.
    """

def run_async(
    quil: builtins.str,
    shots: builtins.int,
    addresses: typing.Mapping[builtins.str, api.AddressRequest],
    params: typing.Mapping[builtins.str, typing.Sequence[builtins.float]],
    client: QVMClient,
    measurement_noise: typing.Optional[tuple[builtins.float, builtins.float, builtins.float]] = None,
    gate_noise: typing.Optional[tuple[builtins.float, builtins.float, builtins.float]] = None,
    rng_seed: typing.Optional[builtins.int] = None,
    options: typing.Optional[QVMOptions] = None,
) -> collections.abc.Awaitable[QVMResultData]:
    r"""
    Runs the given program on the QVM.

    :param quil: A quil program as a string.
    :param shots: The number of times to run the program. Should be a value greater than zero.
    :param addresses: A mapping of memory region names to an ``AddressRequest`` describing what data to get back for that memory region from the QVM at the end of execution.
    :param params: A mapping of memory region names to their desired values.
    :param client: An optional ``QCSClient`` to use. If unset, creates one using the environemnt configuration (see https://docs.rigetti.com/qcs/references/qcs-client-configuration).
    :param options: An optional ``QVMOptions`` to use. If unset, uses ``QVMOptions.default()`` for the request.

    :returns: A ``QVMResultData`` containing the final state of of memory for the requested readouts after the program finished running.

    :raises QVMError: If one of the parameters is invalid, or if there was a problem communicating with the QVM server.
    """