Supported passes¶

This section lists all the compiler pass types currently available within OpenQL.

Statistics cleaner¶

Type name(s): ana.statistics.Clean.

This pass just discards any statistics that previous passes might have attached to the kernel and program. It is inserted automatically after every normal pass that does not have statistics reporting enabled.

Options¶

`output_prefix`¶

Must be any string, default %N.%P. Format string for the prefix used for all output products. %n is substituted with the user-specified name of the program. %N is substituted with the optionally uniquified name of the program. %p is substituted with the local name of the pass within its group. %P is substituted with the fully-qualified name of the pass, using periods as hierarchy separators (guaranteed unique). %U is substituted with the fully-qualified name of the pass, using underscores as hierarchy separators. This may not be completely unique,%D is substituted with the fully-qualified name of the pass, using slashes as hierarchy separators. Any directories that don’t exist will be created as soon as an output file is written.

`debug`¶

Must be one of no, yes, stats, qasm, or both, default no. May be used to implicitly surround this pass with cQASM/report file output printers, to aid in debugging. Set to no to disable this functionality or to yes to write a cQASM file before and after that includes statistics as comments. The filename is built using the output_prefix option, using suffix _debug_[in|out].cq. The option values stats, cqasm, and both are used for backward compatibility with the write_qasm_files and write_report_files global options; for stats and both a statistics report file is written with suffix _[in|out].report, and for qasm and both a cQASM file is written (without stats in the comments) with suffix _[in|out].qasm.

Statistics reporter¶

Type name(s): ana.statistics.Report.

This pass reports some basic statistics of the program and each kernel to a report file. Some passes may also attach additional pass-specific statistics to the program and kernels, in which case these are printed and subsequently discarded as well.

Options¶

`output_prefix`¶

Must be any string, default %N.%P. Format string for the prefix used for all output products. %n is substituted with the user-specified name of the program. %N is substituted with the optionally uniquified name of the program. %p is substituted with the local name of the pass within its group. %P is substituted with the fully-qualified name of the pass, using periods as hierarchy separators (guaranteed unique). %U is substituted with the fully-qualified name of the pass, using underscores as hierarchy separators. This may not be completely unique,%D is substituted with the fully-qualified name of the pass, using slashes as hierarchy separators. Any directories that don’t exist will be created as soon as an output file is written.

`debug`¶

Must be one of no, yes, stats, qasm, or both, default no. May be used to implicitly surround this pass with cQASM/report file output printers, to aid in debugging. Set to no to disable this functionality or to yes to write a cQASM file before and after that includes statistics as comments. The filename is built using the output_prefix option, using suffix _debug_[in|out].cq. The option values stats, cqasm, and both are used for backward compatibility with the write_qasm_files and write_report_files global options; for stats and both a statistics report file is written with suffix _[in|out].report, and for qasm and both a cQASM file is written (without stats in the comments) with suffix _[in|out].qasm.

`output_suffix`¶

Must be any string, default .txt. Suffix to use for the output filename.

`line_prefix`¶

Must be any string, no default value. Historically, report files contain a “# ” prefix before each line. You can use this option to emulate that behavior.

Circuit visualizer¶

Type name(s): ana.visualize.Circuit.

The circuit visualizer produces an image of the circuit containing the operations on each qubit per cycle. If so configured, it can also render instrument waveforms alongside it.

Configuration file structure¶

The visualizer is configured by way of the visualizer configuration file. Each attribute has a default setting, so many can be omitted if no change is wanted.

The circuit visualizer supports the following top-level sections:

"circuit": contains options for the circuit visualization, including pulse visualization.
"saveImage": a boolean indicating whether the generated image should be saved to disk. When this is true, the file will be saved regardless of/in addition to the interactive window as controlled by the interactive option.
"backgroundColor": the background color of the generated image.

Note

A single visualizer configuration file may be used for all three visualization pass types. The configuration file format is designed to be cross-compatible.

Note

When the to-be-visualized circuit is very large, the interactive window may have trouble rendering the circuit even when zoomed in. Therefore, it is recommended to use non-interactive mode and view the generated bitmap with a more capable external viewer.

The "circuit" section has several child sections.

"cycles": contains parameters that govern cycle labels, edges, cycle compression and cutting.
"bitLines": defines the labels and lines, including grouping lines for both quantum and classical bitLines.
"grid": defines several parameters of the image grid.
"gateDurationOutlines": controls parameters for gate duration outlines.
"measurements": several parameters controlling measurement visualization.
"pulses": parameters for pulse visualization.
"instructions": a map of instruction types (the keys) with that type’s gate visualization as value, used for custom instructions.

Example configuration (self-explanatory attributes have no description):

