Code reference¶
module-level¶
- ggf.fiber_distance_capillary(gel_thickness=2e-06, glass_thickness=4e-05, channel_width=4e-05, 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=3e-06, power_per_fiber=0.6, wavelength=1.064e-06, 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) – Semi-major axis of an ellipse fit to the object perimeter [m]
semi_minor (float) – Semi-minor 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 single-mode 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 look-up 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
- 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 [Lure64]
- 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
- 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]¶
Least-squares 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
sci_funcs¶
Other scientific functions
stress¶
- ggf.stress.get_stress(model, semi_major, semi_minor, object_index, medium_index, effective_fiber_distance=0.0001, mode_field_diameter=3e-06, power_per_fiber=0.6, wavelength=1.064e-06, 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) – Semi-major axis of an ellipse fit to the object perimeter [m]
semi_minor (float) – Semi-minor 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 single-mode 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 [BCG09] 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 semi-major axis \(a\) and the semi-minor 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 (semi-minor axis).
epsilon (float) – Stretch ratio; defines size of semi-major 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 [BCG09].
- 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.8466e-06, stretch_ratio=0.1, wavelength=7.8e-07, beam_waist=3, power_left=0.6, power_right=0.6, dist=0.0001, n_points=100, theta_max=<Mock name='mock.pi' id='140032901530064'>, field_approx='davis', ret_legendre_decomp=False, verbose=False)[source]¶
Compute the stress acting on a prolate spheroid
The prolate spheroid has semi-major axis \(a\) and semi-minor 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) – Semi-minor 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 [BCG09].
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 [Lure64] 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.