autoqasm.program.program module

AutoQASM Program class, context managers, and related functions.

class autoqasm.program.program.UserConfig(num_qubits: int | None = None, device: Device | None = None)[source]

Bases: object

User-specified configurations that influence program building.

num_qubits: int | None = None

The total number of qubits to declare in the program.

device: Device | None = None

The target device for the program.

class autoqasm.program.program.ProgramScope(*values)[source]

Bases: Enum

Values used to specify the desired scope of a program to obtain.

CURRENT = 0

References the current scope of the program conversion context.

MAIN = 1

References the top-level (root) scope of the program conversion context.

class autoqasm.program.program.ProgramMode(*values)[source]

Bases: Enum

Values used to specify the desired mode of a program conversion context.

NONE = 0

For general program conversion where all operations are allowed.

UNITARY = 1

For program conversion inside a context where only unitary operations are allowed.

PULSE = 2

For program conversion inside a context where only pulse operations are allowed.

class autoqasm.program.program.MainProgram(program_generator: Callable[[Device | None], Program])[source]

Bases: SerializableProgram

Represents an AutoQASM program. The program can be built by calling build(), or it can be executed by passing it to the run() method of a Device object.

build(device: Device | str | None = None) → Program[source]

Builds and validates the AutoQASM program. If device is specified, program validation is also performed against the properties of the device.

Parameters:

device (Device | str | None) – Configuration to set the target device for the program. Can be either an Device object or a valid Amazon Braket device ARN.

Returns:

Program – The generated AutoQASM program.

to_ir(ir_type: IRType = IRType.OPENQASM, build_if_necessary: bool = True, serialization_properties: OpenQASMSerializationProperties = OpenQASMSerializationProperties(auto_defcalgrammar=False, include_externs=False)) → str[source]

Serializes the program into an intermediate representation.

Parameters:

  • ir_type (IRType) – The IRType to use for converting the program to its IR representation. Defaults to IRType.OPENQASM.

  • build_if_necessary (bool) – Whether to allow the program to be implicitly built as a side effect of calling this function. Defaults to True.

  • serialization_properties (SerializationProperties) – IR serialization configuration. Default to OpenQASMSerializationProperties().

Raises:

  • ValueError – Raised if the supplied ir_type is not supported.

  • RuntimeError – Raised if build_if_necessary is False, since a MainProgram object has not yet been built.

Returns:

str – A representation of the program in the ir_type format.

class autoqasm.program.program.Program(oqpy_program: Program, has_pulse_control: bool = False)[source]

Bases: SerializableProgram

The program that has been generated with AutoQASM. This object can be passed to the run() method of a Braket Device.

Initializes an AutoQASM Program object.

Parameters:

  • oqpy_program (oqpy.Program) – The oqpy program object which contains the generated program.

  • has_pulse_control (bool) – Whether the program contains pulse control instructions. Defaults to False.

with_calibrations(gate_calibrations: Callable | list[Callable]) → Program[source]

Add the gate calibrations to the program. The calibration added program is returned as a new object. The original program is not modified.

Parameters:

gate_calibrations (Callable | list[Callable]) – The gate calibrations to add to the main program. Calibration are passed as callable without evaluation.

Returns:

Program – The program with gate calibrations added.

make_bound_program(param_values: dict[str, float], strict: bool = False) → Program[source]

Binds FreeParameters based upon their name and values passed in.

Parameters:

  • param_values (dict[str, float]) – A mapping of FreeParameter names to a value to assign to them.

  • strict (bool) – If True, raises a ParameterNotFoundError if any of the FreeParameters in param_values do not appear in the program. False by default.

Raises:

ParameterNotFoundError – If a parameter name is given which does not appear in the program.

Returns:

Program – Returns a program with all present parameters fixed to their respective values.

to_ir(ir_type: IRType = IRType.OPENQASM, build_if_necessary: bool = True, serialization_properties: OpenQASMSerializationProperties = OpenQASMSerializationProperties(auto_defcalgrammar=False, include_externs=False)) → str[source]

Serializes the program into an intermediate representation.

Parameters:

  • ir_type (IRType) – The IRType to use for converting the program to its IR representation. Defaults to IRType.OPENQASM.

  • build_if_necessary (bool) – Whether to allow the program to be implicitly built as a side effect of calling this function. Defaults to True. This parameter is ignored for the Program class, since the program has already been built.

  • serialization_properties (SerializationProperties) – IR serialization configuration. Default to OpenQASMSerializationProperties().

Raises:

