oqpy.base

Base classes and conversion methods for OQpy.

This class establishes how expressions are represented in oqpy and how they are converted to AST nodes.

class oqpy.base.ExpressionConvertible(*args, **kwargs)

Bases: Protocol

This is the protocol an object can implement in order to be usable as an expression.

class oqpy.base.HasToAst(*args, **kwargs)

Bases: Protocol

Protocol for objects which can be converted into ast nodes.

to_ast(program: Program) → ast.Expression

Converts the OQpy object into an ast node.

class oqpy.base.OQPyBinaryExpression(op: BinaryOperator, lhs: Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression], rhs: Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression])

Bases: OQPyExpression

An expression consisting of two subexpressions joined by an operator.

to_ast(program: Program) → ast.BinaryExpression

Converts the OQpy expression into an ast node.

class oqpy.base.OQPyExpression

Bases: object

Base class for OQPy expressions.

Subclasses must implement to_ast method and supply the type attribute

Expressions can be composed via overloaded arithmetic and boolean comparison operators to create new expressions. Note this means you cannot evaluate expression equality via == which produces a new expression instead of producing a python boolean.

to_ast(program: Program) → ast.Expression

Converts the oqpy expression into an ast node.

type: ClassicalType

class oqpy.base.Var(name: str, needs_declaration: bool = True)

Bases: ABC

Abstract base class for both classical and quantum variables.

abstract make_declaration_statement(program: Program) → ast.Statement

Make an ast statement that declares the OQpy variable.

abstract to_ast(program: Program) → ast.Expression

Converts the OQpy variable into an ast node.

oqpy.base.expr_matches(a: Any, b: Any) → bool

Check equality of the given objects.

This bypasses calling __eq__ on expr objects.

oqpy.base.map_to_ast(program: Program, items: Iterable[AstConvertible]) → list[ast.Expression]

Convert a sequence of items into a sequence of ast nodes.

oqpy.base.optional_ast(program: Program, item: AstConvertible | None) → ast.Expression | None

Convert item to ast if it is not None.

oqpy.base.to_ast(program: Program, item: AstConvertible) → ast.Expression

Convert an object to an AST node.

oqpy.classical_types

Classes representing oqpy variables with classical types.

class oqpy.classical_types.AngleVar(*args: Any, size: Optional[int] = None, **kwargs: Any)

Bases: _SizedVar

An oqpy variable with angle type.

default_size: int | None = 32

type_cls

alias of AngleType

class oqpy.classical_types.BitVar(*args: Any, size: Optional[int] = None, **kwargs: Any)

Bases: _SizedVar

An oqpy variable with bit type.

type_cls

alias of BitType

class oqpy.classical_types.BoolVar(init_expression: Optional[Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression]] = None, name: Optional[str] = None, needs_declaration: bool = True, **type_kwargs: Any)

Bases: _ClassicalVar

An (unsized) oqpy variable with bool type.

type_cls

alias of BoolType

class oqpy.classical_types.ComplexVar(init_expression: Optional[Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression]] = None, *args: Any, base_type: Type[FloatType] = FloatType(span=None, size=IntegerLiteral(span=None, value=64)), **kwargs: Any)

Bases: _ClassicalVar

An oqpy variable with bit type.

type_cls

alias of ComplexType

class oqpy.classical_types.DurationVar(init_expression: Optional[Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression]] = None, name: Optional[str] = None, *args: Any, **type_kwargs: Any)

Bases: _ClassicalVar

An oqpy variable with duration type.

type_cls

alias of DurationType

class oqpy.classical_types.FloatVar(*args: Any, size: Optional[int] = None, **kwargs: Any)

Bases: _SizedVar

An oqpy variable with floating type.

default_size: int | None = 64

type_cls

alias of FloatType

class oqpy.classical_types.IntVar(*args: Any, size: Optional[int] = None, **kwargs: Any)

Bases: _SizedVar

An oqpy variable with integer type.

default_size: int | None = 32

type_cls

alias of IntType

class oqpy.classical_types.OQFunctionCall(identifier: Union[str, Identifier], args: Iterable[Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression]], return_type: ClassicalType, extern_decl: Optional[ExternDeclaration] = None, subroutine_decl: Optional[SubroutineDefinition] = None)

Bases: OQPyExpression

An oqpy expression corresponding to a function call.

to_ast(program: Program) → ast.Expression

Converts the OQpy expression into an ast node.

class oqpy.classical_types.StretchVar(init_expression: Optional[Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression]] = None, name: Optional[str] = None, needs_declaration: bool = True, **type_kwargs: Any)

Bases: _ClassicalVar

An oqpy variable with stretch type.

type_cls

alias of StretchType

class oqpy.classical_types.UintVar(*args: Any, size: Optional[int] = None, **kwargs: Any)

