CircuitPipeline

class CircuitPipeline(stages, *, suppress_performance_warnings=False)[source]

Bases: object

Single ordered pipeline: one spec stage, then bundle stages. All stages pass keyed MetaCircuit batches.

Parameters:

  • stages (Sequence[Stage]) – Ordered sequence of stages (non-empty). Must contain exactly one SpecStage first, then zero or more BundleStages.

  • suppress_performance_warnings (bool) – When True, silence any DiviPerformanceWarning emitted by individual stages’ validate hooks during pipeline construction. Hard validation errors still raise.

Attributes Summary

stages

Read-only view of the pipeline stages.

Methods Summary

run(initial_spec, env, *[, bypass_cache, ...])

Run the pipeline: spec expand → bundle expand → (substitute params, generate QASM) → execute → reduce.

run_forward_pass(initial_spec, env, *[, ...])

Run only the forward expansion pass and return lineage metadata.

run_spec_stage(initial_spec, env)

Expand only the pipeline's spec stage.

Attributes Documentation

stages

Read-only view of the pipeline stages.

Methods Documentation

run(initial_spec, env, *, bypass_cache=False, execute_fn=<function _default_execute_fn>)[source]

Run the pipeline: spec expand → bundle expand → (substitute params, generate QASM) → execute → reduce.

  1. Run expand on the single spec stage: input any (e.g. Hamiltonian), output batch of MetaCircuits.

  2. Run expand on each bundle stage: each takes a MetaCircuit batch, modifies body/measurement, returns MetaCircuit batch.

  3. Execute: execute_fn(meta_circuit_batch, env) (or default: param substitution + backend run) → raw results.

  4. Convert raw results according to the result format recorded on the circuits.

  5. Run reduce on each stage in reverse order.

Parameters:

  • initial_spec (Any) – Input for the spec stage (typically a Hamiltonian).

  • env (PipelineEnv) – Pipeline environment (backend, reporter, etc.).

  • bypass_cache (bool) – When True, ignore any cached forward trace and recompute the full forward pass from the beginning.

  • execute_fn (Callable[[PipelineTrace, PipelineEnv], dict[Any, Any]]) – (trace, env) → raw_results. Defaults to the built-in lowering of tagged MetaCircuit body/measurement QASMs and backend execution.

Return type:

PipelineResult

Returns:

A PipelineResult dict keyed by NodeKey tuples. For single-circuit pipelines, use result.value to get the result directly.

run_forward_pass(initial_spec, env, *, bypass_cache=False, dry=False)[source]

Run only the forward expansion pass and return lineage metadata.

When dry=True, each stage is invoked via dry_expand() instead of expand(), skipping expensive per-item content generation (DAG copies, QASM rendering, classical simulations). Dry traces are never cached and never read from the cache — they carry placeholder bodies that would corrupt real runs if replayed.

If a dry-aware stage has a downstream neighbour that (a) declares consumes_dag_bodies=True and (b) has not overridden dry_expand(), the pipeline conservatively demotes the upstream stage to its real expand for this run and emits a DiviPerformanceWarning naming both stages. The circuit count stays correct; only the analytic speedup is lost for the affected stage.

Return type:

PipelineTrace

run_spec_stage(initial_spec, env)[source]

Expand only the pipeline’s spec stage.

Reuses the spec output of a forward pass already cached under the current key (e.g. the cost evaluation that precedes the metric within one optimizer step), so the metric measures on the cost’s sampled batch. With no cached trace it expands directly; deterministic per-evaluation seeding means that recompute reproduces the same batch.

Return type:

StageOutput[dict[tuple[tuple[str, Hashable], ...], MetaCircuit]]