fulqrum.gpu.distributed_primme_eigsh

distributed_primme_eigsh(H, k: int, tol: float = 0.001, maxiter: int | None = None, ncv: int | None = None, which: str = 'SA', method: str = 'PRIMME_GD_Olsen_plusK', conv: str = 'abs', precond_diag_local: ndarray | None = None, v0_local: ndarray | None = None, return_eigenvectors: bool = True, return_stats: bool = False, return_unconverged: bool = False, maxBlockSize: int | None = None, minRestartSize: int | None = None, maxPrevRetain: int | None = None, printLevel: int = 0, monitor=None, gpu: bool | str = 'auto', initBasisMode: str | None = None, energy_tol: float = 1e-06, energy_window: int = 3, resnorm_cap: float = 0.01)[source]

Compute eigenpairs of a distributed real Hermitian operator with PRIMME.

For a GPU-backed H, eigensolving combines GPU matrix-vector products with PRIMME linear algebra steps, such as basis orthogonalization and dense operations. gpu=False runs the linear-algebra steps on the host; gpu=True runs the steps on GPUs. Matrix-vector products stay on the GPUs in both modes. Returned eigenvalues and eigenvectors are host NumPy arrays.

Convergence uses the Ritz value theta and residual norm r:

  • "abs": require r < tol.

  • "rel": require r <= tol * max(abs(theta), 4e-11).

  • "norm": use PRIMME’s operator-norm-scaled convergence test.

  • "energy": accept the relative residual test or stability of the tracked Ritz value within energy_tol, subject to resnorm_cap. Energy-based stopping can accept a residual larger than tol.

Parameters:

  • H – Distributed real Hermitian operator.

  • k – Positive number of eigenpairs to request.

  • tol – Convergence tolerance interpreted by conv; defaults to 1e-3.

  • maxiter – Maximum matrix-vector products, passed to PRIMME’s maxMatvecs. None keeps PRIMME’s default limit.

  • ncv – Maximum number of basis vectors. None lets PRIMME choose.

  • which – "SA" for smallest algebraic values (default), "LA" for largest algebraic, "SM" for smallest magnitude or "LM" for largest magnitude.

  • method – PRIMME preset name; defaults to "PRIMME_GD_Olsen_plusK".

  • conv – "abs" (default), "rel", "norm" or "energy".

  • precond_diag_local – Optional real host diagonal of shape (H.n_local,) in the operator’s local row order, for a shifted Jacobi preconditioner. None disables this preconditioner; H.diag_local can supply it.

  • v0_local – Optional real host starting vector, shape (H.n_local,), or block, shape (H.n_local, m). Converted to Fortran-order float64; at most k columns are used. None supplies no starting vectors.

  • return_eigenvectors – Include local eigenvectors; defaults to True.

  • return_stats – Include a statistics dictionary; defaults to False.

  • return_unconverged – Allow PRIMME status -3, including non-convergence, and expose its current result buffers; defaults to False. Buffers retain k entries and are not filtered to converged eigenpairs. Other PRIMME failures still raise.

  • maxBlockSize – Optional maximum PRIMME block size.

  • minRestartSize – Optional number of basis vectors retained at restart.

  • maxPrevRetain – Optional maximum number of previous search directions retained. These three options preserve preset defaults when None.

  • printLevel – PRIMME verbosity level; defaults to 0.

  • monitor – Optional monitor(ritz_value, residual_norm) callback during convergence checks for abs, rel and energy. It is unused for norm; defaults to None.

  • gpu – Placement of PRIMME’s linear-algebra steps: True for GPU, False for host. With a GPU-backed H, matvecs run on GPUs in both modes. "auto" (default) chooses GPU when the native extension and operator advertise device support. GPU mode requires CuPy.

  • initBasisMode – Optional PRIMME initialization constant name. None keeps the preset’s initialization mode.

  • energy_tol – Ritz-value stability tolerance for energy stopping; defaults to 1e-6.

  • energy_window – Number of previous distinct matrix-vector-count samples compared with the current Ritz value; defaults to 3.

  • resnorm_cap – Residual upper bound for the energy-stability criterion; defaults to 1e-2. These energy options must be positive, with energy_window >= 1, when conv="energy".

Returns:

By default, (evals, evecs_local). evals is a float64 array of shape (k,), identical on all solver ranks. evecs_local is a host float64 array of shape (H.n_local, k) containing this rank’s rows; column j belongs to eigenvalue j. Eigenvectors remain distributed rather than being gathered into a global array. Global norms and residuals require contributions from all ranks.

With eigenvectors disabled, returns evals. With statistics enabled, returns (evals, evecs_local, stats) or (evals, stats). stats includes PRIMME counts/timings, residual norms in rnorms, convergence details and gpu_eigsh. Rank-local timings or memory fields may differ. When unconverged returns are allowed, these shapes remain unchanged; the contents are not guaranteed to be converged eigenpairs.

Raises:

  • TypeError – The operator lacks the required local-vector interface.

  • ValueError – Dimensions, local input shapes, target, convergence mode, GPU selection or a PRIMME option are invalid.

  • ImportError – The native PRIMME extension or a required Python dependency is unavailable.

  • RuntimeError – PRIMME fails, cannot use the requested backend, or does not converge and unconverged returns are disabled.

Multi-rank GPU matvec/preconditioner callback failures abort the MPI job to prevent peers from waiting indefinitely in collective operations.