QuantumPatch GUI


The QuantumPatch WaNo is the general entry point to compute the electronic structure of organic thin films e.g. from Deposit using a self-consistent iteration of quantum chemistry calculations. This electronic structure information can then be used to compute rates for microscopic electronic and excitonic processes for simulating charge carrier and exciton dynamics with LightForge KMC. Since the simulation of different processes requires information on different electronic molecular properties, QuantumPatch offers a wide range of Options. The most common applications are:

  • Calculation of HOMO and LUMO level distributions and electronic couplings of the uncharged morphology, the so called disorder, required for any charge transport simulation (QuantumPatch Mode: Polarized / uncharged_equilibration).
  • Calculation of electron affinity (EA) and ionization potential (IP) of molecules embedded in a thin film, while taking into account the influence of the electrostatic environment (QuantumPatch Mode: Matrix EAIP / matrix_eaip).
  • Calculation of reorganization energy of molecules in the charged environment, required for charge transport simulations (QuantumPatch Mode: Matrix EAIP / matrix_eaip)
  • Calculation of EA and IP and reorganization energy of molecules in-vacuo without any taking into account environmental effects, either to provide quick estimates or to analyze the influence of the environment (e.g. for different guest-host combinations) by comparing to EA/IP values computed with the Matrix EAIP mode.

The QuantumPatch GUI consists of four tabs: General, Engines, Shells, LambdaEAIP, which we will go through one by one in the following.

General Tab Enginges Tab
Shells Tab Lambda EA IP Tab
Post processing

General Tab

General Settings:

  • Morphology (CML): Import CML file from Deposit simulation, either from your hard drive or from the Deposit WaNo preceding QuantumPatch in the Workflow. This morphology can either be a pristine or mixed morphology, an interface, or even a small multilayer stack.
  • Run QuantumPatch: This can be disabled if one is only interested in the in-vacuo calculations. Disabling this option means to not take into account the effect of local environment on computed properties.
  • QuantumPatch Type: This selection specifies what type of QP simulation is executed;
    • Polarized: Use this option to only compute the energy disorder (the width of HOMO and LUMO level distributions) for charge transport simulations and electronic couplings (see Calculate Js below). Note that the absolute values of HOMO and LUMO orbital energies are not the electronic transport levels.
    • Matrix EAIP: Computes absolute charge transport enegy levels (EA and IP), e.g. when you wish to analyze energy level alignment in a guest-host material or at an organic-organic interface. In this mode, individual molecules (as defined in the shells tab) will be charged and their electrostatic environment is relaxed to respond to this additional charge. The energy difference between charged and uncharged system (meaning the charged molecule AND the electrostatic environment) is computed, providing EA or IP. Note that, depending on whether or not "Include in-matrix Lambda Calculation" is checked or not (see below, only works for DFTB+ compatible compounds) an additional geometry optimization of the charged compounds in their local environment is performed, which may change EA/IP values sligthly.
    • Polaron: This mode is an older approximation to Matrix EAIP and does a charged equilibration, but currently does not do another analysis and is not recommended anymore.
  • Calculate Js: Compute electronic couling between neighboring molecules, e.g. for transfer rates applied in KMC device simulations. Only applicable in Polarized / uncharged_equilibration simulations.
  • Higher Order Js: Selecting values other than 0 includes more orbitals in the coupling calculation and increases the calculation time considerably. More information about the additional calculations can be found here
  • Include in-vacuo Lambda/EA/IP Calculation: Enable EA-IP and reorganization energy (lambda) calculation of molecules in vacuum. Single molecules are extracted from the provided structure and charged/uncharged (and their geometry relaxed in the case of lambda). As this does not take into account the electrostatic environment, you can disable the "Run QuantumPatch" checkbox above. Note that EA and IP values are not quite reliable and that lambdas are usually overestimated in this approach.
  • Include in-matrix Lambda calculation: This option is only enabled for the Matrix EAIP mode and only works for DFTB+ compatible compounds. Here the reorganization energy is computed by optimizing the charged molecular geometries in their unique local environment, instead in vacuum. As the surrounding molecules limit the geometrical reorganization, the in-matrix lambda values tend to be smaller but more accurate than the in-vacuo lambdas.
  • Charge Damping: This parameter is used in the SCF iterations of the partial charge calculations. We recommend to use 0.15. It regulates how much the last iteration can influence the next one, to overcome an oszillation around the correct charges.

