Settings

Settings and keywords

At this point, we can look at where the methods used for different tasks are actually defined.

If we want to use the best-known methods for certain applications, or the methods with the best cost-benefit ratio, there is no single method that can be used for all purposes. Different methods are needed for different applications. In addition, expert users may want to define their own configuration files to use their own set of methods.

In order to standardize the methods used to perform quantum chemistry calculations, but at the same time provide enough flexibility for individual applications, experimental settings, and various user-specific needs, we use a hierarchy of configuration options:

../_images/hierachy_weasel_jobs.jpg — Hierarchy of settings and options used for a WEASEL job.

Command line keywords: The command line keywords are used when starting WEASEL. Here the default methods and settings are overwritten, e.g. methods used for specific tasks, solvents or system charges.

weasel water.xyz [KEY1] [KEY2] ...

Workflow settings: The workflow settings are used for standard workflows, and are stored in a configuration file. The workflow configuration files are provided together with the standard WEASEL release, but can also be developed together with FAccTs or by the users themselves for their local applications.

weasel water.xyz -workflow <workflow name>

Project settings: The project settings are used for project-specific or user-specific settings, and are also stored in a configuration file. The project settings can be easily copied and modified from the default settings.ini file. They can be quite useful for expert users.

weasel water.xyz -settingsfile mysettings.ini

Default settings: The default settings are stored in a configuration file. These settings are used if e.g. WEASEL is called solely together with a structure file or if an option has not been set by any of the aforementioned interfaces:

weasel water.xyz

Important

Most of the defaults defined in the configuration files can be overwritten via arguments in the command line.

Important

All settings and workflows are version bound to a minor version of WEASEL (i.e., 1.10 or 1.11, ...) as keywords might be changed, removed or added between versions. Therefore, settings files use following name scheme: settings-1.11.ini, where 1.11 is the minor version of WEASEL. Furthermore, all settings and workflow files must contain following keyword:

[SOFTWARE]
# Minor version of WEASEL. See example below
Version = 1.11

Settings files

Default settings

WEASEL's built-in default settings can be customized by creating a system settings file /etc/weasel/settings-1.11.ini or a user settings file ~/.config/weasel/settings-1.11.ini while the values in the latter one take precedence. For running WEASEL some mandatory minimal settings are required (see here for details). For convenience, all built-in default settings are documented with explanatory comments: weasel-<version>/settings/defaults.ini

This file has the format of a configuration file, containing sections with their keys (name-value pairs), here shown for the preoptimization step:

[PREOPT]
# True if preoptimization is the default, else False
Default = True
# Options HF-3c, PBEh-3c, XTB
Method = XTB

The above keys define that, by default, the basic workflow includes the preoptimization task - in which the XTB method (GFN2-xTB) is used.

Note

Note, the path of the system settings file /etc/weasel/settings-1.11.ini can be customized by the environment variable WEASEL_SYSTEM_SETTINGS.

Project settings

Project settings files or personalized settings files can be defined and used as a replacement to the settings.ini file described above. Such a project settings file is added via the command line:

weasel water.xyz -settingsfile /path/to/mysettings.ini

The project settings does not differ from the default settings which are documented in weasel-<version>/settings/defaults.ini. Just the values can be different.

Note

The project settings file can be useful if a project requires different settings from the defaults. Alternatively, experienced users might have different preferred calculations, which they can then define in their own project settings.

Important

The values from the project settings only overwrite the values from the default settings. I.e. if keys or entire sections are missing in the project settings, they are simply taken from the default settings. This can be useful if e.g. the paths to software used by WEASEL are always the same, or if the project settings is from an older version compared to the default settings from a newer release - which usually contains new keys.

Workflow settings

The workflow settings files have the same format as the default and project settings files.

The workflow settings files are stored in:

weasel-<version>
├── workflows
│       ├── workflow_exploreReactivity.ini
│       ├── workflow_IR.ini
│       ├── workflow_NMR.ini
│       └── ...

A workflow settings file does not differ from the default settings which are documented in weasel-<version>/settings/defaults.ini and can also be viewed as a project settings file. It is just that the values can be different and usually the workflow settings files contain fewer sections compared to the default settings file: the workflow settings files only contain those sections, that are necessary for the particular workflow. Values for the missing sections are taken from the default or project settings.

Note

Workflow settings can be combined with project settings. The project settings overwrite the default settings, and the workflow settings overwrite the combination of project and default settings.

Important

We try to keep the workflow files forward compatible, so that once established workflow files can be used with new WEASEL versions as well.

