prop sub-package¶

The otslm.tools.prop package contains classes for propagating the fields. For simple beam propagation, see tools.visualise(). This documentation contains information on the Propagator base class and the propagator sub-classes. The package contains additional base classes for the common code shared between the forward and inverse methods.

For most propagators there are three methods that can be used to create a new instance. The class constructor creates a new instance where you specify all the options. The simple and simpleProp static functions create an instance of the propagator from an input pattern and return an output image or propagator depending on the method.

Propagator base class
Fft3Forward
Fft3Inverse
FftEwaldForward
FftEwaldInverse
FftForward
FftInverse
FftDebyeForward
OttForward
Ott2Forward
RsForward

Propagator base class ¶

class otslm.tools.prop.Propagator¶

Base class for field propagation methods.

Inherits from handle. This means that we can reuse the data block through multiple calls to propagate and easily split our code up into separate overload-able functions.

Abstract methods:: out = propagate(in, …) propagates the complex field amplitudes

Fft3Forward ¶

class otslm.tools.prop.Fft3Forward(sz, varargin)¶

Propagate using forward 3-D fast Fourier transform

Methods

Fft3Forward() – construct a new propagator instance
propagate() – propagate the field forward using 3-D FFT

Properties

data – Memory allocated for transform input
padding – Padding around image
size – Size of image
roi – Region of interest within data for image
roi_output – Region to crop output image after transformation

Static methods

simple() – propagate the field with a simple interface
simpleProp() – construct the propagator for input pattern

See also Fft3Inverse, FftForward and otslm.tools.visualise.

Fft3Forward(sz, varargin)¶

Construct a FFT propagator instance

FFT3FORWARD(sz, …) construct a new propagator instance for the specified pattern size. sz must be a 3 element vector.

Optional named arguments:

padding num | [xy, z] | [x, y, z] padding to add to edges of the image. Either a single number for uniform padding, two numbers for separate axial and radial padding, or three numbers for x, y and z padding. Default: ceil(sz/2)
trim_padding bool if the output_roi should be set to remove the padding added before the transform. Default: false.
gpuArray bool if true, allocates memory on the GPU and does the transform with the GPU instead of the CPU. Default: false.

static simple(pattern, varargin)¶

propagate the field with a simple interface

[output, prop] = simple(pattern, …) construct a new FFT propagator and apply it to the pattern. Returns the propagated pattern and the propagator.

See also simpleProp() for named arguments.

static simpleProp(pattern, varargin)¶

Generate the propagator for the specified pattern.

prop = simpleProp(pattern, …) construct a new propagator.

Optional named arguemnts:

padding num | [num, num] Padding for transform. For details, see FftForward. Default: ceil(size(pattern)/2)
trim_padding bool if padding should be trimmed from output. Default: true.
gpuArray bool if we should use the GPU. Default: isa(pattern, 'gpuArray')

Fft3Inverse ¶

class otslm.tools.prop.Fft3Inverse(sz, varargin)¶

Propagate using inverse 3-D fast Fourier transform

Methods

Fft3Inverse() – construct a new propagator instance
propagate() – propagate the field forward using 3-D FFT

Properties

data – Memory allocated for transform input
padding – Padding around image
size – Size of image
roi – Region of interest within data for image
roi_output – Region to crop output image after transformation

Static methods

simple() – propagate the field with a simple interface
simpleProp() – construct the propagator for input pattern

See also Fft3Forward, FftInverse and otslm.tools.visualise.

Fft3Inverse(sz, varargin)¶

Construct a FFT propagator instance

FFT3INVERSE(sz, …) construct a new propagator instance for the specified pattern size. sz must be a 3 element vector.

Optional named arguments:

padding num | [xy, z] | [x, y, z] padding to add to edges of the image. Either a single number for uniform padding, two numbers for separate axial and radial padding, or three numbers for x, y and z padding. Default: ceil(sz/2)
trim_padding bool if the output_roi should be set to remove the padding added before the transform. Default: false.
gpuArray bool if true, allocates memory on the GPU and does the transform with the GPU instead of the CPU. Default: false.

