Labware Model

Overview

LabOS controls a wide variety of laboratory instruments that operate on labware. For example, a liquid handler may transfer liquids from tubes to plates and a plate reader may read the contents of a 96 well plate. LabOS maintains a labware catalog using its own labware model. When communicating with an instrument that requires a labware definition, it translates the LabOS labware definition to one that the specific instrument can understand. This document describes the LabOS labware model.

Unless otherwise noted, the document describes version 2.1 of the labware model. Version 1, the initial attempt at a labware model, was superseded by version 2.0 in Q1 of 2019.

Labware Families

Each labware supported by LabOS belongs to one of several families. While every family shares a set of common properties (e.g., name), each family also has a set of properties that are unique to that family. Below is a list of supported labware families:

  • Labware – Typical plates and reservoirs, such as a 96 well PCR plate or a single well reservoir. This is the most common type of labware to appear in LabOS.
  • Tuberack – Tube holder. The labware itself cannot hold liquids. It holds tubes of a specific type (e.g., 15 mL tubes) and those tubes hold liquids. For example, Opentrons 24 tube rack for 2 mL tubes.
  • Tube – A tube, which typically is placed inside of a compatible tube rack. Tubes are single well labware.
  • Tiprack – Combination of tips and a tip holder/carrier. This labware defines the dimensions of the tip holder as well as the properties of the tips it is holding. For example, 200 uL filtered Ritter tips in a tall tip holder for the LabMate liquid handler.
  • Carrier – Labware which doesn’t itself have wells but holds another labware. Examples include magnets (e.g., Alpaqua magnet) and thermo-conductive plates (e.g., Corning CoolSink). Carriers could also just be adapters that simply raise the height of another labware.
  • Cover – Lids that are placed on top of, for example, plates.
  • Generic Container – Models a container of unknown dimensions and possibly unknown volume. These are used to model external sources of liquids. For example, a dispenser might be connected to a bottle that holds the liquid it is dispensing.
  • Trash – Denotes an instrument’s trash slot. This labware type is auto generated by the system and cannot currently be defined as a custom labware.

Primitive Types

This document describes the LabOS labware model, starting from common labware properties and continuing to labware family specific properties. This section describes the primitive (base most) types.

Type

Description

"#bool"

Boolean value, which can be set to true or false

"#enum<>"

Value can only be set to one of the listed strings. For example, #enum<red,green,blue> can only be set to “red“, “green“ or “blue”.

"#float"

Value can be set to a floating point number (e.g., 127.51)

"#int"

Value can only be set to an integer value (e.g., 5 but not 5.2).

"#string"

Value is any string. It can be an empty string (e.g., ""), but cannot be null or undefined.

"#rstring"

Value is a required string and therefore cannot be an empty string.

"#uid"

Value is a globally unique object ID (e.g., 659cc20aa11e7bb236ae2fcc)

"#optional<>"

Optional value of a given type. For example #optional<#int> can be set to an integer or left undefined.

["#type"]

[] signifies a list (array) of items of a particular type. For example, ["#string"] is a list of strings.

"#reserved"

Property is reserved for undocumented or future use

Common Properties

All labware defined in LabOS will, at a minimum, have the properties listed below. Each labware will have additional properties depending on its exact family.
				
					{
  id: "#uid",
  name: "#rstring",
  lid: "#rstring | #int",
  isGlobal: "#bool",
  family: "#enum<carrier,cover,genericContainer,labware,tiprack,trash,tube,tuberack>",
  categories: ["#rstring"],
  restrictedInstrumentTypes: ["#rstring"],
  info: {
    name: "#rstring",
    description: "#string",
    vendor: "#rstring",
    vendorCode: "#rstring",
    partNumber: "#string",
    url: "#string",
    images: ["#rstring"],
  },
  blueprint: {
    dimensions: { 
      length: "#float",
      width: "#float",
      height: "#float"
    },
    payloads: ["#CompositionRef"],
    carriers: ["#CompositionRef"],
    wells: "#int",
  },
  movementStrategy: {
    canArmMove: "#bool"
  },
  deckSlotDimensions: {
    x: { dimensionType: "sbs", value: 1, },
    y: { dimensionType: "sbs", value: 1, }
  },
  optimizationHints: "#optional<#reserved>",
  state: "#reserved"
}
				
			

Base Properties

Top level labware properties.

Property

Description

id

Object’s globally unique database ID. This ID is used to query for the object using LabOS’ REST API. Each LabOS tenant will have its own database ID for the same piece of labware.

name

User settable name of the labware. By default, set it to the same value as info.name.

lid

Unique ID assigned to the labware. This ID is the same for each LabOS tenant if the underlying labware is the same. For example, Axygen 96-well plate, 2.2 mL, u-bottom was given a lid of 3 and this plate will have the same lid regardless which tenant it is in (even though the labware’s id will be different). For historical reasons labware created by Genie are assigned integer labware IDs. Labware created by users are assigned uids as the labware ID (e.g., 51935cca-a5ea-40b2-a4d3-4bd369b8b96e).

isGlobal

Set to true if the labware was created by Genie and false otherwise.

family

The family to which the labware belongs, see Labware Families for a full list.

categories

A list of strings to generically group labware. This property can be used for a logical grouping of labware, such as sbs to indicate that a labware fits into a standard SBS slot. The grouping can also be entirely arbitrary. Typically categories would just be set to ["sbs"] or ["sbs", "plate"] or ["tube"].

Labware composition rules can be expressed in terms of labware categories and certain operations in LabOS put category restrictions on which labware they can accept. For example, an operation may set to only accept labware in the "plate" category.

restrictedInstrumentTypes

This property indicates that a particular labware is restricted to a certain instrument or a certain set of instruments. It is usually set for tip racks since most instruments only work with their own consumables. For example, LabMate tip racks have their restrictedInstrumentTypes property set to ["@LiquidHandler:gls1"] to indicate these tips are for the LabMate liquid handler. Generically, restrictedInstrumentTypes values expect the following format instrument_family:instrument_type[:head_type]. For example, "@LiquidHandler:opentrons_ot2:p300_single_gen2" would indicate that a tip rack can be used with the P300 pipetting head on the Opentrons OT2 liquid handler.

