# Library Reference – Phasing Algorithms

When coherent diffraction measurements are performed phase information is lost and in general we obtain the reciprocal space intensity distribution , where is the complex density in Fourier-space. We wish to recover the complex real-space density . This is achieved using iterative reconstruction algorithms that traverse back and forth between direct and Fourier space while applying a constraint at each turn.

Generally, phase retrieval algorithms define a support region in real-space for which the amplitude of the object density is unrestricted. Outside this region the amplitude of the density is minimised in some way. A Fourier-space constraint is also defined () and requires the objects amplitude to be proportional in some way to the original measurement on some set such that , for all in .

It is possible to execute more than one of algorithms in the phasing pipeline Algorithms executed in this way will share reconstruction data, hereafter referred to as sequence data. It is also possible, unless otherwise stated, for algorithms to share `support` data. This is achieved by leaving blank the path string field for the `support` NumPy file. Such a feature is desirable for algorithms that modify the support array such as the shrink-wrap method.

The following describes the available algorithms for phase retrieval.

## Random Start

Randomises the phase of the internally stored `sequence data`. This is typically used before phase retrieval commences. If this is not used, the `sequence data` is filled with zeros.

Parameters:

Amp max

  Specifies the amplitude of the array that is randomised.

## Array Start

Replaces the internally stored `sequence data` with the supplied array. This is typically used before phase retrieval commences.

Parameters:

Input file

  User provided path string to the input NumPy file.

## Hybrid Input-Output (HIO)

Fienup’s hybrid input-output (HIO) algorithm. See here for more details.

Parameters:

Exp amp

  User provided path string to the input experimental data NumPy file.

Square Root Exp amp

  Causes the `Exp amp` array to be square rooted before phase retrieval commences. This is necessary if the array contains intensity measurements.

Support

  User provided path string to the support data NumPy file.

Beta

  Relaxation parameter for the HIO algorithm.

Iterations

  Total number of iterations for which the algorithm will perform.

## HIO Mask

Fienup’s hybrid input-output (HIO) algorithm with the addition of a Fourier space constraint mask. See here for more details.

Parameters:

Exp amp

  User provided path string to the input experimental data NumPy file.

Square Root Exp amp

  Causes the `Exp amp` array to be square rooted before phase retrieval commences. This is necessary if the array contains intensity measurements.

Support

  User provided path string to the support data NumPy file.

Mask

  User provided path string to the `mask` data NumPy file.

Beta

  Relaxation parameter for the HIO algorithm.

Iterations

  Total number of iterations for which the algorithm will perform.

## HIO Plus

Fienup’s hybrid input-output (HIO) algorithm with non-negativity constraint and with the addition of a Fourier space constraint mask. See here for more details.

Parameters:

Exp amp

  User provided path string to the input experimental data NumPy file.

Square Root Exp amp

  Causes the `Exp amp` array to be square rooted before phase retrieval commences. This is necessary if the array contains intensity measurements.

Support

  User provided path string to the support data NumPy file.

Mask

  User provided path string to the `mask` data NumPy file.

Beta

  Relaxation parameter for the HIO algorithm.

Iterations

  Total number of iterations for which the algorithm will perform.

## Phase Constrained HIO (PCHIO)

Fienup’s hybrid input-output (HIO) algorithm with phase constraint and with the addition of a Fourier space constraint mask. See here for more details.

Parameters:

Exp amp

  User provided path string to the input experimental data NumPy file.

Square Root Exp amp

  Causes the `Exp amp` array to be square rooted before phase retrieval commences. This is necessary if the array contains intensity measurements.

Support

  User provided path string to the support data NumPy file.

Mask

  User provided path string to the `mask` data NumPy file.

Beta

  Relaxation parameter for the HIO algorithm.

Iterations

  Total number of iterations for which the algorithm will perform.

Phase Max

  Voxels with phase greater than `Phase max` are penalised.

Phase Min

  Voxels with phase lesser than `Phase min` are penalised.

## Phase Gradient Constrained HIO (PGCHIO)