"cycles": {
    // parameters for the labels above each cycle
    "labels": {
        "show": true,
        // whether the cycle labels should be shown in nanoseconds or
        // cycle numbers
        "inNanoSeconds": false,
        // the height of the cycle label row
        "rowHeight": 24,
        "fontHeight": 13,
        "fontColor": [0, 0, 0]
    },
    // parameters for the vertical edges between cycles
    "edges": {
        "show": true,
        "color": [0, 0, 0],
        "alpha": 0.2
    },
    // parameters for the cutting of cycles (cycles are cut when no new
    // gates are started)
    "cutting": {
        "cut": true,
        // how many cycles should be without a gate starting before the
        // cycle is cut
        "emptyCycleThreshold": 2,
        "cutCycleWidth": 16,
        // a multiplier on the width of the cut cycles
        "cutCycleWidthModifier": 0.5
    },
    // cycles are compressed by reducing each gate's duration to one cycle
    "compressCycles": false,
    // partitioning a cycle means that each gate in that cycle gets its
    // own column within the cycle; this can be done to remove visual
    // overlap
    "partitionCyclesWithOverlap": true
},
"bitLines": {
    // parameters for the labels on each quantum or classical bit line
    "labels": {
        "show": true,
        // the width of the label column
        "columnWidth": 32,
        "fontHeight": 13,
        // the colors of quantum and classical bit labels
        "qbitColor": [0, 0, 0],
        "cbitColor": [128, 128, 128]
    },
    // parameters specifically for quantum bit lines
    "quantum": {
        "color": [0, 0, 0]
    },
    // parameters specifically for classical bit lines
    "classical": {
        "show": true,
        // grouping classical bit lines collapses them into a double line
        // to reduce visual clutter
        "group": false,
        // controls the gap between the double line indicating the
        // collapsed classical lines
        "groupedLineGap": 2,
        "color": [128, 128, 128]
    },
    // parameters for the horizontal edges between bit lines
    "edges": {
        "show": false,
        "thickness": 5,
        "color": [0, 0, 0],
        "alpha": 0.4
    }
},
"grid": {
    // the size of each cell formed by a the crossing of a single bit line
    // and cycle
    "cellSize": 32,
    // the border at the edges of the generated image
    "borderSize": 32
},
"gateDurationOutlines": {
    "show": true,
    // the gap between the edge of the cell and the gate duration outline
    "gap": 2,
    // the filled background alpha
    "fillAlpha": 0.2,
    // the outline alpha
    "outlineAlpha": 0.3,
    "outlineColor": [0, 0, 0]
},
"measurements": {
    // whether to draw a connection from the measurement gate to the
    // classical line it stores the result in
    "drawConnection": true,
    // the gap between the double line representing the connection
    "lineSpacing": 2,
    "arrowSize": 10
},
"pulses": {
    // set this to true to use the pulse visualization
    "displayGatesAsPulses": false,
    // these heights control the line row heights
    "pulseRowHeightMicrowave": 32,
    "pulseRowHeightFlux": 32,
    "pulseRowHeightReadout": 32,
    // these colors control the line colors
    "pulseColorMicrowave": [0, 0, 255],
    "pulseColorFlux": [255, 0, 0],
    "pulseColorReadout": [0, 255, 0]
},
"instructions" {
    // defined below
}

Gate visualization¶

When using default gates, the visualizations for each gate are built in. However, default gates are mostly deprecated (aside from a few exceptions such as barrier), and will likely be removed in the future.

When using custom gates, the default gate visualizations are not used, so the visualization needs to be defined by the user. In the instructions section of the visualizer configuration file, each instruction “type” has its own corresponding description of gate visualization parameters. These instruction types are mapped to actual custom instructions from the hardware configuration file by adding a "visual_type" key to the instructions. For example:

{
    ...,
    "instructions" {
        ...,
        "h q1": {
            "duration": 40,
            "qubits": ["q1"],
            "visual_type": "h"
        },
        ...
    },
    ...
}

This custom Hadamard gate defined on qubit 1 has one additional attribute "visual_type" describing its visualization type. The value of this attribute links to a key in the visualizer configuration file, which has the description of the gate visualization parameters that will be used to visualize this custom instruction. Note that this allows multiple custom instructions to share the same visualization parameters, without having to duplicate the parameters.

The instructions section of the visualizer configuration file then defines how each gate type is rendered. Here’s an excerpt from an example configuration file:

{
    ...,
    "instructions": {
        ...,
        "h": {
            "connectionColor": [0, 0, 0],
            "nodes": [
                {
                    "type": "GATE",
                    "radius": 13,
                    "displayName": "H",
                    "fontHeight": 13,
                    "fontColor": [255, 255, 255],
                    "backgroundColor": [70, 210, 230],
                    "outlineColor": [70, 210, 230]
                }
            ]
        },
        ...
    },
    ...
}

Each gate has a "connectionColor" which defines the color of the connection line for multi-operand gates, and an array of "nodes". A node is the visualization of the gate acting on a specific qubit or classical bit. If a Hadamard gate is acting on qubit 3, that is represented by one node. If a CNOT gate is acting on qubits 1 and 2, it will have two nodes, one describing the visualization of the CNOT gate at qubit 1 and one describing the visualization on qubit 2. A measurement gate measuring qubit 5 and storing the result in classical bit 0 will again have two nodes.

Each node has several attributes describing its visualization.

"type": the visualization type of the node, see below for a list of the available types.
"radius": the radius of the node in pixels.
"displayName": text that will be displayed on the node (for example "H" will be displayed on the Hadamard gate in the example above).
"fontHeight": the height of the font in pixels used by the "displayName".
"fontColor": the color of the font used by the "displayName".
"backgroundColor": the background color of the node.
"outlineColor": the color of the edge-line of the node.

The colors are defined as RGB arrays: [R, G, B].

The type of the nodes can be one of the following.

"NONE": the node will not be visible.
"GATE": a square representing a gate.
"CONTROL": a small filled circle.
"NOT": a circle outline with cross inside (a CNOT cross).
"CROSS": a diagonal cross.

When a gate has multiple operands, each operand should have a node associated with it. Simply create as many nodes in the node array as there are operands and define a type and visual parameters for it. Don’t forget the comma to separate each node in the array. Note that nodes are coupled to each operand sequentially, i.e. the first node in the node array will be used for the first qubit in the operand vector.

Pulse visualization¶

Along with an abstract representation of the gates used in the quantum circuit, the gates can also be represented by the RF pulses used in the real hardware. This will be done when the "displayGatesAsPulses" flag in the "pulses" section is set to true. In this case, the waveform_mapping option must be used to specify a waveform configuration file.

Each qubit consists of three lines, the microwave, flux and readout lines, controlling single-qubit gates, two-qubit gates and readouts respectively. The waveforms used by the hardware should be stored in the waveform mapping configuration file. Then, in the hardware configuration file the "visual_codeword" and "qubits" attributes of each instruction are used as key into the table contained in the waveform mapping file to find the corresponding waveform for the specific instruction and qubit (waveforms for the same instruction can be different for different qubits). Note that a two-qubit gate has two codeword attributes, one for each qubit: "visual_right_codeword" and "visual_left_codeword".

In the waveform mapping configuration file, the waveforms are grouped by codeword first and then by addressed qubit. The waveforms themselves are stored as an array of real numbers. The scale of these numbers does not matter, the visualizer will automatically scale the pulses to fit inside the graph. The time between samples is determined by the sample rate (the sample rate can be different for each of the three lines).