Setting restrictedInstrumentTypes to an empty list ([]) indicates that the labware has no instrument restrictions.

optimizationHints

Optional setting that provides optimization hints to the LabOS LabSync algorithms. Currently only defined on tipracks and used for automatic selection of preferred tips.

state

The state object is used to keep track of the labware state – for example, how much liquid is in each well. This part of the LabOS labware model isn’t currently documented and the property name is reserved.

Info

The info object contains general information about the labware such as its name and vendor information.

Property

Description

name

User friendly name of the labware. Labware names typically follow this naming convention: <Company Name>, <number of wells>, <well volume>, <bottom style>, <use or other info>. For example Eppendorf, 96-well plate, 150 uL, v-bottom, PCR.

description

Longer description of the labware, typically supplied by the labware’s vendor.

vendor

Name of the labware vendor. This string should be set to something reasonable since the LabOS UI shows these strings in labware filters.

vendorCode

Vendor code. Typically set to the same value as the vendor.

partNumber

Vendor’s part number for the labware. If a labware has more than one part number (e.g., different numbers for different colors of the same labware), simply list all of the relevant part numbers as a comma separated list. This property can just be set to an empty string.

url

URL to see the labware description or definition – typically a URL to the vendor’s or a reseller’s site. This property can just be set to an empty string.

images

URLs to drawings or images of this labware. This property is typically set to an empty list ([]).

Base Blueprint​

The blueprint defines a labware’s physical characteristics. Each labware family has its own blueprint extensions, but each labware shares the following Base Blueprint properties.

Property

Description

dimensions

Physical dimensions of the labware – length, width and height of the labware in millimeters. SBS labware typically have a length of 127.76 mm and a width of 85.48 mm. The labware height is defined by the topmost point of the labware.

payloads

Defines how the height of the labware is affected by labware that is placed on top of this labware. For example, a tube rack could define compatible tubes as its payloads. Alternatively, a plate could define itself as its payload to specify the height offsets of stacking plates of the same type on top of each other. See Composition Rules for more information about stacking rules.

carriers

Defines how the height of this labware is affected when it is placed on top of another labware. For example, a tube could define the tube racks with which it is compatible. This value is similar to payloads only that it references the labware on which it is placed while payloads references labware that is placed on top of it. When defining a composition rule for two pieces of labware, you may define it through the payloads field or the carriers field. It isn’t necessary to define both. See Composition Rules for more information about stacking rules.

wells

Total number of wells in this labware. These could be liquid wells (e.g., for regular plates) or tip wells (e.g., for tipracks). This value is set to 0 for labware that doesn’t have wells (e.g., carriers and covers).

Movement Strategy

The movement strategy object provides directives to mechanical arms. Currently the only supported property is canArmMove which can be set to true if a labware can be moved by a mechanical arm and false if it cannot. Typically things like tube racks and magnets are defined to not be movable by an arm.

Deck Slot Dimensions

This object defines how much space a labware takes up on-deck in the x and y direction. It is meant to deal with labware that takes up more than a single SBS slot. It’s an experimental property and should always be set to the value shown below. The one exception are Generic Container labware – their dimensions are unknown, so dimensionType would be set to "unknown".

				
					  deckSlotDimensions: {
    x: { dimensionType: "sbs", value: 1, },
    y: { dimensionType: "sbs", value: 1, }
  }
				
			

Labware

The labware family extends the Base Blueprint model adding the camera and grids objects. camera is an experimental object and should, for the time being, be set to the value shown below. grids defines labware grids. Most labware will have a single grid, but irregular labware (e.g., Opentrons 10 tube rack for 15 mL and 50 mL tubes) would have more than one grid. See the Well Grids section for more information about grids.

				
					    camera: { exposure: 0, illumination: 0, imagingHeight: 0 },
    grids: ["#grid"],
				
			

Sample definition of a 96 well plate:

				
					{
  id: "60005d4989b41db0b71f42fb",
  name: "Eppendorf 96-well plate, 150 uL, v-bottom, PCR",
  lid: 32,
  isGlobal: true,
  family: "labware",
  categories: ["sbs", "plate"],
  info: {
    name: "Eppendorf 96-well plate, 150 uL, v-bottom, PCR",
    description: "Eppendorf twin.tec® PCR Plate 96, skirted, 150 uL, PCR clean, colorless, Catalog No. 951020401",
    vendor: "Eppendorf",
    vendorCode: "Eppendorf",
    partNumber: "951020401",
    url: "https://online-shop.eppendorf.us/US-en/Laboratory-Consumables-44512/Plates-44516/Eppendorf-twin.tec-PCR-Plates-PF-8180.html",
    images: [],
  },
  blueprint: {
    dimensions: { length: 127.76, width: 85.47, height: 15.66 },
    payloads: [],
    carriers: [],
    wells: 96,
    camera: { exposure: 0, illumination: 0, imagingHeight: 0 },
    grids: [
      {
        rows: ["A", "B", "C", "D", "E", "F", "G", "H"],
        cols: ["1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12"],
        offset: { x: 14.536, y: 11.44 },
        spacing: { x: 8.976, y: 9.0 },
        glsConstraints: [
          {
            position: 1,
            constraints: [
              { type: "min", pipette: 1, position: 1 },
              { type: "min", pipette: 2, position: 2 },
              { type: "min", pipette: 3, position: 3 },
              { type: "min", pipette: 4, position: 4 },
              { type: "min", pipette: 5, position: 5 },
              { type: "min", pipette: 6, position: 6 },
              { type: "min", pipette: 7, position: 7 },
              { type: "min", pipette: 8, position: 8 },
            ],
          },
          {
            position: -1,
            constraints: [
              { type: "max", pipette: 1, position: 1 },
              { type: "max", pipette: 2, position: 2 },
              { type: "max", pipette: 3, position: 3 },
              { type: "max", pipette: 4, position: 4 },
              { type: "max", pipette: 5, position: 5 },
              { type: "max", pipette: 6, position: 6 },
              { type: "max", pipette: 7, position: 7 },
              { type: "max", pipette: 8, position: 8 },
            ],
          }
        ],
        well: {
          diameter: 5.4,
          depth: 14.68,
          shape: "circular",
          bottom: "v-bottom",
          maxVolume: 150.0,
          minVolume: 0.0,
          heightToVolume: 7,
          crossSectionArea: 28.27,
          liquidLevels: [
            { volume: 20.0, offset: 4.0 },
            { volume: 30.0, offset: 5.0 },
            { volume: 40.0, offset: 5.8 },
            { volume: 50.0, offset: 6.5 },
            { volume: 60.0, offset: 7.2 },
            { volume: 80.0, offset: 8.5 },
            { volume: 100.0, offset: 9.3 },
            { volume: 120.0, offset: 10.3 },
            { volume: 130.0, offset: 11.5 }
          ],
          pipetteAccess: { h: 1, v: 1 },
        },
      },
    ],
  },
  deckSlotDimensions: {
    x: { dimensionType: "sbs", value: 1, },
    y: { dimensionType: "sbs", value: 1, }
  },
  restrictedInstrumentTypes: [],
  movementStrategy: { canArmMove: true }
}
				
			

