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