Merge pull request #90 from vais-ral/doc_opti

First opti doc

1 files changed, 47 insertions, 3 deletions

diff --git a/README.md b/README.md
index 4a14723..06d30fe 100644
--- a/README.md
+++ b/README.md
@@ -41,10 +41,54 @@ In `ccpi.framework` we define a number of common classes normally used in tomogr
  
  ### `ccpi.optimisation`
  
- This package allows writing of optimisation algorithms. The main actors here are:
+ 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.
  
-  * `Function`
-  * `Operator`
+ 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 optimisation algorithm to solve a particular generic optimisation problem. These are currently python functions by may be changed to operators in another release.
+
+ #### `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.
+ 
+ #### `Function`
+ 
+ A `function` represents a mathematical function of one or more inputs and is intended 
+ to accept `DataContainer`s 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 `grad` 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 
+ `prox` should return the proxial 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`.
+ 
+ #### `Algorithm`
+ 
+ A number of generic algorithm implementations are provided including CGLS and FISTA. An algorithm 
+ is designed for a particular generic optimisation problem accepts and number of `function`s and/or 
+ `operator`s as input to define a specific instance of the generic optimisation problem to be solved.
+ 
+ #### Examples
+ 
+ Please see the demos for examples of defining and using operators, functions and algorithms 
+ to specify and solve optimisation-based reconstruction problems.