qat.experimental.dialect.results.ir package

The Results dialect is used to model the collection and manipulation of results from quantum programs.

It provides types and attributes to represent result records, arrays, and collections. The dialect also defines operations for creating and transforming those structures, including post-selection and record reshaping operations needed by existing lowering and runtime paths.

This dialect is written heavily to be compatible with the legacy QAT runtime, but is expected to rapidly evolve to support more general and flexible results collection and manipulation in the future.

The dialect is centered around collections of results:

• ResultsArrayType allows us to represent a list-like collection of results, grouping them together in a single structure.

• RecordType represents the entire results of a single shot with dictionary-like semantics, allowing each piece of data to be stored by a string key.

• ResultsCollectionType allows us to represent a collection of results, enabling dynamic addition of records, such as adding results from a single shot after each shot completes.

The types are not specific to any particular result data type, and allow us to store arbitrary types of data (e.g. signals, bits, integers, IQ values). Along with operations to assemble these data structures, the dialect also provides operations to manipulate records. For example, an operation to group entries in a record into one single entry, with the original entries placed within a ResultsArrayType, and an operation to reduce records to selected data.

The operations to create data structures and add them to the collections allows us to store results from each shot as we go. This suits the representation of programs at a high level, such as the gate-level or pulse-level. However, this is not always the way results are represented closer to the hardware. For example, a particular control system might not support pulse post-processing operations, and might just return raw IQ values. Then we would need to retroactively apply the post-processing chain once the whole ensemble of results are returned. To support this, the dialect also provides operations to apply a post-processing chain to an entire collection of results. The MapOp allows us to specify a chain of operations that act on a RecordType, and produce a new RecordType. The MapOp then maps this chain of operations to every record in a ResultsCollectionType. This allows us to transform from a representation that applies post-processing to results as they’re collected, to a representation that applies them retroactively to the entire collection of results.

Additionally, the dialect provides a post-selection operation which can be parameterised with predicates to filter out results from a collection that do not satisfy the given predicates.

Mapping to post-processing in the runtime

The runtime operates on legacy instructions. The instructions within this dialect allow us to map those post-processing instructions:

• The GroupEntriesOp maps to an Assign.

• The ReduceOp maps to a Return.

class AddRecordOp(collection, record)

Bases: AddRecordOp, IRDLOperation, Operation, _IRNode, ABC, object

Adds a results record to a results collection.

The operation takes a results collection and a results record as operands, and produces a new results collection that includes the added record.

Variables:

• collection – The SSA value representing the existing results collection.

• record – The SSA value representing the results record to be added.

• result – The resulting collection type, which is a ResultsCollectionType.

Initializes the AddRecordOp with the given collection and record.

Parameters:

• collection (Union[SSAValue[ResultsCollectionType], Operation]) – The SSA value representing the existing results collection.

• record (Union[SSAValue[RecordType], Operation]) – The SSA value representing the results record to be added.

collection

Access a non-variadic construct which appears before any variadic arguments.

classmethod get_irdl_definition()

Get the IRDL operation definition.

name: ClassVar[str] = 'results.add_record'

The operation name. Should be a static member of the class

record

Access a non-variadic construct which appears before any variadic arguments.

result

Access a non-variadic construct which appears before any variadic arguments.

traits: ClassVar[OpTraits] = <xdsl.ir.core.OpTraits object>

Traits attached to an operation definition. This is a static field, and is made empty by default by PyRDL if not set by the operation definition.

verify_()

class CreateRecordOp(keys, values)

Bases: CreateRecordOp, IRDLOperation, Operation, _IRNode, ABC, object

Creates a results record, which can be added to a results collection.

The operation contains a sequence of keys and values, which are used to construct a results record. The keys must be unique, and each key must have a corresponding value.

Since a record takes dictionary semantics, the keys and values are variable-length.

Variables:

• keys – An array of string attributes representing the keys for the record.

