iter Package¶
Package containing algorithms and cost functions for iterative optimisation. This section is split into two parts, a description of the optimisation methods and a description of the objective function classes.
Iterative optimisation methods¶
The package contains a series of iterative optimisation algorithms.
There are currently two types of iterative optimisation algorithms,
methods that attempt to approximate some target farfield and methods
which attempt to combine a series of SLM patterns.
The former can also be used to combine a series of patterns by first
generating a target farfield, for example
using otslm.tools.combine()
:
lin = otslm.simple.linear(sz, 10);
lg = otslm.simple.linear(sz, 10) + otslm.simple.lgmode(sz, 3, 0);
% Convert to complex amplitudes (could use finalize)
lin = exp(1i*2*pi*lin);
lg = exp(1i*2*pi*lg);
target = otslm.tools.combine({lin, lg}, 'method', 'farfield');
The methods which inherit from IterBase
have an objective
function property.
For some methods the objective is required for the method to work,
for other methods the objective is optional and can be used to
track progress of the method.
The objective can be set on construction or by setting the objective
property. See the Objective functions
section for available objectives.
For an example of how to use these iterative methods, see
examples.iterative
, examples.iter_combine
and
GerchbergSaxton examples.
A minimal example for methods which attempt to generate a particular
farfield is shown below:
sz = [512, 512];
incident = ones(sz);
prop = otslm.tools.prop.FftForward.simpleProp(zeros(sz));
vismethod = @(U) prop.propagate(U .* incident);
target = otslm.simple.aperture(sz, sz(1)/20);
gs = otslm.iter.GerchbergSaxton(target, 'adaptive', 1.0, ...
'vismethod', vismethod);
Table 1 compares the runtime and required number of iterations for some of the iterative optimisation methods. This table is based on Di Leonardo et al. 2007, a more detailed discussion can be found in the reference. This is only a guide, some methods may work better than other methods under certain circumstances. For instance, the direct search method can be used for fine tuning the output of other methods but takes too long for practical use when given a bad initial guess. The combination algorithm and 2D optimisation algorithms have been combined, actual performance will be different but similar. There are a range of different extensions to the described methods which may improve performance for particular problems, such as using a superpixel style approach with the Direct Search algorithm.
Iterative methods  Num. Iterations  Typical Runtime 

GerchbergSaxton  30  5 s 
Weighted GS  30  5 s 
Adaptiveadaptive  30  5 s 
Bowman 2017  < 200  2 m 
Simulated Annealing  \(10^4\)  10 m 
Direct Search  \(10^9\)  days 
Methods
GerchbergSaxton¶
The GerchbergSaxton algorithm is an iterative algorithm that involves iterating between the nearfield and farfield and applying constraints to the fields after each iteration. The constraints could include a particular incident illumination or a desired farfield intensity or phase pattern. Components that are not constrained are free to change. The algorithm was originally described in
R. W. Gerchberg, O. A Saxton W., A practical algorithm for the determination of phase from image and diffraction plane pictures, Optik 35(1971) 237250 (Nov 1971).
Details about the algorithm can be found on the Wikipedia page. A sketch of the algorithm for generating a target amplitude pattern using a phaseonly device is shown below:
 Generate initial guess for the SLM phase pattern \(P\).
 Calculate output for phase pattern: \(\text{Proj}(P) \rightarrow O\).
 Multiply output phase by target amplitude: \(T\frac{O}{O} \rightarrow Q\).
 Calculate the complex amplitude required to generate \(Q\): \(\text{Inv}(Q) \rightarrow I\).
 Calculate new guess from the phase of \(I\): \(\text{Angle}(I) \rightarrow P\).
 Goto step 2 until converged.
\(\text{Proj}\) and \(\text{Inv}\) are the forward and inverse propagation methods, these could be, for example, the forward and inverse Fourier transforms. A constraint for the incident illumination can be added to the forward propagator or the constraint can be added at another step. There are other variants for generating a target phase field or applying other constraints to the farfield. If this guess is symmetric, these symmetries will influence the final output, this can be useful for generating symmetric target fields.
GerchbergSaxton
also implements the adaptiveadaptive
algorithm, which we can enable by
setting the adaptive
parameter to a nonunity value.
The adaptiveadaptive algorithm is similar to the above except
step 3 mixes the propagator amplitude output with the target amplitude
instead of replacing it
where \(\alpha\) is the adaptiveadaptive factor.

