order_terms

order_terms(op, key, *, reverse=False)

Returns a copy of an operator with its terms reordered by a user-provided key.

Unlike canonical_order(), which imposes a single fixed, coefficient-independent order, this function lets you sort the terms by any criterion you like: the key function is applied to each term exactly as sorted() would, and the terms are rebuilt into a new operator of the same type in the resulting order. This is useful whenever the order of the terms matters for a downstream computation (e.g. randomized product-formula sampling), since it gives you a deterministic, reproducible order independent of how the operator happened to be assembled.

The terms themselves are left untouched – this only reorders them, it does not simplify or normal-order the operator. This works for any of the built-in operator types implementing the OperatorTrait protocol; the returned operator is of the same type as the input.

Note

The key receives each term as the same tuple that the operator’s iter_terms() yields – or, when the operator tracks groups (see groups), the longer tuple from iter_terms_with_groups(), whose trailing element is the term’s group index. The exact layout of the term itself depends on the operator type. Group indices are preserved – each term carries its group index along as it moves – and if the input tracks no groups, neither does the result.

>>> from qiskit_fermions.operators import FermionOperator
>>> from qiskit_fermions.operators.terms.ordering import order_terms
>>> op = FermionOperator.from_dict(
...     {
...         ((True, 1), (False, 0)): 1.0,  # a†_1 a_0, |coeff| = 1
...         ((True, 0), (False, 1)): 3.0,  # a†_0 a_1, |coeff| = 3
...     }
... )
>>> ordered = order_terms(op, key=lambda term: abs(term[1]), reverse=True)
>>> list(ordered.iter_terms())
[([(True, 0), (False, 1)], (3+0j)), ([(True, 1), (False, 0)], (1+0j))]
Parameters:

  • op (OperatorTrait) – the operator whose terms to reorder.

  • key (Callable[[tuple], Any]) – a function of a single term, used exactly as the key argument of sorted(). It receives each term as the tuple described in the note above.

  • reverse (bool) – if True, the terms are sorted in descending order of key.

Returns:

A new operator of the same type with its terms in the requested order.

Return type:

OperatorTrait