Fix docs

guanhuaw · Jun 6, 2022 · 42e8020 · 42e8020
1 parent f82bb1c
commit 42e8020
Show file tree

Hide file tree

Showing 56 changed files with 1,809 additions and 881 deletions.
diff --git a/.readthedics.yaml → .readthedocs.yaml b/.readthedics.yaml → .readthedocs.yaml
diff --git a/README.md b/README.md
@@ -7,16 +7,20 @@ A Py***Torch***-based differentiable ***I***mage ***R***econstruction ***T***ool
 
 The work is inspired by [MIRT](https://github.com/JeffFessler/mirt), a well-acclaimed toolbox for medical imaging reconstruction. 
 
-The overarching goal is to provide fast iterative and data-driven image reconstruction across CPUs and GPUs. Researchers can rapidly develop new model-based and learning-based methods (i.e., unrolled neural networks) with its convenient abstraction layers. With the full support of auto-differentiation, one may optimize imaging protocols and image reconstruction parameters with gradient methods.
+The overarching goal is to provide fast iterative and data-driven image reconstruction across CPUs and GPUs. Researchers can rapidly develop new model-based and learning-based methods (i.e., unrolled neural networks) with convenient abstraction layers. With the full support of auto-differentiation, one may optimize imaging protocols and image reconstruction parameters with gradient methods.
 
 Documentation: https://mirtorch.readthedocs.io/en/latest/
 
+------
+
 ### Installation
 
 We recommend to [pre-install `PyTorch` first](https://pytorch.org/).
-To install the `MIRTorch` package, after cloning the repo, please try `pip install -e .` 
+To install the `MIRTorch` package, after cloning the repo, please try `python setup.py install`. 
+
+`requirements.txt` details the package dependencies. We recommend installing [pytorch_wavelets](https://github.com/fbcotter/pytorch_wavelets) directly from the source code instead of `pip`. 
 
-`requirements.txt` details the package dependencies. We recommend to install [pytorch_wavelets](https://github.com/fbcotter/pytorch_wavelets) directly from the source code instead of `pip`. 
+------
 
 ### Features
 
@@ -26,29 +30,37 @@ The `LinearMap` class overloads common matrix operations, such as `+, - , *`.
 
 Instances include basic linear operations (like convolution), classical imaging processing, and MRI system matrix (Cartesian and Non-Cartesian, sensitivity- and B0-informed system models). More is on the way...
 
-Since the Jacobian matrix of a linear operator is itself, the toolbox may actively calculate such Jacobians during backpropagation, avoiding the large cache cost required by auto-differentiation.
+Since the Jacobian matrix of a linear operator is itself, the toolbox can actively calculate such Jacobians during backpropagation, avoiding the large cache cost required by auto-differentiation.
 
 #### Proximal operators
 
 The toolbox contains common proximal operators such as soft thresholding. These operators also support the regularizers that involve multiplication with diagonal or unitary matrices, such as orthogonal wavelets.
 
-#### Iterative reconstruction (IR) algorithms
+#### Iterative reconstruction (MBIR) algorithms
 
 Currently, the package includes the conjugate gradient (CG), fast iterative thresholding (FISTA), optimized gradient method (POGM), forward-backward primal-dual (FBPD) algorithms for image reconstruction.
 
 #### Dictionary learning
 
 For dictionary learning-based reconstruction, we implemented an efficient dictionary learning algorithm ([SOUP-DIL](https://arxiv.org/abs/1511.06333)) and orthogonal matching pursuit ([OMP](https://ieeexplore.ieee.org/abstract/document/342465/?casa_token=aTDkQVCM9WEAAAAA:5rXu9YikP822bCBvkhYxKWlBTJ6Fn6baTQJ9kuNrU7K-64EmGOAczYvF2dTW3al3PfPdwJAiYw)). Due to PyTorch’s limited support of sparse matrices, we use SciPy as the backend. 
 
-### Basic usage
+------
+
+### Usage and examples
+
+`/example` includes several examples. 
+
+`/example/demo_mnist.ipynb` shows the LASSO on MNIST with FISTA and POGM. 
 
-#### MRI reconstruction: 
+`/example/demo_mri.ipynb` contains the SENSE (CG-SENSE) and **B0**-informed reconstruction with penalized weighted least squares (*PWLS*).
 
-`/example` includes SENSE (CG-SENSE), Non-Cartesian SENSE, and **B0**-informed reconstruction with penalized weighted least squares (*PWLS*), compressed sensing (CS), and dictionary learning (DL) methods.
+`/example/demo_cs.ipynb` shows the compressed sensing reconstruction of under-determined MRI signals.
 
-#### MRI sampling pattern optimization:
+`/example/demo_dl.ipynb` exhibits the dictionary learning results.
 
-`/example/demo_mri_traj.ipynb` contains MRI sampling pattern optimization examples. One may use the reconstruction loss as objective function to jointly optimize reconstruction algorithms and the sampling pattern.
+[Bjork repo](https://github.com/guanhuaw/Bjork) contains MRI sampling pattern optimization examples. One may use the reconstruction loss as the objective function to jointly optimize reconstruction algorithms and the sampling pattern.
+
+------
 
 ### Acknowledgments
 
@@ -60,6 +72,20 @@ MIRT/MIRT.jl: https://web.eecs.umich.edu/~fessler/code/index.html
 
 PyLops: https://github.com/PyLops/pylops
 
+If the code is useful to your research, please cite:
+
+```bibtex
+@article{wang:22:bjork,
+ author={Wang, Guanhua and Luo, Tianrui and Nielsen, Jon-Fredrik and Noll, Douglas C. and Fessler, Jeffrey A.},
+ journal={IEEE Transactions on Medical Imaging}, 
+ title={B-spline Parameterized Joint Optimization of Reconstruction and K-space Trajectories (BJORK) for Accelerated 2D MRI}, 
+ year={2022},
+ pages={1-1},
+ doi={10.1109/TMI.2022.3161875}}
+```
+
+------
+
 ### License
 
 This package uses the BSD3 license. 
diff --git a/docs/API.rst b/docs/API.rst
@@ -2,3 +2,14 @@
 API
 ====================
 
+.. toctree::
+ :maxdepth: 2
+ :caption: API Documentation
+
+ LinearMap
+ Prox
+ Algorithms
+ DL
+
+
+
diff --git a/docs/Algorithms.rst b/docs/Algorithms.rst
@@ -0,0 +1,14 @@
+Iterative algorithms
+====================
+
+
+
+.. autosummary::
+ :toctree: generated
+ :nosignatures:
+
+ mirtorch.alg.CG
+ mirtorch.alg.POGM
+ mirtorch.alg.FBPD
+ mirtorch.alg.FISTA
+ mirtorch.alg.power_iter
diff --git a/docs/DL.rst b/docs/DL.rst
@@ -0,0 +1,14 @@
+Dictionary Learning
+===================
+
+Dictionary learning methods
+---------------------------
+
+.. autosummary::
+ :toctree: generated
+ :nosignatures:
+
+ mirtorch.dic.soup
+
+
+
diff --git a/docs/HISTORY.md b/docs/HISTORY.md
@@ -1,4 +1,8 @@
 # History
+0.0.2 (2022-06-05)
+---
+- Update the docs
+- Fix the B0-informed system matrix
 
 0.0.1 (2022-02-04)
 ---

diff --git a/docs/LinearMap.rst b/docs/LinearMap.rst
@@ -0,0 +1,39 @@
+Linear Operators
+================
+
+MRI system models
+-----------------
+.. autosummary::
+ :toctree: generated
+ :nosignatures:
+
+ mirtorch.linear.mri.FFTCn
+ mirtorch.linear.mri.NuSense
+ mirtorch.linear.mri.Sense
+ mirtorch.linear.mri.NuSenseFrame
+ mirtorch.linear.mri.Gmri
+
+
+Basic image processing operations
+---------------------------------
+
+.. autosummary::
+ :toctree: generated
+ :nosignatures:
+
+ mirtorch.linear.basics.Diffnd
+ mirtorch.linear.basics.Diff2dframe
+ mirtorch.linear.basics.Diff3dframe
+ mirtorch.linear.basics.Diag
+ mirtorch.linear.basics.Identity
+ mirtorch.linear.basics.Convolve1d
+ mirtorch.linear.basics.Convolve2d
+ mirtorch.linear.basics.Convolve3d
+ mirtorch.linear.basics.Patch2D
+ mirtorch.linear.basics.Patch3D
+ mirtorch.linear.wavelets.Wavelet2D
+
+
+
+
+
diff --git a/docs/Prox.rst b/docs/Prox.rst
@@ -0,0 +1,17 @@
+Proximal Operators
+==================
+
+
+Proximal operator instances
+---------------------------
+.. autosummary::
+ :toctree: generated
+ :nosignatures:
+
+ mirtorch.prox.L2Regularizer
+ mirtorch.prox.L1Regularizer
+ mirtorch.prox.SquaredL2Regularizer
+ mirtorch.prox.Conj
+ mirtorch.prox.Const
+ mirtorch.prox.BoxConstraint
+ mirtorch.prox.L0Regularizer
diff --git a/docs/README.md b/docs/README.md
@@ -1,4 +1,4 @@
-# Intro
+# MIRTorch
 
 ![GitHub release (latest by date including pre-releases)](https://img.shields.io/github/v/release/guanhuaw/mirtorch?include_prereleases)
 ![Read the Docs](https://img.shields.io/readthedocs/mirtorch)
@@ -7,48 +7,60 @@ A Py***Torch***-based differentiable ***I***mage ***R***econstruction ***T***ool
 
 The work is inspired by [MIRT](https://github.com/JeffFessler/mirt), a well-acclaimed toolbox for medical imaging reconstruction. 
 
-The overarching goal is to provide fast iterative and data-driven image reconstruction across CPUs and GPUs. Researchers can rapidly develop new model-based and learning-based methods (i.e., unrolled neural networks) with its convenient abstraction layers. With the full support of auto-differentiation, one may optimize imaging protocols and image reconstruction parameters with gradient methods.
+The overarching goal is to provide fast iterative and data-driven image reconstruction across CPUs and GPUs. Researchers can rapidly develop new model-based and learning-based methods (i.e., unrolled neural networks) with convenient abstraction layers. With the full support of auto-differentiation, one may optimize imaging protocols and image reconstruction parameters with gradient methods.
 
-Documentation: https://readthedocs.org/projects/mirtorch/
+Documentation: https://mirtorch.readthedocs.io/en/latest/
+
+------
 
 ### Installation
 
-We recommend to pre-install `PyTorch` first.
-To install the `MIRTorch` package, after cloning the repo, please try `pip install -e .` 
+We recommend to [pre-install `PyTorch` first](https://pytorch.org/).
+To install the `MIRTorch` package, after cloning the repo, please try `python setup.py install`. 
+
+`requirements.txt` details the package dependencies. We recommend installing [pytorch_wavelets](https://github.com/fbcotter/pytorch_wavelets) directly from the source code instead of `pip`. 
 
-`requirements.txt` details the package dependencies. 
+------
 
 ### Features
 
 #### Linear maps
 
-The `LinearMap` class overloads common matrix operations, such as `+, - , *`. It also supports an efficient backpropagation.
+The `LinearMap` class overloads common matrix operations, such as `+, - , *`.
 
-Instances include basic linear operations (like con\volution), classical imaging processing, and MRI system matrix (Cartesian and Non-Cartesian, sensitivity- and B0-informed system models). More is on the way...
+Instances include basic linear operations (like convolution), classical imaging processing, and MRI system matrix (Cartesian and Non-Cartesian, sensitivity- and B0-informed system models). More is on the way...
 
-Since the Jacobian matrix of a linear operator is itself, the toolbox may actively calculate such Jacobians during backpropagation, avoiding the large cache cost required by auto-differentiation.
+Since the Jacobian matrix of a linear operator is itself, the toolbox can actively calculate such Jacobians during backpropagation, avoiding the large cache cost required by auto-differentiation.
 
 #### Proximal operators
 
 The toolbox contains common proximal operators such as soft thresholding. These operators also support the regularizers that involve multiplication with diagonal or unitary matrices, such as orthogonal wavelets.
 
-#### Iterative reconstruction (IR) algorithms
+#### Iterative reconstruction (MBIR) algorithms
 
 Currently, the package includes the conjugate gradient (CG), fast iterative thresholding (FISTA), optimized gradient method (POGM), forward-backward primal-dual (FBPD) algorithms for image reconstruction.
 
 #### Dictionary learning
 
-For dictionary learning-based reconstruction, we implemented an efficient dictionary learning algorithm (SOUP-DIL) and orthogonal matching pursuit (OMP). Due to PyTorch’s limited support of sparse matrices, we use SciPy as the backend. 
+For dictionary learning-based reconstruction, we implemented an efficient dictionary learning algorithm ([SOUP-DIL](https://arxiv.org/abs/1511.06333)) and orthogonal matching pursuit ([OMP](https://ieeexplore.ieee.org/abstract/document/342465/?casa_token=aTDkQVCM9WEAAAAA:5rXu9YikP822bCBvkhYxKWlBTJ6Fn6baTQJ9kuNrU7K-64EmGOAczYvF2dTW3al3PfPdwJAiYw)). Due to PyTorch’s limited support of sparse matrices, we use SciPy as the backend. 
+
+------
+
+### Usage and examples
+
+`/example` includes several examples. 
 
-### Basic usage
+`/example/demo_mnist.ipynb` shows the LASSO on MNIST with FISTA and POGM. 
 
-#### MRI reconstruction: 
+`/example/demo_mri.ipynb` contains the SENSE (CG-SENSE) and **B0**-informed reconstruction with penalized weighted least squares (*PWLS*).
 
-`/example` includes SENSE, Non-Cartesian SENSE, and **B0**-informed reconstruction with penalized weighted least squares (*PWLS*), compressed sensing (CS), and dictionary learning (DL) methods.
+`/example/demo_cs.ipynb` shows the compressed sensing reconstruction of under-determined MRI signals.
 
-#### MRI sampling pattern optimization:
+`/example/demo_dl.ipynb` exhibits the dictionary learning results.
 
-`/example/demo_mri_traj.ipynb` contains MRI sampling pattern optimization examples. One may use the reconstruction loss as objective function to jointly optimize reconstruction algorithms and the sampling pattern.
+[Bjork repo](https://github.com/guanhuaw/Bjork) contains MRI sampling pattern optimization examples. One may use the reconstruction loss as the objective function to jointly optimize reconstruction algorithms and the sampling pattern.
+
+------
 
 ### Acknowledgments
 
@@ -60,6 +72,20 @@ MIRT/MIRT.jl: https://web.eecs.umich.edu/~fessler/code/index.html
 
 PyLops: https://github.com/PyLops/pylops
 
+If the code is useful to your research, please cite:
+
+```bibtex
+@article{wang:22:bjork,
+ author={Wang, Guanhua and Luo, Tianrui and Nielsen, Jon-Fredrik and Noll, Douglas C. and Fessler, Jeffrey A.},
+ journal={IEEE Transactions on Medical Imaging}, 
+ title={B-spline Parameterized Joint Optimization of Reconstruction and K-space Trajectories (BJORK) for Accelerated 2D MRI}, 
+ year={2022},
+ pages={1-1},
+ doi={10.1109/TMI.2022.3161875}}
+```
+
+------
+
 ### License
 
-The MIRTorch uses the BSD3 license. 
+This package uses the BSD3 license. 
diff --git a/docs/conf.py b/docs/conf.py
@@ -27,7 +27,7 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["myst_parser", "sphinx.ext.autodoc"]
+extensions = ["sphinx.ext.napoleon", "myst_parser", "sphinx.ext.autodoc", "sphinx.ext.autosummary", 'sphinx.ext.mathjax']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -43,7 +43,7 @@
 # The theme to use for HTML and HTML Help pages. See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

diff --git a/docs/generated/mirtorch.alg.CG.rst b/docs/generated/mirtorch.alg.CG.rst
@@ -0,0 +1,23 @@
+mirtorch.alg.CG
+===============
+
+.. currentmodule:: mirtorch.alg
+
+.. autoclass:: CG
+
+
+ .. automethod:: __init__
+
+
+ .. rubric:: Methods
+
+ .. autosummary::
+
+ ~CG.__init__
+ ~CG.run
+
+
+
+
+
+
diff --git a/docs/generated/mirtorch.alg.FBPD.rst b/docs/generated/mirtorch.alg.FBPD.rst
@@ -0,0 +1,23 @@
+mirtorch.alg.FBPD
+=================
+
+.. currentmodule:: mirtorch.alg
+
+.. autoclass:: FBPD
+
+
+ .. automethod:: __init__
+
+
+ .. rubric:: Methods
+
+ .. autosummary::
+
+ ~FBPD.__init__
+ ~FBPD.run
+
+
+
+
+
+