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(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()¶

Is the trap currently executing a move?

Returns:

bool

move_by(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(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(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()¶: Stop all movement of the trap immediately.

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

property current_force: float¶: 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])

Timeline¶

Deprecated since version 2.7.0.

Timeline.mark_begin(name)¶

Start a marked section on the timeline

Be sure to pair each call to mark_begin with a call to mark_end.

Parameters:

namestr: Name of the marked section, may be an empty string.

Timeline.mark_end(export=False, filepath='', channels=[])¶

End a marked section on the timeline.

See also mark_begin.

Parameters:

exportbool: If True, the marker will also be exported immediately.
filepathstr: The exact path where the exported file should be created. If empty, the path will be auto-generated just like exporting in the UI.
channelslist: List of the channels to be exported (only applicable if export is True). If empty, the channels selected in the user interface will be exported.

Returns:

Tuple[int, int]: The (start, stop) timestamps of the created marker.

Raises:

RuntimeError if a marker is not in progress (i.e. no previous matching mark_begin call)
RuntimeError if one of more selected channels are not available on the timeline

Examples

# End the marker without exporting
timeline.mark_begin("marker 1")
...
timeline.mark_end()

# End the marker and export it with an auto-generated name
timeline.mark_begin("marker 2")
...
timeline.mark_end(export=True)

# End the marker and export with a specific name
timeline.mark_begin("marker 3")
...
timeline.mark_end(export=True, filepath="D:/path/to/folder/file_name.h5")

# Select the timeline channels to export
timeline.mark_begin("marker 4")
...
timeline.mark_end(export=True, channels=["Force LF/Trap 1", "Force LF/Trap 2"])

# In all cases `.mark_end()` returns a (start, stop) pair of timestamps
timeline.mark_begin("marker 5")
...
start, stop = timeline.mark_end()

# Make sure a marker gets an end, even if the script is aborted
timeline.mark_begin("marker 6")
try:
  # ... do something else
  pause(2.0)
finally:
  # This always ends the marker, even if the script is aborted with
  # the "Stop" button
  timeline.mark_end()

property Timeline.current_time¶

The time at which the latest timeline data was measured

A 64-bit integer timestamp with nanosecond resolution.