• values – A sequence of SSA values representing the values for the record.

• result – The resulting record type, which is a RecordType.

Initializes the CreateRecordOp with the given keys and values.

Parameters:

• keys (Sequence[str]) – A sequence of strings representing the keys for the record.

• values (Sequence[SSAValue]) – A sequence of SSA values representing the values for the record.

classmethod get_irdl_definition()

Get the IRDL operation definition.

keys: ArrayAttr[StringAttr]

Accessor for an operation property.

name: ClassVar[str] = 'results.create_record'

The operation name. Should be a static member of the class

result

Access a non-variadic construct which appears before any variadic arguments.

traits: ClassVar[OpTraits] = <xdsl.ir.core.OpTraits object>

Traits attached to an operation definition. This is a static field, and is made empty by default by PyRDL if not set by the operation definition.

values

Access a variadic construct in the case where it is the only variadic.

verify_()

Verifies that the number of keys and values match.

class CreateResultsArrayOp(values)

Bases: CreateResultsArrayOp, IRDLOperation, Operation, _IRNode, ABC, object

Creates a results array, which can be added to a results collection.

The operation contains a sequence of values, which are used to construct a results array. The values can be of any type.

Variables:

• values – A sequence of SSA values representing the values for the array.

• result – The resulting array type, which is a ResultsArrayType.

Initializes the CreateResultsArrayOp with the given values.

Parameters:

values (Sequence[SSAValue]) – A sequence of SSA values representing the values for the array.

classmethod get_irdl_definition()

Get the IRDL operation definition.

name: ClassVar[str] = 'results.create_array'

The operation name. Should be a static member of the class

result

Access a non-variadic construct which appears before any variadic arguments.

traits: ClassVar[OpTraits] = <xdsl.ir.core.OpTraits object>

Traits attached to an operation definition. This is a static field, and is made empty by default by PyRDL if not set by the operation definition.

values

Access a variadic construct in the case where it is the only variadic.

verify_()

class CreateResultsCollectionOp

Bases: CreateResultsCollectionOp, IRDLOperation, Operation, _IRNode, ABC, object

Creates a results collection, which can be added to and filtered with given operations.

The operation creates an empty results collection that can be populated by later operations such as AddRecordOp.

Variables:

result – The resulting empty collection, which is a ResultsCollectionType.

Initializes the CreateResultsCollectionOp with no values, as the collection is empty upon creation.

classmethod get_irdl_definition()

Get the IRDL operation definition.

name: ClassVar[str] = 'results.create_collection'

The operation name. Should be a static member of the class

result

Access a non-variadic construct which appears before any variadic arguments.

traits: ClassVar[OpTraits] = <xdsl.ir.core.OpTraits object>

Traits attached to an operation definition. This is a static field, and is made empty by default by PyRDL if not set by the operation definition.

verify_()

class ExtractOp(record, key, result_type)

Bases: ExtractOp, IRDLOperation, Operation, _IRNode, ABC, object

Extracts an entry from a record from a string key.

As part of building the operation, the type of the extracted object must be specified.

Initializes the ExtractOp with the given record, key, and result type.

Parameters:

• record (Union[SSAValue[RecordType], Operation]) – The SSA value representing the existing results record.

• key (str) – A string representing the key to extract from the record.

• result_type (Attribute) – The type of the extracted value, for example a built-in scalar type, RecordType, or ResultsArrayType.

classmethod get_irdl_definition()

Get the IRDL operation definition.

key

Accessor for an operation property.

name: ClassVar[str] = 'results.extract'

The operation name. Should be a static member of the class

record

Access a non-variadic construct which appears before any variadic arguments.

result

Access a non-variadic construct which appears before any variadic arguments.

traits: ClassVar[OpTraits] = <xdsl.ir.core.OpTraits object>

Traits attached to an operation definition. This is a static field, and is made empty by default by PyRDL if not set by the operation definition.

verify_()

