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.
Contents
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()
orvisualiseFarfield()
.- 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, wherexyz
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 matrixD
, and the translated beamtbeam
.[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 usingtbeam = 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
andbsc_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¶