qcs-sdk-python 0.21.21

Python bindings to qcs-sdk-rust
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

"""
The QVM module contains the API for interacting with the Quantum Virtual Machine (QVM).

🔨 This page is under construction and the documentation for some submodules is missing.
In the meantime, you can find documentation in the [the type hints](https://github.com/rigetti/qcs-sdk-rust/tree/main/crates/python/qcs_sdk/qvm).
"""
from typing import Dict, List, Mapping, Optional, Sequence, Tuple, Union, final

from qcs_sdk import RegisterData

from qcs_sdk.qvm import api as api
from qcs_sdk.qvm.api import AddressRequest


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

@final
class QVMClient:
    """Client used to communicate with QVM"""

    @staticmethod
    def new_http(endpoint: str) -> QVMClient:
        """Construct a new QVM client which uses HTTP to communicate with a QVM service"""
        ...
    @staticmethod
    def new_libquil() -> QVMClient:
        """Construct a new QVM client which uses libquil"""
        ...
    @property
    def qvm_url(self) -> str:
        """
        Return the address of the client
        """
        ...

@final
class QVMResultData:
    """
    Encapsulates data returned from the QVM after executing a program.
    """

    @staticmethod
    def from_memory_map(memory: Mapping[str, RegisterData]) -> "QVMResultData":
        """
        Build a ``QVMResultData`` from a mapping of register names to a ``RegisterData`` matrix.
        """
        ...
    @property
    def memory(self) -> Mapping[str, RegisterData]:
        """
        Get the mapping of register names (ie. "ro") to a ``RegisterData`` matrix containing the register values.
        """
        ...
    def to_raw_readout_data(
        self,
    ) -> RawQVMReadoutData:
        """
        Get a copy of this result data flattened into a ``RawQVMReadoutData``
        """
        ...

@final
class RawQVMReadoutData:
    @property
    def memory(self) -> Dict[str, Union[List[List[int]], List[List[float]]]]:
        """
        The mapping of register names (ie. "ro") to a 2-d list containing the
        values for that register.
        """

@final
class QVMOptions:
    """
    Options avaialable for running programs on the QVM.
    """

    def __new__(cls, timeout_seconds: Optional[float] = None) -> QVMOptions: ...
    @staticmethod
    def default() -> QVMOptions:
        """Get the default set of ``QVMOptions`` used for QVM requests.

        Settings:
            timeout: 30.0 seconds
        """
        ...
    @property
    def timeout(cls):
        """The timeout used for reqeusts to the QVM. If set to none, there is no timeout."""
        ...
    @timeout.setter
    def timeout(cls, timeout: Optional[float]):
        """The timeout used for reqeusts to the QVM. If set to none, there is no timeout."""
        ...

@final
class QVMError(RuntimeError):
    """
    Errors that can occur when running a Quil program on the QVM.
    """

    ...

def run(
    quil: str,
    shots: int,
    addresses: Mapping[str, AddressRequest],
    params: Mapping[str, Union[Sequence[float], Sequence[int]]],
    client: QVMClient,
    measurement_noise: Optional[Tuple[float, float, float]] = None,
    gate_noise: Optional[Tuple[float, float, float]] = None,
    rng_seed: Optional[int] = None,
    options: Optional[QVMOptions] = None,
) -> QVMResultData:
    """
    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.
    """
    ...

async def run_async(
    quil: str,
    shots: int,
    addresses: Mapping[str, AddressRequest],
    params: Mapping[str, Sequence[float]],
    client: QVMClient,
    measurement_noise: Optional[Tuple[float, float, float]] = None,
    gate_noise: Optional[Tuple[float, float, float]] = None,
    rng_seed: Optional[int] = None,
    options: Optional[QVMOptions] = None,
) -> QVMResultData:
    """
    Asynchronously 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.
    """
    ...