TODO: the structure of the waveform mapping configuration file should still be documented. For now, use the examples in tests/visualizer as a baseline.

Options¶

`output_prefix`¶

Must be any string, default %N.%P. Format string for the prefix used for all output products. %n is substituted with the user-specified name of the program. %N is substituted with the optionally uniquified name of the program. %p is substituted with the local name of the pass within its group. %P is substituted with the fully-qualified name of the pass, using periods as hierarchy separators (guaranteed unique). %U is substituted with the fully-qualified name of the pass, using underscores as hierarchy separators. This may not be completely unique,%D is substituted with the fully-qualified name of the pass, using slashes as hierarchy separators. Any directories that don’t exist will be created as soon as an output file is written.

`debug`¶

Must be one of no, yes, stats, qasm, or both, default no. May be used to implicitly surround this pass with cQASM/report file output printers, to aid in debugging. Set to no to disable this functionality or to yes to write a cQASM file before and after that includes statistics as comments. The filename is built using the output_prefix option, using suffix _debug_[in|out].cq. The option values stats, cqasm, and both are used for backward compatibility with the write_qasm_files and write_report_files global options; for stats and both a statistics report file is written with suffix _[in|out].report, and for qasm and both a cQASM file is written (without stats in the comments) with suffix _[in|out].qasm.

`config`¶

Must be any string, default visualizer_config.json. Path to the visualizer configuration file.

`waveform_mapping`¶

Must be any string, default waveform_mapping.json. Path to the visualizer waveform mapping file.

`interactive`¶

Must be yes or no, default no. When yes, the visualizer will open a window when the pass is run. When no, an image will be saved as <output_prefix>.bmp instead.

Qubit interaction graph visualizer¶

Type name(s): ana.visualize.Interaction.

The qubit interaction graph visualizes the interactions between each of the qubits in the circuit. If a gate acts on two or more qubits, those qubits interact with each other and an edge will be drawn in the graph, with a number indicating the amount of times those qubits have interacted with each other. Note that the visualization of this is very simple, and the DOT graph the visualizer can produce should be used with the user’s favorite graphing software to create a better looking graph.

Configuration file structure¶

The visualizer is configured by way of the visualizer configuration file. Each attribute has a default setting, so many can be omitted if no change is wanted.

The circuit visualizer supports the following top-level sections:

"interactionGraph": contains options for the interaction graph.
"saveImage": a boolean indicating whether the generated image should be saved to disk. When this is true, the file will be saved regardless of/in addition to the interactive window as controlled by the interactive option.
"backgroundColor": the background color of the generated image.

Note

A single visualizer configuration file may be used for all three visualization pass types. The configuration file format is designed to be cross-compatible.

The "interactionGraph" section should have the following structure.

"interactionGraph": {
    // whether a DOT file should be generated for use with graphing
    // software
    "outputDotFile": true,
    "borderWidth": 32,
    // the minimum radius of the circle on which the qubits are placed
    "minInteractionCircleRadius": 100,
    "interactionCircleRadiusModifier": 3.0,
    "qubitRadius": 17,
    "labelFontHeight": 13,
    "circleOutlineColor": [0, 0, 0],
    "circleFillColor": [255, 255, 255],
    "labelColor": [0, 0, 0],
    "edgeColor": [0, 0, 0]
}

Options¶

`output_prefix`¶

Must be any string, default %N.%P. Format string for the prefix used for all output products. %n is substituted with the user-specified name of the program. %N is substituted with the optionally uniquified name of the program. %p is substituted with the local name of the pass within its group. %P is substituted with the fully-qualified name of the pass, using periods as hierarchy separators (guaranteed unique). %U is substituted with the fully-qualified name of the pass, using underscores as hierarchy separators. This may not be completely unique,%D is substituted with the fully-qualified name of the pass, using slashes as hierarchy separators. Any directories that don’t exist will be created as soon as an output file is written.

`debug`¶

Must be one of no, yes, stats, qasm, or both, default no. May be used to implicitly surround this pass with cQASM/report file output printers, to aid in debugging. Set to no to disable this functionality or to yes to write a cQASM file before and after that includes statistics as comments. The filename is built using the output_prefix option, using suffix _debug_[in|out].cq. The option values stats, cqasm, and both are used for backward compatibility with the write_qasm_files and write_report_files global options; for stats and both a statistics report file is written with suffix _[in|out].report, and for qasm and both a cQASM file is written (without stats in the comments) with suffix _[in|out].qasm.

`config`¶

Must be any string, default visualizer_config.json. Path to the visualizer configuration file.

`interactive`¶

Must be yes or no, default no. When yes, the visualizer will open a window when the pass is run. When no, an image will be saved as <output_prefix>.bmp instead.

Qubit mapping graph visualizer¶

Type name(s): ana.visualize.Mapping.

The mapping graph tracks the journey of the virtual qubits through the real topology of the quantum hardware as the cycles of the quantum program are executed. The virtual qubits change location whenever a swap/move gate (or their decomposed parts) is finished executing. For convenience, the abstract circuit representation of the quantum program is shown above the qubit mappings for each cycle.

The topology of the quantum hardware is taken from the topology section in the hardware configuration file, together with the edges between the qubits. If no coordinates and/or edges are defined for the qubits, the qubits will simply be spaced sequentially in a grid structure without edges being shown.

Configuration file structure¶

The visualizer is configured by way of the visualizer configuration file. Each attribute has a default setting, so many can be omitted if no change is wanted.

The circuit visualizer supports the following top-level sections:

"mappingGraph": contains options for the mapping graph.
"saveImage": a boolean indicating whether the generated image should be saved to disk. When this is true, the file will be saved regardless of/in addition to the interactive window as controlled by the interactive option.
"backgroundColor": the background color of the generated image.

Note

A single visualizer configuration file may be used for all three visualization pass types. The configuration file format is designed to be cross-compatible.

The "mappingGraph" section should have the following structure.

