DIALECT

The DIALECT(DIAbatic Locally Excited and Charge-Transfer states) software was designed to calculate the excited state properties and exciton dynamics of large molecular systems, including strong light-matter interactions between microcavities and molecular assemblies. It is developed in the group of Prof. Dr. Roland Mitrić at the University of Würzburg.

This short documentation provides guidelines for the installation and use of the DIALECT software.

Getting Started

The installation and the software requirements of the DIALECT program are explained in the following part of the documentation.

Using pre-compiled binaries

A precompiled binary of DIALECT, which was compiled using github actions, is provided with the release on github.

The use of the pre-compiled binaries requires the installation of certain libraries on your computer.

GCC

As the pre-complied binaries are dynamically linked against the GCC library, it has to be installed on your system. An example for the installation of GCC on a Debian or Ubuntu machine is shown here.

sudo apt-get install gcc

Compiling the code

If you want to compile the program from source, you need to install additional programs and libraries.

Rust

Of course you need the Rust programming language itself to compile the code. The installation is explained in detail on the official site.

CMaKe

To compile certain Rust packages, you also need to install cmake.

sudo apt-get install cmake

Gfortran

In addition, the Gfortran compiler must be installed.

sudo apt-get install gfortran

Open-SSL

You need Open-SSL as some used Rust libraries depend on it. You can follow the guide shown here to install Open-SSL on linux.

Linear Algebra Libraries

To be able to compile and run the DIALECT program, it is necessary to download a linear algebra package as a requirement for the ndarray_linalg rust crate. You can choose between Intel MKL, OPENBLAS or Netlib by changing the features of ndarray_linalg in the Cargo.toml file according to the documentation (github page). In our experience, the intel MKL library yields the best performance.

Per default, the Cargo.toml files of DIALECT configure the ndarray_linalg create with "openblas-static", which should download and compile the OPENBLAS library and link it with the DIALECT package.

If you want to use the linear algebra packages that are already installed on your system, you need to change the feature of ndarray_linalg in the Cargo.toml files to "openblas-system", "intel-mkl-system" or "netlib-system".

The instructions for the installation of the libraries are provided in the following section.

Installation of LINALG packages

Intel MKL

If you want to compile DIALECT from source using the intel MKL as the linear algebra package, you will need to install it according to the following steps.

You can just download the MKL library from the Intel webpage and after the installation the environment variable $MKLROOT must be set with the setvars.sh script, which is located in the root installation directory of MKL.

source /path/to/MKL/setvars.sh

In the case of the older versions you have to execute the mklvars.sh script that is located in the installation directory of the MKL Library.

source /path/to/MKL/mklvars.sh intel64

OPENBLAS/Netlib

If you want to use OPENBLAS or netlib as the LINALG library, you need to install the BLAS and LAPACK libraries with the package manager of your operating systems.

sudo apt-get install libopenblas-dev
sudo apt-get install libblas-dev
sudo apt-get install libatlas-base-dev 
sudo apt-get install liblapack-dev

Mac users

In case of Mac users that have an apple silicon based processor, we recommend the compilation of DIALECT in conjunction with the accelerate framework.

A few changes to the Cargo.toml files are neccessary to compile DIALECT with accelerate:

ndarray-linalg = { version = "0.16", default-features = false }
blas-src = { version = "0.8", features = ["accelerate"] }

In addition, a build.rs file that contains the following line

fn main() {println!("cargo:rustc-link-lib=framework=Accelerate")}

must be created in the src folders of the DIALECT package and the dialect dynamics subpackage in order to use the accelerate framework.

Installation

There are multiple ways to install DIALECT. Choose any one of the methods below that best suit your needs.

Pre-compiled binaries

An executable binary for linux x86 operating systems is available for download on the GitHub Releases page. Download the binary and add the directory of the executable to your PATH. For some calculations (like the computation of cube files), the environment variable DIALECT_SRC_DIR must be set to the path to the DIALECT source code. Thus, the DIALECT code from github is also neccessary.

Build from source using Rust

