Qiskit / qiskit-fermions / 28774878554

98%

push

github

docs: include identity filtering in SqDRIFT guide (#148)

* docs: include identity filtering in SqDRIFT guide

* refactor: nest operator grouping under new `terms` module

Renames the `qiskit_fermions.operators.grouping` module to
`qiskit_fermions.operators.terms.grouping` across the core, cext, and
pyext crates as well as the Python package, docs, and tests. This is a
pure rename with no behavioral changes.

The motivation is that grouping is really one instance of a broader
family of operations that partition an operator's terms based on their
structure (e.g. filtering out bitstring-invariant terms for SqDRIFT,
splitting pairing from number-conserving sectors, k-body truncation).
Rather than let the narrowly-named `grouping` module accrete unrelated
routines, the new `terms` umbrella names the concept those routines
share and gives future term-partitioning functionality a coherent home.
Doing this now is cheap because none of these modules have been released
or are considered stable yet.

This commit was assisted by Claude Opus 4.8

* feat: add `terms.filtering` module with `filter_terms_by_num_unique_modes`

Adds the `filtering` sibling to the `terms.grouping` module across the
core, cext, and pyext crates as well as the Python package, docs, and
tests. This is the first member of the broader term-partitioning family
that the recent `terms` umbrella refactor prepared for.

The new `filter_terms_by_num_unique_modes` function removes, in place,
every term acting on fewer than a given number of unique fermionic
modes. This promotes the ad-hoc identity-filtering logic previously only
documented in the SqDRIFT guide into a first-class API: filtering with a
threshold of 2 drops the constant energy offset (0 unique modes, a
global phase under time evolution) and the number operators (1 unique
mode, single-qubit Z rotations), neither of which impact the sampled
bitstrings. The SqDRIFT guide is updated to call the new functions,
including the C example that... (continued)

137 of 137 new or added lines in 7 files covered. (100.0%)

7616 of 7785 relevant lines covered (97.83%)

163.18 hits per line