class GroupEntriesOp(collection, keys, group_key)

Bases: GroupEntriesOp, IRDLOperation, Operation, _IRNode, ABC, object

Groups entries in a record into a single entry, producing an array of those entries, ordered by the given keys, with the array stored with a provided key in the record.

This operation is roughly equivalent to the Assign instruction in legacy IR. This operation has a lowering path which could make use of ExtractOp to extract the values from the record, and then a make a new record with the grouped entries. But currently, this operation is more useful to the current runtime.

Note

This operation exists to support legacy runtime implementations of post-processing. Going forward, it is highly encouraged to assemble records in the structure that is desired to promote proper dataflow semantics.

Warning

This operation is likely to be flagged for deprecation in the future.

Initializes the GroupEntriesOp with the given collection, keys, and group key.

Parameters:

• collection (Union[SSAValue[RecordType], Operation]) – The SSA value representing the existing results record.

• keys (Sequence[str]) – A list of strings representing the keys to group in the new entry.

• group_key (str) – A string representing the key for the new grouped entry.

collection

Access a non-variadic construct which appears before any variadic arguments.

classmethod get_irdl_definition()

Get the IRDL operation definition.

group_key: StringAttr

Accessor for an operation property.

keys: ArrayAttr[StringAttr]

Accessor for an operation property.

name: ClassVar[str] = 'results.group_entries'

The operation name. Should be a static member of the class

result

Access a non-variadic construct which appears before any variadic arguments.

traits: ClassVar[OpTraits] = <xdsl.ir.core.OpTraits object>

Traits attached to an operation definition. This is a static field, and is made empty by default by PyRDL if not set by the operation definition.

verify_()

class IntegerStatePredicateAttr(key, disallowed_values)

Bases: IntegerStatePredicateAttr

Models a predicate for post selecting results based on an integer state.

This attribute is used to filter results based on a specific integer state value. It is described by a key and a list of disallowed integer values. The key refers to the entry in a record.

Variables:

• key – The key of the entry in the record that post-selection is performed on.

• disallowed_values – The list of values that are disallowed and will result in the record being post-selected out of the results collection.

Initializes the IntegerStatePredicateAttr with the given key and disallowed values.

Parameters:

• key (str | StringAttr) – The key of the entry in the record that post-selection is performed on.

• disallowed_values (Iterable[int | IntAttr] | ArrayAttr[IntAttr]) – The list of values that are disallowed and will result in the record being post-selected out of the results collection.

disallowed_values: ArrayAttr[IntAttr]

classmethod get_irdl_definition()

Get the IRDL attribute definition.

key: StringAttr

name: ClassVar[str] = 'results.integer_state_predicate'

The attribute name should be a static field in the attribute classes.

class MapOp(value, body)

Bases: MapOp, IRDLOperation, Operation, _IRNode, ABC, object

Maps a transformation over a record to a collection of records, producing a new collection of records.

The operation contains a single region, which contains the operations that transform a record into a new record. The region has a block argument of type RecordType, which represents the input record, and must yield a value of type RecordType. The operation takes a ResultsCollectionType operand, which represents the collection of records to be transformed, and produces a new ResultsCollectionType result. The implication is that the transformation is applied to each record in the collection.

The operation is modelled as pure to not allow for any side effects to be introduced within the region, and is enforced to be isolated from above to ensure that the region does not have access to any values outside of the region, which could introduce side effects.

This is intended to allow for a granular post-processing chain to be implemented that acts locally to a record. It intentionally does not specify any details of how this is implemented, e.g., in parallel or sequentially, apply every operation to each record before moving onto the next or going operation-by-operation (on every record). Those details are left to the runtime implementation, or lowering if relevant.

Within this block, you might expect to see operations such as ExtractOp to extract values from the record, and then post-processing chains (such as those defined in the pulse dialect) to transform the values, and then a CreateRecordOp to create a new record. You might also expect to see operations such as GroupEntriesOp to group entries in the record, or a ReduceOp to filter out entries.