Once you have installed Rust, you need to download the source code of the latest release of DIALECT from the GitHub Releases page. After extracting the source code, change into the new directory

cd DIALECT-rs

and build the executable with the package manager Cargo

cargo build --release

The option --release enables all optimization during the build and ensures fast runtimes, but can result in very long compile times. If you want to compile often e.g. in the case of debugging, then it makes sense to just execute

cargo build

To be able to execute the DIALECT programm you should set DIALECT_SRC_DIR to the installation directory and you can add the binary path to your PATH environment variable.

Running the program

This part of the documentation provides a guide for the user on how to do a calculation with the DIALECT program and how to configure the program settings.

Program settings

To configure the settings for a calculation using the DIALECT program, the file dialect.toml has to be created. You can either create the file yourself or you can run the program in a directory without the configuration file:

/your/path/to/DIALECT/dialect file.xyz

The dialect.toml will then be created using the standard values of the program. The settings of the file dialect.toml are explained in the following sections.

General Settings

jobtype = "sp"   # Type of calculation. Options:
                 # - "sp" (single-point energy calculation)
                 # - "opt" (geometry optimization)
                 # - "grad" (gradient evaluation)
                 # - "hessian" (Hessian matrix calculation)
                 # - "dynamics" (molecular dynamics)
                 # - "monomer_identification" (get the monomer index that corresponds to atomic coordinates)
                 # - "initial_conditions" (Wigner sampling for dynamics)
                 # - "polariton" (exciton-polariton simulation)
                 # - "tdm_ehrenfest" (create the TDMs and/or particle and hole densities along a trajectory of Ehrenfest FMO-LC-TDDFTB)

verbose = 0      # Level of printed output:
                 # - -1: minimal output (silent mode)
                 # -  0: normal/default verbosity
                 # -  1: verbose mode (some debug info)

Tight-Binding Method Options

[tight_binding]
use_dftb = true                  # Enable standard DFTB method (density-functional tight-binding)
use_xtb1 = false                 # Use GFN1-xTB method instead of DFTB (as of now, only ground state properties are supported)
use_gaussian_gamma = true        # Use Gaussian functions to model the gamma matrix (Coulomb interaction); set to false for Slater functions (as most DFTB parametrisations employ Slater functions, we recommend to set this option to false for esternal Slater-Koster parameters)
use_shell_resolved_gamma = false # Allow different Hubbard parameters for different orbital types (s, p, d) instead of one uniform value per atom

Fragment Molecular Orbital (FMO) Settings

[fmo]
use_fmo = false           # Enable FMO method for fragment-based calculations
vdw_scaling = 2.0         # Controls fragmentation behavior:
                          # - Higher values lead to looser fragment pairing
                          # - Controls the number of monomer pairs and ES-DIM pairs

Molecular System Information

[mol]
charge = 0                # Total charge of the system
multiplicity = 1          # Spin multiplicity. Currently, only singlet (1) is supported

SCF Convergence Criteria

[scf]
scf_max_cycles = 250           # Max number of iterations in the self-consistent charge (SCC) loop
scf_charge_conv = 0.00001      # Convergence threshold for charge density between SCC steps
scf_energy_conv = 0.00001      # Convergence threshold for energy between SCC steps

Long-Range Corrections

[lc]
long_range_correction = true   # Apply long-range correction (important for accurate CT excitation energies)
long_range_radius = 3.03       # Radius for applying long-range corrections (in au)

DFTB3 Parameters

[dftb3]
use_dftb3 = false               # Enable DFTB3 (third-order corrections)
use_gamma_damping = false       # Use damping for gamma matrix
hubbard_derivatives = [1.0, 1.0] # Values of the derivatives of the Hubbard U w.r.t. charge for each element (ordered by Z)

Geometry Optimization Options

[opt]
state_to_optimize = 0                  # Electronic state to be optimized (0 = ground state)
geom_opt_max_cycles = 500             # Max number of optimization steps
geom_opt_tol_displacement = 300.0     # Tolerance for geometry displacement, 300 * 10^-6 as default
geom_opt_tol_gradient = 1200.0        # Tolerance for gradient norm (controls convergence), 1200 * 10^-6 as default
geom_opt_tol_energy = 1.0             # Energy change threshold for convergence, 1.0 * 10^-6 as default
use_bfgs = true                       # Use LBFGS optimizer
use_line_search = true               # Enable line search for better step size in optimization

