Metadata-Version: 2.4
Name: qcsc-prefect-sbd
Version: 0.3.1
Summary: SBD Davidson solver integration for qcsc-prefect
Author: QCSC Prefect Contributors
Maintainer: QCSC Prefect Maintainers
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/qiskit-community/qcsc-prefect
Project-URL: Repository, https://github.com/qiskit-community/qcsc-prefect
Project-URL: Documentation, https://qiskit-community.github.io/qcsc-prefect/
Project-URL: Issues, https://github.com/qiskit-community/qcsc-prefect/issues
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: prefect>=2.19
Requires-Dist: pydantic>=2
Requires-Dist: pyscf
Requires-Dist: qcsc-prefect-blocks==0.3.1
Requires-Dist: qcsc-prefect-core==0.3.1
Requires-Dist: qcsc-prefect-executor==0.3.1

# QCSC Prefect SBD

Shared Python-side SBD Davidson solver integration for qcsc-prefect workflows.

This package provides:

- `SBDSolverJob` as a Prefect block (block type slug `sbd_solver_job`)
- `SBDResult`, the parsed solver output
- `create_sbd_blocks` / `register_sbd_block_types`: create the command,
  execution-profile, HPC-profile and solver blocks for `local`, `slurm`, `miyabi` or
  `fugaku`
- SBD input/output file handling and scheduler execution through qcsc-prefect blocks

It is intended to be reused by multiple algorithms. Installing this package does not
build, download, vendor, or install the external SBD executable (`diag`). The executable
must be compiled separately for each target HPC environment.

Source-tree native build helper assets live under:

```text
packages/qcsc-prefect-sbd/native
```

They are not part of the Python package install. See [native/README.md](./native/README.md)
for the build scripts and how to point `sbd_executable` at the separately built binary.

## Usage Example

```python
from qcsc_prefect_sbd import SBDSolverJob, create_sbd_blocks

create_sbd_blocks(
    hpc_target="slurm",
    queue="normal",
    root_dir="/shared/sbd-jobs",
    sbd_executable="/abs/path/to/qcsc-prefect/packages/qcsc-prefect-sbd/native/diag",
    num_nodes=2,
    mpiprocs=4,
    mpi_options=["--mpi=pmix"],
)

# Inside a flow:
solver = await SBDSolverJob.load("sbd-solver")
result = await solver.run(
    ci_strings=(alpha_strings, beta_strings),
    one_body_tensor=h1,
    two_body_tensor=h2,
    norb=norb,
    nelec=nelec,
)
print(result.energy, result.carryover_bitstrings.shape)
```

`create_sbd_blocks` checks the request before it saves any block: local execution takes
no `modules` or `pre_commands`, `gpus_per_node` must fit the target, `solver_mode="gpu"`
needs `resource_class="gpu"`, and `task_comm_size x adet_comm_size x bdet_comm_size` must
divide the MPI rank count (`num_nodes x mpiprocs`). The launcher defaults to `single`
(local), `srun` (Slurm), `mpiexec.hydra` (Miyabi) or `mpiexec` (Fugaku).

## Closed and open shells

`SBDSolverJob.run` takes the same arguments as `DiceSHCISolverJob.run`. SBD diagonalizes
in the product of the alpha and beta determinant sets with the restricted integrals, so it
solves closed-shell and restricted open-shell (ROHF, `nelec[0] != nelec[1]`) problems.

- When the alpha and beta sets are the same, SBD reads `AlphaDets.bin` for both spins.
- When they differ (always for `nelec[0] != nelec[1]`), the beta set goes to
  `BetaDets.bin` (`--bdetfile`), and `SBDResult.carryover_bitstrings_b` holds the beta
  carryover. It is None when one set is shared.

`run` raises `ValueError` (see `check_sbd_input`) when:

- the alpha set does not start with its Hartree-Fock determinant, `(1 << nelec[0]) - 1`,
  or the beta set with `(1 << nelec[1]) - 1`;
- `spin_sq` is not `None` (SBD has no total spin target).

Each determinant must also have `nelec[0]` (alpha) or `nelec[1]` (beta) set bits and a
set must not repeat a determinant. The FCIDUMP has no core energy, so `energy` is the
electronic energy, as with the DICE solver.

The block refers to a `CommandBlock`, an `ExecutionProfileBlock` and an `HPCProfileBlock`
by name. `create_sbd_blocks` creates all four. In the open-loop SQD workflow,
`sqd-create-blocks --solver sbd` (`algorithms/open_loop/sqd/sqd_sbd/create_blocks.py`)
creates them from `sqd_blocks.toml` as `sqd-sbd-solver`, `cmd-sqd-sbd-solver`,
`exec-sqd-sbd-<system>` and `hpc-<system>-sqd-sbd`; see
[its README](../../algorithms/open_loop/sqd/README.md).
`algorithms/closed_loop/sqd_de/create_blocks.py` creates them for the closed-loop
workflow on Miyabi, Fugaku or Slurm.

Blocks saved before this package existed, when `SBDSolverJob` was defined in
`algorithms/closed_loop/sqd_de`, keep working: the block type name (`SBD Solver Job`) and
slug are unchanged, and `carryover_type`, which they lack, defaults to 1.
