`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.CachedExpressionConvertible(*args, **kwargs)[source]

Bases: Protocol

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

The difference between this and ExpressionConvertible is that this requires that the result of _to_cached_oqpy_expression be constant across the lifetime of the OQPy Program. OQPy makes an effort to minimize the number of calls to the AST constructor, but no guarantees are made about this.

class oqpy.base.ExpressionConvertible(*args, **kwargs)[source]

Bases: Protocol

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

class oqpy.base.HasToAst(*args, **kwargs)[source]

Bases: Protocol

Protocol for objects which can be converted into ast nodes.

to_ast(program: Program) → ast.Expression[source]: Converts the OQpy object into an ast node.

Bases: OQPyExpression

An expression consisting of two subexpressions joined by an operator.

to_ast(program: Program) → ast.BinaryExpression[source]: Converts the OQpy expression into an ast node.

class oqpy.base.OQPyExpression[source]

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[source]: Converts the oqpy expression into an ast node.

type: ClassicalType | None

Bases: OQPyExpression

An expression consisting of one expression preceded by an operator.

to_ast(program: Program) → ast.UnaryExpression[source]: Converts the OQpy expression into an ast node.

class oqpy.base.Var(name: str, needs_declaration: bool = True)[source]

Bases: ABC

Abstract base class for both classical and quantum variables.

abstract make_declaration_statement(program: Program) → ast.Statement[source]: Make an ast statement that declares the OQpy variable.

abstract to_ast(program: Program) → ast.Expression[source]: Converts the OQpy variable into an ast node.

oqpy.base.compute_product_types(left: HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression, right: HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression) → ClassicalType[source]: Find the result type for a product of two terms.

oqpy.base.compute_quotient_types(left: HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression, right: HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression) → ClassicalType[source]: Find the result type for a quotient of two terms.

oqpy.base.detect_and_convert_constants(val: float | np.floating[Any], program: Program) → ast.Expression[source]: Construct a float ast expression which is either a literal or an expression using constants.

oqpy.base.expr_matches(a: Any, b: Any) → bool[source]

Check equality of the given objects.

This bypasses calling __eq__ on expr objects.

oqpy.base.logical_and(first: HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression, second: HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression) → OQPyBinaryExpression[source]: Logical AND.

oqpy.base.logical_or(first: HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression, second: HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression) → OQPyBinaryExpression[source]: Logical OR.

oqpy.base.make_annotations(vals: Sequence[str | tuple[str, str]]) → list[Annotation][source]: Convert strings/tuples of strings into Annotation ast nodes.

oqpy.base.map_to_ast(program: Program, items: Iterable[AstConvertible]) → list[ast.Expression][source]: Convert a sequence of items into a sequence of ast nodes.

oqpy.base.optional_ast(program: Program, item: AstConvertible | None) → ast.Expression | None[source]: Convert item to ast if it is not None.

oqpy.base.to_ast(program: Program, item: AstConvertible) → ast.Expression[source]: 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: int | None | EllipsisType = Ellipsis, **kwargs: Any)[source]

Bases: _SizedVar

An oqpy variable with angle type.

default_size: int | None = 32

type_cls: alias of AngleType

class oqpy.classical_types.ArrayVar(*args: ~typing.Any, dimensions: list[int], base_type: type[~oqpy.classical_types._SizedVar | ~oqpy.classical_types.DurationVar | ~oqpy.classical_types.BoolVar | ~oqpy.classical_types.ComplexVar] = <class 'oqpy.classical_types.IntVar'>, **kwargs: ~typing.Any)[source]

Bases: _ClassicalVar

An oqpy array variable.

base_type: type[_SizedVar | DurationVar | BoolVar | ComplexVar]

dimensions: list[int]

type_cls: alias of ArrayType

class oqpy.classical_types.BitVar(*args: Any, size: int | None | EllipsisType = Ellipsis, **kwargs: Any)[source]

Bases: _SizedVar

An oqpy variable with bit type.

type_cls: alias of BitType

class oqpy.classical_types.BoolVar(init_expression: AstConvertible | Literal['input', 'output'] | None = None, name: str | None = None, needs_declaration: bool = True, annotations: Sequence[str | tuple[str, str]] = (), **type_kwargs: Any)[source]

Bases: _ClassicalVar

An (unsized) oqpy variable with bool type.

type_cls: alias of BoolType

class oqpy.classical_types.ComplexVar(init_expression: AstConvertible | Literal['input', 'output'] | None = None, *args: Any, base_type: ast.FloatType = FloatType(span=None, size=IntegerLiteral(span=None, value=64)), **kwargs: Any)[source]

Bases: _ClassicalVar

An oqpy variable with bit type.

base_type: FloatType = FloatType(span=None, size=IntegerLiteral(span=None, value=64))

type_cls: alias of ComplexType

class oqpy.classical_types.DurationVar(init_expression: AstConvertible | Literal['input', 'output'] | None = None, name: str | None = None, *args: Any, **type_kwargs: Any)[source]

Bases: _ClassicalVar

An oqpy variable with duration type.

type_cls: alias of DurationType

class oqpy.classical_types.FloatVar(*args: Any, size: int | None | EllipsisType = Ellipsis, **kwargs: Any)[source]

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: int | None | EllipsisType = Ellipsis, **kwargs: Any)[source]

Bases: _SizedVar

An oqpy variable with integer type.

default_size: int | None = 32

type_cls: alias of IntType

Bases: OQPyExpression

An oqpy expression corresponding to a function call.

to_ast(program: Program) → ast.Expression[source]: Converts the OQpy expression into an ast node.

Bases: OQPyExpression

An oqpy expression corresponding to an index expression.

to_ast(program: Program) → ast.IndexExpression[source]: Converts this oqpy index expression into an ast node.

class oqpy.classical_types.StretchVar(init_expression: AstConvertible | Literal['input', 'output'] | None = None, name: str | None = None, needs_declaration: bool = True, annotations: Sequence[str | tuple[str, str]] = (), **type_kwargs: Any)[source]

Bases: _ClassicalVar

An oqpy variable with stretch type.

type_cls: alias of StretchType

class oqpy.classical_types.UintVar(*args: Any, size: int | None | EllipsisType = Ellipsis, **kwargs: Any)[source]

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 | None = None) → AngleType[source]: Create a sized angle type.

oqpy.classical_types.arrayreference_(dtype: IntType | UintType | FloatType | AngleType | DurationType | BitType | BoolType | ComplexType, dims: int | list[int]) → ArrayReferenceType[source]: Create an array reference type.

oqpy.classical_types.bit_(size: int | None = None) → BitType[source]: Create a sized bit type.

oqpy.classical_types.complex_(size: int) → ComplexType[source]

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: slice | range) → ast.RangeDefinition[source]: Convert a slice or range into an ast node.

oqpy.classical_types.float_(size: int | None = None) → FloatType[source]: Create a sized floating-point type.

oqpy.classical_types.int_(size: int | None = None) → IntType[source]: Create a sized signed integer type.

oqpy.classical_types.uint_(size: int | None = None) → UintType[source]: 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][source]

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: str | None) → contextlib._GeneratorContextManager[IntVar][source]

oqpy.control_flow.ForIn(program: Program, iterator: Iterable[AstConvertible] | range | AstConvertible, identifier_name: str | None, identifier_type: type[ClassicalVarT]) → contextlib._GeneratorContextManager[ClassicalVarT]

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][source]

Context manager for doing conditional evaluation.

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

Bases: object

AstConvertible which creates an integer range.

Unlike builtin python range, this allows the components to be AstConvertible, instead of just int.

to_ast(program: Program) → ast.Expression[source]: Convert to an ast.RangeDefinition.

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

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: str | None = '3.0', simplify_constants: bool = True)[source]

Bases: object

A builder class for OpenQASM/OpenPulse programs.

DURATION_MAX_DIGITS = 12

annotate(keyword: str, command: str | None = None) → Program[source]: Add an annotation to the next statement.

autodeclare(encal: bool = False) → None[source]: Declare any currently undeclared variables at the beginning of the program.

barrier(qubits_or_frames: Iterable[HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression]) → Program[source]: Apply a barrier to a set of qubits or frames.

capture(frame: HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression, kernel: HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression) → Program[source]: Capture signal integrated against a kernel on a particular frame.

declare(variables: list[Var] | Var, to_beginning: bool = False, encal: bool = False) → Program[source]

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: HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression) → Program[source]: Decrement a variable value.

delay(time: HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression, qubits_or_frames: HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression | Iterable[HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression] = ()) → Program[source]: Apply a delay to a set of qubits or frames.

do_expression(expression: HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression) → Program[source]: Add a statement which evaluates a given expression without assigning the output.

expr_cache: dict[Hashable, Expression]

A cache of ast made by CachedExpressionConvertible objects used in this program.

This is used by to_ast to avoid repetitively evaluating ast conversion methods.

property frame_vars: Iterator[FrameVar]: Returns an Iterator of any declared/undeclared FrameVar used in the program.

function_call(name: str, args: Iterable[HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression], assigns_to: HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression | None = None) → None[source]: Add a function call with an optional output assignment.

Apply a gate with its modifiers to a qubit or set of qubits.

Parameters:

qubits (AstConvertible | Iterable[AstConvertible]) – The qubit or list of qubits to which the gate will be applied
name (str) – The gate name
*args (Any) – A list of parameters passed to the gate
control (quantum_types.Qubit | Iterable[quantum_types.Qubit] | None) – The list of control qubits (default: None)
neg_control – (quantum_types.Qubit | Iterable[quantum_types.Qubit] | None): The list of negative control qubits (default: None)
inv (bool) – Flag to use the inverse gate (default: False)
exp (AstConvertible) – The exponent used with pow gate modifier

Returns:

The OQpy program to which the gate is added

Return type:

Program

include(path: str) → Program[source]: Add an include statement.

increment(var: _ClassicalVar, value: HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression) → Program[source]: Increment a variable value.

measure(qubit: Qubit, output_location: BitVar | None = None) → Program[source]

Measure a particular qubit.

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

mod_equals(var: IntVar, value: HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression) → Program[source]: In-place update of a variable to be itself modulo value.

play(frame: HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression, waveform: HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression) → Program[source]: Play a waveform on a particular frame.

pragma(command: str) → Program[source]: Add a pragma instruction.

reset(qubit: Qubit) → Program[source]: Reset a particular qubit.

returns(expression: HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression) → Program[source]: Return a statement from a function definition or a defcal statement.

set(var: _ClassicalVar | OQIndexExpression, value: HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression) → Program[source]: Set a variable value.

set_frequency(frame: HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression, freq: HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression) → Program[source]: Set the frequency of a particular frame.

set_phase(frame: HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression, phase: HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression) → Program[source]: Set the phase of a particular frame.

set_scale(frame: HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression, scale: HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression) → Program[source]: Set the amplitude scaling of a particular frame.

shift_frequency(frame: HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression, freq: HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression) → Program[source]: Shift the frequency of a particular frame.

shift_phase(frame: HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression, phase: HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression) → Program[source]: Shift the phase of a particular frame.

shift_scale(frame: HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression, scale: HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression) → Program[source]: 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[source]

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[source]

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.

Bases: _ClassicalVar

A variable type corresponding to an OpenPulse frame.

type_cls: alias of FrameType

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

Bases: _ClassicalVar

A variable type corresponding to an OpenPulse port.

type_cls: alias of PortType

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][source]: Context manager that begins a cal block.

class oqpy.quantum_types.PhysicalQubits[source]

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, size: int | None = None, needs_declaration: bool = True, annotations: Sequence[str | tuple[str, str]] = ())[source]

Bases: Var

OQpy variable representing a single qubit.

make_declaration_statement(program: Program) → ast.Statement[source]: Make an ast statement that declares the OQpy variable.

to_ast(prog: Program) → ast.Expression[source]: Converts the OQpy variable into an ast node.

oqpy.quantum_types.defcal(program: Program, qubits: Qubit | list[Qubit], name: str, arguments: list[AstConvertible] | None = None, return_type: ast.ClassicalType | None = None) → Iterator[None] | Iterator[list[_ClassicalVar]] | Iterator[_ClassicalVar][source]

Context manager for creating a defcal.

with defcal(program, q1, "X", [AngleVar(name="theta"), oqpy.pi/2], oqpy.bit) as theta:
    program.play(frame, waveform)

oqpy.quantum_types.gate(program: Program, qubits: Qubit | list[Qubit], name: str, arguments: list[AstConvertible] | None = None, declare_here: bool = False) → Iterator[None] | Iterator[list[AngleVar]] | Iterator[AngleVar][source]

Context manager for creating a gate.

with gate(program, q1, "HRzH", [AngleVar(name="theta")]) as theta:
    program.gate(q1, "H")
    program.gate(q1, "Rz", theta)
    program.gate(q1, "H")

`oqpy.subroutines`

Contains methods for producing subroutines and extern function calls.

class oqpy.subroutines.OQPyArgument(name: str, dtype: ClassicalType, access: Literal['readonly', 'mutable'] | None = None)[source]

Bases: object

An oqpy argument to extern declaration..

access: Literal['readonly', 'mutable'] | None = None

dtype: ClassicalType

name: str

unzip() → tuple[str, ClassicalType, AccessControl | None][source]: Returns the three values, name, dtype and access as a tuple.

oqpy.subroutines.declare_extern(name: str, args: list[tuple[str, ClassicalType] | OQPyArgument], return_type: ClassicalType | None = None, annotations: Sequence[str | tuple[str, str]] = ()) → Callable[[...], OQFunctionCall][source]

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, ClassicalType] | OQPyArgument], annotations: Sequence[str | tuple[str, str]] = ()) → Callable[[...], OQFunctionCall][source]: Create a function which generates waveforms using a specified name and argument signature.

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(annotations=("optimize", "-O3"))
def increment_variable(program: Program, i: IntVar):
    program.increment(i, 1)

j = IntVar(0)
increment_variable(j)

This should generate the following OpenQASM:

@optimize-O3
def increment_variable(int[32] i) {
    i += 1;
}

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

Parameters:

func (Callable[[oqpy.Program, VarArg(AstConvertible)], AstConvertible | None]) – function to decorate. Its first argument must be an OQpy program.
annotations (Sequence[str | tuple[str, str]]) – a collection of strings or tuples of string that annotate the subroutine.

Returns:

decorated function with added subroutine_declaration attribute.

Return type:

Callable[[oqpy.Program, VarArg(AstConvertible)], AstConvertible | None]

`oqpy.timing`

Constructs for manipulating sequence timing.

oqpy.timing.Box(program: Program, duration: AstConvertible | None = None) → Iterator[None][source]: Creates a section of the program with a specified duration.

Make value into an expression representing a duration.

Parameters:

time – the time
require_nonnegative – if True, raise an exception if the time value is known to be negative.

oqpy.timing.make_duration(time: HasToAst | bool | int | float | complex | Iterable | ExpressionConvertible | CachedExpressionConvertible | Expression) → HasToAst[source]: Make value into an expression representing a duration.

oqpy.base

oqpy.classical_types

oqpy.control_flow

oqpy.program

oqpy.pulse

oqpy.quantum_types

oqpy.subroutines

oqpy.timing

`oqpy.base`

`oqpy.classical_types`

`oqpy.control_flow`

`oqpy.program`

`oqpy.pulse`

`oqpy.quantum_types`

`oqpy.subroutines`

`oqpy.timing`