quil-rs 0.37.0

Rust tooling for Quil (Quantum Instruction Language)
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
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277

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

import builtins
import enum
from quil import _quil
from quil._quil import instructions
import typing
__all__ = [
    "EvaluationError",
    "Expression",
    "ExpressionFunction",
    "FunctionCallExpression",
    "InfixExpression",
    "InfixOperator",
    "ParseExpressionError",
    "PrefixExpression",
    "PrefixOperator",
]

class EvaluationError(_quil.QuilError):
    r"""
    Errors that may occur while evaluation an ``Expression``.
    """
    ...

class Expression:
    r"""
    The type of Quil expressions.
    
    Quil expressions take advantage of *structural sharing*; if a Quil expression contains the same
    subexpression twice, such as `x + y` in `(x + y) * (x + y)`, the two children of the `*` node
    will be the *same pointer*.  This is implemented through *interning*, also known as
    *hash-consing*; the recursive references to child nodes are done via [`ArcIntern<Expression>`]s.
    Creating an [`ArcIntern`] from an `Expression` will always return the same pointer for the same
    expression.
    
    The structural sharing means that equality, cloning, and hashing on Quil expressions are all
    very cheap, as they do not need to be recursive: equality of [`ArcIntern`]s is a single-pointer
    comparison, cloning of [`ArcIntern`]s is a pointer copy and an atomic increment, and hashing of
    [`ArcIntern`]s hashes a single pointer.  It is also very cheap to key [`HashMap`]s by an
    [`ArcIntern<Expression>`], which can allow for cheap memoization of operations on `Expression`s.
    
    The structural sharing also means that Quil expressions are fundamentally *immutable*; it is
    *impossible* to get an owned or `&mut` reference to the child `Expression`s of any `Expression`,
    as the use of interning means there may be multiple references to that `Expression` at any time.
    
    Note that when comparing Quil expressions, any embedded NaNs are treated as *equal* to other
    NaNs, not unequal, in contravention of the IEEE 754 spec.
    """
    def __add__(self, other: Expression) -> Expression: ...
    def __getnewargs__(self) -> builtins.tuple[instructions.MemoryReference | FunctionCallExpression | InfixExpression | builtins.complex | PrefixExpression | builtins.str]: ...
    def __mul__(self, other: Expression) -> Expression: ...
    def __repr__(self) -> builtins.str:
        r"""
        Implements `__repr__` for Python in terms of the Rust
        [`Debug`](std::fmt::Debug) implementation.
        """
    def __sub__(self, other: Expression) -> Expression: ...
    def __truediv__(self, other: Expression) -> Expression: ...
    def evaluate(self, variables: typing.Mapping[builtins.str, builtins.complex], memory_references: typing.Mapping[builtins.str, typing.Sequence[builtins.float]]) -> builtins.complex:
        r"""
        Evaluate an expression, expecting that it may be fully reduced to a single complex number.
        
        If it cannot be reduced to a complex number, this raises an error.
        """
    def into_simplified(self) -> Expression:
        r"""
        Return an expression derived from this one, simplified as much as possible.
        """
    @staticmethod
    def parse(input: builtins.str) -> Expression:
        r"""
        Parse an ``Expression`` from a string.
        
        Raises a ``ParseExpressionError`` error if the string isn't a valid Quil expression.
        """
    def substitute_variables(self, variable_values: typing.Mapping[builtins.str, Expression]) -> Expression:
        r"""
        Substitute an expression in the place of each matching variable.
        """
    def to_real(self) -> builtins.float:
        r"""
        If this is a number with imaginary part "equal to" zero (of _small_ absolute value), return
        that number. Otherwise, error with an evaluation error of a descriptive type.
        """
    @typing.final
    class Address(Expression):
        __match_args__ = ("_0",)
        @property
        def _0(self) -> instructions.MemoryReference: ...
        def __getitem__(self, key: builtins.int, /) -> typing.Any: ...
        def __len__(self) -> builtins.int: ...
        def __new__(cls, _0: instructions.MemoryReference) -> Expression.Address: ...
    
    @typing.final
    class FunctionCall(Expression):
        __match_args__ = ("_0",)
        @property
        def _0(self) -> FunctionCallExpression: ...
        def __getitem__(self, key: builtins.int, /) -> typing.Any: ...
        def __len__(self) -> builtins.int: ...
        def __new__(cls, _0: FunctionCallExpression) -> Expression.FunctionCall: ...
    
    @typing.final
    class Infix(Expression):
        __match_args__ = ("_0",)
        @property
        def _0(self) -> InfixExpression: ...
        def __getitem__(self, key: builtins.int, /) -> typing.Any: ...
        def __len__(self) -> builtins.int: ...
        def __new__(cls, _0: InfixExpression) -> Expression.Infix: ...
    
    @typing.final
    class Number(Expression):
        __match_args__ = ("_0",)
        @property
        def _0(self) -> builtins.complex: ...
        def __getitem__(self, key: builtins.int, /) -> typing.Any: ...
        def __len__(self) -> builtins.int: ...
        def __new__(cls, _0: builtins.complex) -> Expression.Number: ...
    
    @typing.final
    class Pi(Expression):
        __match_args__ = ()
        def __getitem__(self, key: builtins.int, /) -> typing.Any: ...
        def __len__(self) -> builtins.int: ...
        def __new__(cls) -> Expression.Pi: ...
    
    @typing.final
    class Prefix(Expression):
        __match_args__ = ("_0",)
        @property
        def _0(self) -> PrefixExpression: ...
        def __getitem__(self, key: builtins.int, /) -> typing.Any: ...
        def __len__(self) -> builtins.int: ...
        def __new__(cls, _0: PrefixExpression) -> Expression.Prefix: ...
    
    @typing.final
    class Variable(Expression):
        __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) -> Expression.Variable: ...
    

