Simulations and Error Reporting
This tutorial is for all users of Antha to get a better understanding of why we simulate our workflows, the errors that you may come across and potential solutions to these errors.
About this tutorial
In this tutorial you will learn the basics of what a simulation is for, what it is doing and how to debug any errors due to a failed simulation.
Things you'll need
Before you get started you will need an Antha license so that you have access to Antha OS.
What you'll learn
In this tutorial you will learn:
- What a simulation is for and what it is doing
Different types of errors
Element specific errors
System specific errors
How to debug these errors
Why run a Simulation?
Before you can run any workflow on an automation device you first must run an in silico simulation of your chosen parameter values against your chosen elements in your workflow all of which are simulated against your chosen automation device to validate that your workflow can be implemented.
The first two steps of the simulation (parsing parameters and creating a job) are creating a specific instance of your workflow by matching your specified parameter values to your elements and creating a preliminary job for simulation. Throughout this process, the system will run validation checks to ensure that the user specified parameters match their types for the element inputs within the workflow. (e.g. an integer to an integer and not an integer to a string)
Note that when simulating through the workflow editor, a lot of these type mismatches will be caught in the Parameters tab in the sidebar before simulating so that these errors are caught early. However, there are instances of special cases where these may pass this initial filter.
The third stage is to simulate the preliminary job. This entails running the chosen parameter values through their respective elements to be sure that there are no element specific errors. For example if a volume cannot exceed 10ul specified within the element code but the user has set a value of >10ul, the system will throw an error. At this stage there will be a check to make sure that no parameters exceed possible device or plate specific values. For example 100ul volumes would not be compatible with certain plates or devices. The preliminary job is also passed through several stages of the planner to check for system specific conflicts. The several stages are as follows:
- Define the order of execution
- Convert everything to volumes
- Determine what inputs are missing, at what volumes
- Assign new inputs to plates
- Map outputs to destinations
- Define layout of liquid handler
- Make instructions
- Revise input and tip setups
A failure at any one of these stages will result in a failed simulation.
When and where might a simulation take place
A simulation must take place before any physical experiment can be run. This simulation process may happen at one of four places:
- When running a workflow from a Protocol Card
- When running a workflow from the Workflow Editor
- When selecting a new device from the Dashboard
- When changing the plate layout in Plate Prep
At each one of these stages a simulation (or in the case of changes made from Dashboard or Plate Prep a re-simulation) will be run.
Only if the simulation is a success will a job be created and saved to the Job Queue.
Note that when a simulation runs from a Protocol Card workflow that there are an additional three steps at the beginning of the standard simulation that validates the contents and structure of your uploaded design file.
There are a number of different errors that could occur when you simulate a workflow. These can be split into two broad categories of element specific or system specific.
Element specific errors
Element specific errors are generated when criteria for parameter values stipulated within the code of the element is not met. When this happens the element will return a specified error message.
For example if an element takes two parameter values and performs some calculations on them to determine if there is enough of a solution for the element to run but there isn't, then an error message will be displayed that will let the user know that there isn't enough solution.
These errors are specific to the element that is being run and often will direct you to the problem parameter. Therefore, the error can be rectified by returning to the parameters and correcting values such that you fall within the allowed range for that element.
System Specific errors
System specific errors are generally caused by a conflict during the planning process. These errors can also be considered as workflow specific, as not all workflows can be run on all liquid handling platforms. The general constraint here is due to the number of deck positions on your particular device.
Ran out of Tips
You may find that with some workflows that there may not be enough deck positions available for the number of tips that are required for the physical implementation of that workflow.
This isn't necessarily due to the complexity of the workflow you are trying to run as this error may still be encountered with simple workflows containing a single element.
If you do encounter this problem you will be notified by a "ran out of tips" error.
In some instances this problem can be resolved and the workflow can still be run. Either a modification to the workflow such that plate usage is more efficient to free up deck positions for more tips or to split your workflow into two separate runs. Alternatively some automation devices (Gilson pipetmaX for example) have the ability to allow you to replace tips throughout a run of your experiment such that no more than two deck spaces are ever taken up by tips.
In order to achieve this you would need to edit the Preferences section in the Configuration tab of the workflow editor. For more information about the preferences section take a look at the Workflow Editor documentation
Not enough deck space
Running out of deck space is again an automation device specific error. This is generally linked to more complex workflows that require many different plates or specific risers, e.g. cooling blocks, incubating platforms etc.
This problem can then be confounded by the requirement for lots of tips to implement the workflow and therefore using up more deck space.
If there is a deck space error you will be notified when you simulate that there "is not enough deck space".
A couple of ways to avoid/fix this error is to simplify your workflow such that different elements are run in separate workflows freeing up deck space or optimising plate usage efficiency by altering sample layout on plates.
Auto allocation of samples onto plates is very safe but wastes a lot of plate space in the process. If you have a lot of samples for your workflow then specifying in a plate layout file your samples to all be allocated to a single plate can often save a lot of space.
In some instances you may see a large error stack. In these instances it wont be clear to you what has necessarily gone wrong or how to fix this error. In these rare instances we would advise you to contact us via Intercom for a rapid response and suggested fix if possible.