scf iterations used for new partial charge calculation for all atoms

Molecular states

This segment will only have an impact on EA/IP and Polaron simulation and is ignored in the Polaron mode. For each Molecular State (default to +1 and -1 charge, and no excitations) a equilibration (of the elctrostatic environment of the charged molecules) will be carried out. Every Molecular state is defined by

  • Charge: Charge of the molecules, set to -1 for electrons (EA computation) and +1 for holes (IP computation). If you want to compute both EA and IP, define two separate molecular states, one with -1, one with +1
  • Multiplicity: Multiplicity of the molecular state. Set to 2 for both charge +1 and -1.
  • Excited State of Interest: In order to compute properties of an excited molecule in a matrix, define the excited states of interest here. Leave at 0 for simply compunting EA, IP or lambda.
  • Number of Roots: Number of excited states considered in the DFT calculations. Leave this at its default for most QuantumPatch usecases.


About Engines

As you may know, QuantumPatch conducts a large number of quantum chemistry runs on single molecules. For these quantum chemistry computations, so called Engines are used. The properties of the engines (such as basis set, functional, etc) are defined in this tab. Note that the definition of a QuantumPatch engine does not imply its actual use - the assignment of the DFT engine towards its respective shell and step happens in a shell tab, using the specific identifyer defined in the respective Name field. You can find a description of QM engines in the following and here. Note that this way multiple engines using the same implementation (e.g. Turbomole) but having different settings (e.g. functionals or convergence criteria) can be defined to use fast methods where possible and accurate methods where neccessary during throughout the QuantumPatch iteration.

Engine settings

Please note that not all engines possess all settings.

  • Partial Charge Method: Choose ESP here. Mulliken is another option.
  • D3(BJ) Dispersion Correction: in case of geometrical optimizations this will allow dispersion corrections added to the DFT evaluation. In case of single points, leave off.
  • SCF convergence: normal, tight, extreme. Three presets to allow for better convergence of DFT settings. Normal: Less iterations, fast calculation, tight: better convergence. extreme: possibly long runtime, convergences well.
  • Threads: Per DFT-calculation threads: The number of Threads has to be set lower than the number of cpus set per node on the Resources pane. DFT calculations are only parallelized on a single node via either SMP or MPI.
  • Memory: Per DFT-calculation memory. The total memory per Node has to be smaller than the maximum parallel DFT calculations.

Every DFT Engine also has the option of a Fallback, which will run a second DFT simulation in case the first one does not converge. A good idea is for example to setup two identical DFT engines Turbomole 1 and Turbomole 1 Fallback and set the scf_convergence to normal in the first one and to extreme in the second one to assert convergence.

For most use cases, one DFTB+ engine and one Turbomole Engine is required. We recommend the following settings for users not too familiar with quantum chemistry:

  • Turobomole: Use b3lyp as functional and def2-SVP as basis set. Multithreading of the enginge is recommended only if this engine is used for core molecules in an EA/IP run. Give it a unique name, e.g. "Standard Turbomole"
  • DFTB+: Use CM3 as partial charge method and leave the rest as pre-set. Check the Fallback checkbox and choose your "Standard Turbomole" engine as Fallback engine. In case DFTB+ does not converge (e.g. in case some atom types of your compound are not supported by DFTB), QuantumPatch will re-run this computation using the Fallback engine.


