From 50a48663507097fb9d09b4529ec0dde7078b8ada Mon Sep 17 00:00:00 2001 From: Brendt Wohlberg Date: Wed, 6 Oct 2021 16:46:54 -0600 Subject: [PATCH] Docs improvements: CSS and explicit formatting (#28) --- docs/source/contributing.rst | 11 +++++--- docs/source/functional.rst | 30 ++++++++++++++++++++-- docs/source/overview.rst | 49 +++++++++++------------------------- docs/source/style.rst | 18 ++++++------- docs/source/team.rst | 10 +++++--- 5 files changed, 66 insertions(+), 52 deletions(-) diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst index a5bee060a..e8f7af10c 100644 --- a/docs/source/contributing.rst +++ b/docs/source/contributing.rst @@ -12,10 +12,16 @@ Contributing div.document li > p { margin-bottom: 4px !important; } - div.document li { + div.document ul > li { list-style: square outside !important; margin-left: 1em !important; } + section { + padding-bottom: 1em; + } + ul { + margin-bottom: 1em; + } @@ -90,7 +96,6 @@ Contributing Code - Branches should be named in the form `/`, where `` provides a highly condensed description of the purpose of the branch (e.g. `address_todo`), and may include an issue number if appropriate (e.g. `fix_223`). -| A feature development workflow might look like this: @@ -328,7 +333,6 @@ To run the type checker on the ``scico`` module: - Building Documentation ====================== @@ -340,7 +344,6 @@ To build a local copy of the docs, from the repo root directory, do - Test Coverage ------------- diff --git a/docs/source/functional.rst b/docs/source/functional.rst index 0710e627e..772c118c4 100644 --- a/docs/source/functional.rst +++ b/docs/source/functional.rst @@ -1,6 +1,28 @@ Functionals and Losses ====================== +.. raw:: html + + + + A functional maps an :code:`array-like` to a scalar; abstractly, a functional is a mapping from :math:`\mathbb{R}^n` or :math:`\mathbb{C}^n` to :math:`\mathbb{R}`. @@ -14,10 +36,9 @@ A functional ``f`` can have three core operations. * Gradient - ``f.grad(x)`` returns the gradient of the functional evaluated at :math:`\mb{x}`. - Calculated using JAX reverse-mode automatic differentiation, exposed through :func:`scico.grad`. - - A functional that is smooth has the attribute ``f.is_smooth == True`` + - A functional that is smooth has the attribute ``f.is_smooth == True``. - NOTE: The gradient of a functional ``f`` can be evaluated even if ``f.is_smooth == False``. All that is required is that the functional can be evaluated, ``f.has_eval == True``. However, the result may not be a valid gradient (or subgradient) for all inputs :math:`\mb{x}`. - * Proximal operator - The proximal operator of a functional :math:`f : \mathbb{R}^n \to \mathbb{R}` is the mapping :math:`\mathrm{prox}_f : \mathbb{R}^n \times \mathbb{R} \to \mathbb{R}^n` defined as @@ -39,6 +60,7 @@ Proximal Calculus We support a limited subset of proximal calculus rules. + Scaled Functionals ****************** @@ -106,3 +128,7 @@ Adding New Functionals Losses ------ + +.. todo:: + + Content missing here diff --git a/docs/source/overview.rst b/docs/source/overview.rst index 1a053009c..2ea26a1cb 100644 --- a/docs/source/overview.rst +++ b/docs/source/overview.rst @@ -11,10 +11,16 @@ Overview div.document li > p { margin-bottom: 4px !important; } - div.document li { + div.document ul > li { list-style: square outside !important; margin-left: 1em !important; } + section { + padding-bottom: 1em; + } + ul { + margin-bottom: 1em; + } @@ -41,14 +47,9 @@ SCICO is designed to solve problems of the form \argmin_{\mb{x}} \; f(\mb{x}) + \sum_{r=1}^R g_r(C_r (\mb{x})), -with :math:`\mb{x} \in \mathbb{R}^{n}` representing the reconstruction, e.g., a 1D, 2D, 3D, or 3D+time image, -:math:`C_r: \mathbb{R}^{n} \to \mathbb{R}^{m_r}` being regularization operators, -and :math:`f: \mathbb{R}^{n} \to \mathbb{R}` and :math:`g_r: \mathbb{R}^{m_r} \to \mathbb{R}` being functionals associated with the data fidelity and regularization, respectively. - +with :math:`\mb{x} \in \mathbb{R}^{n}` representing the reconstruction, e.g., a 1D, 2D, 3D, or 3D+time image, :math:`C_r: \mathbb{R}^{n} \to \mathbb{R}^{m_r}` being regularization operators, and :math:`f: \mathbb{R}^{n} \to \mathbb{R}` and :math:`g_r: \mathbb{R}^{m_r} \to \mathbb{R}` being functionals associated with the data fidelity and regularization, respectively. -In a typical computational imaging problem, we have a `forward model` -that models the data acquisition process. We denote this forward -model by the (possibly nonlinear) operator :math:`A`. +In a typical computational imaging problem, we have a `forward model` that models the data acquisition process. We denote this forward model by the (possibly nonlinear) operator :math:`A`. We want to find :math:`\mb{x}` such that :math:`\mb{y} \approx A(\mb{x})` in some appropriate sense. This discrepency is measured in our data fidelity, or `loss`, function @@ -56,45 +57,25 @@ in some appropriate sense. This discrepency is measured in our data fidelity, or .. math:: f(\mb{x}) = L(A(\mb{x}), \mb{y}) \,, -where :math:`L` is a `functional` that maps a vector (or array) into -a scalar. A common choice is :math:`f(\mb{x}) = \norm{\mb{y} - A(\mb{x})}_2^2`. -The SCICO :class:`.Loss` object encapsulates the data -:math:`\mb{y}`, the forward model :math:`A`, and the functional -:math:`L` in a single object. A library of functionals and losses -are implemented in :mod:`.functional` and :mod:`.loss`, -respectively. +where :math:`L` is a `functional` that maps a vector (or array) into a scalar. A common choice is :math:`f(\mb{x}) = \norm{\mb{y} - A(\mb{x})}_2^2`. The SCICO :class:`.Loss` object encapsulates the data :math:`\mb{y}`, the forward model :math:`A`, and the functional :math:`L` in a single object. A library of functionals and losses are implemented in :mod:`.functional` and :mod:`.loss`, respectively. -Note that :math:`f(\mb{x})` can often be interpreted as the negative -log likelihood of the candidate :math:`\mb{x}`, given the measurements -:math:`\mb{y}` and an underlying noise model. +Note that :math:`f(\mb{x})` can often be interpreted as the negative log likelihood of the candidate :math:`\mb{x}`, given the measurements :math:`\mb{y}` and an underlying noise model. -The functionals :math:`g_r(C_r (\mb{x}))` are regularization functionals. The :math:`C_r` are operators, -usually linear operators. Together, these terms encourage solutions that arex -"simple" in some sense. A popular choice is :math:`g = \norm{ \cdot }_1` and :math:`C` to be a :class:`.FiniteDifferece` -linear operator; this combination promotes piecewise smooth solutions to the inverse problem. +The functionals :math:`g_r(C_r (\mb{x}))` are regularization functionals. The :math:`C_r` are operators, usually linear operators. Together, these terms encourage solutions that arex "simple" in some sense. A popular choice is :math:`g = \norm{ \cdot }_1` and :math:`C` to be a :class:`.FiniteDifferece` linear operator; this combination promotes piecewise smooth solutions to the inverse problem. Usage Examples -------------- -Usage examples are available as Python scripts and Jupyter Notebooks. Example -scripts are located in ``examples/scripts``. The corresponding Jupyter Notebooks -are provided in the ``scico-data`` submodule and symlinked to -``examples/notebooks``. They are also viewable on `GitHub -`_ and in the -documentation :ref:`example_notebooks`. +Usage examples are available as Python scripts and Jupyter Notebooks. Example scripts are located in ``examples/scripts``. The corresponding Jupyter Notebooks are provided in the ``scico-data`` submodule and symlinked to ``examples/notebooks``. They are also viewable on `GitHub `_ and in the documentation :ref:`example_notebooks`. Related Projects ---------------- -The SCICO library is inspired by the `GlobalBiolm `_ MATLAB package, -which provides a similar object-oriented design for solving computational imaging problems. `Pycsou `_ is a similar -Python library for inverse problems that is also inspired by GlobalBioIm. +The SCICO library is inspired by the `GlobalBiolm `_ MATLAB package, which provides a similar object-oriented design for solving computational imaging problems. `Pycsou `_ is a similar Python library for inverse problems that is also inspired by GlobalBioIm. -A key advantage of SCICO over these libraries is the usage of JAX, which provides automatic hardware acceleration, automatic differentiation, -and automatic adjoint calculations. Moreover, as JAX is a machine learning library, state of the art Plug-and-Play regularizers such as DnCNN -can specified, trained, and implemented in the same software package. +A key advantage of SCICO over these libraries is the usage of JAX, which provides automatic hardware acceleration, automatic differentiation, and automatic adjoint calculations. Moreover, as JAX is a machine learning library, state of the art Plug-and-Play regularizers such as DnCNN can specified, trained, and implemented in the same software package. Other related projects that may be of interest include: diff --git a/docs/source/style.rst b/docs/source/style.rst index a38609a76..970d9638b 100644 --- a/docs/source/style.rst +++ b/docs/source/style.rst @@ -13,10 +13,16 @@ Style Guide div.document li > p { margin-bottom: 4px !important; } - div.document li { + div.document ul > li { list-style: square outside !important; margin-left: 1em !important; } + section { + padding-bottom: 1em; + } + ul { + margin-bottom: 1em; + } @@ -100,7 +106,6 @@ Things to avoid: - Protected: Use a single underscore, ``_``, for protected access - Pseudo-private: Use double underscores, ``_``, for pseudo-private access via name mangling. -| Displaying and Printing Strings ------------------------------- @@ -114,8 +119,6 @@ Prefer to use Python f-strings, rather than `.format` or `%` syntax. print(f"The state is {state}") # Preferred - - Imports ------- @@ -126,7 +129,6 @@ Usage of ``import`` statements should be reserved for packages and modules only - Use ``from x import y as z`` if two modules named ``y`` are imported or if ``y`` is too long of a name. - Use ``import y as z`` when ``z`` is a standard abbreviation like ``import numpy as np``. -| Variables --------- @@ -146,7 +148,6 @@ Apart from naming conventions there are a few extra documentation and coding pra - Avoid global variables. - A function can refer to variables defined in enclosing functions but cannot assign to them. -| Parameters ---------- @@ -193,7 +194,6 @@ There are three important stlyle components for parameters: - For documentation purposes, ``NoneType`` or ``None`` should be written with double backticks -| Docstrings ---------- @@ -406,8 +406,8 @@ The following are sections that can be added to functions, modules, classes, or with a ``...`` >>> np.add([[1, 2], [3, 4]], - ... [[5, 6], [7, 8]]) - array([[ 6, 8], + ... [[5, 6], [7, 8]]) + array([[ 6, 8], [10, 12]]) """ diff --git a/docs/source/team.rst b/docs/source/team.rst index f0d7fe833..baeddda5b 100644 --- a/docs/source/team.rst +++ b/docs/source/team.rst @@ -11,10 +11,16 @@ SCICO Contributors div.document li > p { margin-bottom: 4px !important; } - div.document li { + div.document ul > li { list-style: square outside !important; margin-left: 1em !important; } + section { + padding-bottom: 1em; + } + ul { + margin-bottom: 1em; + } @@ -28,11 +34,9 @@ Core Developers - `Michael McCann `_ - `Brendt Wohlberg `_ -| Contributors ============ - `Oleg Korobkin `_ (BlockArray improvements) - `Yanpeng Yuan `_ (Improvements to ASTRA interface) -