Blackbird for C++ overview

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

Main components

  • Visitor: the Blackbird visitor, which parses the abstract syntax tree using ANTLR4, evaluating expressions, extracting variables, and storing quantum program information.

    While derived classes can be defined in order to modify the actions performed while parsing the tree, in general this is not needed. In most cases, it is sufficient to simply iterate through the returned information contained in the Program class.

  • parse_blackbird(): a utility function that automates the parsing of the Blackbird abstract syntax tree. Use this function to parse arbitrary Blackbird code, and return the Program class.

Source code overview

The Blackbird C++ library source code, contained in the folder blackbird_cpp, contains the following files:

  • Blackbird.h: the public Blackbird library header. Contains the Visitor declarations, as well as the utility function parse_blackbird(), which automates the process of parsing a Blackbird script given a file stream, and return the Blackbird program.

  • Visitor.cpp: contains the source code for the Visitor. The Visitor is a derived class of blackbirdBaseVisitor, and provides ANTLR4 with actions to perform (e.g., evaluating expressions, storing variables, queuing quantum operations) as the abstract syntax tree is traversed.

    If a new quantum operation or quantum device needs to be added, its initialization will need to be defined here in the corresponding node of the AST.

  • BlackbirdProgram.h: contains the declarations for Program, Operation, and all derived classes.

    • Known devices and gates are recorded in the enum’s blackbird::Device and blackbird::Gate. These have the same value as their Blackbird command name.
    • Each gate and measurement class is declared, including constructors, number of modes, number of parameters, and input/mode validation.
    • Each device class is declared, including constructors, the member function print_device_info, and any required member variables, for instance \(\hbar\) or cutoff dimension, if applicable.

    If a new quantum operation or quantum device needs to be added, its class declaration will need to be made here.

  • BlackbirdVariables.h: contains templates for setting and getting assigned Blackbird variables from a std::unordered_map, with their name (std::string) as the key. Also includes some basic automatic casting operations, and casting exceptions.

  • Autogenerated ANTLR4 headers and source.

    • blackbirdBaseVisitor.cpp
    • blackbirdBaseVisitor.h
    • blackbirdLexer.cpp
    • blackbirdLexer.h
    • blackbirdParser.cpp
    • blackbirdParser.h

    Warning

    These are generated automatically by compiling the ANTLR4 grammar src/blackbird.g4 (see Compiling the grammar), and should not be modified in any case. If they are modified, your changes will be overwritten once the grammar is re-compiled!