Deprecated API¶

Trap steering¶

Deprecated since version 1.7.0.

Control over trap steering is provided through the Trap class. Instances of this class are available by default as:

import bluelake as bl

bl.trap1.move_to(x=1, y=2)

# Note: this line will fail on dual-trap systems:
bl.trap3.move_to(x=0, y=0)

# Additional trap steering devices that are defined in bluelake:
# (depending on actual availability of the hardware on your C-Trap)
bl.trap12xy
bl.trap12z
bl.trap34xy
bl.trap34z
bl.nanostage

class Trap(steering, shutter_number, move_by_factors)¶

Control interface for an optical trap

clear(self, delay_ms=500)¶

Clear any trapped particles from the trap, by briefly closing the shutter.

This works best if there is some amount of liquid flow in the flowcell.

Parameters

delay_msint: For how long to close the shutter, in milliseconds.

is_busy(self)¶

Is the trap currently executing a move?

Returns

bool

move_by(self, dx=0, dy=0, dz=0, speed=1)¶

Move the trap relative to the current position.

The function is blocking until when the trap has finished the move.

Parameters

dx, dy, dzOptional[float]: How much to move the trap, in micrometers. Any of the axes can be omitted, in which case the trap does not move in that direction.
speedfloat: Total speed of the move, in um/s (i.e, magnitude of the velocity vector). Note: The actual speed of the trap depends on the accuracy of the trap steering device. Only for the high-resolution Trap 1 can an accurate motion in X/Y be guaranteed. If no speed is given, it will default to 1.0um/s. If 0 is given, the device will move with its maximum speed.

move_to(self, waypoint=None, x=None, y=None, z=None, speed=None)¶

Move the trap to an absolute position in space.

The function is blocking until the trap has finished the move.

This function is only available for traps that have absolute position control, such as the high-resolution Trap 1 on C-Trap systems.

Parameters

waypointOptional[str]: Name of a previously stored waypoint. Should exactly match the name of the waypoint as entered in the Bluelake user interface.
x, y, zOptional[float]: Instead of giving a waypoint, this function can also be called with a set of destination coordinates, in micrometers. Any of the axes can be omitted, in which case the trap does not move in that direction.
speedfloat: Total speed of the move, in um/s (i.e, magnitude of the velocity vector). Note: The actual speed of the trap depends on the accuracy of the trap steering device. Only for the high-resolution Trap 1 can an accurate motion in X/Y be guaranteed. If no speed is given, either the waypoint speed will be used, or it will default to 1.0um/s for coordinate parameters. If 0 is given, the device will move with its maximum speed.

Examples

trap1.move_to('start position')
trap1.move_to(x=1, y=2, speed=10)

start_oscillation(self, axis, amplitude, frequency, reset_position=False)¶

Start sinusoidal oscillation of the trap

This function starts sinusoidal motion of the trap along the given axis. Note that availability of oscillation depends on the trap: not all trap hardware supports this feature.

To stop the oscillation, simply call stop.

NOTE: For frequencies above 0.075 Hz, this motion is precisely timed (in hardware). Lower frequencies are typically software-timed, and therefore subject to jitter.

NOTE: For higher frequencies, the oscillation might not reach the specified amplitude due to the device response time and inertia.

Parameters

axisstr: Which axis to oscillate: ‘X’ or ‘Y’.
amplitudefloat: Oscillation amplitude, in micrometers.
frequencyfloat: Oscillation frequency, in hertz.
reset_positionbool: Go back to the starting position when the oscillation is stopped (False by default)

stop(self)¶: Stop all movement of the trap immediately.

wait(self)¶: Wait until the movement that is currently in progress has finished

property current_force¶: Total magnitude of the force measured on this trap, in piconewtons

property position¶

Current absolute position of the trap.

This function is only available for traps that have absolute position control, such as the high-resolution Trap 1 on C-Trap systems.

Returns

positionPoint: namedtuple containing the position for each axis in micrometers.

Examples

from bluelake import trap1
current_position = trap1.position

# These two lines both print the x coordinate
print(current_position.x)
print(current_position[0])