class
otslm.iter.
GerchbergSaxton
(target, varargin)¶ Implementation of GerchbergSaxton and AdaptiveAdaptive algorithms Inherits from
IterBase
. Methods
 run() – Run the iterative method
 Properties
 adaptive – Adaptiveadaptive factor (1 for GerchbergSaxton)
 Inherited properties
 guess – Best guess at hologram pattern
 target – Target pattern the method tries to approximate
 vismethod – Method used to do the visualisation
 invmethod – Method used to calculate initial guess/inversevisualisation
 objective – Objective function used to evaluate fitness
 fitness – Fitness evaluated after every iteration
See also GerchbergSaxton.

GerchbergSaxton
(target, varargin)¶ Construct a new instance of the GerchbergSaxton iterative method
 Usage
 mtd = GerchbergSaxton(target, …)
 Parameters
 target – target pattern
 Optional named arguments
 adaptive num AdaptiveAdaptive factor. Default: 1.0, i.e. the method is GerchbergSaxton.
 guess im Initial guess at complex amplitude pattern. If not image is supplied, a guess is created using invmethod.
 vismethod fcn Function to calculate farfield. Takes one argument: the complex amplitude nearfield. Default: @otslm.tools.prop.FftForward.simpleProp.propagate
 invmethod fcn Function to calculate nearfield. Takes one argument: the complex amplitude farfield. Default: @otslm.tools.prop.FftInverse.simpleProp.propagate
 objective fcn Objective function to measure fitness. Default: @otslm.iter.objectives.FlatIntensity
DirectSearch¶
The direct search algorithm involves choosing a pixel, trying a range of possible values for that pixel, and keeping the choice which maximises some objective function. This is a expensive procedure, on a device with 512x512 pixels and 256 values per pixel, cycling over each pixel requires 67 million Fourier transforms. The process is further complicated since the optimal value for any pixel is not independent of every other pixel. However, this method can be useful for further improving a good guess, such as the output of one of the other methods.
A rough outline for the procedure is
 Choose an initial guess, \(P\)
 Randomly select a pixel to modify
 Generate a set of patterns \(P_i\) with a set \(\{i\}\) of different pixel values.
 Propagate these patterns and calculate the fitness \(F_i\)
 Choose the pattern which maximises the fitness \(P_j \rightarrow P\) where \(j = \text{argmax}_i F_i\).
 Go to 2 until converged

class
otslm.iter.
DirectSearch
(target, varargin)¶ Optimiser to search through each pixel value to optimise hologram Inherits from
IterBase
.This method randomly selects a pixel in the pattern and then tries every available level. The pixel value kept is the pixel value whic gives the best fitness.
The algorithm is described in Di Leonardo, et al., Opt. Express 15, 19131922 (2007)
 Methods
 run() – Run the iterative method
 Properties
 levels – Discrete levels that will be search in optimisation
 Inherited properties
 guess – Best guess at hologram pattern
 target – Target pattern the method tries to approximate
 vismethod – Method used to do the visualisation
 invmethod – Method used to calculate initial guess/inversevisualisation
 objective – Objective function used to evaluate fitness
 fitness – Fitness evaluated after every iteration
See also DirectSearch and
SimulatedAnnealing
.
DirectSearch
(target, varargin)¶ Construct a new instance of the DirectSearch iterative method
 Usage
 mtd = DirectSearch(target, …) attempts to produce the target using the Direct Search algorithm.
 Optional named arguments:
 levels num – Number of discrete phase levels or array of levels between pi and pi. Default: 256.
 guess im – Initial guess at complex amplitude pattern. If not image is supplied, a guess is created using invmethod.
 vismethod fcn – Function to calculate farfield. Takes one argument: the complex amplitude nearfield. Default: @otslm.tools.prop.FftForward.simpleProp.propagate
 invmethod fcn – Function to calculate nearfield. Takes one argument: the complex amplitude farfield. Default: @otslm.tools.prop.FftInverse.simpleProp.propagate
 objective fcn – Objective function to measure fitness. Default: @otslm.iter.objectives.FlatIntensity
