Information and Login

To create an account, start by navigating to https://live.openlab.app/ where you should see a form similair to the one below.

To create a free trial account, simply click one of the two social login buttons and you will be redirected to login to your respective Google or Microsoft account. Once authenticated by Google/Microsoft, your OpenLab account will automatically be created and associated with the account name you just logged in with. You will then be redirected back to OpenLab and ready to simulate the drilling process!

If at any time you would like to unlock the full features, extend your simulation limitations, or take a tour of our Control Room, contact us! Or for more info about our plans, check out https://openlab.app/pricing/.

Configuration

Before you can run a simulation, you must first create a well configuration. This video and accompanying tutorial teaches you how to create a configuration from one of several templates we have created.

From the homepage, either click the new configuration button (1), or if you have no configurations yet, the New configuration text (2).

New Configuration Inputs

1) Name your configuration anything you want, as long as a configuration with that name does not already exist. We will call this simulation My Configuration

2) Select which type of rig best describes the well configuration you want to drill with. The main options are:

* Offshore

* Onshore

We will select Offshore

Well Templates

To make things easier to get started, we have created several templates to choose from as a starting guide. The 3 main templates are:

1) Vertical 2) Inclined 3) Horizontal

As you can see, these templates main differences are the well geometry, which plays a pivotal role in the drilling process.

1) Select the template that best initially describes our well, which in this case is Inclined 2500 for us.

2) Finally, we select or make a folder to place this configuration in if you would like, e.g. Tutorials.

Configuration Editing

To see how to edit a configuration, and some tips/tricks to using our configuration editors, see our main tutorials page, and select and filter by Configuration

Editing an existing configuration can be done from any of the edit pages (editors) in your configuration:

When editing a configuration, a set of validation rules will automatically be applied to secure that the configuration is still valid for the computer model to initialize and run. If one or several of the input parameters are outside the acceptable range, you will be given a warning along with a message. The message will guide you to the locations where the input parameters need to be corrected. If you want to go back to the last valid version, you can reload the page (press F5 on the keyboard or reload page on tablets), or click the “Reset all” button in the error message:

Be aware that if your configuration has already been used to create a simulation, any changes to the configuration will create a new version. Previous configurations along with corresponding simulations are stored and can be viewed in the Configuration sidebar, located as a pop-up menu on the right side of the edit pages.

Hole Section

In the Hole Section editor, you can edit lengths and diameters of the riser, casings, liners and open hole section. Just click on any element on the figure, and you will see the table in which you can edit. It is not possible to import any data for this editor, so you must edit manually. In this editor you can easily get validation errors. If you edit e.g. an inner diameter (ID) that does not allow any other casings to be run inside, you will be given a warning. You will be given warnings that are related to this editor, or it can be from other editors in the configuration that are affected. We hope that the error messages guide you to the right place for correcting errors in your configuration.

Wellpath

The front page of the Wellpath editor shows the trajectory of your well. The plot can be zoomed in/out with the mouse wheel scroll, rotated with left mouse click movements, and moved with right mouse click movements. The different colors on the trajectory refer to the dog leg severity (DLS). To edit the wellpath, push the Edit button:

For the Wellpath editor you have the possibility to import the survey points from a CSV file (see Chapter 6). You can edit manually as well, but beware that there are limitations on the dog leg severity (you will get an error message if the DLS is too high). Usually there are many survey stations, so the table is collapsed by default. To see all the stations, click the expand arrow, , in the middle of the table.

Fluid

In the Fluid editor, you can edit two fluids, Fluid 1 and Fluid 2, by pressing the Edit button. Both fluids are based on templates which can be modified to your choice of mud. The density of the mud can also be changed during simulations, but the value you enter in the Fluid editor is your default value.

Drillstring

The drillstring, bottom hole assembly (BHA) and bit can be edited by clicking on each row. The BHA elements can be selected from a drop-down menu by clicking the + sign. Some elements in the BHA and drillstring also have some additional parameters that can be found by expanding the drop-down arrow in the lower right corner of its respective table row. This editor is also likely to give you  8 validation messages when you start editing. Hopefully the messages will guide you to the right locations to change your configuration into a valid configuration.