"mappingGraph": {
    // whether qubits should be filled with the corresponding logical
    // qubit index in the first cycle
    "initDefaultVirtuals": false,
    // give each distinct virtual qubit a color
    "showVirtualColors": true,
    // show the real qubit indices above the qubits
    "showRealIndices": true,
    // whether to use the topology from the hardware configuration file
    "useTopology": true,
    // parameters for controlling the layout
    "qubitRadius": 15,
    "qubitSpacing": 7,
    "fontHeightReal": 13,
    "fontHeightVirtual": 13,
    "textColorReal": [0, 0, 255],
    "textColorVirtual": [255, 0, 0],
    // the gap between the qubit and the real index
    "realIndexSpacing": 1,
    "qubitFillColor": [255, 255, 255],
    "qubitOutlineColor": [0, 0, 0]
}

Options¶

`output_prefix`¶

Must be any string, default %N.%P. Format string for the prefix used for all output products. %n is substituted with the user-specified name of the program. %N is substituted with the optionally uniquified name of the program. %p is substituted with the local name of the pass within its group. %P is substituted with the fully-qualified name of the pass, using periods as hierarchy separators (guaranteed unique). %U is substituted with the fully-qualified name of the pass, using underscores as hierarchy separators. This may not be completely unique,%D is substituted with the fully-qualified name of the pass, using slashes as hierarchy separators. Any directories that don’t exist will be created as soon as an output file is written.

`debug`¶

Must be one of no, yes, stats, qasm, or both, default no. May be used to implicitly surround this pass with cQASM/report file output printers, to aid in debugging. Set to no to disable this functionality or to yes to write a cQASM file before and after that includes statistics as comments. The filename is built using the output_prefix option, using suffix _debug_[in|out].cq. The option values stats, cqasm, and both are used for backward compatibility with the write_qasm_files and write_report_files global options; for stats and both a statistics report file is written with suffix _[in|out].report, and for qasm and both a cQASM file is written (without stats in the comments) with suffix _[in|out].qasm.

`config`¶

Must be any string, default visualizer_config.json. Path to the visualizer configuration file.

`interactive`¶

Must be yes or no, default no. When yes, the visualizer will open a window when the pass is run. When no, an image will be saved as <output_prefix>.bmp instead.

Central Controller code generator¶

Type name(s): arch.cc.gen.VQ1Asm.

Assembly code generator for the Q1 processor in the QuTech Central Controller, version 0.3.1

This pass actually generates three files:

<prefix>.vq1asm: the assembly code output file;
<prefix>.map: the instrument configuration file; and
<prefix>.vcd: a VCD (value change dump) file for viewing the waveforms that the program outputs.

The pass is compile-time configured with the following options:

OPT_CC_SCHEDULE_RC = 0
OPT_SUPPORT_STATIC_CODEWORDS = 1
OPT_STATIC_CODEWORDS_ARRAYS = 1
OPT_VECTOR_MODE = 0
OPT_FEEDBACK = 1
OPT_PRAGMA = 1

Options¶

`output_prefix`¶

Must be any string, default %N.%P. Format string for the prefix used for all output products. %n is substituted with the user-specified name of the program. %N is substituted with the optionally uniquified name of the program. %p is substituted with the local name of the pass within its group. %P is substituted with the fully-qualified name of the pass, using periods as hierarchy separators (guaranteed unique). %U is substituted with the fully-qualified name of the pass, using underscores as hierarchy separators. This may not be completely unique,%D is substituted with the fully-qualified name of the pass, using slashes as hierarchy separators. Any directories that don’t exist will be created as soon as an output file is written.

`debug`¶

Must be one of no, yes, stats, qasm, or both, default no. May be used to implicitly surround this pass with cQASM/report file output printers, to aid in debugging. Set to no to disable this functionality or to yes to write a cQASM file before and after that includes statistics as comments. The filename is built using the output_prefix option, using suffix _debug_[in|out].cq. The option values stats, cqasm, and both are used for backward compatibility with the write_qasm_files and write_report_files global options; for stats and both a statistics report file is written with suffix _[in|out].report, and for qasm and both a cQASM file is written (without stats in the comments) with suffix _[in|out].qasm.

`map_input_file`¶

Must be any string, no default value. Specifies the input map filename.

`verbose`¶

Must be yes or no, default yes. Selects whether verbose comments should be added to the generated .vq1asm file.

`run_once`¶

Must be yes or no, default no. When set, the emitted .vq1asm program runs once instead of repeating indefinitely.

cQASM reader¶

Type name(s): io.cqasm.Read.

This pass completely discards the incoming program and replaces it with the program described by the given cQASM file.

