Bsc classes

This section contains information about the beam shape coefficient classes (Bsc) currently implemented in the toolbox. These classes can be used to describe optical tweezers beams in a basis of vector spherical wave functions. The classes provide functions for translating beams, visualising beams and overloads for adding beams. Most of the core functionality is provided in the base class ott.Bsc. Classes inheriting from this class typically only need to define the beam creation code specific to that type of beam.

Bsc

ott.Bsc is the base class for objects representing beam shape coefficients (BSC) including BscPmGauss and BscPmParaxial. The class can also be used directly to package a set of existing BSC for use with other functions in the toolbox, for example

a = [1; 0; 0]; b = 1i.*a;
basis = 'incoming';
type = 'incident';
beam = ott.Bsc(a, b, basis, type);

would create a new beam with Nmax = 1 (i.e. 3 coefficients for a and b) with the incoming vector spherical wave function basis, representing a incident beam. For further information about creating custom beams, see the Creating a custom beam example.

class ott.Bsc(a, b, basis, type, varargin)

Bsc abstract class representing beam shape coefficients

Most quantities have SI dimensions. Any SI units can be used for these quantities (for example m or microns) as long as the units are consistent.

Beam power (i.e., the Bsc.power property) can be converted to SI units by multiplying by 1/(2*Z*k^2) where Z is the medium impedance and k is the medium wave number (this does not affect force calculation). Changing the beam power is not recommended in this or earlier versions of the toolbox since this effects both accuracy and run-time. This behaviour will be changed (fixed) in a future release.

Properties
  • a – Beam shape coefficients a vector

  • b – Beam shape coefficients b vector

  • type – Beam type (incident, scattered, total)

  • basis – VSWF beam basis (incoming, outgoing or regular)

  • Nmax – Truncation number for VSWF coefficients

  • power – Power of the beam [M*L^2/S^3]

  • Nbeams – Number of beams in this Bsc object

  • wavelength – Wavelength of beam [L]

  • speed – Speed of beam in medium [L/T]

  • omega – Angular frequency of beam [2*pi/T]

  • k_medium – Wavenumber in medium [2*pi/L]

  • dz – Absolute cumulative distance the beam has moved

Methods
  • append – Joins two beam objects together

  • sum – Merge the BSCs for the beams contained in this object

  • translateZ – Translates the beam along the z axis

  • translateXyz – Translation to xyz using rotations and z translations

  • translateRtp – Translation to rtp using rotations and z translations

  • farfield – Calculate fields in farfield

  • emFieldXyz – Calculate field values in cartesian coordinates

  • emFieldRtp – Calculate field values in spherical coordinates

  • getCoefficients – Get the beam coefficients [a, b]

  • getModeIndices – Get the mode indices [n, m]

  • totalField – Calculate the total field reprsentation of the beam

  • scatteredField – Calcualte the scattered field representation of the beam

  • visualise – Generate a visualisation of the beam near-field

  • visualiseFarfield – Generate a visualisation of the beam far-field

  • visualiseFarfieldSlice – Generate scattering slice at specific angle

  • visualiseFarfieldSphere – Generate spherical surface visualisation

  • intensityMoment – Calculate moment of beam intensity in the far-field

Static methods:
  • make_beam_vector – Convert output of bsc_* functions to beam coefficients

See also Bsc, ott.BscPmGauss, ott.BscPlane.

Bsc(a, b, basis, type, varargin)

BSC construct a new beam object

beam = Bsc(a, b, basis, type, …) constructs a new beam vector. Useful if you have a specific set of a/b coefficients that you want to wrap in a beam object.

Basis: incoming, outgoing or regular Type: incident, scattered, total, internal

Optional named arguments:

k_medium n Wavenumber in medium (default: 2*pi) omega n Angular frequency (default: 2*pi) dz n Initial displacement of the beam (default: 0) like beam Construct this beam to be like another beam

static GetVisualisationData(field_type, xyz, rtp, vxyz, vrtp)

Helper to generate the visualisation data output. This function is not intended to be called directly, instead see visualise() or visualiseFarfield().

Usage

GetVisualisationData(field_type, xyz, rtp, vxyz, vrtp) Takes a field_type string, the coordinates (either xyz or rtp), and the data values (either vxyz or vrtp).

Parameters
  • xyz, rtp, vxyz, vrtp – (Nx3 numeric) Coordinates in a suitable form to be passed to ott.utils.xyz2rtp and similar functions. Pass empty arrays for unused values.

  • field_type – (enum) Type of field to calculate. Supported types include:

    • ‘irradiance’ – \(\sqrt{|Ex|^2 + |Ey|^2 + |Ez|^2}\)

    • ‘E2’ – \(|Ex|^2 + |Ey|^2 + |Ez|^2\)

    • ‘Sum(Abs(E))’ – \(|Ex| + |Ey| + |Ez|\)

    • Re(Er), Re(Et), Re(Ep), Re(Ex), Re(Ey), Re(Ez)

    • Abs(Er), Abs(Et), Abs(Ep), Abs(Ex), Abs(Ey), Abs(Ez)

    • Arg(Er), Arg(Et), Arg(Ep), Arg(Ex), Arg(Ey), Arg(Ez)

