The Opentrons App and the OT-2 work together to simulate your protocols when you upload them, and show you errors right in the app. However, you may be interested in simulating protocols on your computer, without having to be connected to a robot at all. This article describes how.

Please note that whenever Opentrons releases a new version of its robot software and desktop app, we also release a new version of the protocol simulator. This document is always updated to describe the latest version. For instructions on how to update the simulator, please see the Updating the Opentrons Module section below.

Installing Python

The first step is to install Python 3.6.1 or higher on your computer. 

Checking if Python Is Already Installed

You may already have Python installed, either directly or because you're using Anaconda or another scientific Python distribution. These will work fine, as long as they are version 3.6.1 or higher. You can check if python is installed by opening a command prompt and typing python

If Python is installed, you can check its version from your Python prompt:

>>> import sys
>>> sys.version
'3.6.4 (default, Aug 14 2018, 10:16:24) \n[GCC 4.2.1 Compatible Apple LLVM 9.1.0 (clang-902.0.39.2)]'

Or from your Jupyter notebook:

Your system may print out something different in the parentheses, but as long as the first trio of numbers is 3.6.1 or higher you're good to go. If you don't have Python installed, or if that trio of numbers is lower, including if it is 2.7, you must install Python 3.6.1 or higher.

Installing

If you do need to install Python, you can download Anaconda, a Python distribution aimed at scientists that has sophisticated editors like Jupyter. It is available for Windows, Mac, and Linux. To start with Jupyter and Anaconda, follow the Jupyter setup instructions. You must download and install the Python 3.7 version of Anaconda, not the Python 2.7 version.

If you don't want to install Anaconda and Jupyter, you can install Python standalone for Windows, Mac, or Linux from www.python.org . Installing Python from these links will give you the language and its shell, but nothing else. 

Regardless of how you decided to install Python, you may want to also download a text editor to write your protocols in, like Sublime Text or Atom.

If you are on Windows and installing Python standalone from python.org, please make sure you select the option in the installer that says "Add Python 3.7 to PATH" (if you're installing Anaconda, you don't have to do this):

Installing the Opentrons Python Module 

Now that Python is installed, you can install our Python module. To do this, you'll use Python's built in package manager, pip .

To install the Opentrons python module,

If you installed Anaconda:
 Open a Python Jupyter notebook and do

In [1]: import sys
        !{sys.executable} -m pip install opentrons

This will take a long time since Jupyter won't show you any of the output until the command is complete. Don't worry, it's working.

If you installed Python on its own
without Jupyter or Anaconda:
Open a command prompt and do

pip install opentrons

In either case, you'll see a string of output that looks something like this:

 Collecting opentrons
  Downloading https://files.pythonhosted.org/packages/f9/85/b4bc34903c2f4dac782d11000d352c82fd3893616871adab22060dff665a/opentrons-2.5.2-py2.py3-none-any.whl (110kB)
    100% |████████████████████████████████| 112kB 3.1MB/s
Collecting requests==2.14.2 (from opentrons)
  Downloading https://files.pythonhosted.org/packages/e4/b0/286e8a936158e5cc5791d5fa3bc4b1d5a7e1ff4e5b3f3766b63d8e97708a/requests-2.14.2-py2.py3-none-any.whl (560kB)
    100% |████████████████████████████████| 563kB 5.8MB/s
Collecting dill==0.2.5 (from opentrons)
  Downloading https://files.pythonhosted.org/packages/47/59/a72f5c3b17647031d426cd3df6874c7e2a8821b007ef4241ee4a59594cb3/dill-0.2.5.tgz (60kB)
    100% |████████████████████████████████| 61kB 11.6MB/s
Requirement already satisfied: pyserial==3.2.1 in ./lib/python3.6/site-packages (from opentrons) (3.2.1)
Building wheels for collected packages: dill
  Building wheel for dill (setup.py) ... done
  Stored in directory: /Users/seth/Library/Caches/pip/wheels/d0/f9/bb/01e2c9bc71ab75df06848f7eb23aa58b0e24713332aee81aa2
Successfully built dill
Installing collected packages: requests, dill, opentrons
Successfully installed dill-0.2.5 opentrons-2.5.2 requests-2.14.2

The specific versions in there will change with releases, but the important thing is that last line: Successfully installed... opentrons... . When you see that, you're ready to go! 

Updating the Opentrons Python Module 

Whenever Opentrons releases a new robot software or desktop application version, we also release a new version of the opentrons module and thus a new version of the simulator. To update to the new version, 

If you installed Anaconda: In your Jupyter notebook, do 

In [1]: import sys
        !{sys.executable} -m pip install --upgrade opentrons

Like when you first installed the module, this will take a long time with no output.
If you installed Python directly: In your terminal, run pip install --upgrade opentrons .

Simulating Protocols 

Once you have the Opentrons python module installed, you're ready to simulate protocols.

First, make sure your protocol is saved to a file (as opposed to a cell in a Jupyter notebook). Then, open a command line, and do

