API Access¶

API Installation¶

The Bumblebee Python package can be obtained from the Downloads tab in the web interface. Clicking on your username will open a menu, from which you can access Downloads.

Installation packages are provided as either a wheel or sdist file.

python -m pip install bumblebee-api.whl

python -m pip install bumblebee-api.tar.gz

Configuring the API Connection¶

A valid API token is required to connect the Python API to the web interface. Login to your Bumblebee account and go to Settings/Authentication. In the API access section, the Generate access token option will generate and download a new credentials file.

Warning

The API token provides access to the data stored in your web interface account. If you believe token access has been compromised, you can delete specific tokens from the settings menu.

Establishing the API Connection¶

In order to use the Python API from a Python script, the Bumblebee Package must be loaded. A connection to the web interface is then made by creating a Client object.

import bumblebee
bb_client =  bumblebee.Client()

By default, Python will look for the credentials file in the current working directory. An alternative location can be specified using:

bb_client = bumblebee.Client(credentials_path="/home/user/Downloads/bumblebee-api.pem")

Creating New Resources¶

The Bumblebee Client allows for the creation of new resources such as materials, compositions, stacks or parameter sets. This can be achieved by using the new method.

material = bb_client.new('material')

These resources are stored locally inside your Python environment and are not automatically added to the database in the web interface. This allows you to make modifications to the local resources before committing them to persistent storage.

New resources use the same default values as those created by the web interface. The print function can be used to see the current resource parameters.

print(material)

Individual resource parameters can be accessed using their common names. These common names are available as part of the tooltips in the web interface. Simply hover over the info icon to view the API name corresponding to the parameter.

Modifications to the resource parameters can be performed using simple Python assignments.

material.name = "Ir(ppy3)"
material.homo = -5.27
material.lumo = -1.86

After you have set all the necessary resource parameters, you can upload the resource to the database using the create method. This will make the resource available from within the web interface.

material.create()

If you wish to make a modification to the resource after it has been added to the database, the update method must be used instead.

material.sigma_homo = 0.1
material.sigma_lumo = 0.1
material.update()

Modifying Existing Resources¶

To make modifications to existing database entries, the get method is used to initialize a local resource.

parameter_set_id = 94
parameter_set = bb_client.get("param_set", parameter_set_id)

The get method retrieves database entries based on their ID. This ID is an integer number assigned to each resource, which can be viewed from the web interface.

A list of resources in the current database can be obtained using the list method.

compositions = bb_client.list("composition")
for composition in compositions:
    print(comp.id, comp.name)

The list method also allows filtering of entries based on:

• The project ID

• User access

• Resource names

# Obtain a list of compositions in project 2 containing CBP in the name
compositions = bb_client.list("composition", project_id=2, scope="project", search="CBP")

# Obtain a list of stacks that are shared with the current user
stacks = bb_client.list("stack", scope="user")

Similar to the newly-created resources, modifications to these existing database entries are only applied locally. Use the update method to upload changes back into the database.

Deleting Resources¶

A resource can be deleted from the database by using the delete method.

material = bb_client.get("material", id=12)
material.delete()

Simulation objects are always moved to the trash folder first, in order to prevent accidental deletion of simulation output. Calling the delete method on a simulation that is already in the trash folder will permanently remove the resource. The web interface will then also request deletion of the simulation output data on the storage server.

simulation = bb_client.get("simulation", id=8)
simulation.delete() # Move to trash
simulation.delete() # Delete permanently

Accessing Simulation Output¶

Simulation output can be accessed through the Python API using the results method.

A convenient way to access simulation results is provided by the results object that is attached to each simulation resource. The available method can be used to list the accessible resources and their corresponding API names.

# List available results
simulation.results.available()

Result methods provided access to numerical data, which can be used for user-defined analysis and visualization routines. Various result methods allow extraction of data from specific parameter sweeps or trajectories. Always use the available method first to confirm that these results are included in the output before calling any access methods.

# Obtain the JV curve from the results
jv_result = sim.results.jv()

# Obtain the electron density profile at 5.0 V during the 3rd trajectory
ne_result = sim.results.electron_profile(sweeppoint=5, box=3)