fulqrum.gpu.TileGPUResidentHamiltonian

class TileGPUResidentHamiltonian(hsub, alpha_strs, beta_strs, *, gpu_ids=(0,), comm=None, process_grid=None, threads_per_block=256, comm_backend='auto', intra_node_size=None, build_threads=0, config=None)

GPU-backed real type-2 Hamiltonian for distributed matrix-free matvecs.

Use this operator with distributed_primme_eigsh for MPI eigenvalue solves.

The subspace must be a half-string/tensor product with alpha in the low qubits and beta in the high qubits. Each sector must have 1–128 orbitals (bits), a fixed electron count and operator groups supported by the GPU kernels. Use at least two occupied orbitals per half string; lower occupations are outside verified GPU support and may give incorrect results. GPU execution requires CuPy and the compiled CUDA components.

Parameters:

• hsub – Real type-2 SubspaceHamiltonian on the tensor product subspace.

• alpha_strs – Spin-sector string collections matching hsub. Each sector supports 1–128 orbitals. Use binary-string sequences or integer NumPy arrays: one-dimensional uint64 for sectors of at most 64 orbitals, shape (N, 2) uint64 (lowest orbitals in column 0) for wider sectors.

• beta_strs – Spin-sector string collections matching hsub. Each sector supports 1–128 orbitals. Use binary-string sequences or integer NumPy arrays: one-dimensional uint64 for sectors of at most 64 orbitals, shape (N, 2) uint64 (lowest orbitals in column 0) for wider sectors.

• gpu_ids – Exactly one CUDA device ID for this rank, as a one-element sequence. Defaults to (0,); choose each rank’s device explicitly.

• comm – MPI communicator; defaults to MPI.COMM_WORLD. LocalComm supports in-process workers, as used by GPUHamiltonian.

• process_grid – (p_alpha, p_beta), with product equal to communicator size (num ranks). None chooses a grid automatically.

• threads_per_block – CUDA threads per kernel block; defaults to 256.

• comm_backend – "auto", "nccl", "host_mpi", "cuda_mpi" or "inproc". Automatic selection respects GPU configuration; it tries nccl first and falls back to host_mpi when conditions are not met. Prefer nccl when available or host_mpi otherwise. cuda_mpi may work, but is not fully validated yet. LocalComm uses the in-process backend.

• intra_node_size – Optional positive size of contiguous rank groups for communication. None uses detected node membership.

• build_threads – CPU construction threads. Zero derives the count from OMP_NUM_THREADS; positive FQ_BUILD_THREADS takes precedence.

• config – Checked GpuConfig snapshot. None uses GpuConfig.from_environ() during construction.

Raises:

• NotImplementedError – Complex operators or multiple GPU IDs per rank are requested.

• ValueError – Device selection, process grid, layout, electron counts, operator groups or shared settings are invalid.

• ImportError – The default MPI communicator cannot be obtained because mpi4py is unavailable.

• RuntimeError – Collective construction or device-memory checks fail.

Methods

compute_rdms(evec_local, *[, rank, spin_summed])	Collectively compute reduced density matrices from local state-vector tiles.
partition_diagnostic()	Return local connection counts and estimates for comparing partition work.
predicted_hbm_split()	Split predicted_hbm_bytes into allocated and not-yet-allocated bytes.
rdm_scratch()
reset_cache()	Clear this rank's cached GPU connection data for rebuilding on the next matvec.
run_workers()	Compatibility no-op; all ranks participate directly in collective calls.
stop_workers()	Compatibility no-op; there are no persistent workers to stop.
verify_hbm_fits()	Collectively check predicted allocations against available GPU memory.

Attributes

H	Hermitian adjoint.
T	Transpose.
assigned_source_ranks	Same source-rank tuple as source_ranks.
backend_name	nccl, host_mpi, cuda_mpi or inproc.
comm	MPI or LocalComm communicator used by this rank.
construction_timing	Return a copy of this rank's construction measurements and resolved settings.
coord_alpha	This rank's zero-based alpha coordinate in process_grid.
coord_beta	This rank's zero-based beta coordinate in process_grid.
diag_local	Return this rank's Hamiltonian diagonal as a host NumPy float64 vector.
last_timing	Return a copy of this rank's latest successful matvec timing dictionary.
min_free_hbm_bytes	Lowest sampled free memory on this rank's GPU, in bytes, or None.
n_a_local	Number of alpha half strings in this rank's vector tile.
n_b_local	Number of beta half strings in this rank's vector tile.
n_local	Local vector length, equal to n_a_local * n_b_local.
predicted_hbm_bytes	Return this rank's predicted GPU memory by allocation category, in bytes.
process_grid	Process grid (p_alpha, p_beta); product equals communicator size.
run_record	Return this rank's JSON-serializable settings and construction choices.
source_ranks	Sorted communicator ranks whose vector tiles contribute to this rank's result.
supports_device_matvec	Whether this instance enables CuPy input and out for local matvecs.
ndim

property assigned_source_ranks: tuple[int, ...]

Same source-rank tuple as source_ranks.

property backend_name: str

nccl, host_mpi, cuda_mpi or inproc.

Type:

Resolved backend

property comm

MPI or LocalComm communicator used by this rank.

