Hello World

In this introductory example to the lrexp Experimenter, we will create a unit that will print 'Hello, world!' to the console. Before we get started, let's first configure our lrexp home directory:
  • Pick/create a directory that will serve as your home directory for the Experimenter. Inside of this folder, make a folder called 'experiments'. Additionally, you will also want to put your custom functions module/package here as well.
  • Create an environment variable named LREXPHOME, and have it point to the home directory.

Starting the Experimenter

To start the experimenter, execute the runExperimenter.py script found in the first folder of the source distribution. If you successfully installed all the dependencies for the experimenter, then you should get a screen that looks like this (look and feel is OS dependent):

New Action

Create a new unit by selecting "New root" from the file menu (or by using the Ctrl-N shortcut (Command-N on Mac OS X)). You should get a New Unit Dialog:
Let's name the new unit 'print Hello World' and make sure Action is selected under Unit type. Select Create. Your main window now shows your new unit in the root tree.

Expand it to get:
There isn't much there now. Your new Action unit contains only its Result as a child. If you deselect the Action (by selecting the Result) you can see that it is colored red. This means that it is not configured yet and we can't execute it. To complete the configuration we need to supply the Action with a function.

New Function

If you right click the Action entry in the tree, you get a drop-down list. Select the 'edit' option to bring up the Action's edit dialog. If you are connected to LabRAD, this might take a while since the program does a one-time polling of the LabRAD servers and settings. You should get this:
Optionally, you can double-click or press return on the Action (or any component) to get its edit dialog.

Every Action possesses a function attribute. This attribute can be a python function or a LabRAD setting. We want to assign this Action a python function, so click 'New Function'. You should get:
The standard module contains functions (and modules) common to every installation of the Experimenter. Expand this module to reveal more modules, including the printer module. Expand this module to reveal some functions. Bring the focus to the printX function, and press the 'Show Info' button (or press Spacebar). This brings up some documentation for the function (information for modules is also accessible this way):
This information tells you that the printX function belongs to the module lrexp.functions.standard.printer and has one argument named toPrint. The documentation tells us that this function simply prints the first argument to console.

This seems to be the function that we want, so close the info box and select the function by double-clicking on it (which in the Experimenter is equivalent to hitting return while it is selected). We note that the Action edit dialog now shows information for the function we just selected. Close the edit dialog.

Our root tree is updated to indicate our function selection. Hit "Expand All" to see the whole tree:
So we see our Action has automatically added the new function's arguments as a child. What we pass as the first (and only, in this case) argument is stored in the value attribute of the Input (furthest down on the tree). Bring up the Input's edit dialog.

Edit the Input

In the "Value" tab of the Input edit dialog, click the "Yaml Value" button, bringing up a line edit.

Into the line edit you can enter any valid Yaml string, which will be parsed into the corresponding python object.
To enter a string, for instance, you simply type the string you wish to enter. You can even omit quotations if there is no chance of it being confused with another data type ( "Apple" doesn't require quotes, but the string "64" does). So in our case, we can just type "Hello, world!" (omitting the quotes if we choose).
Click OK (or press enter) to accept your input. The value tab should be updated to reflect your changes. Exit the Input edit dialog and find the Input in the Root tree and notice that its display text is also updated with the new value.

Our unit configuration is now complete. Notice that the Action is no longer red in the Root tree; this means that it is ready to be executed. Expand out the Root tree and confirm that it matches the tree below:

Unit Execution

Let's finish this tutorial by executing the unit. Any configured Unit in the Root tree can be executed by right clicking the unit and selecting Execute from its drop down menu. For the top level Unit however it is easier to select Execute Root from the Execute menu, or use the Ctrl-E shortcut. Our Root tree consists of only one Unit (the "Hello World" Action), so go ahead and hit Ctrl-E (Command-E on Mac) to bring up its execution dialog:
Clicking "Next" will move step-by-step through Unit execution, while "Run" moves through unit execution continually. Any Action consists of only one execution step, which simply calls the function with the arguments that we configured passed in, so in this case it doesn't matter which button we click.

Click "Next" to execute the Action. The execution tree selects the most recently executed Unit and updates the unit with some information about its execution state:
The "None" text next to the Action indicates the Action's return value. This Action prints its input to console and returns nothing, so this is what we expect.

Go to the console you used to launch the Experimenter to confirm that it indeed printed:
Hello, world!
Clicking "Next" again brings up a window indicating that the Unit has completed execution. Dismiss this window and close the execution dialog.

Press Ctrl-S to save this Unit. Since you haven't saved this Unit yet, this should bring up a file dialog initialized the "experiments" folder located in the LREXPHOME directory. Give it a name like 'Hello' and confirm the save. Now you can experiment with different things like entering different Yaml strings into the Input, or renaming the Action. You can create a German version of this experiment by having the Action print out "Hello, verld!" instead!

This completes the first tutorial for the LabRAD Experimenter. In the next tutorial you will become familiar with some of the Experimenter's more powerful tools.