Code reference¶
modulelevel¶

ggf.
fiber_distance_capillary
(gel_thickness=2e06, glass_thickness=4e05, channel_width=4e05, gel_index=1.449, glass_index=1.474, medium_index=1.335)[source]¶ Effective distance between the two optical fibers
When the optical stretcher is combined with a microfluidic channel (closed setup), then the effective distance between the two optical fibers (with the the stretched object at the channel center) is defined by the refractive indices of the optical components: index matching gel between fiber and channel wall, microfluidic glass channel wall, and medium inside the channel.
Parameters:  gel_thickness (float) – Thickness of index matching gel (distance between fiber and glass wall) [m]
 glass_thickness (float) – Thickness of glass wall [m]
 channel_width (float) – Width of the microfluidic channed [m]
 gel_index (float) – Refractive index of index matching gel
 glass_index (float) – Refractive index of channel glass wall
 medium_index (float) – Refractive index of index medium inside channel
Returns: eff_dist – Effective distance between the fibers
Return type: Notes
The effective distance is computed relative to the medium, i.e. if gel_index == glass_index == medium_index, then eff_dist = 2*`gel_dist` + 2*`glass_dist` + channel_width.

ggf.
get_ggf
(model, semi_major, semi_minor, object_index, medium_index, effective_fiber_distance=0.0001, mode_field_diameter=3e06, power_per_fiber=0.6, wavelength=1.064e06, poisson_ratio=0.5, n_poly=120, use_lut=None, verbose=False)[source]¶ Model the global geometric factor
Parameters:  model (str) – Model to use, one of: boyde2009
 semi_major (float) – Semimajor axis of an ellipse fit to the object perimeter [m]
 semi_minor (float) – Semiminor axis of an ellipse fit to the object perimeter [m]
 object_index (float) – Refractive index of the object
 medium_index (float) – Refractive index of the surrounding medium
 effective_fiber_distance (float) – Effective distance between the two trapping fibers relative
to the medium refractive index [m]. For an open setup, this is
the physical distance between the fibers. For a closed setup
(capillary), this distance takes into account the refractive
indices and thicknesses of the glass capillary and index
matching gel. For the closed setup, the convenience function
ggf.fiber_distance_capillary()
can be used.  mode_field_diameter (float) – The mode field diameter MFD of the fiber used [m]. Note that
the MFD is dependent on the wavelength used. If the
manufacturer did not provide a value for the MFD, the MFD
can be approximated as
3*wavelenth
for a singlemode fiber.  power_per_fiber (float) – The laser power coupled into each of the fibers [W]
 wavelength (float) – The laser wavelength used for the trap [m]
 poisson_ratio (float) – The Poisson’s ratio of the stretched material. Set this to 0.5 for volume conservation.
 n_poly (int) – Number of Legendre polynomials to use for computing the GGF. Note that only even Legendre polynomials are used and thus, this number is effectively halved. To reproduce the GGF as computed with the Boyde2009 Matlab script, set this value to None.
 use_lut (None, str, pathlib.Path or bool) – Use lookup tables to compute the GGF. If set to None, the internal LUTs will be used or the GGF is computed if it cannot be found in a LUT. If True, the internal LUTs will be used and a NotInLUTError will be raised if the GGF cannot be found there. Alternatively, a path to a LUT hdf5 file can be passed.
 verbose (int) – Increases verbosity
Returns: ggf – global geometric factor
Return type:

ggf.
legendre2ggf
(coeff, poisson_ratio)[source]¶ Compute the global geometric factor from Legendre coefficients
The definition of the Legendre coefficients is given in the theory section.
Parameters:  coeff (1d ndarray) – Legendre coefficients as defined in [Lure1964]
 poisson_ratio (float) – Poisson’s ratio of the stretched material. Set this to 0.5 for volume conservation.
Returns: ggf – Global geometric factor
Return type: Notes
All odd Legendre coefficients are assumed to be zero, because the stress profile is symmetric with respect to the stretcher axis.

