qrunch.tools.minimizers.parameter_sorting_strategy.parameter_sorting_strategy_protocol

Parameter sorting strategy protocol and result container.

This module defines the public contract that all parameter sorting strategies must satisfy. A parameter sorting strategy takes

  • a quantum Circuit whose gates may contain a mix of numeric and symbolic

    parameters (currently only single-parameter SingleExcitationGate and DoubleExcitationGate are supported by the concrete strategies),

  • an initial_guess array of shape (L,) consisting of floating point

    values supplied for the last L symbolic parameters present in the circuit (“tail semantics”), and

  • a Hermitian operator (HermitianPauliSum) that can inform ordering

    heuristics (e.g. commutativity metrics),

and returns a permutation (and concomitantly permuted parameter values) of that tail subset. The output is encapsulated in ParameterSortingStrategyResult.

Tail semantics & local indices

Let S be the total number of symbolic (non-numeric) parameters encountered when iterating the circuit’s gates left-to-right. Provided 0 <= L = len(initial_guess) <= S (validated externally by decorators in the concrete implementations), only the last L symbolic parameters are in scope for the strategy. Strategies must internally re-base the indices of these L symbolic gates to a dense local range 0,1,...,L-1 regardless of their absolute (global) positions in the circuit. Consequently, the field sorted_parameter_indices in the result always contains a permutation of [0, 1, ..., L-1] (or is empty if L == 0).

Classes

ParameterSortingStrategy

Protocol defining the interface for parameter sorting strategies.

ParameterSortingStrategyResult

Container for the outcome of a parameter sorting strategy.
class ParameterSortingStrategy

Bases: Protocol

Protocol defining the interface for parameter sorting strategies.

Any implementation must produce a permutation of the tail subset (last L symbolic parameters) consistent with tail semantics and local indexing. See module docstring for full semantic description.

__init__(*args, **kwargs)
sort_parameters(initial_guess: ndarray[Any, dtype[float64]], circuit: Circuit, operator: HermitianPauliSum | None) → ParameterSortingStrategyResult

Return a reordered view of the tail subset of symbolic parameters.

Parameters:

  • initial_guess (ndarray[Any, dtype[float64]]) – 1-D array of length L with initial values for the last L symbolic parameters of circuit. May be empty (L == 0).

  • circuit (Circuit) – Quantum circuit containing a superset of symbolic and numeric gate parameters. Only single-symbolic-parameter excitation gates are supported by existing strategies.

  • operator (HermitianPauliSum | None) – Hermitian operator (observable) that a strategy may use to compute heuristics (e.g. commutativity metrics). Strategies that don’t need it (e.g. random) may ignore it but must still accept the argument.

Return type:

ParameterSortingStrategyResult

Notes

Implementations should refrain from mutating inputs and must only return local indices (0..L-1). Behavior when L == 0: both arrays in the result are empty with appropriate dtypes.

class ParameterSortingStrategyResult

Bases: object

Container for the outcome of a parameter sorting strategy.

The two fields always have matching length L (possibly 0). The sorted_parameter_indices field is guaranteed to be a permutation of [0, 1, ..., L-1] (local tail indices). Detailed per-field descriptions are documented where this result type is referenced; they are intentionally not repeated here to avoid Sphinx duplicate object warnings.

All fields are immutable (frozen=True) so an instance can be safely reused.

Parameters:

  • sorted_parameters – The L parameter values from the input

  • sorted_parameter_indices – The local indices (0..L-1) of the parameters

__init__(sorted_parameters: ndarray[Any, dtype[float64]], sorted_parameter_indices: ndarray[Any, dtype[int64]]) → None
Parameters:

  • sorted_parameters (ndarray[Any, dtype[float64]])

  • sorted_parameter_indices (ndarray[Any, dtype[int64]])

Return type:

None

sorted_parameter_indices: ndarray[Any, dtype[int64]]
sorted_parameters: ndarray[Any, dtype[float64]]