SimulatedAnnealing¶
Simulated annealing is a stochastic method that can be useful for optimising systems with many degrees of freedom (such as patterns with many nonindependent pixels). A description of the method can be found on the wikipedia page. The algorithm is analogous to cooling (annealing) of solids and chooses new state probabilistically depending on a temperature parameter. An outline follows
 Starting with an initial pattern \(P\) and temperature \(T\)
 Pick a random pattern which is similar to the current pattern
 Compare fitness of two patterns \(F_1\) and \(F_2\)
 Accept the new pattern if \(P(F_1, F_2, T) > \text{rand}(0, 1)\)
 Goto 2 until converged, gradually reducing temperature
There are several parameters that can be chosen which strongly affect the performance and convergence of the algorithm. The implementation currently only supports the following function
The change in temperature can be controlled via the
temperatureFcn
optional parameter.
This implementation could be improved and we welcome suggestions.

class
otslm.iter.
SimulatedAnnealing
(target, varargin)¶ Optimise the pattern using simulated annealing. Inherits from
IterBase
. Methods
 run() – Run the iterative method
 Properties
 levels – Discrete levels that will be search in optimisation
 temperature – Current temperature of the system
 maxTemperature – Scaling factor for new pattern guesses
 temperatureFcn – Function used to calculate temperature in iteration
 lastFitness – The fitness associated with the current guess
 guess – Best guess at hologram pattern
 target – Target pattern the method tries to approximate
 vismethod – Method used to do the visualisation
 invmethod – Method used to calculate initial guess/inversevisualisation
 objective – Objective function used to evaluate fitness
 fitness – Fitness evaluated after every iteration
See also SimulatedAnnealing

SimulatedAnnealing
(target, varargin)¶ Construct a new instance of the SimulatedAnnealing iterative method
mtd = SimulatedAnnealing(target, …) attempts to produce the target using the Simulated Annealing algorithm.
 Optional named arguments:
 levels num Number of discrete levels or array of levels between pi and pi. Default: 256.
 temperature num Initial temperature of the solver.
 guess im Initial guess at complex amplitude pattern. If not image is supplied, a guess is created using invmethod.
 vismethod fcn Function to calculate farfield. Takes one argument: the complex amplitude nearfield. Default: @otslm.tools.prop.FftForward.simpleProp.propagate
 invmethod fcn Function to calculate nearfield. Takes one argument: the complex amplitude farfield. Default: @otslm.tools.prop.FftInverse.simpleProp.propagate
 objective fcn Objective function to measure fitness. Default: @otslm.iter.objectives.FlatIntensity

static
simpleTemperatureFcn
(scale, decay)¶ Returns a exponentially decaying temperature function
fcn = simpleTemperatureFcn(scale, decay) creates a exponentially decaying temperature function. Scale is the initial temperature and decay is the exponential decay rate.
GerchbergSaxton3d¶
This function implements the 3D analog of the GerchbergSaxton method. The method is described in
Hao Chen et al 2013 J. Opt. 15 035401
and
Graeme Whyte and Johannes Courtial 2005 New J. Phys. 7 117
For an outline of the GerchbergSaxton algorithm, see
GerchbergSaxton
.

class
otslm.iter.
GerchbergSaxton3d
(target, varargin)¶ Implementation of 3D GerchbergSaxton and AdaptiveAdaptive algorithms Inherits from
GerchbergSaxton
andIterBaseEwald
.This algorithm attempts to recreate the target volume using the 3D analog of the GerchbergSaxton algorithm.
See Hao Chen et al 2013 J. Opt. 15 035401 and Graeme Whyte and Johannes Courtial 2005 New J. Phys. 7 117
 Methods
 run() – Run the iterative method
 Properties
 adaptive – Adaptiveadaptive factor (1 for GerchbergSaxton)
 Inherited properties
 guess – Best guess at hologram pattern
 target – Target pattern the method tries to approximate
 vismethod – Method used to do the visualisation
 invmethod – Method used to calculate initial guess/inversevisualisation
 objective – Objective function used to evaluate fitness
 fitness – Fitness evaluated after every iteration
See also GerchbergSaxton3d and
GerchbergSaxton
.
GerchbergSaxton3d
(target, varargin)¶ Construct a new instance of the GerchbergSaxton3d iterative method
 USage
 mtd = GerchbergSaxton3d(target, …)
 Parameters
 target – target pattern to try and generate
 Optional named arguments
 adaptive num – AdaptiveAdaptive factor. Default: 1.0, i.e. the method is GerchbergSaxton.
 guess im – Initial guess at complex amplitude pattern. If not image is supplied, a guess is created using invmethod.
 vismethod fcn – Function to calculate farfield. Takes one argument: the complex amplitude nearfield. Default: @otslm.tools.prop.FftEwaldForward.simpleProp.propagate
 invmethod fcn – Function to calculate nearfield. Takes one argument: the complex amplitude farfield. Default: @otslm.tools.prop.FftEwaldInverse.simpleProp.propagate
 objective fcn – Optional objective function to measure fitness. Default: @otslm.iter.objectives.FlatIntensity