Excited State Calculations

[excited]
calculate_excited_states = false       # Enable excited state calculation
nstates = 10                           # Number of excited states to calculate
davidson_iterations = 100              # Max iterations in the Davidson solver
davidson_subspace_multiplier = 10      # Controls the max subspace size: subspace = nstates * multiplier
davidson_convergence = 0.00001         # Convergence threshold for the residuals in Davidson method
use_casida = false                     # Use full Casida equations; default is TDA
get_all_states = false                 # Calculate all excited states (not just lowest nstates)

TD-DFTB Excited States

[tddftb]
restrict_active_orbitals = false         # Enable orbital restriction (limits calculation to key orbitals)
active_orbital_threshold = 0.2           # Fraction of orbitals included (0.2 = 20% of occupied and virtual orbitals)
save_transition_densities = false        # Save transition density matrices
save_natural_transition_orbitals = false # Save NTOs as .cube files (for visualization)
states_to_analyse = [0, 1]               # Specify which excited states to analyze (e.g., save NTOs)

Slater-Koster Parameters

[slater_koster]
use_external_skf = false          # Use external Slater-Koster files (recommended)
skf_directory = " "               # Path to the directory containing .skf files

Parallelization

[parallelization]
number_of_cores = 1               # Number of CPU cores to use (parallel execution)

FMO-LC-TDDFTB Settings

[fmo_lc_tddftb]
restrict_active_space = true               # Restrict exchange integral calculation to significant transitions only; only TDM matrix elements that are above a threshold will be considered for the exchange evaluation
active_space_threshold_le = 0.0001         # Threshold for including locally excited transitions
active_space_threshold_ct = 0.0001         # Threshold for charge-transfer transitions
n_le = 2                                   # Number of local excited states to consider
n_ct = 1                                   # Number of CT states to include
calculate_all_states = false               # Whether to compute full excitonic Hamiltonian
calculate_ntos = false                     # Enable NTO calculations
calculate_transition_densities = false     # Save transition density matrices
calculate_particle_hole_densities = false  # Save particle/hole density maps
states_to_analyse = [0, 1]                 # Specify which states to analyze
calc_exact_s_sqrt_inv = false              # Compute exact inverse square root of overlap matrix (costly but accurate)

Dispersion Corrections (DFT-D3)

[dispersion]
use_dispersion = false       # Enable Grimme's DFT-D3 dispersion correction; you need to look up the dispersion parameters to the corresponding Slater-Koster files
s6 = 1.0                     # Global scaling factor for dispersion energy
s8 = 0.01                    # Scaling for higher-order dispersion terms
a1 = 0.497                   # Damping function parameter
a2 = 3.622                   # Damping function parameter

Monomer Identification

[identification_config]
atom_coordinates = [[0.0, 0.0, 0.0]]  # Coordinates of a single atom of the monomer for identification in the structure

Initial Condition Sampling (Wigner)

[wigner_config]
n_samples = 50                     # Number of samples to generate (position + velocity)
temperature = 50.0                 # Temperature for sampling (Wigner distribution)
n_cut = 6                          # Number of modes (typically rotational/translation) to exclude from Hessian
save_in_other_path = false         # Save files outside the working directory
wigner_path = " "                  # If saving elsewhere, specify full directory path
write_velocities = true            # Save velocity vectors in output (NumPy format)

Create cube files along Ehrenfest trajectory

[tdm_config]
calculate_nth_step = 10            # Create a cube file for every nth step
total_steps = 1000                 # Set the total number of steps along the trajectory
store_tdm = false                  # Save the TDM as a Numpy file
store_hole_particle = false        # Save the hole and particle density as a cube file
calc_cube = true                   # Compute the cube file of the particle and hole densities
calc_tdm_cube = false              # Compute the cube file of the transition density matrix
use_parallelization = true         # use multithreading for the calculation (high demand of RAM)

