PCE

class PCE(problem, n_qubits=None, alpha=2.0, encoding_type='dense', decode_parities_fn=None, **kwargs)[source]

Bases: VQE

Generalized Pauli Correlation Encoding (PCE) VQE.

Encodes an N-variable QUBO into qubits by mapping each variable to a parity (Pauli-Z correlation) of the measured bitstring. Qubit scaling depends on encoding_type: O(log2(N)) for dense, O(sqrt(N)) for poly. The algorithm uses the measurement distribution to estimate these parities, applies a smooth relaxation when alpha is small, and evaluates the classical QUBO objective: E = x.T @ Q @ x. For larger alpha, it switches to a discrete objective (CVaR over sampled energies) for harder convergence.

Parameters:

  • problem (list | ndarray | spmatrix | BinaryQuadraticModel | Mapping[tuple[Hashable, ...], float] | BinaryPolynomial) – Binary polynomial objective to minimize. Supports QUBO and HUBO inputs.

  • n_qubits (int | None) – Optional override. Must be >= minimum for the chosen encoding (ceil(log2(N + 1)) for dense; solve n(n+1)/2 >= N for poly). Larger values raise a warning for both encodings.

  • alpha (float) – Scaling factor for the tanh() activation. Higher = harder binary constraints, Lower = smoother gradient.

  • encoding_type (Literal['dense', 'poly']) – “dense” (logarithmic qubits, default) or “poly” (each variable maps to parity of 1 or 2 qubits).

  • decode_parities_fn (Callable[[list[str], ndarray[tuple[Any, ...], dtype[uint]]], ndarray[tuple[Any, ...], dtype[ubyte]]] | None) – Optional custom decoder for mapping encoded bitstrings to parity arrays. Signature: (state_strings, variable_masks_u64) -> parities. Defaults to the built-in parity decoder.

  • **kwargs – Additional arguments passed to VQE (e.g. ansatz, backend).

Attributes Summary

solution

Return the most-probable decoded assignment from the final measurement.

Methods Summary

get_top_solutions([n, min_prob, ...])

Get the top-N solutions with decoded QUBO variable assignments.

sample_solution([params])

Compute the final eigenstate and decode it into a PCE vector.

Attributes Documentation

solution

Return the most-probable decoded assignment from the final measurement.

Note

This returns the assignment corresponding to the highest-probability encoded bitstring, which may not be the lowest-energy solution. For energy-ranked solutions, use get_top_solutions(sort_by="energy") instead.

Returns:

For QUBO problems, a binary 0/1 NumPy array. For HUBO problems with non-integer variable names, a dictionary mapping variable names to binary values.

Raises:

RuntimeError – If run() has not been called yet.

Methods Documentation

get_top_solutions(n=10, *, min_prob=0.0, include_decoded=False, sort_by='prob')[source]

Get the top-N solutions with decoded QUBO variable assignments.

This method overrides the base implementation to decode encoded qubit states into actual QUBO variable assignments. The bitstrings in the probability distribution represent encoded qubit states (O(log2(N)) qubits), not the decoded QUBO solutions (N variables).

Parameters:

  • n (int) – Maximum number of solutions to return. Must be non-negative. If n is 0 or negative, returns an empty list. If n exceeds the number of available solutions (after filtering), returns all available solutions. Defaults to 10.

  • min_prob (float) – Minimum probability threshold for including solutions. Only solutions with probability >= min_prob will be included. Must be in range [0.0, 1.0]. Defaults to 0.0 (no filtering).

  • include_decoded (bool) – Whether to populate the decoded field of each SolutionEntry with the numpy array representation of the QUBO solution. If False, the decoded field will be None. Defaults to False.

  • sort_by (Literal['prob', 'energy']) – Sort order for the returned solutions. "prob" (default): descending by probability. "energy": ascending by objective energy. When set, the energy field of each SolutionEntry is populated.

Returns:

List of solution entries sorted according to

sort_by, with decoded bitstring for deterministic tie-breaking. The bitstring field contains the decoded QUBO solution as a binary string (e.g., “01011” for 5 variables), not the encoded qubit state. Returns an empty list if no probability distribution is available or n <= 0.

Return type:

list[SolutionEntry]

Raises:

  • RuntimeError – If probability distribution is not available because optimization has not been run or final computation was not performed.

  • ValueError – If min_prob is not in range [0.0, 1.0], n is negative, or sort_by is not one of "prob" or "energy".

sample_solution(params=None, **kwargs)[source]

Compute the final eigenstate and decode it into a PCE vector.

Return type:

PCE