Qiskit / qiskit-fermions / 29497777470

98%

push

github

Term ordering (#183)

* feat: add generic term iteration and construction to OperatorTrait

Promote the term-iteration and term-construction surface onto the
`OperatorTrait` protocol so that generic, operator-agnostic term
transforms can be written once against the trait rather than per
operator. For every operator the trait now exposes:

  - `iter` / `iter_with_groups` — borrowed views over the stored terms
    (`iter_with_groups` moves here from an inherent method, unchanged; it
    still panics when `groups` is `None`, documented as a precondition)
  - `from_terms` / `from_terms_with_groups` — their inverses, rebuilding
    an owned operator from an iterator of (group) term views

The view types are named as generic associated types bounded only by
`PartialEq`, so the trait declaration and every impl spell the `iter`
item type identically (`Self::TermView<'_>`) and no impl refines the
signature — the `refining_impl_trait` lint stays quiet without any
`#[allow]`. Implementers must keep spelling the associated type.

The pyext `from_terms*` classmethods, which previously hand-rolled the
CSR field-pushing, now share the core `_append_term` primitive (promoted
to `pub`) so the sparse boundary bookkeeping lives in one place per
operator. They intentionally do not route through the core `from_terms*`:
those borrow term views tied to a single lifetime, whereas Python hands
over owned tuples, so delegating would force materializing every term
up front (a full extra copy). Appending directly keeps construction
streaming.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

* feat: add a canonical term-ordering module

`operators::terms::ordering::canonical::canonical_order` sorts an
operator's terms into a canonical, coefficient-independent order and
rebuilds it via `OperatorTrait::from_terms`.

The ordering key is a new `TermSortKey` trait implemented on each
`*TermView`, and `OperatorTrait::TermView` is bounded by it so the sort
is generic over every... (continued)

447 of 476 new or added lines in 8 files covered. (93.91%)

8010 of 8196 relevant lines covered (97.73%)

155.69 hits per line