CombineGerchbergSaxton¶
This function implements the GerchbergSaxton algorithm and similar
iterative optimisers for generating point traps.
The method can be used to combine a set of SLM patterns \(\phi_m\)
into a single pattern in a similar way to otslm.tools.combine()
.
Starting with an initial guess at the phase pattern \(\phi^0\)
the method proceeds as
where
and \(x, y\) are the SLM pixel coordinates and \(\eta_n^j\) is an optional parameter for AdaptiveAdaptive or weighted versions of the algorithm (for GerchbergSaxton \(\eta = 1\)). To calculate the pattern we simply need to iterative the above equation for a few steps.
There are two relatively simple extensions to this algorithm. First is the AdaptiveAdaptive algorithm which involves setting
where \(\alpha\) is a factor between 0 and 1. The second extension is the weighted GerchbergSaxton algorithm which involves setting
where \(\langle \cdot \rangle\) denotes the average and we recalculate \(\eta\) at each iteration starting with an initial value of 1.
To use the method we need to pass in a set of patterns to combine. For instance, we could have a set of 2 traps:
lin1 = otslm.simple.linear(sz, 10);
lin2 = otslm.simple.linear(sz, 5);
components = zeros([sz, 2]);
components(:, :, 1) = lin1;
components(:, :, 2) = lin1;
Then to use the iterative method we would run
mtd = otslm.iter.CombineGerchbergSaxton(2*pi*components, ...
'weighted', true, 'adaptive', 1.0);
mtd.run(10);
imagesc(mtd.phase);
For a more complete example see examples.iter_combine
.
A more detailed discussion of these algorithms can be found in
R. Di Leonardo, et al., Opt. Express 15 (4) (2007) 19131922. https://doi.org/10.1364/OE.15.001913

class
otslm.iter.
CombineGerchbergSaxton
(components, varargin)¶ Implementation of GerchbergSaxton type combination algorithms. Inherits from
IterCombine
.This includes GerchbergSaxton, AdaptiveAdaptive and weighted GerchbergSaxton algorithms.
For details about these algorithms, see R. Di Leonardo, et al., Opt. Express 15 (4) (2007) 19131922. https://doi.org/10.1364/OE.15.001913
 Properties
 adaptive (numeric) – adaptiveadaptive factor.
 weighted (logical) – if the method is weighted GerchbergSaxton.
 Methods (inherited)
 run() – Run the iterative method
 showFitness() – Show the fitness graph
 Properties (inherited)
 components (real: 0, 2*pi) – NxMxD matrix of D patterns to be combined.
 guess – Best guess at hologram pattern (complex)
 target – Target pattern for estimating fitness (complex, optional)
 vismethod – Method used to do the visualisation
 invmethod – Method used to calculate initial guess/inversevisualisation
 phase – Phase of the best guess (real: 0, 2*pi)
 amplitude – Amplitude of the best guess (real)
 objective – Objective function used to evaluate fitness or []
 fitness – Fitness evaluated after every iteration or []
See also CombineGerchbergSaxton and
GerchbergSaxton
.
CombineGerchbergSaxton
(components, varargin)¶ Construct a new GerchbergSaxton combination iterative method.
 Usage
 mtd = IterCombine(components, …)
 Parameters
 components (real: 0, 2*pi) – NxMxD array of D phase patterns to be combined. Phase patterns should have range [0, 2*pi] or equivalent.
 Optional named arguments
 adaptive num AdaptiveAdaptive factor. Default: 1.0, i.e. the method is GerchbergSaxton.
 weighted (logical) – If the method should use weighted GerchbergSaxton. Default: false.
 target (complex) – approximate pattern for the target.
