PipelineEnv¶

class PipelineEnv(backend, param_sets=(), feature_batch=None, labels=None, artifacts=<factory>, reporter=None, cancellation_event=None, rng=None, evaluation_counter=0, base_seed=None, shots_override=None, collect_variance=False, axes_to_preserve=())[source]¶

Bases: object

Per-run context for the circuit pipeline.

The client passes the backend and any stage-specific data when constructing the env for a pipeline run.

Attributes Summary

`artifacts`	Mutable output dict populated during execution (e.g. `circuit_count`).
`axes_to_preserve`	Stage axes that should not be reduced away.
`backend`	Backend used to run circuits (e.g. simulator or cloud service).
`base_seed`	Fixed per-program entropy for unseeded stochastic stages.
`cancellation_event`	Threading event signalling cancellation (set by ProgramEnsemble).
`collect_variance`	When `True`, measurement stages also estimate the shot-noise variance of each cost value from raw counts and write it to `artifacts['cost_variance']` (`{param_set_idx: variance}`).
`effective_shots`	The shot budget to use for this run.
`evaluation_counter`	Index of the current optimizer evaluation, bumped once per cost call.
`feature_batch`	Classical feature batch for the data axis, shape `(n_samples, n_data)`.
`labels`	Optional per-sample supervised targets, shape `(n_samples,)`, aligned with `feature_batch`.
`param_sets`	Parameter sets for binding — strictly 2D (list-of-lists or 2D ndarray).
`reporter`	Progress reporter for async polling feedback.
`rng`	Random generator for stochastic stage decisions (e.g. `weighted_random` shot allocation).
`shots_override`	Per-evaluation shot budget overriding `backend.shots` without mutating the immutable backend.

Attributes Documentation

artifacts: dict = <dataclasses._MISSING_TYPE object>¶: Mutable output dict populated during execution (e.g. circuit_count).

axes_to_preserve: tuple[str, ...] = ()¶: Stage axes that should not be reduced away. Advanced callers use this when they need branch-level results after normal downstream reductions.

backend: CircuitRunner = <dataclasses._MISSING_TYPE object>¶: Backend used to run circuits (e.g. simulator or cloud service).

base_seed: int | None = None¶: Fixed per-program entropy for unseeded stochastic stages. Combined with evaluation_counter it gives a stable-within-evaluation seed even when no explicit strategy seed is set, so the cost and metric pipelines still agree.

cancellation_event: Event | None = None¶: Threading event signalling cancellation (set by ProgramEnsemble).

collect_variance: bool = False¶: When True, measurement stages also estimate the shot-noise variance of each cost value from raw counts and write it to artifacts['cost_variance'] ({param_set_idx: variance}). Off by default — the estimate costs nothing extra in circuits but adds a small classical post-processing pass.

effective_shots¶

The shot budget to use for this run.

Returns shots_override when set, otherwise the backend’s configured shots.

evaluation_counter: int = 0¶: Index of the current optimizer evaluation, bumped once per cost call. Stochastic spec stages (e.g. QDrift) seed deterministically from it so the cost and metric pipelines sample the same batch within one evaluation.

feature_batch: ndarray[tuple[Any, ...], dtype[floating]] | None = None¶: Classical feature batch for the data axis, shape (n_samples, n_data). Read by DataBindingStage; None otherwise.

labels: ndarray[tuple[Any, ...], dtype[floating]] | None = None¶: Optional per-sample supervised targets, shape (n_samples,), aligned with feature_batch. Read by DataBindingStage.

param_sets: Sequence[Sequence[float]] | ndarray[tuple[Any, ...], dtype[floating]] = ()¶: Parameter sets for binding — strictly 2D (list-of-lists or 2D ndarray).

reporter: ProgressReporter | None = None¶: Progress reporter for async polling feedback.

rng: Generator | None = None¶: Random generator for stochastic stage decisions (e.g. weighted_random shot allocation). When None, stages that need randomness construct a fresh, unseeded generator, which means they are not reproducible.

shots_override: int | None = None¶: Per-evaluation shot budget overriding backend.shots without mutating the immutable backend. Read via effective_shots; set by callers that drive an adaptive shot count (e.g. QUIVER’s M-adaptivity). None falls back to the backend’s configured shots.