Pipeline

The divi.pipeline module provides the circuit pipeline engine that orchestrates circuit generation, transformation, execution, and result reduction.

Core

Functions

dry_run_pipeline(name, trace, stages, env)	Analyze a pipeline trace and compute per-stage factor.
format_dry_run(reports)	Print dry-run reports as rich trees with stage metadata.
format_pipeline_tree(trace)	Print the full pipeline expansion tree to the terminal.
reduce_merge_histograms(grouped)	Reduce grouped probability dicts by averaging across groups.

Classes

BundleStage(name)	Abstract stage that transforms a keyed MetaCircuit batch.
CircuitPipeline(stages, *[, ...])	Single ordered pipeline: one spec stage, then bundle stages.
ContractViolation	Raised when a stage's positional requirements are not met.
DiviPerformanceWarning	Emitted when a pipeline configuration is known to be slow.
DryRunReport(pipeline_name, stages, ...[, ...])	Complete dry-run report for a single pipeline.
ExpansionResult(batch[, stage_name])	Bundle-stage expansion output.
PipelineEnv(backend[, param_sets, ...])	Per-run context for the circuit pipeline.
PipelineResult	Pipeline result dict with convenience access for single-result pipelines.
PipelineTrace(initial_batch, final_batch, ...)	Forward-pass pipeline trace for fan-out verification before execution.
SpecStage(name)	First stage in every pipeline: converts an arbitrary spec into a keyed MetaCircuit batch.
Stage(name)	Abstract base for pipeline stages.
StageInfo(name, axis, factor, metadata)	Per-stage dry-run report.
ResultFormat()	Canonical format that raw backend results should be converted into.

Variables

GroupingStrategy
ShotDistStrategy
NodeKey	Built-in immutable sequence.

Built-in Stages

Functions

resolve_loss_reduction(reduction)	Resolve a LossReductionFn literal/callable to a concrete callable.
resolve_sample_loss(loss)	Resolve a SampleLossFn literal/callable to a concrete callable.

Classes

CircuitSpecStage()	SpecStage that wraps one or more pre-built MetaCircuits into a batch.
DataBindingStage(data_params, loss_reduction)	Fan a parametric circuit out over a classical feature batch.
MeasurementStage([grouping_strategy, ...])	Unified measurement stage for all circuit measurement types.
ParameterBindingStage()	Bind env.param_sets into every circuit body.
PauliTwirlStage([n_twirls, seed])	Fan out each DAG body into Pauli-twirled copies and average on reduce.
PCECostStage(*, problem, alpha, ...[, ...])	Pipeline stage that emits a single Z-basis measurement and computes nonlinear binary-polynomial energy from shot histograms.
PennyLaneSpecStage()	SpecStage that converts PennyLane circuits into MetaCircuit(s).
QEMStage([protocol])	BundleStage that applies a QEM protocol to each circuit body.
QiskitSpecStage()	SpecStage that converts Qiskit QuantumCircuit(s) into MetaCircuit(s).
TrotterSpecStage(trotterization_strategy, ...)	SpecStage that turns a Hamiltonian into a batch of MetaCircuits via a TrotterizationStrategy.

Variables

LossReductionFn
SampleLossFn