QCSC Prefect Fulqrum
Fulqrum subspace eigensolver integration for qcsc-prefect workflows. It is a drop-in alternative to the DICE SHCI solver for SQD.
This package provides:
solve_fulqrum: a Prefect-free solver core. It diagonalizes the molecular Hamiltonian in the subspace spanned by alpha/beta CI strings on the CPU, on the GPUs of one node, or on one MPI rank per GPU across nodes. It returns the energy, orbital occupancies, carryover strings and amplitudes.qcsc-fulqrum-solve <work_dir>: the compute-node executable. It readsinput.npz+solver.json, runssolve_fulqrum, and writesoutput.npz+result.json. On failure it writeserror.json(error.rank<k>.jsonfrom processk > 0of a multi-process run) and exits with status 1. It imports neither Prefect nor qiskit-addon-sqd.FulqrumSolverJob: a Prefect block with the samerun()signature andSCIResultreturn type asDiceSHCISolverJob. It writes the job directory, runsqcsc-fulqrum-solvethroughrun_job_from_blocks, and reads the result back.spin_sqis accepted and ignored.create_fulqrum_blocks/register_fulqrum_block_types: create the command, execution-profile, HPC-profile and solver blocks forlocal,slurm,miyabiorfugaku.
Fulqrum itself is not installed from PyPI. It is built per site with
native/build_fulqrum.sh, by default fulqrum 1.0 at a pinned commit, into the
virtual environment native/fulqrum. The script installs this package there
with --no-deps, so the executable is native/fulqrum/bin/qcsc-fulqrum-solve;
the compute node needs only numpy, scipy and fulqrum, plus CuPy and mpi4py for
the GPU backends.
native/README.md has the CPU and GPU build recipes, the
launch layout and the runtime variables.
The optional PRIMME eigensolver
(eigensolver="primme") is built by the same script with
FULQRUM_WITH_PRIMME=1. PyPI only has a source release, so the build needs a C
compiler, Python headers, pkg-config and a BLAS/LAPACK that has a .pc file
(for example openblas-devel). The default scipy eigensolver needs none of
this.
Backends
FulqrumSolverOptions(backend=...), or the backend field of
FulqrumSolverJob:
cpu(default): one OpenMP process.gpu: one process on every GPU it sees (fulqrum.gpu.GPUHamiltonian), with the samescipyorprimmeeigensolver ascpu.gpu-mpi: one MPI rank per GPU, across nodes (fulqrum.gpu.DistributedMPIGPUHamiltonianand fulqrum's distributed PRIMME). The state stays distributed, so there are no amplitudes; the occupancies and the carryover come from the per-string weights summed over the ranks. Launch it withsrun --mpi=pmixormpirun, one rank per GPU.
The GPU backends need fulqrum built with FULQRUM_WITH_GPU=1, CuPy for the
CUDA major version of the toolkit (cupy-cuda13x by default, cupy-cuda12x for
CUDA 12), and for gpu-mpi mpi4py built against the site's MPI. The kernels
need at least two electrons per spin; smaller problems are solved on the CPU
with a warning. Subspaces of at most dense_max_dim determinants are solved
densely on the CPU with every backend. Under gpu-mpi a rank that fails writes
its error file and aborts MPI.COMM_WORLD, so the others do not hang.
Usage
Direct, in-process:
from qcsc_prefect_fulqrum import FulqrumSolverOptions, solve_fulqrum
solution = solve_fulqrum(
ci_strings=(ci_strs_a, ci_strs_b),
one_body_tensor=h1,
two_body_tensor=eri, # full 4-index, PySCF chemist notation
norb=norb,
nelec=(n_alpha, n_beta),
options=FulqrumSolverOptions(tol=1e-8),
)
total_energy = solution.energy + nuclear_repulsion_energy
Through blocks, on a scheduler:
from qcsc_prefect_fulqrum import FulqrumSolverJob, create_fulqrum_blocks
create_fulqrum_blocks(
hpc_target="slurm",
queue="normal",
root_dir="/shared/fulqrum-jobs",
fulqrum_executable="/path/to/qcsc-prefect/packages/qcsc-prefect-fulqrum/native/fulqrum/bin/qcsc-fulqrum-solve",
ompthreads=8,
)
# Inside a flow:
solver = await FulqrumSolverJob.load("fulqrum-solver")
result = await solver.run(ci_strings, h1, eri, norb, nelec) # SCIResult
The returned energy is electronic only, as with the DICE solver.
solution.amplitudes[ia, ib] (and SCIResult.sci_state.amplitudes) follows the
qiskit_addon_sqd.fermion.SCIState layout over ci_strs_a × ci_strs_b.
The cpu backend runs as one OpenMP process. create_fulqrum_blocks defaults
to launcher="single" with one task. It also exports OMP_NUM_THREADS when
ompthreads is set. If OMP_NUM_THREADS is unset, qcsc-fulqrum-solve falls
back to SLURM_CPUS_PER_TASK.
Tests
- The io, CLI, block and solver-job tests run anywhere. The block and solver-job tests skip where Prefect is not installed.
- The GPU backend tests (
test_fulqrum_gpu_backends.py) run anywhere, against fake fulqrum, CuPy and mpi4py modules. - The numerical tests need fulqrum and PySCF, so they skip when those are not installed. Run them on a node where fulqrum is built.
test_fulqrum_gpu_integration.pycompares the GPU backends with the CPU on real GPUs. It needs a GPU build andFULQRUM_GPU=1, and runs undermpirunorsrun; see native/README.md.test_fulqrum_slurm_integration.pysubmits real Slurm jobs. It needsSLURM_INTEGRATION=1andsbatch, and no Prefect server.
Metadata
Release files for qcsc-prefect-fulqrum 0.3.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| qcsc_prefect_fulqrum-0.3.1.tar.gz | 56.5 kB | With provenance | Details for qcsc_prefect_fulqrum-0.3.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| qcsc_prefect_fulqrum-0.3.1-py3-none-any.whl | Python 3 | none | any | Details for qcsc_prefect_fulqrum-0.3.1-py3-none-any.whl |
Total release size: 89.0 kB
Release files / qcsc_prefect_fulqrum-0.3.1.tar.gz
| Download URL | qcsc_prefect_fulqrum-0.3.1.tar.gz |
|---|---|
| Size | 56.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
17133cce6f9480bc24f6f59fee2fb97afeeb77f29d17dbf9d91be63597f7eb2b
|
|
BLAKE2b-256 checksum How to use checksums |
36391c1040732678480a92d8e7e1634001c8168f3dc0c4fa0e926b7d3c36d3f6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.
Transparency logRelease files / qcsc_prefect_fulqrum-0.3.1-py3-none-any.whl
| Download URL | qcsc_prefect_fulqrum-0.3.1-py3-none-any.whl |
|---|---|
| Size | 32.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2194c6b19ec7a413294b0a14bcb945fafab81cbec98c96c2dd775f0771cf585c
|
|
BLAKE2b-256 checksum How to use checksums |
3bcab9d7934f33fa9ea110293f6b1cea7901d6e006258d872a914dd5dbd0ff00
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.
Transparency logSecurity for qcsc-prefect-fulqrum 0.3.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for qcsc_prefect_fulqrum-0.3.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.