Blackbird for Python overview

The Python Blackbird package provides a Python parser class for parsing Blackbird code, as well as a utility function for automating this procedure given a Blackbird filename.

Nomenclature

Parser

A software component that takes input data and builds a data structure. Examples include:

  • Parsing Blackbird text to form an abstract syntax tree, a graph representation of the Blackbird code. This is performed automatically by the ANTLR library.

  • Parsing the abstract syntax tree (AST) to extract useful data and build a data structure for common applications, such as a Python dictionary. To do this, we must walk through the AST via a listener or a visitor.

Listener

An ANTLR language pattern that automatically traverses the AST. By overwriting listener methods, you can store information depending on where you are in the tree.

Visitor

Similar to a listener, but more flexible. In the visitor pattern, you control the traversal of the AST, must manually visit branches. This allows the use of loops and conditionals while traversing the tree.

The Python Blackbird parser is built using the ANTLR listener pattern.

Modules

  • blackbird.program: the Blackbird program module. Contains the main Blackbird program class, used for encapsulating Blackbird programs in Python.

  • blackbird.listener: the Blackbird listener module. Contains the main Blackbird listener class, as well as a class for encapsulating classical processing of measured modes as register transforms.

  • blackbird.error: contains the error parser for returning useful syntax errors to the user.

  • blackbird.auxiliary: auxiliary parsing functions.

Serializing and deserializing Blackbird

The following functions are provided to easily

  • load(): a utility function that automates the de-serialization of the Blackbird script from a file (specified by file location), returning a BlackbirdProgram object.

  • loads(): a utility function that automates the de-serialization of the Blackbird script from a string, returning a BlackbirdProgram object.

  • dump(): a utility function that automates the serialization of a BlackbirdProgram object to a .write()-supporting file-like object.

  • dumps(): a utility function that automates the serialization of a BlackbirdProgram object to a string.

Main classes

  • BlackbirdProgram: a class that encapsulates a Blackbird program, using standard Python data structures accessible via attributes.

  • BlackbirdListener: the Python Blackbird listener, that traverses the abstract syntax tree using ANTLR4, evaluating expressions, extracting variables, and storing quantum program information.

    This class can be sub-classed, to create more advanced Blackbird listeners that perform actions (e.g., simulations) upon parsing the tree.

  • RegRefTransform: a class for representing classically processed measurement results as parameters for subsequent quantum operations.

    If the operation argument you are parsing is an instance of this class, that indicates that a register transform is required.

Note

All the above classes/functions are importable from the top-level of the Blackbird Python package:

from blackbird import BlackbirdListener, load, BlackbirdProgram

Summary

load(filename)

Deserialize a blackbird program from a file to a BlackbirdProgram object.

loads(string)

Deserialize a blackbird program from a string to a BlackbirdProgram object.

dump(blackbird, f)

Serialize a blackbird program to a .write()-supporting file-like object.

dumps(blackbird)

Serialize a blackbird program to a string.

Code details

load(filename)[source]

Deserialize a blackbird program from a file to a BlackbirdProgram object.

Parameters

filename (str) – file location of a valid Blackbird program

Returns

parsed representation of the program

Return type

BlackbirdProgram

loads(string)[source]

Deserialize a blackbird program from a string to a BlackbirdProgram object.

Parameters

string (str) – string containing a valid Blackbird program

Returns

parsed representation of the program

Return type

BlackbirdProgram

dump(blackbird, f)[source]

Serialize a blackbird program to a .write()-supporting file-like object.

Parameters
  • blackbird (BlackbirdProgram) – a BlackbirdProgram object

  • f (file-like) – a .write()-supporting file-like object.

dumps(blackbird)[source]

Serialize a blackbird program to a string.

Parameters

blackbird (BlackbirdProgram) – a BlackbirdProgram object

Returns

the serialized Blackbird program

Return type

str