Sample definition of a 3 well reservoir:

				
					{
  id: "5f92dfcf28207e79efb4cbcc",
  name: "Agilent 3-well reservoir, 95 mL, v-bottom",
  lid: 20,
  isGlobal: true,
  family: "labware",
  categories: ["sbs", "plate"],
  info: {
    name: "Agilent 3-well reservoir, 95 mL, v-bottom",
    description:
      "Agilent Reservoir, 3 column, polypropylene, 95 mL/column, 285 mL maximum, pyramid base geometries, 44 mm height",
    vendor: "Agilent",
    vendorCode: "Agilent",
    partNumber: "204249-100",
    url: "https://www.agilent.com/store/en_US/Prod-204249-100/204249-100",
    images: [],
  },
  blueprint: {
    dimensions: { length: 127.76, width: 85.47, height: 43.87 },
    payloads: [],
    carriers: [],
    wells: 3,
    camera: { exposure: 0, illumination: 0, imagingHeight: 0 },
    grids: [
      {
        rows: ["A"],
        cols: ["1", "2", "3"],
        offset: { x: 27.895, y: 42.8 },
        spacing: { x: 35.77, y: 9.0 },
        eightSpan: { offset: { x: 27.895, y: 11.15 } },
        glsConstraints: [],
        well: {
          width: 71.0,
          length: 35.1,
          depth: 38.98,
          shape: "rectangular",
          bottom: "v-bottom",
          maxVolume: 95000.0,
          minVolume: 0.0,
          heightToVolume: 3,
          crossSectionArea: 2545.35,
          liquidLevels: [
            { volume: 6000.0, offset: 3.5 },
            { volume: 10554.0, offset: 5.5 },
            { volume: 16246.5, offset: 8.0 },
            { volume: 23077.5, offset: 11.0 },
            { volume: 29908.5, offset: 14.0 },
            { volume: 36739.5, offset: 17.0 },
            { volume: 43570.5, offset: 20.0 },
            { volume: 50401.5, offset: 23.0 },
            { volume: 66340.5, offset: 30.0 },
            { volume: 74310.0, offset: 33.5 },
            { volume: 85695.0, offset: 38.5 },
            { volume: 94803.0, offset: 42.5 }
          ],
          pipetteAccess: { h: 4, v: 8 },
        },
      },
    ],
  },
  deckSlotDimensions: {
    x: { dimensionType: "sbs", value: 1, },
    y: { dimensionType: "sbs", value: 1, }
  },
  restrictedInstrumentTypes: [],
  movementStrategy: { canArmMove: true }
}
				
			

Tuberack

Tuberacks follow the same schema as Labware but zero out depth, maxVolume, minVolume, heightToVolume, crossSectionArea and liquidLevels well properties (see below) since the tube racks themselves cannot hold liquids.

				
					            well: {
              depth: 0,
              maxVolume: 0.0,
              minVolume: 0.0,
              heightToVolume: 0,
              crossSectionArea: 0,
              liquidLevels: [],
            },
				
			

Sample definition of a 24 slot tube rack:

				
					{
  id: "629f882cf05a7f8a266934d0",
  name: "Opentrons 24 tube rack",
  lid: 73,
  isGlobal: true,
  family: "tuberack",
  categories: ["sbs"],
  info: {
    name: "Opentrons 24 tube rack",
    description: "Opentrons 24 Tube Rack",
    vendor: "Opentrons",
    vendorCode: "Opentrons",
    partNumber: "opentrons_24_tuberack_generic_2ml_screwcap",
    url: "https://labware.opentrons.com/opentrons_24_tuberack_generic_2ml_screwcap",
    images: [],
  },
  blueprint: {
    dimensions: { length: 127.75, width: 85.50, height: 78.5 },
    payloads: [
      { type: "lid", value: "76", offset: { x: 0.0, y: 0.0, z: -37.6 } },
      { type: "lid", value: "78", offset: { x: 0.0, y: 0.0, z: -39.6 } },
      { type: "lid", value: "79", offset: { x: 0.0, y: 0.0, z: -37.8 } }
    ],
    carriers: [],
    wells: 24,
    camera: { exposure: 0, illumination: 0, imagingHeight: 0 },
    grids: [
      {
        rows: ["A", "B", "C", "D"],
        cols: ["1", "2", "3", "4", "5", "6"],
        offset: { x: 18.21, y: 10.07 },
        spacing: { x: 19.89, y: 19.28 },
        glsConstraints: [
          {
            position: -1,
            constraints: [
              { type: "max", pipette: 1, position: 0 },
              { type: "max", pipette: 2, position: 0 },
              { type: "max", pipette: 3, position: 0 },
              { type: "max", pipette: 4, position: 0 },
              { type: "max", pipette: 5, position: 1 },
              { type: "max", pipette: 6, position: 2 },
              { type: "max", pipette: 7, position: 3 },
              { type: "max", pipette: 8, position: 4 },
            ],
          }
        ],
        well: {
          diameter: 11.3,
          depth: 0,
          shape: "circular",
          bottom: "flat",
          maxVolume: 0.0,
          minVolume: 0.0,
          heightToVolume: 0,
          crossSectionArea: 0,
          liquidLevels: [],
          pipetteAccess: { h: 1, v: 1 },
        },
      },
    ],
  },
  deckSlotDimensions: {
    x: { dimensionType: "sbs", value: 1, },
    y: { dimensionType: "sbs", value: 1, }
  },
  restrictedInstrumentTypes: [],
  movementStrategy: { canArmMove: false }
}
				
			