Fienup’s hybrid input-output (HIO) algorithm with phase gradient constraint in the Q-vector direction with the addition of a Fourier space constraint mask. See here for more details.

Warning

Co-ordinate transformation of the object or Q-vector may be required.

Parameters:

Exp amp

  User provided path string to the input experimental data NumPy file.

Square Root Exp amp

  Causes the `Exp amp` array to be square rooted before phase retrieval commences. This is necessary if the array contains intensity measurements.

Support

  User provided path string to the support data NumPy file.

Mask

  User provided path string to the `mask` data NumPy file.

Beta

  Relaxation parameter for the HIO algorithm.

Iterations

  Total number of iterations for which the algorithm will perform.

Phase Max

  Voxels with phase gradient greater than `Phase max` are penalised, in the direction the Q-vector.

Phase Min

  Voxels with phase gradient lesser than `Phase min` are penalised, in the direction the Q-vector.

Q {x,y,z}

  Q-vector, in real space coordinates. Only the vectors direction is significant.

## Error Reduction (ER)

Error Reduction (ER) algorithm. See here for more details.

Parameters:

Exp amp

  User provided path string to the input experimental data NumPy file.

Square Root Exp amp

  Causes the `Exp amp` array to be square rooted before phase retrieval commences. This is necessary if the array contains intensity measurements.

Support

  User provided path string to the support data NumPy file.

Iterations

  Total number of iterations for which the algorithm will perform.

## ER Mask

Error Reduction (ER) algorithm with the addition of a Fourier space constraint mask. See here for more details.

Parameters:

Exp amp

  User provided path string to the input experimental data NumPy file.

Square Root Exp amp

  Causes the `Exp amp` array to be square rooted before phase retrieval commences. This is necessary if the array contains intensity measurements.

Support

  User provided path string to the support data NumPy file.

Mask

  User provided path string to the `mask` data NumPy file.

Iterations

  Total number of iterations for which the algorithm will perform.

## Phase Only ER (POER)

Phase Only Error Reduction (POER) algorithm with the addition of a Fourier space constraint mask. See here for more details.

Parameters:

Exp amp

  User provided path string to the input experimental data NumPy file.

Square Root Exp amp

  Causes the `Exp amp` array to be square rooted before phase retrieval commences. This is necessary if the array contains intensity measurements.

Support

  User provided path string to the support data NumPy file.

Mask

  User provided path string to the `mask` data NumPy file.

Iterations

  Total number of iterations for which the algorithm will perform.

## Relaxed Average Alternating Reflection (RAAR)

Relaxed Average Alternating Reflection (RAAR) algorithm. See here for more details.

Parameters:

Exp amp

  User provided path string to the input experimental data NumPy file.

Square Root Exp amp

  Causes the `Exp amp` array to be square rooted before phase retrieval commences. This is necessary if the array contains intensity measurements.

Support

  User provided path string to the support data NumPy file.

Mask

  User provided path string to the `mask` data NumPy file.

Beta

  Relaxation parameter for the RAAR algorithm.

Iterations

  Total number of iterations for which the algorithm will perform.

## Hybrid Projection Reflection (HPR)

Hybrid Projection Reflection (HPR) algorithm. See here for more details.

Parameters:

Exp amp

  User provided path string to the input experimental data NumPy file.

Square Root Exp amp

  Causes the `Exp amp` array to be square rooted before phase retrieval commences. This is necessary if the array contains intensity measurements.

Support

  User provided path string to the support data NumPy file.

Mask

  User provided path string to the `mask` data NumPy file.

Beta

  Relaxation parameter for the HPR algorithm.

Iterations

  Total number of iterations for which the algorithm will perform.

## Compressed Sensing HIO (CSHIO)

Compressed Sensing HIO (CSHIO) algorithm. See here for more details.

Parameters:

Exp amp

  User provided path string to the input experimental data NumPy file.

Square Root Exp amp

  Causes the `Exp amp` array to be square rooted before phase retrieval commences. This is necessary if the array contains intensity measurements.

Support

  User provided path string to the support data NumPy file.