This is only used for estimating the current fitness.
Default:
otslm.tools.combine(components, 'method', 'farfield')
.  guess (complex) – Initial guess at combination of patterns.
Default:
exp(2*pi*1i*random_super)
whererandom_super = tools.combine(components, 'method', 'rsuper')
 vismethod fcn Function to calculate farfield. Takes one argument: the complex amplitude nearfield. Optional, only used for fitness evaluation. Default: @otslm.tools.prop.FftForward.simpleProp.propagate
 invmethod fcn Function to calculate nearfield. Takes one argument: the complex amplitude farfield. Optional, not used. Default: @otslm.tools.prop.FftInverse.simpleProp.propagate
 objective fcn Objective function to measure fitness. Default: @otslm.iter.objectives.FlatIntensity
IterBase¶
This is the base class for iterative methods. It is an abstract class and cannot be directly instantiated. To implement your own iterative method class, inherit from this class and implement the abstract methods/properties.

class
otslm.iter.
IterBase
(varargin)¶ Base class for iterative algorithm classes. Inherits from
handle
. Methods
 run() – Run the iterative method
 showFitness() – Show the fitness graph
 Properties
 guess – Best guess at hologram pattern (complex)
 target – Target pattern the method tries to approximate (complex)
 vismethod – Method used to do the visualisation
 invmethod – Method used to calculate initial guess/inversevisualisation
 phase – Phase of the best guess (real: 0, 2*pi)
 amplitude – Amplitude of the best guess (real)
 objective – Objective function used to evaluate fitness or []
 fitness – Fitness evaluated after every iteration or []
 Abstract methods
 iteration() – run a single iteration of the method

IterBase
(varargin)¶ Constructor for iterative algorithm (abstract) base class
 Usage
 mtd = IterBase(target, …)
 Parameters
 target – target pattern to generate
 Optional named arguments
 guess im Initial guess at complex amplitude pattern. If not image is supplied, a guess is created using invmethod.
 vismethod fcn Function to calculate farfield. Takes one argument: the complex amplitude nearfield. Default: @otslm.tools.prop.FftForward.simpleProp.propagate
 invmethod fcn Function to calculate nearfield. Takes one argument: the complex amplitude farfield. Default: @otslm.tools.prop.FftInverse.simpleProp.propagate
 objective fcn Objective function to measure fitness. Default: @otslm.iter.objectives.FlatIntensity

evaluateFitness
(mtd, varargin)¶ Evaluate the fitness of the current guess
 Usage
score = mtd.evaluateFitness() visualises the current guess and evaluate the fitness.
score = mtd.evaluateFitness(guess) evaluate the fitness of the given guess. If guess is a stack of matrices, the returned score is a vector with size(trial, 3) elements. Guess should be a complex amplitude.

run
(mtd, num_iterations, varargin)¶ Run the method for a specified number of iterations
 Usage
 result = mtd.run(num_iterations, …) run for the specified number of iterations.
 Parameters
 num_iterations (numeric) – Number of iterations
 Optional named arguments
 show_progress bool display a figure with optimisation progress

stopIterations
(mtd, src, event)¶ Callback for the stop button in showFitness
 Usage
 mtd.stopIterations(…) arguments are ignored.
IterCombine¶
This is the base class for iterative methods which combine multiple
input pattern.
It is an abstract class inheriting from IterBase
however
not all properties are needed/used by classes inheriting from this
method.
For instance, the CombineGerchbergSaxton
class only uses the
vismethod
to calculate the fitness when an objective function is
supplied.
If the objective is omitted the method doesn’t calculate the fitness
and doesn’t need vismethod
or invmethod
.

class
otslm.iter.
IterCombine
(components, varargin)¶ Base class for iterative combination algorithms. Inherits from
IterBase
.Iterative methods that inherit from this class attempt to combine a set of SLM phase patterns \(\phi_m\) into a single phase pattern which generates a farfield phase pattern approximating the combination of each input phase pattern.
The target field is a optional and is only used for estimating fitness of the generated pattern.
 Methods (inherited)
 run() – Run the iterative method
 showFitness() – Show the fitness graph
 Properties
 components (real: 0, 2*pi) – NxMxD matrix of D patterns to be combined.
 Properties (inherited)
 guess – Best guess at hologram pattern (complex)
 target – Target pattern for estimating fitness (complex, optional)
 vismethod – Method used to do the visualisation
 invmethod – Method used to calculate initial guess/inversevisualisation
 phase – Phase of the best guess (real: 0, 2*pi)
 amplitude – Amplitude of the best guess (real)
 objective – Objective function used to evaluate fitness or []
 fitness – Fitness evaluated after every iteration or []
 Abstract methods
 iteration() – run a single iteration of the method

