Tutorial
========

About Python Automation in Bluelake
-----------------------------------

The Bluelake software contains a built-in *interpreter* of the `Python programming language`_. This means you can write a text file with Python code, and have that code executed by Bluelake. The code can automate all sorts of things in Bluelake, from moving traps around, to navigating the flowcell and making confocal scans.

.. _Python programming language: https://www.python.org

If you're not familiar with Python: no worries, it's a very easy programming language to learn. We recommend you look at the `Python For Beginners`_ page on the Python website for some great learning resources and tutorials. For the rest of this tutorial, we'll assume you know the basics of Python.

.. _Python For Beginners: https://www.python.org/about/gettingstarted/


Running Your First Script
-------------------------

To run a Bluelake script, you'll need to work on a C-Trap (or m-Trap) Controller PC that has Bluelake installed. On the Controller PC, open up a text editor, and create a new file with the following contents::

    print('Hello from Bluelake')

Save the file as ``test.py`` in any folder of your choice. Make sure that, when saving the file, you add the ``.py`` extension explicitly, and you save the file as type ``All files (*.*)``.

In Bluelake, you'll see a *Browse* button in the *Scripting* panel. Click it, and navigate to the folder where you stored your ``test.py`` script. Open the script, and then run it using the *Start* button in the *Scripting* panel. You should now see the text ``Hello from Bluelake`` appearing in the *Scripting* panel's output box.

What just happened? Bluelake opened the ``test.py`` file, and fed its contents to its built-in Python interpreter. The single line in ``test.py`` then calls Python's ``print`` function to show a line of text on the screen.


Some Basic Bluelake Automation
------------------------------

To do something more useful in your script, you'll first need to *import* the Python module that contains Bluelake's automation functions. Add the following line to the top of your script::

    import bluelake

The functions that are available in this module are documented in the :ref:`api:API Reference`. As an example, you could actuate the shutter of the first optical trap using::

    bluelake.trap1.clear()

Here, ``trap1`` represents the first optical trap, featuring a function ``clear()`` that we can call to close the associated shutter.

Another example would be a script that keeps moving Trap 1 to the right in half-micrometer steps, until the force on a captured particle exceeds 20 pN --- basically a poor-man's version of a force clamp::

    from bluelake import trap1
        # ^ different syntax of the "import" statement, allowing us to
        #   from now on refer just to `trap1`, instead of `bluelake.trap1`

    while trap1.current_force < 20:
        trap1.move_by(dx=0.5, speed=1)

Try copying the above lines of code into a ``.py`` file and running it from Bluelake, while you have a bead captured in the optical trap. The trap should keep moving to the right until the force exceeds 20 pN (something that you could also simulate by starting some liquid flow in the flowcell).


Further Resources
-----------------

* Lumicks provides a `GitHub repository with sample scripts`_. Here, you'll find sample scripts that showcase specific C-Trap components, as well as complete workflow automation scripts.

.. _GitHub repository with sample scripts: https://github.com/lumicks/bluelake-scripting