LightForge GUI

Introduction to the LightForge GUI

As a multipurpose KMC program, LightForge offers a variety of modes of operation, options and ways to provide input for device simulation and the GUI that may be confusing at first sight. However we did our best to make the reducing complexity where possible, while exposing required functionality for both research new to LightForge and expert users. To this end you will find various check boxes throughout the LightForge GUI that allows the user to modify standard values, or supply additional settings. Whenever in doubt, we recommend to stick to the standard values.

The LightForge GUI consists of 7 tabs, through which we will guide you one by one below:

  • general: Defines the mode how the "digital twin" of your device is set up, and determines which options are available in the other tabs.
  • IO: If the LightForge run is based on microscopic parameters computed with QuantumPatch, all QuantumPatch output files can be supplied here as input.
  • materials: In this tab, material specific parameters can be supplied for all materials, either by hand or by assigning a specific QuantumPatch file to each material. Also, the method to compute excitonic rates is set here.
  • device: Define layer structure and electrode settings.
  • topology: In this tab you can define the settings for the topology, i.e. pair parameters such as electronic couplings for holes and electrons
  • physics: Here you can chose between different physical models (e.g. rate models) implemented in LightForge.
  • operation: Set up your virtual experiment, e.g. define applied electric fields or temperature.

"general" tab

  • device layout:
    • stack: This option should be used in most simulations, especially multilayer OLED stacks. Here the layer morphology are automatically stacked on top of each other with correct molecular distances between layers and between outermost layers and the electrodes.
    • manual: Use this option to manually place all layers by defining their center and dimension. Multiple electrodes can be applied e.g. for transistors. For advanced users only.
  • setPBC: periodic boundary condition (PBC) settings
    • automatic: PBC in y- and z-direction are applied and the field is applied in x-direction.
    • manual: PBC in x-, y- and z-direction are set by the user.
  • connect electrodes: If checked, electrodes are used to simulate injection of charge carriers into the device. For specific use cases, e.g. computation of field-dependent charge carrier mobility in bulk systems, electrodes are not required and the usage of periodic boundary conditions in all three dimensions can be applied.
  • particle types: Only checked particle types are considered in the KMC simulation. For a full device, electrons, holes and excitons are required. For charge carrier mobility simulations, for example, only holes or electrons are needed. Checking or unchecking particle types en-/disables different settings e.g. in the materials tab.

"IO" tab

  • use QP output: Uncheck this box if you want to supply all parameters manually. Keep this option checked if some or all parameters should be taken from QuantumPatch output.
  • QP output file box: Microscopic parameters can be read in from multiple QuantumPatch output files. Use the plus-/minus button to add or remove files.
    • name: Give each file a unique identifier that is later needed to assign QP files to materials. These identifiers will appear in drop-down menues in the materials, device and topology tab.
    • QP_output.zip: Load a file from your hard drive or chose a file from a preceding QP run in a workflow.
  • Override Settings: Very special lightforge simulations, or lightforge simulations using new features where the WaNo has not yet been adapted, may require settings not yet exposed in the WaNo. These settings can be entered via a settings-yaml file (see here for further information) which will be merged with the settings file generated via the WaNo, overriding WaNo settings with the settings from the file where applicable.

"materials" tab

Note: Your materials tab looks different than the one displayed in the picture above. Certain options are disabled depending on parameters suppied in other tabs, e.g. particles in the "general" tab, and then not displayed for clarity.

  • manual dopant selection: For simulation of doped injection layers or other systems with charge transfer processes, it may be required to manually select dopants. If checked, a new checkbox "is dopant" will appear for each material. Checkout this tutorial as example.
  • materials box: Each material used in the KMC simulation is defined here. If your system includes 5 compounds, click the plus-buttom 4 times to add four materials.
    • name: Define a unique identifyer for each material. This identifyer will appear in various drop down menues in other tabs.
    • input_mode_transport: For each material, chose which of the transport parameters (disorder, EA&IP, reorganization energy lambda) can be taken from QP output (if available) or supplied manually. In the options of the drop down menue, parameters listed after "QP" are taken from QP, parameters listed after "PAR" are set by the user below. If parameters are to be supplied manually, a table labeled "energies" will appear in the molecule_parameters box.
    • input_mode_excitonics: Only visible when excitons are enabled in the "general" tab. You have two options:
      • abinitio + presets: Where possible, microscopic results from QuantumPatch are used to compute material specific excitonic rates. For everything that is not computed by QuantumPatch, presents are used (see also "show exciton_presets" below). With this option enabled, the "QP_output_excitonics" dropdown is available in the "materials" box.
      • presets only: All excitonic parameters are computed using standard presets. A detailed documentation of the presets will follow shortly.
    • molecule parameters box: Energetic parameters (sigma, lambda, EA&IP) change from drop down to tables, if the user wants to supply them manually (see input_mode_transport above).
      • molecule_pdb: As any QP output file can contain information for multiple materials, we use the single-molecule pdb file used in Deposit to connect information stored in a QP output file to a certain material. This file needs to be provided here, either from the hard drive or from a previous module in the workflow (Parametrizer, DihedralParametrizer or Deposit).
      • QP_output_X: Dropdown menue to chose the QP output file to extract energy quantity X (X=sigma, lambda, EAIP) for this material, from the list of all QP output files provided in the IO section. Depending on the input_transport_mode above, the respecitve dropdown menues disappear and values can be supplied in the energies table.
      • energies: Table to manually supply parameters not extracted from QP output.
      • exciton preset: Chose fluorescent, phosphorescent. tadf or doping exction presets for this material. Checkout some of our usecases to find out which preset to apply.
  • show exciton_presets: Show and modify exciton presets. In case of doubt, do not change the presets.