Variables:

• value – The SSA value representing the existing results collection.

• body – The region containing the operations that transform a record into a new record.

• result – The resulting collection type, which is a ResultsCollectionType.

Initializes the MapOp with the given collection and body.

Parameters:

• value (Union[SSAValue[ResultsCollectionType], Operation]) – The SSA value representing the existing results collection.

• body (Block | Region | Sequence[Block]) – The region or block(s) containing the operations that transform a record into a new record.

body

Access a non-variadic construct which appears before any variadic arguments.

classmethod get_irdl_definition()

Get the IRDL operation definition.

name: ClassVar[str] = 'results.map'

The operation name. Should be a static member of the class

result

Access a non-variadic construct which appears before any variadic arguments.

traits: ClassVar[OpTraits] = <xdsl.ir.core.OpTraits object>

Traits attached to an operation definition. This is a static field, and is made empty by default by PyRDL if not set by the operation definition.

value

Access a non-variadic construct which appears before any variadic arguments.

verify_()

Verifies that the region begins with a block that has a single argument of type RecordType, and that the region yields a value of type RecordType.

class PostSelectOp(collection, *predicates)

Bases: PostSelectOp, IRDLOperation, Operation, _IRNode, ABC, object

Filters a results collection based on a given predicate, producing a new collection that only includes records satisfying the predicate.

The operation takes a results collection operand and a predicates property, and produces a new results collection that includes only the records that satisfy all configured predicates.

This is used to filter a results collection to records that satisfy the predicate. This is modelled around legacy runtime implementations of post-selection, which post-selects on an entire collection of records, and filters them down. Lowering paths could be implemented to allow for an on-the-fly implementation of post-selection making use of classical control flow, given hardware compatibility.

Variables:

• collection – The operand representing the existing results collection.

• predicates – The predicate attributes used to filter records in the collection.

• result – The resulting collection type, which is a ResultsCollectionType.

Initializes the PostSelectOp with the given collection and predicates.

Parameters:

• collection (Union[SSAValue[ResultsCollectionType], Operation]) – The SSA value representing the existing results collection.

• predicates (PostSelectPredicateAttr) – The array of predicate attributes to filter records.

collection

Access a non-variadic construct which appears before any variadic arguments.

classmethod get_irdl_definition()

Get the IRDL operation definition.

name: ClassVar[str] = 'results.post_select'

The operation name. Should be a static member of the class

predicates: ArrayAttr[PostSelectPredicateAttr]

Accessor for an operation property.

result

Access a non-variadic construct which appears before any variadic arguments.

traits: ClassVar[OpTraits] = <xdsl.ir.core.OpTraits object>

Traits attached to an operation definition. This is a static field, and is made empty by default by PyRDL if not set by the operation definition.

verify_()

class PostSelectPredicateAttr(*parameters)

Bases: ParametrizedAttribute, ABC

Models a predicate for post selecting results.

Eventually, this class could be extended to provide a lowering hook.

name: ClassVar[str] = 'results.post_select_predicate'

The attribute name should be a static field in the attribute classes.

class RecordType(*parameters)

Bases: RecordType

A type that carries a results record that can be added to a results collection.

This is used to represent a single record of results, e.g., from a single shot. It has the semantics of a dictionary, where the entries are accessed by string keys, and it can store arbitrary data types.

classmethod get_irdl_definition()

Get the IRDL attribute definition.

name: ClassVar[str] = 'results.record'

The attribute name should be a static field in the attribute classes.

class ReduceOp(collection, keys)

Bases: ReduceOp, IRDLOperation, Operation, _IRNode, ABC, object

Reduces a record, down to a subset of the entries in the record, producing a new record or collection of records.