Sections in settings files

We briefly discuss the most important sections in the settings file.

The preferences file is divided into several sections. To view the contents of each section, click its name in the list:

Note

Possible values for the methods, basis sets, solvents, ... defined in the sections can be listed with the command

weasel -h

SOFTWARE

All information related to the back engine(s) of WEASEL.

For WEASEL-1.11 this part contains the following:

[SOFTWARE]
# To which weasel version does this settings file belong to. Do not change!
Version = 1.11
# Give full path to orca
ORCA_PATH =
# Path to GOAT binaries
GOAT_PATH =
# Give full path to openmpi - lib and bin should be subdirectories of that path
MPI_PATH =
# Give executable of crest with full path.
CREST_EXEC =
# Set rsh command for parallel Weasel runs on clusters
RSH_COMMAND = ssh -x -v
#   Set rsh connection timeout for parallel Weasel runs on clusters (unit: seconds) [default: 15]
RSH_TIMEOUT = 15
# Set number of tries for rsh connection test
# For value <= 0 the connection test will be disabled
RSH_TRIES = 5
# Optional: Set scratch directory for WEASEL jobs. Leave unset for using the current directory of a job.
SCRATCH_DIR =
# Optional: List of environmental variable names, that are ensured to be set on every node by Weasel. Listed variables
#  have to be set on the head node, otherwise they are ignored.
#  (e.g. ENV_VARS=OMPI_MCA_btl_tcp_if_include,OMPI_MCA_btl_tcp_if_exclude,OMPI_MCA_btl)
ENV_VARS =
# Optional: Set backing scratch directory for Open MPI, which is used as fallback in case the usual
#  scratch dir runs out of space.
OPENMPI_BACKING_DIR =

HARDWARE

All information related to available hardware. How many cores can be used, how much memory is available. Part of this has already been discussed here.

For WEASEL-1.11 this part of the settings.ini file contains the following:

[HARDWARE]
# Memory available per core.
# Following SI unit suffixes are allowed: B, K, M, G, T [default: M], e.g. 1G
# Units are interpreted as powers of 1000 (SI format).
# Example: If 4 cores (pal4) are used and in total 32000 MB RAM is available, Memory should be set to 6000
Memory =
# Set the total memory of the current machine. This option is mutually exclusive to "Memory".
# The same rules as for the "Memory" option apply.
MemoryTotal =
# Ratio of available memory allocated to ORCA calculation, should be between 0 and 1. The developer team recommends
# to use only 75%, i.e. 0.75, of physically available memory.
MemoryRatioForORCA = 0.75
# Number of cores to be used for parallel jobs
Cores =
# Allow using hyper-threading [default: False]
Use_Hyperthreading = False
# Enable Intel MKL performance boost for non-Intel CPUs (only available on Linux systems) [default: True]
Boost_NonIntel = True
# Maximum number of cores for a single ORCA calculation.
#  Disable by choosing value < 1.
#  (Option is mandatory)
MaxCoreOrca = 32
# Maximum number of cores for a single numerical Hessian (!NumFreq) ORCA calculation.
#  Disable by choosing value < 1
#  (Option is mandatory)
MaxCoreOrcaNumFreq = 120

PREOPT

The preoptimization step is switched on by default. It is included for computational efficiency. A cheap preoptimization can safe later more expensive optimization steps. The method for preoptimization is defined here:

[PREOPT]
# True if doPreOpt is the default, else False
Default = True
# Options HF-3c, PBEh-3c, XTB
Method = XTB
# True if PreOpt should not change the topology (non-hydrogen bonds) of the structure.
KeepTopology = True

OPT

The optimization step (DFT, semiempirical, or wavefunction) is switched on by default. Its method with accompanying basis set is defined here. Is a frequency run carried out after geometry optimization? At what value does an imaginary frequency indicate a saddle point? How many number of steps are per default used for relaxed surface scans?

This looks like this in the settings.ini file:

[OPT]
# True if doOpt is the default, else False
Default = True
# Options BP86, B3LYP, B3LYP, MP2, XTB, ... see methodOpt
Method = r2SCAN-3c
# Options: see [SP_WF] Basis
Basis = def2-TZVP(-F)
# Options: None (no basis2 for optimization) or see [SP_WF] Basis
Basis2 = def2-TZVP
# Options: any integer
ScanNSteps = 10
# If by default after each optimization a frequency calculation should be run --> True, otherwise False
FreqAfterOpt = False
# If by default after each TS optimization a frequency calculation should be run --> True, otherwise False
FreqAfterOptTS = True
# Threshold for checking for imaginary modes in frequency output. Imaginary frequencies above this threshold
# are not considered as imaginary modes when checking for the nature (minimum or TS) of the stationary point.
threshImagMode = -5
# Threshold for checking for imaginary modes in frequency output. Imaginary frequencies below this threshold
# are considered as critical imaginary modes when checking for the nature (minimum or TS) of the stationary point.
threshImagModeCritical = -20
# Use the default grid (<BLANK>) or a finer grid (DefGrid3) for the optimization. Options: DefGrid1, DefGrid2, DefGrid3
Grid =
# Which thresholds to use for optimization. Options are: Loose, Normal, Tight, VeryTight
OptType = Normal
# If frequency calculation is carried out, rerun optimization in case (unwanted) imaginary modes are found with the
#  frequency analysis. If frequency calculation is not carried out, this keyword is ignored.
#  Options are: True, False
CorrectImagModes = False
# How many optimization reruns should be run if (unwanted) imaginary modes are found
NReRunsCorrectImagModes = 3
# Calculate exact initial Hessian before optimization?
CalcInitialHess = False
# Try to converge a non-converged geometry optimization by running a few more optimization cycles.
# Also see the option: 'CONFORMATIONAL_SEARCH->OptRetry', which overrides this setting within the
# conformer search procedure.
# Options: 'True' or

SP_DFT

The final single point energy calculation at DFT level (all rungs of Jacob's ladder) is switched on by default. Its method with accompanying basis set is defined here:

[SP_DFT]
# True if doSP_DFT is the default, else False
Default = True
# Options: BP86, B3LYP, RIJK-B3LYP
Method = wB97X-V
# Options: see [SP_WF] Basis
#  Not used if composite methods are used, but needed in case a non-composite method is chosen.
Basis = def2-TZVP
# Options: None (no basis2 for SP_DFT) or see [SP_WF] Basis
Basis2 = def2-QZVPP
# Use the default grid (<BLANK>) or a finer grid (DefGrid3) for SP_DFT calculation. Options: DefGrid1, DefGrid2, DefGrid3
Grid =
# SCF Convergence criteria to be used for SP_DFT calculation. Use the default convergence (None) or other criteria.
# Options: None (default), SloppySCF, LooseSCF, NormalSCF, TightSCF, VeryTightSCF, ExtremeSCF.
SCFConv = None
# Compute gradient on SP_DFT level. True or false.
Gradient = False

SP_WF

The final single point energy calculation at wavefunction level is switched off by default. (Switch on typing -spwf) Its method with accompanying basis set is defined here. For DLPNO-methods the default PNO setting is also defined in this section:

[SP_WF]
# True if doSP_WF is the default, else False
Default = False
# Options: MP2, RI-MP2, RIJK-RI-MP2, RIJCOSX-RI-MP2, DLPNO-MP2, RIJK-DLPNO-MP2, RIJCOSX-DLPNO-MP2,
#          CCSD(T), RIJK-CCSD(T), DLPNO-CCSD(T), RIJK-DLPNO-CCSD(T), RIJCOSX-DLPNO-CCSD(T)
Method = DLPNO-CCSD(T)
# Options: def2-SVP, def2-TZVP, def2-TZVPP, def2-QZVP, def2-QZVPP,
#          ma-def2-SVP, ma-def2-TZVP, ma-def2-TZVPP, ma-def2-QZVP, ma-def2-QZVPP,
#          cc-pVDZ, cc-pVTZ, cc-pVQZ, cc-pVZ5, cc-pV6Z,
#          aug-cc-pVDZ, aug-cc-pVTZ, aug-cc-pVQZ, aug-cc-pV5Z, aug-cc-pV6Z
Basis = def2-TZVP
# Options: None (no basis2 for SP_WF) or see [SP_WF] Basis
Basis2 = def2-QZVPP
# PNO Settings for DLPNO calculations.
# Options: Loose, Normal, Tight, Normal_TightPairs, LooseIntra_NormalTightPairsForInteraction, LooseIntra_TightForInteraction, NormalIntra_NormalTightPairsForInteraction, NormalIntra_TightForInteraction
PNOSetting = Normal_TightPairs
# Use the default grid (<BLANK>) or a finer grid (DefGrid3) for the SP_WF calculation. Options: DefGrid1, DefGrid2, DefGrid3
Grid =
# Solvation method used for post-HF calculations.
SolvMethod = PTE(S)

PRE_SCF