Job Submission

The Bumblebee Python API can be used to set up new simulations without going through the BBinput GUI.

In this tutorial, we will illustrate how to set up the Ir(ppy3)-based phosphorescent OLED simulation from a previous GUI tutorial.

Create Materials

Materials created using the Python API automatically configure the default values defined by BBinput. It is not possible to load templates, thus requiring all relevant parameters to be set manually.

# Create phosphorescent dye
dye = resources.Material()
dye.name = "Irppy3"
dye.homo = -5.27
dye.lumo = -1.86

# Compute the exciton levels from the binding energies
dye.singlet_binding_energy = 0.75
dye.triplet_binding_energy = 1.0
dye.singlet = dye.homo - dye.lumo + dye.singlet_binding_energy
dye.triplet = dye.homo - dye.lumo + dye.triplet_binding_energy

# Configure phosphorescent emission
dye.st_ratio = 0
dye.tta_ratio = 0
dye.isc_rate = 1e10
dye.triplet_rad_decay = 6.1e5
dye.triplet_nonrad_decay = 1.9e4

# Create host matrix
host = resources.Material()
host.name = "CBP"
host.homo = -6.08
host.lumo = -1.75
host.singlet_binding_energy = 1.0
host.triplet_binding_energy = 1.7
host.singlet = host.homo - host.lumo + host.singlet_binding_energy
host.triplet = host.homo - host.lumo + host.triplet_binding_energy
host.dexter_prefactor_singlet = 0.95
host.dexter_prefactor_triplet = 0.95
host.singlet_nonrad_decay = 1e5
host.triplet_nonrad_decay = 1e4

# Create electron transport layer
etl = resources.Material()
etl.name = "TPBi"
etl.homo = -6.2
etl.lumo = -1.7
etl.singlet_binding_energy = 0.75
etl.triplet_binding_energy = 1.0
etl.singlet = etl.homo - etl.lumo + etl.singlet_binding_energy
etl.triplet = etl.homo - etl.lumo + etl.triplet_binding_energy
etl.singlet_nonrad_decay = 1e8
etl.triplet_nonrad_decay = 1e8

# Create hole transport layer
htl = resources.Material()
htl.name = "TAPC"
htl.homo = -5.5
htl.lumo = -0.96
htl.singlet_binding_energy = 1.0
htl.triplet_binding_energy = 1.59
htl.singlet = htl.homo - htl.lumo + htl.singlet_binding_energy
htl.triplet = htl.homo - htl.lumo + htl.triplet_binding_energy
htl.singlet_nonrad_decay = 1e8
htl.triplet_nonrad_decay = 1e8

Create Compositions

The add_fraction method is used when creating layer compositions. Note that the Python API does not automatically create pure compositions for the materials.

# Host-guest mixture
hostguest = resources.Composition()
hostguest.name = "CBP-5Irppy3"
hostguest.add_fraction(0.95, host)
hostguest.add_fraction(0.05, dye)

# Pure HTL
pure_htl = resources.Composition()
pure_htl.name = "Pure TAPC"
pure_htl.add_fraction(1, htl)

# Pure ETL
pure_etl = resources.Composition()
pure_etl.name = "Pure TPBi"
pure_etl.add_fraction(1, etl)

Create a Stack

Layers can be added to the stack in a similar way using the add_layer method.

# Add layers to the stack
stack = resources.Stack()
stack.name = "TAPC-CBP-5Irppy3-TPBi"
stack.add_layer("HTL", 20, pure_htl)
stack.add_layer("EMI", 30, hostguest)
stack.add_layer("ETL", 20, pure_etl)

Förster interactions must be specified for each donor-acceptor pair. For this tutorial, we will limit ourselves to interactions between the host and guest. Förster processes are each assigned a unique ID, in accordance with their order in BBinput:

  1. Singlet diffusion

  2. Singlet-hole quenching

  3. Singlet-electron quenching

  4. Singlet-singlet annihilation

  5. Singlet-triplet annihilation

  6. Triplet diffusion

  7. Triplet-hole quenching

  8. Triplet-electron quenching

  9. Triplet-singlet annihilation

  10. Triplet-triplet annihilation

# Configure Förster interactions inside host-guest system
donor_layer = 1
acceptor_layer = 1
radius = 1.5
# Only consider triplet processes
for interaction in [5,6,7,9]:
    for donor_material in range(0, len(hostguest.materials)):
        for acceptor_material in range(0, len(hostguest.materials)):
            stack.add_foerster(interaction,
                               donor_layer,
                               donor_material,
                               acceptor_layer,
                               acceptor_material,
                               radius)

Additional processes can be specified using the add_dexter, add_absorption, add_degradation, and add_dopant methods.

Create a Parameter Set

We select the newly-created stack when configuring the parameter set.

# Link the stack to a new parameter set
parameter_set = resources.Parameters()
parameter_set.name = "SingleVoltage-CBP-5Irppy"
parameter_set.add_stack(stack)

# Set the voltage point
parameter_set.voltage = 5

Note

If the electrode energy levels are not set in the API, default Ohmic contacts will be configured.

Simulation Setup

A simulation resource is used to set up a Bumblebee job. The simulation type is set using the add_sweep method.

# Create a single-voltage simulation using the new parameter set
simulation = resources.Simulation()
simulation.name = "1V-CBP-5Irppy"
simulation.add_sweep(parameter_set, first_disorder=1, final_disorder=5)

# Submit the simulation
simulation.create()

Parameter sweeps can also be specified, analogous to BBinput:

# Create a voltage sweep
sweep = resources.Simulation()
sweep.name = "Sweep-CBP-5Irppy"
sweep.add_sweep(parameter_set, first_disorder=1, final_disorder=2,
                sweep_variable='voltage', sweep_from=1, sweep_to=5, sweep_steps=5)

Starting the Simulation

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

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

Tip

If you want to run the job on a remote queue, you can convert your Python script to a remote job using AMSjobs. This allows you to use your preconfigured remote queues when running Bumblebee.

Alternatively, you can write input files using the write_to_yaml method, then submit your calculations through BBinput as usual.

Simulation Status

The progress of the simulation can be monitored with the status method.

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

When running jobs on a remote machine, the job monitoring tools in BBresults can be used to check the progress of the simulation.