From 91ac62b7069222c7cdb7e6777a3bdbda65383757 Mon Sep 17 00:00:00 2001 From: Edoardo Pasca Date: Tue, 19 Mar 2019 16:55:02 +0000 Subject: initial sphinx doc --- docs/Makefile | 19 +++++ docs/make.bat | 35 ++++++++ docs/source/conf.py | 187 +++++++++++++++++++++++++++++++++++++++++++ docs/source/framework.rst | 20 +++++ docs/source/index.rst | 23 ++++++ docs/source/optimisation.md | 113 ++++++++++++++++++++++++++ docs/source/optimisation.rst | 92 +++++++++++++++++++++ 7 files changed, 489 insertions(+) create mode 100755 docs/Makefile create mode 100755 docs/make.bat create mode 100755 docs/source/conf.py create mode 100644 docs/source/framework.rst create mode 100755 docs/source/index.rst create mode 100755 docs/source/optimisation.md create mode 100644 docs/source/optimisation.rst diff --git a/docs/Makefile b/docs/Makefile new file mode 100755 index 0000000..4801716 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,19 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SOURCEDIR = source +BUILDDIR = docs/build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/make.bat b/docs/make.bat new file mode 100755 index 0000000..f88c76c --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=docs/build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100755 index 0000000..406877b --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,187 @@ +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'CCPi-Framework' +copyright = '2019, Edoardo Pasca' +author = 'Edoardo Pasca' + +# The short X.Y version +version = '' +# The full version, including alpha/beta/rc tags +release = '19.02' + + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.doctest', + 'sphinx.ext.todo', + 'sphinx.ext.coverage', + 'sphinx.ext.mathjax', + 'sphinx.ext.viewcode', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['docstemplates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +source_suffix = ['.rst', '.md'] +#source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = 'en' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = None + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'classic' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# 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, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['docsstatic'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'CCPi-Frameworkdoc' + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'CCPi-Framework.tex', 'CCPi-Framework Documentation', + 'Edoardo Pasca', 'manual'), +] + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'ccpi-framework', 'CCPi-Framework Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'CCPi-Framework', 'CCPi-Framework Documentation', + author, 'CCPi-Framework', 'One line description of project.', + 'Miscellaneous'), +] + + +# -- Options for Epub output ------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + + +# -- Extension configuration ------------------------------------------------- + +# -- Options for todo extension ---------------------------------------------- + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True diff --git a/docs/source/framework.rst b/docs/source/framework.rst new file mode 100644 index 0000000..4da0d6a --- /dev/null +++ b/docs/source/framework.rst @@ -0,0 +1,20 @@ +DataContainers and Geometry +======================================== +| + +.. autoclass:: ccpi.framework.DataContainer + :members: +.. autoclass:: ccpi.framework.ImageData + :members: +.. autoclass:: ccpi.framework.AcquisitionData + :members: +.. autoclass:: ccpi.framework.AcquisitionGeometry + :members: +.. autoclass:: ccpi.framework.ImageGeometry + :members: +.. autoclass:: ccpi.framework.DataProcessor + :members: + +| + +:ref:`Return Home ` diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100755 index 0000000..4342bec --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,23 @@ +.. CCPi-Framework documentation master file, created by + sphinx-quickstart on Tue Mar 19 15:12:44 2019. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to CCPi-Framework's documentation! +========================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + :name: mastertoc + + + framework + optimisation + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/source/optimisation.md b/docs/source/optimisation.md new file mode 100755 index 0000000..a3b9039 --- /dev/null +++ b/docs/source/optimisation.md @@ -0,0 +1,113 @@ +Optimisation framework +====================== + +This package allows rapid prototyping of optimisation-based +reconstruction problems, i.e. defining and solving different +optimization problems to enforce different properties on the +reconstructed image. + +Firstly, it provides an object-oriented framework for defining +mathematical operators and functions as well a collection of useful +example operators and functions. Both smooth and non-smooth functions +can be used. + +Further, it provides a number of high-level generic implementations of +optimisation algorithms to solve genericlly formulated optimisation +problems constructed from operator and function objects. + +The fundamental components are: + +- Operator: A class specifying a (currently linear) operator +- Function: A class specifying mathematical functions such as a least + squares data fidelity. +- Algorithm: Implementation of an iterative optimisation algorithm to + solve a particular generic optimisation problem. Algorithms are + iterable Python object which can be run in a for loop. Can be + stopped and warm restarted. + +Algorithm +--------- + +A number of generic algorithm implementations are provided including +Gradient Descent CGLS and FISTA. An algorithm is designed for a +particular generic optimisation problem accepts and number of Functions +and/or Operators as input to define a specific instance of the generic +optimisation problem to be solved. They are iterable objects which can +be run in a for loop. The user can provide a stopping criterion +different than the default max\_iteration. + +New algorithms can be easily created by extending the Algorithm class. +The user is required to implement only 4 methods: set\_up, \_\_init\_\_, +update and update\_objective. + +- `set_up` and `__init__` are used to configure the algorithm +- `update` is the actual iteration updating the solution +- `update_objective` defines how the objective is calculated. + +For example, the implementation of the update of the Gradient Descent +algorithm to minimise a Function will only be: + +The `Algorithm` provides the infrastructure to continue iteration, to +access the values of the objective function in subsequent iterations, +the time for each iteration. + +::: {.autoclass members="" private-members="" special-members=""} +ccpi.optimisation.algorithms.Algorithm +::: + +::: {.autoclass members=""} +ccpi.optimisation.algorithms.GradientDescent +::: + +::: {.autoclass members=""} +ccpi.optimisation.algorithms.CGLS +::: + +::: {.autoclass members=""} +ccpi.optimisation.algorithms.FISTA +::: + +Operator +-------- + +The two most important methods are `direct` and `adjoint` methods that +describe the result of applying the operator, and its adjoint +respectively, onto a compatible `DataContainer` input. The output is +another `DataContainer` object or subclass hereof. An important special +case is to represent the tomographic forward and backprojection +operations. + +::: {.autoclass members=""} +ccpi.optimisation.operators.Operator +::: + +::: {.autoclass members=""} +ccpi.optimisation.operators.LinearOperator +::: + +::: {.autoclass members=""} +ccpi.optimisation.operators.ScaledOperator +::: + +Function +-------- + +A `Function` represents a mathematical function of one or more inputs +and is intended to accept `DataContainers` as input as well as any +additional parameters. + +Fixed parameters can be passed in during the creation of the function +object. The methods of the function reflect the properties of it, for +example, if the function represented is differentiable the function +should contain a method `gradient` which should return the gradient of +the function evaluated at an input point. If the function is not +differentiable but allows a simple proximal operator, the method +`proximal` should return the proximal operator evaluated at an input +point. The function value is evaluated by calling the function itself, +e.g. `f(x)` for a `Function f` and input point `x`. + +::: {.autoclass members=""} +ccpi.optimisation.functions.Function +::: + +`Return Home `{.interpreted-text role="ref"} diff --git a/docs/source/optimisation.rst b/docs/source/optimisation.rst new file mode 100644 index 0000000..7c1eda6 --- /dev/null +++ b/docs/source/optimisation.rst @@ -0,0 +1,92 @@ +Optimisation framework +********************** +This package allows rapid prototyping of optimisation-based reconstruction problems, i.e. defining and solving different optimization problems to enforce different properties on the reconstructed image. + +Firstly, it provides an object-oriented framework for defining mathematical operators and functions as well a collection of useful example operators and functions. Both smooth and non-smooth functions can be used. + +Further, it provides a number of high-level generic implementations of optimisation algorithms to solve genericlly formulated optimisation problems constructed from operator and function objects. + +The fundamental components are: + ++ Operator: A class specifying a (currently linear) operator ++ Function: A class specifying mathematical functions such as a least squares data fidelity. ++ Algorithm: Implementation of an iterative optimisation algorithm to solve a particular generic optimisation problem. Algorithms are iterable Python object which can be run in a for loop. Can be stopped and warm restarted. + +Algorithm +========= + +A number of generic algorithm implementations are provided including +Gradient Descent CGLS and FISTA. An algorithm is designed for a +particular generic optimisation problem accepts and number of +Functions and/or Operators as input to define a specific instance of +the generic optimisation problem to be solved. +They are iterable objects which can be run in a for loop. +The user can provide a stopping criterion different than the default max_iteration. + +New algorithms can be easily created by extending the Algorithm class. The user is required to implement only 4 methods: set_up, __init__, update and update_objective. + ++ :code:`set_up` and :code:`__init__` are used to configure the algorithm ++ :code:`update` is the actual iteration updating the solution ++ :code:`update_objective` defines how the objective is calculated. + +For example, the implementation of the update of the Gradient Descent +algorithm to minimise a Function will only be: + +.. code-block :: python + + def update(self): + self.x += -self.rate * self.objective_function.gradient(self.x) + def update_objective(self): + self.loss.append(self.objective_function(self.x)) + +The :code:`Algorithm` provides the infrastructure to continue iteration, to access the values of the objective function in subsequent iterations, the time for each iteration. + +.. autoclass:: ccpi.optimisation.algorithms.Algorithm + :members: + :private-members: + :special-members: +.. autoclass:: ccpi.optimisation.algorithms.GradientDescent + :members: +.. autoclass:: ccpi.optimisation.algorithms.CGLS + :members: +.. autoclass:: ccpi.optimisation.algorithms.FISTA + :members: + +Operator +======== +The two most important methods are :code:`direct` and :code:`adjoint` +methods that describe the result of applying the operator, and its +adjoint respectively, onto a compatible :code:`DataContainer` input. +The output is another :code:`DataContainer` object or subclass +hereof. An important special case is to represent the tomographic +forward and backprojection operations. + +.. autoclass:: ccpi.optimisation.operators.Operator + :members: +.. autoclass:: ccpi.optimisation.operators.LinearOperator + :members: +.. autoclass:: ccpi.optimisation.operators.ScaledOperator + :members: + +Function +======== + +A :code:`Function` represents a mathematical function of one or more inputs +and is intended to accept :code:`DataContainers` as input as well as any +additional parameters. + +Fixed parameters can be passed in during the creation of the function object. +The methods of the function reflect the properties of it, for example, if the function +represented is differentiable the function should contain a method :code:`gradient` +which should return the gradient of the function evaluated at an input point. +If the function is not differentiable but allows a simple proximal operator, +the method :code:`proximal` should return the proximal operator evaluated at an +input point. The function value is evaluated by calling the function itself, +e.g. :code:`f(x)` for a :code:`Function f` and input point :code:`x`. + + +.. autoclass:: ccpi.optimisation.functions.Function + :members: + + +:ref:`Return Home ` -- cgit v1.2.3