QuantumPatch Command Line Input Files

Introduction and general remarks

QuantumPatch currently supports input files in the simple yet extendible file format YAML. Sections and subsections in YAML are separated by whitespace indents, values are assigned with a colon :, followed by the value, e.g.:

System:
  Core:
    engine: TM core
    number: 250
    ...

The input file is comprised of four major sections QuantumPatch, DFTEngine, System, Analysis. The following chapters will each describe the setup of a QuantumPatch input file section to run QuantumPatch calculations with. If no settings.yml exists, a template with reasonable defaults is written into the current directory by calling the QuantumPatch executable.

All QuantumPatch inputs are given in the following unit system:

  • Distances/Cutoffs: Ångström [Å]
  • Charges: Elementary Charge [e]

Section: QuantumPatch

The QuantumPatch Section sets up the main QuantumPatch process settings. These are comprised of:

  • morphology: Path to the morphology (created by Deposit), in the CML format. We also support segmented XYZ files (one XYZ file after the other with a molecule identifier in the comment line) and correctly formatted PDB files. Considering that both standards are very fragile especially in the case of large systems, CML input is very much recommended. CML.gz is also supported.
  • type: Type of QuantumPatch run to be executed. Possible inputs are:
    • uncharged_equilibration: Default option. Standard polarized run. Equilibrates charge cloud and calculates disorder.
    • matrix_eaip: Calculates electron affinities (EA) and ionization potentials (IP) in environment. This option should also be set to compute charge transfer activation energies.
  • dimer_cutoff: Defaults to 7.0. Maximum nearest atom distance of a neighboring molecule to be recognized in dimer calculations (for transfer integrals, see calculateJs).
  • number_of_equilibration_steps: Maximum number of charge cloud relaxation steps.
  • charge_damping: Defaults to 0.15. Damps the change of the charge field with each new iteration to lead to smooth convergence (similar to SCF DIIS damping). Increase this, if you observe charge oscillations between iterations. A large value requires more equilibration steps.
  • partial_charge_cutoff: Defaults to 60. Maximum distance for Coulomb cloud point charges to be considered.
  • calculateJs: Defaults to false. Determines whether a full dimer calculation run to retrieve site couplings is carried out.
  • chargetype_multipoles: Option under development, do not use in production yet. This option allows Turbomole to pass on also calculated multipoles between iteration steps and not only partial charges.

Section: DFTEngine

General Engine setup

This defines the DFT Engines used in all QuantumPatch calculations. QuantumPatch supports an arbitrary number of DFT engines. It is also possible to create multiple engine setups for the same underlying DFT code, as long as the given names are unique. There are useful defaults in a settings file which can be modified. More sophisticated engine setups are discussed in this chapter. Regarding the internal engine options please consult the DFT Engines chapter of this manual.

QuantumPatch has a default engine setup in every automatically produced settings file:

DFTEngine:
  defaults:
    DFTBplus:
      charge_model: cm3
      engine: DFTBplus
      threads: 1
    Dalton:
      basis: def2-SVP
      charge_model: ESP
      engine: Dalton
      functional: BP86
      memory: 1500
      threads: 1
    Psi4Engine:
      basis: def2-SVP
      charge_model: ESP
      engine: Psi4Engine
      functional: BP86
      memory: 1500
      reference: rdft
      threads: 1
    Turbomole:
      basis: def2-SVP
      charge_model: ESP
      engine: Turbomole
      functional: BP86
      memory: 1500
      threads: 1

These default definitions are not used by any calculation and are present inside the settings file for reference only. To use a specific engine in your QuantumPatch run, copy&paste the respective engine-settings-block into the and adapt as required, e.g define a multithreaded Turbomole-core engine with b3-lyp/def2-SVP by adding the following block to the DFTEngine settings:

DFTEngine:
  defaults:
    DFTBplus:
      charge_model: cm3
      ...
  user:
    TM core:
      basis: def2-SVP
      charge_model: ESP
      engine: Turbomole
      functional: B3-LYP
      memory: 6000
      threads: 4

Each type of engine (Turbomole, DFTB+, Dalton, XTB, PSI4) has unique properties. Custom DFT engines have to be defined by unique names in it's defining line, defaults are DFTBplus1, Turbomole 1, and Psi4Engine 1. Then define/adapt the following properties:

  • engine: Turbomole, DFTBplus, Dalton, XTBEngine, Psi4Engine
  • charge_model: ESP/mulliken for Turbomole, Dalton and Psi4; CM5/mulliken for DFTBplus and XTBEngine
  • threads: increase if you have sufficient resources (more than parallel DFT jobs in a single iteration) or if some DFT jobs will run much longer than others (e.g. expensive settings in the core shell)
  • fallback: Provide the unique name of the engine here. Further explanation and an example is given below.
  • scf_convergence: Only for Turbomole engines. Set to normal, extreme or superextreme In Turbomole and Psi4, basis set and functional have to be set in addition.

Fallback engines

Every DFT engine also allows the specification of a fallback, e.g. with different DFT-engine or different convergence settings. Please note that number of threads and memory needs to match between engine and its fallback.

