diff --git a/README.md b/README.md index d59844a4..c52657a5 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,9 @@ [![Conda](https://img.shields.io/conda/v/gpytorch/linear_operator.svg)](https://anaconda.org/gpytorch/linear_operator) [![PyPI](https://img.shields.io/pypi/v/linear_operator.svg)](https://pypi.org/project/linear_operator) + + + LinearOperator is a PyTorch package for abstracting away the linear algebra routines needed for structured matrices (or operators). **This package is in beta.** @@ -21,6 +24,8 @@ Package development TODOs: - [ ] Add algebraic routines for generic rectangular operators - [ ] Add sparse operators + + To get started, run either ```sh pip install linear_operator @@ -29,6 +34,10 @@ conda install linear_operator -c gpytorch ``` or [see below](#installation) for more detailed instructions. + + + + ## Why LinearOperator Before describing what linear operators are and why they make a useful abstraction, it's easiest to see an example. Let's say you wanted to compute a matrix solve: @@ -122,7 +131,12 @@ A = LowRankRootLinearOperator(C) + DiagLinearOperator(d) # represents a 10M x 1 torch.linalg.solve(A, b) # computes A^{-1} b efficiently! ``` -### What is a Linear Operator? + + + + + +## What is a Linear Operator? A linear operator is a generalization of a matrix. It is a linear function that is defined in by its application to a vector. The most common linear operators are (potentially structured) matrices, @@ -170,7 +184,6 @@ torch.matmul(D, torch.tensor([4., 5., 6.]) # Returns [4., 10., 18.] ``` -#### Why is This Useful? While `_matmul`, `_size`, and `_transpose_nonbatch` might seem like a limited set of functions, it turns out that most functions on the `torch` and `torch.linalg` namespaces can be efficiently implemented using only these three primitative functions. @@ -181,8 +194,13 @@ This makes it possible to define very complex compositional structures that stil Finally, `LinearOperator` objects can be composed with one another, yielding new `LinearOperator` objects and automatically keeping track of algebraic structure after each computation. As a result, users never need to reason about what efficient linear algebra routines to use (so long as the input elements defined by the user encode known input structure). + See the [using LinearOperator objects](#using-linearoperator-objects) section for more details. + + + + ## Use Cases There are several use cases for the LinearOperator package. @@ -236,6 +254,10 @@ torch.linalg.solve(A, torch.randn(20000)) # Sub O(N^3) routine! ``` + + + + ## Using LinearOperator Objects LinearOperator objects share (mostly) the same API as `torch.Tensor` objects. @@ -330,6 +352,11 @@ This includes: See the documentation for a [full list of supported composition and decoration operations](https://linear-operator.readthedocs.io/en/latest/composition_decoration_operators.html). + + + + + ## Installation LinearOperator requires Python >= 3.8. @@ -357,6 +384,10 @@ To install what is currently on the `main` branch (potentially buggy and unstabl pip install --upgrade git+https://github.com/cornellius-gp/linear_operator.git ``` + + + + ### Development Installation If you are contributing a pull request, it is best to perform a manual installation: diff --git a/docs/requirements.txt b/docs/requirements.txt index 87b46de4..6c637ee5 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,4 @@ +myst-parser setuptools_scm sphinx sphinx_rtd_theme diff --git a/docs/source/about.rst b/docs/source/about.rst new file mode 100644 index 00000000..5b2e4f2c --- /dev/null +++ b/docs/source/about.rst @@ -0,0 +1,7 @@ +.. role:: hidden + :class: hidden-section + +.. include:: ../../README.md + :start-after: + :end-before: + :parser: myst_parser.sphinx_ diff --git a/docs/source/conf.py b/docs/source/conf.py index ceb649ae..eca368d6 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -44,6 +44,7 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + "myst_parser", # For adding sections of the README to the docs "sphinx.ext.intersphinx", "sphinx.ext.coverage", "sphinx.ext.mathjax", @@ -53,6 +54,12 @@ "sphinx_autodoc_typehints", ] +myst_enable_extensions = [ + "amsmath", # Ensure markdown math from README gets compiled into rst math + "dollarmath", # Ensure markdown math from README gets compiled into rst math + "tasklist", # Check boxes +] + # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] diff --git a/docs/source/converting.rst b/docs/source/converting.rst index fc4d512d..d4615d77 100644 --- a/docs/source/converting.rst +++ b/docs/source/converting.rst @@ -4,11 +4,6 @@ Converting Between LinearOperators and torch.Tensor ==================================================== -TODO - .. autofunction:: linear_operator.to_linear_operator .. autofunction:: linear_operator.to_dense - -.. autoclass:: linear_operator.operators.DenseLinearOperator - :members: diff --git a/docs/source/index.rst b/docs/source/index.rst index b82cb53f..b127d54a 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -5,16 +5,45 @@ :github_url: https://github.com/cornellius-gp/linear_operator -LinearOperator Documentation +LinearOperator =========================================== +.. include:: ../../README.md + :start-after: + :end-before: + :parser: myst_parser.sphinx_ + +Why LinearOperator +------------------ + +.. include:: ../../README.md + :start-after: + :end-before: + :parser: myst_parser.sphinx_ + +Use Cases +---------- + +.. include:: ../../README.md + :start-after: ## Use Cases + :end-before: ## Using LinearOperator Objects + :parser: myst_parser.sphinx_ + + +.. toctree:: + :maxdepth: 1 + :caption: Getting Started + + self + install + .. toctree:: :maxdepth: 1 :caption: Basic Concepts - intro + about + using converting - structure custom_linear_operators @@ -22,8 +51,6 @@ LinearOperator Documentation :maxdepth: 1 :caption: Core API - namespace - settings .. toctree:: @@ -33,12 +60,15 @@ LinearOperator Documentation linear_operator data_sparse_operators composition_decoration_operators + structure .. toctree:: :maxdepth: 1 :caption: Advanced Package Reference + settings + namespace utils diff --git a/docs/source/install.rst b/docs/source/install.rst new file mode 100644 index 00000000..b6347730 --- /dev/null +++ b/docs/source/install.rst @@ -0,0 +1,7 @@ +.. role:: hidden + :class: hidden-section + +.. include:: ../../README.md + :start-after: + :end-before: + :parser: myst_parser.sphinx_ diff --git a/docs/source/intro.rst b/docs/source/intro.rst deleted file mode 100644 index 227433fe..00000000 --- a/docs/source/intro.rst +++ /dev/null @@ -1,24 +0,0 @@ -.. role:: hidden - :class: hidden-section - -The LinearOperator Abstraction -=================================== - -A :obj:`~linear_operator.LinearOperator` is an object that represents a tensor -object, similar to :obj:`torch.tensor`, but typically differs in two ways: - -#. A tensor represented by a LinearOperator can typically be represented more - efficiently than storing a full matrix. For example, a LinearOperator - representing :math:`\mathbf A= \mathbf{XX}^{\top}` where :math:`\mathbf A` is :math:`N \times N` but - :math:`\mathbf X` is :math:`N \times D` might store :math:`\mathbf X` - instead of :math:`\mathbf A` directly. -#. A LinearOperator typically defines a matmul routine that performs - :math:`\mathbf {AM}` that is more efficient than storing the full matrix. - Using the above example, performing - :math:`\mathbf{AM}=\mathbf X(\mathbf X^{\top}\mathbf M)` requires only :math:`O(ND)` time, - rather than the :math:`O(N^2)` time required if we were storing :math:`\mathbf A` directly. - -.. note:: - LinearOperators are designed by default to optionally represent batches of matrices. Thus, the size of a - LinearOperator may be (for example) :math:`B_1 \times \ldots \times B_K \times N \times N`. Many of - the methods are designed to efficiently operate on these batches if present. diff --git a/docs/source/namespace.rst b/docs/source/namespace.rst index f299665d..de32a6f0 100644 --- a/docs/source/namespace.rst +++ b/docs/source/namespace.rst @@ -4,6 +4,9 @@ .. currentmodule:: linear_operator +Functions +============================== + LinearOperator objects are designed to work seamlessly with the torch API. For example: @@ -23,9 +26,6 @@ These functions are designed to work on :class:`~linear_operator.operators.Linea objects alike. -linear_operator ----------------- - .. automodule:: linear_operator .. autofunction:: add_diagonal diff --git a/docs/source/settings.rst b/docs/source/settings.rst index 581f3e27..f9d566ee 100644 --- a/docs/source/settings.rst +++ b/docs/source/settings.rst @@ -1,7 +1,7 @@ .. role:: hidden :class: hidden-section -linear_operator.settings +Settings =================================== .. currentmodule:: linear_operator.settings diff --git a/docs/source/structure.rst b/docs/source/structure.rst index 77ead49f..07e1de85 100644 --- a/docs/source/structure.rst +++ b/docs/source/structure.rst @@ -1,12 +1,8 @@ .. role:: hidden :class: hidden-section -Specifying LinearOperator Structure +Structured LinearOperators ==================================================== -TODO - .. autoclass:: linear_operator.operators.TriangularLinearOperator :members: - -TODO: symmetric, PSD diff --git a/docs/source/using.rst b/docs/source/using.rst new file mode 100644 index 00000000..0201f05a --- /dev/null +++ b/docs/source/using.rst @@ -0,0 +1,7 @@ +.. role:: hidden + :class: hidden-section + +.. include:: ../../README.md + :start-after: + :end-before: + :parser: myst_parser.sphinx_ diff --git a/docs/source/utils.rst b/docs/source/utils.rst index 208085ac..459cc756 100644 --- a/docs/source/utils.rst +++ b/docs/source/utils.rst @@ -1,28 +1,16 @@ .. role:: hidden :class: hidden-section -linear_operator.utils +Utilities =================================== .. currentmodule:: linear_operator.utils - -Utilities ----------------- - .. automodule:: linear_operator.utils :members: - -Lanczos Utilities -~~~~~~~~~~~~~~~~~ - .. automodule:: linear_operator.utils.lanczos :members: - -Sparse Utilities -~~~~~~~~~~~~~~~~~ - .. automodule:: linear_operator.utils.sparse :members: