Tutorial: Running a Simulation

In this tutorial, you will learn how to run a simulation on the Labs Platform.

In this tutorial, you will learn how to run a simulation on the Labs Platform.  The Labs Platform allows you to run a cadCAD model on a cloud cluster, allowing for greater speed and computational power for your experiments.  Also, since it is run in a collaborative environment, the experiment only needs to be run once and then anyone who is a collaborator on the project can download and analyze the results.

Simulations Tab

The ‘Simulations’ tab is where you can track all the simulations that have been run within the project and also execute new simulations.

Run Simulation

When you click the ‘Run Simulation’ hyperlink, you will be navigated to a series of screens where you can set up your simulation.  This allows you to run a cadCAD simulation within a repository that also contains a Labs.py file.

Simulation Setup: 01 General Info

The first step to executing a simulation is to name your simulation.

Once you’ve entered a name for your simulation, the ‘Next’ button will change from gray to orange.

The ‘Select a Branch’ dropdown will default to whichever branch you selected in the Project Settings screen.  Optionally, you can change the branch from which you want to run the simulation (if you project has multiple branches).  

If at any point during the simulation setup process you want to cancel and leave the screens, you can click on the upper right ‘X’ to close out the screens and return to your project screen.

Simulation Setup: 02 System Models

The second step to the ‘Simulation Setup’ process is to select your system models.  This allows you to choose which model you want to run for the simulation.

In this example, my model has two system configurations.  I can click on one or both to run them for this simulation.  Once I’ve selected at least one system model, the ‘Next’ button will switch from gray to orange.

If I want to go back and rename this simulation, I can click on the back button to go back to the previous screen.

Also, the ‘Select System Models’ screen has a search bar where you can begin typing the name of the system model you are looking for to filter down the list of system models.  This search bar is not case sensitive.

No System Models Present

If your code encounters an error then instead of seeing a selectable system model on your screen in the second step of the ‘Simulation Setup’ process, you will instead get a warning message asking you to update your Labs.py file.  This error can occur due to three main factors:

  1. You do not have a Labs.py file within your repository.
  2. You are trying to run an ipynb file instead of a .py file.  The platform only supports running .py files at this time.
  3. Your cadCAD code isn’t set up properly for the platform to recognize your system model.

If the issue is isolated to your Labs.py file, then you will be able to fix it within the UI.  Otherwise, you will need to exit the ‘Simulation Setup’ process and resolve the issue.

This warning screen has the following parts:

Why is this important?

There is a tool tip in the sentence ‘Why is this important?’  This will give a brief explanation as to why you need a Labs.py file in your project and will also have a link to a document with simple instructions to convert your project to be Labs Platform ready.

Labs.py Text Box

The Labs.py text box will display the content of your Labs.py file (if one exists).  This will allow you to make edits to the code.

Commit Message

This is where you can either choose to use the default commit message or you can change it to your liking.  If you commit the change, there will be an update to GitHub of your changes with the commit message of your choosing in this text box.

Continue W/O Commit

If you make any edits to your Labs.py file within the text box, the ‘Continue W/O Commit’ option will become available.  This will allow you to move forward with running the simulation without making a change to your GitHub repository.  If you try to run the simulation without making any changes to your GitHub code, then you will run into the warning screen again.

After you click this button, if your code is now runnable, you will get a notification letting you know that the update was successful and you will be able to select your system model.

Commit and Continue

If you make any edits to your Labs.py file within the text box, the ‘Commit and Continue’ option will become available.  This will allow you to move forward with running the simulation and will also commit your changes to your GitHub repository.

After you click this button, if your code is now runnable, you will get a notification letting you know that the update was successful and you will be able to select your system model.

Simulation Setup: 03 Time & Cost

The final step of the ‘Simulation Setup’ process is to inform you of how much it is estimated to cost to run your simulation and how long it is estimated to take.  Your simulation will run on Amazon Web Services and there will be a cost associated with executing your code.


After you click ‘Execute’, you will be taken back to the ‘Simulations’ tab and a new row will be added for the simulation you just executed.

A simulation has the following columns:

Simulation: Displays the name that you gave the simulation.

Run By: The Labs user who executed the simulation.

Run Date: The date and time that the simulation was executed.

Run Time: The length of time that the simulation ran for.

Simulation Status: The current status of the simulation execution.  It will have the following statuses: ‘Created’, ‘Error’, ‘In Progress’ and ‘Finished’.  Once the simulation is complete, you can download the results.

Download Results

After a simulation is completed, you will be able to download the results.  To do so, click on the ‘Download Result’ hyperlink underneath the green status bar.

By clicking the link, your browser will automatically download a .csv file to wherever your default download folder is for your machine.


NOTE: The data within the file is serialized using Pickle.  You will need to unserialize the data before you can run your analysis.

Delete Simulation

The trashcan icon on the right side of the simulation details will allow you to remove the simulation from the platform.

When you click on the trashcan, a pop up box will appear for you to confirm the deletion.

Like What You See?

You can help fund BlockScience Labs and own a piece of its success! Check out our investment site to learn more at https://invest.blocksciencelabs.com/.