Blackbird Program class

Module name: blackbird.program

This module contains a Python class representing a Blackbird program using standard Python data types.

The functions load(), and loads() will read Blackbird scripts and return an instance of the BlackbirdProgram class.


list_to_blackbird(A, var_name) Converts a Python nested list to a Blackbird script array type.
RegRefTransform(expr) Class to represent a classical register transform.
BlackbirdProgram([name, version]) Python representation of a Blackbird program.

Code details

list_to_blackbird(A, var_name)[source]

Converts a Python nested list to a Blackbird script array type.

  • A (list[list]) – 2-dimensional nested list
  • var_name (str) – the array variable name

list containing each line representing the

Blackbird array variable declaration

Return type:


class RegRefTransform(expr)[source]

Class to represent a classical register transform.

Parameters:expr (sympy.Expr) – a SymPy expression representing the RegRef transform

After initialization, the RegRefTransform has three attributes which may be inspected to translate the Blackbird program to a simulator or quantum hardware:

func = None

Scalar function that takes one or more values corresponding to measurement results, and outputs a single numeric value.

regrefs = None

List of integers corresponding to the modes that are measured and act as inputs to func. Note that the order of this list corresponds to the order that the measured mode results should be passed to the function.

func_str = None

String representation of the RegRefTransform function.


Print formatting


Print formatting


list of weak references to the object (if defined)

class BlackbirdProgram(name='blackbird_program', version='1.0')[source]

Python representation of a Blackbird program.

__init__(name='blackbird_program', version='1.0')[source]

Initialize self. See help(type(self)) for accurate signature.


Name of the Blackbird program

Return type:str

Version of the Blackbird parser the program targets

Returns:version number
Return type:str

A set of non-negative integers specifying the mode numbers the program manipulates.

Returns:mode numbers
Return type:set[int]

Contains information regarding the target device of the quantum program (i.e., the target device the Blackbird script is compiled for).

Important keys include:

  • 'name' (Union[str, None]): the name of the device the Blackbird script requests to be
    run on. If no target is requested, the returned value will be None.
  • 'options' (dict): a dictionary of keyword arguments for the target device
Returns:target information
Return type:dict[str->[str, dict]]

List of operations to apply to the device, in temporal order.

Each operation is contained as a dictionary, with the following keys:

  • 'op' (str): the name of the operation
  • 'args' (list): a list of positional arguments for the operation
  • 'kwargs' (dict): a dictionary of keyword arguments for the operation
  • 'modes' (list[int]): modes the operation applies to

Note that, depending on the operation, both 'args' and 'kwargs' might be empty.

Returns:operation information
Return type:list[dict]

List of free parameters the Blackbird script depends on.

Returns:list of free parameter names
Return type:List[str]

Returns True if there is at least one free parameter.

Returns:True if a template
Return type:bool

Create a new Blackbird program, with all free parameters initialized to their passed values.

Return type:Program

list of weak references to the object (if defined)


The length of the quantum program (i.e., the number of operations applied).

Returns:program length
Return type:int

Serializes the blackbird program, returning a valid Blackbird script as a string.

Returns:the blackbird script representing the BlackbirdProgram object
Return type:str