Tube

The tube family extends the Base Blueprint model, adding a tube object, which has the same schema as a labware well. When a tube is placed inside of a tube rack, LabOS (internally) replaces the tube rack’s grids[].well definition with the one of the tube. Below is a sample definition of a generic 2 mL tube. Note that the tube rack definition above has a composition rule for this tube’s labware ID ({ type: "lid", value: "76", offset: { x: 0.0, y: 0.0, z: -37.6 } }), meaning that this tube can be placed into the above tube rack.

				
					{
  id: "629f8b55f05a7f8a266934d3",
  name: "Generic 2 mL screw cap, v-bottom",
  lid: 76,
  isGlobal: true,
  family: "tube",
  categories: ["tube"],
  info: {
    name: "Generic 2 mL screw cap, v-bottom",
    description: "Generic 2 mL screw cap, v-bottom",
    vendor: "Genie Life Sciences",
    vendorCode: "GLS",
    partNumber: "N/A",
    url: "",
    images: [],
  },
  blueprint: {
    dimensions: { length: 12.5, width: 12.5, height: 45.6 },
    payloads: [],
    carriers: [],
    wells: 1,
    camera: { exposure: 0, illumination: 0, imagingHeight: 0 },
    tube: {
      diameter: 8.3,
      depth: 43.0,
      shape: "circular",
      bottom: "v-bottom",
      maxVolume: 2250.0,
      minVolume: 0.0,
      heightToVolume: 10,
      crossSectionArea: 70.9,
      liquidLevels: [
        { volume: 18, offset: 1 },
        { volume: 50, offset: 3 },
        { volume: 600, offset: 13.25 },
        { volume: 1150, offset: 23.5 },
        { volume: 1700, offset: 33.75 },
        { volume: 2250, offset: 44 }
      ],
      pipetteAccess: { h: 1, v: 1 },
    }
  },
  deckSlotDimensions: {
    x: { dimensionType: "sbs", value: 1, },
    y: { dimensionType: "sbs", value: 1, }
  },
  restrictedInstrumentTypes: [],
  movementStrategy: { canArmMove: true }
}
				
			

Tiprack

Tipracks extend the Base Blueprint model in the same way as Labware, adding the camera and grids objects but also add a tip object, which defines the properties of the tips inside of the tiprack.

Note that LabOS currently disallows the creation of custom tipracks.

				
					 tip: {
      carrierPartNumber: "#optional<#string>",
      images: ["#rstring"],
      length: "#float",
      maxVolume: "#float",
      maxVolumeWithOverAspirate: "#optional<#float>",
      maxVolumeWithAirGap: "#float",
      minVolume: "#float",
      defaultAirGap: "#float",
      color: "#rstring",
      filtered: "#bool",
      conductive: "#bool",
      sterile: "#bool",
      wideBore: "#bool",
      orifice: 0,
      volumeClass: "#int",
      lldSensitivity: "#int"
    }
				
			

Property

Description

carrierPartNumber

Optional model number of the tip holder. This is used to distinguish when the same type of hanging tips are placed into different types or tip holders. For example, the 200 uL tips for the LabMate liquid handler can be placed into short tip holders or tall tip holders. 1 mL tips on the other hand can only be placed into tall tip holders. carrierPartNumber captures the part number of the tip holder. This property is omitted if a tip is only ever placed into one type of tip holder.

images

URLs to drawings or images of the tip. This value is typically set to an empty list ([]) and is different from info.images, which would be images of the tip holder with tips.

length

Length of the tip in millimeters.

maxVolume

Maximum volume, in microliters, the tip can hold. This often, but not always, corresponds to the manufacturer’s advertised tip volume. Sometimes the tip can hold slightly more volume than advertised. Other times tip geometries are a bit inconsistent and it’s safer to set the maximum tip volume to something slightly smaller than the advertised tip volume.

maxVolumeWithOverAspirate

Liquid handlers provide an over-aspirate feature where, for example, in order to aspirate 10uL of a given liquid, the liquid handler aspirates 10.5 uL. This property defines the maximum volume if over-aspirate is used. This is an expert feature and could be dangerous to use without expert guidance. It’s therefore recommended to always set maxVolumeWithOverAspirate to the same value as maxVolume.

maxVolumeWithAirGap

This property allows to extend the maximum tip volume for air gaps. For example, if maxVolume is 200 uL and maxVolumeWithAirGap is 205 uL, it’s possible to aspirate 200 uL of liquid into the tip and then take a 5 uL air gap, but it’s not possible to aspirate 205 uL of liquid. By default, maxVolumeWithAirGap should be set to the same value as maxVolume.

minVolume

Minimum volume, in microliters, the tip can affect. For example, it’s not appropriate to try to aspirate 1 uL with a 1 mL tip.

defaultAirGap

Default air gap for this tip, in microliters.

color

Color of the tip when rendered in LabOS. The color is specified as an RGB value – e.g., #40DFF4

filtered

True if it’s a filtered tip and false otherwise

conductive

True if it’s a conductive tip and false otherwise

sterile

True if it’s a sterile tip and false otherwise

wideBore

True if it’s a wide bore tip and false otherwise

orifice

Deprecated value, just set to 0.

volumeClass