Bases: _SizedVar

An oqpy variable with unsigned integer type.

default_size: int | None = 32

type_cls

alias of UintType

oqpy.classical_types.angle_(size: int) → AngleType

Create a sized angle type.

oqpy.classical_types.bit_(size: int) → BitType

Create a sized bit type.

oqpy.classical_types.complex_(size: int) → ComplexType

Create a sized complex type.

Note the size represents the total size, and thus the components have half of the requested size.

oqpy.classical_types.convert_range(program: Program, item: Union[slice, range]) → ast.RangeDefinition

Convert a slice or range into an ast node.

oqpy.classical_types.float_(size: int) → FloatType

Create a sized floating-point type.

oqpy.classical_types.int_(size: int) → IntType

Create a sized signed integer type.

oqpy.classical_types.uint_(size: int) → UintType

Create a sized unsigned integer type.

oqpy.control_flow

Context manager objects used for creating control flow contexts.

oqpy.control_flow.Else(program: Program) → Iterator[None]

Context manager for conditional evaluation. Must come after an “If” context block.

i = IntVar(1)
with If(program, i == 1):
    program.increment(i, 1)
with Else(program):
    program.increment(i, 2)

oqpy.control_flow.ForIn(program: Program, iterator: Iterable[AstConvertible] | range | AstConvertible, identifier_name: Optional[str] = None) → Iterator[IntVar]

Context manager for looping a particular portion of a program.

i = IntVar(1)
with ForIn(program, range(1, 10)) as index:
    program.increment(i, index)

oqpy.control_flow.If(program: Program, condition: OQPyExpression) → Iterator[None]

Context manager for doing conditional evaluation.

i = IntVar(1)
with If(program, i == 1):
    program.increment(i)

oqpy.control_flow.While(program: Program, condition: OQPyExpression) → Iterator[None]

Context manager for looping a repeating a portion of a program while a condition is True.

i = IntVar(1)
with While(program, i < 5) as index:
    program.increment(i, 1)

oqpy.program

Module containing Program and related classes.

This module contains the oqpy.Program class, which is the primary user interface for constructing openqasm/openpulse. The class follows the builder pattern in that it contains a representation of the state of a program (internally represented as AST components), and the class has methods which add to the current state.

class oqpy.program.Program(version: Optional[str] = '3.0')

Bases: object

A builder class for OpenQASM/OpenPulse programs.

autodeclare(encal: bool = False) → None

Declare any currently undeclared variables at the beginning of the program.

barrier(qubits_or_frames: Iterable[Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression]]) → Program

Apply a barrier to a set of qubits or frames.

capture(frame: Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression], kernel: Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression]) → Program

Capture signal integrated against a kernel on a particular frame.

declare(variables: list[oqpy.base.Var] | oqpy.base.Var, to_beginning: bool = False, encal: bool = False) → Program

Declare a variable.

Parameters

• variables – A list of variables to declare, or a single variable to declare.

• to_beginning – If true, insert the declaration at the beginning of the program, instead of at the current point.

• encal – If true, wrap any declarations of undeclared variables with openpulse types in a cal block.

decrement(var: _ClassicalVar, value: Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression]) → Program

Decrement a variable value.

delay(time: Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression], qubits_or_frames: Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression, Iterable[Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression]]] = ()) → Program

Apply a delay to a set of qubits or frames.

property frame_vars: Iterator[FrameVar]

Returns an Iterator of any declared/undeclared FrameVar used in the program.

function_call(name: str, args: Iterable[Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression]]) → None

Add a function call.

gate(qubits: Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression, Iterable[Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression]]], name: str, *args: Any) → Program

Apply a gate to a qubit or set of qubits.

increment(var: _ClassicalVar, value: Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression]) → Program

Increment a variable value.

measure(qubit: Qubit, output_location: Optional[BitVar] = None) → Program

Measure a particular qubit.

If provided, store the result in the given output location.

mod_equals(var: IntVar, value: Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression]) → Program

In-place update of a variable to be itself modulo value.

play(frame: Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression], waveform: Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression]) → Program

Play a waveform on a particular frame.

reset(qubit: Qubit) → Program

Reset a particular qubit.

set(var: _ClassicalVar, value: Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression]) → Program

Set a variable value.

set_frequency(frame: Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression], freq: Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression]) → Program

Set the frequency of a particular frame.

set_phase(frame: Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression], phase: Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression]) → Program

Set the phase of a particular frame.

set_scale(frame: Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression], scale: Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression]) → Program

Set the amplitude scaling of a particular frame.

shift_frequency(frame: Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression], freq: Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression]) → Program

Shift the frequency of a particular frame.

shift_phase(frame: Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression], phase: Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression]) → Program

