initial sphinx doc

7 files changed, 489 insertions, 0 deletions

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 <mastertoc>`
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 <mastertoc>`{.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 <mastertoc>`