Strong light-matter interactions

[polariton]                        # If the jobtype "polariton" is chosen, these options must be considered
e = [[1.0, 1.0, 1.0]]              # activate/deactivate the electric field components of the photon 
p = [[0.0, 0.0, 0.0]]              # electric field polarization of the photon; for x-polarisation, choose [[1.0,0.0,0.0]]
photon_energy = [0.0]              # photon energy
quantized_volume = [1.0]           # quantized volume for the calculation of the light-matter coupling constant g

Calling the program

If you have the DIALECT executable in your PATH, you can simply start a calculation using

dialect file.xyz

Otherwise you would have to call the program using the full path to the DIALECT binary

/your/path/to/DIALECT/dialect file.xyz

Normally the output of the program is printed to the console. To save the output to a file, use:

dialect file.xyz &> output.dat

If you intend to use the built in DFTB parameterization, you are required to set the DIALECT_SRC_DIR to the folder containing the source files of the program:

export DIALECT_SRC_DIR=/your/path/to/DIALECT

Example configurations

In this chapter, we present configurations for a few different example calculations.

DFTB ground state calculation

Here, we show example dialect.toml file configurations for ground state calculations using various DFTB methods.

DFTB2

jobtype = "sp"
verbose = 0

[tight_binding]
use_dftb = true 
use_xtb1 = false   
use_gaussian_gamma = false  
use_shell_resolved_gamma = false 

[mol]
charge = 0
multiplicity = 1 # As of now, only singlets are supported

[lc]
long_range_correction = false
long_range_radius = 3.03

[scf]
scf_max_cycles = 250
scf_charge_conv = 1.0e-8
scf_energy_conv = 1.0e-8

[slater_koster]
use_external_skf = true
skf_directory = "/path/to/slater_koster_files/mio-1-1"

[parallelization]
number_of_cores = 1

[dispersion]
use_dispersion = false
s6 = 1.0
s8 = 0.01
a1 = 0.497
a2 = 3.622

LC-DFTB2

jobtype = "sp"
verbose = 0

[tight_binding]
use_dftb = true 
use_xtb1 = false   
use_gaussian_gamma = false  
use_shell_resolved_gamma = false 

[mol]
charge = 0
multiplicity = 1

[scf]
scf_max_cycles = 250
scf_charge_conv = 1.0e-8
scf_energy_conv = 1.0e-8

[lc]
long_range_correction = true # request long-range correction
long_range_radius = 3.333333 # set the long-range radius -> R_{lc} = 1/omega

[slater_koster]
use_external_skf = true
skf_directory = "/path/to/slater_koster_files/ob2-1-1/split"

[parallelization]
number_of_cores = 1

[dispersion]
use_dispersion = false
s6 = 1.0
s8 = 0.01
a1 = 0.497
a2 = 3.622

DFTB3

jobtype = "sp"
verbose = 0

[tight_binding]
use_dftb = true 
use_xtb1 = false   
use_gaussian_gamma = false  
use_shell_resolved_gamma = false 

[mol]
charge = 0
multiplicity = 1

[lc]
long_range_correction = false
long_range_radius = 3.03

[scf]
scf_max_cycles = 250
scf_charge_conv = 1.0e-8
scf_energy_conv = 1.0e-8

[dftb3]
use_dftb3 = true
use_gamma_damping = false
hubbard_derivatives = [-0.1857, -0.1492] # from the element with the lowest atomic number to the highest

[slater_koster]
use_external_skf = true
skf_directory = "/path/to/work/slater_koster_files/3ob-3-1"

[parallelization]
number_of_cores = 1

[dispersion]
use_dispersion = false
s6 = 1.0
s8 = 0.01
a1 = 0.497
a2 = 3.622

DFTB excited-state calculation

Here, we show an example dialect.toml file configuration for excited-state calculations using LC-DFTB.

jobtype = "sp"
verbose = 0

