Qiskit / qiskit-fermions / 39740542700

98%

push

github

Add a ternary-tree fermion-to-qubit mapping framework (#362)

* refactor(mappers): extract the shared QkObs plumbing from Jordan-Wigner

The four Jordan-Wigner mappers are built from a generic core (a parallel
accumulator with a memory bound, a term-image composer, and a one-string
observable builder) none of which knows anything about Jordan-Wigner. The
ternary-tree mappers landing next differ from them only in the Pauli image they
assign to a single generator, so that core has to be reachable from more than
one module.

Move it to `mappers::qk_obs`: `Wrapper` and its compaction rule,
`map_operator`, `compose_actions`, `one_pauli_string`, `qk_coeff` and `compact`.
The relocated code is unchanged apart from visibility, the bit-term alias names
and a few comments, so the accumulator's tuning (whose constants were arrived at
empirically in #297) carries over exactly rather than being re-derived. The
aliases are re-exported from `qk_obs` so that it is the only place spelling the
two FFI backends' differing names for them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(mappers): add ternary trees and their compiled encodings

A ternary tree on N nodes defines a fermion-to-qubit encoding of N modes onto N
qubits, and every encoding this crate cares about is one particular tree:
Jordan-Wigner is a chain, the balanced tree of Jiang et al. attains the optimal
Pauli weight ceil(log3(2N+1)), and the Bonsai algorithm grows one to fit a
device's coupling graph. Making the tree a first-class structure is what lets a
single mapper implementation cover all of them.

The construction follows the Bonsai paper, in which a node's three downward
links each either descend to a child or terminate in a *leg*. That choice is
what makes the framework general: a node with fewer children does not produce
fewer Pauli strings, it produces more legs, so the count is exactly 2N+1
whatever the shape. Irregular, connectivity-derived trees then need no special
handli... (continued)

1965 of 1981 new or added lines in 13 files covered. (99.19%)

13951 of 14205 relevant lines covered (98.21%)

460128.92 hits per line