Report SBD's trimmed determinants as SCIResult.carryover

[Jim Garrison (garrison)]

SBD selects a subset of its subspace whenever carryover_type is nonzero, returning it in
carryover_adet / carryover_bdet. This wrapper discarded that and returned the
eigenvector instead, read back from a file SBD dumps to disk.

Qiskit/qiskit-addon-sqd#369 introduces the ability for a solver to
report those determinants directly, as SCIResult.carryover, leaving SCIResult.sci_state
as None. This takes that path.

Why

The eigenvector is len(strings_a) * len(strings_b) doubles — the one quantity a large
distributed calculation cannot afford to move between processes. Writing it to disk and
reading it back is pure overhead when the caller only wants a weight-ranked determinant
selection, which is exactly what the trim SQD schedule in that PR wants and what SBD has
already computed.

Interface

report_carryover selects between the two paths:

value	behavior
None (default)	report the carryover when carryover_type is nonzero; return an eigenvector otherwise
True	report the carryover; raises ValueError if carryover_type=0, since SBD then selects nothing
False	keep the eigenvector even when SBD trims — for a caller that wants amplitudes for its own analysis

Since #28 defaults carryover_type to 0, this is opt-in: a caller sets
carryover_type to 1, 2 or 3 through sbd_config.

Revisiting a comment from #28

#28 set carryover_type = 0 with the rationale that SBD's carryover is "NOT consumed on
this path". That was true when written; with this change it describes a default rather than
the wrapper. The comment is updated accordingly. The default value is unchanged — the
reasoning behind it still holds, since most callers ignore SBD's selection and should not
pay to compute it.

Two ordering facts

#29 established that these should be stated rather than assumed:

• The carryover comes back in descending weight order. CarryOverAdet /
  CarryOverBdet (upstream chemistry/tpb/rdmat.h:102) sort by the diagonal reduced
  density matrix and keep the top entries; neither calls sort_bitarray, so the result is
  neither canonically ordered nor deduplicated. That is the order a trim wants, and the
  addon applies its own shape constraints to whatever a policy returns, so nothing here
  depends on either property.
• The eigenvector path is untouched, including Label amplitudes with the subspace that was diagonalized, not the input #29's labelling of amplitudes with the
  canonically ordered, deduplicated lists SBD was given.

The two paths therefore return differently ordered strings. The docstrings now say so.

Ranks other than the control process return a well-formed empty carryover, since the
configuration recovery loop reads results on rank 0 only.

Tests

test/test_report_carryover.py adds ten tests over the vendored h2o data. Nothing
previously exercised report_carryover, and nothing exercised the amplitude handling
either, so the suite could not tell the two paths apart — which matters because the choice
is invisible in an energy, identical either way, and shows up only as a wrong subspace one
iteration later.

• which output is returned, over the (carryover_type, report_carryover) matrix, asserting
  exactly one of sci_state / carryover is populated
• report_carryover=True with carryover_type=0 raises rather than returning empty
• the carryover holds int(ratio * len(strings)) determinants per spin sector
• the eigenvector spans the full input subspace even when carryover_type is nonzero (the
  property possible bug in returning wavefunction amplitudes #19 fixed)
• the carryover is the highest-weight determinants in descending weight order
• the energy does not depend on which output was requested

The weight-order test is the one worth reading: it compares SBD's CarryOverAdet selection
against ranking the amplitudes SBD would otherwise have returned. Two independent routes,
agreeing on the set and the order. It also asserts the result is not ascending, since
a canonically ordered list could match by coincidence.

Verified non-vacuous: with python/sbd_solver.py reverted to origin/main, all ten
fail; with the change, all ten pass.

Verification

Built against system OpenMPI 5.0.9 with a matching from-source mpi4py, cpu backend:

• pytest test/ — 12 passed, 7 skipped
• 2-rank mpirun ... pytest --only-mpi — 1 passed, 18 skipped
• the report_carryover matrix confirmed by hand before the tests were written:
  carryover_type=1 + default reports carryover=(4,4) from 40 inputs at ratio=0.1,
  while report_carryover=False returns the full (40,40) eigenvector, same energy
  (-85.29400075) in every combination

Still blocked on the pin

SCIResult.carryover is unreleased, so the qiskit-addon-sqd pin in pyproject.toml
cannot be raised yet. Testing here used an editable install of the
qiskit-addon-sqd#369 branch. This stays a draft until that lands and ships.

---

This PR was generated by Claude Opus 5 under my guidance.