‘qtensor’ Dialect

The QTensor dialect for one-dimensional tensors of qubits with linear semantics.

The QTensor dialect represents one-dimensional tensors of qubits with linear ownership. Each quantum SSA value must have exactly one use. Extraction consumes a tensor and returns both the extracted qubits and the remaining tensor. Allocation and deallocation create and consume whole qubit tensors. Register slots retain their qubit identities, and quantum operands must denote disjoint resources. See the shared quantum resource contract for helper boundaries, dynamic-index preconditions, and semantic round trips.

Operations

qtensor.alloc (qtensor::AllocOp)

Tensor alloc operation

Syntax:

operation ::= `qtensor.alloc` `(`$size`)` attr-dict `:` type($result)

Allocates a one-dimensional qubit tensor with the given size and returns the allocated tensor. The qubits are initialized to the |0> state. If the size is a constant the resulting tensor has a static size, otherwise the tensor has a dynamic size.

Example:

%qtensor = qtensor.alloc(%c3) : tensor<3x!qco.qubit>

Interfaces: MemoryEffectOpInterface (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{MemoryEffects::Allocate on ::mlir::SideEffects::DefaultResource}

Operands:

Operand	Description
size	index

Results:

Result	Description
result	1D tensor of QCO qubit value type values

qtensor.dealloc (qtensor::DeallocOp)

Deallocate a tensor

Syntax:

operation ::= `qtensor.dealloc` $tensor attr-dict `:` type($tensor)

This operation deallocates the tensor and the values it holds, releasing its resources. Qubits that were extracted but not inserted again need to be deallocated separately.

Example:

qtensor.dealloc %tensor : tensor<3x!qco.qubit>

Interfaces: MemoryEffectOpInterface (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{MemoryEffects::Free on ::mlir::SideEffects::DefaultResource}

Operands:

Operand	Description
tensor	1D tensor of QCO qubit value type values

qtensor.extract (qtensor::ExtractOp)

Extract element from tensor

Syntax:

operation ::= `qtensor.extract` $tensor `[` $index `]` attr-dict `:` type($tensor)

Consume a tensor and return its qubit at the given index together with the remaining tensor. The index must be in bounds and its slot must not already be extracted. Restore the updated qubit to the same slot before passing the complete tensor through a helper or region boundary.

Example:

%outTensor, %q0 = qtensor.extract %tensor[%c0] : tensor<4x!qco.qubit>

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Operands:

Operand	Description
tensor	1D tensor of QCO qubit value type values
index	index

Results:

Result	Description
out_tensor	1D tensor of QCO qubit value type values
result	QCO qubit value type

qtensor.from_elements (qtensor::FromElementsOp)

Create a tensor from a range of values

Syntax:

operation ::= `qtensor.from_elements` $elements attr-dict `:` type($result)

The qtensor.from_elements operation is a wrapper operation of the tensor.from_elements operation. This operation creates a one-dimensional qubit tensor using the operands as its input. This also causes the input qubits to be consumed.

Example:

%tensor = qtensor.from_elements %q0, %q1, %q2 : tensor<3x!qco.qubit>

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Operands:

Operand	Description
elements	variadic of QCO qubit value type

Results:

Result	Description
result	Tensor must be statically shaped and elements must be of qubit type

qtensor.insert (qtensor::InsertOp)

Insert element into tensor

Syntax:

operation ::= `qtensor.insert` $scalar `into` $dest `[` $index `]` attr-dict `:` type($dest)

Consume an extracted qubit and the remaining tensor, restoring the qubit to its original slot. The index must be in bounds and identify that slot. Insertion preserves qubit identity; it cannot move a qubit between slots or replace another qubit. Dynamic index equality is a program precondition.

Example:

%newTensor = qtensor.insert %q0 into %tensor[%c0] : tensor<3x!qco.qubit>

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Operands:

Operand	Description
scalar	QCO qubit value type
dest	1D tensor of QCO qubit value type values
index	index

Results:

Result	Description
result	1D tensor of QCO qubit value type values

Passes

-qtensor-shrink-to-fit

Shrink static qtensors to their actually accessed indices.

Shrinks one-dimensional static qtensors by tracing linear tensor chains from qtensor.dealloc to qtensor.alloc and rebuilding the chain on a compact allocation that only keeps accessed indices.