0
# AST Node Hierarchy
1
2
Complete abstract syntax tree representing all OpenQASM 3 language constructs including quantum gates, classical code, control flow, type system, and calibration blocks. The AST provides a structured representation that enables systematic analysis and manipulation of OpenQASM 3 programs.
3
4
## Capabilities
5
6
### Base Classes
7
8
Foundational classes that define the structure and behavior of all AST nodes.
9
10
```python { .api }
11
@dataclass
12
class QASMNode:
13
"""Base class for all OpenQASM 3 nodes"""
14
span: Optional[Span] = field(init=False, default=None, compare=False)
15
16
@dataclass
17
class Statement(QASMNode):
18
"""A statement: anything that can appear on its own line"""
19
annotations: List[Annotation] = field(init=False, default_factory=list)
20
21
class Expression(QASMNode):
22
"""Base class for anything that returns a value"""
23
pass
24
25
class QuantumStatement(Statement):
26
"""Base class for statements that may appear inside a gate declaration"""
27
pass
28
29
class ClassicalType(QASMNode):
30
"""Base class for classical types"""
31
pass
32
```
33
34
### Program Structure
35
36
Top-level program representation and structural elements.
37
38
```python { .api }
39
@dataclass
40
class Program(QASMNode):
41
"""An entire OpenQASM 3 program represented by a list of top level statements"""
42
statements: List[Union[Statement, Pragma]]
43
version: Optional[str] = None
44
45
@dataclass
46
class CompoundStatement(Statement):
47
"""A sequence of statements enclosed within an anonymous scope block"""
48
statements: List[Statement]
49
50
@dataclass
51
class Annotation(QASMNode):
52
"""An annotation applied to a statement"""
53
keyword: str
54
command: Optional[str] = None
55
56
@dataclass
57
class Pragma(QASMNode):
58
"""Pragma directive"""
59
command: str
60
```
61
62
### Declaration Statements
63
64
Statements that declare variables, qubits, gates, and other program elements.
65
66
```python { .api }
67
@dataclass
68
class QubitDeclaration(Statement):
69
"""Global qubit declaration (e.g., qubit q; or qubit[4] q;)"""
70
qubit: Identifier
71
size: Optional[Expression] = None
72
73
@dataclass
74
class ClassicalDeclaration(Statement):
75
"""Classical variable declaration"""
76
type: ClassicalType
77
identifier: Identifier
78
init_expression: Optional[Union[Expression, QuantumMeasurement]] = None
79
80
@dataclass
81
class ConstantDeclaration(Statement):
82
"""Constant declaration"""
83
type: ClassicalType
84
identifier: Identifier
85
init_expression: Expression
86
87
@dataclass
88
class IODeclaration(Statement):
89
"""Input/output variable declaration"""
90
io_identifier: IOKeyword
91
type: ClassicalType
92
identifier: Identifier
93
94
@dataclass
95
class ExternDeclaration(Statement):
96
"""External function declaration"""
97
name: Identifier
98
arguments: List[ExternArgument]
99
return_type: Optional[ClassicalType] = None
100
```
101
102
### Quantum Statements
103
104
Statements specific to quantum operations and gate definitions.
105
106
```python { .api }
107
@dataclass
108
class QuantumGateDefinition(Statement):
109
"""Define a new quantum gate"""
110
name: Identifier
111
arguments: List[Identifier]
112
qubits: List[Identifier]
113
body: List[QuantumStatement]
114
115
@dataclass
116
class QuantumGate(QuantumStatement):
117
"""Invoking a quantum gate"""
118
modifiers: List[QuantumGateModifier]
119
name: Identifier
120
arguments: List[Expression]
121
qubits: List[Union[IndexedIdentifier, Identifier]]
122
duration: Optional[Expression] = None
123
124
@dataclass
125
class QuantumPhase(QuantumStatement):
126
"""Quantum phase instruction"""
127
modifiers: List[QuantumGateModifier]
128
argument: Expression
129
qubits: List[Union[IndexedIdentifier, Identifier]]
130
131
@dataclass
132
class QuantumBarrier(QuantumStatement):
133
"""Quantum barrier instruction"""
134
qubits: List[Expression]
135
136
@dataclass
137
class QuantumReset(QuantumStatement):
138
"""Reset instruction"""
139
qubits: Union[IndexedIdentifier, Identifier]
140
141
@dataclass
142
class QuantumMeasurement(QASMNode):
143
"""Quantum measurement instruction"""
144
qubit: Union[IndexedIdentifier, Identifier]
145
146
@dataclass
147
class QuantumMeasurementStatement(Statement):
148
"""Stand-alone quantum measurement statement"""
149
measure: QuantumMeasurement
150
target: Optional[Union[IndexedIdentifier, Identifier]] = None
151
```
152
153
### Control Flow Statements
154
155
Statements for classical and quantum control flow including loops and conditionals.
156
157
```python { .api }
158
@dataclass
159
class BranchingStatement(Statement):
160
"""Branch (if) statement"""
161
condition: Expression
162
if_block: List[Statement]
163
else_block: List[Statement]
164
165
@dataclass
166
class WhileLoop(Statement):
167
"""While loop statement"""
168
while_condition: Expression
169
block: List[Statement]
170
171
@dataclass
172
class ForInLoop(Statement):
173
"""For-in loop statement"""
174
type: ClassicalType
175
identifier: Identifier
176
set_declaration: Union[RangeDefinition, DiscreteSet, Expression]
177
block: List[Statement]
178
179
@dataclass
180
class SwitchStatement(Statement):
181
"""Switch-case statement"""
182
target: Expression
183
cases: List[Tuple[List[Expression], CompoundStatement]]
184
default: Optional[CompoundStatement] = None
185
186
class BreakStatement(Statement):
187
"""Break statement"""
188
pass
189
190
class ContinueStatement(Statement):
191
"""Continue statement"""
192
pass
193
194
class EndStatement(Statement):
195
"""End statement"""
196
pass
197
198
@dataclass
199
class ReturnStatement(Statement):
200
"""Classical or quantum return statement"""
201
expression: Optional[Union[Expression, QuantumMeasurement]] = None
202
```
203
204
### Subroutine and Function Definitions
205
206
Definitions for classical subroutines and their arguments.
207
208
```python { .api }
209
@dataclass
210
class SubroutineDefinition(Statement):
211
"""Subroutine definition"""
212
name: Identifier
213
arguments: List[Union[ClassicalArgument, QuantumArgument]]
214
body: List[Statement]
215
return_type: Optional[ClassicalType] = None
216
217
@dataclass
218
class ClassicalArgument(QASMNode):
219
"""Classical argument for gate or subroutine declarations"""
220
type: ClassicalType
221
name: Identifier
222
access: Optional[AccessControl] = None
223
224
@dataclass
225
class QuantumArgument(QASMNode):
226
"""Quantum argument for subroutine declarations"""
227
name: Identifier
228
size: Optional[Expression] = None
229
230
@dataclass
231
class ExternArgument(QASMNode):
232
"""Classical argument for extern declarations"""
233
type: ClassicalType
234
access: Optional[AccessControl] = None
235
```
236
237
### Expression Types
238
239
All expression types including literals, operations, and function calls.
240
241
```python { .api }
242
@dataclass
243
class Identifier(Expression):
244
"""An identifier"""
245
name: str
246
247
@dataclass
248
class IndexedIdentifier(QASMNode):
249
"""Identifier with index operators for use as lvalue"""
250
name: Identifier
251
indices: List[IndexElement]
252
253
# Literal expressions
254
@dataclass
255
class IntegerLiteral(Expression):
256
"""Integer literal"""
257
value: int
258
259
@dataclass
260
class FloatLiteral(Expression):
261
"""Real number literal"""
262
value: float
263
264
@dataclass
265
class ImaginaryLiteral(Expression):
266
"""Imaginary number literal (e.g., 1.1im)"""
267
value: float
268
269
@dataclass
270
class BooleanLiteral(Expression):
271
"""Boolean literal (true or false)"""
272
value: bool
273
274
@dataclass
275
class BitstringLiteral(Expression):
276
"""Literal bitstring value with numerical value and width"""
277
value: int
278
width: int
279
280
@dataclass
281
class DurationLiteral(Expression):
282
"""Duration literal (e.g., 1.0ns)"""
283
value: float
284
unit: TimeUnit
285
286
@dataclass
287
class ArrayLiteral(Expression):
288
"""Array literal for initializing declared arrays"""
289
values: List[Expression]
290
291
# Operation expressions
292
@dataclass
293
class UnaryExpression(Expression):
294
"""Unary expression (e.g., ~b, !bool, -i)"""
295
op: UnaryOperator
296
expression: Expression
297
298
@dataclass
299
class BinaryExpression(Expression):
300
"""Binary expression (e.g., q1 || q2)"""
301
op: BinaryOperator
302
lhs: Expression
303
rhs: Expression
304
305
@dataclass
306
class FunctionCall(Expression):
307
"""Function call expression"""
308
name: Identifier
309
arguments: List[Expression]
310
311
@dataclass
312
class Cast(Expression):
313
"""Type cast expression"""
314
type: ClassicalType
315
argument: Expression
316
317
@dataclass
318
class IndexExpression(Expression):
319
"""Index expression (e.g., q[1])"""
320
collection: Expression
321
index: IndexElement
322
323
@dataclass
324
class Concatenation(Expression):
325
"""Concatenation of two registers (e.g., a ++ b)"""
326
lhs: Expression
327
rhs: Expression
328
329
@dataclass
330
class DurationOf(Expression):
331
"""Duration of a block of statements"""
332
target: List[Statement]
333
334
@dataclass
335
class SizeOf(Expression):
336
"""Size of an array's dimensions"""
337
target: Expression
338
index: Optional[Expression] = None
339
```
340
341
### Classical Types
342
343
Type system for classical variables and function parameters.
344
345
```python { .api }
346
# Basic scalar types
347
@dataclass
348
class IntType(ClassicalType):
349
"""Signed integer type with optional precision (e.g., int[8])"""
350
size: Optional[Expression] = None
351
352
@dataclass
353
class UintType(ClassicalType):
354
"""Unsigned integer type with optional precision (e.g., uint[8])"""
355
size: Optional[Expression] = None
356
357
@dataclass
358
class FloatType(ClassicalType):
359
"""IEEE-754 floating-point type with optional size (e.g., float[64])"""
360
size: Optional[Expression] = None
361
362
@dataclass
363
class ComplexType(ClassicalType):
364
"""Complex type with real and imaginary parts"""
365
base_type: Optional[FloatType] = None
366
367
@dataclass
368
class AngleType(ClassicalType):
369
"""Angle type with optional precision"""
370
size: Optional[Expression] = None
371
372
@dataclass
373
class BitType(ClassicalType):
374
"""Bit type with optional size"""
375
size: Optional[Expression] = None
376
377
class BoolType(ClassicalType):
378
"""Boolean classical type"""
379
pass
380
381
class DurationType(ClassicalType):
382
"""Duration type"""
383
pass
384
385
class StretchType(ClassicalType):
386
"""Stretch type for timing"""
387
pass
388
389
# Array types
390
@dataclass
391
class ArrayType(ClassicalType):
392
"""Arrays with allocated storage"""
393
base_type: Union[IntType, UintType, FloatType, ComplexType, AngleType, BitType, BoolType, DurationType]
394
dimensions: List[Expression]
395
396
@dataclass
397
class ArrayReferenceType(ClassicalType):
398
"""Array references (typically subroutine arguments)"""
399
base_type: Union[IntType, UintType, FloatType, ComplexType, AngleType, BitType, BoolType, DurationType]
400
dimensions: Union[Expression, List[Expression]]
401
```
402
403
### Helper and Utility Nodes
404
405
Supporting nodes for indexing, ranges, modifiers, and other language constructs.
406
407
```python { .api }
408
@dataclass
409
class DiscreteSet(QASMNode):
410
"""Set of discrete values for loops or indexing"""
411
values: List[Expression]
412
413
@dataclass
414
class RangeDefinition(QASMNode):
415
"""Range definition (e.g., 1:2, 1:1:10, :)"""
416
start: Optional[Expression] = None
417
end: Optional[Expression] = None
418
step: Optional[Expression] = None
419
420
@dataclass
421
class QuantumGateModifier(QASMNode):
422
"""Quantum gate modifier (inv, pow, ctrl, negctrl)"""
423
modifier: GateModifierName
424
argument: Optional[Expression] = None
425
426
@dataclass
427
class Include(Statement):
428
"""An include statement"""
429
filename: str
430
431
@dataclass
432
class ExpressionStatement(Statement):
433
"""A statement that contains a single expression"""
434
expression: Expression
435
436
@dataclass
437
class ClassicalAssignment(Statement):
438
"""Classical assignment statement"""
439
lvalue: Union[Identifier, IndexedIdentifier]
440
op: AssignmentOperator
441
rvalue: Expression
442
443
@dataclass
444
class AliasStatement(Statement):
445
"""Alias statement (e.g., let a = qubits[0];)"""
446
target: Identifier
447
value: Union[Identifier, Concatenation]
448
```
449
450
### Timing and Calibration
451
452
Nodes for timing control and pulse-level calibration.
453
454
```python { .api }
455
@dataclass
456
class DelayInstruction(QuantumStatement):
457
"""Delay instruction for timing control"""
458
duration: Expression
459
qubits: List[Union[IndexedIdentifier, Identifier]]
460
461
@dataclass
462
class Box(QuantumStatement):
463
"""Timing box for grouping quantum operations"""
464
duration: Optional[Expression]
465
body: List[QuantumStatement]
466
467
@dataclass
468
class CalibrationGrammarDeclaration(Statement):
469
"""Calibration grammar declaration"""
470
name: str
471
472
@dataclass
473
class CalibrationStatement(Statement):
474
"""Inline cal statement for embedded pulse-grammar interactions"""
475
body: str
476
477
@dataclass
478
class CalibrationDefinition(Statement):
479
"""Calibration definition for pulse-level gate definitions"""
480
name: Identifier
481
arguments: List[Union[ClassicalArgument, Expression]]
482
qubits: List[Identifier]
483
return_type: Optional[ClassicalType]
484
body: str
485
```
486
487
## Usage Examples
488
489
### Creating AST Nodes
490
491
```python
492
from openqasm3 import ast
493
494
# Create a qubit declaration: qubit[2] q;
495
qubit_decl = ast.QubitDeclaration(
496
qubit=ast.Identifier("q"),
497
size=ast.IntegerLiteral(2)
498
)
499
500
# Create a gate call: h q[0];
501
gate_call = ast.QuantumGate(
502
modifiers=[],
503
name=ast.Identifier("h"),
504
arguments=[],
505
qubits=[ast.IndexedIdentifier(
506
name=ast.Identifier("q"),
507
indices=[[ast.IntegerLiteral(0)]]
508
)]
509
)
510
511
# Create a complete program
512
program = ast.Program(
513
version="3.0",
514
statements=[qubit_decl, gate_call]
515
)
516
```
517
518
### Working with Types
519
520
```python
521
from openqasm3 import ast
522
523
# Create classical types
524
int_type = ast.IntType(size=ast.IntegerLiteral(32))
525
float_array = ast.ArrayType(
526
base_type=ast.FloatType(),
527
dimensions=[ast.IntegerLiteral(10)]
528
)
529
530
# Create a classical variable declaration: int[32] x = 42;
531
var_decl = ast.ClassicalDeclaration(
532
type=int_type,
533
identifier=ast.Identifier("x"),
534
init_expression=ast.IntegerLiteral(42)
535
)
536
```