Qiskit / qiskit-fermions / 34232181495

98%

push

github

feat(operators)!: add group analysis helpers to the grouping module (#332)

Group indices deliberately carry no intrinsic meaning: the array records
which terms belong together, never why. Downstream consumers nonetheless
assume properties of a grouping, and those assumptions were neither
documented nor checkable. The qDRIFT pass, for instance, samples whole
groups weighted by the mean coefficient magnitude, which is the right
scale only when each group is one atomic, Hermitian piece.

Add two read-only checks so that such an assumption can be verified up
front instead of being paid for on every transpiler call:

- groups_are_hermitian, the convention that makes fermionic randomized
  product formulas possible at all (a lone a†_p a_q is not Hermitian, so
  its evolution is not unitary and it cannot be sampled on its own)
- groups_have_uniform_coeffs, the assumption group_coeff_means makes

They are independent: neither implies the other. Uniform coefficients do
not make a group Hermitian, and a Hermitian group can mix magnitudes, so
both are documented with what they do and do not prove.

A third property, one group index per term, is enforced rather than
checked. The setter is the only public route by which a mismatched array
can enter an operator (every other operation either clears the group
indices or keeps them in sync, and the constructors derive them), so
validating there makes the corrupt state unreachable instead of leaving a
helper the caller must remember to call. Too few indices silently dropped
the trailing terms wherever terms are iterated with their groups; too
many made num_groups report groups that no term carried.

Rather than growing the operator API by one method per future analysis,
these live in the grouping module, whose scope widens from assigning
group indices to assigning and analysing them. group_weights moves there
too, renamed group_coeff_means: it was never an accessor for stored data
but a reduction computed for one down... (continued)

303 of 339 new or added lines in 13 files covered. (89.38%)

11442 of 11647 relevant lines covered (98.24%)

565940.67 hits per line