As "shells" we label different parts of the morphology. Some parts, often the innermost part or just an individual molecule, are used to actually compute properties of interest, while other parts, e.g. the molecules surrounding this "core shell", are only used tp account for the correct electrostatic environment of the core shell. This "outer shell" can be further devided into a part where the electronic structure of the molecules is relaxed self-consistently over several iterations, and a static part farther away from the core. To each shell, one engine as defined in the Engine tab is assigned. The section on DFT Enginges provides an illustration of the respective shells.

Core Shell settings

The core shell contains all molecules on which the properties of interest are finally computed (energy disorder, Js, EA, IP, lambda, ...).

  • Screened Iterations: Number of self-consistent iterations which will be carried out. We recommend 7 iterations for standard use cases.
  • Inner Part Method: There are different methods to define the "core shell" of your structure.
    • Inner Box Cutoff: Cuts X Angstrom from the sides of a rectangular morphology. A value of cutoff x = 10 and a bounding box of 100 Angstrom will leave a box of 80 Angstrom.
    • Number of Molecules: Take the innermost N molecules. To compute energy disorder and electronic couplings, we recommend to use this option with N>=150. To compute mean values of EA, IP and Lambda with acceptable accuracy in pristince morphologies, use this option as well but limit yourself to 10 molecules, as the Matrix EAIP mode performs N individual relaxations of the electrostatic environment.
    • List of Molecule IDs: Specify the list of molecules and the respective molecular ids manually. This is useful to analyze properties on specific molecules, e.g. guest molecules embedded in a host material. Lists are given in the following format: molstate.0: 0-55;77;263 | molstate.1: 43;57;79-100. This means that first the first list will be simulated using molstate.0 and then the other list using molstate.1 Ranges are [inclusive,exclusive).
    • Number of Random Pairs: Selects N random molecule pairs in the morphology. The pair serach is started in the middle of the morphology and the default distant value of maximal 7 A is used to define two molecues as pair.
    • Number of Random Crosspairs: Selects N random number of molecule pairs, which do not have the same type, e.g. dopants and hosts.
    • Number of Molecules of each Type: Same functionality as Number of Molecules with an extension to do it for each type of molecules, present in the morphology.
  • Default Molecular States: Run the self-consistent iteration for these molecular states (in the order as defined in the general tab).
  • Used Engine: Name of the engine during the self-consistent iteration, as defined in the Engines Tab.
  • Different Engine on Last Iteration: It may be useful to equilibrate the electronic structure with one engine (e.g. DFTB or Turbomole with a medium-size basis or functional), but employ a different and computationally more expensive engine (e.g. with a larger basis set) in the last iteration step to actually compute desired quantities. If this box is checked, a second drop down menue will appear to set this Last Iteration Engine.

Outer Shell settings

To attain sufficient accuracy for quantities computed on molecules in the core shell, we recommend to set up a second self-consistent shell around the core shell has to be setup, in addition to a third outermost shell which only contains vacuum partial charges of the molecules. As for the core shell, a DFT engine has to be assigned to each sell. Further, a cutoff radius and the information, whether it should be self-consistently relaxed (Shelltype: scf) or only calculated in the vacuum state (Shelltype: static) needs to be supplied. A different engine on the last iterations can be specified too, same as with the Core Shell settings.


  • Polarized runs: To compute energy disorder and electronic couplings, DFTB+ engines can be used for both outer shells (if the molecules are supported, see above). We recommend a Cutoff Radius of 25.0 Angstrom for the first, dynamic outer shell and 60.0 Angstrom for the second, static outer shell. For the core shell should recommend to use Turmobole with b3-lyp and def2-SVP at least in the last iteration (and DFTB+ before). Remember to define the Turbomole engine as fallback engine for the DFTB engine, in case your molecules are not supported by DFTB (see Engines tab).
  • Matrix EA/IP run: In this case, a total of four shells are recommended: (i) the core contains only the charged molecule (remember: one full QP run is performed per charged molecule in the "core shell", while the rest is neutral) (ii) a small self-consistent DFT shell (10A) (e.g. with Turbomole engine) as the polarization effect is stronger if a charge is present and DFTB may underestimate this (iii) a larger self-consistent shell using DFTB+ (25A) and (iv) a static DFTB+ shell as above (60A). As DFT computations on charged center molecules run longer than on neutral compounds, you may want to consider to define different DFT engines for (i) and (iv) that both use Turbomole with the same settings, but using ~10 threads in the core shell.