Mask

  User provided path string to the `mask` data NumPy file.

Beta

  Relaxation parameter for the HIO algorithm.

Iterations

  Total number of iterations for which the algorithm will perform.

p-norm

  p-norm of the Lebesgue space.

Epsilon

  Positive relaxation parameter () for the weighted p-norm.

Epsilon min

  Minimum value that `epsilon` can take.

Divisor

  Amount by which `epsilon` is divided when the following condition is met:

eta

  Parameter () in the `divisor` condition above.

## HIO Mask with Partial Coherence Optimisation (HIO Mask PC)

HIO Mask with Partial Coherence Optimisation (HIO Mask PC) algorithm. See here for more details.

Parameters:

Exp amp

  User provided path string to the input experimental data NumPy file.

Square Root Exp amp

  Causes the `Exp amp` array to be square rooted before phase retrieval commences. This is necessary if the array contains intensity measurements.

Support

  User provided path string to the support data NumPy file.

Mask

  User provided path string to the `mask` data NumPy file.

Beta

  Relaxation parameter for the HIO algorithm.

Iterations

  Total number of iterations for which the algorithm will perform (not including R-L iterations).

Iterations preceding R-L optimisation

  Interval of iterations after which Richardson-Lucy optimisation commences in successive cycles.

R-L iterations

  Number of R-L iterations performed at each cycle.

Interval between R-L optimisation

  Number of iterations between each Richardson-Lucy optimisation cycle.

Initial PSF HWHM The initial point spread function (PSF) optimised using the R-L algorithm is a normal Lorentzian function (). The user can specify the HWHM of its Fourier transform ().

Zero fill end dimensions of PSF

  After optimising the PSF with the R-L algorithm, voxels upto a distance {i,j,k} from the perimeter of the PSF array are set to zero. This can improve stability of the algorithm.

Reset PSF

  Resets the PSF to a normal Lorentzian function before the next R-L optimisation cycle.

## ER Mask with Partial Coherence Optimisation (ER Mask PC)

ER Mask with Partial Coherence Optimisation (ER Mask PC) algorithm. See here for more details.

Parameters:

Exp amp

  User provided path string to the input experimental data NumPy file.

Square Root Exp amp

  Causes the `Exp amp` array to be square rooted before phase retrieval commences. This is necessary if the array contains intensity measurements.

Support

  User provided path string to the support data NumPy file.

Mask

  User provided path string to the `mask` data NumPy file.

Beta

  Relaxation parameter for the ER algorithm.

Iterations

  Total number of iterations for which the algorithm will perform (not including R-L iterations).

Iterations preceding R-L optimisation

  Interval of iterations after which Richardson-Lucy optimisation commences in successive cycles.

R-L iterations

  Number of R-L iterations performed at each cycle.

Interval between R-L optimisation

  Number of iterations between each Richardson-Lucy optimisation cycle.

Initial PSF HWHM The initial point spread function (PSF) optimised using the R-L algorithm is a normal Lorentzian function (). The user can specify the HWHM of its Fourier transform ().

Zero fill end dimensions of PSF

  After optimising the PSF with the R-L algorithm, voxels upto a distance {i,j,k} from the perimeter of the PSF array are set to zero. This can improve stability of the algorithm.

Reset PSF

  Resets the PSF to a normal Lorentzian function before the next R-L optimisation cycle.

## HPR Mask with Partial Coherence Optimisation (HPR Mask PC)

HPR Mask with Partial Coherence Optimisation (HPR Mask PC) algorithm. See here for more details.

Parameters:

Exp amp

  User provided path string to the input experimental data NumPy file.

Square Root Exp amp

  Causes the `Exp amp` array to be square rooted before phase retrieval commences. This is necessary if the array contains intensity measurements.

Support

  User provided path string to the support data NumPy file.

Mask

  User provided path string to the `mask` data NumPy file.

Beta

  Relaxation parameter for the HPR algorithm.

Iterations

  Total number of iterations for which the algorithm will perform (not including R-L iterations).

