Other functions¶
These functions operate on beams, particles or data generated by other methods.
There is also a ott.warning and ott.change_warning functions, for
further information about these functions, see the documentation in
their respective files.
forcetorque¶
- ott.forcetorque(ibeam, sbeam, varargin)¶
FORCETORQUE calculate force/torque/spin in a 3D orthogonal space If the beam shape coefficients are in the original coordinates, this outputs the force, torque and spin in 3D carteisan coordinates.
Units are beam power. Force results should be multipled by n/c and torque results multiplied by 1/omega, assuiming the beam coefficients already have the correct units for power.
[fxyz,txyz,sxyz] = FORCETORQUE(ibeam, sbeam) calculates the force, torque and spin using the incident beam, ibeam, and the scattered beam, sbeam.
Output is stored in [3, 1] column vectors. If torque or spin are omitted, only force or force/torque are calculated.
FORCETORQUE(ibeam, T, ‘position’, position) first applies a translation to the beam. position can be a 3xN array, resulting in multiple force/torque calculations for each position.
FORCETORQUE(ibeam, T, ‘rotation’, rotation) effectively applies a rotation to the particle by first applying the rotation to the beam, scattering the beam by the T-matrix and applying the inverse rotation to the scattered beam. rotation can be a 3x3N array, resulting in multiple calculations.
If both position and rotation are present, the translation is applied first, followed by the rotation. If both position and rotation are arrays, they must have the same number of locations (N) or a single location (N=1).
ibeam can contain multiple beams. If multiple beams are present, the outputs are [3, nlocations, nbeams] arrays unless the coherent argument is set to true, in which case the beams are added after translation.
[fx,fy,fz,tx,ty,tz,sx,sy,sz] = FORCETORQUE(…) unpacks the force/torque/spin into separate output arguments.
This uses mathematical result of Farsund et al., 1996, in the form of Chricton and Marsden, 2000, and our standard T-matrix notation S.T. E_{inc}=sum_{nm}(aM+bN);
This file is part of the optical tweezers toolbox. See LICENSE.md for information about using/distributing this file.
axial_equilibrium¶
- ott.axial_equilibrium(tmatrix, beam, z)¶
AXIAL_EQUILIBRIUM find equilibrium position and stiffness along beam axis
[z,kz] = AXIAL_EQUILIBRIUM(T,beam) attempts to locate the equilibrium position for the T-matrix T in beam starting with an initial guess at z = 0.
[z,kz] = axial_equilibrium(…, initial_guess) specifies an initial guess.
This file is part of the optical tweezers toolbox. See LICENSE.md for information about using/distributing this file.
find_equilibrium¶
- ott.find_equilibrium(z, fz)¶
FIND_EQUILIBRIUM estimates equilibrium positions from position-force data
zeq = find_equilibrium(z, fz) finds the axial equilibrium given two vectors z and fz with the position and force values respectively.
Based on the code in example_gaussian from the original toolbox.
See also ott.axial_equilibrium
TODO: Generalize the code to find multiple equilibriums. TODO: z need not be a vector of scalars, we could have a array of
position vectors representing some path we want to find the equilibrium on. We could do a similar thing for fz.
This file is part of the optical tweezers toolbox. See LICENSE.md for information about using/distributing this file.
trap_stiffness¶
- ott.trap_stiffness(beam, T, varargin)¶
TRAP_STIFFNESS calculate the force and torque trap stiffness
[kf, kt, K] = TRAP_STIFFNESS(beam, T) calculate the trap stiffness for the force, kf, and torque, kt for a particle, T, in a beam. K is the full 6x2N stiffness matrix, each column corresponds to a different direction. K can be multiplied by the drag tensor to calculate the fluid+optical trap stiffness.
TRAP_STIFFNESS(…, ‘position’, x0) and TRAP_STIFFNESS(, ‘rotation’, R) specify the particle position and rotation.
TRAP_STIFFNESS(…, ‘direction’, d) specifies the directions to calculate the trap stiffness in. Specify ‘beam’ for the XYZ direction for the current beam orientation. For specific directions, specify a 3xN matrix of vectors to calculate the force along and torque around. Default is ‘beam’.
TRAP_STIFFNESS(…, ‘method’, m) specifies the method to use for calculating the trap stiffness. Supported methods [calculations direction/other]:
‘cntr’ use central differences [4/0] ‘fwd’ use forward differences [2/1]
TRAP_STIFFNESS(…, ‘step’, [ dx dt ]) specifies the position and torque calculation step sizes (in beam units and radians). Default: 1e-3/beam.k_medium and 1e-3.
This file is part of the optical tweezers toolbox. See LICENSE.md for information about using/distributing this file.
find_traps¶
- ott.find_traps(position, force, varargin)¶
FIND_TRAPS attempt to find and characterise traps from position-force data
traps = find_traps(position, force, …) attempts to find and characterise possible traps for the given position and force data. Position and force should be vectors with position and force along one axis.
The returned traps is an array of structures with information about the trap equilibrium position, trap depth and trap stiffness and trap range.
- Optional named arguments:
keep_unstable bool keep unstable equilibriums (default: false) depth_threshold_e num percentage of max depth for trap acceptance
Use [] for no threshold. (default: 1e-2).
- force_zero_tol_e num percentage zero tolerance for pre-filtering
forces. Use [] for no threshold. (default: 1e-3).
- group_stable bool group stable traps separated by smaller
unstable traps together (useful for finding trap depth) (default: false)
- plot bool plot the traps, useful for diagnostics.
(default: false)
See also ott.find_equilibrium ott.axial_equilibrium and ott.trap_stiffness.
This file is part of the optical tweezers toolbox. See LICENSE.md for information about using/distributing this file.