fulqrum.gpu.full_strs.FullStrsGPUHamiltonian

class FullStrsGPUHamiltonian(operator, keys, *, comm=None, engine='auto', _options=None)[source]

GPU-backed real type-2 Hamiltonian on an explicit set of full determinants.

Use with distributed_primme_eigsh to solve eigenvalue problems on one or more ranks. Full determinants must use block spin ordering, with alpha in the low bits and beta in the high bits, equal sector widths of 1–128 orbitals, fixed sector electron counts and supported spin-conserving terms. Unsupported operator groups are rejected.

keys is a uint64 array of shape (n, 2W). W is 1 for up to 64 orbitals per spin sector and 2 for 65 to 128. Each key holds the W alpha words, then the W beta words, low word first. Bit k of word w is set when orbital 64w + k is occupied. The determinants need not form a complete tensor-product subspace.

The keys can be unsorted and can contain duplicates. The constructor removes duplicates, sorts the keys and distributes them for the selected layout. After construction, keys holds this rank’s keys in their final order, n_local is the number of determinants this rank owns, and row_start is the global index of its first determinant. Local vectors and diag_local use the same order: entry i belongs to keys[i].

Parameters:

  • operator – Real type-2 QubitOperator in the block layout above.

  • keys – This rank’s input determinants, uint64 shape (n, 2W). Input assignment and order may change during construction.

  • comm – MPI or LocalComm communicator for all participating ranks. None uses MPI.COMM_SELF.

  • engine – "auto" (default), "tile" or "general". "tile" uses the faster TileGPUResidentHamiltonian and needs a Cartesian-product subspace: the keys must hold every alpha string paired with every beta string. "general" works for any set of keys. "auto" uses "tile" when it can, and "general" otherwise. "tile" raises an error when it cannot run. The engine attribute shows the engine in use. Both engines use the same key order. For only a few matvecs, use "general": the tile engine can take longer to build at high orbital counts.

Raises:

  • ValueError – Keys, operator terms or the engine are unsupported.

  • ImportError – CuPy or required native components are unavailable.

  • MemoryError – GPU allocations cannot fit in available device memory.

  • RuntimeError – Device or communication setup fails.

Methods

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

Collectively compute RDMs from this rank's NumPy or CuPy state slice, shape (n_local,) in keys order.

matvec(x)

Collectively apply the operator to this rank's local vector of shape (n_local,) in keys order.

Attributes

device_bytes

The device memory of the stored groups, tables, keys, diagonal and matvec buffers, in bytes.

keys

Return this rank's post-distribution keys as a uint64 (n_local, 2W) copy, alpha words then beta words, sorted by (beta, alpha).

num_halo

The number of remote rows that this rank reads (0 with one rank).

num_orbitals

The number of orbitals per spin sector.

num_streamed_slices

The number of key slices streamed from host memory at every matvec.
compute_rdms(x, *, rank=1, spin_summed=False)[source]

Collectively compute RDMs from this rank’s NumPy or CuPy state slice, shape (n_local,) in keys order. Every rank receives full host NumPy arrays after device work and collectives complete; rank selects the RDM order (1 or 2), and no normalization is applied. Spin blocks, spin-summed forms, and conventions follow PySCF make_rdm12s(reorder=True).

property device_bytes

The device memory of the stored groups, tables, keys, diagonal and matvec buffers, in bytes.

property keys

Return this rank’s post-distribution keys as a uint64 (n_local, 2W) copy, alpha words then beta words, sorted by (beta, alpha).

matvec(x)[source]

Collectively apply the operator to this rank’s local vector of shape (n_local,) in keys order. NumPy input returns NumPy output; CuPy input returns CuPy output.

property num_halo

The number of remote rows that this rank reads (0 with one rank).

property num_orbitals

The number of orbitals per spin sector.

property num_streamed_slices

The number of key slices streamed from host memory at every matvec.