DIALECT

The DIALECT(DIAbatic Locally Excited and Charge-Transfer states) software was designed to calculate the electronically excited states of large molecular systems. 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

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.

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

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

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 for your platform and add the directory of the executable to your PATH.

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"
fmo = false
verbose = 0

jobtype

You can choose between "sp" for a DFTB or FMO-LC-DFTB calculation or "density" for the calculation of a given density in the AO basis on a grid.

fmo

If you want to do a FMO-DFTB calculation, set fmo=true.

verbose

Concerns the verbosity of the output. Values from -2 to 2 are possible. Higher values result in a much more detailed output.

[mol] config

[mol]
charge = 0
multiplicity = 1

You can change the charge and the multiplicity of the molecule. But at this point in time, the program only supports closed shell configurations!

[scf] config

The convergence settings of the self-consistent charge (SCC) routine are defined here.

[scf]
scf_max_cycles = 250
scf_charge_conv = 0.00001
scf_energy_conv = 0.00001

scf_max_cycles

Maximum number of iterations for the SCC routine

scf_charge_conv

Convergence criterium of the SCC routine. It concerns the charge difference to the previous iteration.

scf_energy_conv

Convergence criterium of the SCC routine. It concerns the energy difference to the previous iteration.

[lc] config

Here, you can turn the long-rang correction on and set the long-range radius. Be aware that a FMO calculation only works with an activated long-range correction.

[lc]
long_range_correction = true
long_range_radius = 3.03

[excited] config

[excited]
calculate_excited_states = false
nstates = 10
davidson_iterations = 100
davidson_subspace_multiplier = 10

calculate_excited_states

If you want to calculate the excited states in a standard DFTB or FMO-DFTB caluculation, set this option to true.

nstates

Number of requested excites states.

davidson_iterations

Maximum number of iterations for the Davidson routine.

davidson_subspace_multiplier

Maximum scaling factor of the dimension for the guess vectors of the Davidson algorithm. It is multiplied with the number of requested excited states.

[tda_dftb] config

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

Settings concerning a normal TDA-TDDFTB calculation

restrict_active_orbitals

Reduce the number of occupied and virtual orbitals involved during the TDDFTB calulation.

active_orbital_threshold

Set the fraction of the full orbital space

save_transition_densities

Save the transition density matrix in AO basis for the requested excited states.

states_to_analyse

Select the states for which you want to calculate and save the transition density matrices.

[slater_koster] config

[slater_koster]
use_external_skf = false
skf_directory = " "

use_external_skf

Use Slater-Koster parameters from external source.

skf_directory

Specify the path to the SKF-files. "/path/to/SKF/"

[parallelization] config

[parallelization]
number_of_cores = 1

number_of_cores

Use the specified number of processor cores for the calculation. It only affects a FMO-DFTB calculation

[fmo_lc_tddftb] config

[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]

Settings for the excited state calculation using the FMO-LC-TDDFTB method

restrict_active_space

Calculate only relevant transitions between orbitals for the exchange part of the couplings between the LE and CT states.

active_space_treshold_le

Threshold for the one electron transition density matrices of the LE states.

active_space_treshold_ct

Threshold for the one electron transition density matrices of the CT states.

n_le

Number of locally excited states for each monomer fragment.

n_ct

Number of charge-transfer states for each pair fragment.

calculate_all_states

Do a full diagonalization of the excitonic Hamiltonian instead of the Davidson routine.

calculate_ntos

Calculate the natural transition orbitals for the specified excited states. They will be stored as molden files, which can be viewed in jmol.

calculate_transition_densities

Calculate the transition density matrices in AO basis for the specified excited states. They will be stored as binary numpy files.

calculate_particle_hole_densities

Calculate the particle and hole densities for the specified excited states. They will be stored as binary numpy files.

states_to_analyze

List of the excited states for which the ntos or densities will be calculated.

[density] config

[density]
path_to_density = " "
points_per_bohr = 2.0
threshold = 0.0001
use_block_implementation = true
n_blocks = 1

Settings regarding the calculation of a density in AO basis on the grid, which will be stored as a cube file.

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

dialect manual