Ctrl+K

Adding support for a new machine of an existing type

Adding support for a new machine of an existing type#

This guide explains how to add support for a new machine of an existing type. For example, if you want to add support for a new liquid handler, you should read this guide. If you want to add support for a new type of machine, you should read this guide first.

The machine types that are currently supported are:

Two documents that you can read before you start are:

  • CONTRIBUTING.md: This document contains general information about contributing to PyLabRobot, and covers things like installation and testing.

  • How to Open Source: This document contains step-by-step instructions for contributing to an open source project. It is not specific to PyLabRobot, and serves as a reference.

Thank you for contributing to PyLabRobot!

Background#

Backends are minimal classes that are responsible for communicating with a machine and are thus specific to one machine. Frontends are higher level classes that are responsible for orchestrating higher-level state and providing nice interfaces to users, and should work with any machine. For example, the STAR liquid handler backend is responsible for executing the liquid handling operations on a Hamilton STAR, while the LiquidHandler frontend is responsible for making sure a requested operation is valid given the current state of the deck.

Backends should contain minimal state. We prefer to manage the state in the frontend, because this allows us to share the code across all machines of a type. For example, the liquid handler backend does not contain any information about the deck, because this is managed by the frontend. If a certain machine has a specific state that needs to be managed, like whether the gripper arm is parked on a liquid handling robot, that should be done by the backend because it is specific to the machine.

0. Get in touch#

Please make a post on the PyLabRobot Development forum to let us know what you are working on. This will help you avoid duplicating work, and it is also a good place to get support.

1. Creating a new concrete backend class#

It is easiest to start by copying the abstract base class for the machine type to a new file. You will find this in backend.py in the module for the machine type. For example, the liquid handling abstract base class is located at pylabrobot.liquid_handling.backends.backend. You should copy this file to a new file called <machine_name>.py in the same directory. For example, the liquid handling backend for the Hamilton STAR is located at pylabrobot.liquid_handling.backends.hamilton.STAR.

2. Implementing the abstract methods#

The abstract base class contains a number of abstract methods. These are the methods that are expected to be implemented by the concrete backend. You should implement these methods in the concrete backend. You can use the abstract base class as a reference for what the methods should do.

PyLabRobot aims to be OS-agnostic, meaning that it should work on Windows, Mac, and Linux. This maximizes flexibility for users and the reproducibility of experiments. However, this also means that you should not use any OS-specific libraries or dlls in the backend.

If an operation is not supported by the machine, you should raise a NotImplementedError.

The actual process of implementing the methods varies widely from machine to machine. It is generally useful to search for firmware documents, search for logs files generated by a manufacturer’s software, or find other open source projects that have implemented the same machine.

Contents