pylabnet

Client-server, Python-based laboratory software

This is the repository for pylabnet, a software package for client-server, Python-based experiment control, designed for use in solid-state quantum optics and quantum network experiments in the Lukin group.

Prerequisites

• Supported Python versions: 3.8 (tested on 3.8.10)

Installation

1. Make sure Git is installed on your computer. For Windows, this can be obtained from git for Windows.

2. In a terminal, navigate to where you want pylabnet to be stored and clone the repository onto the local machine (e.g. C:\\Users\\<Username>). The folder should not have a space in its path and should not be a protected system folder.

git clone https://github.com/lukingroup/pylabnet.git

3. Navigate into the root directory of the cloned repository - this is the Pylabnet root folder.

cd pylabnet

4. (Optional but highly recommended to avoid conflicts with dependencies) Create a virtual environment using the following command:

python -m venv <env_path>

where <env_path> is to be replaced with the desired location of the virtual environment. For example, if you want to name your virtual environment env, the command would simply be python -m venv env.

5. (If step 4 is performed) Activate the development environment using the command:

<env_path>\Scripts\activate # FOr Windows
. <env_path>/bin/activate   # For Linux

If this has succeeded, you should see something like (env) appear at the start of each terminal prompt. You can also check by running Python and then runing import sys; sys.prefix and make sure that it returns the path of the virtual environment you have created. If using an external IDE like VS code, make sure to set the default interpreter in your IDE to <env_path>\Scripts\python.exe (Windows) or <env_path>/bin/python (Linux).

6. Update pip version:

python -m pip install --upgrade pip

7. Install all package requirements:

pip install -r requirements.txt

If it fails, make sure that your Python version is supported and that you have upgraded pip.

8. Finally, run the command to install pylabnet:

python setup.py develop

There may be some errors during dependency installation, but as long as the command terminates with output Finished processing dependencies for pylabnet==x.y.z the installation has worked.

9. To confirm that the installation has completed, you should be able to run import pylabnet in your scripts, and you should also find the executables pylabnet_master and pylabnet_staticproxy in the folder <env_path>\Scripts (Windows) or <env_path>/bin (Linux).

10. The package uses SSL authentication via a self-signed private key. You can generate this key using OpenSSL from the command line (for Windows, OpenSSL can be accessed via the Git Bash shell installed together with Git for Windows):

openssl req -new -x509 -days 365 -nodes -out pylabnet.pem -keyout pylabnet.pem

All questions are optional and you may adjust the value of the days flag in order to change the period over which the key is valid. This private key file pylabnet.pem is generated in C:\Users\<Username>\ by default in Windows and should be placed into C:\Windows\System32 (Windows) or /etc/ssl/certs (Linux).

11. Create a configuration file pylabnet/configs/static_proxy.json with the following fields:

{
    "logger_path": "C:\\Users\\<Username>\\pylabnet_logs", # Only required for master logger (i.e. running pylabnet_master)
    "master_ip": "192.168.50.101",      # Only required for logger client (i.e. running pylabnet_staticproxy)
    "master_log_port": 12345,           # Chosen by the master logger, clients will need to specify the same port as the master
    "master_gui_port": 12346            # Chosen by the master logger, clients will need to specify the same port as the master
}

• Note that the comments above should be removed before saving as JSON files do not support comments.
• The master_log_port and master_gui_port are freely chosen by the master logger, and all clients will need to specify these same ports in order to connect to the master logger. logger_path is freely chosen on the master logger to determine where it should store its logs.
• Clients will additionally also need to specify the master logger's IP address with master_ip.

12. Finally, to test this, run pylabnet_master in the folder <env_path>\Scripts (Windows) or <env_path>/bin (Linux) and if it does not appear to freeze or crash, you are done with setup!

Initial Setup Notes

Configuration and environment files

• In order to ssh into remote computers and start up remote device servers, you will need to create an environment file .env in the Pylabnet root folder with the following field:

LOCALHOST_PW=REMOTE_PC_PASSWORD

A big limitation of the current approach is that it requires all target remote computers to have the same login password.

• (Optional): Create a configuration file pylabnet/configs/lab_name.json with the following field:

{
    "lab_name": B16
}

This can be used for tagging of servers and filtering of servers by lab. Defaults to "NO LAB" if not specified.

• (Optional): Create a configuration file pylabnet/configs/network_configuration.json with the following fields (remove the comments before saving as JSON):

{
    "subnet": "192.168",          # Windows
    "network_interface": "enp0s3" # Linux
}

This is used to specify which IP address of the local computer should be used when creating servers in the event that it has more than one (e.g. one IP for the LAN and another IP for the Internet). For Windows, this is done by specifying a prefix that the IP address should satisfy, while for Linux this is done by specifying the network interface that should be used. To check what IP addresses and network interfaces the computer currently has, run the command ipconfig on Windows or ifconfig on Linux.

Windows Firewall

You will likely need to allow Python through Windows Firewall the first time you run Launch Control on a new machine.

---

Usage

The main executables used for launching the Launch Control GUI are pylabnet_master and pylabnet_staticproxy located in the folder <env_path>\Scripts (Windows) or <env_path>/bin (Linux). If desired, you can create shortcuts for these executables together with the pylabnet_newlogo.ico icon (shown above) for bonus style.

The master Launch Control pylabnet_master starts a LogServer and also keeps track of all servers on the network, while proxy Launch Control instances simply connect to the master logger and mirror its information for convenience on remote machines. The general workflow for working with Launch Control is the following:

1. Choose a computer to be the master logger. We recommend that this computer be stable with low downtime as all pylabnet communication will require the master logger to be online. Here, launch a master Launch Control using the pylabnet_master executable.
2. For all other computers on the network, launch a proxy Launch Control with pylabnet_staticproxy to mirror the information that is being recorded on the master logger. This enables the local computer to receive logging messages from all other computers on the network.
3. For each device that you want to connect, a separate configuration JSON file will be required to specify parameters such as the device ID and ssh settings (if the device is located on a remote computer). These config files must be located in pylabnet/configs/devices/<device_type>/<config_filename>.json. To start this device server, double click on the config filename in the Devices column of Launch Control. You can then write local scripts that connect to these device servers to interact with the device.
4. For each script that you want to run, a separate configuration JSON file will be required, which minimally specifies the prerequisite device servers and the script location. These config files must be located in pylabnet/configs/script/<script_type>/<config_filename>.json. To start this script, double click on the config filename in the Scripts column of Launch Control.

For an in-depth discussion of how pylabnet works under the hood, refer to the Wiki for more information.