qp.workflow.get_compile_pipeline

get_compile_pipeline(qnode, level='user')[source]

Extract CompilePipeline(s) from a qjit()’d QNode.

Note

The device preprocessing passes are represented by a single Device Preprocessing placeholder, since the device applies its own transforms when the QNode is executed. The placeholder cannot be applied to a QNode.

Parameters:
  • qnode (QJIT) – The qjit’d QNode to get the compile pipeline for.

  • level (str | int | slice | Sequence[str | int]) –

    The portion(s) of the CompilePipeline to retrieve. Defaults to "user".

    level accepts the following types:

    • str: One of the presets listed below, or the label of a marker(). A marker label includes all transforms up to the location of that marker.

    • int: The number of transforms to include from the start of the pipeline. Must be non-negative, e.g. level=0 is empty and level=2 contains the first two transforms ([0] and [1]). The device preprocessing passes are denoted by a single level, placed after all user-applied transforms.

    • slice: A range of transforms, using standard Python slicing with non-negative int bounds and a positive step, e.g. level=slice(1, 3) contains transforms [1] and [2]. A slice without a stop, such as slice(1, None), includes device preprocessing passes. To exclude them, give an explicit stop, e.g. slice(1, 2) for a pipeline with two user-applied transforms. A step greater than 1 skips transforms, and emits a warning, as does a slice that selects no transforms.

    • Sequence: A non-empty list, tuple, or similar containing int or str values. One compile pipeline is returned per level, in ascending order. If the levels are not in ascending order, or contain duplicates, they are sorted and deduplicated, with a warning. The "all" and "all-user" presets are not allowed inside a Sequence, since they already correspond to multiple levels.

    The markers placed at the start or the end of the selected transforms are kept, except with a slice with a step greater than 1, which drops all markers.

    The following str presets are provided for ease of use:

    • "top": Equivalent to 0; an empty pipeline, before any transforms are applied.

    • "user": Only the transforms manually applied by the user.

    • "device": The user-applied transforms followed by the device preprocessing, i.e. the full pipeline as prepared for device execution.

    • "all-user": One pipeline for each stage of compilation with respect to the user-applied transforms, from "top" up to "user".

    • "all": One pipeline for each stage of compilation with respect to the user-applied transforms and the device preprocessing, from "top" up to "device".

Returns:

The CompilePipeline at the requested level. If level is a Sequence, "all-user", or "all", a list containing one CompilePipeline per level is returned instead.

Return type:

CompilePipeline | list[CompilePipeline]

Example:

from pennylane.workflow import get_compile_pipeline

dev = qp.device("null.qubit", wires=1)

@qp.qjit(capture=True)
@qp.transforms.merge_rotations
@qp.marker("checkpoint")
@qp.transforms.cancel_inverses
@qp.qnode(dev)
def circuit(angle):
    qp.RX(angle, wires=0)
    qp.H(0)
    qp.H(0)
    qp.RX(angle, wires=0)
    return qp.expval(qp.Z(0))

By default, the transforms manually applied by the user are retrieved:

>>> print(get_compile_pipeline(circuit)) # or level="user"
CompilePipeline(
  [0] cancel_inverses(),
   ├─▶ checkpoint
  [1] merge_rotations()
)

To get the full compile pipeline used during execution on the device, specify level="device". The device preprocessing is appended after the user-applied transforms, and counts as a single level, matching the "Device Preprocessing" level reported by analyze():

>>> print(get_compile_pipeline(circuit, level="device"))
CompilePipeline(
  [0] cancel_inverses(),
   ├─▶ checkpoint
  [1] merge_rotations(),
  [2] Device Preprocessing
)

We can also retrieve the compile pipeline up to a specific stage indicated by the name given to a marker(), which in our example is the "checkpoint" marker:

>>> print(get_compile_pipeline(circuit, level="checkpoint"))
CompilePipeline(
  [0] cancel_inverses()
   └─▶ checkpoint
)

If level is "top" or 0, an empty compile pipeline is returned:

>>> print(get_compile_pipeline(circuit, level=0))
CompilePipeline()
>>> print(get_compile_pipeline(circuit, level="top"))
CompilePipeline()

The level can also be an integer, corresponding to the number of transforms to retrieve from the compile pipeline:

>>> print(get_compile_pipeline(circuit, level=1))
CompilePipeline(
  [0] cancel_inverses()
   └─▶ checkpoint
)

A slice extracts a specific range of transforms from the compile pipeline. For example, we can retrieve only the second transform with:

>>> print(get_compile_pipeline(circuit, level=slice(1, 2)))
CompilePipeline(
   ├─▶ checkpoint
  [0] merge_rotations()
)

Note that the "checkpoint" marker is still in the pipeline, as it marks a location in the pipeline rather than being attached to a particular transform.

To retrieve several compile pipelines at once, provide a Sequence of levels. Unlike a slice, which returns a single range of transforms, one compile pipeline is returned per entry, each containing all transforms up to that level:

>>> for pipeline in get_compile_pipeline(circuit, level=[1, 2]):
...     print(pipeline)
CompilePipeline(
  [0] cancel_inverses()
   └─▶ checkpoint
)
CompilePipeline(
  [0] cancel_inverses(),
   ├─▶ checkpoint
  [1] merge_rotations()
)

The "all-user" and "all" presets return the compile pipeline at every stage of compilation:

>>> len(get_compile_pipeline(circuit, level="all-user"))
3
>>> len(get_compile_pipeline(circuit, level="all"))
4