Qiskit / qiskit-fermions / 29924432889

98%

push

github

Parallel `InitializeModes` via an assert-only validator (#198)

* feat(linalg): add occupation_axis_mask for partial-occupation subspaces

The upcoming InitializeModes validator needs to test whether a state
vector's amplitude is confined to the subspace a (possibly partial)
occupation defines. That subspace is a set of FCI determinants sharing a
fixed occupation on some orbitals while leaving the rest free -- a whole
family, not a single address -- so the existing single-determinant
slater_determinant_statevector seed is not enough.

occupation_axis_mask returns a boolean mask over a sector's addresses,
true where the determinant has all `occupied` bits set and all `empty`
bits clear. Building it from the canonical addr2str addressing keeps the
convention identical to the matvec kernels and ffsim, rather than
reimplementing combinatorial-number-system addressing elsewhere.

Unsatisfiable or malformed constraints (out-of-range bit, an orbital
forced both occupied and empty, or a free-orbital budget too small to
reach nocc) are reported as a dedicated OccupationMaskError instead of
silently yielding an all-false mask, so a caller bug surfaces loudly.

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

* feat(pyext): expose occupation_axis_mask to Python

Wraps the new core helper so the InitializeModes validator can build its
per-axis subspace mask from the canonical Rust addressing rather than
reimplementing combinatorial-number-system ranking in numpy.

pyo3-stub-gen has no NumPyScalar impl for `bool`, so the returned bool
array's stub type is spelled out via override_return_type to match the
numpy.typing.NDArray[...] convention the sibling functions render.

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

* refactor(circuit)!: make InitializeModes an assert-only validator

InitializeModes was a state *producer*: from vec=None it built a full
(norb, nelec) determinant, and given a real vector it discarded and
reseeded. Because the appl... (continued)

134 of 148 new or added lines in 3 files covered. (90.54%)

9762 of 9993 relevant lines covered (97.69%)

329.97 hits per line