Scripting with Bonsu — Bonsu - The Interactive Phase Retrieval Suite 3.0 documentation

# Scripting with Bonsu

## Core concepts

Bonsu provides an object-oriented scripting interface to each algorithm for ease and interoperability with additional Python modules. To begin using this interface, import the phasing module as follows:

    >>> from bonsu import phasing

Once imported, the phasing module provides access to all phase retrieval algorithms. For a complete list see Library Reference – Phasing Algorithms.

Each algorithm will take a number of NumPy arrays as input. Input data is loaded and prepared in wrap around order. It is therefore also necessary to utilise the Wrap Data function. Note that the data must be stored in a “C”-ordered double precision complex Numpy array:

    >>> expdata = numpy.array(numpy.load("expdata.npy"), dtype=numpy.cdouble, copy=True, order='C')
    >>> numpy.sqrt(expdata, expdata)
    >>> expdata[:] = phasing.WrapArray(expdata)

The data `mask` in wrap around order is also needed:

    >>> mask = numpy.load("mask.npy")
    >>> mask[:] = phasing.WrapArray(mask)

An array to contain the reconstructed object is also needed and can be created in a number of ways, with data initialised as needed, i.e. random data or initial starting data from a previous reconstruction.

    >>> seqdata = numpy.empty_like(expdata)
    >>> seqdata[:] = 1.0 # initialise as 1.0.

To utilise the HIO Mask algorithm, create an instance as follows:

    >>> hio = phasing.HIOMask()

Then initialise the remaining parameters for 100 iterations:

    >>> hio.SetStartiter(0)
    >>> hio.SetNumiter(100)
    >>> hio.SetNumthreads(3)
    >>> hio.SetBeta(0.9)
    >>> hio.SetExpdata(expdata)
    >>> hio.SetSupport(support)
    >>> hio.SetMask(mask)
    >>> hio.SetSeqdata(seqdata)

To begin reconstruction we first prepare the algorithm as follows:

    >>> hio.Prepare()

Execution then follows:

    >>> hio.Start()

In a threaded or non-blocking use of the algorithm, it is possible the pause, resume and stop the reconstruction using the following methods:

    >>> hio.Pause()
    >>> hio.Resume()
    >>> hio.Stop()

The output of the reconstruction is saved as follows:

    >>> numpy.save("output.npy", seqdata)

Each algorithm can use `Shrink Wrap` to modify the support during reconstruction. Prefix the algorithm name with `SW` to utilise the `Shrink Wrap` version of the algorithm. For example, to use the `Shrink Wrap` version of the HIO Mask algorithm, import and instantiate the following:

    >>> swhio = phasing.SWHIOMask()

Then initialise the remaining parameters as follows:

    >>> swhio.SetStartiter(0)
    >>> swhio.SetNumiter(100)
    >>> swhio.SetNumthreads(3)
    >>> swhio.SetExpdata(expdata)
    >>> swhio.SetSupport(support)
    >>> swhio.SetMask(mask)
    >>> swhio.SetSeqdata(seqdata)
    >>> swhio.Prepare()

Methods unqiue to the `Shrink Wrap` implementation that require initialisation are as follows:

    >>> swhio.SetSWCyclelength(20)
    >>> swhio.SetSWThreshold(0.2)
    >>> swhio.SetSWSigma(3.0)

To begin reconstruction we also first prepare the `Shrink Wrap` algorithm as follows:

    >>> swhio.SWPrepare()

Execution then follows:

    >>> swhio.SWStart()

## Class Reference

### Abstract Classes

