Usage¶
Graphical User Interface¶
The Bumblebee GUI manages the creation (BBinput), submission (AMSjobs) and analysis (BBresults) of Bumblebee simulations. With BBinput you create a project file (.bee) containing the simulation/device settings. A run script (.run) is also created automatically. The run script can be executed by AMSjobs. The output is stored in a directory (.results) which can be examined with BBresults.
BBinput: Setting up the Simulation¶
Simulation setup can be divided into two steps:
Define the stack
Specify parameters and simulation details
This approach allows you to re-use stacks from earlier simulations in order to easily run multiple analyses. Or, when optimizing a stack, you can re-use the same simulation settings with a modified device.
The OLED stack consists of multiple layers. Each layer has a material composition and a certain thickness. After building the stack, you specify the active processes (TPQ, degradation), simulation parameters (voltage, temperature) and the simulation type (JV, TOF, TRPL).
The GUI tutorials can help you get familiar with running Bumblebee simulations. Tooltips are provided in BBinput to explain various settings and assist in simulation setup.
BBinput also includes various templates for e.g. material classes or simulation types. These allow you to automatically configure most of the settings for commonly-used jobs. Details on these templates and some of the recommended settings are provided in the following sections.
Materials¶
The materials page allows definition of the properties for the various materials to be used in the stack.
Material templates¶
Several template settings are available to expedite the configuration of new materials.
Host layers allow for non-radiative decay of both singlet and triplet species
Transport layers do not emit light
Fluorescent dyes assume all singlet decay processes to be radiative
Phosphorescent dyes assume all excitons to be triplets. All decay processes are assumed to be radiative
TADF dyes assume triplet decay to occur through ISC
Optical layers do not participate in charge carrier processes and are included only to enable calculation of optical device parameters
Advanced materials disable all presets
Material database¶
A database of commonly used and commercially available OLED materials is included with BBinput. The material parameters have been obtained primarily using experimental data.
Database materials can be used to quickly substitute and explore different stack configurations.
Compositions¶
From the materials, compositions can be defined by using nanoscale distributions (mixtures) of multiple materials. If a composition is made of only one material it is called a pure composition.
Basic compositions are defined as a mixture of materials with a specific ratio. Components are distributed randomly within the layer. Mesoscopic layer properties (such as the absorbance) are computed as a stoichiometric average of the material parameters
Advanced compositions allow usage of gradients to construct more complex distributions, as well as the creation of polymeric morphologies
Stack¶
A stack is composed of a number or layers, each with their own composition and thickness. Inter-layer transfer processes can be defined based on the molecular layer properties.
Parameters¶
The parameters section contains the general simulation settings. For clarity, these have been organized into tabs.
The Main tab contains device settings (voltage, temperature, electrodes)
The Modules tab is used to toggle different aspects of the simulation (excitonic processes, photoluminescence, device degradation)
The Output tab controls what properties are calculated in the output
The Volume tab is used to set the device size as well as the spatial energy correlations
The Termination tab sets the length of the simulation
The Transient tab configures time-dependent simulation parameters (such as pulsed illumination or AV)
The OFET tab is used to set up simulations of transistor devices
The Photoluminescence tab contains photoabsorption settings for photoluminescence simulations
The Acceleration tab contains the accelerated kMC settings
The Annealing tab is used to configure annealing and pre-equilibration stages
The Advanced tab contains technical simulations parameters
The Optical tab controls the optical simulation settings for Firefly
Parameter templates¶
Template parameter sets are provided to automatically configure modules and commonly used settings for the various simulation types facilitated by Bumblebee.
Single voltage points allow simulation of excitonic processes at DC
Voltage sweeps automatically configure the voltage as the simulation sweep parameter. Hole-only and electron-only versions allow specification of a fixed carrier density
Bulk simulations enable periodic boundary conditions (PBC) for TOF experiments. Excitonic processes are disabled by default, as these simulations typically use low carrier densities.
Lifetime simulations include device degradation processes
Photoluminescence simulations model current generation upon light exposure. PBC are enabled. Grid densities are doubled compared to other defaults to account for polaron interactions
Photovoltaic and photodetector simulations model photoluminescence processes under closed circuit conditions
Transistor simulations are used to model OFETs
Optical simulations automatically configure Firefly for optical outcoupling calculations
Advanced simulations disable presets
Photoluminescent, photovoltaic and photodetector presets enable transient output files by default.
Simulation¶
The simulation page allows you to define
Parameter sweeps
Stochastic trajectory sampling
Bumblebee typically uses multiple trajectories to improve the kMC statistics. This results in lower uncertainties in the simulated device performance.
Parameter sweeps allow you to run the same simulation while changing certain parameter values. Each sweep point will be submitted as a separate job (with its own set of trajectories). BBresults automatically collects the output from the parameter sweep to generate reports and visualize the results.
AMSjobs¶
AMSjobs is used to manage running Bumblebee simulations, allowing use of remote queues for submitting jobs to compute clusters. AMSjobs can also be used to access BBinput and BBresults. You can select simulations in AMSjobs to view/modify input settings in BBinput, or to use BBresults for visualization or monitoring.
When starting Bumblebee jobs, it is recommended not to let the number of cores exceed the number of trajectories. Consult the queue setup guide for more details on configuring core allocation. For convenience, the number of trajectories is shown in the main Project page of BBinput.
BBresults: Visualization¶
BBresults provides many report options for analyzing Bumblebee output. Both graphs and tables are included in the reports. BBresults can also be used to monitor ongoing simulations.
The Status tab shows the status of the ongoing simulations for each sweep and trajectory
Trajectories can be selected to view the convergence of the simulation
You can terminate trajectories from the monitor view. (Without affecting other jobs)
You can request additional trajectories to improve statistics
You can request additional sweep points to extend screenings
Device reports summarize device-level performance metrics. These reports also display the parameter sweep results when varying external parameters (such as the voltage)
Overview reports yield the voltage-current profiles, integrated quantum efficiency, external quantum efficiency, voltage-dependent process frequencies and carrier densities
Profiles report on the carrier densities and photo-electronic process frequencies
Excitonic events report on the relative process frequencies and are used to break down device losses
Effective mobility reports on the voltage-dependent polaron mobility for TOF measurements
Luminance reports give the effective device luminance for the CIE 1931 and CIE 1978 standard eye responses, in addition to the power efficiency
Sweep reports collect output of multiple kMC trajectories for each sweep point
Overview shows the average carrier densities, photo-electronic process frequencies and device potential
Convergence reports aggregate statistics on the transient current profiles and integrated quantum efficiency
Emission shows the computed emission spectrum
Photoluminescence reports on the radiative excitation rates and exciton densities
Optical reports outcoupling efficiencies for individual layer materials
Material profiles report on carrier densities and photo-electronic process frequencies for individual layer materials
Time progress reports aggregate statistics on transient current profiles, carrier densities, photo-electronic process frequencies, voltages and device degradation
Trajectory reports display the output of individual kMC trajectories
Overview shows the transient carrier densities, photo-electronic process frequencies and device potential
Convergence shows the transient current profile
Morphology shows the distribution of materials in the stack
Optical reports display the optical output from the device: Polarized outcoupling intensities, outcoupling efficiencies and anisotropic Purcell factors.
Outcoupling efficiency reports device-level outcoupling efficiencies
Output intensity contains the polarized outcoupling intensity
Purcell displays the anisotropic Purcell factors
The available reports are shown depending on the output generated by the simulation. Parameter set templates automatically configure output for relevant processes.
Input Files¶
BBinput automatically generates the input files necessary to run Bumblebee simulations. Relevant data can be found in the following files:
params.yml contains the simulation settings (materials, compositions, stack, parameters)
optical contains the simulation data for optical simulations (complex refractive indices, emission spectra)
Output Files¶
Bumblebee output is split across various files.
Human-readable .out files detailing the computed device parameters or simulation statistics
Binary .dat files contain trajectory snapshots that can be analyzed to investigate the individual kMC samples. 64 bit floating point precision is used
Visualization and analysis of these files is handled automatically by BBresults. An overview of the files is provided here if custom visualization, analysis or post-processing is desired.
Tip
You can also export the graph data from BBresults for visualization in other programs.
General output:
output.log documents the progress of the Bumblebee simulation
disorder_result.out stores the simulation summary for the final Monte Carlo step
time_progress.out summarizes the simulation progress results
param_overview.out records the input parameters after Bumblebee pre-processing and input sanitation
Time-averaged device profiles:
elec_profile.out and hole_profile.out report the time-average cross-sectional polaron charge. The combined charge profile is stored in chargedens_profile.out
mat_elec_profile.out and mat_hole_profile.out contain the time-average cross-sectional polaron charge per material. Separate files are generated for each material
singlet_profile.out and triplet_profile.out report the time-average cross-sectional exciton counts
mat_singlet_profile.out and mat_triplet_profile.out contain the time-average cross-sectional exciton counts per material. Separate files are generated for each material
potential_profile_normal.out contains the time-average cross-sectional voltage potential. potential_profile_disccutout.out reports the voltage potential after including the short-range Coulomb corrections. potential_profile_incl_impot.out reports the voltage potential after including periodic image charges. potential_profile_disccutout_incl_impot.out reports the voltage potential after including both the short-range Coulomb corrections and periodic image charges
Transient device profiles:
electroncurrent.out and holecurrent.out report the polaron fluxes for each cross-section. The first entry on each line gives the timestamp. The net charge flux is reported in layercurrent.out
electroncurrentx.out and holecurrentx.out report the polaron fluxes along the OFET gate for each cross-section. The first entry on each line gives the timestamp. The net charge flux is reported in layercurrentx.out
recombination_abs_profile.out reports the cross-sectional radiative exciton recombination event count. The first entry on each line gives the timestamp. recombination_rate_profile.out reports the per-gridpoint, per-timestep average inside each cross-section
generation_abs_profile.out reports the cross-sectional exciton generation event count. The first entry on each line gives the timestamp. generation_rate_profile.out reports the per-gridpoint, per-timestep average inside each cross-section
dissociation_abs_profile.out reports the cross-sectional exciton dissociation event count. The first entry on each line gives the timestamp. dissociation_rate_profile.out reports the per-gridpoint, per-timestep average inside each cross-section
thermal_generation_abs_profile.out reports the cross-sectional thermal exciton generation event count. The first entry on each line gives the timestamp. thermal_generation_rate_profile.out reports the per-gridpoint, per-timestep average inside each cross-section
electron_quenching_abs_profile.out and hole_quenching_abs_profile.out report the cross-sectional electron and hole quenching event counts. The first entry on each line gives the timestamp. quenching_abs_profile.out reports the total quenching event count. electron_quenching_rate_profile.out, hole_quenching_rate_profile.out and quenching_rate_profile.out report the respective per-gridpoint, per-timestep averages inside each cross-section.
annihilation_abs_profile.out reports the cross-sectional exciton annihilation event count. The first entry on each line gives the timestamp. annihilation_rate_profile.out reports the per-gridpoint, per-timestep average inside each cross-section
nonrad_decay_abs_profile.out reports the cross-sectional non-radiative exciton decay event count. The first entry on each line gives the timestamp. nonrad_decay_rate_profile.out reports the per-gridpoint, per-timestep average inside each cross-section
absorption_abs_profile.out reports the cross-sectional photonic absorption event count. The first entry on each line gives the timestamp. absorption_rate_profile.out reports the per-gridpoint, per-timestep average inside each cross-section
degradation_abs_profile.out reports the cross-sectional degradation event count. The first entry on each line gives the timestamp. degradation_rate_profile.out reports the per-gridpoint, per-timestep average inside each cross-section
exciplex_decay_abs_profile.out reports the cross-sectional radiative exciplex decay event count. The first entry on each line gives the timestamp. exciplex_decay_rate_profile.out reports the per-gridpoint, per-timestep average inside each cross-section
exciplex_nonrad_decay_abs_profile.out reports the cross-sectional non-radiative exciplex decay event count. The first entry on each line gives the timestamp. exciplex_nonrad_decay_rate_profile.out reports the per-gridpoint, per-timestep average inside each cross-section
exciplex_thermal_generation_abs_profile.out reports the cross-sectional thermal exciplex generation event count. The first entry on each line gives the timestamp. exciplex_thermal_generation_rate_profile.out reports the per-gridpoint, per-timestep average inside each cross-section
transient_elec_profile.out and transient_hole_profile.out report the cross-sectional polaron charges. The first entry on each line gives the timestamp
transient_mat_elec_profile.out and transient_mat_hole_profile.out contain the cross-sectional polaron charge per material. Separate files are generated for each material. The first entry on each line gives the timestamp
transient_singlet_profile.out and transient_triplet_profile.out report the cross-sectional exciton counts. The first entry on each line gives the timestamp
transient_mat_singlet_profile.out and transient_mat_triplet_profile.out contain the cross-sectional exciton counts per material. Separate files are generated for each material. The first entry on each line gives the timestamp
transient_potential_profile_normal.out contains the cross-sectional voltage potential. transient_potential_profile_disccutout.out reports the voltage potential after including the short-range Coulomb corrections. transient_potential_profile_incl_impot.out reports the voltage potential after including periodic image charges. transient_potential_profile_disccutout_incl_impot.out reports the voltage potential after including both the short-range Coulomb corrections and periodic image charges. The first entry on each line gives the timestamp
Transient trajectories: (Note that these generate significant amounts of data)
transient_recombination_abs_profile.out reports the cross-sectional radiative exciton recombination event count during each individual iteration
transient_quenching_abs_profile.out reports the total cross-sectional polaron quenching event count during each individual iteration
transient_annihilation_abs_profile.out reports the cross-sectional exciton annihilation event count during each individual iteration
transient_nonrad_decay_abs_profile.out reports the cross-sectional non-radiative exciton decay event count during each individual iteration
transient_exciplex_decay_abs_profile.out reports the cross-sectional radiative exciplex decay event count during each individual iteration
transient_exciplex_nonrad_decay_abs_profile.out reports the cross-sectional non-radiative exciplex decay event count during each individual iteration
transient_exciplex_tgens_abs_profile.out reports the cross-sectional thermal exciplex generation event count during each individual iteration
Locations of electronic species:
carrier_config.dat and carrier_config_pt.out report on the charge carrier positions. For each species, the carrier coordinates are followed by the polaron type (0 indicates an electron, 1 indicates a hole)
exciton_config.dat and exciton_config_pt.out report on the charge carrier positions. For each species, the carrier coordinates are followed by the exciton type (1 indicates a singlet, 3 indicates a triplet)
Properties per gridpoint:
composition.dat and composition_plaintext.out record the material ID for each gridpoint inside the stack
disorder.dat and disorder_plaintext.out report on the energetic disorder in the HOMO and LUMO levels at each gridpoint
excitonic_disorder.dat and excitonic_disorder_plaintext.out report on the energetic disorder in the singlet and triplet levels at each gridpoint. exciton_binding_energies.out reports on the singlet and triplet binding energies at each gridpoint
kappa.dat and kappa_plaintext.out report on the transition multipole orientations at each gridpoint
electrons_per_site.out and holes_per_site.out report the time-average polaron charge for each gridpoint
singlets_per_site.out and triplets_per_site.out report the time-average exciton counts for each gridpoint
transient_composition.dat and transient_composition_plaintext.out record the material ID for each gridpoint inside the stack. The first entry on each line gives the timestamp
transient_disorder.dat and transient_disorder_plaintext.out report on the energetic disorder in the HOMO and LUMO levels at each gridpoint. The first entry on each line gives the timestamp
transient_excitonic_disorder.dat and transient_excitonic_disorder_plaintext.out report on the energetic disorder in the singlet and triplet levels at each gridpoint. transient_exciton_binding_energies.out reports on the singlet and triplet binding energies at each gridpoint. The first entry on each line gives the timestamp
A one-dimensional gridpoint indexing system is used. The gridpoint coordinates can be obtained from the (0-based) index \(k\) as:
Event log per gridpoint:
singlet_recomb_per_site.out and triplet_recomb_per_site.out report the number of singlet and triplet recombination events that occurred at each gridpoint. recomb_per_site.out reports on the total number of recombination events. Each line in these files contains the gridpoint coordinates, followed by the event count
singlet_gens_per_site.out and triplet_gens_per_site.out report the number of singlet and triplet generation events that occurred at each gridpoint. gen_per_site.out reports on the total number of generation events. Each line in these files contains the gridpoint coordinates, followed by the event count
singlet_dis_per_site.out and triplet_dis_per_site.out report the number of singlet and triplet dissociation events that occurred at each gridpoint. dis_per_site.out reports on the total number of dissociation events. Each line in these files contains the gridpoint coordinates, followed by the event count
singlet_quenchings_per_site.out and triplet_quenchings_per_site.out report the number of singlet and triplet quenching events that occurred at each gridpoint. quenchings_per_site.out reports on the total number of quenching events. Each line in these files contains the gridpoint coordinates, followed by the event count
singlet_anns_per_site.out and triplet_anns_per_site.out report the number of singlet and triplet annihilation events that occurred at each gridpoint. anns_per_site.out reports on the total number of annihilation events. Each line in these files contains the gridpoint coordinates, followed by the event count
singlet_nonrads_per_site.out and triplet_nonrads_per_site.out report the number of non-radiative singlet and triplet decay events that occurred at each gridpoint. nonrads_per_site.out reports on the total number of non-radiative decay events. Each line in these files contains the gridpoint coordinates, followed by the event count
singlet_iscs_per_site.out and triplet_iscs_per_site.out report the number of intersystem and reverse intersystem crossing events that occurred at each gridpoint. iscs_per_site.out reports on the total number of crossing events. Each line in these files contains the gridpoint coordinates, followed by the event count
singlet_tgens_per_site.out and triplet_tgens_per_site.out report the number of thermal singlet and triplet generation events that occurred at each gridpoint. tgens_per_site.out reports on the total number of thermal generation events. Each line in these files contains the gridpoint coordinates, followed by the event count
abs_per_site.out records the number of photonic absorption events that occurred at each gridpoint
degradations_per_site.out records the number of degradation events that occurred at each gridpoint
exciplex_decay_per_site.out records the number of radiative exciplex decay events that occurred at each gridpoint
exciplex_nonrads_per_site.out records the number of non-radiative exciplex decay events that occurred at each gridpoint
exciplex_tgens_per_site.out records the number of thermal exciplex generation events that occurred at each gridpoint
Transient event log:
eventlog.out records all photo-electronic events. Switches are available to select (0) polaron hopping, (1) polaron injection at the electrodes, (2) polaron collection at the electrodes, (3) radiative exciton recombination, (4) exciton generation, (6) thermal exciton generation, (7) exciton hopping, (8) non-radiative exciton decay, (9) exciton annihilation, (10) polaron quenching, (11) exciton dissociation, (12) intersystem crossing, (13) photonic absorption, (14) degradation, (15) radiative exciton decay, (16) non-radiative exciton decay, (17) thermal exciplex generation, (18) polaron-induced exciton recombination and/or (19) transfer-induced polaron quenching. For each event, the gridpoint, reactant and product are reported (0 for electrons, 1 for holes, 2 for singlets, 3 for triplets). For degradation events, the degradation mechanism and product material are reported instead (0 for exciton generation, 1 for polaron quenching, 2 for exciton annihilation, 3 for hole quenching, 4 for electron quenching, 5 for photonic absorption, 6 for polaron hopping)
emissionlog.out records the location of individual exciton recombination events. For each event, the exciton type and energy are reported
degradationlog.out records the location of individual degradation events. For each event, the degradation mechanism and degradation products are reported. The carrier is indicated as 0 for electrons, 1 for holes, 2 for a singlet, 3 for a triplet
avlog.dat and avlog.out record the voltage and current under AC operation
Binary storage:
profiles.dat is a binary storage for the properties of the stack. This file contains:
The Bumblebee version number
The charge carrier current
The electron current
The hole current
The OFET carrier current
The OFET electron current
The OFET hole current
The cross-sectional exciton recombination event counts
The cross-sectional exciton generation event counts
The cross-sectional exciton dissociation event counts
The cross-sectional thermal exciton generation event counts
The cross-sectional polaron quenching event counts
The cross-sectional electron quenching event counts
The cross-sectional hole quenching event counts
The cross-sectional exciton annihilation event counts
The cross-sectional non-radiative exciton decay event counts
The cross-sectional photonic absorption event counts
The cross-sectional degradation event counts
The cross-sectional radiative exciplex decay event counts
The cross-sectional non-radiative exciplex decay event counts
The cross-sectional thermal exciplex generation event counts
The time-averaged cross-sectional electron counts
The time-averaged cross-sectional hole counts
The time-averaged cross-sectional singlet counts
The time-averaged cross-sectional triplet counts
The time-averaged cross-sectional electron counts per material
The time-averaged cross-sectional hole counts per material
The time-averaged cross-sectional singlet counts per material
The time-averaged cross-sectional triplet counts per material
The time-averaged electron counts at each gridpoint
The time-averaged hole counts at each gridpoint
The time-averaged singlet counts at each gridpoint
The time-averaged triplet counts at each gridpoint
rng.dat records the final state of the random number generator. This file is used for continuation runs
stats.dat records the event statistics. This file contains:
The Bumblebee version number
The number of elapsed Monte Carlo steps
The current simulation time
The last stepsize
The number of electron injections at the anode
The number of electron injections at the cathode
The number of hole injections at the anode
The number of hole injections at the cathode
The number of electron abstractions at the anode
The number of electron abstractions at the cathode
The number of hole abstractions at the anode
The number of hole abstractions at the cathode
The instantaneous device current
The instantaneous device current at the previous iteration
The number of exciton recombination events
The number of exciton recombination events at the previous iteration
The number of exciton generation events
The number of exciton generation events at the previous iteration
The number of photonic absorption events
The number of photonic absorption events at the previous iteration
The number of thermal exciton generation events
The number of exciton dissociation events
The number of polaron quenching events
The number of degradation events
The external field strength
The number of exciton annihilation events
The number of non-radiative exciton decay events
The number of intersystem crossings
The number of reverse intersystem crossings
The normalized minimum cross-sectional current
The normalized maximum cross-sectional current
The total number of exciton recombination events per gridpoint
The number of singlet recombination events per gridpoint
The number of triplet recombination events per gridpoint
The number of photonic absorption events per gridpoint
The number of singlet-generating absorption events per gridpoint
The number of triplet-generating absorption events per gridpoint
The total number of exciton generation events per gridpoint
The number of singlet generation events per gridpoint
The number of triplet generation events per gridpoint
The total number of thermal exciton generation events per gridpoint
The number of thermal singlet generation events per gridpoint
The number of thermal triplet generation events per gridpoint
The total number of exciton dissociation events per gridpoint
The number of singlet dissociation events per gridpoint
The number of triplet dissociation events per gridpoint
The total number of polaron quenching events per gridpoint
The number of singlet quenching events per gridpoint
The number of triplet quenching events per gridpoint
The total number of exciton annihilation events per gridpoint
The number of singlet annihilation events per gridpoint
The number of triplet annihilation events per gridpoint
The total number of non-radiative exciton decay events per gridpoint
The number of non-radiative singlet decay events per gridpoint
The number of non-radiative triplet decay events per gridpoint
The total number of (reverse) intersystem crossing events per gridpoint
The number of intersystem crossing events per gridpoint
The number of reverse intersystem crossing events per gridpoint
The number of degradation events per gridpoint
The number of radiative exciplex decay events per gridpoint
The number of non-radiative exciplex decay events per gridpoint
The number of thermal exciplex generation events per gridpoint
The device voltage
The final output timestamp
The timestamp of the last voltage update
The number of radiative exciplex decay events
The number of non-radiative exciplex decay events
The number of thermal exciplex generation events
Remaining files serve as utilities:
bumblebee.run contains the job submission script for the workload manager
jobid.out records the job ID number assigned by the workload manager
std.out reports messages from the workload manager
std.err reports errors from the workload manager
error.log contains error messages from Bumblebee
status.log records messages from the GUI
started.out records the UNIX timestamp for the start of the simulation
finished.out records the UNIX timestamp for the end of the simulation