[tight_binding]
use_dftb = true 
use_xtb1 = false   
use_gaussian_gamma = false  
use_shell_resolved_gamma = false 

[mol]
charge = 0
multiplicity = 1

[scf]
scf_max_cycles = 250
scf_charge_conv = 1.0e-8
scf_energy_conv = 1.0e-8

[lc]
long_range_correction = true
long_range_radius = 3.333333

[excited]
calculate_excited_states = true # request excited states
nstates = 10 # number of excited states
davidson_iterations = 100 # Maximum number of iterations for the Davidson algorithm
davidson_subspace_multiplier = 10 # Sets the maximum number of guess vectors for the Davidson algorithm as: 10 * NrExcitations -> Here, it would result in a maximum subspace of 100
davidson_convergence = 0.00001 # Tolerance threshold for the residuals of the Davidson alogrithm
use_casida = false # if false, only TDA is performed
get_all_states = false # if requested, the full excited state manifold of singly excited singlet states is calculated -> Builds full A matrix 

[tddftb]
restrict_active_orbitals = false # restrict the number of orbitals for the excited state calculation
active_orbital_threshold = 0.5 # 50% of the occupied and virtual orbitals are used for the excited state calculation
save_transition_densities = false # save transition densities to npy file
save_natural_transition_orbitals = true # request NTOs if desired
states_to_analyse = [0, 1] # states for the calculation of transition densities and NTOs

[slater_koster]
use_external_skf = true
skf_directory = "/path/to/skf/files"

[parallelization]
number_of_cores = 1

[dispersion]
use_dispersion = false
s6 = 1.0
s8 = 0.01
a1 = 0.497
a2 = 3.622

DFTB geometry optimization

Here, we show example dialect.toml file configurations for the geometry optimization of the ground and excited state.

Ground state

jobtype = "opt"
verbose = 0

[tight_binding]
use_dftb = true 
use_xtb1 = false   
use_gaussian_gamma = false  
use_shell_resolved_gamma = false 

[fmo]
fmo = false
vdw_scaling = 2.0

[mol]
charge = 0
multiplicity = 1

[lc]
long_range_correction = false
long_range_radius = 3.03

[scf]
scf_max_cycles = 250
scf_charge_conv = 1.0e-8
scf_energy_conv = 1.0e-8

[opt]
state_to_optimize = 0 # optimize the ground state
geom_opt_max_cycles = 500 # maximum iterations
geom_opt_tol_displacement = 1.0 # geometry displacement tolerance
geom_opt_tol_gradient = 1.0 # gradient tolerance
geom_opt_tol_energy = 1.0e-1 # energy tolerance
use_bfgs = true # employ lbfgs
use_line_search = true # utilize line search

[slater_koster]
use_external_skf = true
skf_directory = "/path/to/skf/files"

[parallelization]
number_of_cores = 1

[dispersion]
use_dispersion = false
s6 = 1.0
s8 = 0.01
a1 = 0.497
a2 = 3.622

Excited state

jobtype = "opt"
verbose = 0

[tight_binding]
use_dftb = true 
use_xtb1 = false   
use_gaussian_gamma = false  
use_shell_resolved_gamma = false 

[fmo]
fmo = false
vdw_scaling = 2.0

[lc]
long_range_correction = false
long_range_radius = 3.03

[scf]
scf_max_cycles = 250
scf_charge_conv = 1.0e-8
scf_energy_conv = 1.0e-8

[opt]
state_to_optimize = 1
geom_opt_max_cycles = 500
geom_opt_tol_displacement = 1.0
geom_opt_tol_gradient = 1.0
geom_opt_tol_energy = 1.0e-1
use_bfgs = true
use_line_search = true

[excited]
calculate_excited_states = true
nstates = 10
davidson_iterations = 100
davidson_subspace_multiplier = 10
davidson_convergence = 0.00001
use_casida = false
get_all_states = false

[slater_koster]
use_external_skf = true
skf_directory = "/path/to/skf/files"

[parallelization]
number_of_cores = 1

[dispersion]
use_dispersion = false
s6 = 1.0
s8 = 0.01
a1 = 0.497
a2 = 3.622