If you want to add along string measurement nodes to the drill string, you can enter the + button and choose ASM among the components. On the simulation graphs you will then be able to read the simulated pressure value from this sensor.

Geology

The geology editor contains three sub editors:

Geopressure

The geopressure profiles define the pore pressure and fracture pressure at any depth along the wellbore. You can list these profiles as functions of the True Vertical Depth (TVD) or as functions of the actual well-path Measured Depth (MD).

Geothermal

To edit the geopressure profile, click the Edit button. The profiles can be edited manually or by importing from a CSV file (see Chapter 6). Beware that when creating a new simulation, you are asked if you want to use the geopressure profiles as limits for the kick and loss simulations.

The geothermal profile is given as temperature gradient as a function of depth. This profile is used in the dynamic temperature calculations and to model e.g. the rheology and density of the drilling fluid at any depth of the well. To edit the geothermal gradient values, click on the Edit button. The profiles can be edited manually or by importing from a CSV file (see Chapter 6).

Formation

The formation strength is used in calculation of weight on bit (WOB) for a given rate of penetration (ROP). Formation strength is given by the unconfined compressive strength (UCS) as a function of depth. If no UCS values are entered, a default value of 100 is chosen in the simulation.

Rig

The Rig editor is where you can change input parameters for the different equipment that are affecting the fluid flow and drill string dynamics. When you hover over the figure, you can see which components are editable. Click on one of them (or click the Edit button) to open the input table to make any changes. Note that entering the traveling block weight is optional.

Versioning

Simulation

Interactive

This tutorial teaches you how to run a simulation interactively and what must be done in order to drill.

Create a New Simulation

A new simulation can be created from the configuration view or from the simulations view by pushing the “New Simulation” button.

When creating a new simulation, you need to specify the name of your simulation and/or any advanced settings you would like. These advanced settings initialization parameters include the initial bit depth of your simulation, the initial top of string position, the auto connection time, and whether you want to be able to simulate influx/losses or not. If you choose “Based on geopressure”, the geopressure curves will define your boundaries for influx and losses.

When creating a simulation, the computer model is first initialized and then (after a few seconds) ready to calculate the dynamic state of the well based on your choice of drilling parameters (setpoints).

Drilling Parameters (Setpoints)

In the current version you can control the following parameters:

  • Main pump flow rate
  • Hook speed
  • ROP
  • Surface RPM
  • MPD Choke Opening
  • MPD pump flow rate
  • Density at inlet
  • Pumped fluid
  • BOP Choke Opening

These drilling parameters are setpoints, which means that they represent the desired or target value for the respective simulated process value. Both in OpenLab and in real life, there is a time-delay before the difference between the setpoint and process value is minimized, which is dependent on the characteristics of the component. To adjust the characteristics of a component, please see the Rig configuration editor.

Beware that the density of the fluid into the well (Density in) is typically not a drilling parameter which is possible to change “on the fly” in a real drilling operation. With today’s equipment, you need to change the density by adjusting the content of weight material in the drilling fluid on the rig, which takes some time. However, in OpenLab we allow the users to change inlet density on the fly because it allows use of this parameter as a manipulated variable in process control simulations. The density given in the Fluid editor will still be your default density for this particular fluid, and the fluid that remains in the pit tank will have the default density. When you start a simulation, your well will always be filled with the fluid named as Fluid 1 in your Fluid editor. The “Density in” only allows you to change the density of the fluid that is being pumped into the well.

Manual Mode

In Manual mode you are free to change any of the setpoints during the simulation. In the current version of the simulator, we have set the length of a simulation step to one second. If you chose to run a simulation in “real time”,  the simulation performs one step per second. You can also run the simulator faster than real time, in the fast-forward mode. In fast forward, the speed of the simulation will depend on your computer device, internet connection, and number of simulation graphs.

A typical simulation speed is around 10x, which means 10 times faster than real time. In Manual mode each drilling parameter can be changed at any time, but be aware that in fast forward there might be some time-delay from when you enter a value until it is used in the simulations, since the simulator is running a few steps ahead of what is visible to you in the browser. If you want to simulate only one step ahead, you can do so by pushing the “Run a single step” button . When pausing a simulation, the simulation is temporarily put on hold and can be resumed at any time. If you do not resume a simulation within a certain time, or if you log out, the simulation is automatically stopped and completed by the system. This is to avoid too many ongoing simulations in the OpenLab system. If you push “Stop and complete a simulation”, the simulation is saved and cannot be resumed. After a simulation has been completed, you can export the setpoints by clicking the “View setpoints” and then Export.

If you want to run through a pre-defined set of drilling parameters, you may use the Sequence mode. This will also result in a higher simulation speed.

Start Drilling

In order to drill and advance the open hole, there are several parameters that must be set. These are:

  • Flow Rate
  • Hook speed (positive is downward)
  • Desired ROP (how fast you wish to drill)
  • Surface RPM

Once you click play and these parameters are set, you will begin to drill after touching bottom.

Sequence

OpenLab supports two main type of running a simulation. Interactively or by uploading pre-defined setpoints set for certain times, known in OpenLab as a sequence.

There are two ways to make a sequence: Using our table editor, or importing a .csv file. This tutorial teaches you the former.

Stay tuned to the blog for news about our new sequence simulations!!

Auto Connection

Import and Export

General

Export data from OpenLab

  1. Find the data you want to export and click Export.

Load data into Excel

  1. In the menu, click Data.
  2. Choose From Text.
  3. Find and select the file you just exported.
  1. Make sure Original data type is set to Delimited (default).
  2. Start import at row should be set to 1 (default) and File origin should be UTF-8.
  3. Tick the My data has headers checkbox.
  4. Click Next.
  1. Make sure Delimiters is set to Semicolon.
  2. Click Next.
  1. Click the Advanced... button.
  1. Make sure Decimal separator is set to . (dot).
  2. Click OK.
  1. Click Finish.
  1. Click OK to place the data in the selected worksheet.

You should now see the imported data in the worksheet.

Load data into Excel (Alternative)

  1. In the menu, click Data.
  2. Choose From Text/CSV.
  3. Find and select the file you just exported.
  1. File origin should be UTF-8
  2. Delimiter should be Semicolon
  3. Click Edit
  1. Select all the columns by clicking each Column Header while holding down the Shift key.
  2. Select Use First Row as Headers

The following are for international users whose Excel uses a decimal seperator other than a decimal point.

  1. Click Replace Values to open up the Replace Values dialog box.
  2. Find all decimal points .
  3. Replace them with your program's decimal separator (in this case a comma ,)
  4. Click OK
  1. Change Data Type to Decimal Number
  2. Finally, click Close & Load

You should now see the imported data in the spreadsheet.

Save data from Excel

  1. In the menu, click File.
  2. Choose Options.
  3. Go to the Advanced tab.
  4. Verify that Decimal separator is . (dot). If not, uncheck Use system separators.
  5. Set Decimal separator to . (dot).
  6. Click OK.

You're now ready to save the CSV-file.

  1. Mark the file you want to save as.
  2. Make sure Save as type is set to CSV.
  3. Click Save.

Importing data back into OpenLab

  1. Navigate to the configuration screen where you want to import your data. Click Import.
  2. Select the file you saved with Excel.
  3. Click Open.

You should now see the updated data in the application. If there are errors in the data, you should see the errors highlighted, like this:

  1. The data with errors should be highlighted in red.
  2. In the top-right corner, you should see a description of the errors.

Configuration

Most of your well configuration data can be exported as a .csv file. This can be handy if you want to use your data elsewhere. This tutorial walks you through how to accomplish this.

Simulation

Currently, OpenLab supports two main type of running a simulation. Interactively or by uploading pre-defined setpoints set for certain times, known in OpenLab as a sequence.

There are two ways to make a sequence: Using our table editor, or importing a .csv file. This tutorial teaches you the latter.

Stay tuned to the blog for news about our new sequence simulations!!

Exporting simulation data can be done by exporting plot data individually.

If you are having problems with excel or importing/exporting in general, take a look at our thorough guide for help!

And for more efficient ways of accessing your simulation data, stay tuned for the upcoming series on our Python client!

Teams

Inviting Someone To A Team

Removing A Team Member

Switching Teams

Other Features

Share a Configuration and a Simulation

Change Units

MatLab and Python Interfaces

Matlab

Python

To install the OpenLab python client, ensure you have python >= 3.6, which comes packaged with the python package installer (pip). To check the version, open a command prompt and type your python environmental variable (in my case, it was customized to py) and followed by -V

Once you have verified your python version, simply run pip install openlab in the command prompt.

This will fetch the OpenLab package, and download all necessary python dependencies if they aren't installed yet.


Note: If you get a PermissionError like the following, try adding --user t0 the previous command to install the package without administrative rights.


Setup your OpenLab credentials

There are 3 ways to validate your OpenLab Credentials (in decreasing priority):

  1. Using the keyring library (Default)
  2. Storing  your credentials in openlab/account.py
  3. Passing keyword arguments into the http_client() initialization

All 3 of the above options require 2 mandatory and 1 optional parameter(s):

  • API Key
  • Username/E-mail
  • License ID (for multi-license holders)

Note: The optional license guuid is only relevant if running a simulation using python, as it is used for checking allotted simulation limits. If it is omitted, OpenLab will take a "best guess" approach as to which license to use.

To generate these values: 1.) Go to your User settings in the top right corner of https://live.openlab.app.  2.) Select which license you want to generate for (if multiple licenses)  3.) Click Generate Python login script.

A new API key will be generated, and a form should appear which will overwrite your old API key (if you had one). Copy this key and paste it in the correct place for the upcoming options.

Authentication

Option 1 - Keyring

Either create a new python script, or open a python shell (following method). The first time you initialize and run openlab.http_client(), you will be prompted to enter your credentials:

After you have entered this, the python client will securely store it in your system's password keychain, and you will not need to input these afterwards (unless your  api key expires or you generate a new one from the webpage).

Note: If you need to switch users or change api key, enter and run openlab.login.switch_user(new_username, new_api_key) from a python script/shell.

Option 2 - Store in file

You can paste the credentials taken earlier into a specific file in the same file directory as your OpenLab python library. This file is acount.py. You will see that the default values are all None. As long as these values are not None, they will take priority over the stored keyring credentials.

Option 3 - Pass in as arguments

Additionally, you can pass the values as keyword arguments when initializing the http client. Make sure to replace the break lines/return lines with commas. For example:

import openlab
session=openlab.http_client(username="openlab.test.user@gmail.com",apikey="66385C24228E02EE0ACBB82894C3F4B1E7CA12F32E3C1C08606682E1135B7111",licenseguid="d66f7084-e59c-4443-bd23-3d43a926fa6e")

This option takes first priority over the previous two options.


If you have any questions or problems authenticating the openlab python client, please don't hesitate to contact us!

Before you start

Make sure your python OpenLab client and credentials are up to date (see our tutorial on how to do this).

Create a new default well configuration in the web client and name it "Offshore Inclined".

Initialize and Authenticate Account

We use the default keyring method which uses our stored credentials (see our tutorial for instructions on this or the other methods if having problems).

import openlab
session = openlab.http_client()

You should see a print out confirming you have been authenticated.

Simulation Initialization

There are several mandatory and optional initialization parameters as listed below (subject to change):

Mandatory:

  • Configuration name (must be a pre-existing configuration created in the web client)
  • Simulation Name (Whatever you wish to call the simulation)
  • Initial Bit Depth (in meters)

Optional:

  • Influx Model
  • Timestep Interval (Default = 1)

We will only use the 3 mandatory parameters for now:

config_name = "Offshore Inclined"
sim_name = "Drill From Python"
initial_bit_depth = 2500

Now, we can initialize and create the simulation:

sim = session.create_simulation(config_name, sim_name, initial_bit_depth)

If you navigate to the web client, you should now see a simulation called "Drill From Python" has been created in the "Simulations" tab, and is awaiting setpoints.