Tips are grouped into volume classes. For example, if an instrument supports 200 uL tips from multiple vendors, all of the 200 uL tips would have the same volume class. It’s much safer to swap a tip for another tip in the same volume class (e.g., 200 uL Ritter for 200 uL LabSource) than a different volume class (e.g., 50 uL tip for a 200 uL tip). The actual value of the volumeClass isn’t important, as long as the value is the same for all tips that are more-or-less interchangeable.

lldSensitivity

This is a Genie LabMate specific property. It’s used to properly detect liquid levels with the specified tip. LabMate blows out a small amount of air as it approaches the liquid and measures the difference in pressure. When the tip touches the liquid, the pressure changes and the instrument signals the start of the liquid level. This property is set by Genie’s firmware team.

Below is a sample tiprack definition for 200 uL filtered tips for the LabMate liquid handler, placed in a tall tip holder.

				
					{
  id: "630619b16142d5e2360b62b8",
  name: "Ritter - 200ul - Filtered - Tall Rack",
  lid: 93,
  isGlobal: true,
  family: "tiprack",
  categories: ["sbs"],
  info: {
    name: "Ritter - 200ul - Filtered - Tall Rack",
    description: "Ritter - 200ul - Filtered - Tall Rack",
    vendor: "Ritter",
    vendorCode: "Ritter",
    partNumber: "GLS1-200F-R",
    url: "",
    images: [],
  },
  blueprint: {
    dimensions: { length: 127.72, width: 85.41, height: 105.68 },
    payloads: [],
    carriers: [],
    wells: 96,
    camera: { exposure: 0, illumination: 0, imagingHeight: 0 },
    grids: [
      {
        rows: ["A", "B", "C", "D", "E", "F", "G", "H"],
        cols: ["1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12"],
        offset: { x: 12.75, y: 11.59 },
        spacing: { x: 9.0, y: 9.0 },
        glsConstraints: [
          {
            position: 1,
            constraints: [
              { type: "min", pipette: 1, position: 1 },
              { type: "min", pipette: 2, position: 2 },
              { type: "min", pipette: 3, position: 3 },
              { type: "min", pipette: 4, position: 4 },
              { type: "min", pipette: 5, position: 5 },
              { type: "min", pipette: 6, position: 6 },
              { type: "min", pipette: 7, position: 7 },
              { type: "min", pipette: 8, position: 8 },
            ],
          },
          {
            position: -1,
            constraints: [
              { type: "max", pipette: 1, position: 1 },
              { type: "max", pipette: 2, position: 2 },
              { type: "max", pipette: 3, position: 3 },
              { type: "max", pipette: 4, position: 4 },
              { type: "max", pipette: 5, position: 5 },
              { type: "max", pipette: 6, position: 6 },
              { type: "max", pipette: 7, position: 7 },
              { type: "max", pipette: 8, position: 8 },
            ],
          }
        ],
      },
    ],
    tip: {
      carrierPartNumber: "GLS1-1000-ER",
      images: [],
      length: 58.3,
      maxVolume: 200.0,
      maxVolumeWithOverAspirate: 200.0,
      maxVolumeWithAirGap: 200.0,
      minVolume: 1.0,
      defaultAirGap: 5.0,
      color: "#40DFF4",
      filtered: true,
      conductive: false,
      sterile: true,
      wideBore: false,
      orifice: 0.45,
      volumeClass: 3,
      lldSensitivity: 140
    },
  },
  deckSlotDimensions: {
    x: { dimensionType: "sbs", value: 1, },
    y: { dimensionType: "sbs", value: 1, }
  },
  restrictedInstrumentTypes: ["@LiquidHandler:gls1"],
  optimizationHints: { automaticGenerationPriority: 15 },
  movementStrategy: { canArmMove: true }
}
				
			

Carrier

Carriers don’t add anything new to the common labware model. Below is the definition of an Alpaqua magnet. Note that it defines a composition rule for plates placed on top of it as well as a composition rule for a specific plate (labware ID 18). The canArmMove property is set to false indicating that the magnet should not be moved by a mechanical arm.

				
					{
  id: "641c7f17f2800ddd23d662b5",
  name: "Alpaqua Magnum FLX",
  lid: 1007,
  isGlobal: true,
  family: "carrier",
  categories: ["sbs", "magnet"],
  info: {
    name: "Alpaqua Magnum FLX",
    description: "Alpaqua Magnum FLX",
    vendor: "Alpaqua",
    vendorCode: "Alpaqua",
    partNumber: "A000400",
    url: "https://www.alpaqua.com/product/magnum-flx/",
    images: [],
  },
  blueprint: {
    dimensions: { length: 127.76, width: 85.98, height: 35.14 },
    payloads: [
      { type: "cat", value: "plate", offset: { x: 0.0, y: 0.0, z: -8.0 } },
      { type: "lid", value: "18", offset: { x: 0.0, y: 0.0, z: -8.6 } },
    ],
    carriers: [],
    wells: 0,
  },
  deckSlotDimensions: {
    x: { dimensionType: "sbs", value: 1, },
    y: { dimensionType: "sbs", value: 1, }
  },
  restrictedInstrumentTypes: [],
  movementStrategy: { canArmMove: false }
}
				
			

Cover

Covers extend the Base Blueprint model, adding a piercers object. This is an experimental object and should be set to an empty list ([]). The intention was to model plate seals as labware of type Cover and then use the piercers property to indicate which tips, if any, can be used to pierce the seal.

Sample definition of the Azenta auto-sealing PCR plate lid:

				
					{
  id: "62191f7476ab13a7be82850a",
  name: "Azenta Auto-Sealing PCR Plate Lid",
  lid: 65592,
  isGlobal: true,
  family: "cover",
  categories: ["sbs"],
  info: {
    name: "Azenta Auto-Sealing PCR Plate Lid",
    description: "Azenta Auto-Sealing PCR Plate Lid",
    vendor: "Azenta",
    vendorCode: "Azenta",
    partNumber: "4ti-0291",
    url: "https://www.azenta.com/products/auto-sealing-pcr-plate-lid",
    images: [],
  },
  blueprint: {
    dimensions: { length: 128.10, width: 85.80, height: 8.20 },
    payloads: [],
    carriers: [{ type: "cat", value: "plate", offset: { x: 0.0, y: 0.0, z: -3.7 } }],
    piercers: [],
    wells: 0,
  },
  deckSlotDimensions: {
    x: { dimensionType: "sbs", value: 1, },
    y: { dimensionType: "sbs", value: 1, }
  },
  restrictedInstrumentTypes: [],
  movementStrategy: { canArmMove: true }
}
				
			