Because libqasm (the library used by this pass to parse cQASM files; see http://libqasm.readthedocs.io/) needs information about gate prototypes that does not currently exist in the platform configuration file, an additional configuration file is needed for this, specified using the gateset_file option. This must be a JSON file consisting of an array of objects, where each object has the following form.

{
    "name": "<name>",               # mandatory
    "params": "<typespec>",         # mandatory, refer to cqasm::types::from_spec()
    "allow_conditional": <bool>,    # whether conditional gates of this type are accepted,
                                    #   defaults to true
    "allow_parallel": <bool>,       # whether parallel gates of this type are accepted,
                                    #   defaults to true
    "allow_reused_qubits": <bool>,  # whether reused qubit args for this type are accepted,
                                    #   defaults to false
    "ql_name": "<name>",            # defaults to "name"
    "ql_qubits": [                  # list or "all", defaults to the "Q" args
        0,                          # hardcoded qubit index
        "%0"                        # reference to argument 0, which can be a qubitref, bitref,
                                    #   or int
    ],
    "ql_cregs": [                   # list or "all", defaults to the "I" args
        0,                          # hardcoded creg index
        "%0"                        # reference to argument 0, which can be an int variable
                                    #   reference, or int for creg index
    ],
    "ql_bregs": [                   # list or "all", defaults to the "B" args
        0,                          # hardcoded breg index
        "%0"                        # reference to argument 0, which can be an int variable
                                    #   reference, or int for creg index
    ],
    "ql_duration": 0,               # duration; int to hardcode or "%i" to take from param i
                                    #   (must be of type int), defaults to 0
    "ql_angle": 0.0,                # angle; float to hardcode or "%i" to take from param i
                                    #   (must be of type int or real), defaults to first arg
                                    #   of type real or 0.0
    "ql_angle_type": "<type>",      # interpretation of angle arg; one of "rad" (radians),
                                    #   "deg" (degrees), or "pow2" (2pi/2^k radians), defaults
                                    #   to "rad"
    "implicit_sgmq": <bool>,        # if multiple qubit args are present, a single-qubit gate
                                    #   of this type should be replicated for these qubits
                                    #   (instead of a single gate with many qubits)
    "implicit_breg": <bool>         # the breg operand(s) that implicitly belongs to the qubit
                                    #   operand(s) in the gate should be added to the OpenQL
                                    #   operand list
}

Options¶

`output_prefix`¶

Must be any string, default %N.%P. Format string for the prefix used for all output products. %n is substituted with the user-specified name of the program. %N is substituted with the optionally uniquified name of the program. %p is substituted with the local name of the pass within its group. %P is substituted with the fully-qualified name of the pass, using periods as hierarchy separators (guaranteed unique). %U is substituted with the fully-qualified name of the pass, using underscores as hierarchy separators. This may not be completely unique,%D is substituted with the fully-qualified name of the pass, using slashes as hierarchy separators. Any directories that don’t exist will be created as soon as an output file is written.

`debug`¶

Must be one of no, yes, stats, qasm, or both, default no. May be used to implicitly surround this pass with cQASM/report file output printers, to aid in debugging. Set to no to disable this functionality or to yes to write a cQASM file before and after that includes statistics as comments. The filename is built using the output_prefix option, using suffix _debug_[in|out].cq. The option values stats, cqasm, and both are used for backward compatibility with the write_qasm_files and write_report_files global options; for stats and both a statistics report file is written with suffix _[in|out].report, and for qasm and both a cQASM file is written (without stats in the comments) with suffix _[in|out].qasm.

`cqasm_file`¶

Must be any string, no default value. cQASM file to read. Mandatory.

`gateset_file`¶

Must be any string, no default value. JSON gateset configuration file path. Mandatory.

cQASM writer¶

Type name(s): io.cqasm.Report.

This pass writes the current program out as a cQASM file.

Options¶

`output_prefix`¶

Must be any string, default %N.%P. Format string for the prefix used for all output products. %n is substituted with the user-specified name of the program. %N is substituted with the optionally uniquified name of the program. %p is substituted with the local name of the pass within its group. %P is substituted with the fully-qualified name of the pass, using periods as hierarchy separators (guaranteed unique). %U is substituted with the fully-qualified name of the pass, using underscores as hierarchy separators. This may not be completely unique,%D is substituted with the fully-qualified name of the pass, using slashes as hierarchy separators. Any directories that don’t exist will be created as soon as an output file is written.

`debug`¶

Must be one of no, yes, stats, qasm, or both, default no. May be used to implicitly surround this pass with cQASM/report file output printers, to aid in debugging. Set to no to disable this functionality or to yes to write a cQASM file before and after that includes statistics as comments. The filename is built using the output_prefix option, using suffix _debug_[in|out].cq. The option values stats, cqasm, and both are used for backward compatibility with the write_qasm_files and write_report_files global options; for stats and both a statistics report file is written with suffix _[in|out].report, and for qasm and both a cQASM file is written (without stats in the comments) with suffix _[in|out].qasm.

`output_suffix`¶

Must be any string, default .cq. Suffix to use for the output filename.

`with_statistics`¶

Must be yes or no, default no. Whether to include the current statistics for each kernel and the complete program in the generated comments.

Sweep points writer¶

Type name(s): io.sweep_points.Write.

Writes a simple JSON file of the following form:

{ "measurement_points": [...] }

wherein the ellipsis is populated with the contents of the sweep points array specified to the program through the set_sweep_points(). API call. The filename defaults to <output_prefix>.json, but this may be overridden using the set_config_file() API call on program.

This pass has no further use and only exists for backward compatibility. It may be removed entirely in a later version of OpenQL.

Options¶

`output_prefix`¶

Must be any string, default %N.%P. Format string for the prefix used for all output products. %n is substituted with the user-specified name of the program. %N is substituted with the optionally uniquified name of the program. %p is substituted with the local name of the pass within its group. %P is substituted with the fully-qualified name of the pass, using periods as hierarchy separators (guaranteed unique). %U is substituted with the fully-qualified name of the pass, using underscores as hierarchy separators. This may not be completely unique,%D is substituted with the fully-qualified name of the pass, using slashes as hierarchy separators. Any directories that don’t exist will be created as soon as an output file is written.

`debug`¶

Must be one of no, yes, stats, qasm, or both, default no. May be used to implicitly surround this pass with cQASM/report file output printers, to aid in debugging. Set to no to disable this functionality or to yes to write a cQASM file before and after that includes statistics as comments. The filename is built using the output_prefix option, using suffix _debug_[in|out].cq. The option values stats, cqasm, and both are used for backward compatibility with the write_qasm_files and write_report_files global options; for stats and both a statistics report file is written with suffix _[in|out].report, and for qasm and both a cQASM file is written (without stats in the comments) with suffix _[in|out].qasm.

Mapper¶

Type name(s): map.qubits.Map.

The purpose of this pass is to ensure that the qubit connectivity constraints are met for all multi-qubit gates in each kernel. This is done by optionally applying a mixed integer linear programming algorithm to look for a perfect solution that does not require routing or figure out a good initial qubit placement, and then by heuristically inserting swap/move gates to change the mapping on the fly as needed. Finally, it decomposes all gates in the circuit to primitive gates.

Note

The substeps of this pass will probably be subdivided into individual passes in the future.

Warning

This pass currently operates purely on a per-kernel basis. Because it may adjust the qubit mapping from input to output, a program consisting of multiple kernels that maintains a quantum state between the kernels may be silently destroyed.

Initial placement¶

This step attempts to find a single mapping of the virtual qubits of a circuit to the real qubits of the platform’s qubit topology that minimizes the sum of the distances between the two mapped operands of all two-qubit gates in the circuit. The distance between two real qubits is the minimum number of swaps that is required to move the state of one of the two qubits to the other. It employs a Mixed Integer Linear Programming (MIP) algorithm to solve this, modelled as a Quadratic Assignment Problem. If enabled, this step may find a mapping that is optimal for the whole circuit, but because its time-complexity is exponential with respect to the size of the circuit, this may take quite some computer time. Also, the result is only really useful when in the mapping found all mapped operands of two-qubit gates are nearest-neighbor (i.e. distance 1). So, there is no guarantee for success: it may take too long and the result may not be optimal.

Note

Availability of this step depends on the build configuration of OpenQL due to license conflicts with the library used for solving the MIP problem. If it is not included, the step is effectively no-op, and a warning message will be printed.

Heuristic routing¶

This step essentially transforms the program by iterating over its gates from front to back and inserting swap or move gates when needed. Whenever it does this, it updates its internal virtual to real qubit mapping. While iterating, the virtual qubit indices of the incoming gates are replaced with real qubit indices, i.e. those defined in the topology section of the platform.

Some platforms have gates for which parameters differ based on the qubits they operate on. For example, cz q0, q1 may have a different duration than cz q2, q3, and cz q0, q2 may not even exist because of topological constraints. However, rules like this make no sense when the cz gate is still using virtual qubit indices: it’s perfectly fine for the user to do cz q0, q2 at the input if the mapper is enabled.

To account for this, the mapper will look for an alternative gate definition when it converts the virtual qubit indices to real qubit indices: specifically, it will look for a gate with _real or _prim (see also the primitive decomposition step) appended to the original gate name. For example, cz q0, q2 may, after routing, be transformed to cz_real q2, q3. This allows you to define cz using a generalized gate definition (i.e. independent on qubit operands), and cz_real as a set of specialized gates as required by the platform.

Note

The resolution order is *_prim, *_real, and finally just the original gate name. Thus, if you don’t need this functionality, you don’t need to define any *_real gates.

Because the mapper inserts swap and/or move gates, it is important that these gates are actually defined in the configuration file (usually by means of a decomposition rule). The semantics for them must be as follows.

swap x, y or swap_real x, y: must apply a complete swap gate to the given qubits to exchange their state. If in the final decomposition one of the operands is used before the other, the second operand (y) is expected to be used first for the reverse_swap_if_better option to work right.
move x, y or move_real x, y: if use_moves is enabled, the mapper will attempt to use these gates instead of swap/swap_real if it knows that the y qubit is in the |0> state (or it can initialize it as such) and the result is better (or not sufficiently worse) than using a normal swap. Such a move gate can be implemented with two CNOTs instead of three.

The order in which non-nearest-neighbor two-qubit gates are routed, the route taken for them, and where along the route the actual two-qubit gate is performed, is determined heuristically. The way in which this is done is controlled by the various options for this pass; it can be made really simple by just iterating over the circuit in the specified order and just choosing a random routing alternative whenever routing is needed, or more intelligent methods can be used at the cost of execution time and memory usage (the latter especially when a lot of alternative solutions are generated before a choice is made). Based on these options, time and space complexity can be anywhere from linear to exponential!

Decomposition into primitives¶

As a final step, the mapper will try to decompose the “real” gates (i.e. gates with qubit operands referring to real qubits) generated by the previous step into primitive gates, as actually executable by the target architecture. It does this by attempting to suffix the name of each gate with _prim. Thus, if you define a decomposition rule named cz_prim rather than cz, this rule will only be applied after mapping.

Options¶

`output_prefix`¶

Must be any string, default %N.%P. Format string for the prefix used for all output products. %n is substituted with the user-specified name of the program. %N is substituted with the optionally uniquified name of the program. %p is substituted with the local name of the pass within its group. %P is substituted with the fully-qualified name of the pass, using periods as hierarchy separators (guaranteed unique). %U is substituted with the fully-qualified name of the pass, using underscores as hierarchy separators. This may not be completely unique,%D is substituted with the fully-qualified name of the pass, using slashes as hierarchy separators. Any directories that don’t exist will be created as soon as an output file is written.

`debug`¶

Must be one of no, yes, stats, qasm, or both, default no. May be used to implicitly surround this pass with cQASM/report file output printers, to aid in debugging. Set to no to disable this functionality or to yes to write a cQASM file before and after that includes statistics as comments. The filename is built using the output_prefix option, using suffix _debug_[in|out].cq. The option values stats, cqasm, and both are used for backward compatibility with the write_qasm_files and write_report_files global options; for stats and both a statistics report file is written with suffix _[in|out].report, and for qasm and both a cQASM file is written (without stats in the comments) with suffix _[in|out].qasm.

`initialize_one_to_one`¶

Must be yes or no, default yes. Controls whether the mapper should assume that each kernel starts with a one-to-one mapping between virtual and real qubits. When disabled, the initial mapping is treated as undefined.

`assume_initialized`¶

Must be yes or no, default no. Controls whether the mapper should assume that each qubit starts out as zero at the start of each kernel, rather than with an undefined state.

`assume_prep_only_initializes`¶

Must be yes or no, default no. Controls whether the mapper may assume that a user-written prepz gate actually leaves the qubit in the zero state, rather than any other quantum state. This allows it to make some optimizations.

`enable_mip_placer`¶

Must be yes or no, default no. Controls whether the MIP-based initial placement algorithm should be run before resorting to heuristic mapping.

`mip_horizon`¶

Must be an integer less than or equal to 0, default 0. This controls how many two-qubit gates the MIP-based initial placement algorithm considers for each kernel (if enabled). If 0 or unspecified, all gates are considered.

`route_heuristic`¶

Must be one of base, baserc, minextend, minextendrc, or maxfidelity, default base. Controls which heuristic the router should use when selecting between possible routing operations. base and base_rc are the simplest forms: all routes are considered equally good, so the tie-breaking strategy is just applied immediately. minextend and minextendrc are way more involved (but also take longer to compute): these options will speculate what each option will do in terms of extending the duration of the circuit, optionally recursively, to find the best alternatives in terms of circuit duration within somelookahead window. The existence of the rc suffix specifies whether the internal scheduling for fitness determination should be done with or without resource constraints. maxfidelity is not supported in this build of OpenQL.

`tie_break_method`¶

Must be one of first, last, random, or critical, default random. Controls how to tie-break equally-scoring alternative mapping solutions. first and last choose respectively the first and last solution in the list (assuming the qubits have planar coordinates specified in the topology section, first selects the left-most alternative with the two-qubit gate near target, and last selects the right-most alternative with the two-qubit gate near source; when no coordinates are given the choice is undefined, though deterministic), random uses random number generation to select an alternative, and critical favors the alternative that maps the most critical gate as determined by the scheduler (if any).

`lookahead_mode`¶

Must be one of no, 1qfirst, noroutingfirst, or all, default noroutingfirst. Controls the strategy for selecting the next gate(s) to map. When no, just map the gates in the order of the circuit, disregarding commutation as allowed by the circuit’s dependency graph. Single-qubit and nearest-neighbor two-qubit gates are mapped trivially; non-nearest-neighbor gates are mapped when encountered by generating alternative routing solutions and picking the best one via route_heuristic. For 1qfirst, the dependency graph is used to greedily map all single-qubit gates, before proceeding with mapping the most critical two-qubit gate. If this gate is not nearest-neighbor, it is routed the same way as for no. noroutingfirst works the same, but also greedily maps two-qubit gates that don’t require any routing regardless of criticality, before routing the most critical non-nearest-neighbor two-qubit gate. Finally, all works the same as noroutingfirst, but instead of considering only routing alternatives for the most critical non-nearest-neighbor two-qubit gate, alternatives are generated for all available non-nearest-neighbor two-qubit gates, thus ignoring criticality and relying only on route_heuristic (which may be better depending on the heuristic chosen, but will cost execution time).

`path_selection_mode`¶

Must be one of all or borders, default all. Controls whether to consider all paths from a source to destination qubit while routing, or to favor routing along the route search space. The latter is only supported and sensible when the qubits are given planar coordinates in the topology section of the platform configuration file.

`swap_selection_mode`¶

Must be one of one, all, or earliest, default all. This controls how routing interacts with speculation. When all, allswaps for a particular routing option are committed immediately, before trying anything else. When one, only the first swap in the route from source to target qubit is committed. When earliest, the swap that can be done at the earliest point is selected, which might be the one swapping the source or target qubit.

`recurse_on_nn_two_qubit`¶

Must be yes or no, default no. When a nearest-neighbor two-qubit gate is the next gate to be mapped, this controls whether the mapper will speculate on adding it now or later, or if it will add it immediately without speculation. NOTE: this is an advanced/unstable option that influences lookahead_mode in a complex way; don’t use it unless you know what you’re doing. May be removed or changed in a later version of OpenQL.

`recursion_depth_limit`¶

Must be an integer less than or equal to 0 or inf, default 0. Controls the maximum recursion depth while searching for alternative mapping solutions. NOTE: this is an advanced/unstable option; don’t use it unless you know what you’re doing. May be removed or changed in a later version of OpenQL.

`recursion_width_factor`¶

Must be an real number less than or equal to 0, default 1. Limits how many alternative mapping solutions are considered as a factor of the number of best-scoring alternatives, rounded up. NOTE: this is an advanced/unstable option; don’t use it unless you know what you’re doing. May be removed or changed in a later version of OpenQL.

`recursion_width_exponent`¶

Must be an real number between 0 and 1 inclusive, default 1. Adjustment for recursion_width_factor based on the current recursion depth. For each additional level of recursion, the effective width factor is multiplied by this number. NOTE: this is an advanced/unstable option; don’t use it unless you know what you’re doing. May be removed or changed in a later version of OpenQL.

`use_moves`¶

Must be an integer less than or equal to 0 or one of no or yes, default yes. Controls if/when the mapper inserts move gates rather than swap gates to perform routing. If no, swap gates are always used. Otherwise, a move gate is used if the other qubit has been initialized, or if initializing it only extends the circuit by the given number of cycles. yes implies this limit is 0 cycles.

`reverse_swap_if_better`¶

Must be yes or no, default yes. Controls whether the mapper will reverse the operands for a swap gate when reversal improves the schedule. NOTE: this currently assumes that the second qubit operand of the swap gate decomposition in the platform configuration file is used before than the first operand; if this is not the case, enabling this will worsen the routing result rather than improve it.

`commute_multi_qubit`¶

Must be yes or no, default no. Whether to consider commutation rules for the CZ and CNOT quantum gates.

`commute_single_qubit`¶

Must be yes or no, default no. Whether to consider commutation rules for single-qubit X and Z rotations.

`write_dot_graphs`¶

Must be yes or no, default no. Whether to print dot graphs of the schedules created using the embedded scheduler.

Clifford gate optimizer¶

Type name(s): opt.clifford.Optimize.

This pass tries to minimize sequences of single-qubit gates in the Clifford C1 set to their minimal counterpart in terms of cycles. The pass returns the total number of cycles saved by this optimization per qubit.

Note that the relation between the Clifford state transition corresponding to a particular gate is currently hardcoded based on gate name, and the equivalent cycle counts are also hardcoded.

Options¶

`output_prefix`¶

Must be any string, default %N.%P. Format string for the prefix used for all output products. %n is substituted with the user-specified name of the program. %N is substituted with the optionally uniquified name of the program. %p is substituted with the local name of the pass within its group. %P is substituted with the fully-qualified name of the pass, using periods as hierarchy separators (guaranteed unique). %U is substituted with the fully-qualified name of the pass, using underscores as hierarchy separators. This may not be completely unique,%D is substituted with the fully-qualified name of the pass, using slashes as hierarchy separators. Any directories that don’t exist will be created as soon as an output file is written.

`debug`¶

Must be one of no, yes, stats, qasm, or both, default no. May be used to implicitly surround this pass with cQASM/report file output printers, to aid in debugging. Set to no to disable this functionality or to yes to write a cQASM file before and after that includes statistics as comments. The filename is built using the output_prefix option, using suffix _debug_[in|out].cq. The option values stats, cqasm, and both are used for backward compatibility with the write_qasm_files and write_report_files global options; for stats and both a statistics report file is written with suffix _[in|out].report, and for qasm and both a cQASM file is written (without stats in the comments) with suffix _[in|out].qasm.

Scheduler¶

Type name(s): sch.Schedule.

This pass analyzes the data dependencies between gates and applies cycle numbers to them based on some scheduling heuristic. Depending on options, the scheduler will either be resource-constrained or will ignore resources.

Options¶

`output_prefix`¶

Must be any string, default %N.%P. Format string for the prefix used for all output products. %n is substituted with the user-specified name of the program. %N is substituted with the optionally uniquified name of the program. %p is substituted with the local name of the pass within its group. %P is substituted with the fully-qualified name of the pass, using periods as hierarchy separators (guaranteed unique). %U is substituted with the fully-qualified name of the pass, using underscores as hierarchy separators. This may not be completely unique,%D is substituted with the fully-qualified name of the pass, using slashes as hierarchy separators. Any directories that don’t exist will be created as soon as an output file is written.

`debug`¶

Must be one of no, yes, stats, qasm, or both, default no. May be used to implicitly surround this pass with cQASM/report file output printers, to aid in debugging. Set to no to disable this functionality or to yes to write a cQASM file before and after that includes statistics as comments. The filename is built using the output_prefix option, using suffix _debug_[in|out].cq. The option values stats, cqasm, and both are used for backward compatibility with the write_qasm_files and write_report_files global options; for stats and both a statistics report file is written with suffix _[in|out].report, and for qasm and both a cQASM file is written (without stats in the comments) with suffix _[in|out].qasm.

`resource_constraints`¶

Must be yes or no, default yes. Whether to respect or ignore resource constraints when scheduling.

`scheduler_target`¶

Must be one of asap, alap, or uniform, default alap. Which scheduling target is to be used; ASAP schedules all gates as soon as possible, ALAP starts from the last gate and schedules all gates as late as possible, and uniform tries to smoothen out the amount of parallelism throughout each kernel. Uniform scheduling is only supported without resource constraints. ALAP is best for most simple quantum circuits, because the measurements at the end will be done in parallel if possible, and state initialization is postponed as much as possible to reduce state lifetime.

`commute_multi_qubit`¶

Must be yes or no, default no. Whether to consider commutation rules for the CZ and CNOT quantum gates.

`commute_single_qubit`¶

Must be yes or no, default no. Whether to consider commutation rules for single-qubit X and Z rotations.

`write_dot_graphs`¶

Must be yes or no, default no. Whether to emit a graphviz dot graph representation of the schedule of the kernel. The emitted file will use suffix _<kernel>.dot.

Supported passes¶

Statistics cleaner¶

Options¶

output_prefix¶

debug¶

Statistics reporter¶

Options¶

output_prefix¶

debug¶

output_suffix¶

line_prefix¶

Circuit visualizer¶

Configuration file structure¶

Gate visualization¶

Pulse visualization¶

Options¶

output_prefix¶

debug¶

config¶

waveform_mapping¶

interactive¶

Qubit interaction graph visualizer¶

Configuration file structure¶

Options¶

output_prefix¶

debug¶

config¶

interactive¶

Qubit mapping graph visualizer¶

Configuration file structure¶

Options¶

output_prefix¶

debug¶

config¶

interactive¶

Central Controller code generator¶

Options¶

output_prefix¶

debug¶

map_input_file¶

verbose¶

run_once¶

cQASM reader¶

Options¶

output_prefix¶

debug¶

cqasm_file¶

gateset_file¶

cQASM writer¶

Options¶

output_prefix¶

debug¶

output_suffix¶

with_statistics¶

Sweep points writer¶

Options¶

output_prefix¶

debug¶

Mapper¶

Initial placement¶

Heuristic routing¶

Decomposition into primitives¶

Options¶

output_prefix¶

debug¶

initialize_one_to_one¶

assume_initialized¶

assume_prep_only_initializes¶

enable_mip_placer¶

mip_horizon¶

route_heuristic¶

tie_break_method¶

lookahead_mode¶

path_selection_mode¶

swap_selection_mode¶

recurse_on_nn_two_qubit¶

recursion_depth_limit¶

recursion_width_factor¶

recursion_width_exponent¶

use_moves¶

`output_prefix`¶

`debug`¶

`output_prefix`¶

`debug`¶

`output_suffix`¶

`line_prefix`¶

`output_prefix`¶

`debug`¶

`config`¶

`waveform_mapping`¶

`interactive`¶

`output_prefix`¶

`debug`¶

`config`¶

`interactive`¶

`output_prefix`¶

`debug`¶

`config`¶

`interactive`¶

`output_prefix`¶

`debug`¶

`map_input_file`¶

`verbose`¶

`run_once`¶

`output_prefix`¶

`debug`¶

`cqasm_file`¶

`gateset_file`¶

`output_prefix`¶

`debug`¶

`output_suffix`¶

`with_statistics`¶

`output_prefix`¶

`debug`¶

`output_prefix`¶

`debug`¶

`initialize_one_to_one`¶

`assume_initialized`¶

`assume_prep_only_initializes`¶

`enable_mip_placer`¶

`mip_horizon`¶

`route_heuristic`¶

`tie_break_method`¶

`lookahead_mode`¶

`path_selection_mode`¶

`swap_selection_mode`¶

`recurse_on_nn_two_qubit`¶

`recursion_depth_limit`¶

`recursion_width_factor`¶

`recursion_width_exponent`¶

`use_moves`¶

`reverse_swap_if_better`¶

`commute_multi_qubit`¶

`commute_single_qubit`¶

`write_dot_graphs`¶

`output_prefix`¶

`debug`¶

`output_prefix`¶

`debug`¶

`resource_constraints`¶

`scheduler_target`¶

`commute_multi_qubit`¶

`commute_single_qubit`¶

`write_dot_graphs`¶