In order to actually drill and advance the wellbore, we initialize with the following 4 setpoints (Make note that all numeric values must be sent in SI units) :

sim.setpoints.RPM = 0 #Hz
sim.setpoints.DesiredROP = 0.02 #m/s
sim.setpoints.TopOfStringVelocity = 0.02
sim.setpoints.FlowRateIn = 2500 / 60000 #60000 is to convert l/min to m^3/s

Advance/Run the Simulation

In order to advance and step the simulation, a setpoint must be sent to the OpenLab server with one mandatory setpoint -> timestep. We do this using a for loop:

simulation_time = 300 # seconds

for i in range(1, simulation_time + 1):
	sim.step(i)

You can watch and verify the simulation is running by clicking on the simulation in the web page.

Ending the Simulation

To end a simulation through the API, a new setpoint must be sent containing the value of ShouldComplete = True. This is done automatically for you in the python client by calling the Simulation class's stop() method:

sim.stop()

Note: When running a simulation script (i.e. not interactively in the shell), the default OpenLab session behaviour is to automatically end all initialized simulations. To toggle this feature, you can use the end_simulation_on_exiting flag of the openlab.Simulation class. Or in our case:

sim.end_simulation_on_exiting = True/False

Specific use case:

  • Double all the formation strength UCS

Recommended work flow:

  • Create a scratch configuration in the web client to use as a data template to edit.
  • Get the configuration data from this scratch configuration via our API. For this case, we will use python alongside the openlab module.
  • Programmatically edit/make the desired changes to this configuration data.
  • Push the edited data to the API

Walkthrough

For the final code, jump to the bottom section

Create a scratch configuration

Go to https://live.openlab.app/ and login into your account.

Click the "New configuration" button on the homepage and a dialog box should appear. Choose the template that is most closely related to your configuration and name it. You will delete this configuration later.

Take note of the configuration id.

Retrieve configuration data

import openlab

# Auto-generated credentials from https://live.openlab.app
username="hols@norceresearch.no"
apikey=""
licenseguid=""

session = openlab.http_client()

Get the data and print it out to inspect it.

# Copy and paste this id from the web client url endpoint
config_id = ""

data = session.get_configuration_data(config_id)

print(data)

This outputs an unnavigable chunk of text, so we inspect the dictionaries keys to give us a clue and help navigate to where UCS might be.

print(data.keys())

output -> ['Rig', 'Fluids', 'GeoThermal', 'Trajectory', 'DrillString', 'GeoPressure', 'Architecture', 'FormationStrength']

Upon further investigation, we see that FormationStrength is a list of dictionaries, with each dictionary element consisting of a UCS key:value pair.

Let's print out the last element's UCS

# Get the last elements UCS
fs_last = data["FormationStrength"][-1]
ucs_last = fs_last["UCS"]

print(ucs)

Edit the data

Now that we have found the data we want to make changes to, we can update it. We will assign the original scratch config data a new value (double the original value).

# Double each UCS
for fs in data["FormationStrength"]:
    fs["UCS"] *= 2

Push the new configuration data

Finally, we create the new configuration by calling the create_configuration(name, data) method, passing in the newly manipulated configuration data.

# Create a new configuration with the edited data
name = "Doubled UCS"
session.create_configuration(name, data)

Now, we have created a new configuration which has double the UCS as the default template. You can verify this by going to the web client and viewing the new configuration.

Final Code

import openlab

# Initialize an openlab session
session = openlab.http_client()

# Get an existing configuration
config_id = "aee5eb03-f550-4c27-81d9-5673cd9b5876"
data = session.configuration_data(config_id)


# Double each UCS
for fs in data["FormationStrength"]:
    fs["UCS"] *= 2

# Create a new configuraition with the edited data
session.create_configuration("New Configuration", data)

Joystick Enablement

Connecting and Enabling Joystick

Summary of Joystick Controls

Calibration

Who is using OpenLab:

  • University of Stavanger
  • NTNU
  • Aker BP
  • Maersk Drilling
  • Equinor
  • University of Calgary