Qiskit / qiskit-fermions / 34373221764

98%

Build Type

push

github

Committed by web-flow

Commit Message

feat(operators): order terms by group and exploit the resulting layout (#338)

Group indices are a per-term tag that says nothing about where those terms sit,
so a group's terms are in general scattered throughout an operator. The grouping
this repository ships makes that concrete: group_terms_by_electronic_structure
assigns indices in order of first encounter, which leaves a group's second term
arbitrarily far from its first. Nothing could exploit a grouping's locality
because no operation produced any.

group_order sorts the terms by group index alone, making each group one
contiguous run. The sort is stable, so terms keep their relative order within a
group: ordering canonically first and by group second refines the canonical
order rather than replacing it with an arbitrary permutation. An operator
tracking no groups has nothing to order by and comes back as an unchanged copy,
which keeps the function composable rather than forcing a guard at every step of
a pipeline.

That layout alone changes nothing, which is the point of the second half of this
commit: split_out_groups staged the requested groups in a HashMap and then
walked every term testing each against it, so a lookup cost the same whether one
group was requested or forty. It now binary-searches the group boundaries when
the group indices are sorted, making a lookup scale with the groups requested
rather than the terms held. Measured on an N2 Hamiltonian of 251,468 terms in
75,616 groups, a release-mode lookup drops from ~1.9 ms to ~0.02 ms.

Sortedness is detected per call rather than tracked on the operator. A cached
flag would be tractable now that #337 funnelled the whole-array writes through
one gate, but it would not help the callers that motivate this: the incremental
builders in library must keep writing the field directly, and neither FCIDump nor
group_terms_by_electronic_structure produces sorted indices, so the flag would
read "unknown" for exactly the operators being optimized. ... (continued)

Coverage Stats

263 of 283 new or added lines in 9 files covered. (92.93%)

51 existing lines in 3 files now uncovered.

11722 of 11974 relevant lines covered (97.9%)

550487.55 hits per line