class `bonsu.phasing.abstract.` `PhaseAbstract`

  Bases: `object`

  Phasing Base Class

  `Prepare`()

    Prepare algorithm.

  `SetStartiter`(startiter)

    Set the starting iteration number.

  `SetNumiter`(numiter)

    Set the number of iterations of the algorithm to perform.

  `SetNumthreads`(nthreads)

    Set the number of FFTW threads.

  `SetSeqdata`(seqdata)

    Set the reconstruction data array.

  `GetSeqdata`()

    Get the reconstruction data array.

  `SetExpdata`(expdata)

    Set the raw experimental amplitude data array.

  `GetExpdata`()

    Get the raw experimental amplitude data array.

  `SetSupport`(support)

    Set the support array.

  `GetSupport`()

    Get the support array.

  `SetMask`(mask)

    Set the mask data array.

  `GetMask`()

    Set the mask data array.

  `SetBeta`(beta)

    Set beta relaxation parameter.

  `GetBeta`()

    Get beta relaxation parameter.

  `Pause`()

    Pause the reconstruction process.

  `Resume`()

    Resume the reconstruction process.

  `Start`()

    Start the reconstruction process.

  `Stop`()

    Stop the reconstruction process.

class `bonsu.phasing.abstract.` `PhaseAbstractPC`

  Bases: `bonsu.phasing.abstract.PhaseAbstract`

  Phasing Partial Coherence Base Class

  `SetPSF`(psf)

    Set point-spread function from data array.

  `GetPSF`()

    Get point-spread function from data array.

  `LorentzFillPSF`()

    Create a point-spread function with Lorentz distribution. This will use the HWHM specified using SetGammaHWHM.

  `SetNumiterRLpre`(niterrlpre)

    Set the number of iterations before RL optimisation.

  `GetNumiterRLpre`()

    Get the number of iterations before RL optimisation.

  `SetNumiterRL`(niterrl)

    Set the number of RL iterations.

  `GetNumiterRL`()

    Get the number of RL iterations.

  `SetNumiterRLinterval`(niterrlinterval)

    Set number of iterations between each RL optimisation cycle.

  `GetNumiterRLinterval`()

    Get number of iterations between each RL optimisation cycle.

  `SetGammaHWHM`(gammaHWHM)

    Set the half-width half-maximum of the Lorentz distribution. This is utilised in the LorentzFillPSF method.

  `GetGammaHWHM`()

    Get the half-width half-maximum of the Lorentz distribution.

  `SetPSFZeroEnd`(ze)

    Voxels upto a distance of [i,j,k] from the perimeter of the PSF array are set to zero. This can improve stability of the algorithm.

  `GetPSFZeroEnd`()

    Get zero voxels perimeter size.

  `Prepare`()

    Prepare algorithm.

class `bonsu.phasing.ShrinkWrap.` `ShrinkWrap`

  Shrink Wrap algorithm.

  `SetSWCyclelength`(cycle)

    Set interval of iterations after which the support is updated.

  `GetSWCyclelength`()

    Get interval of iterations after which the support is updated.

  `SetSWSigma`(sigma)

    Set standard deviation of the Gaussian smoothing function for the support.

  `GetSWSigma`()

    Get standard deviation of the Gaussian smoothing function for the support.

  `SetSWThreshold`(thresh)

    Set fractional value below which sequence data is not used when creating the new support.

  `GetSWThreshold`()

    Get fractional value below which sequence data is not used when creating the new support.

  `SWPrepare`()

    Prepare shrink wrap algorithm.

  `SWStart`()

    Start the shrink wrap reconstruction process.

### Hybrid Input-Output Classes

class `bonsu.phasing.HIO.` `HIO`

  Bases: `bonsu.phasing.abstract.PhaseAbstract`

  Fienup’s hybrid input-output (HIO) algorithm.

class `bonsu.phasing.HIO.` `SWHIO`

  Bases: `bonsu.phasing.HIO.HIO`, `bonsu.phasing.ShrinkWrap.ShrinkWrap`

  Fienup’s hybrid input-output (HIO) algorithm. Shrink wrapped.

class `bonsu.phasing.HIO.` `HIOMask`

  Bases: `bonsu.phasing.abstract.PhaseAbstract`

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

class `bonsu.phasing.HIO.` `SWHIOMask`

  Bases: `bonsu.phasing.HIO.HIOMask`, `bonsu.phasing.ShrinkWrap.ShrinkWrap`

  Fienup’s hybrid input-output (HIO) algorithm with the addition of a Fourier space constraint mask. Shrink wrapped.

class `bonsu.phasing.HIO.` `HIOPlus`

  Bases: `bonsu.phasing.abstract.PhaseAbstract`

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

class `bonsu.phasing.HIO.` `SWHIOPlus`

  Bases: `bonsu.phasing.HIO.HIOPlus`, `bonsu.phasing.ShrinkWrap.ShrinkWrap`

  Fienup’s hybrid input-output (HIO) algorithm with non-negativity constraint and with the addition of a Fourier space constraint mask. Shrink wrapped.

class `bonsu.phasing.HIO.` `PCHIO`

  Bases: `bonsu.phasing.abstract.PhaseAbstract`

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

  `SetMaxphase`(max)

    Set phase maximum.

  `GetMaxphase`()

    Get phase maximum.

  `SetMinphase`(min)

    Set phase minimum.

  `GetMinphase`()

    Get phase minimum.

class `bonsu.phasing.HIO.` `SWPCHIO`

  Bases: `bonsu.phasing.HIO.PCHIO`, `bonsu.phasing.ShrinkWrap.ShrinkWrap`

  Fienup’s hybrid input-output (HIO) algorithm with phase constraint and with the addition of a Fourier space constraint mask. Shrink wrapped.

class `bonsu.phasing.HIO.` `PGCHIO`

  Bases: `bonsu.phasing.abstract.PhaseAbstract`

  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.

  `SetMaxphase`(max)

    Set phase maximum.

  `GetMaxphase`()

    Get phase maximum.

  `SetMinphase`(min)

    Set phase minimum.

  `GetMinphase`()

    Get phase minimum.

  `SetQ`(q)

    Set Q-vector tuple

  `GetQ`()

    Get Q-vector tuple

  `Prepare`()

    Prepare algorithm.

class `bonsu.phasing.HIO.` `SWPGCHIO`

  Bases: `bonsu.phasing.HIO.PGCHIO`, `bonsu.phasing.ShrinkWrap.ShrinkWrap`

  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. Shrink wrapped.

class `bonsu.phasing.HIO.` `HIOMaskPC`

  Bases: `bonsu.phasing.abstract.PhaseAbstractPC`

  HIO Mask with Partial Coherence Optimisation.

class `bonsu.phasing.HIO.` `SWHIOMaskPC`

  Bases: `bonsu.phasing.HIO.HIOMaskPC`, `bonsu.phasing.ShrinkWrap.ShrinkWrap`

  HIO Mask with Partial Coherence Optimisation. Shrink wrapped.

  `Start`()

    Start the reconstruction process.

### Error Reduction Classes

class `bonsu.phasing.ER.` `ER`

  Bases: `bonsu.phasing.abstract.PhaseAbstract`

  Error Reduction (ER) algorithm.

class `bonsu.phasing.ER.` `SWER`

  Bases: `bonsu.phasing.ER.ER`, `bonsu.phasing.ShrinkWrap.ShrinkWrap`

  Error Reduction (ER) algorithm. Shrink wrapped.

class `bonsu.phasing.ER.` `ERMask`

  Bases: `bonsu.phasing.abstract.PhaseAbstract`

  Error Reduction (ER) algorithm with the addition of a Fourier space constraint mask.

class `bonsu.phasing.ER.` `SWERMask`

  Bases: `bonsu.phasing.ER.ERMask`, `bonsu.phasing.ShrinkWrap.ShrinkWrap`

  Error Reduction (ER) algorithm with the addition of a Fourier space constraint mask. Shrink wrapped.

class `bonsu.phasing.ER.` `POER`

  Bases: `bonsu.phasing.abstract.PhaseAbstract`

  Phase Only Error Reduction (POER) algorithm with the addition of a Fourier space constraint mask.

class `bonsu.phasing.ER.` `ERMaskPC`

  Bases: `bonsu.phasing.abstract.PhaseAbstractPC`

  ER Mask with Partial Coherence Optimisation algorithm.