static simple(pattern, varargin)¶

propagate the field with a simple interface

[output, prop] = simple(pattern, …) construct a new FFT propagator and apply it to the pattern. Returns the propagated pattern and the propagator.

See also simpleProp for named arguments.

static simpleProp(pattern, varargin)¶

Generate the propagator for the specified pattern.

prop = simpleProp(pattern, …) construct a new propagator.

Optional named arguemnts:

padding num | [num, num] Padding for transform. For details, see FftForward. Default: ceil(size(pattern)/2)
trim_padding bool if padding should be trimmed from output. Default: true.
gpuArray (logical) – if we should use the GPU. Default: isa(pattern, 'gpuArray')

FftEwaldForward ¶

class otslm.tools.prop.FftEwaldForward(sz, varargin)¶

Propagate using forward Ewald sphere and 3-D FFT. Inherits from EwaldBase and Fft3Forward.

Ewald surfaces are described in

Gal Shabtay, Three-dimensional beam forming and Ewald surfaces, Optics Communications, Volume 226, Issues 16, 2003, Pages 33-37, https://doi.org/10.1016/j.optcom.2003.07.056.

and

P.P. Ewald, J. Opt. Soc. Am., 9 (1924), p. 626

Methods

FftEwaldForward() – construct a new propagator instance
propagate() – propagate the field

Properties

data – Memory allocated for transform input (3-D)
padding – Padding around image [x, y, z]
size – Size of image [x, y, z]
roi – Region of interest within data for image
roi_output – Region to crop output image after transformation
focal_length – Focal length of the lens

Static methods

simple() – propagate the field with a simple interface
simpleProp() – construct the propagator for input pattern

See also FftEwaldInverse, FftForward and otslm.tools.visualise.

FftEwaldForward(sz, varargin)¶

Construct a Ewald sphere FFT propagator instance

FFTEWALDFORWARD(sz, …) construct a new propagator instance for the specified pattern size. sz must be a 3 element vector.

Optional named arguments:

focal_length num focal length of the lens in pixels. Default: min(sz/2).
interpolate bool If the Ewald mapping should interpolate. Default: true.
padding num | [xy, z] | [x, y, z] padding to add to edges of the image. Either a single number for uniform padding, two numbers for separate axial and radial padding, or three numbers for x, y and z padding. Default: ceil(sz/2).
trim_padding bool if the output_roi should be set to remove the padding added before the transform. Default: false.
gpuArray bool if true, allocates memory on the GPU and does the transform with the GPU instead of the CPU. Default: false.

static simple(pattern, varargin)¶

propagate the field with a simple interface

[output, prop] = simple(pattern, …) construct a new propagator and apply it to the pattern. Returns the propagated pattern and the propagator.

See also simpleProp for named arguments.

static simpleProp(pattern, varargin)¶

Generate the propagator for the specified pattern.

prop = simpleProp(pattern, …) construct a new propagator.

Optional named arguemnts:

diameter num Diameter of the lens. Default: min(size(pattern))
zsize num Depth of the FFT volume. Default: Calculated from focal_length and diameter
focal_length num Set the focal length of the lens. Default: diameter/2 (unless NA is set)
NA num Set the focal length via NA. Default: [] (i.e. defer to focal_length default)
interpolate bool If the Ewald mapping should interpolate. Default: true.
padding num | [xy, z] | [x, y, z] Padding for transform. For details, see FftEwaldForward. Default: ceil([size(pattern), zsize]/2)
trim_padding bool if padding should be trimmed from output. Default: true.
gpuArray bool if we should use the GPU. Default: isa(pattern, ‘gpuArray’)

FftEwaldInverse ¶

class otslm.tools.prop.FftEwaldInverse(sz, varargin)¶

Propagate using inverse Ewald sphere and 3-D FFT. Inherits from EwaldBase and Fft3Inverse.

Ewald surfaces are described in

Gal Shabtay, Three-dimensional beam forming and Ewald surfaces, Optics Communications, Volume 226, Issues 16, 2003, Pages 33-37, https://doi.org/10.1016/j.optcom.2003.07.056.