FMO-DFTB ground state calculation

Here, we show an example dialect.toml file configuration for a ground state calculation using the (LC-)DFTB2 method.

DFTB2

jobtype = "sp"
verbose = 0

[tight_binding]
use_dftb = true 
use_xtb1 = false   
use_gaussian_gamma = false  
use_shell_resolved_gamma = false 

[fmo]
fmo = true
vdw_scaling = 2.0

[mol]
charge = 0
multiplicity = 1

[scf]
scf_max_cycles = 250
scf_charge_conv = 1.0e-8
scf_energy_conv = 1.0e-8

[lc]
long_range_correction = false
long_range_radius = 3.333333

[slater_koster]
use_external_skf = true
skf_directory = "/path/to/slater_koster"

[parallelization]
number_of_cores = 1

[dispersion]
use_dispersion = false
s6 = 1.0
s8 = 0.01
a1 = 0.497
a2 = 3.622

LC-DFTB2

jobtype = "sp"
verbose = 0

[tight_binding]
use_dftb = true 
use_xtb1 = false   
use_gaussian_gamma = false  
use_shell_resolved_gamma = false 

[fmo]
fmo = true
vdw_scaling = 2.0

[mol]
charge = 0
multiplicity = 1

[scf]
scf_max_cycles = 250
scf_charge_conv = 1.0e-8
scf_energy_conv = 1.0e-8

[lc]
long_range_correction = true
long_range_radius = 3.333333

[slater_koster]
use_external_skf = true
skf_directory = "/path/to/skf/files"

[parallelization]
number_of_cores = 1

[dispersion]
use_dispersion = false
s6 = 1.0
s8 = 0.01
a1 = 0.497
a2 = 3.622

FMO-DFTB excited state calculation

Here, we show an example dialect.toml file configuration for an excited state calculation using the FMO-LC-TDDFTB method.

jobtype = "sp"
verbose = 0

[tight_binding]
use_dftb = true 
use_xtb1 = false   
use_gaussian_gamma = false  
use_shell_resolved_gamma = false 

[fmo]
fmo = true
vdw_scaling = 2.0

[mol]
charge = 0
multiplicity = 1

[scf]
scf_max_cycles = 250
scf_charge_conv = 1.0e-8
scf_energy_conv = 1.0e-8

[lc]
long_range_correction = true
long_range_radius = 3.333333

[excited]
calculate_excited_states = true
nstates = 100
davidson_iterations = 100
davidson_subspace_multiplier = 10
davidson_convergence = 0.00001
use_casida = false
get_all_states = false

[slater_koster]
use_external_skf = true
skf_directory = "/path/to/skf/files"

[parallelization]
number_of_cores = 1

[fmo_lc_tddftb]
restrict_active_space = true # Restricts the transition density matrix elements for the calculation of the exchange interactions between LE and CT states 
active_space_threshold_le = 0.0001 # threshold for the tdm matrix for LE interactions
active_space_threshold_ct = 0.0001 # threshold for the tdm matrix for CT interactions
n_le = 3 # Number of requested LE states for each fragment
n_ct = 1 # Number of requested CT states for each fragment pair
calculate_all_states = false # Calculate all excited states of the excitonic Hamiltonian
calculate_ntos = false # Calculate NTOs, which are then saved in a molden file that works with jmol
calculate_transition_densities = false # request the calculation of transition densities
calculate_particle_hole_densities = false # request the calculation of particle hole densities
states_to_analyse = [0, 1] # states for the NTO generation
calc_exact_s_sqrt_inv = false # request the exact calculation of the S^-1/2 matrix

[dispersion]
use_dispersion = false
s6 = 1.0
s8 = 0.01
a1 = 0.497
a2 = 3.622

DFTB dynamics simulation

Here, we show example dialect.toml and dynamics.toml file configurations for the simulation of molecular dynamics using DFTB methods.

Ground state dynamics

dialect.toml

jobtype = "dynamics"
verbose = 0

