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, *[, ...])

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.

Attributes Documentation

stages

Read-only view of the pipeline stages.

Methods Documentation

run(initial_spec, env, *, force_forward_sweep=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 env.result_format (set by the measurement stage).

  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.).

  • force_forward_sweep (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, *, force_forward_sweep=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