translateXyz(beam, varargin)

Translate the beam given Cartesian coordinates.

Units for the coordinates should be consistent with the beam wave number (i.e., if the beam was created by specifying wavelength in units of meters, distances here should also be in units of meters).

Usage

tbeam = beam.translateXyz(xyz) translate the beam to locations given by the xyz coordinates, where xyz is a 3xN matrix of coordinates.

tbeam = beam.translateXyz(Az, Bz, D) Translate the beam using z-translation and rotation matrices.

[tbeam, Az, Bz, D] = beam.translateXyz(…) returns the z-translation matrices Az, Bz, the rotation matrix D, and the translated beam tbeam.

[tbeam, A, B] = beam.translateXyz(…) returns the translation matrices A, B and the translated beam.

[tbeam, AB] = beam.translateXyz(…) returns the translation matrices A, B packaged so they can be directly applied to a beam using tbeam = AB * beam.

tbeam = beam.translateXyz(…, ‘Nmax’, Nmax) specifies the output beam Nmax. Takes advantage of not needing to calculate a full translation matrix.

translateZ(beam, varargin)

Translate a beam along the z-axis.

Units for the coordinates should be consistent with the beam wave number (i.e., if the beam was created by specifying wavelength in units of meters, distances here should also be in units of meters).

Usage

tbeam = beam.translateZ(z) translates by a distance z along the z axis.

[tbeam, A, B] = beam.translateZ(z) returns the translation matrices and the translated beam. See also ott.Bsc.translate().

[tbeam, AB] = beam.translateZ(z) returns the A, B matrices packed so they can be directly applied to a beam: tbeam = AB * beam.

[…] = beam.translateZ(…, ‘Nmax’, Nmax) specifies the output beam Nmax. Takes advantage of not needing to calculate a full translation matrix.

visualise(beam, varargin)

Create a visualisation of the beam

Usage

visualise(…) displays an image of the beam in the current figure window.

im = visualise(…) returns a image of the beam. If the beam object contains multiple beams, returns images for each beam.

Optional named arguments
  • ‘size’ [ x, y ] Width and height of image

  • ‘field’ type Type of field to calculate

  • ‘axis’ ax Axis to visualise (‘x’, ‘y’, ‘z’) or a cell array with 2 or 3 unit vectors for x, y, [z].

  • ‘offset’ offset Plane offset along axis (default: 0.0)

  • ‘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 ].

  • ‘mask’ func(xyz) Mask function for regions to keep in vis

  • ‘combine’ (enum) If multiple beams should be treated as ‘coherent’ or ‘incoherent’ beams and their outputs added. incoherent may only makes sense if the field is an intensity. Default: [].

visualiseFarfield(beam, varargin)

Create a 2-D visualisation of the farfield of the beam

visualiseFarfield(…) displays an image of the farfield in the current figure window.

im = visualiseFarfield(…) returns a 2-D image of the farfield.

[im, data] = visualiseFarfield(…, ‘saveData’, true) returns the saved data that can be used for repeated calculation.

TODO: Should the data object instead be a callable object?

This would make the interface simpler.

Optional named arguments:

‘size’ [ x, y ] Size of the image ‘direction’ dir Hemisphere string (‘pos’ or ‘neg’),

2-vector (theta, phi) or 3x3 rotation matrix.

‘field’ type Type of field to calculate ‘mapping’ map Mapping from sphere to plane (‘sin’, ‘tan’) ‘range’ [ x, y ] Range of points to visualise

‘saveData’ bool save data for repeated calculation (default: false) ‘data’ data data saved for repeated calculation. ‘thetaMax’ num maximum theta angle to include in image ‘showVisualisation’ bool show the visualisation in the

current figure (default: nargout == 0).

visualiseFarfieldSlice(beam, phi, varargin)

Generate a 2-D scattering plot of the far-field.

Usage:

beam.visualiseFarfieldSlice(phi, …) Generates a slice/polar plot of the far-field. In this version the slice is always aligned to the z-axis. phi specifies the rotation of the plane about the z-axis.

[theta, I] = beam.visualiseFarfieldSlice(phi, …) calculate data for the visualisation but don’t generate a visualisation unless showVisualisation is true.

Optional named arguments:
  • field (enum) – The field type to visualise. Defaults to ‘irradiance’. Not all field types support visualisation.

  • normalise (logical) – If true, the calculated fields are normalised by the maximum calculated field value.

  • ntheta (numeric) – Number of angular points to use. Defaults to 100.

  • showVisualisation (logical) – If the visualisation should be shown. Defaults to nargout == 0.

visualiseFarfieldSphere(beam, varargin)

Generate a spherical surface visualisation of the far-field

beam.visualiseFarfieldSphere(phi)

Optional named arguments:

npts num Number of points to use for sphere surface normalise bool If intensity values should be normalised to 1 type str Type of visualisation to produce.

sphere (default) draw a sphere with intensity as color 3dpolar scale the radius by the intensity

BscPlane

Representation of a plane wave in VSWF coefficients

class ott.BscPlane(theta, phi, varargin)

BscPlane representation of a plane wave in VSWF coefficients

BscPlane properties:

theta Beam direction (polar angle) phi Beam direction (azimuthal angle) polarisation Beam polarisation [ Etheta Ephi ]

BscPlane methods:

translateZ Translates the beam and checks within beam range

Based on bsc_plane.m from ottv1.

See also BscPlane and ott.Bsc.

This file is part of the optical tweezers toolbox. See LICENSE.md for information about using/distributing this file.

BscPmGauss

Provides HG, LG and IG beams using point matching method

class ott.BscPmGauss(varargin)

BscPmGauss provides HG, LG and IG beams using point matching method

Properties
  • gtype – Type of beam (‘gaussian’, ‘lg’, ‘hg’, or ‘ig’)

  • mode – Beam modes (2 or 4 element vector)

  • polarisation – Beam polarisation

  • truncation_angle – Truncation angle for beam [rad]

  • offset – Offset for original beam calculation

  • angle – Angle of incoming beam waist

  • angular_scaling – Angular scaling function (tantheta | sintheta)

See ott.Bsc for inherited properties.

This class is based on bsc_pointmatch_farfield.m and bsc_pointmatch_focalplane.m from OTT (version 1).

See also BscPmGauss.

BscPmGauss(varargin)

Construct a new IG, HG, LG or Gaussian beam.

Usage

BscPmGauss(…) constructs a new Gassian beam (LG00).

BscPmGauss(type, mode, …) constructs a new beam with the given type. Supported types [mode]:

  • ‘lg’ – Laguarre-Gauss [ radial azimuthal ]

  • ‘hg’ – Hermite-Gauss [ m n ]

  • ‘ig’ – Ince-Gauss [ paraxial azimuthal parity elipticity ]

Optional named parameters
  • ‘Nmax’ – Truncation number for beam shape coefficients. If omitted, Nmax is initially set to 100, the beam is calculated and Nmax is reduced so that the power does not drop significantly.

  • ‘zero_rejection_level’ – Level used to determine non-zero beam coefficients in far-field point matching. Default: 1e-8.

  • ‘NA’ – Numerical aperture of objective

  • ‘polarisation’ – Polarisation of the beam

  • ‘power’ – Rescale the power of the beam (default: [])

  • ‘omega’ – Optical angular frequency (default: 2*pi)

  • ‘k_medium’ – Wave number in medium

  • ‘index_medium’ – Refractive index of medium

  • ‘wavelength_medium’ – Wavelength in medium

  • ‘wavelength0’ – Wavelength in vacuum

  • ‘offset’ – Offset of the beam from origin

  • translation_method – Method to use when calculating translations. Can either be ‘Default’ or ‘NewBeamOffset’, the latter calculates new beam shape coefficients for every new position.

  • angular_scaling (enum) – Angular scaling function. For a discussion of this parameter, see Documentation (Point-matching and angle projections).

    • ‘sintheta’ – angular scaling function is the same as the one present in standard microscope objectives. Preserves high order mode shape!

    • ‘tantheta’ – default angular scaling function, “small angle approximation” which is valid for thin lenses ONLY. Does not preserve high order mode shape at large angles.

  • truncation_angle (numeric) – Adds a hard edge to the beam, this can be useful for simulating the back-aperture of a microscope objective. Default: pi/2 (i.e. no edge).

  • truncation_angle_deg – Same as truncation_angle but with degrees instead of radians.

BscPmParaxial

Calculate representation from farfield/paraxial beam

class ott.BscPmParaxial(NA, E_ff, varargin)

BscPmParaxial calculate representation from farfield/paraxial beam

Properties:

a (Bsc) Beam shape coefficients a vector b (Bsc) Beam shape coefficients b vector type (Bsc) Beam type (incoming, outgoing or scattered)

Methods:

translateZ (Bsc) Translates the beam along the z axis translateXyz (Bsc) Translation to xyz using rotations and z translations translateRtp (Bsc) Translation to rtp using rotations and z translations farfield (Bsc) Calculate fields in farfield emFieldXyz (Bsc) Calculate fields at specified locations set.Nmax (Bsc) Resize the beam shape coefficient vectors get.Nmax (Bsc) Get the current size of the beam shape vectors getCoefficients (Bsc) Get the beam coefficients [a, b] getModeIndices (Bsc) Get the mode indices [n, m] power (Bsc) Calculate the power of the beam

Based on paraxial_to_bsc from ottv1.

See also BscPmParaxial, ott.Bsc and examples/slm_to_focalplane

This file is part of the optical tweezers toolbox. See LICENSE.md for information about using/distributing this file.

BscPointmatch

Base class for BSC generated using point matching

ott.BscPointMatch