Commit 128e2eb2 authored by Russell Luke's avatar Russell Luke
Browse files

new .rst files

parent be92909e
#################
Extending Samsara
#################
This will be a short guide on how to extend ProxPython with new functions.
Functions
=========
The ProxPython package is divided into the following modules:
...
Now that we know how the samsara package is structured we can look at
how to add a new function ourself:
#. Implement the function in the appropriate module.
#. Add the function as a new case to the appropriate wrapper in the
same module.
* If your new function has a parameter that is currently not
provided by the wrapper, you will need to add it and update all
calls to the wrapper.
#. If your function is an alternative to
:func:`blah`,
:func:`blah-blah` or
:func:`blah-blah-blah`,
then you will also need to add another case for your function in
:func:`4blah`.
Your function is now implemented in ProxPython. To use it, you will need
to import it into your driver and tell ProxPython to use it in the
options. The following example illustrates these steps.
Example
-------
Let's say we want to add a new algorithm to ProxPython...
Documentation
=============
This documentation is built using `Sphinx`_ with the
`numpydoc`_ extension. `This example`_ from the numpy project gives
a small overview and guideline on how to document your Python
functions. To build the documentation you can invoke the included
`Makefile`:
.. _Sphinx: http://sphinx-doc.org/
.. _numpydoc: https://github.com/numpy/numpydoc
.. _This example: https://github.com/numpy/numpy/blob/master/doc/example.py
>>> make html
or simply
>>> make
to see all available build targets.
################
Matlab-to-Python
################
Here are some notes on the Python port itself, as well as some pointers
when coming from MATLAB.
Coming From MATLAB
==================
Main differences between writing for MATLAB and writing for Python.
A short overview over the differences between MATLAB and Python as
well as a list of corresponing sytax can be found in the `scipy wiki`_
(the site is currently unavailable). `This presentation`_ gives a
more thorough introduction. The most common and important differences
are noted below:
.. _scipy wiki: http://wiki.scipy.org/NumPy_for_Matlab_Users
.. _This presentation: https://python-for-matlab-users.googlecode.com/files/tutorial_slides.pdf
* Matrix multiplication is elementwise (so \* in Python corresponds to
.\* in MATLAB for matrices). Use :func:`numpy.dot` for actual
matrix multiplication.
* Matlab accesses matrix elements via A(...), Python uses A[...].
* Python indexing starts with 0, wheres MATLAB indexing starts with 1.
Also for ranges the end value in Python is exclusive, not inclusive
as in MATLAB.
* Example: Let's say we have a 5x5 matrix `A` and we want to access
the first two columns. In MATLAB we would write
>>> A(:, 1:2)
which becomes
>>> A[:, 0:2]
in Python.
* In Python complex data types (such as matrices) are copied as
references only, unless you specifically invoce :func:`numpy.copy()`
on them.
* Example: We have a matrix `A`. In MATLAB
>>> B = A
would give an independent matrix `B` of `A`. So
>>> B(1, 1) = 5
would not change the value in `A`. In Python
>>> B = A
would make `B` a reference to `A`, so
>>> B[0, 0] = 5
would change the value in `A` as well. To get an independent copy
in Python use
>>> B = A.copy()
* Slicing a column or row out of a matrix gives a 1 dimensional array
in Python, so you loose the orientation. At the same time,
:func:`numpy.dot` of two vectors will always result in the scalar
product, without the need of transposing the vector first.
* Two concatenate two matrices in MATLAB you would write:
>>> C = [A , B]
>>> D = [A ; B]
In Python you will need to use `numpy.c_`_ and
`numpy.r_`_ to concatenate columns or rows
respectively:
.. _numpy.c_: http://docs.scipy.org/doc/numpy/reference/generated/numpy.c_.html
.. _numpy.r_: http://docs.scipy.org/doc/numpy/reference/generated/numpy.r_.html
>>> C = c_[A, B]
>>> D = r_[A, B]
Changes to ProxToolbox
=======================
The problems and data sets are always expanding, but structurally,
the biggest change to ProxToolbox is the move from a function in MATLAB to
a class in Python. This allows all relevant variables to stay in
memory after a single iteration which removes the need to save them in
a file in between iterations. Most other changes are related to
removing unused code or variables and are noted by a
>>> # PYTHON PORT ANNOTATION
followed by a short description of the change and the reason for it.
#######
Credits
#######
Contributors:
* Alexander Dornheim, Inst. for Numerical and Applied Math, Universität Göttingen (Matlab-Python port)
* Robert Hesse, Inst. for Numerical and Applied Math, Universität Göttingen
* Pär Mattson, Inst. for Numerical and Applied Math, Universität Göttingen (Ptychography)
* `Matthew Tam <http://num.math.uni-goettingen.de/~mtam/>`_, Inst. for Numerical and Applied Math, Universität Göttingen (Ptychography)
* Robin Wilke, Inst. for X-Ray Physics, Univesität Göttingen (Ptychography and Phase)
* Alexander Stalljahn, Inst. for Numerical and Applied Math, Universität Göttingen (Sudoku)
* Stefan Ziehe, Inst. for Numerical and Applied Math, Universität Göttingen (Matlab-Python port)
Funding:
This has grown over the years and has been supported in part by:
* NASA grant NGT5-66
* the Pacific Institute for Mathematical Sciences (PIMS)
* USA NSF Grant DMS-0712796
* German DFG grant SFB-755
Bibliography:
for a complete listing of papers with links go to
http://vaopt.math.uni-goettingen.de/en/publications.php
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment