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

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.

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

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.

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.

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.

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.

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.

class bonsu.phasing.CSHIO.SWCSHIO

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

Compressed Sensing HIO (CSHIO) algorithm. Shrink wrapped.