LambdaEAIP settings

This tab allows settings for the in-vacuo Lambda and EA IP calculations. If you require higher accuracy, please conduct a complete Matrix EAIP calculation.

  • Calculate Lambda: Calculate reorganization energies.
  • Lambda Type: Holes, Electrons, both
  • Calculate EA/IP: Calculate EA and IP in a vacuum approach.
  • Vertical EA/IP: Do a vertical transition without extra geometrical optimization.
  • Engine for geometrical Optimization: Engine for geometry optimizations.
  • Engine for single points: Engine for single points


In this tab you can enable additional post-processing of the QuantumPatch output, e.g. to create input for specific types of LightForge runs.

  • Compute exction disorder in last iteration: With this option checked, QuantumPatch evaluates excitation energies in addition to ground state energies in the last iteration on the core molecules and computes exciton disorder for LightForge. Please note that enabling this option will produce many warnings printed in the progress.txt file in the runtime directory, due to global molecular states being overwritten by molecular states defined in the engine of the last iteration.

  • Predict site energy distribution: Compute HOMO and LUMO energies of all molecules in the full morphology taking into account their unique electrostatic environment, based on partial charges extrapolated from molecules in the core-shell. Additonally, center of mass and nearest atom distances between neighboring molecules are evaluated for later usage in LightForge. Additional options are:

    • z-Rotation: This will rotate the final morophology after the expansion and exchange z- and x-direction. This is required if you wish to align the deposition axis (z-axis in Deposit) with the charge transport axis (x-axis) in LightForge, e.g. for a slab interface. If you wish to analyze transport along the x-axis, so perpendicular to the deposition axis but with neat periodic boundaries, keep this option unchecked. Therefore, check the axis for deposition, the axis along you want to analyze the structure.
    • non PBC Structure: Provide the non-PBC morphology labeled "structure.cml" from the same Deposit run used to generate the morphology (normally labeled "structurePBC.cml") provided in the "General" tab.
    • Periodic copies: This will define the number of copies created in th x-,y- and z-direction. Periodic extension in z-direction should not be applied for slab-interfaces. Note that this step may define the sample size in LightForge: For deposited samples with a width of 10nm (Lx=Ly=50) and hight of 12nm, extension by 3,2,2 and z-Rotation turned off generates a system of 30x20x24nm, where 30nm is then the layer thickness in the LightForge run.
    • ESP average options:
      • Coulomb cutoff: This cutoff is applied when computing HOMO/LUMO level shifts induced by neighboring partial charges.
      • Include copies for environment in z-direction: If enabled, z-periodicity is enforced (even for Periodic copies in z-direction=1) to generate environment for molecules at the top and bottom of the morphology for HOMO/LUMO prediction. This makes sense for homogeneously mixted systems and should be disabled for interface morphologies.
      • Distance binning: Especially at interfaces, molecules far from the interface may be polarized differently than when close to the interface. This option maps electrostatics of molecules of a specific species in respect to their distance from the other species.
      • Bins per nanometer: Determines how fine the distance binning is.

Further details about this analysis, additional options and how to perform it for an already finished QuantumPatch run are described here.

Parallelization and Performance:

For every option not checked in the Resources tab, the server defaults that depend on your HPC machine will be used. Check individual options to modify specific values.

Recommended resources for QuantumPatch: A standard polarization calculation including transfer integrals with 100 inner molecules and 7 iterations will take about 500 CPU*hours for alpha-NPD sized molecules using SVP basis sets and a GGA exchange-correlation functional depending on your hardware. Allocate as many CPUs as you want to afford to reduce calculation time. 100 CPUs would mean a calculation time of roughly 4 hours.



The results of the search are