Shift the phase of a particular frame.

shift_scale(frame: Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression], scale: Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression]) → Program

Shift the amplitude scaling of a particular frame.

to_ast(encal: bool = False, include_externs: bool = True, ignore_needs_declaration: bool = False, encal_declarations: bool = False) → Program

Convert to an AST program.

Parameters

• encal – If true, wrap all statements in a “Cal” block, ensuring that all openpulse statements are contained within a Cal block.

• include_externs – If true, for all used extern statements, include an extern declaration at the top of the program.

• ignore_needs_declaration – If true, the field _needs_declaration of undeclared variables is ignored and their declaration will not be added to the AST

• encal_declarations – If true, when declaring undeclared variables, if the variables have openpulse types, automatically wrap the declarations in cal blocks.

to_qasm(encal: bool = False, include_externs: bool = True, ignore_needs_declaration: bool = False, encal_declarations: bool = False) → str

Convert to QASM text.

See to_ast for option documentation.

property waveform_vars: Iterator[WaveformVar]

Returns an Iterator of any declared/undeclared WaveformVar used in the program.

oqpy.pulse

Classes representing OpenPulse variable types.

class oqpy.pulse.FrameVar(port: Optional[PortVar] = None, frequency: Optional[Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression]] = None, phase: Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression] = 0, name: Optional[str] = None, needs_declaration: bool = True)

Bases: _ClassicalVar

A variable type corresponding to an OpenPulse frame.

type_cls

alias of FrameType

class oqpy.pulse.PortVar(name: Optional[str] = None, **kwargs: Any)

Bases: _ClassicalVar

A variable type corresponding to an OpenPulse port.

type_cls

alias of PortType

class oqpy.pulse.WaveformVar(init_expression: Optional[Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression]] = None, name: Optional[str] = None, **kwargs: Any)

Bases: _ClassicalVar

A variable type corresponding to an OpenPulse waveform.

type_cls

alias of WaveformType

oqpy.quantum_types

Classes representing variables containing quantum types (i.e. Qubits).

oqpy.quantum_types.Cal(program: Program) → Iterator[None]

Context manager that begins a cal block.

class oqpy.quantum_types.PhysicalQubits

Bases: object

Provides a means of accessing qubit variables corresponding to physical qubits.

For example, the openqasm qubit “$3” is accessed by PhysicalQubits[3].

class oqpy.quantum_types.Qubit(name: str, needs_declaration: bool = True)

Bases: Var

OQpy variable representing a single qubit.

make_declaration_statement(program: Program) → ast.Statement

Make an ast statement that declares the OQpy variable.

to_ast(prog: Program) → ast.Expression

Converts the OQpy variable into an ast node.

class oqpy.quantum_types.QubitArray

Bases: object

Represents an array of qubits.

oqpy.quantum_types.defcal(program: Program, qubits: Union[Qubit, list[Qubit]], name: str) → Iterator[None]

Context manager for creating a defcal.

with defcal(program, q1, "X"):
    program.play(frame, waveform)

oqpy.subroutines

Contains methods for producing subroutines and extern function calls.

oqpy.subroutines.declare_extern(name: str, args: list[tuple[str, openqasm3.ast.ClassicalType]], return_type: ClassicalType) → Callable[[...], OQFunctionCall]

Declare an extern and return a callable which adds the extern.

sqrt = declare_extern(
    "sqrt",
    [("x", classical_types.float32)],
    classical_types.float32,
)
var = FloatVar[32]()
program.set(var, sqrt(0.5))

oqpy.subroutines.declare_waveform_generator(name: str, argtypes: list[tuple[str, openqasm3.ast.ClassicalType]]) → Callable[[...], OQFunctionCall]

Create a function which generates waveforms using a specified name and argument signature.

oqpy.subroutines.subroutine(func: Callable[[Program, Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression]], Optional[Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression]]]) → Callable[[Program, Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression]], OQFunctionCall]

Decorator to declare a subroutine.

The function should take a program as well as any other arguments required. Note that the decorated function must include type hints for all arguments, and (other than the initial program) all of these type hints must be oqpy Variable types.

@subroutine
def increment_variable(program: Program, i: IntVar):
    program.increment(i, 1)

j = IntVar(0)
increment_variable(j)

This should generate the following OpenQASM:

def increment_variable(int[32] i) {
    i += 1;
}

int[32] j = 0;
increment_variable(j);

oqpy.timing

Constructs for manipulating sequence timing.

oqpy.timing.Box(program: Program, duration: AstConvertible | None = None) → Iterator[None]

Creates a section of the program with a specified duration.

oqpy.timing.make_duration(time: Union[HasToAst, bool, int, float, complex, Iterable, ExpressionConvertible, Expression]) → HasToAst

Make value into an expression representing a duration.