We often want to gather a number of measurements to use in post-processing for use cases such as post-selection, and more general error mitigation methods. But not each of these measurements are the measurements that are requested in the original circuit. After the post-processing has completed and we have no need for these measurements, we can reduce records down to only the entries we would like to return.

This is a high-level operation that is roughly equivalent to the Return instruction in legacy IR. This has a lowering path to extract the entries from the record, and then create a new record with only the entries that are requested. But currently, this operation is more useful to the current runtime.

Note

This operation exists to support legacy runtime implementations of post-processing. Going forward, it is highly encouraged to assemble records in the structure that is desired to promote proper dataflow semantics.

Warning

This operation is likely to be flagged for deprecation in the future.

Initializes the ReduceOp with the given collection and keys.

Parameters:

• collection (Union[SSAValue[RecordType], Operation]) – The SSA value representing the existing results record.

• keys (Sequence[str]) – A list of strings representing the keys to retain in the reduced records.

collection

Access a non-variadic construct which appears before any variadic arguments.

classmethod get_irdl_definition()

Get the IRDL operation definition.

keys: ArrayAttr[StringAttr]

Accessor for an operation property.

name: ClassVar[str] = 'results.reduce'

The operation name. Should be a static member of the class

result

Access a non-variadic construct which appears before any variadic arguments.

traits: ClassVar[OpTraits] = <xdsl.ir.core.OpTraits object>

Traits attached to an operation definition. This is a static field, and is made empty by default by PyRDL if not set by the operation definition.

verify_()

class ResultsArrayType(*parameters)

Bases: ResultsArrayType

A type that represents an array of results, which can be added to and filtered with given operations.

This is used to represent a collection of results that can be indexed into, e.g., a register of classical bits measured from a quantum circuit. It takes standard array semantics, holding an ordered list of results.

ResultsArrayType is modelled to be immutable, and must be complete when constructed.

classmethod get_irdl_definition()

Get the IRDL attribute definition.

name: ClassVar[str] = 'results.array'

The attribute name should be a static field in the attribute classes.

class ResultsCollectionType(*parameters)

Bases: ResultsCollectionType

A type that represents a collection of results, which can be added to and filtered with given operations.

Each entry is expected to hold the results of a single circuit execution, such as a single shot. Results can dynamically be added to the collection, and filtered away with given operations.

classmethod get_irdl_definition()

Get the IRDL attribute definition.

name: ClassVar[str] = 'results.collection'

The attribute name should be a static field in the attribute classes.

class YieldOp(record)

Bases: YieldOp, IRDLOperation, Operation, _IRNode, ABC, object

Yields a record from a region, which can be used to produce a new collection of records.

This operation is used to yield a record from a region, which can be used to produce a new collection of records. The yielded record must be of type RecordType.

Variables:

record – The SSA value representing the record to be yielded.

Initializes the YieldOp with the given record.

Parameters:

record (Union[SSAValue[RecordType], Operation]) – The SSA value representing the record to be yielded.

classmethod get_irdl_definition()

Get the IRDL operation definition.

name: ClassVar[str] = 'results.yield'

The operation name. Should be a static member of the class

record

Access a non-variadic construct which appears before any variadic arguments.

traits: ClassVar[OpTraits] = <xdsl.ir.core.OpTraits object>

Traits attached to an operation definition. This is a static field, and is made empty by default by PyRDL if not set by the operation definition.

verify_()

Submodules

• qat.experimental.dialect.results.ir.attributes module
  • IntegerStatePredicateAttr
    • IntegerStatePredicateAttr.disallowed_values
    • IntegerStatePredicateAttr.get_irdl_definition()
    • IntegerStatePredicateAttr.key
    • IntegerStatePredicateAttr.name
  • PostSelectPredicateAttr
    • PostSelectPredicateAttr.name
