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 aBlackbirdProgram
object.loads()
: a utility function that automates the de-serialization of the Blackbird script from a string, returning aBlackbirdProgram
object.dump()
: a utility function that automates the serialization of aBlackbirdProgram
object to a .write()-supporting file-like object.dumps()
: a utility function that automates the serialization of aBlackbirdProgram
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¶
|
Deserialize a blackbird program from a file to a |
|
Deserialize a blackbird program from a string to a |
|
Serialize a blackbird program to a .write()-supporting file-like object. |
|
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
- 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
- dump(blackbird, f)[source]¶
Serialize a blackbird program to a .write()-supporting file-like object.
- Parameters
blackbird (BlackbirdProgram) – a
BlackbirdProgram
objectf (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