[tight_binding]
use_dftb = true 
use_xtb1 = false   
use_gaussian_gamma = false  
use_shell_resolved_gamma = false 

[mol]
charge = 0
multiplicity = 1

[scf]
scf_max_cycles = 250
scf_charge_conv = 1.0e-8
scf_energy_conv = 1.0e-8

[lc]
long_range_correction = true
long_range_radius = 3.333333

[slater_koster]
use_external_skf = true
skf_directory = "/path/to/skf/files"

[parallelization]
number_of_cores = 1

[dispersion]
use_dispersion = false
s6 = 1.0
s8 = 0.01
a1 = 0.497
a2 = 3.622

dynamics.toml

nstep = 100 # Number of steps
stepsize = 0.1 # stepsize in fs
restart_flag = false # request restart of the dynamcis simulation
initial_state = [0] # initial state for the simulation
nstates = 1 # Number of electronic states
gs_dynamic = true # Flag for ground state dynamics
use_surface_hopping = false
use_ehrenfest = false 
load_velocities_from_file = false # Read initial velocities from the file velocities.npy
use_boltzmann_velocities = true # Sample initial velocities from Maxwell-Boltzmann distribution

[thermostat_config]
use_thermostat = false # Use a thermostat, here Berendsen
temperature = 300.0 
time_coupling = 50.0 # time coupling constant of the thermostat

[print_config]
print_restart = true # write a restart file
print_coordinates = true # write the coordinates in a trajetory file, dynamics.xyz
print_energies = true # write the energies to a file
print_temperature = true # write the temperature to a file

Excited state surface hopping dynamics

dialect.toml

jobtype = "dynamics"
verbose = 0

[tight_binding]
use_dftb = true 
use_xtb1 = false   
use_gaussian_gamma = false  
use_shell_resolved_gamma = false 

[mol]
charge = 0
multiplicity = 1

[scf]
scf_max_cycles = 250
scf_charge_conv = 1.0e-8
scf_energy_conv = 1.0e-8

[lc]
long_range_correction = true
long_range_radius = 3.333333

[excited]
calculate_excited_states = true
nstates = 10
davidson_iterations = 100
davidson_subspace_multiplier = 10
davidson_convergence = 0.00001
use_casida = false
get_all_states = false

[tddftb]
restrict_active_orbitals = false
active_orbital_threshold = 0.2
save_transition_densities = false
states_to_analyse = [0, 1]

[slater_koster]
use_external_skf = true
skf_directory = "/path/to/skf/files"

[parallelization]
number_of_cores = 1

[dispersion]
use_dispersion = false
s6 = 1.0
s8 = 0.01
a1 = 0.497
a2 = 3.622

dynamics.toml

nstep = 100
stepsize = 0.1
restart_flag = false
initial_state = [2]
nstates = 8
gs_dynamic = false
use_surface_hopping = true # Do a surface hopping molecular dynamics simulation
use_ehrenfest = false # request the use of the Ehrenfest method
load_velocities_from_file = false
use_boltzmann_velocities = true

[hopping_config]
force_switch_to_gs = true # In TDDFTB, the conical intersection between the ground state and the excited states is only represented by a simple crossing instead of a cone. This option forces the trajectory to hop to the ground state if the difference in potential energy is below a certain threshold.
decoherence_correction = true # Use a decoherence correction
use_rk_integration = false # integrate the differential equation of the expansion coefficients with Runge-Kutta
use_local_diabatisation = true # Use the local diabatisation for the surface hopping dynamics to avoid strongly peaked nonadiabatic coupling values
use_rescaling_at_frustrated_hop = true # rescale velocities at frustrated hops
integration_steps = 1000 # integration steps for the Runge-Kutta routine

[nonadibatic_config]
use_nacv_couplings = true # Use nonadiabatic coupling vectors for the surface hopping procedure
use_nact_couplings = false # Use the scalar coupling for the surface hopping dynamics

[thermostat_config]
use_thermostat = false # use a Berendsen thermostat
temperature = 300.0 # Temperature in Kelvin
time_coupling = 50.0 # time coupling constant of the Berendsen thermostat

