Skip to content

Part I - Starting your first simulation

Download the jupyter notebook

Starting your first 3Di simulation💡

In this notebook we will go through the steps of connecting to the threedi-api and start our first simple 3Di simulation.

Let's first import all required modules for the notebook:

from datetime import datetime
from getpass import getpass
from threedi_api_client.openapi import ApiException
from threedi_api_client.api import ThreediApi
from threedi_api_client.versions import V3Api

Then we'll provide our credentials to connect to the threedi-api

USERNAME = input("Username")
PASSWORD = getpass("Password")
config = {

api_client: V3Api = ThreediApi(config=config)

Check if we can connect to the threedi-api with the provided credentials:

    user = api_client.auth_profile_list()
except ApiException as e:
    print("Oops, something went wrong. Maybe you made a typo?")
    print(f"Successfully logged in as {user.username}!")

To run a simulation we'll need a threedi-model. Let's see which threedi-models are available:

models = api_client.threedimodels_list(limit=5)  # limit to the first 5 results
for model in models.results:

If we already know the name of a specific model, we can also look it up with the following api call:

my_model = api_client.threedimodels_list(name__icontains='v2_bergermeer')

my_model = my_model.results[0]

Now that we have a model we are almost ready to create the simulation. But first we'll need to choose an organisation under which name the simulation will run.

Let's see which organisations are available:

organisations = api_client.organisations_list()
for organisation in organisations.results:
    print(f"{}: {organisation.unique_id}")

Here I use the following organisation, you should select from the list below

organisation_uuid = "b08433fa47c1401eb9cbd4156034c679"

Now we have all the components to create a simulation

my_simulation = api_client.simulations_create(
        "name": "my first simulation",
        "organisation": organisation_uuid,
        "duration": 3600  # in seconds, ie. 1-hour simulation duration

The simulation has now been created but it is not yet running. We can see the status of the simulation with the following call:

status = api_client.simulations_status_list(

To run this simulation, we have to tell it to start:

api_client.simulations_actions_create(, data={"name": "start"})

Eventually the simulation will finish. You can periodically check its progress by calling for the status again:


Eventually you should see something like this::

     'created': datetime.datetime(2020, 7, 27, 14, 7, 6, 654905, tzinfo=tzutc()),
     'id': 15866,
     'name': 'finished',
     'paused': False,
     'time': 3600.0


Congratulations, you just made your first simulation via the threedi-api-client!