What is Automancer?

Introduction

Automancer is a software application which allows users to automate lab protocols. A protocol consists in a complex or less complex structure that describes actions to take on different devices at different moments.

Unlike other scheduling systems, Automancer relies on text protocols defined in a simple, human-readable language that can be learned in a few hours. Despite not being a full programming language, it allows for the creation of complex protocols with advanced features that would require a significant amount of code to implement in a programming language.

Protocol examples

A simple protocol might look like the following. This protocol is composed of two 10-second steps, one with a pressure set at 10 psi and the other at 12 psi.

protocol:
  actions:
    - wait: 10 sec
      PressureController.setpoint: 10 psi
    - wait: 10 sec
      PressureController.setpoint: 12 psi

A more complex protocol could look like the following. That one integrates a record of the pressure value over time, and uploads it to an S3 bucket at the end. By using a shorthand, parts of the protocol can be reused across a protocol or multiple protocols, keep them DRY.

Note also the use of the {{ ... }} syntax to expressions. Each expression is re-evaluated when one of its dependencies changes, enabling the creation of dynamic protocols that react to the environment, as reported by sensor readouts.

shorthands:
  record_field:
    record:
      fields:
        - name: Pressure
          value: {{ arg.value }}
      output: {{ arg.output }}

protocol:
  actions:
    - actions:
        - wait: 10 sec
          PressureController.setpoint: 10 psi
        - wait: 10 sec
          PressureController.setpoint: 12 psi
      record_field:
        value: {{ PressureController.readout }}
        output: record.csv
    - s3_upload:
        source: record.csv
        bucket: pressure-records
        region: eu-central-1
        target: {{ f"records/{int(time())}.csv" }}

Protocol format

Protocols in Automancer are written as text files in a custom language called PCRL. This language is very close to YAML, without the rarely-used features that make YAML a very complex language, contrary to what one make think at first glance.

The use of text files as opposed to a visual editor has numerous advantages:

Protocols can be easily shared, by email, on a drive service, SFTP, Git, etc.
Protocols can be edited with any text editor, including IDEs such as Visual Studio Code or Sublime Text.
Protocols are lightweight, they rarely weight more than 100 kB.
Protocols can be versioned using Git or other source control management systems.
Protocols can be generated by any program that can output YAML, or a lower-level data structure when interfacing with the API.
Protocols are reproducible. The same protocol will always produce the same results and it is trivial to observe the difference between two protocols using a text editor.

Modular design

Automancer is designed to be modular on two levels. First, Automancer itself is composed of several modules that communicate with each other, and can be replaced for users with advanced needs. In particular, the following modules work together in Automancer:

automancer – The core Python package of Automancer. Its code is in host.
automancer_server – A Python package that builds on top of automancer and exposes its API over pipes, TCP sockets, UNIX sockets or WebSockets. Its code is in app/server.
automancer-client – A TypeScript/SCSS project that provides the user interface powered by React. Its code is in client.
automancer-app – An Electron app written in TypeScript that embeds the user interface into a native application. Its code is in app/electron.
automancer-shared – A TypeScript package that provides types and platform-neutral utilities for all other TypeScript packages. Its code is in app/shared.
automancer-library – A TypeScript package that provides reusable components for server-side TypeScript packages, in particular clients of automancer_server. Its code is in app/library.
automancer-vscode – A Visual Studio Code extension written in TypeScript that provides a large number of features and can be used as an alternative to the user interface. Its code is in app/vscode-extension.

A few other projects that have been developed for and are heavily used in Automancer:

Second, Automancer doesn't do much on its own but is meant to be extended using plugins. A plugin is a Python package that can be trivially installed from PyPI to extend Automancer's capabilities. More specifically, plugins can do one or more of the following:

Add a device control command to the protocol language, for example to control a pressure controller.
Add a control flow command to the protocol language, for example to add support for loops.
Add a visualization panel to the user interface, for example to observe a complex device's status.
Define devices directly, allowing commands and visualization to be generated automatically with little effort.