torch.lobpcg(A: torch.Tensor, k: Optional[int] = None, B: Optional[torch.Tensor] = None, X: Optional[torch.Tensor] = None, n: Optional[int] = None, iK: Optional[torch.Tensor] = None, niter: Optional[int] = None, tol: Optional[float] = None, largest: Optional[bool] = None, method: Optional[str] = None, tracker: None = None, ortho_iparams: Optional[Dict[str, int]] = None, ortho_fparams: Optional[Dict[str, float]] = None, ortho_bparams: Optional[Dict[str, bool]] = None) → Tuple[torch.Tensor, torch.Tensor][source]

Find the k largest (or smallest) eigenvalues and the corresponding eigenvectors of a symmetric positive defined generalized eigenvalue problem using matrix-free LOBPCG methods.

This function is a front-end to the following LOBPCG algorithms selectable via method argument:

method=”basic” - the LOBPCG method introduced by Andrew Knyazev, see [Knyazev2001]. A less robust method, may fail when Cholesky is applied to singular input.

method=”ortho” - the LOBPCG method with orthogonal basis selection [StathopoulosEtal2002]. A robust method.

Supported inputs are dense, sparse, and batches of dense matrices.


In general, the basic method spends least time per iteration. However, the robust methods converge much faster and are more stable. So, the usage of the basic method is generally not recommended but there exist cases where the usage of the basic method may be preferred.

  • A (Tensor) – the input tensor of size (,m,m)(*, m, m)

  • B (Tensor, optional) – the input tensor of size (,m,m)(*, m, m) . When not specified, B is interpereted as identity matrix.

  • X (tensor, optional) – the input tensor of size (,m,n)(*, m, n) where k <= n <= m. When specified, it is used as initial approximation of eigenvectors. X must be a dense tensor.

  • iK (tensor, optional) – the input tensor of size (,m,m)(*, m, m) . When specified, it will be used as preconditioner.

  • k (integer, optional) – the number of requested eigenpairs. Default is the number of XX columns (when specified) or 1.

  • n (integer, optional) – if XX is not specified then n specifies the size of the generated random approximation of eigenvectors. Default value for n is k. If XX is specifed, the value of n (when specified) must be the number of XX columns.

  • tol (float, optional) – residual tolerance for stopping criterion. Default is feps ** 0.5 where feps is smallest non-zero floating-point number of the given input tensor A data type.

  • largest (bool, optional) – when True, solve the eigenproblem for the largest eigenvalues. Otherwise, solve the eigenproblem for smallest eigenvalues. Default is True.

  • method (str, optional) – select LOBPCG method. See the description of the function above. Default is “ortho”.

  • niter (int, optional) – maximum number of iterations. When reached, the iteration process is hard-stopped and the current approximation of eigenpairs is returned. For infinite iteration but until convergence criteria is met, use -1.

  • tracker (callable, optional) –

    a function for tracing the iteration process. When specified, it is called at each iteration step with LOBPCG instance as an argument. The LOBPCG instance holds the full state of the iteration process in the following attributes:

    iparams, fparams, bparams - dictionaries of integer, float, and boolean valued input parameters, respectively

    ivars, fvars, bvars, tvars - dictionaries of integer, float, boolean, and Tensor valued iteration variables, respectively.

    A, B, iK - input Tensor arguments.

    E, X, S, R - iteration Tensor variables.

    For instance:

    ivars[“istep”] - the current iteration step X - the current approximation of eigenvectors E - the current approximation of eigenvalues R - the current residual ivars[“converged_count”] - the current number of converged eigenpairs tvars[“rerr”] - the current state of convergence criteria

    Note that when tracker stores Tensor objects from the LOBPCG instance, it must make copies of these.

    If tracker sets bvars[“force_stop”] = True, the iteration process will be hard-stopped.

  • ortho_fparams, ortho_bparams (ortho_iparams,) – various parameters to LOBPCG algorithm when using method=”ortho”.


tensor of eigenvalues of size (,k)(*, k)

X (Tensor): tensor of eigenvectors of size (,m,k)(*, m, k)

Return type

E (Tensor)


[Knyazev2001] Andrew V. Knyazev. (2001) Toward the Optimal Preconditioned Eigensolver: Locally Optimal Block Preconditioned Conjugate Gradient Method. SIAM J. Sci. Comput., 23(2), 517-541. (25 pages)

[StathopoulosEtal2002] Andreas Stathopoulos and Kesheng Wu. (2002) A Block Orthogonalization Procedure with Constant Synchronization Requirements. SIAM J. Sci. Comput., 23(6), 2165-2182. (18 pages)

[DuerschEtal2018] Jed A. Duersch, Meiyue Shao, Chao Yang, Ming Gu. (2018) A Robust and Efficient Implementation of LOBPCG. SIAM J. Sci. Comput., 40(5), C655-C676. (22 pages)


Access comprehensive developer documentation for PyTorch

View Docs


Get in-depth tutorials for beginners and advanced developers

View Tutorials


Find development resources and get your questions answered

View Resources