Generic Container

Generic containers extend the Base Blueprint model, adding a container object, which defines a set of optional container properties:

				
					    container: {
      minVolume: #optional<#float>,
      maxVolume: #optional<#float>,
    },
				
			

Sample definition of a generic container:

				
					{
  id: "6516bc266d25f970e7cff728",
  name: "Generic Container",
  lid: 1030,
  isGlobal: true,
  family: "genericContainer",
  categories: [],
  featureFlag: "",
  info: {
    name: 'Generic Container',
    description: 'Generic Container',
    vendor: 'Genie Life Sciences',
    vendorCode: 'GLS',
    partNumber: 'N/A',
    url: '',
    images: [],
  },
  blueprint: {
    dimensions: { length: 0, width: 0, height: 0 },
    payloads: [],
    carriers: [],
    wells: 1,
    container: {
      minVolume: 0,
    },
  },
  deckSlotDimensions: {
    x: { dimensionType: "unknown", value: 1, },
    y: { dimensionType: "unknown", value: 1, }
  },
  restrictedInstrumentTypes: [],
  movementStrategy: { canArmMove: false }
}
				
			

Trash

Trash denotes an instrument’s trash slot and follows the Labware model. Trash slots are auto generated by the system and cannot be defined as custom labware. An example of a trash is included just for completion’s sake.

				
					{
    id: 'default_trash',
    name: 'trash',
    lid: 0,
    family: 'trash',
    categories: [],
    info: {
      name: 'trash',
      description: '',
      vendor: 'Genie',
      vendorCode: 'Genie',
      partNumber: 'default_trash',
      url: '',
      images: [],
    },
    blueprint: {
      dimensions: { width: 85.48, length: 127.76, height: 0.0 },
      payloads: [],
      carriers: [],
      wells: 1,
      camera: { exposure: 0.0, illumination: 0.0, imagingHeight: 0.0 },
      grids: [
        {
          rows: ['A'],
          cols: ['1'],
          offset: { x: 63.88, y: 42.74 },
          spacing: { x: 0.0, y: 0.0 },
          glsConstraints: [],
          well: {
            width: 85.48,
            length: 127.76,
            depth: 0.0,
            shape: 'rectangular',
            bottom: 'flat',
            maxVolume: 0.0,
            minVolume: 0.0,
            heightToVolume: 0.0,
            crossSectionArea: 0.0,
            liquidLevels: [],
            pipetteAccess: { h: 12, v: 8 },
          },
        },
      ],
    },
    movementStrategy: {
      canArmMove: false,
    },
}
				
			

Shared Types

Well Grids

Labware in the Labware and Tuberack family consist of one or more grids. Each grid consists of equally spaced rectangularly laidout wells. For example, a typical 96 well labware has a single grid of 8×12 wells. Irregular labware are modeled as having multiple grids. When defining multiple grids, each well must have a unique well ID. Note that most instruments cannot support multi-grid labware.

A grid has the following definition:

				
					      {
        rows: ["#rstring"],
        cols: ["#rstring"],
        offset: { x: "#float", y: "#float" },
        spacing: { x: "#float", y: "#float" },
        eightSpan: "#optional<#reserved>",
        well: "#well",
        glsConstraints: "#glsConstraints",
      }
				
			

Property

Description

rows

IDs of the individual rows. The length of the rows list is the number of well rows in the labware. By convention alphabetic characters are used as row IDs – ["A", "B", "C", "D", ...].

cols

IDs of the individual columns. The length of the cols list is the number of well columns in the labware. By convention numeric characters are used as row IDs – ["1", "2", "3", ...].

offset

X/Y distance, in millimeters, from the top-left corner of the labware to the center of the top-left-most well of the grid.

spacing

X/Y distance from the center of one well to the center of the diagonally located well. All wells in a single grid must have a consistent distance. The x value is the distance from the center of a well to the center of the next well in the same row. The y value is the distance from the center of a well to the center of the next well in the same column.

eightSpan

Property marked for deprecation

Labware extension specific to the LabMate liquid handler. The LabMate expects the offset to represent the target location of the first pipette rather than the center of the well. For example, in case of reservoirs eightSpan.offset.y provides an override for offset.y when a LabOS labware is converted into the LabMate’s labware definition. This property is proprietary to the LabMate and can be calculated rather than defined in the model so it will be removed in future revisions of the labware model. Until then, it must be set for all reservoirs.

well

Defines the properties of the wells in the grid. See Well for more details.

glsConstraints

Property proprietary to Genie’s LabMate liquid handler. See the GLS Accessibility Constraints section for more details.

Well

The well object defines properties of a labware well. It consists of the following properties:

				
					        well: {
          diameter: "#optional<#float>",
          width: "#optional<#float>",
          length: "#optional<#float>",
          depth: "#float",
          shape: "#enum<rectangular,circular,hex,square>",
          bottom: "#enum<flat,circular,v-bottom,u-bottom,pyramid>",
          maxVolume: "#float",
          minVolume: "#float",
          heightToVolume: "#float",
          crossSectionArea: "#float",
          liquidLevels: ["#liquidLevels"],
          pipetteAccess: { h: "#int", v: "#int" },
        },

				
			

Property

Description

diameter, width, length

Labware with round wells define the diameter of the well, in millimeters. Labware with rectangular wells define the width and length of their wells. If diameter is defined, width and length must not be defined – and vice versa.

depth

Depth of the well (from blueprint.dimensions.height) in millimeters

shape