class FunctionCallExpression:
    r"""
    The type of function call Quil expressions, e.g. `sin(e)`.
    
    Quil expressions take advantage of *structural sharing*, which is why the `expression` here is
    wrapped in an [`ArcIntern`]; for more details, see the documentation for [`Expression`].
    
    Note that when comparing Quil expressions, any embedded NaNs are treated as *equal* to other
    NaNs, not unequal, in contravention of the IEEE 754 spec.
    """
    @property
    def expression(self) -> Expression: ...
    @property
    def function(self) -> ExpressionFunction: ...
    def __eq__(self, other: builtins.object, /) -> builtins.bool: ...
    def __getnewargs__(self) -> tuple[ExpressionFunction, Expression]: ...
    def __hash__(self) -> builtins.int: ...
    def __new__(cls, function: ExpressionFunction, expression: Expression) -> FunctionCallExpression: ...
    def __repr__(self) -> builtins.str:
        r"""
        Implements `__repr__` for Python in terms of the Rust
        [`Debug`](std::fmt::Debug) implementation.
        """

class InfixExpression:
    r"""
    The type of infix Quil expressions, e.g. `e1 + e2`.
    
    Quil expressions take advantage of *structural sharing*, which is why the `left` and `right`
    expressions here are wrapped in [`ArcIntern`]s; for more details, see the documentation for
    [`Expression`].
    
    Note that when comparing Quil expressions, any embedded NaNs are treated as *equal* to other
    NaNs, not unequal, in contravention of the IEEE 754 spec.
    """
    @property
    def left(self) -> Expression: ...
    @property
    def operator(self) -> InfixOperator: ...
    @property
    def right(self) -> Expression: ...
    def __eq__(self, other: builtins.object, /) -> builtins.bool: ...
    def __getnewargs__(self) -> tuple[Expression, InfixOperator, Expression]: ...
    def __hash__(self) -> builtins.int: ...
    def __new__(cls, left: Expression, operator: InfixOperator, right: Expression) -> InfixExpression: ...
    def __repr__(self) -> builtins.str:
        r"""
        Implements `__repr__` for Python in terms of the Rust
        [`Debug`](std::fmt::Debug) implementation.
        """

class ParseExpressionError(_quil.QuilError):
    r"""
    Errors that may occur while parsing an ``Expression``.
    """
    ...

class PrefixExpression:
    r"""
    The type of prefix Quil expressions, e.g. `-e`.
    
    Quil expressions take advantage of *structural sharing*, which is why the `expression` here is
    wrapped in an [`ArcIntern`]; for more details, see the documentation for [`Expression`].
    
    Note that when comparing Quil expressions, any embedded NaNs are treated as *equal* to other
    NaNs, not unequal, in contravention of the IEEE 754 spec.
    """
    @property
    def expression(self) -> Expression: ...
    @property
    def operator(self) -> PrefixOperator: ...
    def __eq__(self, other: builtins.object, /) -> builtins.bool: ...
    def __getnewargs__(self) -> tuple[PrefixOperator, Expression]: ...
    def __hash__(self) -> builtins.int: ...
    def __new__(cls, operator: PrefixOperator, expression: Expression) -> PrefixExpression: ...
    def __repr__(self) -> builtins.str:
        r"""
        Implements `__repr__` for Python in terms of the Rust
        [`Debug`](std::fmt::Debug) implementation.
        """

@typing.final
class ExpressionFunction(enum.Enum):
    r"""
    A function defined within Quil syntax.
    """
    CIS = ...
    COSINE = ...
    EXPONENT = ...
    SINE = ...
    SQUARE_ROOT = ...

    def __getnewargs__(self) -> tuple[builtins.int]: ...
    def __new__(cls, value: builtins.int) -> ExpressionFunction: ...
    def __repr__(self) -> builtins.str:
        r"""
        Implements `__repr__` for Python in terms of the Rust
        [`Debug`](std::fmt::Debug) implementation.
        """

@typing.final
class InfixOperator(enum.Enum):
    CARET = ...
    PLUS = ...
    MINUS = ...
    SLASH = ...
    STAR = ...

    def __getnewargs__(self) -> tuple[builtins.int]: ...
    def __new__(cls, value: builtins.int) -> InfixOperator: ...
    def __repr__(self) -> builtins.str:
        r"""
        Implements `__repr__` for Python in terms of the Rust
        [`Debug`](std::fmt::Debug) implementation.
        """

@typing.final
class PrefixOperator(enum.Enum):
    PLUS = ...
    MINUS = ...

    def __getnewargs__(self) -> tuple[builtins.int]: ...
    def __new__(cls, value: builtins.int) -> PrefixOperator: ...
    def __repr__(self) -> builtins.str:
        r"""
        Implements `__repr__` for Python in terms of the Rust
        [`Debug`](std::fmt::Debug) implementation.
        """