ggf.
stress2ggf
(stress, theta, poisson_ratio, n_poly=120)[source]¶ Compute the GGf from radial stress using Legendre decomposition
Parameters: Returns: ggf – Global geometric factor
Return type: Notes
All odd Legendre coefficients are assumed to be zero, because the stress profile is symmetric with respect to the stretcher axis. Therefore, only n_poly/2 polynomials are considered.

ggf.
stress2legendre
(stress, theta, n_poly)[source]¶ Decompose stress into even Legendre Polynomials
The definition of the Legendre decomposition is given in the theory section.
Parameters:  stress (1d ndarray) – Radial stress profile (in imaging plane)
 theta (1d ndarray) – Polar angles corresponding to stress
 n_poly (int) – Number of Legendre polynomials to use
Returns: coeff – Legendre coefficients as defined in [Lure1964]
Return type: 1d ndarray
Notes
All odd Legendre coefficients are assumed to be zero, because the stress profile is symmetric with respect to the stretcher axis. Therefore, only n_poly/2 polynomials are considered.
matlab_funcs¶
Special functions translated from Matlab to Python

ggf.matlab_funcs.
gammaln
(x)[source]¶ Logarithm of the absolute value of the Gamma function
Notes
https://de.mathworks.com/help/matlab/ref/gammaln.html
See also
scipy.special.gammaln()

ggf.matlab_funcs.
legendre
(n, x)[source]¶ Associated Legendre functions
Parameters:  n (int) – degree
 x (ndarray of floats) – argument
Notes
x is treated always as a row vector
The statement legendre(2,0:0.1:0.2) returns the matrix
/ x = 0 x = 0.1 x = 0.2 m = 0 0.5000 0.4850 0.4400 m = 1 0 0.2985 0.5879 m = 2 3.0000 2.9700 2.8800 Notes

ggf.matlab_funcs.
lscov
(A, B, w=None)[source]¶ Leastsquares solution in presence of known covariance
\(A \cdot x = B\), that is, \(x\) minimizes \((B  A \cdot x)^T \cdot \text{diag}(w) \cdot (B  A \cdot x)\). The matrix \(w\) typically contains either counts or inverse variances.
Parameters:  A (matrix or 2d ndarray) – input matrix
 B (vector or 1d ndarray) – input vector
Notes
stress¶

ggf.stress.
get_stress
(model, semi_major, semi_minor, object_index, medium_index, effective_fiber_distance=0.0001, mode_field_diameter=3e06, power_per_fiber=0.6, wavelength=1.064e06, n_points=100, verbose=False)[source]¶ Compute the optical stress profile in the optical stretcher
Parameters:  model (str) – Model to use, one of: boyde2009
 semi_major (float) – Semimajor axis of an ellipse fit to the object perimeter [m]
 semi_minor (float) – Semiminor axis of an ellipse fit to the object perimeter [m]
 object_index (float) – Refractive index of the object
 medium_index (float) – Refractive index of the surrounding medium
 effective_fiber_distance (float) – Effective distance between the two trapping fibers relative
to the medium refractive index [m]. For an open setup, this is
the physical distance between the fibers. For a closed setup
(capillary), this distance takes into account the refractive
indices and thicknesses of the glass capillary and index
matching gel. For the closed setup, the convenience function
ggf.fiber_distance_capillary()
can be used.  mode_field_diameter (float) – The mode field diameter MFD of the fiber used [m]. Note that
the MFD is dependent on the wavelength used. If the
manufacturer did not provide a value for the MFD, the MFD
can be approximated as
3*wavelenth
for a singlemode fiber.  power_per_fiber (float) – The laser power coupled into each of the fibers [W]
 wavelength (float) – The laser wavelength used for the trap [m]
 n_points (int) – Number of points to compute.
 verbose (int) – Increases verbosity
Returns:  theta (1d ndarray of length n_points) – Polar angles [rad]
 sigma (1d ndarray of length n_points) – Radial stress profile along theta [Pa]
stress.boyde2009¶
stress.boyde2009.core¶