class `bonsu.phasing.ER.` `SWERMaskPC`

  Bases: `bonsu.phasing.ER.ERMaskPC`, `bonsu.phasing.ShrinkWrap.ShrinkWrap`

  ER Mask with Partial Coherence Optimisation algorithm. Shrink wrapped.

  `Start`()

    Start the reconstruction process.

### Hybrid Project-Reflection Classes

class `bonsu.phasing.HPR.` `HPR`

  Bases: `bonsu.phasing.abstract.PhaseAbstract`

  Hybrid Projection Reflection (HPR) algorithm.

class `bonsu.phasing.HPR.` `SWHPR`

  Bases: `bonsu.phasing.HPR.HPR`, `bonsu.phasing.ShrinkWrap.ShrinkWrap`

  Hybrid Projection Reflection (HPR) algorithm. Shrink wrapped.

class `bonsu.phasing.HPR.` `HPRPC`

  Bases: `bonsu.phasing.abstract.PhaseAbstractPC`

  HPR Mask with Partial Coherence Optimisation algorithm.

class `bonsu.phasing.HPR.` `SWHPRPC`

  Bases: `bonsu.phasing.HPR.HPRPC`, `bonsu.phasing.ShrinkWrap.ShrinkWrap`

  HPR Mask with Partial Coherence Optimisation algorithm. Shrink wrapped.

  `Start`()

    Start the reconstruction process.

### Relaxed Average Alternating Reflection Classes

class `bonsu.phasing.RAAR.` `RAAR`

  Bases: `bonsu.phasing.abstract.PhaseAbstract`

  Relaxed Average Alternating Reflection (RAAR) algorithm.

class `bonsu.phasing.RAAR.` `SWRAAR`

  Bases: `bonsu.phasing.RAAR.RAAR`, `bonsu.phasing.ShrinkWrap.ShrinkWrap`

  Relaxed Average Alternating Reflection (RAAR) algorithm. Shrink wrapped.

class `bonsu.phasing.RAAR.` `RAARPC`

  Bases: `bonsu.phasing.abstract.PhaseAbstractPC`

  RAAR Mask with Partial Coherence Optimisation algorithm.

class `bonsu.phasing.RAAR.` `SWRAARPC`

  Bases: `bonsu.phasing.RAAR.RAARPC`, `bonsu.phasing.ShrinkWrap.ShrinkWrap`

  RAAR Mask with Partial Coherence Optimisation algorithm. Shrink wrapped.

  `Start`()

    Start the reconstruction process.

### CSHIO Classes

class `bonsu.phasing.CSHIO.` `CSHIO`

  Bases: `bonsu.phasing.abstract.PhaseAbstract`

  Compressed Sensing HIO (CSHIO) algorithm.

  `SetPnorm`(p)

    Set p-norm of the Lebesgue space.

  `GetPnorm`()

    Get p-norm of the Lebesgue space.

  `SetEpsilon`(epsilon)

    Set positive relaxation parameter (epsilon) for the weighted p-norm.

  `GetEpsilon`()

    Get positive relaxation parameter (epsilon) for the weighted p-norm.

  `SetEpsilonmin`(epsilonmin)

    Set minimum value that epsilon can take.

  `GetEpsilonmin`()

    Set minimum value that epsilon can take.

  `SetDivisor`(d)

    Set amount by which epsilon is divided when constraint is met.

  `GetDivisor`()

    Get amount by which epsilon is divided when constraint is met.

  `SetEta`(eta)

    Set parameter in the divisor condition.

  `GetEta`()

    Get parameter in the divisor condition.

  `Prepare`()

    Prepare algorithm.

class `bonsu.phasing.CSHIO.` `SWCSHIO`

  Bases: `bonsu.phasing.CSHIO.CSHIO`, `bonsu.phasing.ShrinkWrap.ShrinkWrap`

  Compressed Sensing HIO (CSHIO) algorithm. Shrink wrapped.