Shape of the well. Must be one of the following values: rectangular, circular, hex, or square.

bottom

Shape of the bottom of the well. Must be one of the following values: flat, circular, v-bottom, u-bottom, or pyramid.

maxVolume

Maximum volume, in microliters, the well can hold. This can be set to the working well volume or to the actual maximum well volume.

minVolume

Minimum amount of volume, in microliters, the well can hold. Currently always set to 0.

heightToVolume

Property is proprietary to the LabMate liquid handlers. It affects how fast the tip moves to follow the liquid while, for example, aspirating from a well. LabMates’ firmware will be updated to instead use the crossSectionArea property.

crossSectionArea

Set to length*width for square wells and πr^2 for circular wells. This value will be used by future LabMate liquid handlers to determine how fast the tips need to move to follow the liquid while, for example, aspirating from a well.

liquidLevels

Defines the labware’s Liquid Table, which are used by the “Estimated Liquid Level” feature in LabOS. If you don’t intend to use this feature, set the property to [].

pipetteAccess

Indicates how many pipettes (assuming the standard 9mm pipette pitch) can fit into a single well. v indicates how many pipettes can fit vertically and h how many pipettes can fit horizontally. For example h: 2 indicates that a Span 8 liquid handler can fit 2 pipettes into the each well. A single well trough would define pipetteAccess: { h: 12, v: 8 }, indicating that a whole 96 pipette head can fit into the single well.

Liquid Table

LabOS tracks the amount of liquid that is contained in each well and can direct a liquid handler to aspirate/dispense relative to the location of the liquid. The liquid can be detected using, for example, a LLD (Liquid Level Detect) feature, but (1) LLD isn’t supported on every instrument, (2) using LLD requires a new tip and (3) detecting liquid is a bit slower than moving the pipette to a static offset. LabOS can estimate the offset at which the liquid starts based on the amount of liquid it believes to be in the well. This feature is called “Estimated Liquid Level” and it relies on having an accurate liquid level lookup table for the given labware. If you do not intend on using the Estimate Liquid Level feature, simply set the liquidLevels property to [].

If you want to use Estimated Liquid Level and related features with the custom labware, you need to specify an accurate liquid level table. liquidLevels is a list of volume and offset pairs ({ volume: "#float", offset: "#float" }).

Property

Description

volume

Volume in microliters

offset

Offset, in millimeters, from the bottom of well for the specified volume

liquidLevels table may look as follows:

				
					          liquidLevels: [
            { volume: 20.0, offset: 4.0 },
            { volume: 30.0, offset: 5.0 },
            { volume: 40.0, offset: 5.8 },
            { volume: 50.0, offset: 6.5 },
            { volume: 60.0, offset: 7.2 },
            { volume: 80.0, offset: 8.5 },
            { volume: 100.0, offset: 9.3 },
            { volume: 120.0, offset: 10.3 },
            { volume: 130.0, offset: 11.5 }
          ],
				
			

Based on the table above, we know that if the well has 20 uL of liquid, the liquid would start at 4 mm above the bottom of the well. If the well has 50 uL of liquid, the liquid would start at 6.5 mm above the bottom of the well. If the volume falls in-between a specified range, LabOS will calculate the offset linearly. For example, if the well has 35 uL of volume, the liquid would start at 5.4 mm (5.0 + ((5.8 - 5.0) / (40.0 - 30.0)) * 5) above the bottom of the well.

Wells with a consistent shape (e.g., cylindrical wells) may only require 2 liquid level entries while wells with less cleanly defined well structured (e.g., round bottom wells) may require 5 to 10 liquid level entries to ensure accuracy. In many cases, it doesn’t make sense to add liquid level entries that are less than 1 mm apart.

Composition Rules

Composition rules are used to define offset adjustments for labware stacking. For example, when placing a 96 well plate on top of the same 96 well plate, the combined height usually isn’t twice the height of a single plate, but rather it’s twice the height of a single plate minus a small value – to account for the fact that one labware “sinks in” to the other one. Another example is placing a tube into a tube rack – what are the top-of-tube and bottom-of-tube offsets relative to the instrument’s deck? A composition rule defines how labware offsets are affected when labware is combined. Composition rules can be defined on the “bottom” labware through the carriers field or the “top” labware through the payloads field. It isn’t necessary to define both carrier and payload for the same labware pair. Which one to use is contextual. For example, when adding a tube for a global (and therefore read-only) tube rack, you’d define the composition rule on the tube’s carrier property.

				
					{
  type: "#enum<lid,cat>",
  value: "#rstring",
  offset: {
    x: "#float",
    y: "#float",
    z: "#float",
  }
}
				
			

type can be set to "lid" or "cat". If it’s set to lid, then value is interpreted as a labware ID. If it’s set to cat, then value is interpreted as a labware category. Each labware has a unique labware ID (lid) and can belong to zero or more categories (e.g., sbs, plate, magnet). offset defines how the well locations of the labware are affected. A well’s new z offset is calculated by adding the height of the bottom labware to the height of the top labware and then adding offset.z. offset.x and offset.y are used to adjust the blueprint.grids[].offset values. x and y offsets are unusual but come into play when, for example, a non-SBS to SBS adapter shifts the plate to the side causing an x/y offset to its wells.

If a labware defines "lid" and "cat" composition rules and another labware matches both rules (e.g. it’s in the right category and matches the labware ID), then the "lid" rule is given preference because it’s more specific. A "lid" composition rule can be used to override a more generic "cat" composition rule for a specific piece of labware.

GLS Accessibility Constraints

The glsConstraints property is proprietary to the LabMate liquid handler. It defines which pipettes can reach which wells depending on where the labware is placed on the deck. For example, it’s not possible to reach well H1 on a 96 well plate with the first (top) channel when the labware is placed on the bottom most row of the liquid handler. These rules are used by the LabSync algorithm to optimize deck layout so that each of the accessed labware well can be reached by the desired pipette.

Eventually these rules may be removed from the LabOS labware model and instead be stored in the LabMate’s instrument definition. For the time being use the following pre-defined rules. The rules depend on the number of rows of the labware.