and

P.P. Ewald, J. Opt. Soc. Am., 9 (1924), p. 626

Methods

FftEwaldInverse() – construct a new propagator instance
propagate() – propagate the field

Properties

data – Memory allocated for transform input (3-D)
padding – Padding around image [x, y, z]
size – Size of image [x, y, z]
roi – Region of interest within data for image
roi_output – Region to crop output image after transformation
focal_length – Focal length of the lens

Static methods

simple() – propagate the field with a simple interface
simpleProp() – construct the propagator for input pattern

See also FftEwaldForward, FftInverse and otslm.tools.visualise.

FftEwaldInverse(sz, varargin)¶

Construct a Ewald inverse FFT propagator instance.

FFTEWALDINVERSE(sz, …) construct a new propagator instance for the specified pattern size. sz must be a 3 element vector.

Optional named arguments:

focal_length num focal length of the lens in pixels. Default: ((min(sz(1:2))/2).^2 + sz(3).^2)/(2*sz(3))
interpolate bool If the Ewald mapping should interpolate. Default: true.
padding num | [xy, z] | [x, y, z] padding to add to edges of the image. Either a single number for uniform padding, two numbers for separate axial and radial padding, or three numbers for x, y and z padding. Default: ceil(sz/2)
trim_padding (logical) – if the output_roi should be set to remove the padding added before the transform. Default: false.
gpuArray (logical) – if true, allocates memory on the GPU and does the transform with the GPU instead of the CPU. Default: false.

static simple(pattern, varargin)¶

propagate the field with a simple interface

[output, prop] = simple(pattern, …) construct a new Ewald FFT propagator and apply it to the pattern. Returns the propagated pattern and the propagator.

See also simpleProp for named arguments.

static simpleProp(pattern, varargin)¶

Generate the propagator for the specified pattern.

prop = simpleProp(pattern, …) construct a new propagator.

Optional named arguemnts:

padding num | [xy, z] | [x, y, z] Padding for transform. For details, see FftEwaldInverse(). Default: ceil(size(pattern)/2)
trim_padding bool if padding should be trimmed from output. Default: true.
gpuArray bool if we should use the GPU. Default: isa(pattern, ‘gpuArray’)

FftForward ¶

class otslm.tools.prop.FftForward(sz, varargin)¶

Propagate using forward 2-D fast Fourier transform

Methods

FftForward() – construct a new propagator instance
propagate() – propagate the field forward using 2-D FFT

Properties

data – Memory allocated for transform input
lens – Lens to be applied before transformation
padding – Padding around image
size – Size of image
roi – Region of interest within data for image
roi_output – Region to crop output image after transformation

Static methods

simple() – propagate the field with a simple interface
simpleProp() – construct the propagator for input pattern
calculateLens() – lens function used by simple and FftInverse.simple.

See also FftInverse, Fft3Forward and otslm.tools.visualise.

FftForward(sz, varargin)¶

FFTFORWARD Construct a FFT propagator instance

FFTFORWARD(sz, …) construct a new propagator instance for the specified pattern size. sz must be a 2 element vector.

Optional named arguments

padding num | [num, num] – padding to add to edges of the image. Either a single number for uniform padding or two numbers to pass to padarray(). Default: ceil(sz/2)
lens pattern – lens function to add to the transform. This can be useful for shifting the pattern in the axial direction. Pattern should have same size as sz + padding. The lens function should be a complex field amplitude. Default: [].
trim_padding (logical) – if output_roi should be set to remove the padding added before the transform. Default: false.
gpuArray (logical) – if true, allocates memory on the GPU and does the transform with the GPU instead of the CPU. Default: false.

static simple(pattern, varargin)¶

propagate the field with a simple interface

[output, prop] = simple(pattern, …) construct a new FFT propagator and apply it to the pattern. Returns the propagated pattern and the propagator.

See also simpleProp for input arguments.

static simpleProp(pattern, varargin)¶

Generate the propagator for the specified pattern.

prop = simpleProp(pattern, …) construct a new propagator.

Optional named arguemnts:

axial_offset num Offset along the propagation axis Default: 0.0.
NA num Numerical aperture for axial offset lens. Default: 0.1.
padding num | [num, num] Padding for transform. For details, see FftForward. Default: ceil(size(pattern)/2)
trim_padding bool if padding should be trimmed from output. Default: true.
gpuArray bool if we should use the GPU. Default: isa(pattern, ‘gpuArray’)

FftInverse ¶

class otslm.tools.prop.FftInverse(sz, varargin)¶

Propagate using inverse 2-D fast Fourier transform

Methods

FftInverse() – construct a new propagator instance
propagate() – propagate the field using 2-D inverse FFT

Properties

data – Memory allocated for transform input
lens – Lens to be applied after transformation
padding – Padding around image
size – Size of image
roi – Region of interest within data for image
roi_output – Region to crop output image after transformation

Static methods

simple() – propagate the field with a simple interface
simpleProp() – construct the propagator for input pattern
calculateLens() – lens function used by simple and FftInverse.simple.

See also FftForward, Fft3Inverse and otslm.tools.visualise.

FftInverse(sz, varargin)¶

Construct a inverse FFT propagator instance

FFTINVERSE(sz, …) construct a new propagator instance for the specified pattern size. sz must be a 2 element vector.

Optional named arguments:

padding num | [num, num] padding to add to edges of the image. Either a single number for uniform padding or two numbers to pass to the padarray function. Default: ceil(sz/2)
lens pattern lens function added after transformation. This can be useful for shifting the pattern in the axial direction. Pattern should have same size as sz + padding. The lens function should be a complex field amplitude. Default: [].
trim_padding (logical) – if output_roi should be set to remove the padding added before the transform. Default: false.
gpuArray (logical) – if true, allocates memory on the GPU and does the transform with the GPU instead of the CPU. Default: false.

static simple(pattern, varargin)¶

propagate the field with a simple interface

[output, prop] = simple(pattern, …) construct a new inverse FFT propagator and apply it to the pattern. Returns the propagated pattern and the propagator.

See also simpleProp for named arguments.

static simpleProp(pattern, varargin)¶

Generate the propagator for the specified pattern.

prop = simpleProp(pattern, …) construct a new propagator.

Optional named arguemnts

axial_offset num Offset along the propagation axis Default: 0.0.
NA num Numerical aperture for axial offset lens. Default: 0.1.
padding num | [num, num] Padding for transform. For details, see FftForward. Default: ceil(size(pattern)/2)
trim_padding bool if padding should be trimmed from output. Default: true.
gpuArray bool if we should use the GPU. Default: isa(pattern, ‘gpuArray’)

FftDebyeForward ¶

class otslm.tools.prop.FftDebyeForward(sz, varargin)¶

Propagate using forward 2-D FFT formulation of Debye integral. Inherits from FftForward.

This method is useful for simulating focusing of paraxial fields by high numerical aperture (NA) objectives. The method accounts for some of the polarisation and phase affects present in high NA focussing.

The method and conditions for obtaining acurate results are described in

M. Leutenegger, et al., Fast focus field calculations, Optics Express Vol. 14, Issue 23, pp. 11277-11291 (2006) https://doi.org/10.1364/OE.14.011277

Methods

FftForward() – construct a new propagator instance
propagate() – propagate the field forward using 2-D FFT

Properties

NA – Numerical aperture of lens
radius – Radius of lens
polarisation – Default polarisation for scalar input to propagate

Properties (inherited)

data – Memory allocated for transform input
lens – Lens to be applied before transformation
padding – Padding around image
size – Size of image
roi – Region of interest within data for image
roi_output – Region to crop output image after transformation

Static methods

simple() – propagate the field with a simple interface
simpleProp() – construct the propagator for input pattern
calculateLens() – generates the lens required by the method

See also FftForward, Fft3Forward and OttForward

FftDebyeForward(sz, varargin)¶

Construct a FFT Debye forward propagator instance.

Usage

obj = FftDebyeForward(sz, …) construct a new propagator instance for the specified pattern size. sz must be a 2 element vector.

Optional named arguments

