From 15b1fbcac006fef85648bafb50aae3240b262892 Mon Sep 17 00:00:00 2001 From: Sophia Wen Date: Wed, 7 Oct 2026 17:10:03 -0400 Subject: [PATCH 1/2] docs: list the API users call, grouped, and document the config fields The API pages used automodule :members:, which documents every public-named object: 40 entries, including internals (DeviceConfig.apply, create_sbd_solver), a deprecated alias (gpu_nvidia_omp), single-item forms of bulk functions (makestring, from_string), and debugging aids. Each page now names its objects explicitly, under task headings: 26 entries. Nothing is removed from __all__ or the code, so every name still works; this only chooses what the reference shows. TPB_SBD and GDB_SBD are factory functions, so none of their fields appeared anywhere in the docs. They are now tabulated: fields shared by both, then each struct's own, taken from the bindings.cpp docstrings and filled in where those were terse. There is no defaults column, because upstream's struct defaults and the ones solve_sci applies differ. DeviceConfig needs :no-inherited-members: alongside its explicit member list: conf.py's autodoc_default_options set inherited-members, which otherwise brought apply and gpu_nvidia_omp back. Co-Authored-By: Claude Opus 5.5 --- docs/apidocs/sbd.device_config.rst | 12 ++- docs/apidocs/sbd.rst | 148 ++++++++++++++++++++++++++++- docs/apidocs/sbd.sbd_solver.rst | 15 ++- 3 files changed, 163 insertions(+), 12 deletions(-) diff --git a/docs/apidocs/sbd.device_config.rst b/docs/apidocs/sbd.device_config.rst index 7c1a7d1..268cca7 100644 --- a/docs/apidocs/sbd.device_config.rst +++ b/docs/apidocs/sbd.device_config.rst @@ -2,7 +2,13 @@ Device configuration (:mod:`sbd.device_config`) ================================================ -.. automodule:: sbd.device_config - :members: +.. module:: sbd.device_config + +Selects the backend a solver call runs on. Pass a :class:`DeviceConfig` as the +``device_config`` argument of :func:`sbd.sbd_solver.solve_sci_batch` or +:func:`~sbd.sbd_solver.solve_sci`. + +.. autoclass:: DeviceConfig + :members: cpu, gpu, gpu_omp, auto + :member-order: bysource :no-inherited-members: - :no-special-members: diff --git a/docs/apidocs/sbd.rst b/docs/apidocs/sbd.rst index 2e256e8..9f2c870 100644 --- a/docs/apidocs/sbd.rst +++ b/docs/apidocs/sbd.rst @@ -2,8 +2,146 @@ SBD bindings (:mod:`sbd`) ============================= -.. automodule:: sbd - :members: - :exclude-members: sbd_solver - :no-inherited-members: - :no-special-members: +.. module:: sbd + +Direct access to SBD's two diagonalization methods. **TPB** (tensor-product basis) +diagonalizes in the product of an alpha and a beta determinant list. **GDB** +(general determinant basis) diagonalizes in an explicit list of determinants, and is +experimental. For use inside a ``qiskit-addon-sqd`` loop, see :mod:`sbd.sbd_solver` +instead. + +The backend initializes itself on first use, so :func:`init` is needed only to choose +a device or communicator explicitly. + +Diagonalization +=============== + +.. autofunction:: tpb_diag +.. autofunction:: tpb_diag_from_files +.. autofunction:: gdb_diag + +Configuration +============= + +.. autofunction:: TPB_SBD +.. autofunction:: GDB_SBD + +Both return a configuration object whose fields are set as attributes before it is +passed to a diagonalization, for example ``config.eps = 1e-8``. The defaults are +upstream SBD's; :func:`sbd.sbd_solver.solve_sci` and +:func:`~sbd.sbd_solver.solve_sci_batch` set their own unless overridden through +``sbd_config``. + +Fields shared by ``TPB_SBD`` and ``GDB_SBD``: + +.. list-table:: + :header-rows: 1 + :widths: 28 72 + + * - Field + - Meaning + * - ``method`` + - ``0`` Davidson, ``1`` Davidson with the Hamiltonian stored. TPB also has + ``2`` and ``3``, the Lanczos variants; GDB rejects them. + * - ``eps`` + - Davidson stopping tolerance on the residual norm, not on the energy. + * - ``max_it`` + - Maximum Davidson iterations. Reaching it before ``eps`` returns a partly + converged vector without warning. + * - ``max_nb`` + - Maximum number of Davidson basis vectors. + * - ``max_time`` + - Wall-clock limit, in seconds. + * - ``init`` + - Starting vector: ``0`` puts unit weight on the first determinant of the basis, + ``1`` is random. + * - ``seed`` + - Seed for the random starting vector; used only with ``init = 1``. + * - ``do_rdm`` + - ``0`` returns the orbital density only, ``1`` also the 1- and 2-particle RDMs. + * - ``carryover_type`` + - How SBD selects determinants for a next iteration. ``0`` is off. See the + per-method tables below for what the other values do. + * - ``ratio``, ``threshold`` + - Carryover selection parameters. Which of the two a given ``carryover_type`` + reads differs, and SBD silently ignores the other. + * - ``bit_length`` + - Bits per word when packing determinants. At most 63. + +Fields of ``TPB_SBD`` only: + +.. list-table:: + :header-rows: 1 + :widths: 28 72 + + * - Field + - Meaning + * - ``adet_comm_size``, ``bdet_comm_size`` + - MPI ranks spanning the alpha and beta determinant dimensions. + * - ``task_comm_size`` + - MPI ranks spanning task-level parallelism. The rank count must be a multiple of + ``task_comm_size * adet_comm_size * bdet_comm_size``; the remainder becomes the + derived helper dimension. + * - ``carryover_type`` + - ``1`` ranks half-determinants by marginal weight; ``2`` also adds their single + excitations; ``3`` ranks whole determinants by amplitude, then adds single + excitations. + * - ``do_shuffle`` + - Shuffle the determinants loaded from file before use. + * - ``dump_matrix_form_wf`` + - Path to which SBD writes the wavefunction as an ``|adet| x |bdet|`` matrix. + * - ``use_precalculated_dets`` + - Thrust backend only. Precompute a determinant index for the whole subspace on + the GPU: faster, but far more memory. + * - ``max_memory_gb_for_determinants`` + - Thrust backend only, and used only when ``use_precalculated_dets`` is off: a + per-thread buffer cap in GB, or ``-1`` for none. + +Fields of ``GDB_SBD`` only: + +.. list-table:: + :header-rows: 1 + :widths: 28 72 + + * - Field + - Meaning + * - ``b_comm_size`` + - MPI ranks the determinant basis is sharded across. It is the only dimension + that divides memory. With more than 1, each rank passes only its own shard to + :func:`gdb_diag`. + * - ``t_comm_size`` + - MPI ranks spanning tasks. Must not exceed ``b_comm_size``. + * - ``carryover_type`` + - ``1`` truncates by weight; ``2`` and ``3`` expand by heatbath selection. + * - ``heatbath_cutoff`` + - Heatbath selection cutoff: a candidate is added when ``|c_i H_ij|`` exceeds it. + * - ``heatbath_truncation`` + - Weight below which parents are dropped before expansion. Large values remove + the parents the expansion needs. + * - ``heatbath_batch_size`` + - Number of candidates processed per batch during expansion. + +Inputs +====== + +.. autofunction:: LoadFCIDump +.. autofunction:: LoadAlphaDets +.. autofunction:: sort_bitarray +.. autofunction:: from_strings +.. autofunction:: sort_bitarray_array + +Backends and devices +==================== + +.. autofunction:: init +.. autofunction:: finalize +.. autofunction:: available_backends +.. autofunction:: backend_load_errors +.. autofunction:: get_backend +.. autofunction:: get_device_id + +MPI +=== + +.. autofunction:: get_rank +.. autofunction:: get_world_size diff --git a/docs/apidocs/sbd.sbd_solver.rst b/docs/apidocs/sbd.sbd_solver.rst index 65be11d..2d62fe9 100644 --- a/docs/apidocs/sbd.sbd_solver.rst +++ b/docs/apidocs/sbd.sbd_solver.rst @@ -2,7 +2,14 @@ SQD-compatible solver (:mod:`sbd.sbd_solver`) ============================================= -.. automodule:: sbd.sbd_solver - :members: - :no-inherited-members: - :no-special-members: +.. module:: sbd.sbd_solver + +SBD as the eigensolver of a ``qiskit-addon-sqd`` loop. Pass +:func:`solve_sci_batch`, with its options bound by :func:`functools.partial`, as the +``sci_solver`` argument of ``diagonalize_fermionic_hamiltonian``; it runs on every MPI +rank. These solvers use SBD's TPB method. GDB has no SQD-loop integration; call +:func:`sbd.gdb_diag` directly. + +.. autofunction:: solve_sci_batch +.. autofunction:: solve_sci +.. autofunction:: assemble_rdms From 644fda3e57a2fe2f67f0084aa969986c7517aa44 Mon Sep 17 00:00:00 2001 From: Sophia Wen Date: Fri, 9 Oct 2026 15:41:59 -0400 Subject: [PATCH 2/2] docs: bit_length limits for GDB, and GDB's rank layout on Thrust Co-Authored-By: Claude Opus 5.5 --- docs/apidocs/sbd.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/apidocs/sbd.rst b/docs/apidocs/sbd.rst index 9f2c870..1a5e968 100644 --- a/docs/apidocs/sbd.rst +++ b/docs/apidocs/sbd.rst @@ -66,7 +66,11 @@ Fields shared by ``TPB_SBD`` and ``GDB_SBD``: - Carryover selection parameters. Which of the two a given ``carryover_type`` reads differs, and SBD silently ignores the other. * - ``bit_length`` - - Bits per word when packing determinants. At most 63. + - Bits per word when packing determinants. At most 63; 64 is undefined + behavior in SBD's multi-rank redistribution. For GDB's heatbath expansion + (``carryover_type`` 2 or 3) it must also be even whenever a determinant spans + more than one word, or the expansion crashes or returns a wrong energy. The + ``examples/gdb`` drivers require an even value of at most 62. Fields of ``TPB_SBD`` only: @@ -110,7 +114,9 @@ Fields of ``GDB_SBD`` only: that divides memory. With more than 1, each rank passes only its own shard to :func:`gdb_diag`. * - ``t_comm_size`` - - MPI ranks spanning tasks. Must not exceed ``b_comm_size``. + - MPI ranks spanning tasks. Must not exceed ``b_comm_size``. The rank count must + be a multiple of ``t_comm_size * b_comm_size``; on the Thrust backend it must + equal it, since GDB on Thrust has no helper dimension. * - ``carryover_type`` - ``1`` truncates by weight; ``2`` and ``3`` expand by heatbath selection. * - ``heatbath_cutoff``