samplomatic.quantum_program

Quantum Programs.

Overview

A QuantumProgram is an ordered collection of items, where each item pairs a single circuit with the parameter data used to bind it. The program bundles these items together with shared settings such as the number of shots, the classical-register measurement level, and optional noise maps, so that a whole family of related circuits can be described as one object.

Every item is a QuantumProgramItem, which comes in two flavors depending on how the circuit’s parameters are supplied:

  • A CircuitItem holds a circuit together with an explicit array of circuit_arguments. This is the natural choice when the parameter values are already known, for instance a parameter sweep laid out on a grid.

  • A SamplexItem holds a circuit together with a Samplex that generates the circuit’s parameters. This is the natural choice for randomized circuits, such as Pauli twirling, where the concrete parameter values are drawn on demand rather than fixed in advance.

Shapes and broadcasting

Each item has a shape, obtained by broadcasting the extrinsic shapes of its inputs. Input arrays split their axes into extrinsic axes (leftmost, defining the sweep grid) and intrinsic axes (rightmost, fixed by the data type). For example, circuit_arguments for a circuit with n parameters has intrinsic shape (n,), so an array of shape (5, 3, n) has extrinsic shape (5, 3). For a SamplexItem, the shape argument can enlarge the extrinsic grid beyond what the samplex arguments imply, with the extra axes enumerating independent randomizations.

Results

The QuantumProgramResult class collects the results associated with a program. This class mirrors the program’s structure: it holds one QuantumProgramItemResult per program item, in the same order. Each item result behaves like a mapping from output names to arrays, and carries per-item metadata alongside the shared, program-level metadata stored on the QuantumProgramResult.

Classes

ChunkPart(idx_item, size)

A description of the contents of a single part of an execution chunk.

ChunkSpan(start, stop, parts)

Timing information about a single chunk of execution.

ChunkTiming(spans)

A collection of chunk timing information for a QuantumProgramResult.

CircuitItem(circuit, *[, circuit_arguments, ...])

An item of a QuantumProgram containing a circuit and its arguments.

QuantumProgram(shots[, items, noise_maps, ...])

A quantum runtime executable.

QuantumProgramItem(circuit[, chunk_size])

An item of a QuantumProgram.

QuantumProgramItemResult(result)

A container to store results for a single item of a QuantumProgram.

QuantumProgramResult(data[, passthrough_data])

A container to store results from executing a QuantumProgram.

SamplexItem(circuit, samplex, *[, ...])

An item of a QuantumProgram containing a circuit and samplex to feed it arguments.