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 want to simulate 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. Updating the app on your computer does not update the simulator. For instructions on how to update the simulator, please see the Updating the Opentrons Module section below.

Get Ready: Install Python and the Opentrons Module

The first step is to install Python 3.7 or higher on your computer. 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.7 or higher.

Note: If Python is already installed, depending on how it is configured on your computer, you may need to slightly modify the commands below, e.g. using pip3 in place of pip.

Installing Python

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 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 run:

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 run:

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 version numbers you'll see will change, 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, run:

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 in the Terminal

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

If your protocol is saved to a file (as opposed to a cell in a Jupyter notebook), Open a command line, and run:

opentrons_simulate my_protocol.py

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

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.

Simulating Protocols in Jupyter


If you're using Jupyter, and want to see the run log printed in a cell, the process will be slightly different. First, make sure your code is structured as for running with Jupyter described in the API documentation. Then you should be able to add:

for line in protocol.commands(): 
print(line)

to the end of the cell in order to print the run log as seen below:

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.7 (usually 3.6.0). Please update to the latest 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?