Iterations preceding R-L optimisation

  Interval of iterations after which Richardson-Lucy optimisation commences in successive cycles.

R-L iterations

  Number of R-L iterations performed at each cycle.

Interval between R-L optimisation

  Number of iterations between each Richardson-Lucy optimisation cycle.

Initial PSF HWHM The initial point spread function (PSF) optimised using the R-L algorithm is a normal Lorentzian function (). The user can specify the HWHM of its Fourier transform ().

Zero fill end dimensions of PSF

  After optimising the PSF with the R-L algorithm, voxels upto a distance {i,j,k} from the perimeter of the PSF array are set to zero. This can improve stability of the algorithm.

Reset PSF

  Resets the PSF to a normal Lorentzian function before the next R-L optimisation cycle.

## RAAR Mask with Partial Coherence Optimisation (RAAR Mask PC)

RAAR Mask with Partial Coherence Optimisation (RAAR Mask PC) algorithm. See here for more details.

Parameters:

Exp amp

  User provided path string to the input experimental data NumPy file.

Square Root Exp amp

  Causes the `Exp amp` array to be square rooted before phase retrieval commences. This is necessary if the array contains intensity measurements.

Support

  User provided path string to the support data NumPy file.

Mask

  User provided path string to the `mask` data NumPy file.

Beta

  Relaxation parameter for the RAAR algorithm.

Iterations

  Total number of iterations for which the algorithm will perform (not including R-L iterations).

Iterations preceding R-L optimisation

  Interval of iterations after which Richardson-Lucy optimisation commences in successive cycles.

R-L iterations

  Number of R-L iterations performed at each cycle.

Interval between R-L optimisation

  Number of iterations between each Richardson-Lucy optimisation cycle.

Initial PSF HWHM The initial point spread function (PSF) optimised using the R-L algorithm is a normal Lorentzian function (). The user can specify the HWHM of its Fourier transform ().

Zero fill end dimensions of PSF

  After optimising the PSF with the R-L algorithm, voxels upto a distance {i,j,k} from the perimeter of the PSF array are set to zero. This can improve stability of the algorithm.

Reset PSF

  Resets the PSF to a normal Lorentzian function before the next R-L optimisation cycle.

## Reweighted 2D Saddle Point Optimisation (SO2D)

Reweighted 2D Saddle Point Optimisation (SO2D) algorithm. See here for more details.

Parameters:

Exp amp

  User provided path string to the input experimental data NumPy file.

Square Root Exp amp

  Causes the `Exp amp` array to be square rooted before phase retrieval commences. This is necessary if the array contains intensity measurements.

Support

  User provided path string to the support data NumPy file.

Mask

  User provided path string to the `mask` data NumPy file.

Iterations

  Total number of iterations for which the algorithm will perform.

Step optimisation iterations

  Total number of iterations performed when optimising the step length.

Max step size

  Maximum size for the total step length ().

Initial Beta

  Relaxation parameter for the initial step ().

Max step increment

  Maximum amount by which the step can be incremented.

Min step increment

  Minimum amount by which the step can be incremented.

Exit Ratio

  Value below will halt step length optimisation.

Reset Ratio

  Value above will reset step length to that of the initial value (initial ).

Exit Error

  Value below will halt step length optimisation.

## Shrink Wrap

Shrink Wrap algorithm. See here for more details.

Parameters:

Exp amp

  User provided path string to the input experimental data NumPy file.

Square Root Exp amp

  Causes the `Exp amp` array to be square rooted before phase retrieval commences. This is necessary if the array contains intensity measurements.

Support

  User provided path string to the support data NumPy file.

Mask

  User provided path string to the `mask` data NumPy file.

Beta

  Relaxation parameter for the HIO algorithm.

Iterations

  Total number of iterations for which the algorithm will perform.

Cycle length

  Interval of iterations after which the support is updated.

Sigma

  Standard deviation of the Gaussian smoothing function for the support.

Threshold

  Fractional value below which `sequence data` is not used when creating the new support.

Algorithm

  Algorithm to use when performing the shrink wrapped phase retrieval.