2 Row Labware

Labware with 2 rows such as a 2×3 tube rack for 50 mL tubes.

				
					[
  {
    position: 1,
    constraints: [
      { type: "min", pipette: 1, position: 1 },
      { type: "min", pipette: 2, position: 2 },
      { type: "max", pipette: 3, position: 0 },
      { type: "max", pipette: 4, position: 0 },
      { type: "max", pipette: 5, position: 0 },
      { type: "max", pipette: 6, position: 0 },
      { type: "max", pipette: 7, position: 0 },
      { type: "max", pipette: 8, position: 0 },
    ],
  },
  {
    position: -2,
    constraints: [
      { type: "max", pipette: 1, position: 0 },
      { type: "max", pipette: 2, position: 0 },
      { type: "max", pipette: 3, position: 2 },
      { type: "max", pipette: 4, position: 2 },
      { type: "max", pipette: 5, position: 2 },
      { type: "max", pipette: 6, position: 2 },
      { type: "max", pipette: 7, position: 2 },
      { type: "max", pipette: 8, position: 2 },
    ],
  },
  {
    position: -1,
    constraints: [
      { type: "max", pipette: 1, position: 0 },
      { type: "max", pipette: 2, position: 0 },
      { type: "max", pipette: 3, position: 0 },
      { type: "max", pipette: 4, position: 0 },
      { type: "max", pipette: 5, position: 0 },
      { type: "max", pipette: 6, position: 0 },
      { type: "max", pipette: 7, position: 1 },
      { type: "max", pipette: 8, position: 2 },
    ],
  },
]
				
			

3 Row Labware

Labware with 3 rows such as a 3×5 tube rack.

				
					[
  {
    position: 1,
    constraints: [
      { type: "min", pipette: 1, position: 1 },
      { type: "min", pipette: 2, position: 2 },
      { type: "min", pipette: 3, position: 3 },
      { type: "max", pipette: 4, position: 0 },
      { type: "max", pipette: 5, position: 0 },
      { type: "max", pipette: 6, position: 0 },
      { type: "max", pipette: 7, position: 0 },
      { type: "max", pipette: 8, position: 0 },
    ],
  },
  {
    position: -2,
    constraints: [
      { type: "max", pipette: 1, position: 0 },
      { type: "max", pipette: 2, position: 1 },
      { type: "max", pipette: 3, position: 2 },
      { type: "max", pipette: 4, position: 3 },
      { type: "max", pipette: 5, position: 3 },
      { type: "max", pipette: 6, position: 3 },
      { type: "max", pipette: 7, position: 3 },
      { type: "max", pipette: 8, position: 3 },
    ],
  },
  {
    position: -1,
    constraints: [
      { type: "max", pipette: 1, position: 0 },
      { type: "max", pipette: 2, position: 0 },
      { type: "max", pipette: 3, position: 0 },
      { type: "max", pipette: 4, position: 0 },
      { type: "max", pipette: 5, position: 0 },
      { type: "max", pipette: 6, position: 1 },
      { type: "max", pipette: 7, position: 2 },
      { type: "max", pipette: 8, position: 3 },
    ],
  },
]
				
			

4 Row Labware

Labware with 4 rows, such as a 4×6 plate

				
					[
  {
    position: -1,
    constraints: [
      { type: "max", pipette: 1, position: 0 },
      { type: "max", pipette: 2, position: 0 },
      { type: "max", pipette: 3, position: 0 },
      { type: "max", pipette: 4, position: 0 },
      { type: "max", pipette: 5, position: 1 },
      { type: "max", pipette: 6, position: 2 },
      { type: "max", pipette: 7, position: 3 },
      { type: "max", pipette: 8, position: 4 },
    ],
  },
]
				
			

8 Row Labware

Labware with 8 rows, such as 96-well plates.

				
					[
  {
    position: 1,
    constraints: [
      { type: "min", pipette: 1, position: 1 },
      { type: "min", pipette: 2, position: 2 },
      { type: "min", pipette: 3, position: 3 },
      { type: "min", pipette: 4, position: 4 },
      { type: "min", pipette: 5, position: 5 },
      { type: "min", pipette: 6, position: 6 },
      { type: "min", pipette: 7, position: 7 },
      { type: "min", pipette: 8, position: 8 },
    ],
  },
  {
    position: -1,
    constraints: [
      { type: "max", pipette: 1, position: 1 },
      { type: "max", pipette: 2, position: 2 },
      { type: "max", pipette: 3, position: 3 },
      { type: "max", pipette: 4, position: 4 },
      { type: "max", pipette: 5, position: 5 },
      { type: "max", pipette: 6, position: 6 },
      { type: "max", pipette: 7, position: 7 },
      { type: "max", pipette: 8, position: 8 },
    ],
  },
]
				
			

16 Row Labware

Labware with 16 rows such as 384-well plates.

				
					[
  {
    position: 1,
    constraints: [
      { type: "min", pipette: 1, position: 1 },
      { type: "min", pipette: 2, position: 3 },
      { type: "min", pipette: 3, position: 5 },
      { type: "min", pipette: 4, position: 7 },
      { type: "min", pipette: 5, position: 9 },
      { type: "min", pipette: 6, position: 11 },
      { type: "min", pipette: 7, position: 13 },
      { type: "min", pipette: 8, position: 15 },
    ],
  },
  {
    position: -1,
    constraints: [
      { type: "max", pipette: 1, position: 2 },
      { type: "max", pipette: 2, position: 4 },
      { type: "max", pipette: 3, position: 6 },
      { type: "max", pipette: 4, position: 8 },
      { type: "max", pipette: 5, position: 10 },
      { type: "max", pipette: 6, position: 12 },
      { type: "max", pipette: 7, position: 14 },
      { type: "max", pipette: 8, position: 16 },
    ],
  },
]
				
			

Book a Demo

Genie is now in limited Beta. Complete the form below and one of our sales representitives will reach out to you within 24 hours to setup an in-person demo of our platform.