Qiskit / qiskit-fermions / 30544761657

98%

push

github

refactor(circuit): make UCJ.__init__ take an explicit variant instead of inferring it (#236)

`nelec` was stored on `UCJ` only to infer the spin variant from its type
(int vs. tuple) and cross-check it against the tensor shapes, never read
for its actual particle-count value at construction time. This made
`__init__` inconsistent with `from_t_amplitudes`, which already takes
`variant` explicitly, and forced a shape-sniffing inference path
(`_infer_variant`) that only existed because `__init__` didn't ask for the
variant directly.

`__init__` now takes `variant` explicitly, mirroring `from_t_amplitudes`.
`nelec` is dropped from `self` entirely; it remains purely a call-time
argument to `_apply_unitary_placed_`/`_apply_unitary_`, which already
received it as a parameter.

This also drops the implicit "2-register spinless shortcut" (running
spinless-shaped tensors on a spinful sector by passing a tuple `nelec`),
which was never a deliberate feature -- just a side effect of keying off
`nelec`'s type -- and cannot be offered faithfully by a `Gate` with a
fixed `num_modes` anyway. The same physics remains fully expressible via
`Variant.BALANCED` with a zeroed alpha-beta block, which is now both
documented and covered by a dedicated equivalence test. Reworking that
test surfaced a latent test bug: `test_ucj_from_t_amplitudes_spinless_matches_ffsim`
was relying on this exact shortcut with a spinful `nelec`, so it now
exercises a genuinely spinless system instead.

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

17 of 17 new or added lines in 1 file covered. (100.0%)

10422 of 10623 relevant lines covered (98.11%)

312.37 hits per line