A script to install the labscript suite onto a system.
[TOC]
You will need to install Python and Mercurial prior to running the labscript suite installer. Mercurial—also known as 'hg'—is a 'version control system', which the installer uses to download the latest versions of the labscript suite components from bitbucket.org, and which you can use to update those components to newer versions in the future.
On Windows, we recommend you obtain Mercurial by installing TortoiseHg and Python from the Anaconda Python Distribution. For new setups, we recommend using Python 3. The labscript suite is compatible with Python 2.7, but Python 2.7 is nearing end of life and the labscript suite will eventually drop support for it.
If you are using the Anaconda Python distribution, we recommend that you install it
"just for me" (not "for all users"), and that you do not check the "add Anaconda to the
PATH" checkbox in the installer. Then, to use Anaconda Python from the command line,
open the "Anaconda Prompt" start menu shortcut instead of cmd.exe. From there you can
use the python, conda and pip commands as required below. If using Anaconda Python
on Unix, you will need to follow Anaconda's instructions for your operating system and
shell to activate the conda environment before running commands. You may use Anaconda
environments to install multiple copies of the labscript suite if you like—if so the
start menu shortcuts will contain the conda environment name.
Use mercurial to download ('clone') the latest version of the installer from bitbucket.
You can do this using TortoiseHg's graphical interface by right clicking in your file
manager and selecting Tortoisehg > Clone. Then, enter the address of this repository,
https://bitbucket.org/labscript_suite/installer in the 'source' field and click
'clone'. Alternately, you can clone this repository from the command line using the
following command:
hg clone https://bitbucket.org/labscript_suite/installerWhichever method is used, a folder called 'installer' will be created in the current directory. TortoiseHg, if you used it, may open 'hg workbench' showing the revision history of the installer itself. You can close that for now.
Open the command prompt (the Anaconda Prompt if using Anaconda) and navigate to the
freshly-cloned 'installer' folder using cd. To quickly navigate to a particular folder
in Windows, you can press Ctrl-L in the file explorer to highlight the current
directory, and copy it to the clipboard with Ctrl-C. Then, in the command prompt type
cd and a space followed by Ctrl-V, and press enter. Once in the installer directory
run the installer by typing
python setup.py installand follow the prompts.
Note: if on Unix, you may need to specify python3 instead of just python to ensure
the suite is installed with Python 3 instead of Python 2. If on Unix and using system
Python (i.e. not Anaconda), you should also run the above command with sudo. Even
though the installer will by default install the labscript suite to your home directory,
in order to add that directory to the Python search path, it may need root privileges.
During installation, the installer will check if the required Python packages are installed, and will list any that are not. If using Anaconda, most packages are available in the conda repositories and can be installed by typing:
conda install <package>from the Anaconda prompt. Some packages are not available in the conda repositories however, and these should be installed using pip, the standard Python package manager, by typing:
pip install <package>As a general rule, always prefer using conda, where possible, and use pip only to
install packages not available from conda. If you are on Windows and not using Anaconda,
you can install all packages using pip. If you are on Unix and not using Anaconda, you
may have another package manager that you prefer installing packages with, only using
pip for the packages not available from your package manager.
Once all required (and desired optional) Python packages are installed, the installer will copy the labscript suite components to the chosen install directory, add that directory (as well as the 'userlib' and 'userlib/pythonlib' subdirectories—more on these later) to the Python search path, and if on Windows, will create start menu shortcuts for the applications.
If you encounter a problem during installation, you may wish to try running
python setup.py cleanto clear temporary files from the installer and begin installation from scratch. Do not hesitate to ask for help or report a problem with the installer (or any labscript suite component) by filing an issue here on the installer's Bitbucket repository, or by sending a message to the mailing list.
To use the labscript suite, you will need at the very least, a text editor to write labscript experiment scripts. Notepad++ and Sublime Text are great options, but any text editor or Python IDE will do, including Spyder which comes with Anaconda and is geared toward those familiar with MatLab. The single most important issue when setting up a text editor to write Python code is that you configure it to insert four spaces—and not a tab character—when you hit the tab key. Almost all Python code is written with four spaces used for indentation, and you will run into difficult-to-debug issues if your code contains tab characters. So whichever text editor you install, if it does not already insert four spaces (Spyder already does for example), check its documentation for how to configure it to do so.
Labscript shot files are in the HDF5 format, and can be viewed using the HDFview tool. Although you don't need HDFview to use the labscript suite, it can be informative to quickly inspect shot files to see their contents without writing Python code.
The installer creates a file labscript_suite/labconfig/<your_computer's_hostname>.ini,
which contains configuration settings for the labscript suite. The reason the filename
is your computer's hostname is that the labscript suite can be run over multiple
computers, and these computers may need to have configuration files that are in sync
with each other in order for the labscript suite components to communicate with each
other. As such, you may wish to keep all the configuration files for a laboratory in one
folder under version control. The filename being the hostname means labscript suite
programs know which file to read even if several config files are present.
Most of the settings in labconfig do not need to be modified. Exceptions are:
[DEFAULT]/experiment_name: this is the name of the experiment, or laboratory, as a
whole. This name determines the names of subfolders where shot files are saved,
subfolders where saved settings from labscript suite applications are stored, and
default locations where labscript suite programs expect experiment scripts and analysis
scripts to be located. It should be short, and a valid Python module name, i.e. contain
only alphanumeric characters and underscores, and not begin with a numerical digit (this
ensures that code stored in subfolders with this name can be imported by other Python
code). As with the labconfig file being specific to each computer, experiment names
being unique to different experiments allows experiment scripts and other data from
multiple experiments to be stored in the same version control repository without
interference.
[DEFAULT]/shared_drive: this is the drive letter or mount path of the drive that shot
files (and some other files) will be stored on. If running the labscript suite on
multiple computers, this is how the programs share shot files - by passing filepaths to
each other that refer to files on the shared drive. If using the labscript suite on a
single computer, you can leave this as C:\ or ~/labscript_shared on Windows or Unix
respectively. Then shot files will be saved in C:\Experiments or
~/labscript_shared/Experiments. Otherwise, set it to the drive letter of a network
drive that will be accessible to all computers running labscript suite programs (it is
OK if each computer has the shared drive mounted as a different drive letter or at a
different mount point, so long as this setting in each computer's labconfig file points
to the right location).
[servers]/zlock This is the hostname or IP address of the computer that will be
running a 'zlock' server. Zlock is a program that tracks which other program has a file
open at any time. By asking zlock server for permission before opening a file, labscript
suite programs ensure that they do not write to a file at the same time as another
labscript suite program is reading or writing, which could cause data corruption. If you
are running the labscript suite on a single computer, you can leave this as 'localhost'
and not take any further action. Otherwise, choose one of your computers—preferably one
that is likely to be reliably on all the time and not under very high load—and enter its
IP address or hostname here. All computers that might access the same shot files (i.e.
all that have been configured to use the same shared drive for shot files) must be
configured to use the same zlock server, otherwise there is a risk of data corruption.
See below for how to start the zlock server on the computer in question
[programs]/text_editor This is the command or path to the text editor that will be
launched when you click buttons in labscript suite programs to edit labscript experiment
files or your connection table. For example, you might set it to
C:\Program Files\Sublime Text 3\sublime_text.exe on windows or subl on Unix. You
normally don't need to modify text_editor_arguments, but you can if you wish to pass
additional command line arguments to the text editor when it is launched.
[programs]/hdf5_viewer This is the command or path to the HDF viewer executable. You
might set it to for example
C:\Users\<your_username>\AppData\Local\HDF_Group\HDFView\3.1.0\hdfview.bat on windows,
or hdfview or hdfview.bat on Unix, depending on how/where you installed HDFview to
(the above path is the default install location for HDFview 3.1.0 on Windows). This will
be used to open a HDF5 file for viewing when, for example, double clicking a shot file
in lyse.
On the computer that you have decided to run the zlock server, from the command prompt (or Anaconda Prompt), run:
python -m labscript_utils.zlockThat's it! A zlock server is now running on that computer. You may wish to automate starting the zlock server when the computer starts, and/or create a batch file to run the above. In either case, if using anaconda on Windows, the batch file will need to activate the conda environment first, which will look something like this:
CALL C:\Users\<your_user_name>\AppData\Local\Continuum\anaconda3\condabin\conda.bat activate
start cmd /k python -m labscript_utils.zlockwhere <your_user_name> is replaced with your username. The above method of activating
conda from within a batch file is current as of conda 4.6.11 (April 2019), but may
change in the future, so if it does not work, you may wish to search for instructions
specific to your version of conda.
Note: if a labscript program runs and sees that the zlock server is supposed to be on that computer, but that the server is not running, it will start a zlock server running in the background (this is why you do not need to start zlock manually if only using one computer). So if you forget to start the zlock server before starting other programs, but then remember and start the zlock server manually, you may get an error that 'the port is already in use'. You can just ignore this and rest assured that zlock is already running. However, if you want to have a visible terminal for zlock, you will need to kill the background one using the task manager, or reboot.
A general note about task management: All labscript suite processes will appear in Windows' task manager as "Python". To see which is which, if you need to end them, in Windows 8 or 10, go to the 'details' tab of the Task manager, right click on one of the column headers and click "Select Columns". Select the "Command line" column. Then you will be able to see in this column which Python process corresponds to which labscript suite component. In Windows 7, you can view this information in a tooltip when hovering over the task.
In your labconfig file, one of the configuration settings is
[paths]/connection_table_py. This is the location of the python file containing your
'connection table'. A connection table is an experiment script, written in Python,
containing a description of the devices in use in your experiment and how they are
connected to each other. It is a valid experiment script, and in principle could
compiled and run just like any other labscript experiment script. Instead of actually
running it however, when this experiment script is compiled, the resulting HDF5 file is
used by BLACS to know what hardware is in use in the experiment so that it can set up
the appropriate device tabs in its user interface and initialise communication with the
devices in question.
If you did not change the labconfig setting, then labscript suite programs will expect
your connection table .py file to be called connectiontable.py, and to be located
within your experiment-specific 'labscriptlib' folder:
<labscript_suite_directory>/userlib/labscriptlib/<experiment_name>/. Create this file,
including the <experiment_name> parent directory, and edit it to make your first
connection table. Here is a minimal connection table .py file that can get you started,
though describing how to make a complete and realistic connection table is outside the
scope of this getting-started guide:
from labscript import *
from labscript_devices.PulseBlaster import PulseBlaster
PulseBlaster('pulseblaster_0')
if __name__ == '__main__':
start()
stop(1)This connection table imports the PulseBlaster labscript device class from the
labscript_devices Python package, creates an instance of it, specifying its name, and
then calls start() and stop(), which are functions from the labscript Python
package. Calling these two functions is necessary to tell the labscript module to save
the details of this experiment script to a HDF5 file, even though that file will only be
used for the description of devices contained within it, and not for running any
experiment (which in this case would be an experiment of duration 1 second, that does
nothing). By wrapping the start() and stop() functions in the
if __name__ == '__main'__ check, we ensure that those functions only run if this code
is executed directly by Python, and not if this code is imported by another Python
script. This is useful since you may wish to import this connection table file in other
experiment scripts.
Note: there are at present two common practices among labscript users as to whether to
have a single connection table .py file that all experiment scripts import, or whether
to duplicate, within each experiment script, the bits of the connection table that are
relevant to that specific script. Both practices have their pros and cons. Using a
common connection table means that one need not duplicate code, which can be
time-consuming and prone to human error. However, duplicating the code into each
experiment script means that each script has a self-contained record of the devices it
requires and their configuration, and any devices that are in your lab but not in use by
a specific script will not need to functional in order for the script to run (BLACS will
simply skip over these devices when it comes time to run an experiment). The choice is
yours, but if you do decide to use a common connection table that is imported from other
scripts, instead of importing it normally, you will need to use the function
labscript_utils.import_or_reload, like so:
from labscript_utils import import_or_reload
import_or_reload('labscriptlib.<experiment_name>.connectiontable')
# other imports and experiment script continue hereThis is because, when runmanager compiles shots, it runs the experiment script file
multiple times within the same Python process. Python caches imports, such that if you
import a module twice, the second time the imported code does not actually run. Because
of the way labscript works, the code in the connection table must run ever time a shot
file runs. The import_or_reload() function ensures this. Readers familiar with Python
may realise that one could achieve the same result by putting the connection table code
within a function, and calling that function within the if __name__ == '__main__' of
connectiontable.py block as well as at the top of experiment scripts. This will work
too.
Once you have created your connection table .py file, it needs to be compiled to produce
the connection table HDF5 file. You could do this using runmanager, and then manually
rename the resulting shot file and move it to the correct location, however a quicker
way is using BLACS. Start BLACS from the start menu shortcut (or with python -m blacs
from a terminal if on unix). BLACS will complain with an error that it cannot open the
connection table HDF5 file. Dismiss this error, and from the 'connection table' menu,
select 'recompile'. This will open a dialog box from which you can compile your
connection table. Once it has successfully compiled, click the button to restart BLACS.
BLACS will then restart and load the device interfaces appropriate for the set of
hardware described by your connection table.
If your connection table requires 'globals' in order to compile—for example, calibration quantities used for unit conversion (so that one can use custom units to control devices in BLACS in manual mode), you may configure BLACS to compile the connection table using specified globals files, settable by going to connection table > select globals in BLACS. It is a good idea to store globals required by the connection table in a separate file than those used in the rest of the experiment, and to compile the connection table with your 'connection table globals' file, and to compile regular shots with both this file and another file (or several files) containing globals used in the experiment logic. This allows BLACS to prompt you to recompile the connection table if the relevant globals change, without the prompt giving false positives whenever unrelated globals are modified.
The labscript suite is now installed and configured on your computer/computers. You may
launch programs from the start menu items in Windows, or from a terminal (on any
operating system) using python -m <program_name>, where <program_name> is blacs,
runmanager, lyse, or runviewer. Launching from a terminal can be useful to see
additional output if something is going wrong, such as a program crashing.
The labscript suite installer creates a number of folders that it adds to the Python
search path, and as such, python code placed in these folders may be imported by other
Python code, whether it is an experiment script, an analysis routine, or something else.
These folders are the userlib folder within the labscript suite installation
directory, and the pythonlib folder within that. Typical usage is to place code that
you wish to re-use in experiment scripts within
userlib/labscriptlib/<experiment_name>, or, if the code is not specific to one
experiment, within userlib/labscriptlib/common/. Then such code may be imported as:
from labscriptlib.common.some_module import some_function
from labscriptlib.<experiment_name>.some_other_module import some_experiment_specific_functionSimilarly, code re-used by analysis routines can be placed in the analysislib subfolder, following the same pattern of an experiment-specific subdirectory and a 'common' subdirectory.
The labscriptlib and analysislib subdirectories are also the default locations for new experiment scripts and analysis routines respectively.
The pythonlib subfolder is added directly to the Python search path, so code within it
can be imported by name without the pythonlib prefix. This is a place to put modules
used perhaps both by experiment scripts and analysis routines, or by other code
altogether that happens to run in your laboratory.
When code is organised in this way, a laboratory or research group with multiple
experiments may have a single userlib folder, under version control or synchronised
across computers using Google drive or similar, without conflict, whilst still sharing
common components. It takes some discipline to keep things organised in this way, but is
worth learning how to use version control (for example mercurial or git) for the benefit
it provides in synchronising and tracking the history of changes to your experiment code
over time.
The labscript suite is an open-source, community project. Please contribute back! The open-source nature of the project is what makes it viable in the long run, but this relies on fixes and other work being shared. 'Upstreaming' (contributing back) your changes also means that other work on the labscript suite will be building on top of code that already contains your changes, avoiding a situation in which the code changes to a point where it is difficult to update to a newer version of the labscript suite whilst retaining custom changes you have made. Upstreaming your changes is the best way to avoid being stuck on a 'legacy' version of the labscript suite as it continues to improve in the future.
If you find a bug, please report it to the relevant subproject here on bitbucket, or if you are not sure, send an email on the mailing list. We may also make announcements on the mailing list from time to time, and it is a good way to be informed of issues others are having and their solutions, so you may wish to subscribe to the mailing list regardless.
If you fix an issue in the labscript suite, enhance it in a way that might be generally useful, or implement support for a device others might use, the best way to contribute it back is by making a 'pull request' on bitbucket to the relevant subproject. If you are having trouble working out how to do this, ask for help on the mailing list and we will try to help.
Finally, if you use the labscript suite in work leading to a scientific publication, do not forget to cite our article, A scripted control system for autonomous hardware-timed experiments, Review of Scientific Instruments 84, 085111 (2013). arXiv:1303.0080. Whilst it is not necessary to cite the software in every publication resulting from an apparatus that uses the labscript suite, it is reasonable to cite it in any context where you are otherwise describing the technical details of your apparatus.
The above instructions should be used to install the labscript suite. However, the install script can also be used to uninstall a previously made installation, and other less-commonly-needed functionality.
usage: python setup.py (install | uninstall | build | dist | clean)
Runs 'build' if it has not already run. Copies the labscript suite packages to a chosen install directory, adds them to Python's search path, and creates application shortcuts. Checks that dependencies are satisfied and list missing ones.
Removes labscript directories from Python's search path, removes application shortcuts and deletes the contents of the install directory, except for the userlib directory and config files. Install directory will be automatically detected by looking in Python's search path, or it can be provided as an argument if this fails.
The installer also copies also itself into the install directory as 'uninstall.py', and can used from there to uninstall the labscript suite.
Clones the labscript repositories from bitbucket into the current directory Which revisions are used can be set in setup.py, but defaults to
max(branch(default) and tag())which means the most recent tagged revision in the default branch. Since we use tags for version numbers only, this will use the latest stable release of each package.
Creates a zip file of the installer.
Removes build files and zip file, if any.