PCECostStage

class PCECostStage(*, problem, alpha, use_soft_objective, decode_parities_fn, variable_masks_u64, alpha_cvar=0.25)

Bases: BundleStage

Pipeline stage that emits a single Z-basis measurement and computes nonlinear binary-polynomial energy from shot histograms.

PCE only needs raw bitstring counts (not expectation values), so this stage bypasses MeasurementStage’s observable grouping entirely. Expand generates a single “measure all qubits” QASM per circuit spec, and reduce applies the soft tanh or hard CVaR energy formula.

Parameters:

• problem (BinaryPolynomialProblem) – Canonical binary polynomial problem used for objective evaluation.

• alpha (float) – Scaling factor for the tanh activation.

• use_soft_objective (bool) – If True, compute relaxed (soft) energy; otherwise compute hard CVaR energy.

• decode_parities_fn (Callable) – Function mapping (state_strings, masks) → parities.

• variable_masks_u64 (ndarray[tuple[Any, ...], dtype[uint]]) – Precomputed uint64 masks for each QUBO variable.

• alpha_cvar (float) – CVaR tail fraction (only used when use_soft_objective is False).

Attributes Summary

axis_name	Axis name introduced by this stage.
consumes_dag_bodies	Whether this stage reads meta.circuit_bodies during expand.
handles_measurement	Whether this stage sets up measurement circuits and result format.

Methods Summary

expand(batch, env)	Emit a single Z-basis measurement circuit per circuit spec.
reduce(results, env, token)	Compute polynomial energy from shot histograms.

Attributes Documentation

axis_name

consumes_dag_bodies

handles_measurement

Methods Documentation

expand(batch, env)

Emit a single Z-basis measurement circuit per circuit spec.

Generates “measure all qubits” QASM and sets the result format to COUNTS so raw shot histograms reach reduce.

Return type:

tuple[ExpansionResult, Any]

reduce(results, env, token)

Compute polynomial energy from shot histograms.

Each param set has a single histogram (no observable-group merging needed). Applies the soft tanh or hard CVaR energy formula.

Return type:

dict[Any, Any]