• qat.experimental.dialect.results.ir.ops module
  • AddRecordOp
    • AddRecordOp.attributes
    • AddRecordOp.collection
    • AddRecordOp.get_irdl_definition()
    • AddRecordOp.location
    • AddRecordOp.name
    • AddRecordOp.properties
    • AddRecordOp.record
    • AddRecordOp.result
    • AddRecordOp.traits
    • AddRecordOp.verify_()
  • CreateRecordOp
    • CreateRecordOp.attributes
    • CreateRecordOp.get_irdl_definition()
    • CreateRecordOp.keys
    • CreateRecordOp.location
    • CreateRecordOp.name
    • CreateRecordOp.properties
    • CreateRecordOp.result
    • CreateRecordOp.traits
    • CreateRecordOp.values
    • CreateRecordOp.verify_()
  • CreateResultsArrayOp
    • CreateResultsArrayOp.attributes
    • CreateResultsArrayOp.get_irdl_definition()
    • CreateResultsArrayOp.location
    • CreateResultsArrayOp.name
    • CreateResultsArrayOp.properties
    • CreateResultsArrayOp.result
    • CreateResultsArrayOp.traits
    • CreateResultsArrayOp.values
    • CreateResultsArrayOp.verify_()
  • CreateResultsCollectionOp
    • CreateResultsCollectionOp.attributes
    • CreateResultsCollectionOp.get_irdl_definition()
    • CreateResultsCollectionOp.location
    • CreateResultsCollectionOp.name
    • CreateResultsCollectionOp.properties
    • CreateResultsCollectionOp.result
    • CreateResultsCollectionOp.traits
    • CreateResultsCollectionOp.verify_()
  • ExtractOp
    • ExtractOp.attributes
    • ExtractOp.get_irdl_definition()
    • ExtractOp.key
    • ExtractOp.location
    • ExtractOp.name
    • ExtractOp.properties
    • ExtractOp.record
    • ExtractOp.result
    • ExtractOp.traits
    • ExtractOp.verify_()
  • GroupEntriesOp
    • GroupEntriesOp.attributes
    • GroupEntriesOp.collection
    • GroupEntriesOp.get_irdl_definition()
    • GroupEntriesOp.group_key
    • GroupEntriesOp.keys
    • GroupEntriesOp.location
    • GroupEntriesOp.name
    • GroupEntriesOp.properties
    • GroupEntriesOp.result
    • GroupEntriesOp.traits
    • GroupEntriesOp.verify_()
  • MapOp
    • MapOp.attributes
    • MapOp.body
    • MapOp.get_irdl_definition()
    • MapOp.location
    • MapOp.name
    • MapOp.properties
    • MapOp.result
    • MapOp.traits
    • MapOp.value
    • MapOp.verify_()
  • PostSelectOp
    • PostSelectOp.attributes
    • PostSelectOp.collection
    • PostSelectOp.get_irdl_definition()
    • PostSelectOp.location
    • PostSelectOp.name
    • PostSelectOp.predicates
    • PostSelectOp.properties
    • PostSelectOp.result
    • PostSelectOp.traits
    • PostSelectOp.verify_()
  • ReduceOp
    • ReduceOp.attributes
    • ReduceOp.collection
    • ReduceOp.get_irdl_definition()
    • ReduceOp.keys
    • ReduceOp.location
    • ReduceOp.name
    • ReduceOp.properties
    • ReduceOp.result
    • ReduceOp.traits
    • ReduceOp.verify_()
  • YieldOp
    • YieldOp.attributes
    • YieldOp.get_irdl_definition()
    • YieldOp.location
    • YieldOp.name
    • YieldOp.properties
    • YieldOp.record
    • YieldOp.traits
    • YieldOp.verify_()
• qat.experimental.dialect.results.ir.types module
  • RecordType
    • RecordType.get_irdl_definition()
    • RecordType.name
  • ResultsArrayType
    • ResultsArrayType.get_irdl_definition()
    • ResultsArrayType.name
  • ResultsCollectionType
    • ResultsCollectionType.get_irdl_definition()
    • ResultsCollectionType.name