polarisation [num, num] – X and Y polarisation to use when propagate() is called with only a single argument. Default: [1.0, 0.0].
NA (numeric) – Numerical aperture for axial offset lens. Default: 1.0.
radius (numeric) – Radius of lens. Default: min(sz)/2.
padding num | [num, num] – padding to add to edges of the image. Either a single number for uniform padding or two numbers to pass to padarray(). Default: ceil(sz/2)
lens (complex) – lens pattern to add to the transform. This should typically be a result of calculateLens(). Pattern should have same size as sz + padding. The lens function should be a complex field amplitude. Default: [].
trim_padding (logical) – if output_roi should be set to remove the padding added before the transform. Default: false.
gpuArray (logical) – if true, allocates memory on the GPU and does the transform with the GPU instead of the CPU. Default: false.

static calculateLens(sz, NA, radius, z)¶

Calculate lens function for FftDebyeForward.

The lens function is given by

where \(\theta = \arcsin(r)\) and \(r\) is the normalized radius of the lens.

Usage

lens = calculateLens(sz, NA, radius, z)

Parameters

sz (size) – Size of the pattern [rows, cols].
NA (numeric) – Numerical aperture of lens. Assumes medium has refractive index of 1. NA should be adjusted if medium has different refractive index (NA/n_medium).
radius (numeric) – Radial scaling factor for lens. (units: pixels).
z (numeric) – Axial offset (units: inverse wavelength in medium).

propagate(input, varargin)¶

Propagate the input image

Usage

output = propagate(input, …) propagates the complex input image using 2-D FFT formulation of the Debye integral. Returns a NxMx3 matrix for the complex vector field at the focus.

Parameters

input (numeric) – paraxial far-field image. Should either be a NxM or NxMx2 matrix. If the matrix is single channel, the method polarisation property is used.

static simple(pattern, varargin)¶

propagate the field with a simple interface

[output, prop] = simple(pattern, …) construct a new FftDebye propagator and apply it to the pattern. Returns the propagated pattern and the propagator.

See also simpleProp() for input arguments.

static simpleProp(pattern, varargin)¶

Generate the propagator for the specified pattern.

prop = simpleProp(pattern, …) construct a new propagator.

Optional named arguments:

polarisation [num, num] – X and Y polarisation to use when propagate() is called with only a single argument. Default: [1.0, 0.0].
axial_offset num Offset along the propagation axis Default: 0.0.
NA num Numerical aperture for axial offset lens. Default: 1.0.
radius (numeric) – Radius of lens. Default: min(size(pattern))/2.
padding num | [num, num] Padding for transform. For details, see FftForward. Default: ceil(size(pattern)/2)
trim_padding bool if padding should be trimmed from output. Default: true.
gpuArray bool if we should use the GPU. Default: isa(pattern, ‘gpuArray’)

OttForward ¶

class otslm.tools.prop.OttForward(sz, varargin)¶

Propagate the field using the optical tweezers toolbox

Requires the optical tweezers toolbox (OTT).

Properties

size – Size of input beam image
beam_data – Beam with saved data for repeated computations
Nmax – Nmax for VSWF
polarisation – Polarisation of beam (jones vector)
index_medium – Refractive index in medium
NA – Numerical aperture
wavelength0 – Wavelength in vacuum
omega – Angular frequency of light

Static methods

simple() – propagate the field with a simple interface
simpleProp() – construct the propagator for input pattern

See also Ott2Forward and otslm.tools.visualise.

OttForward(sz, varargin)¶

OTTFORWARD Construct a new propagator instance

Usage

prop = OttForward(sz, …) construct a new propagator instance.

Parameters

sz (size) – 2 element vector for the far-field size.

Optional named arguments

pre_calculate bool If beam_data should be set at construction or at first use of propagate(). Defalut: true
beam_data ott.Bsc Beam object to use instead of calculating the VSWF expansion. Incompatible with pre_calculate. Default: []
Nmax num The VSWF truncation number
polarisation [x,y] Default polarisation of the VSWF beam. Only used for single channel input images. Default [1, 1i].
radius (numeric) – Radius of lens aperture. Default: min(sz)/2.
index_medium num Refractive index of medium
NA num Numerical aperture of objective
wavelength0 num Wavelength of light in vacuum (default: 1)
omega num Angular frequency of light (default: 2*pi)

