fulqrum.gpu.DistributedMPIGPUHamiltonian

DistributedMPIGPUHamiltonian(hsub, layout: str = 'tile_resident', **kwargs)[source]

Wrapper for distributed GPU-backed real type-2 Hamiltonian implementations.

Supports one implementation, TileGPUResidentHamiltonian (layout="tile_resident") currently. Returns a TileGPUResidentHamiltonian using the alpha and beta strings stored in hsub. Use the returned operator with distributed_primme_eigsh for distributed eigensolving.

The subspace must be fq.Subspace([alpha_strs, beta_strs]), a tensor product, subspace with alpha in the low qubits and beta in the high qubits. Each spin-sector supports 1–128 orbitals and must have a fixed electron count. Use at least two occupied orbitals per half string; smaller occupations are outside verified GPU support and may give incorrect results. Operator groups must pass the GPU compatibility checks.

Parameters:

  • hsub – Real type-2 SubspaceHamiltonian on the half-string product.

  • layout – Must be "tile_resident" (default).

  • **kwargs – Optional constructor settings listed below. Other keyword names raise TypeError. Sector strings are supplied from hsub.

Keyword Arguments:

  • gpu_ids – One-element sequence selecting this rank’s CUDA device; defaults to (0,). Exactly one device is required per rank.

  • comm – MPI communicator; defaults to MPI.COMM_WORLD. LocalComm can instead coordinate in-process workers.

  • process_grid – (p_alpha, p_beta), whose product must equal communicator size. None chooses a grid automatically.

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

  • comm_backend – "auto" (default), "nccl", "host_mpi", "cuda_mpi" or "inproc". For MPI, auto first consults FQ_DIST_BACKEND. If that is also auto, multiple ranks use NCCL when every rank supports it and uses a distinct GPU; otherwise host MPI is selected. CUDA-aware MPI must be requested explicitly. LocalComm uses inproc. Failed NCCL initialization raises rather than retrying with host MPI.

  • intra_node_size – Optional positive number of contiguous ranks per communication domain. None uses detected node membership.

  • build_threads – CPU threads for tile construction. Zero uses OMP_NUM_THREADS; a positive FQ_BUILD_THREADS overrides this argument. Defaults to 0.

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

Returns:

A TileGPUResidentHamiltonian with global square shape, float64 dtype and local length n_local. Local vectors use beta-outer, alpha-inner order within this rank’s tile; see the class for the local-vector protocol.

Raises:

  • ValueError – The layout is unsupported, the subspace is not a half-string product, or a forwarded constructor option is invalid.

  • TypeError – An unrecognized keyword option is supplied.

Additional constructor errors follow TileGPUResidentHamiltonian.