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.

 

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! 

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.
This will either print out Simulation successful! or an error message showing any problems in the protocol.

Some messages are OK to ignore. Messages about files not being found are all ignorable.

You can also run this command from a jupyter notebook:

!opentrons_simulate my_protocol.py

Finally, for now you can simply execute your protocols directly by executing their cell in jupyter or running the Python files.

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.

Did this answer your question?