To define a fallback with same settings and different convergence, simply do as follows:

DFTEngine:
  user:
    Turbomole 1:
      engine: Turbomole
      basis: def2-SVP
      functional: BP86
      threads: 1
      memory: 1500
      reference: rdft
      charge_model: ESP
      fallback: Turbomole 1 Fallback
    Turbomole 1 Fallback:
      keysfrom: DFTEngine.defaults.Turbomole
      scf_convergence: extreme

In case a simulation calculated using Turbomole 1 fails, the simulation is rerun using Turbomole 1 Fallback.

Another example is a system with only a few molecules containing elements that are not compatible with DFTB, e.g. for doped systems where the host consists of only organic elements. In this case, DFTB in the outer shells would crash and Turbomole would be required for all environment molecules, leading to increased computational costs. Instead, you can define a fallback engine for DFTB:

DFTEngine:
  user:
    TM FB:
      basis: def2-SVP
      charge_model: ESP
      engine: Turbomole
      functional: B3-LYP
      memory: 6000
      threads: 4
    DFTBplus:
      charge_model: cm3
      engine: DFTBplus
      threads: 1
      fallback: TM FB

In this case, DFTB would be run successfully on host molecules in the environment, and only for a couple of dopants the fallback would kick in.

Please note that by default these DFT engines are defined in the exemplary output generated by QuantumPatch. If no fallback is specified, non-converged simulations lead to a QuantumPatch exit.

Section: System

The system section defines the shell setup of a QuantumPatch run, i.e. defines which molecules are part of the core shell (and in which molstates the core molecules are computed), how large the environment shells are and which engines are applied in each shell. The System-part of the settings file has four subsections described below:

System:
  Core:
    ...
  Identical Molecules:
    ...
  MolStates:
    ...
  Shells:
    ...

Core Shell

The core shell of the system is the most integral part of your simulation. It strongly influences the quality of your output and enough staticstics and accuracy will be important to yield reliable results. It is set up as follows:

System:
  Core:
    GeometricalOptimizationSteps: []
    default_molstates: 0;1
    engine: TM core
    engine_by_iter: {}
    number: 250
    type: number

These settings define:

  • type: There are different possibilities how to define molecules of your core shell.
    • number: Chooses the given number of innermost molecules as the core shell
    • number_by_type: For a mixed morphology, core shell will be defined by N molecules of each species.
    • random_molstate_pairs: Number of random pairs from the morphology.
    • random_molstate_crosspairs: Number of random pairs from a mixed morphology, with two different molecules in each pair.
    • distance: Defines a box with cutoffs in both positive and negative direction from the middle of the box in x, y, and z coordinates, i.e. a cutoff of 10 Å in the each coordinate will create a cube with side lengths of 20 Å around the center of the morphology.
    • list: Gives the user the most control over defining a core shell by assigning list of molecule identifiers (IDs) within the morphology to a certain molecular state.
  • number: Add this settings for type: number, number_by_type, random_molstate_crosspairs and random_molstate_pairs
  • list: If type: list, specify an additional parameter labeled list containing a string argument. List strings are separated with the pipe | symbol, each section separated by pipes will describe a separate QuantumPatch simulation. Molecule IDs within one list are separated by a semicolon ; while ranges can be defined by a dash -. For example, if MolState 0 is applied to molecules 0, 1, and all molecules from 21 to 36, the list entry would be: molstate.0: 0;1;21-36 | .... As an example, if the list is defined by molstate.0: 1-100 | molstate.1: 1-100 | molstate.2: 1-15, it will cause QuantumPatch to first calculate molecules 1 to 100 all in MolState 0, then to start a new run with molecules 1 to 100 calculated in MolState 1, then a new run is executed with now only molecules 1 to 15 being put into MolState 2.
  • distance: If type: distance is used, provide an additional setting distance with sub-settings cutoff_x: X, cutoff_y: Y and cutoff_z: Z with X,Y,Z being distances in Angstrom from the edge of the box. Aside from the method to determine the core shell, the user has to define which engine to use. Here it will be sufficient to supply the engine name, not the whole path to the engine definition, e.g. Turbomole 1 Finally, the default_molstates option is used for defining which MolStates will be calculated with the core molecules in the case of number and distance specification. Mind that each molecule in your MolStates will be calculated separately. Again, this list is separated by a semicolon ; for each MolState number. It does not apply in an uncharged_equilibration simulation. Here every molecule is calculated in a non-excited not-charged singlet groundstate.
  • engine: Specify the engine as defined in the DFTEngine-section of the settings file
  • engine_by_iter: With this setting you can use different engines (e.g. different DFT settings) in different iteration steps of QuantumPatch. A prominent example is to equilibrate the charge cloud using a computationally efficient DFT setup, and evaluation properties on core molecules with a more refined setup in the last iteration. This can be achieved as follows:
DFTEngine:
  user:
    TM core:
      basis: def2-SVP
      charge_model: ESP
      engine: Turbomole
      functional: B3-LYP
      memory: 6000
      threads: 4
    TM core last iter:
      basis: def2-SVP
      charge_model: ESP
      engine: Turbomole
      functional: B2PLYP
      memory: 6000
      threads: 4
