pytorch/docs/source
Pearu Peterson 2ec779d46c PCA and SVD for low-rank matrices, LOBPCG for positive-defined generalized eigenvalue problem (#29488)
Summary:
This PR implements the following linear algebra algorithms for low-rank matrices:
- [x] Approximate `A` as `Q Q^H A` - using Algorithm 4.4 from [Halko et al, 2009](http://arxiv.org/abs/0909.4061).
  + exposed as `torch.lowrank.get_approximate_basis(A, q, niter=2, M=None) -> Q`
  + [x] dense matrices
  + [x] batches of dense matrices
  + [x] sparse matrices
  + [x] documentation
- [x] SVD - using Algorithm 5.1 from [Halko et al, 2009](http://arxiv.org/abs/0909.4061).
  + uses `torch.lowrank.get_approximate_basis`
  + exposed as `torch.svd_lowrank(A, q=6, niter=2, M=None) -> (U, S, V)`
  + [x] dense matrices
  + [x] batches of dense matrices
  + [x] sparse matrices
  + [x] documentation
- [x] PCA - using `torch.svd_lowrank`
  + uses `torch.svd_lowrank`
  + exposed as `torch.pca_lowrank(A, center=True, q=None, niter=2) -> (U, S, V)`
  + [x] dense matrices
  + [x] batches of dense matrices
  + [x] sparse matrices, uses non-centered sparse matrix algorithm
  + [x] documentation
- [x] generalized eigenvalue solver using the original LOBPCG algorithm [Knyazev, 2001](https://epubs.siam.org/doi/abs/10.1137/S1064827500366124)
  + exposed as `torch.lobpcg(A, B=None, k=1, method="basic", ...)`
  + [x] dense matrices
  + [x] batches of dense matrices
  + [x] sparse matrices
  + [x] documentation
- [x] generalized eigenvalue solver using robust LOBPCG with orthogonal basis selection [Stathopoulos, 2002](https://epubs.siam.org/doi/10.1137/S1064827500370883)
  + exposed as `torch.lobpcg(A, B=None, k=1, method="ortho", ...)`
  + [x] dense matrices
  + [x] batches of dense matrices
  + [x] sparse matrices
  + [x] documentation
- [x] generalized eigenvalue solver using the robust and efficient LOBPCG Algorithm 8 from [Duersch et al, 2018](https://epubs.siam.org/doi/abs/10.1137/17M1129830) that switches to orthogonal basis selection automatically
  + the "ortho" method improves iterations so rapidly that in the current test cases it does not make sense to use the basic iterations at all. If users will have matrices for which basic iterations could improve convergence then the `tracker` argument allows breaking the iteration process at user choice so that the user can switch to the orthogonal basis selection if needed. In conclusion, there is no need to implement Algorithm 8 at this point.
- [x] benchmarks
  + [x] `torch.svd` vs `torch.svd_lowrank`, see notebook [Low-rank SVD](https://github.com/Quansight/pearu-sandbox/blob/master/pytorch/Low-rank%20SVD.ipynb). In conclusion, the low-rank SVD is going to be useful only for large sparse matrices where the full-rank SVD will fail due to memory limitations.
  + [x] `torch.lobpcg` vs `scipy.sparse.linalg.lobpcg`, see notebook [LOBPCG - pytorch vs scipy](https://github.com/Quansight/pearu-sandbox/blob/master/pytorch/LOBPCG%20-%20pytorch%20vs%20scipy.ipynb). In conculsion, both implementations give the same results (up to numerical errors from different methods), scipy lobpcg implementation is generally faster.
  + [x] On very small tolerance cases, `torch.lobpcg` is more robust than `scipy.sparse.linalg.lobpcg` (see `test_lobpcg_scipy` results)

Resolves https://github.com/pytorch/pytorch/issues/8049.
Pull Request resolved: https://github.com/pytorch/pytorch/pull/29488

Differential Revision: D20193196

Pulled By: vincentqb

fbshipit-source-id: 78a4879912424595e6ea95a95e483a37487a907e
2020-03-11 07:33:49 -07:00
..
_static Improve documentation around builtin functions (#30347) 2019-12-04 13:50:40 -08:00
_templates Generate sphinx docs with secure content. (#18508) 2019-03-27 11:01:48 -07:00
_templates-stable Add layout.html to template for stable docs (#33770) 2020-03-04 03:14:52 -08:00
community Fix broken links in governance.rst 2020-02-04 14:26:09 -08:00
notes Enhance reproducibility documentation (#33795) 2020-03-06 15:32:04 -08:00
org/pytorch Revert D19320493: Javadoc changes 2020-01-09 14:23:30 -08:00
scripts Add torch.nn.GELU for GELU activation (#28944) 2019-11-03 21:55:05 -08:00
__config__.rst Allow a non-OpenMP based build (#19749) 2019-05-06 19:34:48 -07:00
amp.rst [WIP] Reanimate gradient scaling API with original scale update heuristic (#33366) 2020-02-25 19:00:34 -08:00
autograd.rst Added docs for context method mixins. Fixes issue #27365 (#28643) 2019-10-28 08:31:35 -07:00
bottleneck.rst [docs] Clarify more CUDA profiling gotchas in bottleneck docs (#6763) 2018-04-19 13:15:27 -04:00
checkpoint.rst Stashing checkpointing RNG states based on devices of arg tensors (#14518) 2018-12-11 09:48:45 -08:00
conf.py Revert D19320493: Javadoc changes 2020-01-09 14:23:30 -08:00
cpp_extension.rst Inline JIT C++ Extensions (#7059) 2018-04-30 11:48:44 -04:00
cuda_deterministic_backward.rst Typo correction in cuda_deterministic_backward.rst (#25011) 2019-08-22 21:19:39 -07:00
cuda_deterministic.rst Amend nondeterminism notes (#12217) 2018-10-16 23:59:26 -07:00
cuda.rst Fix most documentation warnings (#27782) 2019-10-13 10:34:01 -07:00
cudnn_deterministic.rst Amend nondeterminism notes (#12217) 2018-10-16 23:59:26 -07:00
cudnn_persistent_rnn.rst don't copy weight gradients in rnn (#12600) 2018-10-12 13:34:10 -07:00
data.rst Fix typo in data.rst docs 2019-12-18 09:52:10 -08:00
distributed.rst Fix typos (#30606) 2019-12-02 20:17:42 -08:00
distributions.rst Feature/vonmises upstream (#33418) 2020-02-26 08:19:12 -08:00
dlpack.rst document torch.utils.dlpack (#9343) 2018-07-11 07:46:09 -07:00
hub.rst Fix typos, via a Levenshtein-type corrector (#31523) 2020-01-17 16:03:19 -08:00
index.rst Add list of view ops to public doc. (#32560) 2020-02-28 15:05:55 -08:00
jit_builtin_functions.rst Fix builtin function reference (#24056) 2019-08-09 15:58:15 -07:00
jit_language_reference.rst [docs] add experimental warning to TorchScript classes in language reference (#33697) 2020-02-24 14:01:19 -08:00
jit_python_reference.rst Add Python language reference docs (#30686) 2019-12-26 13:21:36 -08:00
jit_unsupported.rst [JIT] add support for torch.norm (#33783) 2020-03-05 14:46:24 -08:00
jit.rst Fix typos, via a Levenshtein-type corrector (#31523) 2020-01-17 16:03:19 -08:00
math-quantizer-equation.png adding quantization.rst file for quantization feature (#27559) 2019-10-09 16:45:09 -07:00
model_zoo.rst add/move a few apis in torch.hub (#18758) 2019-04-10 23:10:39 -07:00
multiprocessing.rst Bag of documentation fixes; fix more sphinx warnings (#27850) 2019-10-15 07:31:14 -07:00
name_inference.rst Fix typos (#30606) 2019-12-02 20:17:42 -08:00
named_tensor.rst Bag of documentation fixes; fix more sphinx warnings (#27850) 2019-10-15 07:31:14 -07:00
nn.functional.rst Breaks up NN module in docs so it loads faster. 2019-06-11 09:38:41 -07:00
nn.init.rst Bag of documentation fixes; fix more sphinx warnings (#27850) 2019-10-15 07:31:14 -07:00
nn.rst Pruning Functionality (#24076) 2019-11-08 19:38:00 -08:00
onnx.rst Adds true_divide function, analogous to Python 's, JAX's, NumPy's (true) division (#34236) 2020-03-09 21:06:33 -07:00
optim.rst Fix capitalization inconsistency in optim.rst 2019-12-04 08:17:03 -08:00
packages.rst Revert D19320493: Javadoc changes 2020-01-09 14:23:30 -08:00
quantization.rst Fixed typos in quantization docs / docstrings (#34182) 2020-03-06 21:53:52 -08:00
random.rst Fix most documentation warnings (#27782) 2019-10-13 10:34:01 -07:00
rpc.rst Use double quotes in C++ to stay consistent with Python RPC docs (#34095) 2020-03-03 16:44:30 -08:00
sparse.rst Bag of documentation fixes; fix more sphinx warnings (#27850) 2019-10-15 07:31:14 -07:00
storage.rst
tensor_attributes.rst Expose a torch.result_type and simplify tensor iterator 2019-09-25 06:52:23 -07:00
tensor_view.rst Add list of view ops to public doc. (#32560) 2020-02-28 15:05:55 -08:00
tensorboard.rst Add method add_hparams to API doc (#27344) 2019-10-03 17:07:45 -07:00
tensors.rst Add list of view ops to public doc. (#32560) 2020-02-28 15:05:55 -08:00
torch.rst PCA and SVD for low-rank matrices, LOBPCG for positive-defined generalized eigenvalue problem (#29488) 2020-03-11 07:33:49 -07:00
type_info.rst Allow converting char tensor to numpy; add [fi]info.min (#15046) 2018-12-24 09:11:24 -08:00