The optical tweezers toolbox can be used to calculate optical forces and torques of particles using the T-matrix formalism in a vector spherical wave basis. The toolbox includes codes for calculating T-matrices, beams described by vector spherical wave functions, functions for calculating forces and torques, simple codes for simulating dynamics and examples.

To use the toolbox, download or clone the GitHub repository. You will also need a modern version of MATLAB, at least R2016b. To modify any of the GUI applications you will need at least R2018a. We have tested the toolbox on R2018a and it should work on newer versions. You may also need some of the Matlab support packages (list coming soon). This version of the toolbox is released as a package, +ott, which contains a collection of functions for calculating T-matrices, beam coefficients, force and torques. To use the functions in your code, the easiest way is to add the directory containing the package to your path,

addpath('<download-path>/ott');
help ott   % Test that ott was found, should display ott Contents page

if you regularly use the toolbox you might want to add the command to your startup.m file.

The toolbox has changed a lot since previous releases. To get started, take a look at the documentation over on read the docs. The documentation source can be found in the docs directory or you can download a PDF copy of the documentation with the latest release. Alternatively, take a look at the examples directory.

To calculate the force on a spherical particle, you need to setup a beam obejct, setup a particle and run the ott.forcetorque function. One of the shortest examples of this is:

beam = ott.BscPmGauss();
tmatrix = ott.TmatrixMie(0.5, 'k_medium', 2*pi, 'k_particle', 2*pi*1.3);
fz = ott.forcetorque(beam, tmatrix, 'position', [0;0;1].*linspace(-8, 8));
figure(), plot(fz.')

this assumes everything is in units of the wavelength, and creates a Gaussian beam with the default parameters.

There have been many changes since the previous release, mainly the switch to object orientated programming. Beams and T-matrices are now represented by obects, we have added shape objects and moved everything into packages.

T-matrices are represented by Tmatrix objects. For simple shapes, the Tmatrix.simple method can be used to construct T-matrices for a variety of common objects. More complex T-matrices can be generated by inheriting the T-matrix class, for an example, take a look at TmatrixMie and TmatrixPm.

Beams are represented by a Bsc objects. A beam can be multiplied by T-matrices or other matrix/scalar values to generate new beams. For Gaussian type beams, including Hermite-Gauss, Ince-Gauss, and Laguarre-Gaussian beams, the BscPmGauss class provides the equivalent of bsc_pointmatch_farfield in the previous release.

The new implementation hides Nmax, most routines have a default choice of Nmax based on the beam/particle size. Nmax can still be accessed and changed manually, but in most cases the automatic choice of Nmax should be fine. Beams can T-matrices can be multiplied without needing to worry about the having equal Nmax, the beam/T-matrix will be expanded to match the maximum Nmax. If repeated calculations are being done, it may be faster to first ensure the Nmax of the beam and T-matrix match, this is done in forcetorque when the position or rotation arguments are used.

• Version 2 will introduces a focus on simulating particles in optical traps rather than just focussing on calculating optical forces and torques. The plan is also to introduce geometric optics and other methods not requiring a T-matrix. The toolbox will be more automated and include a graphical user interface.
• Version 1.6 we may move Beams and Tmatrices to a beams and tmatrix sub-package. We might also add drag calculation codes.

Except where otherwise noted, this toolbox is made available under the Creative Commons Attribution-NonCommercial 4.0 License. For full details see LICENSE.md. For use outside the conditions of the license, please contact us. The toolbox includes some third-party components, information about these components can be found in the documentation and corresponding file in the thirdparty directory.

This version of the toolbox can be referenced by citing the following paper

T. A. Nieminen, V. L. Y. Loke, A. B. Stilgoe, G. Knöner, A. M. Branczyk, N. R. Heckenberg, and H. Rubinsztein-Dunlop, "Optical tweezers computational toolbox", Journal of Optics A 9, S196-S203 (2007)

or by directly citing the toolbox

T. A. Nieminen, V. L. Y. Loke, A. B. Stilgoe, I. C. D. Lenton, Y. Hu, G. Knöner, A. M. Branczyk, N. R. Heckenberg, and H. Rubinsztein-Dunlop, "Optical tweezers toolbox", https://github.com/ilent2/ott

and the respective Bibtex entry

@misc{Nieminen2018,
  author = {Nieminen, Timo A. and Loke, Vincent L. Y. and Stilgoe, Alexander B. and Lenton, Isaac C. D. and Kn{\ifmmode\ddot{o}\else\"{o}\fi}ner, Gregor and Bra{\ifmmode\acute{n}\else\'{n}\fi}czyk, Agata M. and Heckenberg, Norman R. and Rubinsztein-Dunlop, Halina},
  title = {Optical Tweezers Toolbox},
  year = {2018},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/ilent2/ott}},
  commit = {Optional, a specific commit}
}

The best person to contact for inquiries about the toolbox or lincensing is Isaac Lenton

README.md     - Overview of the toolbox (this file)
LICENSE.md    - License information for OTSLM original code
AUTHORS.md    - List of contributors (pre-GitHub)
CHANGES.md    - Overview of changes to the toolbox
TODO.md       - Changes that may be made to the toolbox
thirdparty/   - Third party licenses (multiple files)
examples/     - Example files showing different toolbox features
tests/        - Unit tests to verify toolbox features function correctly
docs/         - Sphinx documentation for the project
+ott/         - The toolbox

The +ott package, as well as tests/ and examples/ directories and sub-directories contain Contents.m files which list the files and packages in each directory. These files can be viewed in Matlab by typing help ott or help ott.subpackage.