"device" tab

  • morphology width [nm]: Defines the width of the simulated stack. As of now, all layers defined below have the same width in the KMC simulation.

  • layers: Add or remove layers to your stack structure using plus- or minus-button.

    • thickness: defines the thickness of a layer in nm
    • morphology_input_mode:
      • select QP output: A morphology generated with Deposit is taken from a QP output. Using this option, the user can then chose the respective QP output, as defined in the IO-tab, from the otherwise hidden "morphology_QP_output" drop-down menue.
      • cubic: Use a simple cubic lattice with lattice constant of 1nm as morphology. This is a good approach to include additional layers in KMC, using a parametric approach without having to run the full workflow (Parametrizer+Deposit+QP).
      • Custom files: morphology: Read in center of geometry for this layer from a file, where each lines contains x,y and z coordinate and an integer label in the 4th column.
      • Custom files: morphology, eaip: Along with the center of geometry you can supply an additional file containing site-specific EA and IP energy levels. This is a useful option for non-standard device setups such as gradual doping.
      • Custom files: morphology, homolumo: This is analogous to "Custom files: morphology, eaip", except that only the distribution of site energies is read from a file, but the mean value is taken from the material definition.
      • QP_output: HL generator: selecting this option will use periodically extended morphologies and energy levels from QuantumPatch. This only works if homolumo generator was activated in the QuantumPatch analysis section. A respective QP_ouput file has to be selected. This also requires to set "morphology expansion scheme: no expansion". If this option is chosen, thickness, width and dimension parameters are ignored.
    • molecule_species: adapt the number of materials ("molecule species") in the layer to simulate pristine or mixed layers, chose your molecules as defined in the materials section and adapt the concentrations.
  • electrodes: Define work functions and coupling models for electrodes. This option is hidden, if "connect_electrodes" in the general tab is disabled. There are three models available to compute coupling between electrodes and the organic layers:

    • QP_output: Couplings between the nearest organic layer and electrode are computed based on averaged distance dependent organic-organic couplings. This coupling can be scaled in electrode_J_stack_scaling in the advanced settings in the physics tab.
    • QM_fit: This works similar to the QP_output option, but any distance-coupling distribution can be provided in the electrode_coupling_file field (appears if this option is used). The format of the file provided should be distance in Angstrom in the first column and electronic couplings in eV in the second column.
    • parametrized: Couplings between nearest organic material and electrode are computed based on Miller-Abrahams rates using the electrode_coupling value as square-root of the prefactor and the value in the electrode_wf_decay_length field as inverse decay length (prefactor in the exponent of the Miller-Abrahams rates).
  • morphology expansion scheme: Morphologies can be expanded to run KMC simulations on layers that are larger than the morphologies used to compute microscopic input. There are three expansion schemes available:

    • lfx: Iterative boltzmann inversion to generate a site distribution with correct Radial Distribution Function. We recommend to use this option.
    • edcm: Extended dominance competition model. While this is slightly more robust than lfx, it does not work with highly isotropic densely packed molecules.
    • no expansion: If you wish to use the exact morphology provided in a morphology file/QP file (e.g. for Bulk Heterojunctions), use this option. Please note that layer dimensions in the device tab have to match the layer dimensions in the morphology file provided.