...
System:
  Core:
    GeometricalOptimizationSteps: []
    default_molstates: 0;1
    engine: TM core
    engine_by_iter:
      LastUncharged: TM core last iter
    number: 250
    type: number

Please refer to the definitions of the engines by iteration below for further information.

Shells

The shells surrounding the core shell are defined here. There can be as many shells defined as the user wishes. There are three settings that define a shell:

  • cutoff: The cutoff defines the radius of the shell around the lower lying shell.
  • engine: Which DFT engine should be used for the given shell
  • engine_by_iter: The DFT Engine can be overriden on a specific step.
  • type: Can be either of two types
    • scf: SCF shells are included in the equilibration of the charge cloud and will be recalculated with a new charge cloud each iteration. These types of shells should be inner shells.
    • static: Static shells will be calculated in the first iteration and the charges will be fixed for the rest of the run. Usually static shells are used as the outermost shell of the setup.

Each shell is identified by a number in the input file which will also be used to refer to the shell in QuantumPatch log files, e.g.:

    '0':
      cutoff: 25.0
      engine: DFTBplus 1
      engine_by_iter: {}
      type: scf

The engine_by_iter functionality is advanced and does not need to be used a-priori. It allows for optimization of runtime by switching to DFT only in the later steps for example. Steps can be refered as either as an integer id or as a named step (highly recommended). Review the names of iteration steps section further above for names. The syntax is then:

    '0':
      cutoff: 25.0
      engine: DFTBplus 1
      engine_by_iter: { 'LastUncharged': "Turbomole 1", "LastCharged": "Turbomole 1" }
      type: scf

to switch to the Turbomole 1 engine in the LastUncharged and LastCharged steps.

Molecular States

Molecular state definitions are required (short MolStates) for polaron or exciton runs and their subtypes EA/IP, Lambda and Emission/Absorption runs, and ignored for uncharged equilibration runs. More exact, molecular states (MolStates) are defined for runs that involve excited state calculations or charged molecules. There can be as many MolStates as wanted with enumeration of each MolState serving as a means to assign the state to molecule types. Settings for MolStates are:

  • charge: Net molecular charge.
  • multiplicity: Molecule spin multiplicity as an integer, i.e. singlets are 1, doublets are 2, triplets are 3.
  • excitation_of_interest: The excitation geometry relaxations will be carried out in. Has to be > 1 for excited state simulations.
  • roots: Number of roots (number of excited states) to be considered by the excited state simulation. Should be at least 5+excitation_of_interest

Section: Analysis

The recommended settings for this section depend strongly on the type of calculation you wish to perform and some are listed in the following:

MatrixEAIP Analysis

MatrixEAIP calculates a double counting correction in a specified radius. This radius should be at least big enough to carry the nearest atom neighbours. A good rule of thumb is at least 12 to 15 Angströms. Make sure to setup a SCF shell with the same radius to not waste computational time. This shell has to have a Turbomole DFT engine in the LastCharged and LastUncharged steps. QuantumPatch simulations will not start unless this condition is met.

Analysis.MatrixEAIP.do_lambda leads to two changes to the simulation. In the FirstUncharged and FirstCharged steps geometry relaxations are carried out using the geo_opt engine. Also two final steps are carried out to allow the calculation of the reorganization energies.

homo_lumo_generator

In a disorder run, you can enable the analysis below to compute HOMO/LUMO distributions 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.

  homo_lumo_generator:
    coulomb_cutoff: 25
    enabled: true
    non_PBC_morphology: structure.cml
    periodic_copies: [2, 2, 1]
    swap_x_z_axis: True
    esp_avrg_options:
      bins_per_nm: 1.7
      mode: by_distance
      z-extend: true

A good explanation is also given in the respective WaNo documentation with the following mapping of names in the GUI and settings listed above: | WaNo documentation name | setting in the yaml-file |

z-Rotation swap_x_z_axis
non PBC structure non_PBC_morphology
Periodic copies periodic_copies
ESP average options esp_avrg_options
Distance binning mode: by_distance (any other string than by_distance will turn distance binning off
Bins per nanometer bins_per_nm
Include copies for engiornment in z-direction z-extend

Names of iteration steps

Usually all QuantumPatch iterations are numbered from 1 to the preferred number of equilibration steps. Important steps in the simulation are also named to be able to reference them a-priori without calculating the absolute step number before the simulation.

The step numbers are:

  • uncharged_equilibration:
    • Vacuum
    • FirstUncharged
    • LastUncharged
    • Dimer (in case a dimer simulation is carried out).
  • matrix_eaip
    • Vacuum
    • FirstUncharged
    • LastUncharged
    • FirstCharged
    • LastCharged
    • LambdaUnchargedGeometryChargedEnv (in case of reorganization energy simulation)
    • LambdaChargedGeometryUnchargedEnv (in case of reorganization energy simulation)
  • excitonic_preprocessing
    • Fluroescence
    • Phosphorescence
    • TTA
    • TPQ

Previous: QuantumPatch Usage | Next: DFT Engines

The results of the search are