IterCombine
(components, varargin)¶ Constructor for iterative combination algorithms (abstract) base class
 Usage
 mtd = IterCombine(components, …)
 Parameters
 components (real: 0, 2*pi) – NxMxD array of D phase patterns to be combined. Phase patterns should have range [0, 2*pi] or equivalent.
 Optional named arguments
 target (complex) – approximate pattern for the target.
This is only used for estimating the current fitness.
Default:
otslm.tools.combine(components, 'method', 'farfield')
.  guess (complex) – Initial guess at combination of patterns.
Default:
exp(2*pi*1i*random_super)
whererandom_super = tools.combine(components, 'method', 'rsuper')
 vismethod fcn Function to calculate farfield. Takes one argument: the complex amplitude nearfield. Optional: only used for fitness evaluation. Default: @otslm.tools.prop.FftForward.simpleProp.propagate
 invmethod fcn Function to calculate nearfield. Takes one argument: the complex amplitude farfield. Optional: not used. Default: @otslm.tools.prop.FftInverse.simpleProp.propagate
 objective fcn Objective function to measure fitness. Default: @otslm.iter.objectives.FlatIntensity
 target (complex) – approximate pattern for the target.
This is only used for estimating the current fitness.
Default:
IterBaseEwald¶
This is the base class for iterative methods that 3D Fourier transforms
and an Ewald sphere farfield mapping.
This is class can be combined with IterBase
to provide
the 3D specialisation.
Currently only used by GerchbergSaxton3d
.

class
otslm.iter.
IterBaseEwald
(target, varargin)¶ Abstract base class for 3D Ewald iterative algorithm classes Inherits from
IterBase
. Methods
 run() – Run the iterative method
 Properties
 guess – Best guess at hologram pattern (complex, matrix)
 target – Target pattern the method tries to approximate (volume)
 vismethod – Method used to do the visualisation
 invmethod – Method used to calculate initial guess/inversevisualisation
 phase – Phase of the best guess (real: 0, 2*pi)
 amplitude – Amplitude of the best guess (real)
 objective – Objective function used to evaluate fitness or []
 fitness – Fitness evaluated after every iteration or []
 Abstract methods
 iteration() – run a single iteration of the method

IterBaseEwald
(target, varargin)¶ Abstract constructor for 3D iterative algorithm base class
 Usage
 mtd = IterBaseEwald(target, …) constructs a new instance. target should be a 3D volume. Guess, if supplied, should be a 2D matrix for the pattern on the SLM.
 Optional named arguments:
 guess im Initial guess at complex amplitude pattern. If no image is supplied, a guess is created using invmethod.
 vismethod fcn Function to calculate farfield. Takes one argument: the complex amplitude nearfield. Default: @otslm.tools.prop.FftEwaldForward.simpleProp.propagate
 invmethod fcn Function to calculate nearfield. Takes one argument: the complex amplitude farfield. Default: @otslm.tools.prop.FftEwaldInverse.simpleProp.propagate
 objective fcn Objective function to measure fitness. Default: @otslm.iter.objectives.FlatIntensity
bsc¶
This function attempts to optimise the beam using vector spherical wave functions. The function may be unstable/change in future releases but demonstrates how OTT can be used with OTSLM.

otslm.iter.
bsc
(sz, target, varargin)¶ Optimisation in vector spherical wave function basis
Requires the optical tweezers toolbox (OTT).
 Usage
 [pattern, beam, coeffs] = bsc(target, …) attempt to produce target using a phase pattern. Returns the phase pattern matched to the beam (bsc) and optimised basis weighting coefficients.
 Parameters
 target – target pattern
 Optional named parameters
 ‘incident’ pattern – Incident illumination on SLM
 ‘roi’ func – Region to optimise (default: roiAll)
 ‘basis’ str – BSC basis to optimise in (default: vswf_lg)
 ‘basis_size’ num – Number of basis functions to use
 ‘polarisation’ [x y] – Polarisation of the basis functions
 ‘wavelength’ num – Wavelength in medium [m]
 ‘speed’ num – Speed in medium [m/s]
 ‘NA’ num – Numberical aperture of objective
 ‘pixel_size’ num – Size of pixels in target [m]
 ‘method’ str – Optimisation method to use
 ‘radius’ num – Radius for hologram unwrapping (default: 1.0)
bowman2017¶
This function provides an interface for Bowman, et al. Optics Express 25, 11692 (2017). This requires a suitable Python version and various libraries. The wrapper may be unstable and will hopefully be improved in future releases.