"topology" tab

  • max neighbors: Number of nearest neighbors to take into account for charge carrier and exciton dynamics.

  • transfer integral source: The options in this drop-down menue determine how transfer integrals (Js) between pairs of molecules are computed. There are three options available:

    • QP_output: Extract pair parameters from QuantumPatch output
    • QM_expansion: If enabled, three files can be provided for each pair of molecules below for hole, electron and Dexter transfer integrals. These files need to be formatted with the distances in Angstrom in the first column, and the coupling in eV in the second column.
    • Miller-Abrahams: This option computes transfer integrals using Miller-Abrahams formalism. If this option is used, the user needs to provide wave function decay lengths and a maximal values for transfer integrals for each pair of molecules in the pair parameters section below.
    • file: Supply couplings by loading a file via the field popping up. The file contains seven columns where the first and second entry of each line are the site ids of each pair, third and fourth entries are neglected and entries five, six and seven are coupling for holes, electrons and excitons (Dexter) respectively.
  • FRET: Here you have two options to supply rates for FRET processes:

    • automatically computed from material properties
    • use pairwise heuristic parameters.

    We recommend to go with the first option. For the second option, parameters can be supplied manually for each pair.

  • pair parameters: Use the plus-buttom to add as many pairs of materials as required. Every pair of materials that is connected in the device needs to be listed here. See this usecase as an example.

    • molecule 1 and molecule 2: Chose the identifiers as defined in the materials tab.
    • QP_output: For each pair, chose a QP output file identifyer (defined in the IO tab) to extract transfer integrals from QP runs. Make sure that Js were actually calculated in the respective QP run (see the QuantumPatch GUI for reference)
    • QP_output_coulomb: only available if doping is activated and coulomb_correcton_mode is QP. Chose a QP_output of a donor-acceptor CT-energy computation.
    • QP_output_coulomb_EAIP: only available if doping is activated and coulomb_correcton_mode is QP. Chose a QP_output of an EAIP calculation for the identical molecules which were calculated in the QP setup of QP_output_coulomb. This is used to compensate for systematic CT-energy error in DFT.
    • transfer_intergral_parameters: Provide either input files or parameters for Miller-Abrahams rates, if mode is not set to "QP_output" in the "transfer integral source" dropdown above.
  • prune transfer integrals: reduced number of effective neighbours. This can increase performance by factor 2 without lack of accuracy. Does not work if morphology_input_mode is set to QP_output: HL generator in the device tab.

"physics" tab

  • rates: Charge transfer rates can be computed using either Marcus, Miller-Abrahams or mixed-marcus formalism. There is also a new option "automatic" that automatically choses a mixed set of rates that works best for various processes.
  • superexchange: Enable second-order charge transfer via virtually occupied intermediate states. This option increases computation time, but also provides more accurate results.
  • dielectric properties: Here we have four options, the last of which are only enabled for simulations where CT energies are computed from QP (enable coulomb correction, coulomb_correction_mode=QP)
    • fixed permittivity: Constant permittivity defined in "epsilon material" below is applied to the full OLED
    • fixed distance dependent permittivity: Permittivity where screening is reduced for small pairs and approximates bulk permittivity (epsilon material) for far pairs. For this option a new setting "screening length" is displayed.
    • permittivity fitted to QP: If CT/coulomb binding energies are provided from QP for close pairs, material permittivity is fitted to coulomb binding energy computed with QP
    • distance dependent permittivity fitted to QP: With this option, screening is reduced for close pairs and both screening length and material permittivity are fitted to QP data.
  • epsilon material: Dielectric constant of the OLED. As of now, only a global parameter can be applied and we recommend to use 4.0, unless otherwise determined e.g. by QuantumPatch. This field may not be visible depending on the "dielectric properties" dropdown.
  • screening length: Required for distance dependent permittivity. This value is a measure for how quickly the dielectric constant goes from 1.0 to the bulk value provided above.
  • coulomb_correction: only available if doping is turned on. Allows to modify nearest neighbour coulomb interaction. In particular relevant for donor acceptor charge transfer, as classical coulomb interaction underestimates electron hole binding energy for intermediate distances and my overestimates it for very short distances.
  • coulomb_correcton_mode: only available if coulomb correction is turned on. Set to
    • constant: set nearest neighbour coulomb binding energy to value of coulomb_binding_energy.
    • QP: requires CT QuantumPatch calculation. Uses distributions of ab-initio Coulomb binding energies from Quantum Patch. If set, additional input sources for the QP CT output have to be supplied in the pair_parameter section of the topology tab.
    • cutoff: classical coulomb interaction with a maximum value defined by coulomb_binding_energy.
  • polarization_correction: only available if coulomb_correction_mode is "QP". Classical correction of coulomb binding energy from QP, to compensate the finite number of screening molecules in the QP calculation.
  • coulomb_binding_energy: see coulomb_correction_mode -> cutoff, constant
  • coulomb_binding_shift: only used if polarization correction is false. Shifts coulomb binding energy distribution by value in eV.
  • doping: Enables integer charge transfer between uncharged molecules. Currently does not work in combination with exciton dynamics simulations, however the exciton box needs to be checked in the general tab due to technical reasons.
  • show advanced: Enables the user to additionally set the following parameters:
    • doping_regeneration_steps: Refresh rate for bleached CT sites. Further documentation in progress. Default value sufficient for all values.
    • electrode_stack_distance: Change this value to account for injection effects at the electrode, e.g. tunneling through thin insulating layers.
    • electrode_J_scale: This enables the user to shift the coupling between organic material and electrode by X times the distance-dependent widht of the coupling distribution, where X is given in this field.
    • tta_rate: rate equation used for exciton quenching. Options are: "miller", "marcus" and "mixed-marcus". "mixed-marcus" is a Marcus rate without inverted regime.
    • td_scaling: if excitonics are set to "preset", transition dipoles are estimated from the lifetimes supplied in the preset. The transition dipoles are then used to calculate Foerster exciton transfer rates. td_scaling allows to modify the estimated transition dipole to reduce Foerster rates. The Foerster rate scales with the 4th power of the transition dipole.
    • ct_rate_memory_multiplier: Exciton quenching rates are by default cached for a maximum of 2000 particles per particle type. If your system has more particles, this settings allows to increase the size of the interaction cache.
    • n_injection_layer: by default the number of sites on which charge can be injected per elecrode is width(nm) x width(nm). To increase the number of injection sites to e.g. 150%, set this setting to 1.5. The sites closest to the electrodes are chosen.
    • ML_energy_environment: deprecated feature, do not use.
    • rate_scaling: allows to scale rates for some physical processes
      • charge_seperation: scales rates for excitons to seperate to bi-molecular electron hole pairs.
      • charge_injection: scales injection rates from electrodes.
      • ptq: scales dexter based charge exciton quenching.
      • dexter_spinflip: scales ct based spinflip rates.
    • mesh_scale: only relevant for amorphous systems with attached electrodes. These systems require a Coulomb grid for the long-range part of the Ewald-sum. This settings defines the grid spacing in x,y and z direction. The default grid resolution is 1.0 nm. For dense systems this should be increased at least in x direction. It can be computationally quite expensive to have a dense grid spacing.