compute_rdms(evec_local, *, rank: int = 1, spin_summed: bool = False)

Collectively compute reduced density matrices from local state-vector tiles.

Every rank supplies its part of the same real state and uses the same rank and spin_summed options. All ranks receive the full result as host NumPy arrays after GPU work and communication complete. Alpha and beta must have equal orbital counts.

Amplitudes are used without normalization. Scaling the full state by a real factor scales every RDM by its square. Normalize the full state before distributing it if you need RDMs for a normalized state. Spin and tensor-index conventions follow PySCF make_rdm12s(reorder=True).

Parameters:

• evec_local – NumPy-compatible or CuPy array of n_local real amplitudes, or shape (n_b_local, n_a_local). Uses the same beta-outer, alpha-inner tile order as the local matvec.

• rank – RDM order, 1 or 2; defaults to 1. This is not an MPI rank.

• spin_summed – Combine alpha and beta spin blocks; defaults to False.

Returns:

For rank=1, (gamma_a, gamma_b) or spin-summed gamma. For rank=2, ((gamma_a, gamma_b), (G_aa, G_ab, G_bb)) or spin-summed (gamma, G). Each one-particle array has shape (m, m) and each two-particle array (m, m, m, m), where m is the common number of orbitals per sector.

Raises:

• FulqrumError – A sector has more than 128 orbitals.

• ValueError – The RDM order, local vector size or sector counts are invalid, or alpha and beta have different orbital counts.

property construction_timing: dict

Return a copy of this rank’s construction measurements and resolved settings.

Phase times are in seconds and allocation sizes in bytes. The dictionary also includes counts, grid dimensions and execution choices. Reading it does not repeat construction or launch GPU work.

property coord_alpha: int

This rank’s zero-based alpha coordinate in process_grid.

property coord_beta: int

This rank’s zero-based beta coordinate in process_grid.

property diag_local: ndarray

Return this rank’s Hamiltonian diagonal as a host NumPy float64 vector.

Includes constant energy, has length n_local and uses beta-outer, alpha-inner tile order. Suitable for the distributed solver’s local diagonal preconditioner. The array may be cached; treat it as read-only. Access may compute the diagonal or copy it from the GPU. Without CuPy, this property returns a zero array.

property last_timing: dict

Return a copy of this rank’s latest successful matvec timing dictionary.

Empty before the first successful product. wall, compute and exchange are in seconds; comm_ms_total is in milliseconds, and *_bytes fields are byte counts. The compute interval includes exchange, so these durations are not additive. Reading uses existing measurements only.

property min_free_hbm_bytes

Lowest sampled free memory on this rank’s GPU, in bytes, or None.

Samples are recorded after construction and matvecs. This is a local sampled minimum, not a continuously measured peak or a cross-rank minimum.

property n_a_local: int

Number of alpha half strings in this rank’s vector tile.

property n_b_local: int

Number of beta half strings in this rank’s vector tile.

property n_local: int

Local vector length, equal to n_a_local * n_b_local.

partition_diagnostic() → dict

Return local connection counts and estimates for comparing partition work.

property predicted_hbm_bytes: dict

Return this rank’s predicted GPU memory by allocation category, in bytes.

Covers Hamiltonian buffers, tables and caches. Solver-owned storage is separate. These are the estimates used by verify_hbm_fits, not a measurement of total device usage. Reading does not allocate GPU memory.

predicted_hbm_split() → tuple[dict, dict]

Split predicted_hbm_bytes into allocated and not-yet-allocated bytes.

Returns (resident, pending). Resident categories are allocated by the end of construction; pending ones are allocated lazily, mostly by the first matvec. verify_hbm_fits compares only the pending bytes with free memory, and the sum of both with total memory.

property process_grid: tuple[int, int]

Process grid (p_alpha, p_beta); product equals communicator size.

reset_cache() → None

Clear this rank’s cached GPU connection data for rebuilding on the next matvec.

Host-resident caches are retained. For a distributed operator, invoke this on all ranks before their next collective product.

property run_record: dict

Return this rank’s JSON-serializable settings and construction choices.

Includes the resolved backend, exchange mode, process grid, tuning decisions and configuration digests. Uses existing state without GPU work or communicator collectives.

run_workers() → None

Compatibility no-op; all ranks participate directly in collective calls.

property source_ranks: tuple[int, ...]

Sorted communicator ranks whose vector tiles contribute to this rank’s result.

Includes this rank. The tuple describes source communication, not a separate set of eigensolver participants.

stop_workers() → None

Compatibility no-op; there are no persistent workers to stop.

property supports_device_matvec: bool

Whether this instance enables CuPy input and out for local matvecs.

This reports the selected device-vector code path; it is not a separate CUDA hardware or kernel validation test.

verify_hbm_fits()

Collectively check predicted allocations against available GPU memory.

Call on every communicator rank. Tries to release unused CuPy device and pinned memory-pool blocks before querying free memory, then checks estimates with reserved headroom. Existing allocated buffers remain in use. Without CuPy, the memory test is skipped; ranks still participate in the collective error check.

Returns:

None when no rank reports an overrun.

Raises:

RuntimeError – At least one rank’s predicted allocations do not fit; the error is raised on every rank.