Pipeline

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

Core

Functions

cost_preprocessor()	Measure the seed's cost observable as expectation values (identity transform).
dry_run_pipeline(name, trace, stages, env)	Analyze a pipeline trace and compute per-stage factor.
extract_param_set_idx(key[, default])	Extract the param_set index from a pipeline result KEY.
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.
group_by_base_key(results, axis_name, *[, ...])	Group child results by base key (label with axis stripped).
reduce_mean(grouped)	Reduce grouped values by averaging (e.g. Trotter ham samples).
reduce_merge_histograms(grouped)	Reduce grouped probability dicts by averaging across groups.
reduce_postprocess_ordered(grouped, ...)	Reduce grouped index->value dicts by sorting by index and calling a postprocess function.
sample_preprocessor()	Sample the prepared state in the computational basis (clears the observable).
strip_axis_from_label(child_label, axis_name)	Remove the (axis_name, value) pair from a child label to get the base key.

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.
CircuitPreprocessor(name[, preprocess, ...])	A named seed transform and the readout it targets.
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.
StageOutput(batch[, token])	Complete, cacheable output of one stage expansion.
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)	Bind a classical feature batch into a parametric circuit.
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).
PreprocessStage(preprocessor)	Apply a CircuitPreprocessor's transform to the post-spec batch.
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