ggf.stress.boyde2009.core.
boundary
(costheta, a=1, epsilon=0.1, nu=0)[source]¶ Projected boundary of a prolate spheroid
Compute the boundary according to equation (4) in [Boyde2009] with the addition of the Poisson’s ratio of the object.
\[B(\theta) = a (1+\epsilon) \left[ (1+\epsilon)^2  \epsilon (1+\nu) (2+\epsilon (1\nu)) \cos^2 \theta \right]^{1/2}\]This boundary function was derived for a prolate spheroid under the assumption that the semimajor axis \(a\) and the semiminor axes \(b=c\) are defined as
\[a = b \cdot \frac{1+ \epsilon}{1 \nu \epsilon}\]The boundary function \(B(\theta)\) can be derived with the above relation using the equation for a prolate spheroid.
Parameters:  costheta (float or np.ndarray) – Cosine of polar coordinates \(\theta\) at which to compute the boundary.
 a (float) – Equatorial radii of prolate spheroid (semiminor axis).
 epsilon (float) – Stretch ratio; defines size of semimajor axis: \(a = (1+\epsilon) b\). Note that this is not the eccentricity of the prolate spheroid.
 nu (float) – Poisson’s ratio \(\nu\) of the material.
Returns: B – Radial object boundary in dependence of theta \(B(\theta)\).
Return type: 1d ndarray
Notes
For \(\nu=0\), the above equation becomes equation (4) in [Boyde2009].

ggf.stress.boyde2009.core.
get_hgc
[source]¶ Load hypergeometric coefficients from hypergeomdata2.dat.
These coefficients were computed by Lars Boyde using Wolfram Mathematica.

ggf.stress.boyde2009.core.
stress
(object_index=1.41, medium_index=1.3465, poisson_ratio=0.45, semi_minor=2.8466e06, stretch_ratio=0.1, wavelength=7.8e07, beam_waist=3, power_left=0.6, power_right=0.6, dist=0.0001, n_points=100, theta_max=<Mock name='mock.pi' id='139916155602032'>, field_approx='davis', ret_legendre_decomp=False, verbose=False)[source]¶ Compute the stress acting on a prolate spheroid
The prolate spheroid has semimajor axis \(a\) and semiminor axis \(b=c\).
Parameters:  object_index (float) – Refractive index of the spheroid
 medium_index (float) – Refractive index of the surrounding medium
 poisson_ratio (float) – Poisson’s ratio of the spheroid material
 semi_minor (float) – Semiminor axis (inner) radius of the stretched object \(b=c\).
 stretch_ratio (float) – Measure of the deformation, defined as \((a  b) / b\)
 wavelength (float) – Wavelenth of the gaussian beam [m]
 beam_waist (float) – Beam waist radius of the gaussian beam [wavelengths]
 power_left (float) – Laser power of the left beam [W]
 power_right (float) – Laser power of the right beam [W]
 dist (float) – Distance between beam waist and object center [m]
 n_points (int) – Number of points to compute stresses for
 theta_max (float) – Maximum angle to compute stressed for
 field_approx (str) – TODO
 ret_legendre_decomp (bool) – If True, return coefficients of decomposition of stress into Legendre polynomials
 verbose (int) – Increase verbosity
Returns:  theta (1d ndarray) – Angles for which stresses are computed
 sigma_rr (1d ndarray) – Radial stress corresponding to angles
 coeff (1d ndarray) – If ret_legendre_decomp is True, return compositions of decomposition of stress into Legendre polynomials.
Notes
 The angles theta are computed on a grid that does not include zero and theta_max.
 This implementation was first presented in [Boyde2009].
stress.boyde2009.globgeomfact¶
Computation of the global geometric factor

ggf.stress.boyde2009.globgeomfact.
coeff2ggf
(coeff, poisson_ratio=0.45)[source]¶ Compute the global geometric factor from stress coefficients
The radial displacements of an elastic sphere can be expressed in terms of Legendre polynomials (see [Lure1964] equation 6.2.9) whose coefficients are computed from the Legendre decomposition of the radial stress.
Notes
For a \(\sigma_0 \cos^n(\theta)\) stress profile, the GGF already includes the peak stress according to:
\[\text{GGF} = \sigma_0 F_\text{G}.\]This is a conversion of the Matlab script GGF.m to Python. The code solves a linear system of equations to determine all Legendre coefficients. The new implementation in
ggf.legendre2ggf()
uses the direct solution and thus should be preferred.