sbd-eigensolver 1.7.0__tar.gz → 1.7.1__tar.gz

{sbd_eigensolver-1.7.0/sbd_eigensolver.egg-info → sbd_eigensolver-1.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sbd-eigensolver
-Version: 1.7.0
+Version: 1.7.1
 Summary: Python bindings for Selected Basis Diagonalization (SBD) library
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://github.com/Qiskit/sbd-eigensolver-python
@@ -272,6 +272,7 @@ config = sbd.TPB_SBD()
 | `adet_comm_size` | 1 | Alpha determinant communicator size |
 | `bdet_comm_size` | 1 | Beta determinant communicator size |
 | `task_comm_size` | 1 | Task communicator size |
+| `dump_matrix_form_wf` | `""` | Path to write the amplitudes to — see [Getting the TPB amplitudes](#getting-the-tpb-amplitudes) for the file format |
 
 Total MPI ranks = `task_comm_size × adet_comm_size × bdet_comm_size`.
 
@@ -315,6 +316,39 @@ results = sbd.tpb_diag(fcidump, adet, bdet, sbd_data,
 
 **Returns:** `dict` with keys `energy`, `density`, `carryover_adet`, `carryover_bdet`, `one_p_rdm`, `two_p_rdm`.
 
+#### Getting the TPB amplitudes
+
+Neither return dict holds the wavefunction amplitudes. Two separate mechanisms write them, in **different formats**, and the one named in the function signature is not the one most callers want:
+
+| | `sbd_data.dump_matrix_form_wf` | `savename` argument |
+|---|---|---|
+| Writes | the full `len(adet) × len(bdet)` subspace, gathered onto one rank | one file per b_comm position, each holding **only that rank's block** |
+| Path | exactly what you set | `f"{savename}{rank_b:06d}.bin"` |
+| Header | **none** | three `size_t` (`adet_range`, `bdet_range`, `det_length`), then that block's alpha and beta determinant words |
+| Payload | `float64`, row-major over α×β | `adet_range × bdet_range` `float64` |
+| Intended for | analysis | checkpoint/restart, paired with `loadname` |
+
+So the whole-subspace read is just:
+
+```python
+config.dump_matrix_form_wf = "wf.bin"
+results = sbd.tpb_diag(fcidump, adet, bdet, config)
+
+amplitudes = np.fromfile("wf.bin").reshape(len(adet), len(bdet))
+```
+
+Naming that file `.dat` or `.txt` instead writes a text table labelling every amplitude with its own alpha and beta bitstring — the easiest form to inspect by hand, and it sidesteps having to reconstruct the ordering yourself:
+
+```
+<amplitude> # <alpha index>: <alpha bitstring> <beta index>: <beta bitstring>
+```
+
+Be aware that this text form is written with the stream's default formatting, so amplitudes land with only ~6 significant digits; use the binary form when you need full `float64` precision.
+
+Rows and columns follow `adet`/`bdet` as the diagonalizer saw them. `sort_bitarray` removes duplicates as well as sorting, so pass lists already in that form if you intend to label the axes yourself — `from_strings` documents the word packing.
+
+This is the mechanism [`sbd_solver.py`](python/sbd_solver.py) uses to populate `SCIState.amplitudes` — though it skips the write entirely when SBD is picking the carryover itself (`carryover_type` 1, against a qiskit-addon-sqd that accepts it), since then the next subspace comes back in `carryover_adet`/`carryover_bdet` and the amplitudes never need to reach Python.
+
 ```python
 # GDB: over an explicit list of full determinants rather than a product space
 results = sbd.gdb_diag(fcidump, det, sbd_data,

{sbd_eigensolver-1.7.0 → sbd_eigensolver-1.7.1}/README.md

@@ -224,6 +224,7 @@ config = sbd.TPB_SBD()
 | `adet_comm_size` | 1 | Alpha determinant communicator size |
 | `bdet_comm_size` | 1 | Beta determinant communicator size |
 | `task_comm_size` | 1 | Task communicator size |
+| `dump_matrix_form_wf` | `""` | Path to write the amplitudes to — see [Getting the TPB amplitudes](#getting-the-tpb-amplitudes) for the file format |
 
 Total MPI ranks = `task_comm_size × adet_comm_size × bdet_comm_size`.
 
@@ -267,6 +268,39 @@ results = sbd.tpb_diag(fcidump, adet, bdet, sbd_data,
 
 **Returns:** `dict` with keys `energy`, `density`, `carryover_adet`, `carryover_bdet`, `one_p_rdm`, `two_p_rdm`.
 
+#### Getting the TPB amplitudes
+
+Neither return dict holds the wavefunction amplitudes. Two separate mechanisms write them, in **different formats**, and the one named in the function signature is not the one most callers want:
+
+| | `sbd_data.dump_matrix_form_wf` | `savename` argument |
+|---|---|---|
+| Writes | the full `len(adet) × len(bdet)` subspace, gathered onto one rank | one file per b_comm position, each holding **only that rank's block** |
+| Path | exactly what you set | `f"{savename}{rank_b:06d}.bin"` |
+| Header | **none** | three `size_t` (`adet_range`, `bdet_range`, `det_length`), then that block's alpha and beta determinant words |
+| Payload | `float64`, row-major over α×β | `adet_range × bdet_range` `float64` |
+| Intended for | analysis | checkpoint/restart, paired with `loadname` |
+
+So the whole-subspace read is just:
+
+```python
+config.dump_matrix_form_wf = "wf.bin"
+results = sbd.tpb_diag(fcidump, adet, bdet, config)
+
+amplitudes = np.fromfile("wf.bin").reshape(len(adet), len(bdet))
+```
+
+Naming that file `.dat` or `.txt` instead writes a text table labelling every amplitude with its own alpha and beta bitstring — the easiest form to inspect by hand, and it sidesteps having to reconstruct the ordering yourself:
+
+```
+<amplitude> # <alpha index>: <alpha bitstring> <beta index>: <beta bitstring>
+```
+
+Be aware that this text form is written with the stream's default formatting, so amplitudes land with only ~6 significant digits; use the binary form when you need full `float64` precision.
+
+Rows and columns follow `adet`/`bdet` as the diagonalizer saw them. `sort_bitarray` removes duplicates as well as sorting, so pass lists already in that form if you intend to label the axes yourself — `from_strings` documents the word packing.
+
+This is the mechanism [`sbd_solver.py`](python/sbd_solver.py) uses to populate `SCIState.amplitudes` — though it skips the write entirely when SBD is picking the carryover itself (`carryover_type` 1, against a qiskit-addon-sqd that accepts it), since then the next subspace comes back in `carryover_adet`/`carryover_bdet` and the amplitudes never need to reach Python.
+
 ```python
 # GDB: over an explicit list of full determinants rather than a product space
 results = sbd.gdb_diag(fcidump, det, sbd_data,

{sbd_eigensolver-1.7.0 → sbd_eigensolver-1.7.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sbd-eigensolver"
-version = "1.7.0"
+version = "1.7.1"
 description = "Python bindings for Selected Basis Diagonalization (SBD) library"
 readme = "README.md"
 requires-python = ">=3.10"

{sbd_eigensolver-1.7.0 → sbd_eigensolver-1.7.1}/python/__init__.py

@@ -318,8 +318,9 @@ def init(device='cpu', comm_backend='mpi'):
     first use with ``device='cpu'`` and ``comm_backend='mpi'``.  Call it
     explicitly only when you need GPU or want to control startup timing.
 
-    The device can be overridden per-call via the ``device`` parameter on
-    ``tpb_diag()``, ``tpb_diag_from_files()``, and ``get_backend()``.
+    The device can be overridden per call via the ``device`` parameter of
+    ``tpb_diag()``, ``tpb_diag_from_files()``, ``gdb_diag()`` and
+    ``get_backend()``.
 
     Args:
         device: Default compute device — 'cpu', 'gpu', 'gpu-omp', or 'auto'.
@@ -413,11 +414,20 @@ def get_backend(device=None):
     Get the backend module for the given device.
 
     Auto-initializes SBD if needed. Passing ``device`` overrides the
-    default — this is how you switch between CPU and GPU within the
-    same process.
+    default, which is how you switch backends within one process. The one
+    combination to avoid is the CPU backend together with the OpenMP-offload
+    one ('gpu-omp'): they share an OpenMP runtime, and loading both leaves
+    offload regions running on the host. ``sbd.has_backend_conflict()``
+    reports it.
 
     Args:
-        device: 'cpu', 'gpu', 'auto', or None (use default).
+        device: 'cpu', 'gpu' (Thrust), 'gpu-omp' (OpenMP offload), 'auto', an
+            alias accepted by :func:`init`, or None. None means the device set
+            by :func:`init`. If nothing has initialized yet it means 'auto',
+            which prefers Thrust, then OpenMP offload, then CPU, whereas the
+            first call of :func:`tpb_diag` or :func:`gdb_diag` initializes with
+            'cpu'. Call :func:`init` with the device you want to avoid
+            depending on call order.
 
     Returns:
         The pybind11 backend module (_core_cpu, _core_gpu_thrust, or
@@ -496,13 +506,19 @@ def barrier():
 # ---------------------------------------------------------------------------
 
 def TPB_SBD(device=None):
-    """Create TPB_SBD configuration object."""
+    """Create a TPB_SBD configuration object, for :func:`tpb_diag`.
+
+    Its fields are listed in the tables below.
+    """
     _ensure_initialized()
     return get_backend(device).TPB_SBD()
 
 
 def GDB_SBD(device=None):
-    """Create GDB_SBD configuration object."""
+    """Create a GDB_SBD configuration object, for :func:`gdb_diag`.
+
+    Its fields are listed in the tables below.
+    """
     _ensure_initialized()
     return get_backend(device).GDB_SBD()
 
@@ -514,25 +530,65 @@ def FCIDump(device=None):
 
 
 def LoadFCIDump(filename, device=None):
-    """Load FCIDUMP file."""
+    """Load an FCIDUMP file.
+
+    Args:
+        filename: Path to the FCIDUMP file.
+        device: Backend whose ``FCIDump`` type to build; None uses the default.
+
+    Returns:
+        The ``FCIDump`` object that :func:`tpb_diag` and :func:`gdb_diag` take.
+    """
     _ensure_initialized()
     return get_backend(device).LoadFCIDump(filename)
 
 
 def LoadAlphaDets(filename, bit_length, total_bit_length, device=None):
-    """Load alpha determinants from file."""
+    """Load determinants from a file of bitstrings, one per line.
+
+    Each line is packed as :func:`from_strings` does. Upstream sorts the
+    determinants and removes duplicates, so the result is ready to use as a
+    TPB determinant list and may hold fewer determinants than the file has
+    lines.
+
+    The format is chosen by extension: ``.txt`` for one bitstring per line,
+    ``.bin`` for upstream's binary format. Any other extension returns an
+    empty list without an error.
+
+    Args:
+        filename: Path to the file.
+        bit_length: Bits per packed word. Must match the config's
+            ``bit_length``.
+        total_bit_length: Length of each bitstring, ``norb`` for the alpha or
+            beta strings of TPB.
+        device: Backend to use; None uses the default.
+
+    Returns:
+        A list of packed determinants, each a list of words, sorted and
+        distinct.
+    """
     _ensure_initialized()
     return get_backend(device).LoadAlphaDets(filename, bit_length, total_bit_length)
 
 
 def makestring(config, bit_length, total_bit_length, device=None):
-    """Convert determinant to string representation."""
+    """Render a packed determinant as a ``total_bit_length``-character string.
+
+    The inverse of :func:`from_string`, and subject to the same right-to-left
+    word packing, which :func:`from_strings` describes.
+    """
     _ensure_initialized()
     return get_backend(device).makestring(config, bit_length, total_bit_length)
 
 
 def from_string(s, bit_length, total_bit_length, device=None):
-    """Convert binary string to determinant format."""
+    """Convert a binary string to SBD's packed determinant format.
+
+    Returns a list of ``size_t`` words, e.g. ``from_string("0011", 20, 4)`` is
+    ``[3]``. :func:`makestring` is the inverse. See :func:`from_strings`, the
+    bulk form, for the word-packing convention and for why it is worth
+    preferring that form outside of one-off calls.
+    """
     _ensure_initialized()
     return get_backend(device).from_string(s, bit_length, total_bit_length)
 
@@ -540,10 +596,29 @@ def from_string(s, bit_length, total_bit_length, device=None):
 def from_strings(strings, bit_length, total_bit_length, device=None):
     """Pack many bitstrings into one ``(n, words)`` array.
 
-    The bulk form of :func:`from_string`, looping in C++ instead of once per
+    The bulk form of ``sbd.from_string``, looping in C++ instead of once per
     determinant across the Python boundary. Prefer it for anything larger than a
     handful: the per-call form costs tens of thousands of round trips on the
     vendored inputs alone.
+
+    Each row holds ``total_bit_length`` bits packed ``bit_length`` to a word, so
+    a bitstring longer than ``bit_length`` occupies more than one word. The
+    packing runs from the **right end** of the string: its trailing
+    ``bit_length`` characters become word 0, the next ``bit_length`` to the left
+    become word 1, and so on, so the leading characters of a multi-word string
+    land in the *last* word rather than the first::
+
+        from_strings(["0011"], 20, 4)           # -> array([[3]], dtype=uint64)
+        from_strings(["1" + "0" * 69], 62, 70)  # -> array([[  0, 128]], ...)
+        from_strings(["0" * 69 + "1"], 62, 70)  # -> array([[1, 0]], ...)
+
+    Within a word the rightmost character is the least significant bit, which is
+    why ``"0011"`` packs to ``3`` rather than ``12``. Getting this backwards
+    produces a valid-looking but wrong subspace rather than an error, so check
+    round trips with ``sbd.makestring`` when building determinants by hand.
+
+    ``bit_length`` must match the ``bit_length`` of the config passed to the
+    diagonalizers, since it sets how many words each determinant occupies.
     """
     _ensure_initialized()
     return get_backend(device).from_strings(list(strings), bit_length, total_bit_length)
@@ -575,17 +650,27 @@ def tpb_diag_from_files(fcidumpfile, adetfile, sbd_data,
     """
     Perform TPB diagonalization from files.
 
+    The one determinant file supplies both the alpha and the beta list, so the
+    subspace is the product of that list with itself. For different alpha and
+    beta lists, as an open-shell case needs, load them and call :func:`tpb_diag`.
+
     Args:
         fcidumpfile: Path to FCIDUMP file.
-        adetfile: Path to alpha determinants file.
+        adetfile: Path to the determinant file, used for both alpha and beta.
         sbd_data: TPB_SBD configuration object.
-        loadname: Path to load initial wavefunction (optional).
-        savename: Path to save final wavefunction (optional).
-        device: Override device ('cpu', 'gpu', or None for default).
+        loadname: Path prefix to load an initial wavefunction from (optional).
+        savename: Path prefix to save the final wavefunction to (optional).
+        device: Backend to run on: 'cpu', 'gpu' (Thrust), 'gpu-omp' (OpenMP
+            offload), or an alias accepted by :func:`init`. None uses the
+            default; see :func:`get_backend`.
 
     Returns:
         dict with keys: energy, density, carryover_adet, carryover_bdet,
         one_p_rdm, two_p_rdm.
+
+    Note:
+        As with :func:`tpb_diag`, no amplitudes are returned in the dict; see
+        that function for the two ways of writing them to disk.
     """
     _ensure_initialized()
     backend = get_backend(device)
@@ -604,13 +689,54 @@ def tpb_diag(fcidump, adet, bdet, sbd_data,
         adet: Alpha determinants.
         bdet: Beta determinants.
         sbd_data: TPB_SBD configuration object.
-        loadname: Path to load initial wavefunction (optional).
-        savename: Path to save final wavefunction (optional).
-        device: Override device ('cpu', 'gpu', or None for default).
+        loadname: Path prefix to load an initial wavefunction from (optional).
+        savename: Path prefix to save the final wavefunction to (optional). See
+            the note below: for reading amplitudes back,
+            ``sbd_data.dump_matrix_form_wf`` is usually the one you want.
+        device: Backend to run on: 'cpu', 'gpu' (Thrust), 'gpu-omp' (OpenMP
+            offload), or an alias accepted by :func:`init`. None uses the
+            default; see :func:`get_backend`.
 
     Returns:
         dict with keys: energy, density, carryover_adet, carryover_bdet,
         one_p_rdm, two_p_rdm.
+
+    Note:
+        The returned dict holds no wavefunction amplitudes. There are two ways
+        to get them, and they write *different* formats -- do not mix them up:
+
+        ``sbd_data.dump_matrix_form_wf = "wf.bin"`` writes the full
+        ``len(adet) x len(bdet)`` subspace, gathered onto one rank, as a bare
+        row-major array of ``float64`` with **no header** -- so
+        ``np.fromfile(path).reshape(len(adet), len(bdet))`` reads it. Naming it
+        ``.dat`` or ``.txt`` instead writes a text table in which every
+        amplitude is labelled with its own alpha and beta bitstring, which is
+        the easiest form to inspect by hand. This is the mechanism this
+        package's own SQD integration uses.
+
+        ``savename`` instead writes one file per b_comm position,
+        ``f"{savename}{rank_b:06d}.bin"``, each holding only **that rank's
+        block** of the subspace: three ``size_t`` headers
+        (``adet_range``, ``bdet_range``, ``det_length``), then that block's
+        alpha and then beta determinant words, then
+        ``adet_range x bdet_range`` ``float64`` amplitudes. It pairs with
+        ``loadname`` for restarting a run, so it is the better choice for
+        checkpointing and the worse one for analysis.
+
+        Amplitudes are ordered by ``adet``/``bdet`` as the diagonalizer saw
+        them. ``sort_bitarray`` removes duplicates as well as sorting, so pass
+        lists already in that form if you need to label the rows and columns
+        yourself.
+
+        Both files use SBD's sign convention, which orders a determinant's
+        creation operators orbital by orbital (alpha 0, beta 0, alpha 1, ...).
+        PySCF, and so qiskit-addon-sqd's ``SCIState``, puts all alpha operators
+        before all beta ones, so some determinants differ in sign: multiply each
+        amplitude by ``(-1) ** n``, where ``n`` counts, over the occupied beta
+        orbitals ``p``, the occupied alpha orbitals above ``p``, before handing
+        it to PySCF. Magnitudes, and so selection by weight, are the same either
+        way. :func:`sbd.sbd_solver.solve_sci` converts the amplitudes in its
+        ``SCIState`` already.
     """
     _ensure_initialized()
     backend = get_backend(device)
@@ -671,7 +797,11 @@ def gdb_diag(fcidump, det, sbd_data,
             writes one file per b_comm position, ``f"{savename}{rank_b:06d}.bin"``,
             each holding only that shard; rank 0's file is not the whole
             wavefunction. GDB has no combined matrix-form dump.
-        device: Override device ('cpu', 'gpu', or None for default).
+        device: Backend to run on: 'cpu', 'gpu' (Thrust), 'gpu-omp' (OpenMP
+            offload), or an alias accepted by :func:`init`. None uses the
+            default; see :func:`get_backend`. 'gpu-omp' is accepted, but SBD
+            has no OpenMP-offload GDB code, so the run executes on the host;
+            use 'gpu' for GDB on GPUs.
         determinant_distribution: How to place determinants across b_comm — one
             of ``input`` (keep the shards as given), ``equal-bra-a`` (default;
             equal distinct-alpha count per rank, which is what balances the

{sbd_eigensolver-1.7.0 → sbd_eigensolver-1.7.1}/python/bindings.cpp

@@ -319,7 +319,12 @@ PYBIND11_MODULE(SBD_MODULE_NAME, m) {
         .def_readwrite("bit_length", &sbd::tpb::SBD::bit_length,
                       "Bit length for determinant representation")
         .def_readwrite("dump_matrix_form_wf", &sbd::tpb::SBD::dump_matrix_form_wf,
-                      "Filename to dump wavefunction in matrix form")
+                      "Path to write the full adet x bdet amplitude matrix to, "
+                      "gathered onto one rank. A .bin path writes a bare "
+                      "row-major float64 array with no header; .dat/.txt write "
+                      "a labelled text table. Distinct from tpb_diag's "
+                      "savename, which writes per-rank blocks with a header "
+                      "for restart -- see the tpb_diag docstring.")
 #ifdef SBD_THRUST
         .def_readwrite("use_precalculated_dets", &sbd::tpb::SBD::use_precalculated_dets,
                       "Use precalculated determinants (THRUST)")

{sbd_eigensolver-1.7.0 → sbd_eigensolver-1.7.1}/python/device_config.py

@@ -27,18 +27,14 @@ class DeviceConfig:
     
     Usage::
 
-        # Auto-detect (uses GPU if available)
-        config = DeviceConfig.auto()
+        from sbd.device_config import DeviceConfig
+        from sbd.sbd_solver import solve_sci_batch
 
-        # Force CPU
-        config = DeviceConfig.cpu()
+        device = DeviceConfig.auto()               # best backend that is built
+        device = DeviceConfig.cpu()                # or force one
+        device = DeviceConfig.gpu(max_memory_gb=16)
 
-        # Force GPU with specific settings
-        config = DeviceConfig.gpu(max_memory_gb=16)
-
-        # Apply to SBD configuration
-        sbd_config = sbd.TPB_SBD()
-        config.apply(sbd_config)
+        results = solve_sci_batch(..., device_config=device)
     """
     
     def __init__(self, device: str = 'cpu',
@@ -72,17 +68,11 @@ class DeviceConfig:
         """
         Auto-detect the best available backend and use it.
 
-        Resolves against the backends that were actually COMPILED, not just the
-        hardware that is present. Detecting a GPU and returning 'gpu'
-        unconditionally was wrong in two ways: on an AMD host it selected the
-        Thrust/CUDA backend, which cannot exist there (upstream wires Thrust to
-        nvc++ -cuda), so a machine that reported "GPU detected (HIP)" then failed
-        to load a CUDA module; and on a CPU-only build with a GPU present it
-        picked a backend that was never built.
-
-        Preference order matches sbd._resolve_device(): Thrust ('gpu') first
-        where it exists, since it is the long-validated NVIDIA default and keeps
-        more phases on the device, then OpenMP offload ('gpu-omp'), then CPU.
+        Chooses among the backends that were actually built, not merely the
+        hardware present, so an AMD host or a CPU-only build is never handed a
+        backend it lacks. The preference order is Thrust ('gpu') where it exists,
+        then OpenMP offload ('gpu-omp'), then CPU, the same order
+        ``sbd.get_backend('auto')`` uses.
 
         Args:
             max_memory_gb: Maximum GPU memory in GB (-1 = auto)
@@ -158,8 +148,8 @@ class DeviceConfig:
         one combination to avoid in a single process is this backend together
         with the CPU one: they share an OpenMP runtime (``libnvomp`` on NVIDIA,
         ``libomp`` on AMD), and loading ``_core_cpu`` first leaves it initialised
-        host-only, after which offload regions run on the host. See
-        :func:`sbd.has_backend_conflict`.
+        host-only, after which offload regions run on the host.
+        ``sbd.has_backend_conflict()`` reports that combination.
         """
         return cls(device='gpu-omp', max_memory_gb=max_memory_gb)
 

{sbd_eigensolver-1.7.0 → sbd_eigensolver-1.7.1}/python/sbd_solver.py

@@ -297,8 +297,10 @@ def _solve_sci_core(
                 "a different size means the dump and the subspace have diverged."
             )
 
+        amplitudes = flat.reshape(n_a, n_b)
+        _to_alpha_first_signs(amplitudes, solved_strings_a, solved_strings_b, norb)
         sci_state = SCIState(
-            amplitudes=flat.reshape(n_a, n_b),
+            amplitudes=amplitudes,
             ci_strs_a=solved_strings_a,
             ci_strs_b=solved_strings_b,
             norb=norb,
@@ -470,25 +472,20 @@ def assemble_rdms(results: dict, norb: int) -> tuple[np.ndarray | None, np.ndarr
     which only computes the diagonal density, not the correlation
     functions), matching SCIResult's own ``rdm1``/``rdm2`` default.
 
-    The reshape/transpose below is not a guess: it was verified against
-    PySCF's ``make_rdm1``/``make_rdm2`` on a fixed subspace, on all three
-    SBD backends (cpu, gpu-thrust, gpu-omp-offload) -- both element-wise on
-    the full tensors and via the energy identity
+    The layout conversion was verified against PySCF's ``make_rdm1`` and
+    ``make_rdm2`` on all three backends (cpu, gpu, gpu-omp), both element-wise
+    and through the energy identity
     ``E = einsum("pr,pr->",rdm1,hcore) + 0.5*einsum("prqs,prqs->",rdm2,eri)``
-    that ``SCIResult.rdm1``/``rdm2`` are contracted with everywhere else in
-    qiskit-addon-sqd (e.g. ``fermion.py``'s own ``solve_fermion``).
+    with which ``qiskit-addon-sqd`` contracts ``SCIResult.rdm1`` and ``rdm2``.
 
-    SBD's documented layout (sbd-ext docs/user-guide.md, matching the C++
-    reference in apps/chemistry_tpb_selected_basis_diagonalization/main.cc)::
+    SBD's layout, as documented in upstream SBD's ``docs/user-guide.md``::
 
         one_p_rdm[s][i + L*j]                 = <c+_{i,s} c_{j,s}>
         two_p_rdm[s+2t][i + L*j + L^2*k + L^3*l] = <c+_{i,s} c+_{j,t} c_{l,t} c_{k,s}>
 
-    A Fortran-order reshape implements those flat-index formulas directly
-    (arr_F[i, j] / arr_F[i, j, k, l]); rdm1 needs no further transpose
-    (it is symmetric here regardless), and rdm2's spin-summed block sum
-    needs axes (0, 2, 1, 3) to land in the "prqs" slot order SCIResult's
-    contract expects.
+    A Fortran-order reshape implements those flat-index formulas directly.
+    rdm1 needs no further transpose, and the spin-summed rdm2 is transposed
+    with axes ``(0, 2, 1, 3)`` into the "prqs" order ``SCIResult`` expects.
     """
     one_p_rdm = results.get("one_p_rdm")
     two_p_rdm = results.get("two_p_rdm")
@@ -693,6 +690,41 @@ def _ci_strings_to_sbd_dets(
     return backend.sort_bitarray(dets)
 
 
+def _to_alpha_first_signs(amplitudes, strings_a, strings_b, norb, block_elements=1 << 24):
+    """Convert SBD's amplitudes, in place, to the sign convention SCIState assumes.
+
+    The two conventions order the creation operators of a determinant differently.
+    SBD interleaves the spins orbital by orbital (alpha 0, beta 0, alpha 1, ...);
+    PySCF, and so ``SCIState.rdm()`` and ``SCIState.spin_square()``, put every alpha
+    operator before every beta one. Moving each beta operator past the alpha
+    operators of higher orbitals gives the determinant the phase
+
+        (-1) ** sum over occupied beta orbitals p of (occupied alpha orbitals above p)
+
+    The magnitudes are the same, so energies, SBD's own RDMs, occupancies and any
+    selection by amplitude magnitude are unaffected, which is why this went unnoticed:
+    only what PySCF computes *from the amplitudes* was wrong -- e.g. ``spin_square()``
+    of 0.036 for an exact singlet, and an energy from ``rdm()`` 89 mHa off.
+
+    Args:
+        amplitudes: The ``(len(strings_a), len(strings_b))`` matrix, modified in place.
+        strings_a: Alpha CI strings labelling the rows; bit ``p`` is orbital ``p``.
+        strings_b: Beta CI strings labelling the columns.
+        norb: Number of spatial orbitals.
+        block_elements: Rows are converted in blocks of about this many elements, so
+            the temporary sign matrix stays bounded at large subspaces.
+    """
+    orbitals = np.arange(norb, dtype=np.int64)
+    occupied_b = ((np.asarray(strings_b, dtype=np.int64)[:, None] >> orbitals) & 1).astype(np.int32)
+    occupied_a = (np.asarray(strings_a, dtype=np.int64)[:, None] >> orbitals) & 1
+    # alpha electrons in orbitals strictly above p, kept only as a parity
+    above_a = ((np.cumsum(occupied_a[:, ::-1], axis=1)[:, ::-1] - occupied_a) & 1).astype(np.int32)
+    rows = max(1, block_elements // max(1, len(strings_b)))
+    for start in range(0, len(strings_a), rows):
+        parity = (above_a[start:start + rows] @ occupied_b.T) & 1
+        amplitudes[start:start + rows][parity == 1] *= -1.0
+
+
 def _sbd_dets_to_ci_strings(
     dets: list[list[int]], norb: int, backend,
     bit_length: int = SBD_DEFAULT_BIT_LENGTH,

{sbd_eigensolver-1.7.0 → sbd_eigensolver-1.7.1/sbd_eigensolver.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sbd-eigensolver
-Version: 1.7.0
+Version: 1.7.1
 Summary: Python bindings for Selected Basis Diagonalization (SBD) library
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://github.com/Qiskit/sbd-eigensolver-python
@@ -272,6 +272,7 @@ config = sbd.TPB_SBD()
 | `adet_comm_size` | 1 | Alpha determinant communicator size |
 | `bdet_comm_size` | 1 | Beta determinant communicator size |
 | `task_comm_size` | 1 | Task communicator size |
+| `dump_matrix_form_wf` | `""` | Path to write the amplitudes to — see [Getting the TPB amplitudes](#getting-the-tpb-amplitudes) for the file format |
 
 Total MPI ranks = `task_comm_size × adet_comm_size × bdet_comm_size`.
 
@@ -315,6 +316,39 @@ results = sbd.tpb_diag(fcidump, adet, bdet, sbd_data,
 
 **Returns:** `dict` with keys `energy`, `density`, `carryover_adet`, `carryover_bdet`, `one_p_rdm`, `two_p_rdm`.
 
+#### Getting the TPB amplitudes
+
+Neither return dict holds the wavefunction amplitudes. Two separate mechanisms write them, in **different formats**, and the one named in the function signature is not the one most callers want:
+
+| | `sbd_data.dump_matrix_form_wf` | `savename` argument |
+|---|---|---|
+| Writes | the full `len(adet) × len(bdet)` subspace, gathered onto one rank | one file per b_comm position, each holding **only that rank's block** |
+| Path | exactly what you set | `f"{savename}{rank_b:06d}.bin"` |
+| Header | **none** | three `size_t` (`adet_range`, `bdet_range`, `det_length`), then that block's alpha and beta determinant words |
+| Payload | `float64`, row-major over α×β | `adet_range × bdet_range` `float64` |
+| Intended for | analysis | checkpoint/restart, paired with `loadname` |
+
+So the whole-subspace read is just:
+
+```python
+config.dump_matrix_form_wf = "wf.bin"
+results = sbd.tpb_diag(fcidump, adet, bdet, config)
+
+amplitudes = np.fromfile("wf.bin").reshape(len(adet), len(bdet))
+```
+
+Naming that file `.dat` or `.txt` instead writes a text table labelling every amplitude with its own alpha and beta bitstring — the easiest form to inspect by hand, and it sidesteps having to reconstruct the ordering yourself:
+
+```
+<amplitude> # <alpha index>: <alpha bitstring> <beta index>: <beta bitstring>
+```
+
+Be aware that this text form is written with the stream's default formatting, so amplitudes land with only ~6 significant digits; use the binary form when you need full `float64` precision.
+
+Rows and columns follow `adet`/`bdet` as the diagonalizer saw them. `sort_bitarray` removes duplicates as well as sorting, so pass lists already in that form if you intend to label the axes yourself — `from_strings` documents the word packing.
+
+This is the mechanism [`sbd_solver.py`](python/sbd_solver.py) uses to populate `SCIState.amplitudes` — though it skips the write entirely when SBD is picking the carryover itself (`carryover_type` 1, against a qiskit-addon-sqd that accepts it), since then the next subspace comes back in `carryover_adet`/`carryover_bdet` and the amplitudes never need to reach Python.
+
 ```python
 # GDB: over an explicit list of full determinants rather than a product space
 results = sbd.gdb_diag(fcidump, det, sbd_data,

{sbd_eigensolver-1.7.0 → sbd_eigensolver-1.7.1}/sbd_eigensolver.egg-info/SOURCES.txt

@@ -27,6 +27,7 @@ sbd_eigensolver.egg-info/top_level.txt
 test/test_gdb_drivers.py
 test/test_gdb_equivalence.py
 test/test_reference_energies.py
+test/test_sci_state.py
 test/test_sqd_integration.py
 vendor/sbd-upstream/LICENSE.txt
 vendor/sbd-upstream/include/sbd/sbd.h