fulqrum.gpu.GPUHamiltonian

class GPUHamiltonian(hsub, gpu_ids=None, threads_per_block=256, verbose=False)[source]

GPU-accelerated real type-2 Hamiltonian for tensor-product subspace (non-MPI).

It performs matrix-free matrix @ vector (matvec) product and can used with SciPy LinearOperator-compatible eigensolvers such as scipy.sparse.linalg.eigsh and primme.eigsh. MPI is not required to use single or multiple GPUs on a single node via this wrapper. For multiple processes, use DistributedMPIGPUHamiltonian.

Requires at least two occupied orbitals in every half string. Smaller occupations trigger RuntimeWarning and may produce incorrect results.

Parameters:

  • hsub – Real type-2 SubspaceHamiltonian on the half-string/tensor product subspace described above.

  • gpu_ids – Sequence of CUDA device IDs, one per worker. Repeated IDs share a device. None uses the current CUDA device; the sequence must be nonempty.

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

  • verbose – Emit a DEBUG log describing wrapper construction. Configure the GPU logger at DEBUG level to display it.

Raises:

  • NotImplementedError – The Hamiltonian has complex values.

  • FulqrumError – The Hamiltonian is not Fulqrum’s type 2 operator or the subspace is not a half-string/tensor product.

  • ValueError – Device selection, sector layout, electron counts or operator groups are unsupported.

  • ImportError – CuPy or a required compiled GPU component is unavailable.

  • RuntimeError – Construction checks or predicted device-memory checks fail.

Methods

compute_rdms(evec, *[, rank, spin_summed])

Compute one- and optionally two-particle reduced density matrices.

dump_profile_summary([stream])

Write the latest matvec timings for each worker and return the text.

reset_cache()

Clear cached GPU connection data on every worker.

Attributes

H

Hermitian adjoint.

T

Transpose.

gpu_ids

CUDA device IDs in worker order, returned as an immutable tuple.

last_timing

Return one timing-dictionary copy per worker, in gpu_ids order.

ndim

compute_rdms(evec, *, rank: int = 1, spin_summed: bool = False)[source]

Compute one- and optionally two-particle reduced density matrices.

Pass the full real state vector in the same sorted product order as the tensor-product subspace. The wrapper distributes it to every worker and returns the combined result as host NumPy arrays after GPU work completes. Alpha and beta must have equal orbital counts for this operation.

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

Parameters:

  • evec – NumPy-compatible or CuPy array containing n_alpha * n_beta real amplitudes, in beta-outer, alpha-inner order.

  • rank – RDM order, 1 or 2; defaults to 1. This is not a worker index.

  • 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 or vector length is invalid, or alpha and beta have different orbital counts.

dump_profile_summary(stream=None) → str[source]

Write the latest matvec timings for each worker and return the text.

Reports wall, compute and exchange in seconds, with worker and device IDs. The compute interval includes exchange, so the reported times are not additive. Uses existing measurements without launching GPU work or enabling additional profiling.

Parameters:

stream – Text stream with a write method; defaults to stdout.

Returns:

Summary text without a trailing newline. Returns an empty string and writes nothing if no worker has a matvec timing record.

property gpu_ids: tuple

CUDA device IDs in worker order, returned as an immutable tuple.

property last_timing: list

Return one timing-dictionary copy per worker, in gpu_ids order.

Dictionaries are empty before the first successful matvec. wall, compute and exchange are in seconds; other fields follow TileGPUResidentHamiltonian.last_timing. Reading this property uses existing measurements and does not launch GPU work.

reset_cache() → None[source]

Clear cached GPU connection data on every worker.

The next matvec rebuilds the GPU caches it needs. Host-resident caches are retained.