1. Intro to pylabnet

Installation

Refer to installation instructions here.

Key pylabnet Structure

pylabnet consists of several interacting components that work together to create a network of computers that can access and control hardware connected to any another computer. We review the main building blocks here:

• pylabnet can be used whenever we have a collection of computers that are all connected over a single local area network
• Whenever we have a hardware device that is physically connected to a computer (host computer), this host computer will connect to and control the device using a device-specific Driver which implements desired functionality using device-native commands. The host computer will also host a device Server that provides exposed Services, which are Python functions that other computers can use in order to interact with the device.
• In order to communicate with the device from another computer (client computer), the client computer will need to run a device Client locally, and we will connect to the Server by specifying its IP address and port. These parameters can also be automatically specified when the client is created from Launch Control instead (see below). Once the Client is initialized, it will be able to call client-side functions, which are communicated to the host computer via RPyC, translated to the equivalent server-side functions, and finally sent to the device via the device Driver.
• To provide logging of error, debug, or informational messages generated by the devices or functions, there is an analogous server-client structure for message logging. There will be a master computer / master logger that will start up a LogServer. All other pylabnet servers will then create their own LogClient to communicate with the LogServer in order to send messages and receive messages sent by other computers.

In principle, this is all that we need to run pylabnet! We can start Servers and Clients in Jupyter notebooks and use the associated device functionality from any connected computer on the local network. However, it is tedious to keep track of all the Servers and their associated IP addresses and ports, and it would also be annoying to have to remote into different computers to start up different device Servers. This brings us to the Launch Control GUI.

This brings several new functionalities:

• We can start a Server on a remote computer by specfiying its IP address and ssh parameters.
• We can create Clients that connect to the appropriate existing Server automatically (without specifying the Server IP/port) via name matching of the Server.
• We can launch scripts and GUIs for commonly performed tasks, and specify which Servers are required for these scripts to load. If these Servers do not exist, they will be created automatically together with the corresponding Client.
• We can specify device-specific and script-specific configurations using a JSON config file, which are then listed in the Launch Control GUI and can be double-clicked to launch their respective device Server or script.

Folder Structure

pylabnet/gui: modules for graphical output, e.g. plotting and PyQT based GUIs

pylabnet/hardware: modules for hardware drivers, organized by task. For simple devices, an interface structure is followed, so that the user can use simple, hardware-independent interface commands in scripts. Individual drivers connect those commands with hardware specific operations. For more complicated or specialized devices, the interface layer may be skipped. These can be used directly without involving any client server interface for direct and transparent access to devices if necessary

pylabnet/launchers: scripts for launching experiments or components of experiments, such as hardware servers

pylabnet/network: all functionality relating to the client-server interface for pylabnet, including core implementation of ServiceBase, ClientBase, and GenericServer, as well as implementation of specific Service and Client classes for relevant GUI and hardware modules

pylabnet/scripts: experimental scripts. These may combine several different devices and GUI objects into a single experiment, and are the main interface for the user. These potentially leverage (multiple) client-server interface(s). For a given experiment, once all device connections are properly initialized via notebooks, for a given experiment, the user should be able to instantiate a script object which can be used to easily run the desired experiment and output the result conveniently.

pylabnet/utils: low-level utilities, such as logging

Notes for new developers

1. Create a new working branch before making any changes to the repository. Please do not make the changes directly in the master branch! This can be done either from your IDE of choice, or from the command line within the local pylabnet repository using git checkout -b <new-branch-name>. It is recommended to create a branch from the existing master branch instead of branching off another existing feature branch to avoid conflicts.

2. When creating a branch for the first time, it will not be visible online on the GitHub repository since the branch only lives locally on your computer; you will need to push it onto the repository (using git push -u origin <new-branch-name>). Note that pushing changes to the lukingroup/pylabnet repository requires administrative access. Please contact one of the previous contributors for details.

3. Implement and test your changes on the local working branch. It is best practice to commit often for every small increment of code developed, and include descriptive message for each commit -- avoid one single giant commit for the entire project! For long-running development branches, try and keep your local repository up to date with the master branch by merging regularly from the master branch (using git pull origin master) to avoid unnecessary merge conflicts down the line.

4. For GUI-based applications, it is recommended to create a launcher module (see here for more details). For non-GUI applications (e.g. device drivers, servers & clients), it is recommended to make a Jupyter notebook in the pylabnet/demo folder to demonstrate and test the added functionality.

5. Once the feature is stable and working, commit all changes locally and push them onto the GitHub repository. Submit a pull request with documentation of what was changed and any notes about how to use the new functionality, and assign reviewers who will check and approve this code to be merged into the master branch.