otslm.iter.
bowman2017
(target, varargin)¶ Wrapper for Bowman 2017 conjugate gradient implementation
See Bowman, et al. Optics Express 25, 11692 (2017) If you use this method, please consider citing Bowman 2017.
Warning
This wrapper may be unstable and may change in future releases.
 Usage
 pattern = bowman2017(target, …) attempt to generate the target using a phase pattern optimised using conjugate gradient method.
 Parameters
 target – target pattern to generate
 Optional named parameters
 ‘guess’ – Initial guess at the phase
 ‘iterations’ – Number of iterations (default: 200)
 ‘steepness’ – Steepness for Bowman cost function (default: 9.0)
 ‘incident’ – Incident illumination (default: ones)
 ‘roisize’ – Optimisation region size (default: min(size)/2)
Objective functions¶
Objective functions are contained in the otslm.iter.objectives
subpackage. These functions are used with the above optimisation
methods for both optimisation and diagnostics.
To evaluate the fitness (similarity) between a trial pattern and
a target, we can construct a new objective instance and call the
evaluate method. For example, using the Flatness
objective:
% Setup the trial and target
sz = [256, 256];
target = ones(sz);
trial = randn(sz) + 1.0;
% Setup the objective
obj = otslm.iter.objectives.Flatness('target', target);
% Evaluate the fitness
fitness = obj.evaluate(trial);
It is possible to reuse the objective multiple times or test the trial pattern against a different target pattern when evaluate is called:
new_target = zeros(sz);
fitness = obj.evaluate(trial, new_target);
Objective classes support a region of interest mask. The region of interest can either be a logical mask or a function which selects a region of the image, for example:
% Select only half of the image with a function
obj.roi = @(pattern) pattern(1:end/2, :)
fitness = obj.evaluate(trial);
% Use a logical array
obj.roi = otslm.simple.aperture(sz, 128);
fitness = obj.evaluate(trial);
Objectives
Objective base class¶

class
otslm.iter.objectives.
Objective
(varargin)¶ Abstract base class for optimisation objective functions.
To use this class, you need to inherit from it and implement the evaluate_internal function.
 Methods
 evaluate() – Evaluate the fitness of the specified pattern
 Properties
 target (numeric) – Target pattern to compare with (or [] for no default). This is only used if no target is provided in evaluate().
 type (enum) – Type of optimisation function (‘min’ or ‘max’) This property isn’t widely used (may change in future version). For now, most functions simply have this property set to ‘min’.
 roi (logicalemptyfunction_handle) – Region of interest to apply to
target and trial. Must be either a logical array the same size
as target, an empty matrix for no roi, or a function handle.
If roi is a function handle, the function should have the
signature
masked = roi(pattern)
. Calling the function should select elements from the pattern for comparison. The function is applied to both the target and the trial pattern.
 Abstract methods
 evaluate_internal() – Implementation called by evaluate().
Signature:
fitness = obj.evaluate_internal(target, trial)
. The roi has already been applied to the trial and target.
 evaluate_internal() – Implementation called by evaluate().
Signature:
See also Objective,
Intensity
andFlatness
.
Objective
(varargin)¶ Construct a new objective function instance
 Usage
 obj = Objective(…) construct a new objective function instance.
 Optional named arguments
 roi []  logical  function_handle – specify the roi to use when evaluating the fitness function. Can be a logical array or a function handle. Default: []
 target []  matrix – specify the target pattern for this objective. If not supplied, the target must be supplied when the evaluate function is called. Default: []

evaluate
(trial, target)¶ Evaluate the fitness of the specified trial pattern.
 Usage
 fitness = obj.evaluate(trial, [target]) evaluate the specified trial pattern. If target is not specified, uses the internal target pattern set during construction.
 Parameters
 trial (numeric) – pattern to compare to target
 target (numeric) – pattern to compare to trial. Optional. Default target is obj.target.
Bowman2017¶

class
otslm.iter.objectives.
Bowman2017
(varargin)¶ Cost function used in Bowman et al. 2017 paper. Inherits from
Objective
.\[C = 10^d * (1.0  \sum_{nm} \sqrt{I_nm T_nm} \cos(phi_nm  psi_nm))^2\]target and trial should be the complex field amplitudes.
 Properties
 scale –
d
scaling factor in cost function  field – ‘complex’, ‘phase’, or ‘amplitude’ for optimisation type
 normalize – Normalize target/trial every evaluation
 scale –
