README.md 8.92 KB
Newer Older
1
# ProxToolbox
2

Jochen Schulz's avatar
Jochen Schulz committed
3 4

[[_TOC_]]
5

s.gretchko's avatar
s.gretchko committed
6 7 8 9
The ProxToolbox is a collection of modules for solving mathematical problems
using fixed point iterations with proximal operators. It was used to generate
many if not all of the numerical experiments conducted in the papers in the
ProxMatlab Literature folder.
10

Jochen Schulz's avatar
Jochen Schulz committed
11 12
For a complete listing of papers with links, go to the [groups publications]
(https://vaopt.math.uni-goettingen.de/en/publications.php).
13

14
This site is maintained by the Working Group in Variational Analysis of the
s.gretchko's avatar
s.gretchko committed
15
Institute for Numerical and Applied Mathematics at the University of Göttingen.
Russell Luke's avatar
Russell Luke committed
16

17
![Video: Representative iterate of a noisy JWST test wavefront recovered with the Douglas-Rachford algorithm](./media/JWST.mp4)
Russell Luke's avatar
Russell Luke committed
18

19 20
## Python version

Russell Luke's avatar
Russell Luke committed
21 22 23
**1.0.4**:
* [Sources](https://gitlab.gwdg.de/nam/ProxPython/-/releases/1.0.4)
* [Documentation](https://num.math.uni-goettingen.de/proxtoolbox/versions/1.0.4)
Russell Luke's avatar
Russell Luke committed
24 25


26
The documentation includes a tutorial.
27

28
### Older versions
Russell Luke's avatar
Russell Luke committed
29

Jochen Schulz's avatar
Jochen Schulz committed
30
- **0.2.2**: [Source](https://gitlab.gwdg.de/nam/ProxPython/-/releases/0.2.2), [Documentation](https://num.math.uni-goettingen.de/proxtoolbox/versions/0.2)
Jochen Schulz's avatar
fixes  
Jochen Schulz committed
31
- **0.1**: [Source](https://num.math.uni-goettingen.de/proxtoolbox/tarballs/0.1/proxpython-0.1.tar.gz), [Documentation](https://num.math.uni-goettingen.de/proxtoolbox/versions/0.1)
Russell Luke's avatar
Russell Luke committed
32 33


Jochen Schulz's avatar
Jochen Schulz committed
34
## Matlab version
35

Jochen Schulz's avatar
Jochen Schulz committed
36
[3.0](https://vaopt.math.uni-goettingen.de/en/software/ProxMatlab-Release3.0.tar.gz)
37

Jochen Schulz's avatar
Jochen Schulz committed
38
For help with the Matlab version, see the :code:`README` file in the ProxMatlab source.
39 40


Jochen Schulz's avatar
Jochen Schulz committed
41
## Additional binary data
42

43 44 45
* [Phase (28mb)](https://vaopt.math.uni-goettingen.de/data/Phase.tar.gz)
* [Ptychography (417mb)](https://vaopt.math.uni-goettingen.de/data/Ptychography.tar.gz)
* [CT (1.7mb)](https://vaopt.math.uni-goettingen.de/data/CT.tar.gz)
46

47 48
The binary data need to be unpacked in the `InputData` subdirectory source code.
For example, the `Phase` data in ProxPython would be in `ProxPython/InputData/Phase`.
49

50 51 52 53 54 55
## Acknowledgements

**Main Author**: Russell Luke, University of Göttingen

**Contributors**:

56 57 58 59
Contributors are from institute for Numerical and Applied Mathematics, University of Göttingen, if not stated otherwise.

Sylvain Gretchko (python); 
Jochen Schulz (python, administration and structure);
60
Matthijs Jansen, I. Institute for Physics, University of Göttingen (Orbital Tomography);
61 62 63
Alexander Dornheim (python);
Stefan Ziehe (python);
Rebecca Nahme (python);
64
Matthew Tam, CARMA, University of Newcastle, Australia (Ptychography);
65
Pär Mattson (Ptychography);
66
Robin Wilke, Inst. for X-Ray Physics, Univesität Göttingen (Ptychography and Phase);
67 68
Robert Hesse;
Alexander Stalljahn (Sudoku).
69 70 71 72 73

**Funding**:

This has grown over the years and has been supported in part by:

Russell Luke's avatar
Russell Luke committed
74 75
* NASA grant NGT5-66; 
* Pacific Institute for Mathematical Sciences (PIMS);
76 77 78 79 80
* USA NSF Grant DMS-0712796;
* German DFG grant SFB-755 TPC2;
* German Israeli Foundation (GIF) grant G-1253-304.6/2014.


Jochen Schulz's avatar
fixes  
Jochen Schulz committed
81
# Getting started
82 83 84 85 86

The easiest way to use ProxPython is to run some of the included demos.
There are different families of experiments and various demos.
All the demos are located in the ProxPython/demos folder. For convenience,
all the Nanoscale Photonic Imaging demos have been grouped together
87
in the `ProxPython/Nanoscale_Photonic_Imaging` folder.
88 89 90

To run a demo, open a command line. Assuming ProxPython is in your current folder,
change your current folder to demos by
91 92 93 94

``` bash
cd ProxPython/demos
```
95 96

Then just type
97 98 99 100 101


``` bash
python3 demo_name
```
102 103 104 105 106

to run the demo called "demo_name".

For example,

107 108 109
``` bash
python3 JWST_RAAR.py
```
110 111 112

will run the RAAR algortihm on the JWST experiment.

113
## Structure
114 115 116

What is the basic structure of ProxPython?

Jochen Schulz's avatar
fixes  
Jochen Schulz committed
117
### I. proxtoolbox folder
118

119
This is the heart of the proxtoolbox. Most of the code is found here.
120 121 122 123
There are four subfolders:

1. experiments

124
    This folder contains the different experiments to which the
125 126
    proxtoolbox can be applied. It defines the abstract Experiment
    class which contains all the information that describes a given
s.gretchko's avatar
s.gretchko committed
127 128
    experiment. Essentially, this class loads or generates the data
    used in the experiment and instanciates the algorithm that works on
129 130 131
    this data. This class is meant to be derived from to implement
    concrete experiments.
    There are currently four families of experiments: the phase retrieval
132
    experiments, computed tomography (CT), ptychography, and Sudoku.
133 134 135 136
    The orbital tomography experiment will be integrated soon.

2. algorithms

137
    The proxtoolbox allows the use of different algortihms.
138
    This folder contains the abstract Algorithm class and
139
    various concrete classes.
140 141
    At moment the following algortihms have been implemented:

Russell Luke's avatar
Russell Luke committed
142 143
     - AP:   Alternating Projections
     - AvP:  Averaged Projections
144
     - CDRl: relaxed version of a cyclic averaged
Russell Luke's avatar
Russell Luke committed
145
             alternating reflections method (CDR) proposed by
Russell Luke's avatar
Russell Luke committed
146
             Borwein and Tam, Journal of Nonlinear and Convex Analysis
Russell Luke's avatar
Russell Luke committed
147 148 149
             Volume 16, Number 4.  The relaxation (CDRl) is the cyclic 
             implementation of the relaxed Douglas Rachford algorithm proposed 
             by Luke.  The convex case for CDRL was studied in 
Russell Luke's avatar
Russell Luke committed
150 151
             "Relaxed Cyclic Douglas-Rachford Algorithms for Nonconvex 
             Optimization", D. R. Luke, A. Martins and M. K. Tam. 
Russell Luke's avatar
Russell Luke committed
152 153 154
             ICML 2018 Workshop. Stockholm, July 2018 
             (https://sites.google.com/view/icml2018nonconvex/papers) and 
             the performance on phase retrieval was studied in 
Russell Luke's avatar
Russell Luke committed
155 156
             D. R. Luke, S. Sabach and M. Teboulle , SIAM J. Mathematics of 
             Data Science, 1(3), 408-445 (2019). 
Russell Luke's avatar
Russell Luke committed
157
     - CP:   Cyclic Projections
158 159
     - DRAP: a type of hybrid Douglas-Rachford and Alternating projections
             proposed by Nguyen H. Thao, ``A convergent relaxation of the
Russell Luke's avatar
Russell Luke committed
160
             Douglas--Rachford algorithm", Comput. Optim. Appl., 70
s.gretchko's avatar
s.gretchko committed
161
             (2018), pp. 841--863.
Russell Luke's avatar
Russell Luke committed
162
     - DRl:  Douglas-Rachford-lambda (same as RAAR below)
163 164
     - HPR:  (Heinz-Patrick-Russell algorithm.
             See Bauschke,Combettes&Luke, Journal of the Optical
Russell Luke's avatar
Russell Luke committed
165
             Society of America A, 20(6):1025-1034 (2003))
Russell Luke's avatar
Russell Luke committed
166 167
     - RRR: Relaxed-Reflect-Reflect algorithm by Veit Elser, 
            IEEE Trans. Inform. Theory, 64 (2018), pp. 412–428.
168
     - PHeBIE: Proximal Heterogenious Block Implicit-Explicit (PHeBIE)
Russell Luke's avatar
Russell Luke committed
169 170 171
             minimzation algorithm as proposed in the paper
             "Proximal Heterogeneous Block Implicit-Explicit Method and
             Application to Blind Ptychographic Diffraction Imaging",
172
             R. Hesse, D. R. Luke, S. Sabach and M. K. Tam,
Russell Luke's avatar
Russell Luke committed
173
             SIAM J. on Imaging Sciences, 8(1):426--457 (2015))
s.gretchko's avatar
s.gretchko committed
174
     - QNAvP: Quasi-Newton Accelerated Averaged Projections
175
     - RAAR: Relaxed Averaged Alternating Reflection algorithm.
Russell Luke's avatar
Russell Luke committed
176 177 178
             For background see:
             D.R.Luke, Inverse Problems 21:37-50(2005)
             D.R. Luke, SIAM J. Opt. 19(2): 714--739 (2008))
179 180 181


3. proxoperators
s.gretchko's avatar
s.gretchko committed
182
    Contains the prox operators classes used by the algorithms.
183

Russell Luke's avatar
Russell Luke committed
184

185 186 187
4. utils
    Contains some utilities, mostly for loading and processing data.

Jochen Schulz's avatar
fixes  
Jochen Schulz committed
188
### II. InputData
189 190

When you first download the proxtoolbox this folder should be empty.
Russell Luke's avatar
Russell Luke committed
191 192
When you call a ART/Phase/Ptychography demo the first time, you are asked if you
want to automatically download the InputData for ART, phase or ptychography.
193 194
If this does not work you need to download the data manually from:

195 196 197
* [Phase (28mb)](https://vaopt.math.uni-goettingen.de/data/Phase.tar.gz)
* [Ptychography (417mb)](https://vaopt.math.uni-goettingen.de/data/Ptychography.tar.gz)
* [CT (1.7mb)](https://vaopt.math.uni-goettingen.de/data/CT.tar.gz)
Russell Luke's avatar
Russell Luke committed
198

199
Extract the data and store it in
200
``` bash
201
InputData/Phase/
Russell Luke's avatar
Russell Luke committed
202
InputData/Ptychography/
203 204
InputData/CT/
```
205

Jochen Schulz's avatar
fixes  
Jochen Schulz committed
206
### III. Demos
207 208 209

All the demos are located in the demos folder. For convenience,
all the Nanoscale Photonic Imaging demos have been grouped together
210 211
in the ProxPython/Nanoscale_Photonic_Imaging folder. To run a demo,
change your current folder to demos or Nanoscale_Photonic_Imaging and
212 213
type

214 215 216
``` bash
python3 demo_name
```
Jochen Schulz's avatar
Jochen Schulz committed
217

Jochen Schulz's avatar
fixes  
Jochen Schulz committed
218
#### Demos Accompanying Publications:
Jochen Schulz's avatar
Jochen Schulz committed
219 220 221 222 223 224 225

- [Cone and Sphere benchmark](https://vaopt.math.uni-goettingen.de/en/software/ProxMatlab-Cone_and_Sphere.tar.gz):
  The demos are in the subfolder Cone_and_Sphere.  These are the codes generating the benchmarks in the article
  [Optimization on Spheres: Models and Proximal Algorithms with Computational Performance Comparisons](https://epubs.siam.org/doi/abs/10.1137/18M1193025)
  by D.R. Luke, S. Sabach and M. Teboulle, SIAM J. Mathematics of Data Science, 1(3), 408-445 (2019).


226 227 228
- Nanoscale Photonic Imaging demos:
  The demos [(Matlab)](https://vaopt.math.uni-goettingen.de/en/software/ProxMatlab-Cone_and_Sphere.tar.gz) 
  [(Python)](https://gitlab.gwdg.de/nam/ProxPython/-/releases/1.0.3) are in the subfolder Nanosclae_Photonic_Imaging.  These are the codes accompanying the tutorial chapter by D. R. Luke
Jochen Schulz's avatar
Jochen Schulz committed
229
  'Proximal Methods for Image Processing' pp. 165-202 (2020).
230
  In T. Salditt, A. Egner and D.R. Luke (eds)  [Nanoscale Photonic Imaging](https://link.springer.com/book/10.1007/978-3-030-34413-9).
Jochen Schulz's avatar
Jochen Schulz committed
231
  Topics in Applied Physics, vol 134. Springer, Cham.