"operation" tab

  • restart: Restart the KMC simulation from a previous KMC run. If checked, the restartfile (output of KMC) needs to be provided.
  • simulations: To get converged results with sufficient statistics, each "virtual experiment" should be performed multiple times. We recommend to start with a low value to check if all inputs are provided accurately, but perform 10 or more simulations for quantitative analysis.
  • measurement: There are currently three measurements available:
    • DC: standard DC run e.g. to compute material mobility or I-V / IQE of an multilayer device. See various tutorials for further information.
    • Photoluminescence: Run virtual PL experiments, e.g. as illustrated in the photoluminescence tutorial.
    • exciton_diffusion_length: Simulate diffusion of a single exciton in your material/device to compute exciton diffusion constants and PLQY without exciton-exciton and exciton-polaron interactions.
  • temperature: Device temperature in K.
  • field strength: Separated by spaces, supply values for the electric field in the KMC simulation, in V/nm.
  • initial holes and electrons: A fixed number of charge carriers can be assigned randomly on sites in the sample. This becomes especially relevant, if no electrodes are connected (e.g. during full PBC computations of bulk properties such as mobility), i.e. no charge carriers can be injected. The availability of this option depends on the particle_types settings in the general tab.
  • computational: Convergence criteria for LightForge runs. The simulation is either terminated, if the relative change of the I-V between subsequent simulation steps drops below the value supplied in the IV fluctuation field, if the number of steps reaches max_iterations, or if the physical simulation time reaches max_time (in s).
  • activate bond damping: Damps rates for back- and forth processes to increase simulation efficiency. This option should be activated, if test simulations show that most simulation steps are used on these rattle type processes, e.g. at interfaces or near electrodes. Use with care and for now only modify the following three values:
    • max bond noise: If activated bond damping affects physical results (such as current density), increase max bond noise.
    • max damp factor: If bond damping does not show any effect, increase this value, but do not exceed 0.35.
    • healing: increase this value along with an increase in max damp factor.

analysis tab

This tab contains advanced options for analysis of LightForge runs. Many options do only work in special cases and should not be enabled in standard runs. A detailed description on each option will follow shortly. The following figure contains the setup to analyze doping activation in doped (injection) layers.

The results of the search are