See also Bowman2017 and
Intensity
.
Bowman2017
(varargin)¶ Construct a new objective function instance
 Usage
 obj = Bowman2017(…) construct a new objective function instance.
 Optional named arguments
 scale num – d scaling factor in cost function. Default: 0.5
 field [char] – One of ‘complex’, ‘phase’, or ‘amplitude’ for optimisation type. Default: ‘complex’.
 normalize bool – Normalize target/trial every evaluation. Default: true.
 roi []  logical  function_handle – specify the roi to use when evaluating the fitness function. Can be a logical array or a function handle. Default: []
 target []  matrix – specify the target pattern for this objective. If not supplied, the target must be supplied when the evaluate function is called. Default: []
FlatIntensity¶

class
otslm.iter.objectives.
FlatIntensity
(varargin)¶ Objective function for pattern flatness and intensity. Inherits from
Intensity
andFlatness
.Evaluates the fitness using the Intensity and Flatness method and adds the result:
 Properties
 flatness – scaling factor for pattern flatness
See also FlatIntensity and
Bowman2017
.
FlatIntensity
(varargin)¶ Construct a new objective function instance
 Usage
 obj = FlatIntensity(…)
 Optional named arguments
 roi []  logical  function_handle – specify the roi to use when evaluating the fitness function. Can be a logical array or a function handle. Default: []
 target []  matrix – specify the target pattern for this objective. If not supplied, the target must be supplied when the evaluate function is called. Default: []
 flatness num – Scaling factor for pattern flatness. Default: 0.5.
Flatness¶

class
otslm.iter.objectives.
Flatness
(varargin)¶ Objective function for pattern flatness Inherits from
Objective
.See also Flatness,
Intensity
andFlatIntensity
.
Flatness
(varargin)¶ Construct a new objective function instance
 Usage
 obj = Flatness(…)
 Optional named arguments
 roi []  logical  function_handle specify the roi to use when evaluating the fitness function. Can be a logical array or a function handle. Default: []
 target []  matrix specify the target pattern for this objective. If not supplied, the target must be supplied when the evaluate function is called. Default: []

Goorden2014¶

class
otslm.iter.objectives.
Goorden2014
(varargin)¶ Fidelity function from Goorden, et al. 2014 paper.
\[F = \textrm{conj}(target) * trial^2\]Error is 1  F.
 Properties
 normalize (logical) – True if the patterns should be normalized by the area (i.e., \(F = F/A^2\)).
See also Goorden2014,
Flatness
and :class`Bowman2017`.
Goorden2014
(varargin)¶ Construct a new objective function instance
 Usage
 obj = Goorden2014(…)
 Optional named arguments
 normalize logical – If true, normalized the pattern by the number of pixels in the pattern. Default: true.
 roi []  logical  function_handle – specify the roi to use when evaluating the fitness function. Can be a logical array or a function handle. Default: []
 target []  matrix – specify the target pattern for this objective. If not supplied, the target must be supplied when the evaluate function is called. Default: []
Intensity¶

class
otslm.iter.objectives.
Intensity
(varargin)¶ Objective function for pattern intensity.
See also Intensity,
Flatness
andFlatIntensity
.
Intensity
(varargin)¶ Construct a new objective function instance
 Usage
 obj = Intensity(…)
 Optional named arguments
 roi []  logical  function_handle specify the roi to use when evaluating the fitness function. Can be a logical array or a function handle. Default: []
 target []  matrix specify the target pattern for this objective. If not supplied, the target must be supplied when the evaluate function is called. Default: []

RmsIntensity¶

class
otslm.iter.objectives.
RmsIntensity
(varargin)¶ Objective function for pattern RMS intensity Inherits from
Objective
.Evaluates the fitness according to
\[F = \sqrt{\textrm{mean}((t^2  T^2)^2)}\]Where \(t\) and \(T\) are the trial and target pattern complex amplitudes.
See also RmsIntensity,
Intensity
andFlatness
.
RmsIntensity
(varargin)¶ Construct a new objective function instance
 Usage
 obj = RmsIntensity(…)
 Optional named arguments
 roi []  logical  function_handle specify the roi to use when evaluating the fitness function. Can be a logical array or a function handle. Default: []
 target []  matrix specify the target pattern for this objective. If not supplied, the target must be supplied when the evaluate function is called. Default: []
