bsc Package

The bsc package provides classes for representing beams in a vector spherical wave function (VSWF) basis. The base class for all VSWF beams is Bsc, which provides methods for visualising beams, calculating forces, and manipulating the VSWF data. Similar to T-matrices, the data is stored internally as a vector, allowing the type to be changed to any valid Matlab matrix type (such as gpuArray or sparse).

Simple multipole beams can be created by directly specifying their beam shape coefficients. For more complex beams, the Pointmatch, PlaneWave and Annular classes provide provide methods to calculate BSC data. Additionally, the PlaneWave and Annular beams provide alternative translation methods that are more optimal for these types of beams. These methods are summarised in Fig. 7.

Unlike the previous version of the toolbox, the Bsc class does not track the position/rotation of the beam. This is to avoid suggesting that the beam actually has a well defined position/rotation. Other notable differences include the use of Hetrogeneous arrays, support for arbitrary beam data data-types, and moving user friendly features such as nice units to ott.beam.Beam.

Bsc rotations have units of radians and displacements have units of medium wavelength. For a more user friendly interface with SI units, see ott.beam.Beam.

Graphical (overview) table of contents for bsc package

Fig. 7 Graphical display showing the different BSC classes currently included in the T-matrix. The Bsc class is the base class and can be used directly for simple multipole mode descriptions. The other classes provide specialisations and methods for approximating more complex beams.

Bsc

class ott.bsc.Bsc(oa, ob)

Class representing vector spherical wave function beam shape coefficients. Inherits from ott.utils.RotateHelper and ott.utils.TranslateHelper.

Unlike the previous version of the toolbox, the Bsc class does not track the position/rotation of the beam. This is to avoid suggesting that the beam actually has a well defined position/rotation. Other notable differences include the use of Hetrogeneous arrays, support for arbitrary beam data data-types, and moving user friendly features such as nice units to ott.beam.Beam.

Bsc rotations have units of radians and displacements have units of medium wavelength.

Properties

  • a – Beam shape coefficients a vector

  • b – Beam shape coefficients b vector

  • Nmax – (Dependent) Truncation number for VSWF coefficients

  • power – (Dependent) Power of the beam shape coefficients

Static methods

  • FromDenseBeamVectors – Construct beam from dense beam vectors.

  • BasisSet – Generate basis set of VSWF beams

  • PmNearfield – Construct using near-field point matching

  • PmFarfield – Construct using far-field point matching

Methods

  • Bsc – Class constructor

  • nbeams – Get the total number of beams in array

  • issparse – Check if the beam data is sparse

  • full – Make the beam data full

  • sparse – Make the beam data sparse

  • makeSparse – Make the beam data sparse (with additional options)

  • setNmax – Resize beam data to desired Nmax

  • shrinkNmax – Reduce Nmax while preserving beam power

  • gpuArray – Make beam a gpuArray

  • gather – Apply gather to beam data

  • rotate* – (Inherited) Functions for rotating the beam

  • translate* – (Inherited) Functions for translating the beam

  • translateZ – Translation along the theta=0 (z) axis

  • getCoefficients – Get a/b vectors with additional options

  • setCoefficients – Set a/b vectors with additional options

Mathematical operations

  • sum – Combine array of beams using summation

  • times – Scalar multiplication of beam vectors

  • mtimes – Scalar and matrix multiplication of beam vectors

  • safeTimes – Matrix multiplication with support for shrinking

  • rdivide – Scalar division of beam vectors

  • mrdivide – Scalar division of beam vectors

  • uminus – Negation of beam vectors

  • minus – Subtraction of beam vectors

  • plus – Addition of beam vectors

  • real – Extract real part of BSC data

  • imag – Extract imag part of BSC data

  • abs – Calculate absolute value of BSC data

Field calculation methods

  • efieldRtp – Calculate electric field around the origin

  • hfieldRtp – Calculate magnetic field around the origin

  • efarfield – Calculate electric fields in the far-field

Force and torque related methods

  • force – Calculate the change in momentum between two beams

  • torque – Calculate change in angular momentum between beams

  • spin – Calculate change in spin momentum between beams

Casts

  • ott.bsc.Bsc – Downcast BSC superclass to base class

  • ott.tmatrix.Tmatrix – Create T-matrix from beam array

Pointmatch

ott.bsc.Pointmatch

PlaneWave

class ott.bsc.PlaneWave(varargin)

Bsc specialisation for plane waves

Plane waves can be translated in any direction by simply applying a phase shift to the beam. This class provides overloads for the beam translation functions implementing this optimisation.

Properties

  • direction – Propagation direction of plane wave

Static methods

  • FromDirection – Construct a beam for the specified direction

Annular

class ott.bsc.Annular(varargin)

Bsc specialisation for Bessel-like beams

Bessel beams and other annular beams can be translated axially with only a phase shift applied to the beam shape coefficients. This class overloads the axial translation function to implement this.

Properties

  • theta – Angle describing annular

Static methods

  • FromBessel – Construct Annular beam from Bessel specification.