static simple(pattern, varargin)¶

SIMPLE propagate the field with a simple interface

[output, prop] = simple(pattern, …) propagates the 2-D complex field amplitude pattern using the optical tweezers toolbox. Returns the beam and the propagator.

Additional named arguments are passed to Ott2Forward.

static simpleProp(pattern, varargin)¶

Generate the propagator for the specified pattern.

prop = simpleProp(pattern, …) construct a new propagator.

Additional named arguments are passed to Ott2Forward.

Ott2Forward ¶

class otslm.tools.prop.Ott2Forward(sz, varargin)¶

Propagate the field using the optical tweezers toolbox. Provides a wrapper to calculate the 2-D field after beam calculation.

Requires the optical tweezers toolbox (OTT).

Properties

axis – Axis perpendicular to output image plane
offset – Offset along axial direction
field – Type of field to calculate
output_size – Size of the output image
range – Range of values to calculate field over

Inherited properties

size – Size of input beam image
beam_data – Beam with saved data for repeated computations
Nmax – Nmax for VSWF
polarisation – Polarisation of beam (jones vector)
index_medium – Refractive index in medium
NA – Numerical aperture
wavelength0 – Wavelength in vacuum
omega – Angular frequency of light

Static methods

simple() – propagate the field with a simple interface
simpleProp() – construct the propagator for input pattern

See also OttForward, FftForward and otslm.tools.visualise.

Ott2Forward(sz, varargin)¶

OTT2FORWARD Construct a new propagator instance

Usage

prop = Ott2Forward(sz, …) construct a new propagator instance.

Parameters

sz (size) – size of the pattern in far-field [rows, cols]

Optional named arguments

axis (enum) – ‘x’, ‘y’ or ‘z’ for axis perpendicular to image. Default: z.
offset (numeric) – Offset along axial direction. Default: 0.0.
field (enum) – Field to calculate. See ott.Bsc.visualise() for a list of valid parameters. Default: ‘irradiance’.
output_size [num, num] – Size of output image. Default: [80, 80]
range [ x, y ] Range of points to visualise. Can either be a cell array { x, y }, two scalars for range [-x, x], [-y, y] or 4 scalars [ x0, x1, y0, y1 ]. Default: [] (parameter is omitted, see ott.Bsc.visualise)
pre_calculate (logical) – If beam_data should be set at construction or at first use of propagate(). Defalut: true

static simple(pattern, varargin)¶

SIMPLE propagate the field with a simple interface

[output, prop] = simple(pattern, …) propagates the 2-D complex field amplitude pattern using the optical tweezers toolbox. Returns the field in the specified output plane and the propagator. The propagator contains the OTT.Bsc beam.

Additional named arguments are passed to Ott2Forward.

static simpleProp(pattern, varargin)¶

Generate the propagator for the specified pattern.

prop = simpleProp(pattern, …) construct a new propagator.

Additional named arguments are passed to Ott2Forward.

RsForward ¶

Warning

This method may be unstable.

class otslm.tools.prop.RsForward(sz, distance, varargin)¶

Propagate the field forward using Rayleight-Sommerfeld integral

Properties

size – Size of the pattern
distance – Distance to propagate pattern

Static methods

simple() – propagate the field with a simple interface
simpleProp() – construct the propagator for input pattern

See also FftForward, OttForward and otslm.tools.visualise.

RsForward(sz, distance, varargin)¶

RSFORWARD Construct a new propagator instance

obj = RsForward(sz, distance, …) construct a propagator instance for the specified image size and propagation distance. distance must be a scalar, sz must be a 2 element vector.

static simple(pattern, distance, varargin)¶

SIMPLE propagate the field with a simple interface

output = simple(pattern, distance, …) propagates the 2-D complex field amplitude pattern using the Rayleigh-Sommerfeld integral by the specified distance.