opentrons_simulate my_protocol.py

where my_protocol.py  is replaced with the path to your protocol file.

You can also run this command from a jupyter notebook:

!opentrons_simulate my_protocol.py

When you use the opentrons_simulate  script, it prints out what the protocol will do - the equivalent of the log you see in the Opentrons App. The log prints the action the robot will take (for instance, aspirate , dispense , or transfer ) and any actions that are part of those commands (for instance, a mix causes the robot to do multiple aspirate  and dispense actions, one pair for each mix ). The log also includes the location in which these actions will occur, and other parameters - for instance, the volume the robot will aspirate. In addition, the log will contain any warning messages that the robot might print - for instance, messages about doing a pick_up_tip  multiple times without a drop_tip  in between.

This is an example of a run log from the Opentrons logo demo protocol (the first line is the command used to run the simulation):

$ opentrons_simulate Opentrons_Logo.ot2.py
Distributing 50 from well A2 in "2" to wells A5...H9 in "3"
Transferring 50 from well A2 in "2" to wells A5...H9 in "3"
Picking up tip well A1 in "1"
Aspirating 280.0 uL from well A2 in "2" at 1 speed
Dispensing 50.0 uL into well A5 in "3"
Dispensing 50.0 uL into well A6 in "3"
Dispensing 50.0 uL into well A8 in "3"
Dispensing 50.0 uL into well A9 in "3"
Dispensing 50.0 uL into well B4 in "3"
Blowing out at well A1 in "12"
Aspirating 280.0 uL from well A2 in "2" at 1 speed
Dispensing 50.0 uL into well B10 in "3"
Dispensing 50.0 uL into well C3 in "3"
Dispensing 50.0 uL into well C11 in "3"
Dispensing 50.0 uL into well D3 in "3"
Dispensing 50.0 uL into well D11 in "3"
Blowing out at well A1 in "12"
Aspirating 280.0 uL from well A2 in "2" at 1 speed
Dispensing 50.0 uL into well E3 in "3"
Dispensing 50.0 uL into well E11 in "3"
Dispensing 50.0 uL into well F3 in "3"
Dispensing 50.0 uL into well F11 in "3"
Dispensing 50.0 uL into well G4 in "3"
Blowing out at well A1 in "12"
Aspirating 280.0 uL from well A2 in "2" at 1 speed
Dispensing 50.0 uL into well G10 in "3"
Dispensing 50.0 uL into well H5 in "3"
Dispensing 50.0 uL into well H6 in "3"
Dispensing 50.0 uL into well H7 in "3"
Dispensing 50.0 uL into well H8 in "3"
Blowing out at well A1 in "12"
Aspirating 50.0 uL from well A2 in "2" at 1 speed
Dispensing 50.0 uL into well H9 in "3"
Dropping tip well A1 in "12"
Distributing 50 from well A1 in "2" to wells C7...G8 in "3"
Transferring 50 from well A1 in "2" to wells C7...G8 in "3"
Picking up tip well B1 in "1"
Aspirating 280.0 uL from well A1 in "2" at 1 speed
Dispensing 50.0 uL into well C7 in "3"
Dispensing 50.0 uL into well D6 in "3"
Dispensing 50.0 uL into well D7 in "3"
Dispensing 50.0 uL into well D8 in "3"
Dispensing 50.0 uL into well E5 in "3"
Blowing out at well A1 in "12"
Aspirating 280.0 uL from well A1 in "2" at 1 speed
Dispensing 50.0 uL into well E6 in "3"
Dispensing 50.0 uL into well E7 in "3"
Dispensing 50.0 uL into well E8 in "3"
Dispensing 50.0 uL into well E9 in "3"
Dispensing 50.0 uL into well F5 in "3"
Blowing out at well A1 in "12"
Aspirating 280.0 uL from well A1 in "2" at 1 speed
Dispensing 50.0 uL into well F6 in "3"
Dispensing 50.0 uL into well F7 in "3"
Dispensing 50.0 uL into well F8 in "3"
Dispensing 50.0 uL into well F9 in "3"
Dispensing 50.0 uL into well G6 in "3"
Blowing out at well A1 in "12"
Aspirating 130.0 uL from well A1 in "2" at 1 speed
Dispensing 50.0 uL into well G7 in "3"
Dispensing 50.0 uL into well G8 in "3"
Blowing out at well A1 in "12"
Dropping tip well A1 in "12"

Frequently Asked Questions


Issue: When I run a simulation, I get an error like this:

TypeError: __new__() missing 3 required positional arguments: 'repetitions', 'volume', and 'rate'

Solution: This error is caused by having a version of python below 3.6.1 (usually 3.6.0). Please update to the latest 3.6 or 3.7 version of python. 

Issue: The behavior I see from the opentrons_simulate  script doesn't match the behavior documented here. For instance, I don't see a run log, only Simulation successful!

Solution: Update your opentrons module to the latest version (see the Updating the Opentrons Python Module section above)

Did this answer your question?