ValueError – If the supplied ir_type is not supported.

Returns:

str – A representation of the program in the ir_type format.

display(ir_type: IRType = IRType.OPENQASM) → None[source]

Print the Program with syntax highlighting. Returns None to avoid duplicate printing when used with print(program.display()).

Parameters:

ir_type (IRType) – The IRType to use for displaying the program. Defaults to IRType.OPENQASM.

class autoqasm.program.program.GateArgs[source]

Bases: object

Represents a list of qubit and angle arguments for a gate definition.

append_qubit(name: str) → None[source]

Appends a qubit argument to the list of gate arguments.

Parameters:

name (str) – The name of the argument.

append_angle(name: str) → None[source]

Appends a parameter argument to the list of gate arguments.

Parameters:

name (str) – The name of the argument.

property qubits: list[Qubit]
property angles: list[AngleVar]
property qubit_indices: list[int]
property angle_indices: list[int]
class autoqasm.program.program.ProgramConversionContext(user_config: UserConfig | None = None)[source]

Bases: object

The data structure used while converting a program. Intended for internal use.

defer_python_value(name: str, deferred: DeferredVarMixin) → None[source]

Store a deferred wrapper for potential promotion later.

Parameters:

  • name – The variable name to associate with the deferred value.

  • deferred – The deferred wrapper to store.

promote_deferred_value(name: str) → Var | None[source]

Pop a stored deferred value, promote it to an oqpy Var, and declare it at the root program scope.

Returns the promoted Var, or None if no deferred value exists for the given name.

Parameters:

name – The variable name to look up.

make_program() → Program[source]

Makes a Program object using the oqpy program from this conversion context.

Returns:

Program – The program object.

property qubits: list[int]

Return a sorted list of virtual qubits used in this program.

Returns:

list[int] – The list of virtual qubits, e.g. [0, 1, 2]

register_qubit(qubit: int) → None[source]

Register a virtual qubit that is used in this program.

get_declared_qubits() → int | None[source]

Return the number of qubits to declare in the program, as specified by the user. Returns None if the user did not specify how many qubits are in the program.

declare_global_qubit_register(size: int) → None[source]

Declare the global qubit register for the program.

Parameters:

size (int) – The size of the global qubit register to declare.

register_gate(gate_name: str, is_compiler_directive: bool = False) → None[source]

Register a gate that is used in this program.

Parameters:

  • gate_name (str) – The name of the gate being used.

  • is_compiler_directive (bool) – Whether gate_name is a compiler directive (e.g. barrier) rather than a unitary gate. Compiler directives are exempt from the verbatim-block native-gate restriction but are still validated at build time against the target device’s supportedOperations. Default is False.

Raises:

errors.UnsupportedNativeGate – If the gate is being used inside a verbatim block and the gate is not a native gate of the target device.

register_args(args: Iterable[Any]) → None[source]

Register any FreeParameters in the list of arguments.

Parameters:

args (Iterable[Any]) – Arguments passed to the main program or a subroutine.

register_input_parameter(name: str, param_type: float | bool = <class 'float'>) → None[source]

Register an input parameter if it has not already been registered.

Parameters:

  • name (str) – The name of the parameter to register with the program.

  • param_type (float | int | bool) – The type of the parameter to register with the program. Default: float.

Raises:

  • NotImplementedError – If the parameter type is not supported.

  • errors.ParameterTypeError – If name is already registered with a different type.

register_output_parameter(name: str, value: bool | float | oqpy.base.Var | oqpy.OQPyExpression | None) → None[source]

Register a new output parameter if it is not None.

Parameters:

  • name (str) – The name of the parameter to register with the program.

  • value (bool | float | Var | OQPyExpression | None) – Value to register as an output parameter.

get_input_parameter(name: str) → oqpy.Var | None[source]

Return the oqpy.Var associated with the variable name name in the program.

add_io_declarations() → None[source]

Add input and output declaration statements to the program.

get_target_device() → Device | None[source]

Return the target device for the program, as specified by the user. Returns None if the user did not specify a target device.

next_var_name(kind: type) → str[source]

Return the next name for a new classical variable.

For example, a declared bit will be named __bit_0__ and the next integer will be named __int_1__.

Parameters:

kind (type) – The type of the new variable.

Returns:

str – The name for the variable.

is_var_name_used(var_name: str) → bool[source]

Check if the variable already exists in the oqpy program.

Parameters:

var_name (str) – variable name

Returns:

bool – Return True if the variable already exists

validate_gate_targets(qubits: list[Any], angles: list[Any]) → None[source]

