Qiskit / qiskit-fermions / 34488183873

98%

push

github

feat(operators): expose the FCIDump integral arrays (#341)

An FCIDump could be turned into a FermionOperator and nothing else. The
integrals it had just parsed were unreachable, and so was the constant energy,
which left the whole electronic-structure data set visible only through the
operator built from it. That is a lossy view: the operator folds the raw
integrals into terms carrying a factor of one half, and it discards the shape
they arrived in. Any workflow needing the integrals themselves (handing them to
a subspace-diagonalization post-processor, rotating them into another basis,
comparing two files) had no way to get at them short of re-reading and
re-parsing the file in Python.

The C API showed the gap most sharply: it could already consume packed
integrals through qf_ferm_op_from_2body_tril_spin, yet could not read back the
packed integrals it had itself just parsed.

The accessors mirror the existing from_*_tril_* constructors one for one, so the
read and write surfaces are exact inverses and a caller can move an FCIDump
through an operator and back without learning a second layout. That is also why
no dense variants appear here: no from_*_full_* constructor exists yet either
(both traits still carry those as TODOs), and adding a dense read side before
the write side would introduce a layout with no counterpart. Expanding these
arrays into (norb, norb) and (norb,) * 4 tensors is documented but left to the
caller, whose target library dictates the convention.

Optionality drove the shape of both bindings. The beta blocks are all or
nothing: the parser sets one flag when any index falls in the beta range, so
five arrays collapse to a single question. Python returns None per array, which
the type system already expresses. C follows the has_groups precedent instead,
pairing one is_unrestricted predicate with getters that panic when called
unguarded, rather than inventing a NULL sentinel that a caller could mistake for
an empty array. The cons... (continued)

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

12088 of 12340 relevant lines covered (97.96%)

534165.71 hits per line