[print_config]
print_restart = true # write a restart file from where a dynamics calculation can be restarted
print_coordinates = true # write the coordinates to the file "dynamics.xyz"
print_energies = true # write the energies to a file
print_temperature = true # write the temperature to a file
print_state = true # write the state for the surface hopping method for each geometry along the trajectory to a file

DFTB excited state dynamics initial conditions

Here, we show example dialect.toml file configuration for the calculation of initial coordinates and velocities of a surface hopping simulation.

The jobtype "initial_conditions" first performs a optimization of the geometry, which is followed by the calculation of the ground-state Hessian and concluded by the sampling of a Wigner distribution.

dialect.toml

jobtype = "initial_conditions"
verbose = 0

[tight_binding]
use_dftb = true 
use_xtb1 = false   
use_gaussian_gamma = false  
use_shell_resolved_gamma = false 

[scf]
scf_max_cycles = 250
scf_charge_conv = 1.0e-8
scf_energy_conv = 1.0e-8

[lc]
long_range_correction = true
long_range_radius = 3.333333

[opt]
state_to_optimize = 0 # optimize the ground state
geom_opt_max_cycles = 500 # maximum iterations
geom_opt_tol_displacement = 1.0 # geometry displacement tolerance
geom_opt_tol_gradient = 1.0 # gradient tolerance
geom_opt_tol_energy = 1.0e-1 # energy tolerance
use_bfgs = true # employ lbfgs
use_line_search = true # utilize line search

[slater_koster]
use_external_skf = true
skf_directory = "/path/to/skf/files"

[parallelization]
number_of_cores = 1

[dispersion]
use_dispersion = false
s6 = 1.0
s8 = 0.01
a1 = 0.497
a2 = 3.622

[wigner_config]
n_samples = 50                     # Number of samples to generate (position + velocity)
temperature = 50.0                 # Temperature for sampling (Wigner distribution)
n_cut = 6                          # Number of modes (typically rotational/translation) to exclude from Hessian
save_in_other_path = false         # Save files outside the working directory?
wigner_path = " "                  # If saving elsewhere, specify full directory path
write_velocities = true            # Save velocity vectors in output (NumPy format)

Strong light-matter interactions

Here, we present an example dialect.toml configuration for the calculation of the polaritonic excited states in the framework of FMO-LC-TDDFTB.

dialect.toml

jobtype = "polariton"
verbose = 0

[tight_binding]
use_dftb = true
use_xtb1 = false
use_gaussian_gamma = false
use_shell_resolved_gamma = false

[fmo]
fmo = true
vdw_scaling = 2.0

[scf]
scf_max_cycles = 250
scf_charge_conv = 1.0e-8
scf_energy_conv = 1.0e-8

[lc]
long_range_correction = true
long_range_radius = 3.33333333333333

[excited]
calculate_excited_states = true
nstates = 600
davidson_iterations = 100
davidson_subspace_multiplier = 10
davidson_convergence = 0.00001
use_casida = false
get_all_states = false

[tddftb]
restrict_active_orbitals = false
active_orbital_threshold = 0.2
save_transition_densities = false
save_natural_transition_orbitals = false
states_to_analyse = [0, 1]

[slater_koster]
use_external_skf = true
skf_directory = "/Users/einseler/work/slater_koster_files/ob2-1-1/split"

[parallelization]
number_of_cores = 4

[fmo_lc_tddftb]
restrict_active_space = true
active_space_threshold_le = 0.0001
active_space_threshold_ct = 0.0001
n_le = 2
n_ct = 1
calculate_all_states = false
calculate_ntos = false
calculate_transition_densities = false
calculate_particle_hole_densities = false
states_to_analyse = [0, 1]
calc_exact_s_sqrt_inv = false

[dispersion]
use_dispersion = false
s6 = 1.0
s8 = 0.01
a1 = 0.497
a2 = 3.622

[polariton]
e = [[1.0, 1.0, 1.0]]
p = [[0.0, 1.0, 0.0]]
quantized_volume = [10000000]
photon_energy = [0.1838950000382341]