Validate that the specified gate targets are valid at this point in the program.

Parameters:

  • qubits (list[Any]) – The list of target qubits to validate.

  • angles (list[Any]) – The list of target angles to validate.

Raises:
get_oqpy_program(scope: ProgramScope = ProgramScope.CURRENT, mode: ProgramMode = ProgramMode.NONE) → Program[source]

Gets the oqpy.Program object associated with this program conversion context.

Parameters:

  • scope (ProgramScope) – The scope of the oqpy.Program to retrieve. Defaults to ProgramScope.CURRENT.

  • mode (ProgramMode) – The mode for which the oqpy.Program is being retrieved. Defaults to ProgramMode.NONE.

Raises:

  • errors.InvalidGateDefinition – If this function is called from within a gate

  • definition where only unitary gate operations are allowed, and the –

  • mode –

  • errors.InvalidCalibrationDefinition – If this function is called from within a

  • calibration definition where only pulse operations are allowed, and the –

  • mode –

Returns:

oqpy.Program – The requested oqpy program.

push_oqpy_program(oqpy_program: Program) → None[source]

Pushes the provided oqpy program onto the stack.

Parameters:

oqpy_program (Program) – The oqpy program to push onto the stack.

if_block(condition: Any) → _GeneratorContextManager[source]

Sets the program conversion context into an if block context.

Parameters:

condition (Any) – The condition of the if block.

Yields:

_GeneratorContextManager – The context manager of the oqpy.If block.

else_block() → _GeneratorContextManager[source]

Sets the program conversion context into an else block context. Must be immediately preceded by an if block.

Yields:

_GeneratorContextManager – The context manager of the oqpy.Else block.

for_in(iterator: Range, iterator_name: str | None) → _GeneratorContextManager[source]

Sets the program conversion context into a for loop context.

Parameters:

  • iterator (Range) – The iterator of the for loop.

  • iterator_name (str | None) – The symbol to use as the name of the iterator.

Yields:

_GeneratorContextManager – The context manager of the oqpy.ForIn block.

while_loop(condition: Any) → _GeneratorContextManager[source]

Sets the program conversion context into a while loop context.

Parameters:

condition (Any) – The condition of the while loop.

Yields:

_GeneratorContextManager – The context manager of the oqpy.While block.

gate_definition(gate_name: str, gate_args: GateArgs) → None[source]

Sets the program conversion context into a gate definition context.

Parameters:

  • gate_name (str) – The name of the gate being defined.

  • gate_args (GateArgs) – The list of arguments to the gate.

calibration_definition(gate_name: str, qubits: Iterable[int | str | Qubit | _ClassicalVar | OQPyExpression | Qubit], angles: Iterable[float]) → None[source]

Sets the program conversion context into a calibration definition context.

Parameters:

  • gate_name (str) – The name of the gate being defined.

  • qubits (Iterable[Qubit]) – The list of qubits to the gate.

  • angles (Iterable[float]) – The angles at which the gate calibration is defined.

box(pragma: str | None = None, annotations: str | Iterable[str] | None = None) → None[source]

Sets the program conversion context into a box context.

Parameters:

  • pragma (str | None) – Pragma to include before the box. Defaults to None.

  • annotations (str | Iterable[str] | None) – Annotations for the box.

autoqasm.program.program.build_program(user_config: UserConfig | None = None) → None[source]

Creates a context manager which ensures there is a valid thread-local ProgramConversionContext object. If this context manager created the ProgramConversionContext object, it removes it from thread-local storage when exiting the context manager.

For example:

with build_program() as program_conversion_context:
    h(0)
    cnot(0, 1)
program = program_conversion_context.make_program()
Parameters:

user_config (UserConfig | None) – User-supplied program building options.

autoqasm.program.program.in_active_program_conversion_context() → bool[source]

Indicates whether a program conversion context exists in the current scope, that is, whether there is an active program conversion context.

Returns:

bool – Whether there is a program currently being built.

autoqasm.program.program.get_program_conversion_context() → ProgramConversionContext[source]

Gets the current thread-local ProgramConversionContext object.

Must be called inside an active program conversion context (that is, while building a program) so that there is a valid thread-local ProgramConversionContext object.

Raises:

errors.OutsideProgramContextError – If there is no active program conversion context — typically because an AutoQASM instruction or helper was called outside a function decorated with @aq.main / @aq.subroutine / @aq.gate.

Returns:

ProgramConversionContext – The thread-local ProgramConversionContext object.