The Input File
General
The concept of the input file is based on the definition of so-called “commands”. A command in the input file can have one of the two following forms and is always case-insensitive:
key = value;
key = [value1, value2, …];
Note
The semicolon at the end of both command definitions is necessary, while the number of whitespaces can be arbitrary at any position of the command as long as key and value are not split in parts. Input keys and string options are case-insensitive. Dashes and underscores are treated equivalently where both spellings are supported.
Command definition 1. represents a single value command, whereas definition 2. can be considered as a list of input values which will always be represented with [].
Command Usage
Due to the use of ; one line of the input file can contain multiple commands and blank lines will be ignored.
Types of Input Values
In the following sections the types of the input values will be denoted via {}, where {[]} represents a list of types:
Type |
Description |
|---|---|
{int} |
integer |
{uint+} |
positive integers |
{uint} |
positive integers including 0 |
{double} |
floating point numbers |
{string} |
- |
{file} |
- |
{path} |
- |
{pathFile} |
equal to {path/file} |
{bool} |
true/false |
{selection} |
selection |
Note
The {selection} type is used to select a specific atom or group of atoms. If the PQ software package was built with the python3.12 dependencies, the user can apply the selection grammar defined in the PQAnalysis package. However, if PQ was compiled without these dependencies it is possible to index via the atomic indices starting from 0. If more than one atom index should be selected, the user can give a list of indices like {0, 1, 2}. If a range of atom indices should be selected the user can use the following syntax {0-5, 10-15} or {0..5, 10-15} or {0..5, 10..15}, where all would be equivalent to {0, 1, 2, 3, 4, 5, 10, 11, 12, 13, 14, 15}.
Input Keys
Note
Some of the following keys are necessary in the input file and are therefore marked with a *. If there exists a default value for the possible options related to a key, they will be marked with -> after the command. Units of the values are given after the {}.
General Keys
Jobtype
Key
jobtype* = {string}
With the jobtype keyword the user can choose from different engines to perform (not only) MD simulations.
Possible options are:
mm-md - Represents a full molecular mechanics molecular dynamics simulation performed via the GUFF formalism and/or the
Amber force field. Respective input file keys are found in the MM Keys section.qm-md - Represents a full quantum mechanics molecular dynamics simulation. For more information see the QM Keys section.
qm-rpmd - Represents a full quantum mechanics ring polymer molecular dynamics simulation. For more information see the Ring Polymer MD Keys section
qmmm-md - Represents a hybrid quantum mechanics - molecular mechanics molecular dynamics simulation. (Not implemented yet)
mm-opt - represents a geometry optimization calculation using molecular mechanics.
mm-hessian - represents a molecular mechanics Hessian calculation. By default, the geometry is optimized first and the Hessian is built at the optimized structure. Set
optimize_before_hessian = falseto calculate the Hessian directly at the input geometry.
Timestep
Key
timestep* = {double} fs
With the timestep keyword the time step in fs of one molecular dynamics loop is set.
NStep
Key
nstep* = {uint+}
The nstep keyword sets the total number of MD steps or optimization epochs to be performed within this simulation run. It is required for MD job types, optimization job types and mm-hessian runs with optimize_before_hessian = true. It is not required for mm-hessian runs with optimize_before_hessian = false.
Floating Point Type
Key
floating_point_type = {string} -> “double”
With the floating_point_type keyword the user can choose the precision of the floating point numbers used in the QM calculations if enabled by the external QM program/model.
Possible options are:
double (default) - double precision floating point numbers are used
float - single precision floating point numbers are used
Integrator
Key
integrator = {string} -> “v-verlet”
With the integrator keyword the user can choose the integrator type which should be applied.
Possible options are:
v-verlet (default) - represents the Velocity-Verlet integrator
Random Seed
Key
random_seed = {uint}
With the random_seed keyword the user can provide a seed for all random events of the MD simulation.
Danger
This keyword should be used only for reproducibility purposes.
Virial
Key
virial = {string} -> “molecular”
With the virial keyword the user can control if an intramolecular virial correction should be applied based on the definition of molecular units in the Moldescriptor setup file.
Possible options are:
molecular (default) - an intramolecular correction will be applied to the resulting virial from the force contributions
atomic - no intramolecular correction to the resulting virial will be applied
Start File
Key
start_file* = {file}
The start_file keyword sets the name of the Restart File file for an MD simulation of any kind.
RPMD Start File
Key
rpmd_start_file = {file}
The rpmd_start_file keyword is used to continue a ring polymer MD simulation containing positions, velocities and forces of all atoms of each bead of the ring polymer.
General Output Keys
Note
The PQ application has a special naming convention for output files. For every job type a certain set of Output Files is written per default. If no output file names are given all prefixes of the output files will be named default.<ext>. If at least one of the output file keys was given in the input file - the program will determine the most common prefix (i.e. string before the first . character) and set it for all unspecified output files.
This feature enables easier post-processing of data and deletion of output files as PQ does not overwrite any existing output files.
Output Frequency
Key
output_freq = {uint} -> 1
The output_freq keyword sets the frequency (i.e. every n-th step) of how often the application should write into the Output Files. For a complete dry run without any output files the output frequency can be set to 0.
default value = 1
Overwrite Output Files
Key
overwrite_output = {bool} -> false
The overwrite_output keyword allows the user to overwrite any existing output files.
default value = false
Output Metadata
Key
include_output_metadata = {bool} -> false
When enabled, include_output_metadata adds a comment header containing the
simulation timestep to the averaged and instantaneous MD energy files. It also
adds the effective simulation step to the comment line of trajectory, velocity,
force, and charge frames, including their ring-polymer variants. It is disabled
by default to preserve the existing file formats.
default value = false
File Prefix
Key
file_prefix = {string}
The file_prefix keyword allows the user to set a common prefix name for all generated Output Files.
Log File
Key
output_file = {file} -> “default.log”
The output_file keyword sets the name for the Log File, in which important information about the performed calculation can be found.
default value = “default.log”
MD Output File Keys
All of the following output files are written during calculations using MD related jobtypes.
Box File
Key
box_file = {file} -> “default.box”
The box_file keyword sets the name for the Box File, which stores information about the simulation box throughout the simulation.
default value = “default.box”
Charge File
Key
charge_file = {file} -> “default.chrg”
The charge_file keyword sets the name for the Charge File, which stores the atomic partial charges throughout the MD simulation.
default value = “default.chrg”
Energy File
Key
energy_file = {file} -> “default.en”
The energy_file keyword sets the name for the Energy File, in which the most important physical properties of the full simulation can be found.
default value = “default.en”
Force File
Key
force_file = {file} -> “default.force”
The force_file keyword sets the name for the Force File, which stores the atomic forces throughout the MD simulation.
default value = “default.force”
Info File
Key
info_file = {file} -> “default.info”
The info_file keyword sets the name for the Info File, in which the most important physical properties of the last written step can be found.
default value = “default.info”
Instant Energy File
Key
instant_energy_file = {file} -> “default.instant_en”
The instant_energy_file keyword sets the name for the Instant Energy File, in which the most important physical properties of the full simulation can be found.
default value = “default.instant_en”
Momentum File
Key
momentum_file = {file} -> “default.mom”
The momentum_file keyword sets the name for the Momentum File, which stores information about the total linear and total angular momentum throughout the MD simulation.
default value = “default.mom”
Reference File
Key
reference_file = {file} -> “default.ref”
The reference_file keyword sets the name for the Reference File, which lists the sources to be cited when publishing data with the chosen settings.
default value = “default.ref”
Restart File
Key
rst_file = {file} -> “default.rst”
The rst_file keyword sets the name for the Restart File, which contains all necessary information to restart (i.e. continue) the calculation from its current timestamp.
default value = “default.rst”
Stress File
Key
stress_file = {file} -> “default.stress”
The stress_file keyword sets the name for the Stress File, which stores information about the stress tensor throughout the MD simulation.
default value = “default.stress”
Timings File
Key
timings_file = {file} -> “default.timings”
The timings_file keyword sets the name for the Timing File, which tracks the time PQ takes for executing individual parts of the simulation.
default value = “default.timings”
Trajectory File
Key
traj_file = {file} -> “default.xyz”
The traj_file keyword sets the name for the Trajectory File, which stores the atomic positions throughout the MD simulation.
default value = “default.xyz”
Velocity File
Key
vel_file = {file} -> “default.vel”
The vel_file keyword sets the name for the Velocity File, which stores the atomic velocities throughout the MD simulation.
default value = “default.vel”
Virial File
Key
virial_file = {file} -> “default.vir”
The virial_file keyword sets the name for the Virial File, which stores information about the virial tensor throughout the MD simulation.
default value = “default.vir”
RPMD Output File Keys
All of the following output files are written during calculations using ring polymer MD jobtype. The files represent the trajectories of all individual beads.
RPMD Charge File
Key
rpmd_charge_file = {file} -> “default.rpmd.chrg”
The rpmd_charge_file keyword sets the name for the file containing partial charges of all atoms of each bead of the ring polymer trajectory.
default value = “default.rpmd.chrg”
RPMD Energy File
Key
rpmd_energy_file = {file} -> “default.rpmd.en”
The rpmd_energy_file keyword sets the name for the file containing relevant energy data for each ring polymer bead of the simulation.
default value = “default.rpmd.en”
RPMD Force File
Key
rpmd_force_file = {file} -> “default.rpmd.force”
The rpmd_force_file keyword sets the name for the file containing forces of all atoms of each bead of the ring polymer trajectory.
default value = “default.rpmd.force”
RPMD Restart File
Key
rpmd_restart_file = {file} -> “default.rpmd.rst”
The rpmd_restart_file keyword sets the name for the ring polymer restart file, which contains all necessary information to restart (i.e. continue) the calculation from its current timestamp.
default value = “default.rpmd.rst”
RPMD Trajectory File
Key
rpmd_traj_file = {file} -> “default.rpmd.xyz”
The rpmd_traj_file keyword sets the name for the file containing positions of all atoms of each bead of the ring polymer trajectory.
default value = “default.rpmd.xyz”
RPMD Velocity File
Key
rpmd_vel_file = {file} -> “default.rpmd.vel”
The rpmd_vel_file keyword sets the name for the file containing velocities of all atoms of each bead of the ring polymer trajectory.
default value = “default.rpmd.vel”
Setup File Keys
In order to set up certain calculations additional input files have to be used. The names of these setup files have to be specified in the input file. Further information about the individual files can be found in the Setup Files section.
Note
topology_file becomes mandatory when force-field
is set to on or bonded, or when shake is set to
on or shake. parameter_file becomes mandatory when
force-field is set to on or bonded.
Moldescriptor File
Key
moldescriptor_file = {file} -> “moldescriptor.dat”
default value = “moldescriptor.dat”
GUFF File
Key
guff_file = {file} -> “guff.dat”
default value = “guff.dat”
DFTB Setup File
Key
dftb_file = {file} -> “dftb_in.template”
default value = “dftb_in.template”
Topology File
Key
topology_file = {file}
Parameter File
Key
parameter_file = {file}
M-SHAKE File
Key
mshake_file = {file}
Intra-NonBonded_File
Key
intra-nonbonded_file = {file}
Simulation Box Keys
Density
Key
density = {double} kgL⁻¹
With the density keyword the box dimension of the system can be inferred from the total mass of the simulation box.
Note
This keyword implies that the simulation box has a cubic shape. Furthermore, the density keyword will be ignored if in the Restart File contains any box information.
Radial Coulomb Cutoff
Key
rcoulomb = {double} \(\mathrm{\mathring{A}}\) -> 12.5 \(\mathrm{\mathring{A}}\)
With the rcoulomb keyword the radial cut-off in \(\mathrm{\mathring{A}}\) of Coulomb interactions for MM-MD type simulations can be set. If pure QM-MD type simulations are applied this keyword will be ignored and the value will be set to 0 \(\mathrm{\mathring{A}}\).
default value = 12.5 \(\mathrm{\mathring{A}}\) (for MM-MD type simulations)
Initial Velocities
Key
init_velocities = {string} -> false
To initialize the velocities of the system according to the target temperature with a Boltzmann distribution the user has to set the init_velocities to true or force.
Possible options are:
false (default) - velocities are taken from start file
true - velocities are initialized according to a Boltzmann distribution at the target temperature, if all velocities in the start file are zero or not given
force - velocities are initialized according to a Boltzmann distribution at the target temperature, regardless of the velocities in the start file
Danger
The option force should be used very carefully, since it neglects the velocities in the start file.
Temperature Coupling Keys
Temperature
Key
temp = {double} K
With the temp keyword the target temperature in K of the system can be set.
Note
This keyword is not restricted to the use of any temperature coupling method, as it is used e.g. also for the initialization of Boltzmann distributed velocities or the reset of the system temperature.
Starting Temperature
Key
start_temp = {double} K
With the start_temp keyword the initial temperature in K of the system can be set. If a value is given the PQ application will perform a temperature ramping from the start_temp to the temp value.
End Temperature
Key
end_temp = {double} K
The end_temp keyword is a synonym for the temp keyword and can be used to set the target temperature of the system. It cannot be used in combination with the temp keyword.
Temperature Ramp Steps
Key
temp_ramp_steps = {uint+}
With the temp_ramp_steps keyword the user can specify the number of steps for the temperature ramping from the start_temp to the temp value. If no starting temperature is given the keyword will be ignored. If a starting temperature is given and this keyword is omitted the temperature ramping will be performed over the full simulation time.
default value = full simulation time
Temperature Ramp Frequency
Key
temp_ramp_frequency = {uint+} -> 1
With the temp_ramp_frequency keyword the user can specify the frequency of the temperature ramping from the start_temp to the temp value. If no starting temperature is given the keyword will be ignored. If a starting temperature is given and this keyword is omitted the temperature ramping will be performed, so that each step the temperature is increased by the same value.
default value = 1 step
Thermostat
Key
thermostat = {string} -> “none”
With the thermostat keyword the temperature coupling method can be chosen.
Possible options are:
none (default) - no thermostat is set, hence {N/µ}{p/V}E settings are applied.
berendsen - the Berendsen weak coupling thermostat. Based on the rescaling of velocities according to the scaling factor \(\zeta\), equation (1). Ideal for crude temperature adjustments. Not able to reproduce the correct canonical ensemble.
(1)\[\zeta = \sqrt{1 + \frac{\Delta t}{\tau} \left( \frac{T_0}{T} - 1 \right)}\]velocity_rescaling - the stochastic velocity rescaling thermostat also known as Bussi-Donadio-Parrinello thermostat. Based on the rescaling of velocities according to the scaling factor \(\zeta\), equation (2). Enforces a canonical kinetic energy distribution.
(2)\[\zeta = \sqrt{1 + \frac{\Delta t}{\tau} \left( \frac{T_0}{T} - 1 +2 \sqrt{\frac{T_0}{T} \frac{\Delta t}{\tau} \frac{1}{df}} dW \right)}\]langevin - temperature coupling via stochastic Langevin dynamics. Based on modifying the force of each individual particle \(F_{\text i}\) via a friction force \(\gamma \cdot p_{\text i}\) and a random force \(\xi\), equation (3). The friction coefficient \(\gamma\) can be set with the Friction keyword. Enforces a canonical kinetic energy distribution. However, the Langevin thermostat is unable to conserve the total momentum of the system, which may lead to critical errors in the resulting dynamical data.
(3)\[m_{\text i} \dot{v}_{\text i} = F_{\text i} - \gamma \cdot p_{\text i} + \xi\]nh-chain - temperature coupling via Nose Hoover extended Lagrangian. Based on modifying the forces after each time step. The length of the Nose Hoover chain and the coupling frequency can be set with the NH-Chain Length and the Coupling Frequency keywords, respectively. Enforces a canonical kinetic energy distribution.
Temperature Relaxation Time
This keyword is used in combination with the Berendsen and velocity rescaling thermostat.
Key
t_relaxation = {double} ps -> 0.1 ps
With the t_relaxation keyword the relaxation time in ps (i.e. \(\tau\)) of the Berendsen or stochastic velocity rescaling thermostat is set, see equations (1) and (2).
default value = 1.0 ps
Friction
Key
friction = {double} ps⁻¹ -> 0.1 ps⁻¹
With the friction keyword the friction coefficient \(\gamma\) in ps⁻¹ of the Langevin thermostat, equation (3), can be set.
default value = 0.1 ps⁻¹
NH-Chain Length
Key
nh-chain_length = {uint+} -> 3
With the nh-chain_length keyword the length of the chain for temperature control via an extended Nose-Hoover Lagrangian can be set.
default value = 3
Coupling Frequency
Key
coupling_frequency = {double} cm⁻¹ -> 1000 cm⁻¹
With the coupling_frequency keyword the coupling frequency of the Nose-Hoover chain in cm⁻¹ can be set.
default value = 1000 cm⁻¹
Pressure Coupling Keys
Pressure
Key
pressure = {double} bar
With the pressure keyword the target pressure in bar of the system can be set.
Note
This keyword is only used if a manostat for controlling the pressure is explicitly defined.
Manostat
Key
manostat = {string} -> “none”
With the manostat keyword the type of pressure coupling can be chosen.
Possible options are:
none (default) - no pressure coupling is applied (i.e. constant volume)
berendsen - Berendsen weak coupling manostat
stochastic_rescaling - stochastic cell rescaling manostat
Pressure Relaxation
This keyword is used in combination with the Berendsen and stochastic cell rescaling manostat.
Key
p_relaxation = {double} ps -> 1.0 ps
With the p_relaxation keyword the relaxation time in ps (i.e. \(\tau\)) of the Berendsen or stochastic cell rescaling manostat is set.
default value = 0.1 ps
Compressibility
This keyword is used in combination with the Berendsen and stochastic cell rescaling manostat.
Key
compressibility = {double} bar⁻¹ -> 4.591e-5 bar⁻¹
With the compressibility keyword the user can specify the compressibility of the target system in bar⁻¹ for the Berendsen and stochastic cell rescaling manostat.
default value = 4.591e-5 bar⁻¹ (compressibility of water)
Isotropy
Key
isotropy = {string} -> “isotropic”
With the isotropy keyword the isotropy of the pressure coupling for all manostat types is controlled.
Possible options are:
isotropic (default) - all axes are scaled with the same scaling factor
xy - semi-isotropic settings, with axes
xandycoupled isotropicxz - semi-isotropic settings, with axes
xandzcoupled isotropicyz - semi-isotropic settings, with axes
yandzcoupled isotropicanisotropic - all axes are coupled in an anisotropic way
full_anisotropic - all axes are coupled in an anisotropic way and the box angles are also scaled
Reset Kinetics Keys
NScale
Key
nscale = {uint} -> 0
With the nscale keyword the user can specify the first n steps in which the temperature is reset via a hard scaling approach to the target temperature.
Note
Resetting the temperature to the target temperature does imply also a subsequent reset of the total box momentum. Furthermore, resetting to the target temperature does not necessarily require a constant temperature ensemble setting.
default value = 0 (i.e. never)
FScale
Key
fscale = {uint} -> nstep + 1
With the fscale keyword the user can specify the frequency f at which the temperature is reset via a hard scaling approach to the target temperature.
Note
Resetting the temperature to the target temperature does imply also a subsequent reset of the total box momentum. Furthermore, resetting to the target temperature does not necessarily require a constant temperature ensemble setting.
default value = nstep + 1 (i.e. never)
special case = 0 -> nstep + 1
NReset
Key
nreset = {uint} -> 0
With the nreset keyword the user can specify the first n steps in which the total box momentum is reset.
default value = 0 (i.e. never)
FReset
Key
freset = {uint} -> nstep + 1
With the freset keyword the user can specify the frequency f at which the total box momentum is reset.
default value = nstep + 1 (i.e. never)
special case = 0 -> nstep + 1
NReset Angular
Key
nreset_angular = {uint} -> 0
With the nreset_angular keyword the user can specify the first n steps in which the total angular box momentum is reset.
Danger
This setting should be used very carefully, since in periodic systems a reset of the angular momentum can result in severe unphysical behavior.
default value = 0 (i.e. never)
FReset Angular
Key
freset_angular = {uint} -> nstep + 1
With the freset_angular keyword the user can specify the frequency f at which the total angular box momentum is reset.
Danger
This setting should be used very carefully, since in periodic systems a reset of the angular momentum can result in severe unphysical behavior.
default value = nstep + 1 (i.e. never)
special case = 0 -> nstep + 1
FReset Forces
Key
freset_forces = {uint} -> nstep + 1
With the freset_forces keyword the user can specify the frequency f at which the total force of the system is reset. At each reset step the average force vector is subtracted from every atom, so that the summed force over all atoms is zero.
default value = nstep + 1 (i.e. never)
special case = 0 -> nstep + 1
Constraints Keys
Shake
Key
shake = {string} -> “off”
With the shake keyword the SHAKE/RATTLE algorithm for bond constraints can be activated.
Possible options are:
off (default) - no shake will be applied
on or shake - SHAKE for bond constraints defined in the Topology File will be applied.
mshake - M-SHAKE for bond constraints defined in a special M-SHAKE File will be applied. As the M-SHAKE algorithm is designed for the treatment of rigid body molecular units the general shake algorithm will be activated automatically along with the M-SHAKE algorithm. The shake bonds can be defined as usual in the Topology File and if no SHAKE bonds are defined only the M-SHAKE algorithm will be applied (without any overhead)
Shake Tolerance
Key
shake-tolerance = {double} -> 1e-8
With the shake-tolerance keyword the user can specify the tolerance, with which the bond length of the shaked bonds should converge.
default value = 1e-8
Shake Iteration
Key
shake-iter = {uint+} -> 20
With the shake-iter keyword the user can specify the maximum number of iterations until the convergence of the bond lengths should be reached within the shake algorithm.
default value = 20
Rattle Tolerance
Key
rattle-tolerance = {double} s⁻¹kg⁻¹ -> 1e4 s⁻¹kg⁻¹
With the rattle-tolerance keyword the user can specify the tolerance in s⁻¹kg⁻¹, with which the velocities of the shaked bonds should converge.
default value = 1e4 s⁻¹kg⁻¹
Rattle Iteration
Key
rattle-iter = {uint+} -> 20
With the rattle-iter keyword the user can specify the maximum number of iterations until the convergence of the velocities of the shaked bonds should be reached within the rattle algorithm.
default value = 20
MShake Tolerance
Key
mshake-tolerance = {double} -> 1e-8
With the mshake-tolerance keyword the user can specify the tolerance, with which the bond length of the mshaked bonds should converge.
default value = 1e-8
MShake Iteration
Key
mshake-iter = {uint+} -> 20
With the mshake-iter keyword the user can specify the maximum number of iterations until the convergence of the bond lengths should be reached within the mshake algorithm.
default value = 20
Distance Constraints
Key
distance-constraints = {string} -> “off”
With the distance-constraints keyword it is possible to activate distance constraints for the simulation. The distance constraints are defined via the Topology File.
default value = “off”
MM Keys
NonCoulomb
Key
noncoulomb = {string} -> “guff”
With the noncoulomb keyword the user can specify which kind of GUFF formalism should be used for parsing the GUFF File.
Note
This keyword is only considered if an MM-MD type simulation is requested and the Force Field is turned off.
Possible options are:
guff (default) - full GUFF formalism
lj - Lennard Jones quick routine
buck - Buckingham quick routine
morse - Morse quick routine
Force Field
Key
force-field = {string} -> “off”
With the force-field keyword the user can switch from the GUFF formalism to a force field type simulation. Force field setup files are described in the Setup Files section.
Possible options are:
off (default) - GUFF formalism is applied
on - full force field definition is applied
bonded - non bonded interaction are described via GUFF formalism and bonded interactions via force field approach
Long Range Correction
Long Range
Key
long_range = {string} -> “none”
With the long_range correction keyword the user can specify the type of Coulombic long range correction, which should be applied during the simulation.
Possible options are:
none (default) - no long range correction
reaction-field - reaction field
wolf - Wolf summation
Reaction Field Epsilon
Key
rf_epsilon = {double}
With the rf_epsilon keyword the user can set the static relative permittivity \(\epsilon\) used by the reaction field Coulomb correction. The value must be greater than 1.0.
Note
This keyword has no default value and is therefore mandatory if the long_range keyword is set to reaction-field.
Wolf Parameter
Key
wolf_param = {double} Å⁻¹ -> 0.25 Å⁻¹
With the wolf_param keyword the user can set the damping parameter \(\kappa\) used by the Wolf summation Coulomb correction. The value must be non-negative and is only used if long_range is set to wolf.
default value = 0.25 Å⁻¹
QM Keys
QM Program
Key
qm_prog = {string}
With the qm_prog keyword the external QM engine for any kind of QM MD simulation is chosen.
Note
This keyword is required for any kind of QM MD simulation!
Possible options are:
QM Script
Key
qm_script = {file}
With the qm_script keyword the external executable to run the QM engine and to parse its output is chosen. All possible scripts can be found under https://github.com/MolarVerse/PQ/tree/main/src/QM/scripts. The script name should match the selected QM engine and input format.
QM Script Full Path
Key
qm_script_full_path = {pathFile}
Attention
This keyword can not be used in conjunction with the qm_script keyword! Furthermore, this keyword needs to be used in combination with any singularity or static build of PQ. For further details regarding the compilation/installation please refer to the Installation section.
With the qm_script_full_path keyword the user can specify the full path to the external executable to run the QM engine and to parse its output. All possible scripts can be found under https://github.com/MolarVerse/PQ/tree/main/src/QM/scripts. The script name should match the selected QM engine and input format.
QM Loop Time Limit
Key
qm_loop_time_limit = {double} s -> 3600 s
With the qm_loop_time_limit keyword the user can specify the loop time limit in s of all QM type calculations. If the time limit is reached the calculation will be stopped. Default value is 3600 s (1 hour). Values smaller equal than zero are interpreted as no time limit and the calculation will continue until it is finished.
default value = 3600 s
Dispersion Correction
Key
dispersion = {bool} -> false
With the dispersion keyword the user can activate the dispersion correction for the QM calculations - at the moment only enabled for ASE based QM engines.
default value = false
Remove Net Force
Key
remove_net_force = {bool} -> false
With the remove_net_force keyword the user can request the removal of the net force after reading in forces from the QM program.
Removal is achieved by distributing the total net force evenly across all atoms in the system.
This can increase momentum conservation when using a QM program with limited numerical precision.
default value = false
MACE Model
Key
mace_model = {string} -> “medium”
With the mace_model keyword the user can specify the MACE model for the QM calculations.
Possible options are:
small - small MACE model
medium (default) - medium MACE model
large - large MACE model
small-0b - small MACE-MP-0b model
medium-0b - medium MACE-MP-0b model
small-0b2 - small MACE-MP-0b2 model
medium-0b2 - medium MACE-MP-0b2 model
large-0b2 - large MACE-MP-0b2 model
medium-0b3 - medium MACE-MP-0b3 model
medium-mpa-0 - medium MACE-MPA-0 model
medium-omat-0 - medium MACE-OMAT-0 model
custom - custom MACE model (to be set via the mace_model_path keyword)
Note
The qm_prog option mace-off is only compatible with the first three models: “small”, “medium” and “large”
MACE Model Path
Key
mace_model_path = {string}
With the mace_model_path keyword the user can specify a custom URL corresponding to a MACE model for the QM calculations.
Note
The mace_model_path can only be specified if mace_model keyword is set to custom.
MACE Mode
Key
mace_mode = {string} -> “accurate”
With the mace_mode keyword the user can select the evaluation mode / kernel backend of the MACE model for the QM calculations.
Possible options are:
accurate (default) - the exact e3nn reference implementation
fast - cuequivariance-accelerated kernels; substantially faster for MD, but the results are an approximation of (not bit-identical to) the e3nn reference
Note
The fast mode requires cuequivariance, cuequivariance-torch and the matching CUDA ops package cuequivariance-ops-torch-cuXX, where XX is the CUDA major your torch was built against (e.g. cu13 for a CUDA-13 torch build). The ops package is not pulled in automatically by cuequivariance-torch – install it explicitly, e.g. pip install cuequivariance-ops-torch-cu13. Use accurate for the exact e3nn reference.
default value = “accurate”
ASE-xTB Method
Key
xtb-method = {string} -> “GFN2-xTB”
With the xtb-method keyword the user can specify the xTB method of the ase-xtb approach for the extended tight-binding calculation.
Possible options are:
GFN1-xTB - GFN1-xTB parametrization
GFN2-xTB (default) - GFN2-xTB parametrization
IPEA1-xTB - IPEA-xTB parametrization
ASE-DFTB+ Approach
Key
slakos = {string}
With the slakos keyword the user can specify the type of the ase-dftbplus approach for DFTB+ calculations.
It is required when qm_prog = ase-dftbplus.
Possible options are:
3ob - 3ob parameters
matsci - matsci parameters
custom - custom parameters (see Slater-Koster Path)
Slater-Koster Path
Key
slakos_path = {pathFile}
With the slakos_path keyword the user can specify the path to the Slater-Koster files for ASE DFTB+ calculations. Is only compatible, but mandatory if the slakos keyword is set to custom.
Third-Order
Key
third_order = {bool} -> false
With the third_order keyword the user can activate the 3rd order DFTB expansion according to Grimme et al. for ASE DFTB+ calculations. Is automatically set to true if the slakos keyword is set to 3ob.
default value = false
Hubbard Derivatives
Key
hubbard_derivs = {dict}
If the Slater-Koster parameters are of DFTB3 type, the Hubbard derivatives can be set with the hubbard_derivs keyword. The Hubbard derivatives are given as a dictionary with the chemical element as key and the Hubbard derivative as value. Standard Hubbard derivatives for slakos 3ob are preset according to dftb.org and can be overwritten by the user.
Example
hubbard_derivs = C: 0.1, H: 0.2, O: 0.3;
FeNNol Model Path
Key
fennol_model_path = {string}
With the fennol_model_path keyword the path to the FeNNol model to be used can be specified.
Note
The fennol_model_path keyword is mandatory when the qm_prog keyword is set to fennol.
GPU Pre-processing
Key
gpu_preprocessing = {bool} -> true
With the gpu_preprocessing keyword the user can activate/deactivate the GPU preprocessing step of the FeNNol QM runner.
default value = true
Ring Polymer MD Keys
RPMD n replica
Key
rpmd_n_replica = {uint+}
With the rpmd_n_replica keyword the number of beads for a ring polymer MD simulation is controlled.
Note
This keyword is required for any kind of ring polymer MD simulation!
QM/MM Keys
QM Center
Key
qm_center = {selection} -> 0
With the qm_center keyword the user can specify the center of the QM region. The default selection is the first atom of the system (i.e. 0). For more information about the selection grammar see the selectionType section. The qm_center if more than one atom is selected will be by default the center of mass of the selected atoms.
default value = 0
QM Only List
Key
qm_only_list = {selection}
With the qm_only_list keyword the user can specify a list of atoms which should be treated as QM atoms only. This means that these atoms can not leave the QM region during the simulation. For more information about the selection grammar see the selectionType section. By default no atoms are selected.
MM Only List
Key
mm_only_list = {selection}
With the mm_only_list keyword the user can specify a list of atoms which should be treated as MM atoms only. This means that these atoms can not enter the QM region during the simulation. For more information about the selection grammar see the selectionType section. By default no atoms are selected.
QM Charges
Key
qm_charges = {string} -> “off”
With the qm_charges keyword the user can specify the charge model for the QM atoms.
Possible options are:
off (default) - charges of the QM atoms are taken from the MM model
on - charges of the QM atoms are taken from the QM calculation
QM Core Radius
Key
qm_core_radius = {double} \(\mathrm{\mathring{A}}\) -> 0.0 \(\mathrm{\mathring{A}}\)
With the qm_core_radius keyword the user can specify the core radius in \(\mathrm{\mathring{A}}\) around the qm_center. The default value is 0.0 \(\mathrm{\mathring{A}}\), which means that the core radius is not set and only explicit QM atoms are used for the QM region.
default value = 0.0 Å
QM/MM Layer Radius
Key
qmmm_layer_radius = {double} \(\mathrm{\mathring{A}}\) -> 0.0 \(\mathrm{\mathring{A}}\)
With the qmmm_layer_radius keyword the user can specify the layer radius in \(\mathrm{\mathring{A}}\) around the qm_center. The default value is 0.0 \(\mathrm{\mathring{A}}\), which means that no special QM/MM treatment is applied.
default value = 0.0 Å
QM/MM Smoothing Radius
Key
qmmm_smoothing_radius = {double} \(\mathrm{\mathring{A}}\) -> 0.0 \(\mathrm{\mathring{A}}\)
With the qmmm_smoothing_radius keyword the user can specify the smoothing radius in \(\mathrm{\mathring{A}}\) of the QM atoms. The default value is 0.0 \(\mathrm{\mathring{A}}\), which means that the smoothing radius is not set and no smoothing is applied.
default value = 0.0 Å
Cell List Keys
Cell List
Key
cell-list = {string} -> “off”
With the cell-list the user can activate a cell-list approach to calculate the pair-interactions in MM-MD simulations (no effect in pure QM-MD type simulations).
Possible options are:
off (default) - brute force routine
on - cell list approach is applied
Cell Number
Key
cell-number = {uint+} -> 7
With the cell-number keyword the user can set the number of cells in each direction in which the simulation box will be split up (e.g. cell-number = 7 -> total cells = 7x7x7)
default value = 7
Optimization Keys
In order to perform a geometry optimization one of the optimizer Jobtypes has to be chosen.
Optimizer
Key
optimizer = {string}
This keyword is mandatory for any kind of geometry optimization. The user has to specify the optimizer which should be used for the optimization.
Possible options are:
steepest-descent - steepest descent optimizer
ADAM - ADAM optimizer
Learning Rate Strategy
Key
learning-rate-strategy = {string} -> “exponential-decay”
With the learning-rate-strategy keyword the user can specify the learning rate strategy for all kind of optimization jobs.
Possible options are:
exponential-decay (default) - exponential decay of the learning rate
constant - constant learning rate
constant-decay - constant decay of the learning rate
Initial Learning Rate
Key
initial-learning-rate = {double} -> 0.0001
With the initial-learning-rate keyword the user can specify the initial learning rate for all kind of optimization jobs.
default value = 0.0001
Learning Rate Decay
Key
learning-rate-decay = {double}
With the learning-rate-decay keyword the user can specify the decay speed of the learning rate. Pay attention this key is used at the moment for different kind of decay strategies and therefore the value is dependent on the chosen strategy.
Convergence Keys
Energy Convergence Strategy
In general the convergence of the geometry optimization is checked by assuring that the absolute and relative energy difference between two consecutive steps is smaller than a certain threshold. The user can choose between different strategies to change this behavior.
Key
energy-conv-strategy = {string} -> “rigorous”
With the energy-conv-strategy keyword the user can specify the energy convergence strategy for all kind of optimization jobs.
Possible options are:
rigorous (default) - both absolute and relative energy difference have to be smaller than the threshold
loose - only one of the two energy differences has to be smaller than the threshold
relative - only the relative energy difference has to be smaller than the threshold
absolute - only the absolute energy difference has to be smaller than the threshold
Enable/Disable Energy Convergence Check
Key
use-energy-conv = {bool} -> true
With the use-energy-conv keyword the user can enable or disable the energy convergence check for all kind of optimization jobs.
default value = true
Enable/Disable MAX Force Convergence Check
Key
use-max-force-conv = {bool} -> true
With the use-max-force-conv keyword the user can enable or disable the maximum force convergence check for all kind of optimization jobs.
default value = true
Enable/Disable RMS Force Convergence Check
Key
use-rms-force-conv = {bool} -> true
With the use-rms-force-conv keyword the user can enable or disable the root mean square force convergence check for all kind of optimization jobs.
default value = true
Energy Convergence Threshold
Key
energy-conv = {double} -> 1e-6
With the energy-conv keyword the user can specify the energy convergence threshold for all kind of optimization jobs.
This keyword will set both the absolute and relative energy convergence threshold.
default value = 1e-6
Relative Energy Convergence Threshold
Key
rel-energy-conv = {double} -> 1e-6
With the rel-energy-conv keyword the user can specify the relative energy convergence threshold for all kind of optimization jobs. This keyword overrides the energy-conv keyword.
default value = 1e-6
Absolute Energy Convergence Threshold
Key
abs-energy-conv = {double} -> 1e-6
With the abs-energy-conv keyword the user can specify the absolute energy convergence threshold for all kind of optimization jobs. This keyword overrides the energy-conv keyword.
default value = 1e-6
Force Convergence Threshold
Key
force-conv = {double} -> 1e-6
With the force-conv keyword the user can specify the force convergence threshold for all kind of optimization jobs. This keyword will set both the maximum and root mean square force convergence threshold.
default value = 1e-6
Maximum Force Convergence Threshold
Key
max-force-conv = {double} -> 1e-6
With the max-force-conv keyword the user can specify the maximum force convergence threshold for all kind of optimization jobs. This keyword overrides the force-conv keyword.
default value = 1e-6
RMS Force Convergence Threshold
Key
rms-force-conv = {double} -> 1e-6
With the rms-force-conv keyword the user can specify the root mean square force convergence threshold for all kind of optimization jobs. This keyword overrides the force-conv keyword.
default value = 1e-6
Hessian Keys
The Hessian keys configure mm-hessian runs. The generated Hessian can be analyzed with the PQAnalysis vibrations input-file command.
Hessian File
Key
hessian_file = {file} -> “default.hessian”
The hessian_file keyword sets the plain text matrix output file for the Cartesian Hessian.
default value = “default.hessian”
Hessian Info File
Key
hessian_info_file = {file} -> “default.hessian.info”
The hessian_info_file keyword sets the metadata output file for the Hessian run. The file records the Hessian builder, displacement, unit, sign convention, matrix dimensions and whether the geometry was optimized before the Hessian was calculated.
default value = “default.hessian.info”
Hessian Displacement
Key
hessian_displacement = {double} -> 1.0e-3
The hessian_displacement keyword sets the Cartesian displacement used by finite-difference Hessian builders. The value must be greater than zero.
default value = 1.0e-3
Optimize Before Hessian
Key
optimize_before_hessian = {bool} -> true
The optimize_before_hessian keyword controls whether mm-hessian first performs a geometry optimization using the normal Optimization Keys and Convergence Keys. The default is true because vibrational frequencies are meaningful at stationary points. Set it to false for a Hessian at the input geometry, for example when the geometry was optimized in a previous run or by an external program.
default value = true
Hessian Builder
Key
hessian_builder = {string} -> “central”
The hessian_builder keyword selects how the Hessian is generated.
Possible options are:
central (default) - central finite differences of forces
forward - forward finite differences of forces
five-point - five-point finite differences of forces
analytic - analytic Hessian evaluator hook, available only for evaluators that implement it
default value = “central”
Comments
Every character following a
#will be ignored. The#as a comment flag can be used also in all setup files - with some exceptions when contiguous input blocks are necessary.