Bumblebee API

Bumblebee provides a Python API to allow for automated submission of Bumblebee simulations.

This tutorial documents:

  • How to load the Bumblebee API

  • How to access, modify or create simulation input

  • Job submission and access to simulation output

Establishing the API Connection

In order to use the Bumblebee API from a Python script, the API package must be loaded.

from scm.bumblebee.api import resources

By using the amspython environment, this package is automatically included.

Note

In order to submit jobs or analyse output, a valid AMS installation and license file must be available on your machine. Make sure that the AMS environment variables are available in your Python shell in order for the API to detect the installation. When using amspython, this should have been configured automatically.

Creating New Resources

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

material = resources.Material()

New resources use the same default values as those defined by BBinput. 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 BBinput. 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 create a new input file by using the write_to_yaml method. Materials or compositions created this way can then be imported into the BBinput database to make them available for other simulations.

material.write_to_yaml(filename="ir_ppy3.yml")

Note

Material parameters that were obtained using the AMS OLED Workflow can be loaded directly into Python. The Bumblebee API allows you to construct materials using these parameters in order to perform device-level simulations. The construction of compositions using multiple materials will be treated in the next tutorial.

Modifying Existing Resources

Previously-created resources can be loaded by reading YAML or BEE files.

irppy3 = resources.Material("ir_ppy3.yml")

In order to load multiple resources from a single file, the ProjectController can be used instead. This will load all materials, compositions, stack, parameter sets and simulation settings, if available.

# View list of compositions in BEE project
project = resources.ProjectController("input.bee")
for composition in project.compositions:
    print(comp.name)

Job Submission and Monitoring

The run method is used to start new Bumblebee simulations through the API. By default, this will start the Bumblebee job on your local machine.

# Submit the simulation in the current working directory
simulation.run()

If you want to run the job on a remote queue, you can convert your Python script to a remote job using AMSjobs. The Python script will then be executed on the remote machine instead. AMSjobs allows you to use your preconfigured remote queues when running Bumblebee.

The status of an ongoing job can be monitored using the status method.

# Return code 0 to indicate successful job completion
status = simulation.status()

Status codes follow the Python standards for your platform.

The Bumblebee API allows for multiple jobs to run in parallel. Once the jobs have been submitted, we can wait for the simulations to finish by invoking the wait method.

# Wait for simulation to finish
simulation.wait()

Accessing Simulation Output

Simulation output can be accessed through the Python API using the Report class. The list method can be used to get an overview of the available analysis tools.

# Load simulation output
report = resources.Report(simulation.folder)

# Print overview of analysis methods
print(report.list())

These tools 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.

# Obtain the JV curve from the results
jv_result, err = report.get(report_name="jv")

# Obtain the electron density profile at 5.0 V during the 3rd trajectory
ne_result, err = report.get(report_name="Trajectory/electron_profile", sweep=5, trajectory=3, dataframe=True)

Tip

The dataframe option will attempt to convert the output into a pandas DataFrame, if this package is installed on your machine.