README.md 9.14 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

21
22
23
**1.0.5**:
* [Sources](https://gitlab.gwdg.de/nam/ProxPython/-/releases/1.0.5)
* [Documentation](https://num.math.uni-goettingen.de/proxtoolbox/versions/1.0.5)
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

Russell Luke's avatar
Russell Luke committed
83
84
85
86
87
88
89
90
91
92
Before you do anything, you need to load the following python packages:
        * numpy
        * matplotlib
        * iamgeio
        * h5py
        * urllib3 
        * numba 
        * scikitimage 
        * scikitlearn

93
94
95
96
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
97
in the `ProxPython/Nanoscale_Photonic_Imaging` folder.
98
99
100

To run a demo, open a command line. Assuming ProxPython is in your current folder,
change your current folder to demos by
101
102
103
104

``` bash
cd ProxPython/demos
```
105
106

Then just type
107
108
109
110
111


``` bash
python3 demo_name
```
112
113
114
115
116

to run the demo called "demo_name".

For example,

117
``` bash
Russell Luke's avatar
Russell Luke committed
118
python3 JWST_DRl.py
119
```
120

Russell Luke's avatar
Russell Luke committed
121
will run the DRl algortihm on the JWST experiment.
122

123
## Structure
124
125
126

What is the basic structure of ProxPython?

Jochen Schulz's avatar
fixes  
Jochen Schulz committed
127
### I. proxtoolbox folder
128

129
This is the heart of the proxtoolbox. Most of the code is found here.
130
131
132
133
There are four subfolders:

1. experiments

134
    This folder contains the different experiments to which the
135
136
    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
137
138
    experiment. Essentially, this class loads or generates the data
    used in the experiment and instanciates the algorithm that works on
139
140
141
    this data. This class is meant to be derived from to implement
    concrete experiments.
    There are currently four families of experiments: the phase retrieval
142
    experiments, computed tomography (CT), ptychography, and Sudoku.
143
144
145
146
    The orbital tomography experiment will be integrated soon.

2. algorithms

147
    The proxtoolbox allows the use of different algortihms.
148
    This folder contains the abstract Algorithm class and
149
    various concrete classes.
150
151
    At moment the following algortihms have been implemented:

Russell Luke's avatar
Russell Luke committed
152
153
     - AP:   Alternating Projections
     - AvP:  Averaged Projections
154
     - CDRl: relaxed version of a cyclic averaged
Russell Luke's avatar
Russell Luke committed
155
             alternating reflections method (CDR) proposed by
Russell Luke's avatar
Russell Luke committed
156
             Borwein and Tam, Journal of Nonlinear and Convex Analysis
Russell Luke's avatar
Russell Luke committed
157
158
159
             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
160
161
             "Relaxed Cyclic Douglas-Rachford Algorithms for Nonconvex 
             Optimization", D. R. Luke, A. Martins and M. K. Tam. 
Russell Luke's avatar
Russell Luke committed
162
163
164
             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
165
166
             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
167
     - CP:   Cyclic Projections
168
169
     - 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
170
             Douglas--Rachford algorithm", Comput. Optim. Appl., 70
s.gretchko's avatar
s.gretchko committed
171
             (2018), pp. 841--863.
Russell Luke's avatar
Russell Luke committed
172
     - DRl:  Douglas-Rachford-lambda (same as RAAR below)
173
174
     - HPR:  (Heinz-Patrick-Russell algorithm.
             See Bauschke,Combettes&Luke, Journal of the Optical
Russell Luke's avatar
Russell Luke committed
175
             Society of America A, 20(6):1025-1034 (2003))
Russell Luke's avatar
Russell Luke committed
176
177
     - RRR: Relaxed-Reflect-Reflect algorithm by Veit Elser, 
            IEEE Trans. Inform. Theory, 64 (2018), pp. 412–428.
178
     - PHeBIE: Proximal Heterogenious Block Implicit-Explicit (PHeBIE)
Russell Luke's avatar
Russell Luke committed
179
180
181
             minimzation algorithm as proposed in the paper
             "Proximal Heterogeneous Block Implicit-Explicit Method and
             Application to Blind Ptychographic Diffraction Imaging",
182
             R. Hesse, D. R. Luke, S. Sabach and M. K. Tam,
Russell Luke's avatar
Russell Luke committed
183
             SIAM J. on Imaging Sciences, 8(1):426--457 (2015))
s.gretchko's avatar
s.gretchko committed
184
     - QNAvP: Quasi-Newton Accelerated Averaged Projections
185
     - RAAR: Relaxed Averaged Alternating Reflection algorithm.
Russell Luke's avatar
Russell Luke committed
186
187
188
             For background see:
             D.R.Luke, Inverse Problems 21:37-50(2005)
             D.R. Luke, SIAM J. Opt. 19(2): 714--739 (2008))
189
190
191


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

Russell Luke's avatar
Russell Luke committed
194

195
196
197
4. utils
    Contains some utilities, mostly for loading and processing data.

Jochen Schulz's avatar
fixes  
Jochen Schulz committed
198
### II. InputData
199
200

When you first download the proxtoolbox this folder should be empty.
Russell Luke's avatar
Russell Luke committed
201
202
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.
203
204
If this does not work you need to download the data manually from:

205
206
207
* [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
208

209
Extract the data and store it in
210
``` bash
211
InputData/Phase/
Russell Luke's avatar
Russell Luke committed
212
InputData/Ptychography/
213
214
InputData/CT/
```
215

Jochen Schulz's avatar
fixes  
Jochen Schulz committed
216
### III. Demos
217
218
219

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

224
225
226
``` bash
python3 demo_name
```
Jochen Schulz's avatar
Jochen Schulz committed
227

Jochen Schulz's avatar
fixes  
Jochen Schulz committed
228
#### Demos Accompanying Publications:
Jochen Schulz's avatar
Jochen Schulz committed
229
230
231
232
233
234
235

- [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).


236
237
238
- 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
239
  'Proximal Methods for Image Processing' pp. 165-202 (2020).
240
  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
241
  Topics in Applied Physics, vol 134. Springer, Cham.