Source code for scm.input_classes.drivers.conformers
from __future__ import annotations
from pathlib import Path
from typing import Iterable, Literal, Sequence
from scm.pisa.block import DriverBlock,EngineBlock,FixedBlock,FreeBlock,InputBlock
from scm.pisa.key import BoolKey,FloatKey,FloatListKey,IntKey,IntListKey,MultipleChoiceKey,PathStringKey,StringKey,BoolType
[docs]class Conformers(DriverBlock):
r"""
:ivar InputConformersSet: The path to a file containing a set of conformers.
The file should be either an 'conformers.rkf' file (i.e. the results file of conformers), a concatenated .xyz file, a .sdf file, or even .dcd file. In the case of a .dcd file, an additional System block is required. If the specified file does not contain energies in the AMS conformers format (as produced by the conformers tool), all conformer energies will be set to zero.
You can specify multiple input conformers sets by including the InputConformersSet keyword multiple times.
:vartype InputConformersSet: str | Path | StringKey
:ivar InputMaxConfs: The maximum number of conformers to carry forward when loading conformer sets. If this input is not specified, this limit will not be imposed.
:vartype InputMaxConfs: int | IntKey
:ivar InputMaxEnergy: Threshold for filtering out high-energy conformers when loading conformers sets using the InputConformerSet keyword. Conformers with an larger relative energy will not be loaded.
:vartype InputMaxEnergy: float | FloatKey
:ivar RNGSeed: Initial seed for the (pseudo)random number generator. If this is unset, the generator will be seeded randomly from external sources of entropy and the generated conformers will be non-deterministic.
:vartype RNGSeed: int | IntKey
:ivar Task: The task to be performed by the Conformers tool.
'Generate': given a molecule, generate a set of conformers. Note: this task will automatically optimize, filter and score the conformers.
'Optimize': given a previously generated set of conformers, optimize, filter and score the structures using the specified engine.
'Filter': given one or more previously generated set of conformers, merge them into a single conformer set and filter out duplicate conformers. Note: this will not optimize or re-score the conformers.
'Score' given one or more previously generated set of conformers, re-score them by computing the energy using the specified engine. Note: this will only do a single point calculation, and will not optimize the structures.
In case of 'Optimize', 'Filter' and 'Score' you can specify the input conformer set(s) using the 'InputConformersSet' keyword.
:vartype Task: Literal["Generate", "Optimize", "Filter", "Score", "Expand"]
:ivar Constraints: The Constraints block allows geometry optimizations and potential energy surface scans with constraints. The constraints do not have to be satisfied at the start of the calculation.
:vartype Constraints: Conformers._Constraints
:ivar Engine: The input for the computational engine used to compute energy and forces.
:vartype Engine: EngineBlock
:ivar EngineAddons: This block configures all the engine add-ons.
:vartype EngineAddons: Conformers._EngineAddons
:ivar Equivalence: Options for the procedure determining whether two structures are equivalent or distinct conformers.
:vartype Equivalence: Conformers._Equivalence
:ivar Expander: Options for the conformer expander. The Expander expands an existing conformer set, by adding new conformers to it. The new conformers are generated from the original conformers in the set. Unlike the generators, the outcome of an expander is therefore very dependent on the input conformations.
The GC generator uses a genetic algorithm to create a combinatorial expansion by combining local substructures.
The MD expander start MD simulations from the conformers in the set, and extracts snapshots to create new conformers. Both these expanders are part of the CREST generator.
:vartype Expander: Conformers._Expander
:ivar Filter: Options for the conformer filtering.
:vartype Filter: Conformers._Filter
:ivar Generator: Options for the conformer generator.
:vartype Generator: Conformers._Generator
:ivar GeometryOptimization: Some options / details regarding the optimization procedure.
:vartype GeometryOptimization: Conformers._GeometryOptimization
:ivar LoadSystem: Block that controls reading the chemical system from a KF file instead of the [System] block.
:vartype LoadSystem: Conformers._LoadSystem
:ivar Output: Options regarding the output and result files.
:vartype Output: Conformers._Output
:ivar Restraints: The Restraints block allows to add soft constraints to the system. A restraint is a potential energy function (a spring) attached to a certain coordinate, for example, an interatomic distance, with its minimum at the specified optimal value. A restraint is defined using one or two parameters: the ForceConstant and, for some types, the F(Inf) value. The ForceConstant parameter corresponds to second derivative of the restraint potential energy d2V(x)/dx^2 for any x (harmonic restraints) or only at at x=0 (other restraints). Here, x is a deviation from the restraint's optimal value.
:vartype Restraints: Conformers._Restraints
:ivar Rotamers: Options for the treatment of Grimme-rotamers.
:vartype Rotamers: Conformers._Rotamers
:ivar System: Specification of the chemical system. For some applications more than one system may be present in the input. In this case, all systems except one must have a non-empty string ID specified after the System keyword. The system without an ID is considered the main one.
:vartype System: Conformers._System
"""
[docs] class _Constraints(FixedBlock):
r"""
The Constraints block allows geometry optimizations and potential energy surface scans with constraints. The constraints do not have to be satisfied at the start of the calculation.
:ivar All: Fix multiple distances using one the following formats:
All [bondOrder] bonds at1 at2 [to distance]
All triangles at1 at2 at3
The first option constrains all bonds between atoms at1 at2 to a certain length, while the second - bonds at1-at2 and at2-at3 as well as the angle between them.
The [bondOrder] can be a number or a string such as single, double, triple or aromatic. If it's omitted then any bond between specified atoms will be constrained. Atom names are case-sensitive and they must be as they are in the Atoms block, or an asterisk '*' denoting any atom. If the distance is omitted then the bond length from the initial geometry is used.
Important: only the bonds present in the system at the start of the simulation can be constrained, which means that the bonds may need to be specified in the System block.
Valid examples:
All single bonds C C to 1.4
All bonds O H to 0.98
All bonds O H
All bonds H *
All triangles H * H
:vartype All: str | StringKey
:ivar Angle: Fix the angle between three atoms. Three atom indices followed by an angle in degrees.
:vartype Angle: str | StringKey
:ivar Atom: Fix the position of an atom. Just one integer referring to the index of the atom in the [System%Atoms] block.
:vartype Atom: int | IntKey
:ivar AtomList: Fix positions of the specified atoms. A list of integers referring to indices of atoms in the [System%Atoms] block.
:vartype AtomList: Iterable[int] | IntListKey
:ivar Block: Name of the region to constrain as a rigid block. Regions are specified in the System%Atoms block.
:vartype Block: str | StringKey
:ivar BlockAtoms: List of atom indices for a block constraint, where the internal degrees of freedom are frozen.
:vartype BlockAtoms: Iterable[int] | IntListKey
:ivar Coordinate: Fix a particular coordinate of an atom. Atom index followed by (x|y|z).
:vartype Coordinate: str | StringKey
:ivar DifDist: Four atom indices i j k l followed by the distance in Angstrom. This will constrain the difference R(ij)-R(kl) at the given value.
:vartype DifDist: str | StringKey
:ivar Dihedral: Fix the dihedral angle between four atoms. Four atom indices followed by an angle in degrees.
:vartype Dihedral: str | StringKey
:ivar Distance: Fix the distance between two atoms. Two atom indices followed by the distance in Angstrom.
:vartype Distance: str | StringKey
:ivar EqualStrain: Exclusively for lattice optimizations:
Accepts a set of strain components [xx, xy, xz, yy, yz, zz] which are to be kept equal.
The applied strain will be determined by the average of the corresponding stress tensors components.
In AMSinput just check the corresponding check buttons.
:vartype EqualStrain: str | StringKey
:ivar FixedRegion: Fix positions of all atoms in a region.
:vartype FixedRegion: str | StringKey
:ivar FreezeStrain: Exclusively for lattice optimizations:
Freezes any lattice deformation corresponding to a particular component of the strain tensor.
Accepts a set of strain components [xx, xy, xz, yy, yz, zz] to be frozen.
In AMSinput just check the corresponding check buttons.
:vartype FreezeStrain: str | StringKey
:ivar SumDist: Four atom indices i j k l followed by the distance in Angstrom. This will constrain the sum R(ij)+R(kl) at the given value.
:vartype SumDist: str | StringKey
"""
def __post_init__(self):
self.All: str | StringKey = StringKey(name='All', comment="Fix multiple distances using one the following formats: \nAll [bondOrder] bonds at1 at2 [to distance]\nAll triangles at1 at2 at3\n\nThe first option constrains all bonds between atoms at1 at2 to a certain length, while the second - bonds at1-at2 and at2-at3 as well as the angle between them.\n\nThe [bondOrder] can be a number or a string such as single, double, triple or aromatic. If it's omitted then any bond between specified atoms will be constrained. Atom names are case-sensitive and they must be as they are in the Atoms block, or an asterisk '*' denoting any atom. If the distance is omitted then the bond length from the initial geometry is used.\n\nImportant: only the bonds present in the system at the start of the simulation can be constrained, which means that the bonds may need to be specified in the System block.\n\nValid examples:\nAll single bonds C C to 1.4\nAll bonds O H to 0.98\nAll bonds O H\nAll bonds H *\nAll triangles H * H", unique=False)
self.Angle: str | StringKey = StringKey(name='Angle', comment='Fix the angle between three atoms. Three atom indices followed by an angle in degrees.', unique=False)
self.Atom: int | IntKey = IntKey(name='Atom', comment='Fix the position of an atom. Just one integer referring to the index of the atom in the [System%Atoms] block.', unique=False)
self.AtomList: Iterable[int] | IntListKey = IntListKey(name='AtomList', comment='Fix positions of the specified atoms. A list of integers referring to indices of atoms in the [System%Atoms] block.', unique=False)
self.Block: str | StringKey = StringKey(name='Block', comment='Name of the region to constrain as a rigid block. Regions are specified in the System%Atoms block.', unique=False, gui_type='region')
self.BlockAtoms: Iterable[int] | IntListKey = IntListKey(name='BlockAtoms', comment='List of atom indices for a block constraint, where the internal degrees of freedom are frozen.', unique=False)
self.Coordinate: str | StringKey = StringKey(name='Coordinate', comment='Fix a particular coordinate of an atom. Atom index followed by (x|y|z).', unique=False)
self.DifDist: str | StringKey = StringKey(name='DifDist', comment='Four atom indices i j k l followed by the distance in Angstrom. This will constrain the difference R(ij)-R(kl) at the given value.', unique=False)
self.Dihedral: str | StringKey = StringKey(name='Dihedral', comment='Fix the dihedral angle between four atoms. Four atom indices followed by an angle in degrees.', unique=False)
self.Distance: str | StringKey = StringKey(name='Distance', comment='Fix the distance between two atoms. Two atom indices followed by the distance in Angstrom.', unique=False)
self.EqualStrain: str | StringKey = StringKey(name='EqualStrain', comment='Exclusively for lattice optimizations:\n\nAccepts a set of strain components [xx, xy, xz, yy, yz, zz] which are to be kept equal.\n\nThe applied strain will be determined by the average of the corresponding stress tensors components.\n\nIn AMSinput just check the corresponding check buttons.')
self.FixedRegion: str | StringKey = StringKey(name='FixedRegion', comment='Fix positions of all atoms in a region.', unique=False, gui_type='region')
self.FreezeStrain: str | StringKey = StringKey(name='FreezeStrain', comment='Exclusively for lattice optimizations:\n\nFreezes any lattice deformation corresponding to a particular component of the strain tensor.\n\nAccepts a set of strain components [xx, xy, xz, yy, yz, zz] to be frozen.\n\nIn AMSinput just check the corresponding check buttons.')
self.SumDist: str | StringKey = StringKey(name='SumDist', comment='Four atom indices i j k l followed by the distance in Angstrom. This will constrain the sum R(ij)+R(kl) at the given value.', unique=False)
[docs] class _Engine(EngineBlock):
r"""
The input for the computational engine used to compute energy and forces.
"""
def __post_init__(self):
pass
[docs] class _EngineAddons(FixedBlock):
r"""
This block configures all the engine add-ons.
:ivar Pressure: Add a hydrostatic pressure term to the engine's energy and stress tensor. Can only be used for 3D periodic boundary conditions.
:vartype Pressure: float | FloatKey
:ivar AtomEnergies: Add an element-dependent energy per atom. On each line, give the chemical element followed by the energy (in atomic units).
:vartype AtomEnergies: str | Sequence[str] | FreeBlock
:ivar D3Dispersion: This block configures the add-on that adds the Grimme D3 dispersion correction to the engine's energy, gradients, and stress tensor.
:vartype D3Dispersion: Conformers._EngineAddons._D3Dispersion
:ivar D4Dispersion: This block configures the addon that adds the Grimme D4(EEQ) dispersion correction to the engine's energy, gradients, stress tensor and Hessian.
:vartype D4Dispersion: Conformers._EngineAddons._D4Dispersion
:ivar ExternalEngine: External engine as an addon
:vartype ExternalEngine: Conformers._EngineAddons._ExternalEngine
:ivar ExternalStress: This block configures the addon that adds external stress term to the engine's energy and stress tensor.
:vartype ExternalStress: Conformers._EngineAddons._ExternalStress
:ivar PipeEngine: Pipe engine as an addon
:vartype PipeEngine: Conformers._EngineAddons._PipeEngine
:ivar Repulsion: This block configures an addon that adds a repulsive Weeks-Chandler-Andersen potential to all atom pairs.
:vartype Repulsion: Conformers._EngineAddons._Repulsion
:ivar WallPotential: This block configures the addon that adds a spherical wall potential to the engine's energy and gradients.
:vartype WallPotential: Conformers._EngineAddons._WallPotential
"""
[docs] class _AtomEnergies(FreeBlock):
r"""
Add an element-dependent energy per atom. On each line, give the chemical element followed by the energy (in atomic units).
"""
def __post_init__(self):
pass
[docs] class _D3Dispersion(FixedBlock):
r"""
This block configures the add-on that adds the Grimme D3 dispersion correction to the engine's energy, gradients, and stress tensor.
:ivar Damping: Type of damping: BJ (Becke-Johnson) or Zero. BJ is recommended for most applications.
:vartype Damping: Literal["BJ", "Zero"]
:ivar Enabled: Enables the D3 dispersion correction addon.
:vartype Enabled: BoolType | BoolKey
:ivar Functional: Use the D3 parameterization by Grimme for a given xc-functional. Accepts the same values as the --func command line option of the official dftd3 program. Note: the naming convention is different from elsewhere in the AMS suite. For example, BLYP should be called b-lyp.
:vartype Functional: str | StringKey
:ivar a1: The a1 parameter. Only used if Damping is set to BJ. If set, it overwrites the a1 value for the chosen functional.
:vartype a1: float | FloatKey
:ivar a2: The a2 parameter. Only used if Damping is set to BJ. If set, it overwrites the a2 value for the chosen functional.
:vartype a2: float | FloatKey
:ivar alp: The a2 parameter. Only used if Damping is set to BJ. If set, it overwrites the a2 value for the chosen functional.
:vartype alp: float | FloatKey
:ivar s6: The s6 parameter, global scaling parameter. If set, it overwrites the s6 value for the chosen functional.
:vartype s6: float | FloatKey
:ivar s8: The s8 parameter. If set, it overwrites the s8 value for the chosen functional.
:vartype s8: float | FloatKey
:ivar sr6: The sr6 parameter. Only used if Damping is set to Zero. If set, it overwrites the sr6 value for the chosen functional.
:vartype sr6: float | FloatKey
"""
def __post_init__(self):
self.Damping: Literal["BJ", "Zero"] = MultipleChoiceKey(name='Damping', comment='Type of damping: BJ (Becke-Johnson) or Zero. BJ is recommended for most applications.', default='BJ', choices=['BJ', 'Zero'])
self.Enabled: BoolType | BoolKey = BoolKey(name='Enabled', comment='Enables the D3 dispersion correction addon.', gui_name='D3 dispersion:', default=False)
self.Functional: str | StringKey = StringKey(name='Functional', comment='Use the D3 parameterization by Grimme for a given xc-functional. Accepts the same values as the --func command line option of the official dftd3 program. Note: the naming convention is different from elsewhere in the AMS suite. For example, BLYP should be called b-lyp.', default='PBE')
self.a1: float | FloatKey = FloatKey(name='a1', comment='The a1 parameter. Only used if Damping is set to BJ. If set, it overwrites the a1 value for the chosen functional.')
self.a2: float | FloatKey = FloatKey(name='a2', comment='The a2 parameter. Only used if Damping is set to BJ. If set, it overwrites the a2 value for the chosen functional.')
self.alp: float | FloatKey = FloatKey(name='alp', comment='The a2 parameter. Only used if Damping is set to BJ. If set, it overwrites the a2 value for the chosen functional.', hidden=True)
self.s6: float | FloatKey = FloatKey(name='s6', comment='The s6 parameter, global scaling parameter. If set, it overwrites the s6 value for the chosen functional.')
self.s8: float | FloatKey = FloatKey(name='s8', comment='The s8 parameter. If set, it overwrites the s8 value for the chosen functional.')
self.sr6: float | FloatKey = FloatKey(name='sr6', comment='The sr6 parameter. Only used if Damping is set to Zero. If set, it overwrites the sr6 value for the chosen functional.')
[docs] class _D4Dispersion(FixedBlock):
r"""
This block configures the addon that adds the Grimme D4(EEQ) dispersion correction to the engine's energy, gradients, stress tensor and Hessian.
:ivar Enabled: Enables the D4 dispersion correction addon.
:vartype Enabled: BoolType | BoolKey
:ivar Functional: Use the D4 parameterization by Grimme for a given xc-functional.
:vartype Functional: Literal["HF", "BLYP", "BPBE", "BP86", "BPW", "LB94", "MPWLYP", "MPWPW91", "OLYP", "OPBE", "PBE", "RPBE", "REVPBE", "PW86PBE", "RPW86PBE", "PW91", "PW91P86", "XLYP", "B97", "TPSS", "REVTPSS", "SCAN", "B1LYP", "B3LYP", "BHLYP", "B1P86", "B3P86", "B1PW91", "B3PW91", "O3LYP", "REVPBE0", "REVPBE38", "PBE0", "PWP1", "PW1PW", "MPW1PW91", "MPW1LYP", "PW6B95", "TPSSH", "TPSS0", "X3LYP", "M06L", "M06", "OMEGAB97", "OMEGAB97X", "CAM-B3LYP", "LC-BLYP", "LH07TSVWN", "LH07SSVWN", "LH12CTSSIRPW92", "LH12CTSSIFPW92", "LH14TCALPBE", "B2PLYP", "B2GPPLYP", "MPW2PLYP", "PWPB95", "DSDBLYP", "DSDPBE", "DSDPBEB95", "DSDPBEP86", "DSDSVWN", "DODBLYP", "DODPBE", "DODPBEB95", "DODPBEP86", "DODSVWN", "PBE02", "PBE0DH", "DFTB(3ob)", "DFTB(mio)", "DFTB(pbc)", "DFTB(matsci)", "DFTB(ob2)", "B1B95", "MPWB1K", "REVTPSSH", "GLYP", "REVPBE0DH", "REVTPSS0", "REVDSDPBEP86", "REVDSDPBEPBE", "REVDSDBLYP", "REVDODPBEP86", "B97M", "OMEGAB97M", "R2SCAN"]
:ivar Verbosity: Controls the verbosity of the dftd4 code. Equivalent to the --silent and --verbose command line switches of the official dftd4 program.
:vartype Verbosity: Literal["Silent", "Normal", "Verbose", "VeryVerbose"]
:ivar a1: The a1 parameter, see D4 article. The physically reasonable range for a1 is [0.0,1.0]. If set, it overwrites the a1 value for the chosen functional.
:vartype a1: float | FloatKey
:ivar a2: The a2 parameter, see D4 article. The physically reasonable range for a2 is [0.0,7.0]. If set, it overwrites the a2 value for the chosen functional.
:vartype a2: float | FloatKey
:ivar ga: The ga parameter. GCP
:vartype ga: float | FloatKey
:ivar gc: The gc parameter. GCP
:vartype gc: float | FloatKey
:ivar s6: The s6 parameter, see D4 article. The physically reasonable range for s6 is [0.0,1.0]. If set, it overwrites the s6 value for the chosen functional.
:vartype s6: float | FloatKey
:ivar s8: The s8 parameter, see D4 article. The physically reasonable range for s8 is [0.0,3.0]. If set, it overwrites the s8 value for the chosen functional.
:vartype s8: float | FloatKey
:ivar s9: The s9 parameter, see D4 article. If set, it overwrites the s9 value for the chosen functional.
:vartype s9: float | FloatKey
"""
def __post_init__(self):
self.Enabled: BoolType | BoolKey = BoolKey(name='Enabled', comment='Enables the D4 dispersion correction addon.', gui_name='D4 dispersion:', default=False)
self.Functional: Literal["HF", "BLYP", "BPBE", "BP86", "BPW", "LB94", "MPWLYP", "MPWPW91", "OLYP", "OPBE", "PBE", "RPBE", "REVPBE", "PW86PBE", "RPW86PBE", "PW91", "PW91P86", "XLYP", "B97", "TPSS", "REVTPSS", "SCAN", "B1LYP", "B3LYP", "BHLYP", "B1P86", "B3P86", "B1PW91", "B3PW91", "O3LYP", "REVPBE0", "REVPBE38", "PBE0", "PWP1", "PW1PW", "MPW1PW91", "MPW1LYP", "PW6B95", "TPSSH", "TPSS0", "X3LYP", "M06L", "M06", "OMEGAB97", "OMEGAB97X", "CAM-B3LYP", "LC-BLYP", "LH07TSVWN", "LH07SSVWN", "LH12CTSSIRPW92", "LH12CTSSIFPW92", "LH14TCALPBE", "B2PLYP", "B2GPPLYP", "MPW2PLYP", "PWPB95", "DSDBLYP", "DSDPBE", "DSDPBEB95", "DSDPBEP86", "DSDSVWN", "DODBLYP", "DODPBE", "DODPBEB95", "DODPBEP86", "DODSVWN", "PBE02", "PBE0DH", "DFTB(3ob)", "DFTB(mio)", "DFTB(pbc)", "DFTB(matsci)", "DFTB(ob2)", "B1B95", "MPWB1K", "REVTPSSH", "GLYP", "REVPBE0DH", "REVTPSS0", "REVDSDPBEP86", "REVDSDPBEPBE", "REVDSDBLYP", "REVDODPBEP86", "B97M", "OMEGAB97M", "R2SCAN"] = MultipleChoiceKey(name='Functional', comment='Use the D4 parameterization by Grimme for a given xc-functional.', default='PBE', choices=['HF', 'BLYP', 'BPBE', 'BP86', 'BPW', 'LB94', 'MPWLYP', 'MPWPW91', 'OLYP', 'OPBE', 'PBE', 'RPBE', 'REVPBE', 'PW86PBE', 'RPW86PBE', 'PW91', 'PW91P86', 'XLYP', 'B97', 'TPSS', 'REVTPSS', 'SCAN', 'B1LYP', 'B3LYP', 'BHLYP', 'B1P86', 'B3P86', 'B1PW91', 'B3PW91', 'O3LYP', 'REVPBE0', 'REVPBE38', 'PBE0', 'PWP1', 'PW1PW', 'MPW1PW91', 'MPW1LYP', 'PW6B95', 'TPSSH', 'TPSS0', 'X3LYP', 'M06L', 'M06', 'OMEGAB97', 'OMEGAB97X', 'CAM-B3LYP', 'LC-BLYP', 'LH07TSVWN', 'LH07SSVWN', 'LH12CTSSIRPW92', 'LH12CTSSIFPW92', 'LH14TCALPBE', 'B2PLYP', 'B2GPPLYP', 'MPW2PLYP', 'PWPB95', 'DSDBLYP', 'DSDPBE', 'DSDPBEB95', 'DSDPBEP86', 'DSDSVWN', 'DODBLYP', 'DODPBE', 'DODPBEB95', 'DODPBEP86', 'DODSVWN', 'PBE02', 'PBE0DH', 'DFTB(3ob)', 'DFTB(mio)', 'DFTB(pbc)', 'DFTB(matsci)', 'DFTB(ob2)', 'B1B95', 'MPWB1K', 'REVTPSSH', 'GLYP', 'REVPBE0DH', 'REVTPSS0', 'REVDSDPBEP86', 'REVDSDPBEPBE', 'REVDSDBLYP', 'REVDODPBEP86', 'B97M', 'OMEGAB97M', 'R2SCAN'])
self.Verbosity: Literal["Silent", "Normal", "Verbose", "VeryVerbose"] = MultipleChoiceKey(name='Verbosity', comment='Controls the verbosity of the dftd4 code. Equivalent to the --silent and --verbose command line switches of the official dftd4 program.', default='Silent', choices=['Silent', 'Normal', 'Verbose', 'VeryVerbose'])
self.a1: float | FloatKey = FloatKey(name='a1', comment='The a1 parameter, see D4 article. The physically reasonable range for a1 is [0.0,1.0]. If set, it overwrites the a1 value for the chosen functional.')
self.a2: float | FloatKey = FloatKey(name='a2', comment='The a2 parameter, see D4 article. The physically reasonable range for a2 is [0.0,7.0]. If set, it overwrites the a2 value for the chosen functional.')
self.ga: float | FloatKey = FloatKey(name='ga', comment='The ga parameter. GCP', hidden=True)
self.gc: float | FloatKey = FloatKey(name='gc', comment='The gc parameter. GCP', hidden=True)
self.s6: float | FloatKey = FloatKey(name='s6', comment='The s6 parameter, see D4 article. The physically reasonable range for s6 is [0.0,1.0]. If set, it overwrites the s6 value for the chosen functional.')
self.s8: float | FloatKey = FloatKey(name='s8', comment='The s8 parameter, see D4 article. The physically reasonable range for s8 is [0.0,3.0]. If set, it overwrites the s8 value for the chosen functional.')
self.s9: float | FloatKey = FloatKey(name='s9', comment='The s9 parameter, see D4 article. If set, it overwrites the s9 value for the chosen functional.')
[docs] class _ExternalEngine(FixedBlock):
r"""
External engine as an addon
:ivar Execute: execute command
:vartype Execute: str | StringKey
"""
def __post_init__(self):
self.Execute: str | StringKey = StringKey(name='Execute', comment='execute command', gui_name='Execute:')
[docs] class _ExternalStress(FixedBlock):
r"""
This block configures the addon that adds external stress term to the engine's energy and stress tensor.
:ivar StressTensorVoigt: The elements of the external stress tensor in Voigt notation. One should specify 6 numbers for 3D periodic system (order: xx,yy,zz,yz,xz,xy), 3 numbers for 2D periodic systems (order: xx,yy,xy) or 1 number for 1D periodic systems.
:vartype StressTensorVoigt: Iterable[float] | FloatListKey
:ivar UpdateReferenceCell: Whether ot not the reference cell should be updated every time the system changes (see documentation).
:vartype UpdateReferenceCell: BoolType | BoolKey
"""
def __post_init__(self):
self.StressTensorVoigt: Iterable[float] | FloatListKey = FloatListKey(name='StressTensorVoigt', comment='The elements of the external stress tensor in Voigt notation. One should specify 6 numbers for 3D periodic system (order: xx,yy,zz,yz,xz,xy), 3 numbers for 2D periodic systems (order: xx,yy,xy) or 1 number for 1D periodic systems.', gui_name='External stress tensor:', unit='Hartree/Bohr^3')
self.UpdateReferenceCell: BoolType | BoolKey = BoolKey(name='UpdateReferenceCell', comment='Whether ot not the reference cell should be updated every time the system changes (see documentation).', default=False)
[docs] class _PipeEngine(FixedBlock):
r"""
Pipe engine as an addon
:ivar WorkerCommand: pipe worker command
:vartype WorkerCommand: str | StringKey
"""
def __post_init__(self):
self.WorkerCommand: str | StringKey = StringKey(name='WorkerCommand', comment='pipe worker command', gui_name='Worker command:')
[docs] class _Repulsion(FixedBlock):
r"""
This block configures an addon that adds a repulsive Weeks-Chandler-Andersen potential to all atom pairs.
:ivar Enabled: Enables the repulsive Weeks-Chandler-Andersen potential addon.
When enabled, all atom pairs will experience repulsion E = 4*epsilon*( (sigma/r)^12 - (sigma/r)^6 + 1/4 ) at the distances shorter than about 1.12*sigma.
:vartype Enabled: BoolType | BoolKey
:ivar Epsilon: The epsilon parameter in the potential equation. It is equal to the amount of energy added at r=sigma.
:vartype Epsilon: float | FloatKey
:ivar HydrogenSigmaScale: The sigma parameter for a pair of atoms where one of them is hydrogen is scaled with the given factor. For H-H interactions the sigma is scaled with this value squared.
:vartype HydrogenSigmaScale: float | FloatKey
:ivar Sigma: The sigma parameter in the potential equation. The potential is exactly zero at the distances larger than about 1.12*sigma
:vartype Sigma: float | FloatKey
:ivar SkinLength: Technical parameter specifying skin length for the neighbor list generation. A larger value increases the neighbor list cutoff (and cost) but reduces the frequency it needs to be re-created.
:vartype SkinLength: float | FloatKey
"""
def __post_init__(self):
self.Enabled: BoolType | BoolKey = BoolKey(name='Enabled', comment='Enables the repulsive Weeks-Chandler-Andersen potential addon.\n\nWhen enabled, all atom pairs will experience repulsion E = 4*epsilon*( (sigma/r)^12 - (sigma/r)^6 + 1/4 ) at the distances shorter than about 1.12*sigma.', gui_name='Repulsion:', default=False)
self.Epsilon: float | FloatKey = FloatKey(name='Epsilon', comment='The epsilon parameter in the potential equation. It is equal to the amount of energy added at r=sigma.', default=0.01, unit='Hartree')
self.HydrogenSigmaScale: float | FloatKey = FloatKey(name='HydrogenSigmaScale', comment='The sigma parameter for a pair of atoms where one of them is hydrogen is scaled with the given factor. For H-H interactions the sigma is scaled with this value squared.', default=0.75, unit='Angstrom')
self.Sigma: float | FloatKey = FloatKey(name='Sigma', comment='The sigma parameter in the potential equation. The potential is exactly zero at the distances larger than about 1.12*sigma', default=0.55, unit='Angstrom')
self.SkinLength: float | FloatKey = FloatKey(name='SkinLength', comment='Technical parameter specifying skin length for the neighbor list generation. A larger value increases the neighbor list cutoff (and cost) but reduces the frequency it needs to be re-created.', default=2.0, unit='Angstrom')
[docs] class _WallPotential(FixedBlock):
r"""
This block configures the addon that adds a spherical wall potential to the engine's energy and gradients.
:ivar Enabled: Enables the wall potential addon. When enabled, a spherical wall of radius [Radius] around the origin will be added. The force due to the potential will decay exponentially inside the wall, will be close to [Prefactor*Gradient] outside and exactly half of that at the wall.
:vartype Enabled: BoolType | BoolKey
:ivar Gradient: The radial gradient outside the sphere.
:vartype Gradient: float | FloatKey
:ivar Prefactor: The multiplier for the overall strength of the potential.
:vartype Prefactor: float | FloatKey
:ivar Radius: The radius of the sphere, wherein the potential is close to zero.
:vartype Radius: float | FloatKey
"""
def __post_init__(self):
self.Enabled: BoolType | BoolKey = BoolKey(name='Enabled', comment='Enables the wall potential addon. When enabled, a spherical wall of radius [Radius] around the origin will be added. The force due to the potential will decay exponentially inside the wall, will be close to [Prefactor*Gradient] outside and exactly half of that at the wall.', default=False)
self.Gradient: float | FloatKey = FloatKey(name='Gradient', comment='The radial gradient outside the sphere.', default=10.0, unit='1/Angstrom')
self.Prefactor: float | FloatKey = FloatKey(name='Prefactor', comment='The multiplier for the overall strength of the potential.', default=0.01, unit='Hartree')
self.Radius: float | FloatKey = FloatKey(name='Radius', comment='The radius of the sphere, wherein the potential is close to zero.', default=30.0, unit='Angstrom', range='value > 0')
def __post_init__(self):
self.Pressure: float | FloatKey = FloatKey(name='Pressure', comment="Add a hydrostatic pressure term to the engine's energy and stress tensor. Can only be used for 3D periodic boundary conditions.", default=0.0, unit='GPa')
self.AtomEnergies: str | Sequence[str] | FreeBlock = self._AtomEnergies(name='AtomEnergies', comment='Add an element-dependent energy per atom. On each line, give the chemical element followed by the energy (in atomic units).')
self.D3Dispersion: Conformers._EngineAddons._D3Dispersion = self._D3Dispersion(name='D3Dispersion', comment="This block configures the add-on that adds the Grimme D3 dispersion correction to the engine's energy, gradients, and stress tensor.")
self.D4Dispersion: Conformers._EngineAddons._D4Dispersion = self._D4Dispersion(name='D4Dispersion', comment="This block configures the addon that adds the Grimme D4(EEQ) dispersion correction to the engine's energy, gradients, stress tensor and Hessian.")
self.ExternalEngine: Conformers._EngineAddons._ExternalEngine = self._ExternalEngine(name='ExternalEngine', comment='External engine as an addon')
self.ExternalStress: Conformers._EngineAddons._ExternalStress = self._ExternalStress(name='ExternalStress', comment="This block configures the addon that adds external stress term to the engine's energy and stress tensor.")
self.PipeEngine: Conformers._EngineAddons._PipeEngine = self._PipeEngine(name='PipeEngine', comment='Pipe engine as an addon')
self.Repulsion: Conformers._EngineAddons._Repulsion = self._Repulsion(name='Repulsion', comment='This block configures an addon that adds a repulsive Weeks-Chandler-Andersen potential to all atom pairs.')
self.WallPotential: Conformers._EngineAddons._WallPotential = self._WallPotential(name='WallPotential', comment="This block configures the addon that adds a spherical wall potential to the engine's energy and gradients.")
[docs] class _Equivalence(FixedBlock):
r"""
Options for the procedure determining whether two structures are equivalent or distinct conformers.
:ivar AcceptAll: If set to True, add any candidate to the set without checks of connectivity changes, stereo- or cis/trans isomerization, or duplication.
:vartype AcceptAll: BoolType | BoolKey
:ivar AcceptBondchanges: If set to True, perform all checks of a new conformer candidate, except for the connectivity check.
:vartype AcceptBondchanges: BoolType | BoolKey
:ivar AcceptIsomers: If set to True, perform all checks of a new conformer candidate, except for the stereo- or cis/trans isomerization check.
:vartype AcceptIsomers: BoolType | BoolKey
:ivar CheckForDuplicates: If set to True, check any new conformer candidate for duplication, and only accept unique conformers. If set to False, accept duplicates into the set.
:vartype CheckForDuplicates: BoolType | BoolKey
:ivar EnableSwapping: If set to True, a conformer candidate will replace another conformer if it is deemed a duplicate but with slightly lower energy.
:vartype EnableSwapping: BoolType | BoolKey
:ivar LogDuplicates: If set to True, print information on equivalence to logfile and standard output.
:vartype LogDuplicates: BoolType | BoolKey
:ivar Method: Method used to determine (and filter out) equivalent conformers.
The CREST equivalence method relies on rotational constants comparisons. For this reason, conformers with the same rotational constants (such as mirror images) will be considered equivalent conformers.
The AMS equivalence method uses a distance matrix and dihedrals to compare conformers. This equivalence method can be computationally expensive for large molecules.
The TFD equivalence method uses the Torsion Fingerprint Difference as implemented in RDKit.
The RMSD equivalence method uses the RDKit GetBestRMS implementation.
:vartype Method: Literal["AMS", "TFD", "RMSD", "CREST"]
:ivar Reorder: Reorder conformers based on energy, whenever a new conformer is added.
:vartype Reorder: BoolType | BoolKey
:ivar Verbose: If set to True, print errors in adding conformer candidates to the logfile.
:vartype Verbose: BoolType | BoolKey
:ivar AMS: Options for the AMS method of checking equivalence. This method uses the atomic distance matrices and the torsion angles between heavy atoms to determine if conformer candidates are duplicates.
:vartype AMS: Conformers._Equivalence._AMS
:ivar CREST: Options for the CREST method of checking equivalence. This method uses the rotational constants of conformer candidates to determine if they are duplicates.
:vartype CREST: Conformers._Equivalence._CREST
:ivar RMSD: Options for the RMSD method of checking equivalence. This method uses the RDKit implementation of GetBestRMS, which enumerates over atomic permutations for pairs of geometries to detect duplicates based on the RMSD value.
:vartype RMSD: Conformers._Equivalence._RMSD
:ivar TFD: Options for the TFD method of checking equivalence. This method uses the Torsion Finger Print method to determine if two conformer candidates are duplicates.
:vartype TFD: Conformers._Equivalence._TFD
"""
[docs] class _AMS(FixedBlock):
r"""
Options for the AMS method of checking equivalence. This method uses the atomic distance matrices and the torsion angles between heavy atoms to determine if conformer candidates are duplicates.
:ivar DihedralThreshold: Maximum difference a dihedral can have for a conformer to be considered a duplicate.
:vartype DihedralThreshold: float | FloatKey
:ivar DistanceThreshold: Maximum difference a distance between two atoms can have for a conformer to be considered a duplicate.
:vartype DistanceThreshold: float | FloatKey
:ivar EnergyThreshold: The energy difference beyond which two conformers are always considered distinct.
:vartype EnergyThreshold: float | FloatKey
:ivar IrrelevantAtoms: To detect equivalence, only a subset of atoms is used. The atoms that are excluded from equivalence comparison should be specified here. By default only non-hydrogen atoms will be used for the comparison. Numbering starts at 0.
:vartype IrrelevantAtoms: Iterable[int] | IntListKey
:ivar StoreRotamers: Whether or not rotamers (permutations of the conformers) should be stored in the conformers object. If set to yes, writing the rotamers to file still needs to be explicitly enabled. Storing the rotamers considerably slows down the conformer filtering process.
:vartype StoreRotamers: BoolType | BoolKey
:ivar UseTorsions: To detect equivalence, a two-step procedure is followed. First the permutation of atoms with the best match is determined, and then this permutation is used to see if distances and torsion angles are within the threshold values. For the first step by default both the distance matrices and the torsion angles aere used as well, but this is time consuming. By settings this key to False, only the distance matrix will be used for this first step. As a result it may happen that geometries that are actually equivalent will be accepted as unique conformers, but this will only happen for very symmetric molecules.
:vartype UseTorsions: BoolType | BoolKey
"""
def __post_init__(self):
self.DihedralThreshold: float | FloatKey = FloatKey(name='DihedralThreshold', comment='Maximum difference a dihedral can have for a conformer to be considered a duplicate.', default=30.0)
self.DistanceThreshold: float | FloatKey = FloatKey(name='DistanceThreshold', comment='Maximum difference a distance between two atoms can have for a conformer to be considered a duplicate.', default=0.1)
self.EnergyThreshold: float | FloatKey = FloatKey(name='EnergyThreshold', comment='The energy difference beyond which two conformers are always considered distinct.', default=0.2, unit='kcal/mol')
self.IrrelevantAtoms: Iterable[int] | IntListKey = IntListKey(name='IrrelevantAtoms', comment='To detect equivalence, only a subset of atoms is used. The atoms that are excluded from equivalence comparison should be specified here. By default only non-hydrogen atoms will be used for the comparison. Numbering starts at 0.')
self.StoreRotamers: BoolType | BoolKey = BoolKey(name='StoreRotamers', comment='Whether or not rotamers (permutations of the conformers) should be stored in the conformers object. If set to yes, writing the rotamers to file still needs to be explicitly enabled. Storing the rotamers considerably slows down the conformer filtering process.', hidden=True, default=False)
self.UseTorsions: BoolType | BoolKey = BoolKey(name='UseTorsions', comment='To detect equivalence, a two-step procedure is followed. First the permutation of atoms with the best match is determined, and then this permutation is used to see if distances and torsion angles are within the threshold values. For the first step by default both the distance matrices and the torsion angles aere used as well, but this is time consuming. By settings this key to False, only the distance matrix will be used for this first step. As a result it may happen that geometries that are actually equivalent will be accepted as unique conformers, but this will only happen for very symmetric molecules.', hidden=True, default=True)
[docs] class _CREST(FixedBlock):
r"""
Options for the CREST method of checking equivalence. This method uses the rotational constants of conformer candidates to determine if they are duplicates.
:ivar BconstScalingFactor: This is the scaling factor of the rotational constant difference used only for cluster analysis. This is not used to determine conformer equivalence (see ScaledBconstSettings). However, if FollowPaper is set to True, then this value IS used to determine conformer equivalence.
:vartype BconstScalingFactor: float | FloatKey
:ivar EnergyThreshold: The energy difference beyond which two conformers are always considered distinct.
:vartype EnergyThreshold: float | FloatKey
:ivar FollowPaper: By default this code uses a procedure to determine equivalence that is as close as possible to the procedure followed by Grimmes crest code. However, when this flag is turned on, then the procedure as described by the CREST paper (DOI: 10.1039/c9cp06869d) is followed. If set to True, then the rotational constant difference threshold used to determine equivalence is BconstScalingFactor, and not BconstThreshold.
:vartype FollowPaper: BoolType | BoolKey
:ivar RMSDThreshold: Threshold for the RMSD between two conformers that determines if they are duplicates or rotamers (according to the CREST rotamer definition.)
:vartype RMSDThreshold: float | FloatKey
:ivar SizeThreshold: An additional threshold based on the difference between distance matrices. This is used to determine if two geometries are duplicates or rotamers.
:vartype SizeThreshold: float | FloatKey
:ivar StoreRotamers: Whether or not rotamers (permutations of the conformers) should be stored in the conformers object. If set to yes, writing the rotamers to file still needs to be explicitly enabled. Storing the rotamers considerably slows down the conformer filtering process.
:vartype StoreRotamers: BoolType | BoolKey
:ivar ScaledRotationalConstantSettings: By default, the equivalence of two geometries is determined mainly by comparing the rotational constants, and weighing the difference based on the average anisotropy of the two systems. This procedure has several settings that can be user defined.
:vartype ScaledRotationalConstantSettings: Conformers._Equivalence._CREST._ScaledRotationalConstantSettings
"""
[docs] class _ScaledRotationalConstantSettings(FixedBlock):
r"""
By default, the equivalence of two geometries is determined mainly by comparing the rotational constants, and weighing the difference based on the average anisotropy of the two systems. This procedure has several settings that can be user defined.
:ivar BthrMax: Maximum rotational constant threshold due to anisotropy.
:vartype BthrMax: float | FloatKey
:ivar BthrShift: Shift in the error function used to compute modified rotational constant threshold, based on anisotropy.
:vartype BthrShift: float | FloatKey
:ivar RotationalConstantThreshold: Threshold for the difference in rotational constants that determines if two geometries are duplicates. The threshold is weighed by the anisotropy of the systems. Note: in the grimme code they use 0.01 as bconst_threshold, but this leads to a lot of misclassifications (i.e. different conformers are classified as equivalent rotamers) So, here we use a smaller default value.
:vartype RotationalConstantThreshold: float | FloatKey
"""
def __post_init__(self):
self.BthrMax: float | FloatKey = FloatKey(name='BthrMax', comment='Maximum rotational constant threshold due to anisotropy.', hidden=True, default=0.025)
self.BthrShift: float | FloatKey = FloatKey(name='BthrShift', comment='Shift in the error function used to compute modified rotational constant threshold, based on anisotropy.', hidden=True, default=0.5)
self.RotationalConstantThreshold: float | FloatKey = FloatKey(name='RotationalConstantThreshold', comment='Threshold for the difference in rotational constants that determines if two geometries are duplicates. The threshold is weighed by the anisotropy of the systems. Note: in the grimme code they use 0.01 as bconst_threshold, but this leads to a lot of misclassifications (i.e. different conformers are classified as equivalent rotamers) So, here we use a smaller default value.', default=0.003)
def __post_init__(self):
self.BconstScalingFactor: float | FloatKey = FloatKey(name='BconstScalingFactor', comment='This is the scaling factor of the rotational constant difference used only for cluster analysis. This is not used to determine conformer equivalence (see ScaledBconstSettings). However, if FollowPaper is set to True, then this value IS used to determine conformer equivalence.', hidden=True, default=15.0)
self.EnergyThreshold: float | FloatKey = FloatKey(name='EnergyThreshold', comment='The energy difference beyond which two conformers are always considered distinct.', default=0.05, unit='kcal/mol')
self.FollowPaper: BoolType | BoolKey = BoolKey(name='FollowPaper', comment='By default this code uses a procedure to determine equivalence that is as close as possible to the procedure followed by Grimmes crest code. However, when this flag is turned on, then the procedure as described by the CREST paper (DOI: 10.1039/c9cp06869d) is followed. If set to True, then the rotational constant difference threshold used to determine equivalence is BconstScalingFactor, and not BconstThreshold.', hidden=True, default=False)
self.RMSDThreshold: float | FloatKey = FloatKey(name='RMSDThreshold', comment='Threshold for the RMSD between two conformers that determines if they are duplicates or rotamers (according to the CREST rotamer definition.)', default=0.125)
self.SizeThreshold: float | FloatKey = FloatKey(name='SizeThreshold', comment='An additional threshold based on the difference between distance matrices. This is used to determine if two geometries are duplicates or rotamers.', hidden=True, default=0.001)
self.StoreRotamers: BoolType | BoolKey = BoolKey(name='StoreRotamers', comment='Whether or not rotamers (permutations of the conformers) should be stored in the conformers object. If set to yes, writing the rotamers to file still needs to be explicitly enabled. Storing the rotamers considerably slows down the conformer filtering process.', hidden=True, default=False)
self.ScaledRotationalConstantSettings: Conformers._Equivalence._CREST._ScaledRotationalConstantSettings = self._ScaledRotationalConstantSettings(name='ScaledRotationalConstantSettings', comment='By default, the equivalence of two geometries is determined mainly by comparing the rotational constants, and weighing the difference based on the average anisotropy of the two systems. This procedure has several settings that can be user defined.')
[docs] class _RMSD(FixedBlock):
r"""
Options for the RMSD method of checking equivalence. This method uses the RDKit implementation of GetBestRMS, which enumerates over atomic permutations for pairs of geometries to detect duplicates based on the RMSD value.
:ivar EnergyThreshold: The energy difference beyond which two conformers are always considered distinct.
:vartype EnergyThreshold: float | FloatKey
:ivar RMSDThreshold: Threshold on the RMSD difference to determine if two geometries represent the same conformer. This value is in Angstrom.
:vartype RMSDThreshold: float | FloatKey
"""
def __post_init__(self):
self.EnergyThreshold: float | FloatKey = FloatKey(name='EnergyThreshold', comment='The energy difference beyond which two conformers are always considered distinct.', default=0.05, unit='kcal/mol')
self.RMSDThreshold: float | FloatKey = FloatKey(name='RMSDThreshold', comment='Threshold on the RMSD difference to determine if two geometries represent the same conformer. This value is in Angstrom.', default=0.125)
[docs] class _TFD(FixedBlock):
r"""
Options for the TFD method of checking equivalence. This method uses the Torsion Finger Print method to determine if two conformer candidates are duplicates.
:ivar EnergyThreshold: The energy difference beyond which two conformers are always considered distinct.
:vartype EnergyThreshold: float | FloatKey
:ivar TFDThreshold: Threshold on the torsion fingerprint difference to determine if two geometries represent the same conformer. This value is unit-less.
:vartype TFDThreshold: float | FloatKey
:ivar UseEnergyThreshold: Accept all conformers with an energy difference greater than the energy threshold as unique, without TFD testing.
:vartype UseEnergyThreshold: BoolType | BoolKey
:ivar UseWeights: Use the weights of the torsion angles to compute the torsion fingerprint difference (all determined by RDKit).
:vartype UseWeights: BoolType | BoolKey
"""
def __post_init__(self):
self.EnergyThreshold: float | FloatKey = FloatKey(name='EnergyThreshold', comment='The energy difference beyond which two conformers are always considered distinct.', default=0.05, unit='kcal/mol')
self.TFDThreshold: float | FloatKey = FloatKey(name='TFDThreshold', comment='Threshold on the torsion fingerprint difference to determine if two geometries represent the same conformer. This value is unit-less.', default=0.05)
self.UseEnergyThreshold: BoolType | BoolKey = BoolKey(name='UseEnergyThreshold', comment='Accept all conformers with an energy difference greater than the energy threshold as unique, without TFD testing.', hidden=True, default=True)
self.UseWeights: BoolType | BoolKey = BoolKey(name='UseWeights', comment='Use the weights of the torsion angles to compute the torsion fingerprint difference (all determined by RDKit).', hidden=True, default=True)
def __post_init__(self):
self.AcceptAll: BoolType | BoolKey = BoolKey(name='AcceptAll', comment='If set to True, add any candidate to the set without checks of connectivity changes, stereo- or cis/trans isomerization, or duplication.', default=False)
self.AcceptBondchanges: BoolType | BoolKey = BoolKey(name='AcceptBondchanges', comment='If set to True, perform all checks of a new conformer candidate, except for the connectivity check.', default=False)
self.AcceptIsomers: BoolType | BoolKey = BoolKey(name='AcceptIsomers', comment='If set to True, perform all checks of a new conformer candidate, except for the stereo- or cis/trans isomerization check.', default=False)
self.CheckForDuplicates: BoolType | BoolKey = BoolKey(name='CheckForDuplicates', comment='If set to True, check any new conformer candidate for duplication, and only accept unique conformers. If set to False, accept duplicates into the set.', default=True)
self.EnableSwapping: BoolType | BoolKey = BoolKey(name='EnableSwapping', comment='If set to True, a conformer candidate will replace another conformer if it is deemed a duplicate but with slightly lower energy.', hidden=True, default=True)
self.LogDuplicates: BoolType | BoolKey = BoolKey(name='LogDuplicates', comment='If set to True, print information on equivalence to logfile and standard output.', default=False)
self.Method: Literal["AMS", "TFD", "RMSD", "CREST"] = MultipleChoiceKey(name='Method', comment='Method used to determine (and filter out) equivalent conformers.\n\nThe CREST equivalence method relies on rotational constants comparisons. For this reason, conformers with the same rotational constants (such as mirror images) will be considered equivalent conformers.\n\nThe AMS equivalence method uses a distance matrix and dihedrals to compare conformers. This equivalence method can be computationally expensive for large molecules.\n\nThe TFD equivalence method uses the Torsion Fingerprint Difference as implemented in RDKit.\n\nThe RMSD equivalence method uses the RDKit GetBestRMS implementation.', gui_name='Equivalence method:', default='CREST', choices=['AMS', 'TFD', 'RMSD', 'CREST'])
self.Reorder: BoolType | BoolKey = BoolKey(name='Reorder', comment='Reorder conformers based on energy, whenever a new conformer is added.', default=True)
self.Verbose: BoolType | BoolKey = BoolKey(name='Verbose', comment='If set to True, print errors in adding conformer candidates to the logfile.', hidden=True, default=False)
self.AMS: Conformers._Equivalence._AMS = self._AMS(name='AMS', comment='Options for the AMS method of checking equivalence. This method uses the atomic distance matrices and the torsion angles between heavy atoms to determine if conformer candidates are duplicates.')
self.CREST: Conformers._Equivalence._CREST = self._CREST(name='CREST', comment='Options for the CREST method of checking equivalence. This method uses the rotational constants of conformer candidates to determine if they are duplicates.')
self.RMSD: Conformers._Equivalence._RMSD = self._RMSD(name='RMSD', comment='Options for the RMSD method of checking equivalence. This method uses the RDKit implementation of GetBestRMS, which enumerates over atomic permutations for pairs of geometries to detect duplicates based on the RMSD value.')
self.TFD: Conformers._Equivalence._TFD = self._TFD(name='TFD', comment='Options for the TFD method of checking equivalence. This method uses the Torsion Finger Print method to determine if two conformer candidates are duplicates.')
[docs] class _Expander(FixedBlock):
r"""
Options for the conformer expander. The Expander expands an existing conformer set, by adding new conformers to it. The new conformers are generated from the original conformers in the set. Unlike the generators, the outcome of an expander is therefore very dependent on the input conformations.
The GC generator uses a genetic algorithm to create a combinatorial expansion by combining local substructures.
The MD expander start MD simulations from the conformers in the set, and extracts snapshots to create new conformers. Both these expanders are part of the CREST generator.
:ivar AdjustInputBonds: If geometry optimization of the initial conformer results in bond changes, adjust the reference connectivity. If the changes are too severe, the calculation will stop.
:vartype AdjustInputBonds: BoolType | BoolKey
:ivar MaxEnergy: Threshold for filtering out high-energy conformers. If the relative energy of a conformer with respect to the lowest conformer is larger than this value, the conformer will be discarded.
:vartype MaxEnergy: float | FloatKey
:ivar Method: Method used to generate the conformers.
:vartype Method: Literal["MD", "GC"]
:ivar RNGSeed: Initial guesses for conformers can be randomly generated by RDKit, using the ETKDG algorithm. For reproducibility, a random number seed can be provided here.
:vartype RNGSeed: int | IntKey
:ivar Verbose: If set to True, print additional info about conformer equivalence to standard output.
:vartype Verbose: BoolType | BoolKey
:ivar GC: Options for the genetic algorithm for combinatorial expansion of conformer geometries. This generator only works if a non-zero set of conformers is already provided.
:vartype GC: Conformers._Expander._GC
:ivar MD: Produces conformers by running a set of MD simulations at different elevated temperatures, extracting snapshots, and optimizing those.
:vartype MD: Conformers._Expander._MD
:ivar Preoptimization: If this block is enabled geometries will be preoptimized. After preoptimization the high energy conformers will be discarded, and then from the remaining set the unoptimized geometries will be optimized at higher level. This is to prevent the preoptimizer from collapsing different conformers into a single false minimum. As a result, preoptimization is only useful if MaxEnergy is chosen low.
:vartype Preoptimization: Conformers._Expander._Preoptimization
:ivar RDKitETKDG: Settings for the call to RDKits ETKDG conformer generator tool.
:vartype RDKitETKDG: Conformers._Expander._RDKitETKDG
"""
[docs] class _GC(FixedBlock):
r"""
Options for the genetic algorithm for combinatorial expansion of conformer geometries. This generator only works if a non-zero set of conformers is already provided.
:ivar ClashThreshold: Newly generated geometries are only accepted if the increase in coordination number per atom is below this threshold..
:vartype ClashThreshold: float | FloatKey
:ivar CoordnumThreshold: Distance squared threshold, above which the coordination number can be neglected in Angstrom**2.
:vartype CoordnumThreshold: float | FloatKey
:ivar GCNgeomsFactor: Parameter used to determine the maximum number of geometries that this generator is allowed to produce.
:vartype GCNgeomsFactor: float | FloatKey
:ivar MaxGCenergy: The maximum energy (relative to the lowest in the set) of the conformers we are going to use for expansion. The default is 6.0 kcal/mol, but if MaxEnergy was set, then that value is used.
:vartype MaxGCenergy: float | FloatKey
:ivar Parallel: Determines if the combinatorial expansion of conformers should be performed in parallel or not (default: True).
:vartype Parallel: BoolType | BoolKey
:ivar RMSDThreshold: Newly generated geometries are only considered unique if their RMSD from all other newly generated geometries is larger than this threshold.
:vartype RMSDThreshold: float | FloatKey
"""
def __post_init__(self):
self.ClashThreshold: float | FloatKey = FloatKey(name='ClashThreshold', comment='Newly generated geometries are only accepted if the increase in coordination number per atom is below this threshold..', hidden=True, default=0.3)
self.CoordnumThreshold: float | FloatKey = FloatKey(name='CoordnumThreshold', comment='Distance squared threshold, above which the coordination number can be neglected in Angstrom**2.', hidden=True, default=28.002852053907812)
self.GCNgeomsFactor: float | FloatKey = FloatKey(name='GCNgeomsFactor', comment='Parameter used to determine the maximum number of geometries that this generator is allowed to produce.', hidden=True, default=50.0)
self.MaxGCenergy: float | FloatKey = FloatKey(name='MaxGCenergy', comment='The maximum energy (relative to the lowest in the set) of the conformers we are going to use for expansion. The default is 6.0 kcal/mol, but if MaxEnergy was set, then that value is used.', default=6.0)
self.Parallel: BoolType | BoolKey = BoolKey(name='Parallel', comment='Determines if the combinatorial expansion of conformers should be performed in parallel or not (default: True).', default=True)
self.RMSDThreshold: float | FloatKey = FloatKey(name='RMSDThreshold', comment='Newly generated geometries are only considered unique if their RMSD from all other newly generated geometries is larger than this threshold.', default=0.25)
[docs] class _MD(FixedBlock):
r"""
Produces conformers by running a set of MD simulations at different elevated temperatures, extracting snapshots, and optimizing those.
:ivar Blocksize: The interval between the trajectory snapshots written to file that are extracted and optimized. By default all written snapshots are extracted.
:vartype Blocksize: int | IntKey
:ivar Multiples: The number of MD simulations per selected temperature and starting geometry. The default is 1.
:vartype Multiples: int | IntKey
:ivar Ngeoms: At each temperature, MD simulations are started from Ngeoms different starting geometries. The starting geometries are extracted from the provided conformer set. If the conformer set is empty, then no more than a single geometry per temperature can be provided, limiting the total number of MD simulations.
:vartype Ngeoms: int | IntKey
:ivar Temperatures: The list of different temperatures at which MD simulations are run.
:vartype Temperatures: Iterable[float] | FloatListKey
:ivar UseShake: Constrain all -H bonds with shake. If turned on, the MD timestep is automatically increased.
:vartype UseShake: BoolType | BoolKey
:ivar UseXtb: Use Grimmes XTB code to perform the MD simulations instead of AMS
:vartype UseXtb: BoolType | BoolKey
:ivar MolecularDynamics: Configures molecular dynamics (with the velocity-Verlet algorithm) with and without thermostats. This block allows to specify the details of the molecular dynamics calculation. Default values will be ignored.
:vartype MolecularDynamics: Conformers._Expander._MD._MolecularDynamics
"""
[docs] class _MolecularDynamics(FixedBlock):
r"""
Configures molecular dynamics (with the velocity-Verlet algorithm) with and without thermostats. This block allows to specify the details of the molecular dynamics calculation. Default values will be ignored.
:ivar NSteps: The number of steps to be taken in the MD simulation.
:vartype NSteps: int | IntKey
:ivar Restart: The path to the ams.rkf file from which to restart the simulation.
:vartype Restart: str | Path | StringKey
:ivar TimeStep: The time difference per step.
:vartype TimeStep: float | FloatKey
:ivar Checkpoint: Sets the frequency for storing the entire MD state necessary for restarting the calculation.
:vartype Checkpoint: Conformers._Expander._MD._MolecularDynamics._Checkpoint
:ivar InitialVelocities: Sets the frequency for printing to stdout and storing the molecular configuration on the .rkf file.
:vartype InitialVelocities: Conformers._Expander._MD._MolecularDynamics._InitialVelocities
:ivar Preserve: Periodically remove numerical drift accumulated during the simulation to preserve different whole-system parameters.
:vartype Preserve: Conformers._Expander._MD._MolecularDynamics._Preserve
:ivar Print: This block controls the printing of additional information to stdout.
:vartype Print: Conformers._Expander._MD._MolecularDynamics._Print
:ivar Shake: Parameters of the Shake/Rattle algorithm.
:vartype Shake: Conformers._Expander._MD._MolecularDynamics._Shake
:ivar Thermostat: This block allows to specify the use of a thermostat during the simulation. Depending on the selected thermostat type, different additional options may be needed to characterize the specific thermostat's behavior.
:vartype Thermostat: Conformers._Expander._MD._MolecularDynamics._Thermostat
:ivar Trajectory: Sets the frequency for printing to stdout and storing the molecular configuration on the .rkf file.
:vartype Trajectory: Conformers._Expander._MD._MolecularDynamics._Trajectory
"""
[docs] class _Checkpoint(FixedBlock):
r"""
Sets the frequency for storing the entire MD state necessary for restarting the calculation.
:ivar Frequency: Write the MD state to the Molecule and MDResults sections on ams.rkf once every N steps. Setting this to zero disables checkpointing during the simulation, but one checkpoint at the very end of the simulation will always be written.
:vartype Frequency: int | IntKey
:ivar WriteProperties: Honor top-level Properties input block when writing engine results files.
DEPRECATED: This input option will be removed in AMS2026 and will be considered always enabled. If you rely on it being disabled, please contact [email protected].
:vartype WriteProperties: BoolType | BoolKey
"""
def __post_init__(self):
self.Frequency: int | IntKey = IntKey(name='Frequency', comment='Write the MD state to the Molecule and MDResults sections on ams.rkf once every N steps. Setting this to zero disables checkpointing during the simulation, but one checkpoint at the very end of the simulation will always be written.', gui_name='Checkpoint frequency:', default=1000)
self.WriteProperties: BoolType | BoolKey = BoolKey(name='WriteProperties', comment='Honor top-level Properties input block when writing engine results files.\n\nDEPRECATED: This input option will be removed in AMS2026 and will be considered always enabled. If you rely on it being disabled, please contact [email protected].', default=False)
[docs] class _InitialVelocities(FixedBlock):
r"""
Sets the frequency for printing to stdout and storing the molecular configuration on the .rkf file.
:ivar File: AMS RKF file containing the initial velocities.
:vartype File: str | Path | StringKey
:ivar RandomVelocitiesMethod: Specifies how are random velocities generated. Three methods are available.
Exact: Velocities are scaled to exactly match set random velocities temperature.
Boltzmann: Velocities are not scaled and sample Maxwell-Boltzmann distribution. However, the distribution is not corrected for constraints.
Gromacs: Velocities are scaled to match set random velocities temperature, but removal of net momentum is performed only after the scaling. Resulting kinetic energy is lower based on how much net momentum the system had.
:vartype RandomVelocitiesMethod: Literal["Exact", "Boltzmann", "Gromacs"]
:ivar Temperature: Sets the temperature for the Maxwell-Boltzmann distribution when the type of the initial velocities is set to random, in which case specifying this key is mandatory.
AMSinput will use the first temperature of the first thermostat as default.
:vartype Temperature: float | FloatKey
:ivar Type: Specifies the initial velocities to assign to the atoms. Three methods to assign velocities are available.
Zero: All atom are at rest at the beginning of the calculation.
Random: Initial atom velocities follow a Maxwell-Boltzmann distribution for the temperature given by the [MolecularDynamics%InitialVelocities%Temperature] keyword.
FromFile: Load the velocities from a previous ams result file.
Input: Atom's velocities are set to the values specified in the [MolecularDynamics%InitialVelocities%Values] block, which can be accessed via the Expert AMS panel in AMSinput.
:vartype Type: Literal["Zero", "Random", "FromFile", "Input"]
:ivar Values: This block specifies the velocity of each atom, in Angstrom/fs, when [MolecularDynamics%InitialVelocities%Type] is set to Input. Each row must contain three floating point values (corresponding to the x,y,z component of the velocity vector) and a number of rows equal to the number of atoms must be present, given in the same order as the [System%Atoms] block.
:vartype Values: str | Sequence[str] | FreeBlock
"""
[docs] class _Values(FreeBlock):
r"""
This block specifies the velocity of each atom, in Angstrom/fs, when [MolecularDynamics%InitialVelocities%Type] is set to Input. Each row must contain three floating point values (corresponding to the x,y,z component of the velocity vector) and a number of rows equal to the number of atoms must be present, given in the same order as the [System%Atoms] block.
"""
def __post_init__(self):
pass
def __post_init__(self):
self.File: str | Path | StringKey = PathStringKey(name='File', comment='AMS RKF file containing the initial velocities.', ispath=True, gui_type='{} {{{AMS result file} .rkf}}')
self.RandomVelocitiesMethod: Literal["Exact", "Boltzmann", "Gromacs"] = MultipleChoiceKey(name='RandomVelocitiesMethod', comment='Specifies how are random velocities generated. Three methods are available.\n\nExact: Velocities are scaled to exactly match set random velocities temperature. \n\nBoltzmann: Velocities are not scaled and sample Maxwell-Boltzmann distribution. However, the distribution is not corrected for constraints.\n\nGromacs: Velocities are scaled to match set random velocities temperature, but removal of net momentum is performed only after the scaling. Resulting kinetic energy is lower based on how much net momentum the system had.', gui_name='Velocity randomization method:', default='Exact', choices=['Exact', 'Boltzmann', 'Gromacs'])
self.Temperature: float | FloatKey = FloatKey(name='Temperature', comment='Sets the temperature for the Maxwell-Boltzmann distribution when the type of the initial velocities is set to random, in which case specifying this key is mandatory.\n\nAMSinput will use the first temperature of the first thermostat as default.', gui_name='Initial temperature:', unit='Kelvin')
self.Type: Literal["Zero", "Random", "FromFile", "Input"] = MultipleChoiceKey(name='Type', comment="Specifies the initial velocities to assign to the atoms. Three methods to assign velocities are available.\n\nZero: All atom are at rest at the beginning of the calculation.\n\nRandom: Initial atom velocities follow a Maxwell-Boltzmann distribution for the temperature given by the [MolecularDynamics%InitialVelocities%Temperature] keyword.\n\nFromFile: Load the velocities from a previous ams result file.\n\nInput: Atom's velocities are set to the values specified in the [MolecularDynamics%InitialVelocities%Values] block, which can be accessed via the Expert AMS panel in AMSinput.", gui_name='Initial velocities:', default='Random', choices=['Zero', 'Random', 'FromFile', 'Input'])
self.Values: str | Sequence[str] | FreeBlock = self._Values(name='Values', comment='This block specifies the velocity of each atom, in Angstrom/fs, when [MolecularDynamics%InitialVelocities%Type] is set to Input. Each row must contain three floating point values (corresponding to the x,y,z component of the velocity vector) and a number of rows equal to the number of atoms must be present, given in the same order as the [System%Atoms] block.')
[docs] class _Preserve(FixedBlock):
r"""
Periodically remove numerical drift accumulated during the simulation to preserve different whole-system parameters.
:ivar AngularMomentum: Remove overall angular momentum of the system. This option is ignored for 2D and 3D-periodic systems, and disabled by default for systems which are not translationally invariant (for example when frozen atoms are present).
:vartype AngularMomentum: BoolType | BoolKey
:ivar CenterOfMass: Translate the system to keep its center of mass at the coordinate origin. This option is not very useful for 3D-periodic systems.
:vartype CenterOfMass: BoolType | BoolKey
:ivar Momentum: Remove overall (linear) momentum of the system. This is disabled by default for systems which are not translationally invariant (for example when frozen atoms are present).
:vartype Momentum: BoolType | BoolKey
"""
def __post_init__(self):
self.AngularMomentum: BoolType | BoolKey = BoolKey(name='AngularMomentum', comment='Remove overall angular momentum of the system. This option is ignored for 2D and 3D-periodic systems, and disabled by default for systems which are not translationally invariant (for example when frozen atoms are present).', gui_name=': Angular momentum', default=True)
self.CenterOfMass: BoolType | BoolKey = BoolKey(name='CenterOfMass', comment='Translate the system to keep its center of mass at the coordinate origin. This option is not very useful for 3D-periodic systems.', gui_name=': Center of mass', default=False)
self.Momentum: BoolType | BoolKey = BoolKey(name='Momentum', comment='Remove overall (linear) momentum of the system. This is disabled by default for systems which are not translationally invariant (for example when frozen atoms are present).', gui_name='Preserve: Total momentum', default=True)
[docs] class _Print(FixedBlock):
r"""
This block controls the printing of additional information to stdout.
:ivar System: Print the chemical system before and after the simulation.
:vartype System: BoolType | BoolKey
:ivar Velocities: Print the atomic velocities before and after the simulation.
:vartype Velocities: BoolType | BoolKey
"""
def __post_init__(self):
self.System: BoolType | BoolKey = BoolKey(name='System', comment='Print the chemical system before and after the simulation.', default=False)
self.Velocities: BoolType | BoolKey = BoolKey(name='Velocities', comment='Print the atomic velocities before and after the simulation.', default=False)
[docs] class _Shake(FixedBlock):
r"""
Parameters of the Shake/Rattle algorithm.
:ivar All: Constraint description in one the following formats:
All [bondOrder] bonds at1 at2 [to distance]
All triangles at1 at2 at3
The first option constrains all bonds between atoms at1 at2 to a certain length, while the second - bonds at1-at2 and at2-at3 and the angle between them.
The [bondOrder] can be a number or a string such as single, double, triple or aromatic. If it's omitted then all bonds between specified atoms will be constrained. Atom names are case-sensitive and they must be as they are in the Atoms block, or an asterisk '*' denoting any atom. The distance, if present, must be in Angstrom. If it is omitted then the bond length from the initial geometry is used.
Important: only the bonds present in the system at certain points of the simulation (at the start or right after adding/removing atoms) can be constrained, which means that the bonds may need to be specified in the System block.
Warning: the triangles constraint should be used with care because each constrained bond or angle means removing one degree of freedom from the dynamics. When there are too many constraints (for example, "All triangles H C H" in methane) some of them may be linearly dependent, which will lead to an error in the temperature computation.
Valid examples:
All single bonds C C to 1.4
All bonds O H to 0.98
All bonds O H
All bonds H *
All triangles H * H
:vartype All: str | StringKey
:ivar ConvergeR2: Convergence criterion on the max squared difference, in atomic units.
:vartype ConvergeR2: float | FloatKey
:ivar ConvergeRV: Convergence criterion on the orthogonality of the constraint and the relative atomic velocity, in atomic units.
:vartype ConvergeRV: float | FloatKey
:ivar Iterations: Number of iterations.
:vartype Iterations: int | IntKey
:ivar ShakeInitialCoordinates: Apply constraints before computing the first energy and gradients.
:vartype ShakeInitialCoordinates: BoolType | BoolKey
"""
def __post_init__(self):
self.All: str | StringKey = StringKey(name='All', comment='Constraint description in one the following formats: \nAll [bondOrder] bonds at1 at2 [to distance]\nAll triangles at1 at2 at3\n\nThe first option constrains all bonds between atoms at1 at2 to a certain length, while the second - bonds at1-at2 and at2-at3 and the angle between them.\n\nThe [bondOrder] can be a number or a string such as single, double, triple or aromatic. If it\'s omitted then all bonds between specified atoms will be constrained. Atom names are case-sensitive and they must be as they are in the Atoms block, or an asterisk \'*\' denoting any atom. The distance, if present, must be in Angstrom. If it is omitted then the bond length from the initial geometry is used.\n\nImportant: only the bonds present in the system at certain points of the simulation (at the start or right after adding/removing atoms) can be constrained, which means that the bonds may need to be specified in the System block.\n\nWarning: the triangles constraint should be used with care because each constrained bond or angle means removing one degree of freedom from the dynamics. When there are too many constraints (for example, "All triangles H C H" in methane) some of them may be linearly dependent, which will lead to an error in the temperature computation. \n\nValid examples:\nAll single bonds C C to 1.4\nAll bonds O H to 0.98\nAll bonds O H\nAll bonds H *\nAll triangles H * H', unique=False, gui_name='Constrain all:')
self.ConvergeR2: float | FloatKey = FloatKey(name='ConvergeR2', comment='Convergence criterion on the max squared difference, in atomic units.', default=1e-08)
self.ConvergeRV: float | FloatKey = FloatKey(name='ConvergeRV', comment='Convergence criterion on the orthogonality of the constraint and the relative atomic velocity, in atomic units.', default=1e-08)
self.Iterations: int | IntKey = IntKey(name='Iterations', comment='Number of iterations.', default=100)
self.ShakeInitialCoordinates: BoolType | BoolKey = BoolKey(name='ShakeInitialCoordinates', comment='Apply constraints before computing the first energy and gradients.', default=True)
[docs] class _Thermostat(FixedBlock):
r"""
This block allows to specify the use of a thermostat during the simulation. Depending on the selected thermostat type, different additional options may be needed to characterize the specific thermostat's behavior.
:ivar BerendsenApply: Select how to apply the scaling correction for the Berendsen thermostat:
- per-atom-velocity (Local)
- on the molecular system as a whole (Global).
:vartype BerendsenApply: Literal["Local", "Global"]
:ivar ChainLength: Number of individual thermostats forming the NHC thermostat
:vartype ChainLength: int | IntKey
:ivar Duration: Specifies how many steps should a transition from a particular temperature to the next one in sequence take.
:vartype Duration: Iterable[int] | IntListKey
:ivar ExcludedDirection: Exclude a component of the velocities from rescaling by the thermostat. For example in NEMD simulations, when a shear force/velocity is applied in the x direction, the x-direction is often excluded from thermostatting. This currently only works for the Nose-Hoover thermostat.
:vartype ExcludedDirection: Literal["None", "X", "Y", "Z"]
:ivar Friction: Friction coefficient used in langevin dynamics
:vartype Friction: float | FloatKey
:ivar Region: The identifier of the region to thermostat. The default `*` applies the thermostat to the entire system. The value can by a plain region name, or a region expression, e.g. `*-myregion` to thermostat all atoms that are not in myregion, or `regionA+regionB` to thermostat the union of the 'regionA' and 'regionB'. Note that if multiple thermostats are used, their regions may not overlap.
:vartype Region: str | StringKey
:ivar ScaleFrequency: Optional parameter used only by the Scale thermostat.
If specified, the thermostat will be applied every N steps, using that step's ensemble temperature and the specified thermostat temperature to compute the scaling factor.
If not specified, the thermostat will be applied at every step, using the mean temperature of the ensemble and the specified thermostat temperature to compute the scaling factor.
:vartype ScaleFrequency: int | IntKey
:ivar Tau: The time constant of the thermostat.
:vartype Tau: float | FloatKey
:ivar Temperature: The target temperature of the thermostat.
You can specify multiple temperatures (separated by spaces). In that case the Duration field specifies how many steps to use for the transition from one T to the next T (using a linear ramp). For NHC thermostat, the temperature may not be zero.
:vartype Temperature: Iterable[float] | FloatListKey
:ivar Type: Selects the type of the thermostat.
:vartype Type: Literal["None", "Scale", "Berendsen", "NHC", "Langevin"]
"""
def __post_init__(self):
self.BerendsenApply: Literal["Local", "Global"] = MultipleChoiceKey(name='BerendsenApply', comment='Select how to apply the scaling correction for the Berendsen thermostat:\n\n- per-atom-velocity (Local)\n- on the molecular system as a whole (Global).', gui_name='Apply Berendsen:', default='Global', choices=['Local', 'Global'])
self.ChainLength: int | IntKey = IntKey(name='ChainLength', comment='Number of individual thermostats forming the NHC thermostat', gui_name='NHC chain length:', default=10)
self.Duration: Iterable[int] | IntListKey = IntListKey(name='Duration', comment='Specifies how many steps should a transition from a particular temperature to the next one in sequence take.', gui_name='Duration(s)')
self.ExcludedDirection: Literal["None", "X", "Y", "Z"] = MultipleChoiceKey(name='ExcludedDirection', comment='Exclude a component of the velocities from rescaling by the thermostat. For example in NEMD simulations, when a shear force/velocity is applied in the x direction, the x-direction is often excluded from thermostatting. This currently only works for the Nose-Hoover thermostat.', hidden=True, default='None', choices=['None', 'X', 'Y', 'Z'])
self.Friction: float | FloatKey = FloatKey(name='Friction', comment='Friction coefficient used in langevin dynamics', hidden=True, default=1.0)
self.Region: str | StringKey = StringKey(name='Region', comment="The identifier of the region to thermostat. The default `*` applies the thermostat to the entire system. The value can by a plain region name, or a region expression, e.g. `*-myregion` to thermostat all atoms that are not in myregion, or `regionA+regionB` to thermostat the union of the 'regionA' and 'regionB'. Note that if multiple thermostats are used, their regions may not overlap.", default='*', gui_type='region')
self.ScaleFrequency: int | IntKey = IntKey(name='ScaleFrequency', comment="Optional parameter used only by the Scale thermostat.\n\nIf specified, the thermostat will be applied every N steps, using that step's ensemble temperature and the specified thermostat temperature to compute the scaling factor.\n\nIf not specified, the thermostat will be applied at every step, using the mean temperature of the ensemble and the specified thermostat temperature to compute the scaling factor.", hidden=True)
self.Tau: float | FloatKey = FloatKey(name='Tau', comment='The time constant of the thermostat.', gui_name='Damping constant:', unit='Femtoseconds')
self.Temperature: Iterable[float] | FloatListKey = FloatListKey(name='Temperature', comment='The target temperature of the thermostat.\n\nYou can specify multiple temperatures (separated by spaces). In that case the Duration field specifies how many steps to use for the transition from one T to the next T (using a linear ramp). For NHC thermostat, the temperature may not be zero.', gui_name='Temperature(s)', unit='Kelvin')
self.Type: Literal["None", "Scale", "Berendsen", "NHC", "Langevin"] = MultipleChoiceKey(name='Type', comment='Selects the type of the thermostat.', gui_name='Thermostat:', default='None', choices=['None', 'Scale', 'Berendsen', 'NHC', 'Langevin'], hiddenchoices=['Scale', 'Langevin'])
[docs] class _Trajectory(FixedBlock):
r"""
Sets the frequency for printing to stdout and storing the molecular configuration on the .rkf file.
:ivar EngineResultsFreq: Write MDStep*.rkf files with engine-specific results once every N steps. Setting this to zero disables writing engine results files except for one file at the end of the simulation. If unset or negative, defaults to the value of Checkpoint%Frequency.
:vartype EngineResultsFreq: int | IntKey
:ivar ExitConditionFreq: Check the exit conditions every N steps. By default this is done every SamplingFreq steps.
:vartype ExitConditionFreq: int | IntKey
:ivar PrintFreq: Print current thermodynamic properties to the output every N steps. By default this is done every SamplingFreq steps.
:vartype PrintFreq: int | IntKey
:ivar SamplingFreq: Write the molecular geometry (and possibly other properties) to the ams.rkf file once every N steps.
:vartype SamplingFreq: int | IntKey
:ivar TProfileGridPoints: Number of points in the temperature profile. If TProfileGridPoints > 0, a temperature profile along each of the three lattice axes will be written to the .rkf file. The temperature at a given profile point is calculated as the total temperature of all atoms inside the corresponding slice of the simulation box, time-averaged over all MD steps since the previous snapshot. By default, no profile is generated.
:vartype TProfileGridPoints: int | IntKey
:ivar WriteBonds: Write detected bonds to the .rkf file.
:vartype WriteBonds: BoolType | BoolKey
:ivar WriteCharges: Write current atomic point charges (if available) to the .rkf file. Disable this to reduce trajectory size if you do not need to analyze charges.
:vartype WriteCharges: BoolType | BoolKey
:ivar WriteCoordinates: Write atomic coordinates to the .rkf file.
:vartype WriteCoordinates: BoolType | BoolKey
:ivar WriteEngineGradients: Write atomic gradients (negative of the atomic forces, as calculated by the engine) to the History section of ams.rkf.
:vartype WriteEngineGradients: BoolType | BoolKey
:ivar WriteMolecules: Write the results of molecule analysis to the .rkf file.
:vartype WriteMolecules: BoolType | BoolKey
:ivar WriteVelocities: Write velocities to the .rkf file. Disable this to reduce trajectory size if you do not need to analyze the velocities.
:vartype WriteVelocities: BoolType | BoolKey
"""
def __post_init__(self):
self.EngineResultsFreq: int | IntKey = IntKey(name='EngineResultsFreq', comment='Write MDStep*.rkf files with engine-specific results once every N steps. Setting this to zero disables writing engine results files except for one file at the end of the simulation. If unset or negative, defaults to the value of Checkpoint%Frequency.', gui_name='Engine results frequency:')
self.ExitConditionFreq: int | IntKey = IntKey(name='ExitConditionFreq', comment='Check the exit conditions every N steps. By default this is done every SamplingFreq steps.', gui_name='Exit condition frequency:')
self.PrintFreq: int | IntKey = IntKey(name='PrintFreq', comment='Print current thermodynamic properties to the output every N steps. By default this is done every SamplingFreq steps.', gui_name='Printing frequency:')
self.SamplingFreq: int | IntKey = IntKey(name='SamplingFreq', comment='Write the molecular geometry (and possibly other properties) to the ams.rkf file once every N steps.', gui_name='Sample frequency:', default=100)
self.TProfileGridPoints: int | IntKey = IntKey(name='TProfileGridPoints', comment='Number of points in the temperature profile. If TProfileGridPoints > 0, a temperature profile along each of the three lattice axes will be written to the .rkf file. The temperature at a given profile point is calculated as the total temperature of all atoms inside the corresponding slice of the simulation box, time-averaged over all MD steps since the previous snapshot.\u200b By default, no profile is generated.', default=0)
self.WriteBonds: BoolType | BoolKey = BoolKey(name='WriteBonds', comment='Write detected bonds to the .rkf file.', default=True)
self.WriteCharges: BoolType | BoolKey = BoolKey(name='WriteCharges', comment='Write current atomic point charges (if available) to the .rkf file. Disable this to reduce trajectory size if you do not need to analyze charges.', default=True)
self.WriteCoordinates: BoolType | BoolKey = BoolKey(name='WriteCoordinates', comment='Write atomic coordinates to the .rkf file.', default=True)
self.WriteEngineGradients: BoolType | BoolKey = BoolKey(name='WriteEngineGradients', comment='Write atomic gradients (negative of the atomic forces, as calculated by the engine) to the History section of ams.rkf.', default=False)
self.WriteMolecules: BoolType | BoolKey = BoolKey(name='WriteMolecules', comment='Write the results of molecule analysis to the .rkf file.', default=True)
self.WriteVelocities: BoolType | BoolKey = BoolKey(name='WriteVelocities', comment='Write velocities to the .rkf file. Disable this to reduce trajectory size if you do not need to analyze the velocities.', default=True)
def __post_init__(self):
self.NSteps: int | IntKey = IntKey(name='NSteps', comment='The number of steps to be taken in the MD simulation.', gui_name='Number of steps:', default=1000)
self.Restart: str | Path | StringKey = PathStringKey(name='Restart', comment='The path to the ams.rkf file from which to restart the simulation.', gui_name='Restart from:', ispath=True, gui_type='.rkf {{{AMS result file} .rkf}}')
self.TimeStep: float | FloatKey = FloatKey(name='TimeStep', comment='The time difference per step.', default=0.25, unit='Femtoseconds')
self.Checkpoint: Conformers._Expander._MD._MolecularDynamics._Checkpoint = self._Checkpoint(name='Checkpoint', comment='Sets the frequency for storing the entire MD state necessary for restarting the calculation.')
self.InitialVelocities: Conformers._Expander._MD._MolecularDynamics._InitialVelocities = self._InitialVelocities(name='InitialVelocities', comment='Sets the frequency for printing to stdout and storing the molecular configuration on the .rkf file.')
self.Preserve: Conformers._Expander._MD._MolecularDynamics._Preserve = self._Preserve(name='Preserve', comment='Periodically remove numerical drift accumulated during the simulation to preserve different whole-system parameters.')
self.Print: Conformers._Expander._MD._MolecularDynamics._Print = self._Print(name='Print', comment='This block controls the printing of additional information to stdout.')
self.Shake: Conformers._Expander._MD._MolecularDynamics._Shake = self._Shake(name='Shake', comment='Parameters of the Shake/Rattle algorithm.')
self.Thermostat: Conformers._Expander._MD._MolecularDynamics._Thermostat = self._Thermostat(name='Thermostat', comment="This block allows to specify the use of a thermostat during the simulation. Depending on the selected thermostat type, different additional options may be needed to characterize the specific thermostat's behavior.", unique=False)
self.Trajectory: Conformers._Expander._MD._MolecularDynamics._Trajectory = self._Trajectory(name='Trajectory', comment='Sets the frequency for printing to stdout and storing the molecular configuration on the .rkf file.')
def __post_init__(self):
self.Blocksize: int | IntKey = IntKey(name='Blocksize', comment='The interval between the trajectory snapshots written to file that are extracted and optimized. By default all written snapshots are extracted.', hidden=True, default=1)
self.Multiples: int | IntKey = IntKey(name='Multiples', comment='The number of MD simulations per selected temperature and starting geometry. The default is 1.', hidden=True, default=1)
self.Ngeoms: int | IntKey = IntKey(name='Ngeoms', comment='At each temperature, MD simulations are started from Ngeoms different starting geometries. The starting geometries are extracted from the provided conformer set. If the conformer set is empty, then no more than a single geometry per temperature can be provided, limiting the total number of MD simulations.', default=4)
self.Temperatures: Iterable[float] | FloatListKey = FloatListKey(name='Temperatures', comment='The list of different temperatures at which MD simulations are run.', default=[400.0, 500.0], unit='Kelvin')
self.UseShake: BoolType | BoolKey = BoolKey(name='UseShake', comment='Constrain all -H bonds with shake. If turned on, the MD timestep is automatically increased.', default=False)
self.UseXtb: BoolType | BoolKey = BoolKey(name='UseXtb', comment='Use Grimmes XTB code to perform the MD simulations instead of AMS', hidden=True, default=False)
self.MolecularDynamics: Conformers._Expander._MD._MolecularDynamics = self._MolecularDynamics(name='MolecularDynamics', comment='Configures molecular dynamics (with the velocity-Verlet algorithm) with and without thermostats. This block allows to specify the details of the molecular dynamics calculation. Default values will be ignored.')
[docs] class _Preoptimization(FixedBlock):
r"""
If this block is enabled geometries will be preoptimized. After preoptimization the high energy conformers will be discarded, and then from the remaining set the unoptimized geometries will be optimized at higher level. This is to prevent the preoptimizer from collapsing different conformers into a single false minimum. As a result, preoptimization is only useful if MaxEnergy is chosen low.
:ivar Enable: Perform preoptimization at a low level of accuracy.
:vartype Enable: BoolType | BoolKey
:ivar PreoptFactor: This factor is multiplied with MaxEnergy, to determine which high energy conformers can be discarded after preoptimization.
:vartype PreoptFactor: int | IntKey
:ivar Engine: The engine specifics to be used for preoptimization.
:vartype Engine: EngineBlock
"""
[docs] class _Engine(EngineBlock):
r"""
The engine specifics to be used for preoptimization.
"""
def __post_init__(self):
pass
def __post_init__(self):
self.Enable: BoolType | BoolKey = BoolKey(name='Enable', comment='Perform preoptimization at a low level of accuracy.', default=False)
self.PreoptFactor: int | IntKey = IntKey(name='PreoptFactor', comment='This factor is multiplied with MaxEnergy, to determine which high energy conformers can be discarded after preoptimization.', default=2)
self.Engine: EngineBlock = self._Engine(name='Engine', comment='The engine specifics to be used for preoptimization.')
[docs] class _RDKitETKDG(FixedBlock):
r"""
Settings for the call to RDKits ETKDG conformer generator tool.
:ivar BestRMSDThreshold: After ETKDG conformer generation by RDKit, RDKit can be used to remove duplicates via the BestRMS algorithm. This filter does exactly the same as the RMSD equivalence detector in the Equivalence block.
:vartype BestRMSDThreshold: float | FloatKey
:ivar ConstrainedAtoms: The indices of the atoms to constrain during ETKDG conformer generation. The atom numbering starts at zero.
:vartype ConstrainedAtoms: Iterable[int] | IntListKey
:ivar Forcefield: The name of the RDKit forcefield to use for geometry optimization at the end of ETKDG conformer generation (by default no geometry optimization is performed). Using the RDKit internal optimization may make the subsequent geometry optimizations with AMS faster.
:vartype Forcefield: Literal["None", "UFF", "MMFF"]
:ivar Parallel: Experimental: Parallelize the RDKit generation step by calling the RDKit conformer generation method in parallel from multiple processes.
:vartype Parallel: BoolType | BoolKey
:ivar RMSDThreshold: Root Mean Square deviation threshold for removing similar/equivalent conformations during the RDKit ETKDG procedure. By default there is no pruning (value: -1).
:vartype RMSDThreshold: float | FloatKey
:ivar UseExpTorsionAnglePrefs: Impose experimental torsion angle preferences in RDKit ETKDG conformer generation. By default the RDKit version determines whether or not to switch this on.
:vartype UseExpTorsionAnglePrefs: str | StringKey
"""
def __post_init__(self):
self.BestRMSDThreshold: float | FloatKey = FloatKey(name='BestRMSDThreshold', comment='After ETKDG conformer generation by RDKit, RDKit can be used to remove duplicates via the BestRMS algorithm. This filter does exactly the same as the RMSD equivalence detector in the Equivalence block.', default=-1.0)
self.ConstrainedAtoms: Iterable[int] | IntListKey = IntListKey(name='ConstrainedAtoms', comment='The indices of the atoms to constrain during ETKDG conformer generation. The atom numbering starts at zero.', hidden=True)
self.Forcefield: Literal["None", "UFF", "MMFF"] = MultipleChoiceKey(name='Forcefield', comment='The name of the RDKit forcefield to use for geometry optimization at the end of ETKDG conformer generation (by default no geometry optimization is performed). Using the RDKit internal optimization may make the subsequent geometry optimizations with AMS faster.', default='None', choices=['None', 'UFF', 'MMFF'])
self.Parallel: BoolType | BoolKey = BoolKey(name='Parallel', comment='Experimental: Parallelize the RDKit generation step by calling the RDKit conformer generation method in parallel from multiple processes.', default=False)
self.RMSDThreshold: float | FloatKey = FloatKey(name='RMSDThreshold', comment='Root Mean Square deviation threshold for removing similar/equivalent conformations during the RDKit ETKDG procedure. By default there is no pruning (value: -1).', default=-1.0)
self.UseExpTorsionAnglePrefs: str | StringKey = StringKey(name='UseExpTorsionAnglePrefs', comment='Impose experimental torsion angle preferences in RDKit ETKDG conformer generation. By default the RDKit version determines whether or not to switch this on.', default='default')
def __post_init__(self):
self.AdjustInputBonds: BoolType | BoolKey = BoolKey(name='AdjustInputBonds', comment='If geometry optimization of the initial conformer results in bond changes, adjust the reference connectivity. If the changes are too severe, the calculation will stop.', default=True)
self.MaxEnergy: float | FloatKey = FloatKey(name='MaxEnergy', comment='Threshold for filtering out high-energy conformers. If the relative energy of a conformer with respect to the lowest conformer is larger than this value, the conformer will be discarded.', unit='kcal/mol')
self.Method: Literal["MD", "GC"] = MultipleChoiceKey(name='Method', comment='Method used to generate the conformers.', gui_name='Generator method:', default='GC', choices=['MD', 'GC'])
self.RNGSeed: int | IntKey = IntKey(name='RNGSeed', comment='Initial guesses for conformers can be randomly generated by RDKit, using the ETKDG algorithm. For reproducibility, a random number seed can be provided here.')
self.Verbose: BoolType | BoolKey = BoolKey(name='Verbose', comment='If set to True, print additional info about conformer equivalence to standard output.', hidden=True, default=False)
self.GC: Conformers._Expander._GC = self._GC(name='GC', comment='Options for the genetic algorithm for combinatorial expansion of conformer geometries. This generator only works if a non-zero set of conformers is already provided.')
self.MD: Conformers._Expander._MD = self._MD(name='MD', comment='Produces conformers by running a set of MD simulations at different elevated temperatures, extracting snapshots, and optimizing those.')
self.Preoptimization: Conformers._Expander._Preoptimization = self._Preoptimization(name='Preoptimization', comment='If this block is enabled geometries will be preoptimized. After preoptimization the high energy conformers will be discarded, and then from the remaining set the unoptimized geometries will be optimized at higher level. This is to prevent the preoptimizer from collapsing different conformers into a single false minimum. As a result, preoptimization is only useful if MaxEnergy is chosen low.')
self.RDKitETKDG: Conformers._Expander._RDKitETKDG = self._RDKitETKDG(name='RDKitETKDG', comment='Settings for the call to RDKits ETKDG conformer generator tool.')
[docs] class _Filter(FixedBlock):
r"""
Options for the conformer filtering.
:ivar MaxEnergy: Threshold for filtering out high-energy conformers. If the relative energy of a conformer with respect to the lowest conformer is larger than this value, the conformer will be discarded.
:vartype MaxEnergy: float | FloatKey
:ivar RemoveNonMinima: For the final set of conformers, explicitly check that the geometry corresponds to a local minimum, and remove it if it does not. Note: this will run a PES point characterization, which can be computationally expensive!
:vartype RemoveNonMinima: BoolType | BoolKey
"""
def __post_init__(self):
self.MaxEnergy: float | FloatKey = FloatKey(name='MaxEnergy', comment='Threshold for filtering out high-energy conformers. If the relative energy of a conformer with respect to the lowest conformer is larger than this value, the conformer will be discarded.', unit='kcal/mol')
self.RemoveNonMinima: BoolType | BoolKey = BoolKey(name='RemoveNonMinima', comment='For the final set of conformers, explicitly check that the geometry corresponds to a local minimum, and remove it if it does not. Note: this will run a PES point characterization, which can be computationally expensive!', default=False)
[docs] class _Generator(FixedBlock):
r"""
Options for the conformer generator.
:ivar AdjustInputBonds: If geometry optimization of the initial conformer results in bond changes, adjust the reference connectivity. If the changes are too severe, the calculation will stop.
:vartype AdjustInputBonds: BoolType | BoolKey
:ivar MaxEnergy: Threshold for filtering out high-energy conformers. If the relative energy of a conformer with respect to the lowest conformer is larger than this value, the conformer will be discarded.
:vartype MaxEnergy: float | FloatKey
:ivar Method: Method used to generate the conformers.
The RDKit generator is based on random distance matrix method. This is the recommended (and default) method.
The CREST Generator uses a multi-step workflow with meta-dynamics simulations to explore the conformers space of a molecule. This can be a powerful conformer search method, but it is generally computationally expensive compared to the RDKit generator.
The ANNEALING generator performs a simulated annealing simulation to explore conformer space.
:vartype Method: Literal["RDKit", "CREST", "METADYNAMICS", "ANNEALING", "TORSION"]
:ivar RNGSeed: Initial guesses for conformers can be randomly generated by RDKit, using the ETKDG algorithm. For reproducibility, a random number seed can be provided here.
:vartype RNGSeed: int | IntKey
:ivar Verbose: If set to True, print additional info about conformer equivalence to standard output.
:vartype Verbose: BoolType | BoolKey
:ivar ANNEALING: Options for the annealing generator. This generator creates conformers by performing a simulated annealing simulation.
:vartype ANNEALING: Conformers._Generator._ANNEALING
:ivar CREST: Options for the CREST generator. The CREST generator performs a set of metadynamics simulations (using the METADYNAMICS generator), then a set of MD simulations (using the MD expander), and finally it does a combinatorial expansion of the generated conformers using the GC expander. This sequence is repeated in an iterative fashion until the lowest energy conformer no longer changes.
:vartype CREST: Conformers._Generator._CREST
:ivar METADYNAMICS: Produces conformers by running a set of CREST-RMSD metadynamics simulations with different biases, extracting snapshots, and optimizing those.
:vartype METADYNAMICS: Conformers._Generator._METADYNAMICS
:ivar Preoptimization: If this block is enabled geometries will be preoptimized. After preoptimization the high energy conformers will be discarded, and then from the remaining set the unoptimized geometries will be optimized at higher level. This is to prevent the preoptimizer from collapsing different conformers into a single false minimum. As a result, preoptimization is only useful if MaxEnergy is chosen low.
:vartype Preoptimization: Conformers._Generator._Preoptimization
:ivar RDKit: Options for the RDKit generator. This generator produces initial guesses for conformers using the RDKit ETKDG method, followed by AMS geometry optimizations.
:vartype RDKit: Conformers._Generator._RDKit
:ivar RDKitETKDG: Settings for the call to RDKits ETKDG conformer generator tool.
:vartype RDKitETKDG: Conformers._Generator._RDKitETKDG
:ivar TORSION: Options for the TorsionGenerator, which generates geometries by enumerative rotation around rotatable bonds. This is the slowest of all generator, and quickly becomes infeasible for large systems. Currently does not work for systems with interconnected rings.
:vartype TORSION: Conformers._Generator._TORSION
"""
[docs] class _ANNEALING(FixedBlock):
r"""
Options for the annealing generator. This generator creates conformers by performing a simulated annealing simulation.
:ivar Blocksize: The spacing between the number of frames stored on the MD trajectory file, that will be used to generate conformers.
:vartype Blocksize: int | IntKey
:ivar Temperatures: The minimum and maximum temperature of the annealing simulation. The simulation will start at the highest temperature, and cool down to the lowest.
:vartype Temperatures: Iterable[float] | FloatListKey
:ivar UseShake: Constrain all -H bonds with shake. If turned on, the MD timestep is automatically increased.
:vartype UseShake: BoolType | BoolKey
:ivar MolecularDynamics: Configures molecular dynamics (with the velocity-Verlet algorithm) with and without thermostats. This block allows to specify the details of the molecular dynamics calculation. Default values will be ignored.
:vartype MolecularDynamics: Conformers._Generator._ANNEALING._MolecularDynamics
"""
[docs] class _MolecularDynamics(FixedBlock):
r"""
Configures molecular dynamics (with the velocity-Verlet algorithm) with and without thermostats. This block allows to specify the details of the molecular dynamics calculation. Default values will be ignored.
:ivar NSteps: The number of steps to be taken in the MD simulation.
:vartype NSteps: int | IntKey
:ivar Restart: The path to the ams.rkf file from which to restart the simulation.
:vartype Restart: str | Path | StringKey
:ivar TimeStep: The time difference per step.
:vartype TimeStep: float | FloatKey
:ivar Checkpoint: Sets the frequency for storing the entire MD state necessary for restarting the calculation.
:vartype Checkpoint: Conformers._Generator._ANNEALING._MolecularDynamics._Checkpoint
:ivar InitialVelocities: Sets the frequency for printing to stdout and storing the molecular configuration on the .rkf file.
:vartype InitialVelocities: Conformers._Generator._ANNEALING._MolecularDynamics._InitialVelocities
:ivar Preserve: Periodically remove numerical drift accumulated during the simulation to preserve different whole-system parameters.
:vartype Preserve: Conformers._Generator._ANNEALING._MolecularDynamics._Preserve
:ivar Print: This block controls the printing of additional information to stdout.
:vartype Print: Conformers._Generator._ANNEALING._MolecularDynamics._Print
:ivar Shake: Parameters of the Shake/Rattle algorithm.
:vartype Shake: Conformers._Generator._ANNEALING._MolecularDynamics._Shake
:ivar Thermostat: This block allows to specify the use of a thermostat during the simulation. Depending on the selected thermostat type, different additional options may be needed to characterize the specific thermostat's behavior.
:vartype Thermostat: Conformers._Generator._ANNEALING._MolecularDynamics._Thermostat
:ivar Trajectory: Sets the frequency for printing to stdout and storing the molecular configuration on the .rkf file.
:vartype Trajectory: Conformers._Generator._ANNEALING._MolecularDynamics._Trajectory
"""
[docs] class _Checkpoint(FixedBlock):
r"""
Sets the frequency for storing the entire MD state necessary for restarting the calculation.
:ivar Frequency: Write the MD state to the Molecule and MDResults sections on ams.rkf once every N steps. Setting this to zero disables checkpointing during the simulation, but one checkpoint at the very end of the simulation will always be written.
:vartype Frequency: int | IntKey
:ivar WriteProperties: Honor top-level Properties input block when writing engine results files.
DEPRECATED: This input option will be removed in AMS2026 and will be considered always enabled. If you rely on it being disabled, please contact [email protected].
:vartype WriteProperties: BoolType | BoolKey
"""
def __post_init__(self):
self.Frequency: int | IntKey = IntKey(name='Frequency', comment='Write the MD state to the Molecule and MDResults sections on ams.rkf once every N steps. Setting this to zero disables checkpointing during the simulation, but one checkpoint at the very end of the simulation will always be written.', gui_name='Checkpoint frequency:', default=1000)
self.WriteProperties: BoolType | BoolKey = BoolKey(name='WriteProperties', comment='Honor top-level Properties input block when writing engine results files.\n\nDEPRECATED: This input option will be removed in AMS2026 and will be considered always enabled. If you rely on it being disabled, please contact [email protected].', default=False)
[docs] class _InitialVelocities(FixedBlock):
r"""
Sets the frequency for printing to stdout and storing the molecular configuration on the .rkf file.
:ivar File: AMS RKF file containing the initial velocities.
:vartype File: str | Path | StringKey
:ivar RandomVelocitiesMethod: Specifies how are random velocities generated. Three methods are available.
Exact: Velocities are scaled to exactly match set random velocities temperature.
Boltzmann: Velocities are not scaled and sample Maxwell-Boltzmann distribution. However, the distribution is not corrected for constraints.
Gromacs: Velocities are scaled to match set random velocities temperature, but removal of net momentum is performed only after the scaling. Resulting kinetic energy is lower based on how much net momentum the system had.
:vartype RandomVelocitiesMethod: Literal["Exact", "Boltzmann", "Gromacs"]
:ivar Temperature: Sets the temperature for the Maxwell-Boltzmann distribution when the type of the initial velocities is set to random, in which case specifying this key is mandatory.
AMSinput will use the first temperature of the first thermostat as default.
:vartype Temperature: float | FloatKey
:ivar Type: Specifies the initial velocities to assign to the atoms. Three methods to assign velocities are available.
Zero: All atom are at rest at the beginning of the calculation.
Random: Initial atom velocities follow a Maxwell-Boltzmann distribution for the temperature given by the [MolecularDynamics%InitialVelocities%Temperature] keyword.
FromFile: Load the velocities from a previous ams result file.
Input: Atom's velocities are set to the values specified in the [MolecularDynamics%InitialVelocities%Values] block, which can be accessed via the Expert AMS panel in AMSinput.
:vartype Type: Literal["Zero", "Random", "FromFile", "Input"]
:ivar Values: This block specifies the velocity of each atom, in Angstrom/fs, when [MolecularDynamics%InitialVelocities%Type] is set to Input. Each row must contain three floating point values (corresponding to the x,y,z component of the velocity vector) and a number of rows equal to the number of atoms must be present, given in the same order as the [System%Atoms] block.
:vartype Values: str | Sequence[str] | FreeBlock
"""
[docs] class _Values(FreeBlock):
r"""
This block specifies the velocity of each atom, in Angstrom/fs, when [MolecularDynamics%InitialVelocities%Type] is set to Input. Each row must contain three floating point values (corresponding to the x,y,z component of the velocity vector) and a number of rows equal to the number of atoms must be present, given in the same order as the [System%Atoms] block.
"""
def __post_init__(self):
pass
def __post_init__(self):
self.File: str | Path | StringKey = PathStringKey(name='File', comment='AMS RKF file containing the initial velocities.', ispath=True, gui_type='{} {{{AMS result file} .rkf}}')
self.RandomVelocitiesMethod: Literal["Exact", "Boltzmann", "Gromacs"] = MultipleChoiceKey(name='RandomVelocitiesMethod', comment='Specifies how are random velocities generated. Three methods are available.\n\nExact: Velocities are scaled to exactly match set random velocities temperature. \n\nBoltzmann: Velocities are not scaled and sample Maxwell-Boltzmann distribution. However, the distribution is not corrected for constraints.\n\nGromacs: Velocities are scaled to match set random velocities temperature, but removal of net momentum is performed only after the scaling. Resulting kinetic energy is lower based on how much net momentum the system had.', gui_name='Velocity randomization method:', default='Exact', choices=['Exact', 'Boltzmann', 'Gromacs'])
self.Temperature: float | FloatKey = FloatKey(name='Temperature', comment='Sets the temperature for the Maxwell-Boltzmann distribution when the type of the initial velocities is set to random, in which case specifying this key is mandatory.\n\nAMSinput will use the first temperature of the first thermostat as default.', gui_name='Initial temperature:', unit='Kelvin')
self.Type: Literal["Zero", "Random", "FromFile", "Input"] = MultipleChoiceKey(name='Type', comment="Specifies the initial velocities to assign to the atoms. Three methods to assign velocities are available.\n\nZero: All atom are at rest at the beginning of the calculation.\n\nRandom: Initial atom velocities follow a Maxwell-Boltzmann distribution for the temperature given by the [MolecularDynamics%InitialVelocities%Temperature] keyword.\n\nFromFile: Load the velocities from a previous ams result file.\n\nInput: Atom's velocities are set to the values specified in the [MolecularDynamics%InitialVelocities%Values] block, which can be accessed via the Expert AMS panel in AMSinput.", gui_name='Initial velocities:', default='Random', choices=['Zero', 'Random', 'FromFile', 'Input'])
self.Values: str | Sequence[str] | FreeBlock = self._Values(name='Values', comment='This block specifies the velocity of each atom, in Angstrom/fs, when [MolecularDynamics%InitialVelocities%Type] is set to Input. Each row must contain three floating point values (corresponding to the x,y,z component of the velocity vector) and a number of rows equal to the number of atoms must be present, given in the same order as the [System%Atoms] block.')
[docs] class _Preserve(FixedBlock):
r"""
Periodically remove numerical drift accumulated during the simulation to preserve different whole-system parameters.
:ivar AngularMomentum: Remove overall angular momentum of the system. This option is ignored for 2D and 3D-periodic systems, and disabled by default for systems which are not translationally invariant (for example when frozen atoms are present).
:vartype AngularMomentum: BoolType | BoolKey
:ivar CenterOfMass: Translate the system to keep its center of mass at the coordinate origin. This option is not very useful for 3D-periodic systems.
:vartype CenterOfMass: BoolType | BoolKey
:ivar Momentum: Remove overall (linear) momentum of the system. This is disabled by default for systems which are not translationally invariant (for example when frozen atoms are present).
:vartype Momentum: BoolType | BoolKey
"""
def __post_init__(self):
self.AngularMomentum: BoolType | BoolKey = BoolKey(name='AngularMomentum', comment='Remove overall angular momentum of the system. This option is ignored for 2D and 3D-periodic systems, and disabled by default for systems which are not translationally invariant (for example when frozen atoms are present).', gui_name=': Angular momentum', default=True)
self.CenterOfMass: BoolType | BoolKey = BoolKey(name='CenterOfMass', comment='Translate the system to keep its center of mass at the coordinate origin. This option is not very useful for 3D-periodic systems.', gui_name=': Center of mass', default=False)
self.Momentum: BoolType | BoolKey = BoolKey(name='Momentum', comment='Remove overall (linear) momentum of the system. This is disabled by default for systems which are not translationally invariant (for example when frozen atoms are present).', gui_name='Preserve: Total momentum', default=True)
[docs] class _Print(FixedBlock):
r"""
This block controls the printing of additional information to stdout.
:ivar System: Print the chemical system before and after the simulation.
:vartype System: BoolType | BoolKey
:ivar Velocities: Print the atomic velocities before and after the simulation.
:vartype Velocities: BoolType | BoolKey
"""
def __post_init__(self):
self.System: BoolType | BoolKey = BoolKey(name='System', comment='Print the chemical system before and after the simulation.', default=False)
self.Velocities: BoolType | BoolKey = BoolKey(name='Velocities', comment='Print the atomic velocities before and after the simulation.', default=False)
[docs] class _Shake(FixedBlock):
r"""
Parameters of the Shake/Rattle algorithm.
:ivar All: Constraint description in one the following formats:
All [bondOrder] bonds at1 at2 [to distance]
All triangles at1 at2 at3
The first option constrains all bonds between atoms at1 at2 to a certain length, while the second - bonds at1-at2 and at2-at3 and the angle between them.
The [bondOrder] can be a number or a string such as single, double, triple or aromatic. If it's omitted then all bonds between specified atoms will be constrained. Atom names are case-sensitive and they must be as they are in the Atoms block, or an asterisk '*' denoting any atom. The distance, if present, must be in Angstrom. If it is omitted then the bond length from the initial geometry is used.
Important: only the bonds present in the system at certain points of the simulation (at the start or right after adding/removing atoms) can be constrained, which means that the bonds may need to be specified in the System block.
Warning: the triangles constraint should be used with care because each constrained bond or angle means removing one degree of freedom from the dynamics. When there are too many constraints (for example, "All triangles H C H" in methane) some of them may be linearly dependent, which will lead to an error in the temperature computation.
Valid examples:
All single bonds C C to 1.4
All bonds O H to 0.98
All bonds O H
All bonds H *
All triangles H * H
:vartype All: str | StringKey
:ivar ConvergeR2: Convergence criterion on the max squared difference, in atomic units.
:vartype ConvergeR2: float | FloatKey
:ivar ConvergeRV: Convergence criterion on the orthogonality of the constraint and the relative atomic velocity, in atomic units.
:vartype ConvergeRV: float | FloatKey
:ivar Iterations: Number of iterations.
:vartype Iterations: int | IntKey
:ivar ShakeInitialCoordinates: Apply constraints before computing the first energy and gradients.
:vartype ShakeInitialCoordinates: BoolType | BoolKey
"""
def __post_init__(self):
self.All: str | StringKey = StringKey(name='All', comment='Constraint description in one the following formats: \nAll [bondOrder] bonds at1 at2 [to distance]\nAll triangles at1 at2 at3\n\nThe first option constrains all bonds between atoms at1 at2 to a certain length, while the second - bonds at1-at2 and at2-at3 and the angle between them.\n\nThe [bondOrder] can be a number or a string such as single, double, triple or aromatic. If it\'s omitted then all bonds between specified atoms will be constrained. Atom names are case-sensitive and they must be as they are in the Atoms block, or an asterisk \'*\' denoting any atom. The distance, if present, must be in Angstrom. If it is omitted then the bond length from the initial geometry is used.\n\nImportant: only the bonds present in the system at certain points of the simulation (at the start or right after adding/removing atoms) can be constrained, which means that the bonds may need to be specified in the System block.\n\nWarning: the triangles constraint should be used with care because each constrained bond or angle means removing one degree of freedom from the dynamics. When there are too many constraints (for example, "All triangles H C H" in methane) some of them may be linearly dependent, which will lead to an error in the temperature computation. \n\nValid examples:\nAll single bonds C C to 1.4\nAll bonds O H to 0.98\nAll bonds O H\nAll bonds H *\nAll triangles H * H', unique=False, gui_name='Constrain all:')
self.ConvergeR2: float | FloatKey = FloatKey(name='ConvergeR2', comment='Convergence criterion on the max squared difference, in atomic units.', default=1e-08)
self.ConvergeRV: float | FloatKey = FloatKey(name='ConvergeRV', comment='Convergence criterion on the orthogonality of the constraint and the relative atomic velocity, in atomic units.', default=1e-08)
self.Iterations: int | IntKey = IntKey(name='Iterations', comment='Number of iterations.', default=100)
self.ShakeInitialCoordinates: BoolType | BoolKey = BoolKey(name='ShakeInitialCoordinates', comment='Apply constraints before computing the first energy and gradients.', default=True)
[docs] class _Thermostat(FixedBlock):
r"""
This block allows to specify the use of a thermostat during the simulation. Depending on the selected thermostat type, different additional options may be needed to characterize the specific thermostat's behavior.
:ivar BerendsenApply: Select how to apply the scaling correction for the Berendsen thermostat:
- per-atom-velocity (Local)
- on the molecular system as a whole (Global).
:vartype BerendsenApply: Literal["Local", "Global"]
:ivar ChainLength: Number of individual thermostats forming the NHC thermostat
:vartype ChainLength: int | IntKey
:ivar Duration: Specifies how many steps should a transition from a particular temperature to the next one in sequence take.
:vartype Duration: Iterable[int] | IntListKey
:ivar ExcludedDirection: Exclude a component of the velocities from rescaling by the thermostat. For example in NEMD simulations, when a shear force/velocity is applied in the x direction, the x-direction is often excluded from thermostatting. This currently only works for the Nose-Hoover thermostat.
:vartype ExcludedDirection: Literal["None", "X", "Y", "Z"]
:ivar Friction: Friction coefficient used in langevin dynamics
:vartype Friction: float | FloatKey
:ivar Region: The identifier of the region to thermostat. The default `*` applies the thermostat to the entire system. The value can by a plain region name, or a region expression, e.g. `*-myregion` to thermostat all atoms that are not in myregion, or `regionA+regionB` to thermostat the union of the 'regionA' and 'regionB'. Note that if multiple thermostats are used, their regions may not overlap.
:vartype Region: str | StringKey
:ivar ScaleFrequency: Optional parameter used only by the Scale thermostat.
If specified, the thermostat will be applied every N steps, using that step's ensemble temperature and the specified thermostat temperature to compute the scaling factor.
If not specified, the thermostat will be applied at every step, using the mean temperature of the ensemble and the specified thermostat temperature to compute the scaling factor.
:vartype ScaleFrequency: int | IntKey
:ivar Tau: The time constant of the thermostat.
:vartype Tau: float | FloatKey
:ivar Temperature: The target temperature of the thermostat.
You can specify multiple temperatures (separated by spaces). In that case the Duration field specifies how many steps to use for the transition from one T to the next T (using a linear ramp). For NHC thermostat, the temperature may not be zero.
:vartype Temperature: Iterable[float] | FloatListKey
:ivar Type: Selects the type of the thermostat.
:vartype Type: Literal["None", "Scale", "Berendsen", "NHC", "Langevin"]
"""
def __post_init__(self):
self.BerendsenApply: Literal["Local", "Global"] = MultipleChoiceKey(name='BerendsenApply', comment='Select how to apply the scaling correction for the Berendsen thermostat:\n\n- per-atom-velocity (Local)\n- on the molecular system as a whole (Global).', gui_name='Apply Berendsen:', default='Global', choices=['Local', 'Global'])
self.ChainLength: int | IntKey = IntKey(name='ChainLength', comment='Number of individual thermostats forming the NHC thermostat', gui_name='NHC chain length:', default=10)
self.Duration: Iterable[int] | IntListKey = IntListKey(name='Duration', comment='Specifies how many steps should a transition from a particular temperature to the next one in sequence take.', gui_name='Duration(s)')
self.ExcludedDirection: Literal["None", "X", "Y", "Z"] = MultipleChoiceKey(name='ExcludedDirection', comment='Exclude a component of the velocities from rescaling by the thermostat. For example in NEMD simulations, when a shear force/velocity is applied in the x direction, the x-direction is often excluded from thermostatting. This currently only works for the Nose-Hoover thermostat.', hidden=True, default='None', choices=['None', 'X', 'Y', 'Z'])
self.Friction: float | FloatKey = FloatKey(name='Friction', comment='Friction coefficient used in langevin dynamics', hidden=True, default=1.0)
self.Region: str | StringKey = StringKey(name='Region', comment="The identifier of the region to thermostat. The default `*` applies the thermostat to the entire system. The value can by a plain region name, or a region expression, e.g. `*-myregion` to thermostat all atoms that are not in myregion, or `regionA+regionB` to thermostat the union of the 'regionA' and 'regionB'. Note that if multiple thermostats are used, their regions may not overlap.", default='*', gui_type='region')
self.ScaleFrequency: int | IntKey = IntKey(name='ScaleFrequency', comment="Optional parameter used only by the Scale thermostat.\n\nIf specified, the thermostat will be applied every N steps, using that step's ensemble temperature and the specified thermostat temperature to compute the scaling factor.\n\nIf not specified, the thermostat will be applied at every step, using the mean temperature of the ensemble and the specified thermostat temperature to compute the scaling factor.", hidden=True)
self.Tau: float | FloatKey = FloatKey(name='Tau', comment='The time constant of the thermostat.', gui_name='Damping constant:', unit='Femtoseconds')
self.Temperature: Iterable[float] | FloatListKey = FloatListKey(name='Temperature', comment='The target temperature of the thermostat.\n\nYou can specify multiple temperatures (separated by spaces). In that case the Duration field specifies how many steps to use for the transition from one T to the next T (using a linear ramp). For NHC thermostat, the temperature may not be zero.', gui_name='Temperature(s)', unit='Kelvin')
self.Type: Literal["None", "Scale", "Berendsen", "NHC", "Langevin"] = MultipleChoiceKey(name='Type', comment='Selects the type of the thermostat.', gui_name='Thermostat:', default='None', choices=['None', 'Scale', 'Berendsen', 'NHC', 'Langevin'], hiddenchoices=['Scale', 'Langevin'])
[docs] class _Trajectory(FixedBlock):
r"""
Sets the frequency for printing to stdout and storing the molecular configuration on the .rkf file.
:ivar EngineResultsFreq: Write MDStep*.rkf files with engine-specific results once every N steps. Setting this to zero disables writing engine results files except for one file at the end of the simulation. If unset or negative, defaults to the value of Checkpoint%Frequency.
:vartype EngineResultsFreq: int | IntKey
:ivar ExitConditionFreq: Check the exit conditions every N steps. By default this is done every SamplingFreq steps.
:vartype ExitConditionFreq: int | IntKey
:ivar PrintFreq: Print current thermodynamic properties to the output every N steps. By default this is done every SamplingFreq steps.
:vartype PrintFreq: int | IntKey
:ivar SamplingFreq: Write the molecular geometry (and possibly other properties) to the ams.rkf file once every N steps.
:vartype SamplingFreq: int | IntKey
:ivar TProfileGridPoints: Number of points in the temperature profile. If TProfileGridPoints > 0, a temperature profile along each of the three lattice axes will be written to the .rkf file. The temperature at a given profile point is calculated as the total temperature of all atoms inside the corresponding slice of the simulation box, time-averaged over all MD steps since the previous snapshot. By default, no profile is generated.
:vartype TProfileGridPoints: int | IntKey
:ivar WriteBonds: Write detected bonds to the .rkf file.
:vartype WriteBonds: BoolType | BoolKey
:ivar WriteCharges: Write current atomic point charges (if available) to the .rkf file. Disable this to reduce trajectory size if you do not need to analyze charges.
:vartype WriteCharges: BoolType | BoolKey
:ivar WriteCoordinates: Write atomic coordinates to the .rkf file.
:vartype WriteCoordinates: BoolType | BoolKey
:ivar WriteEngineGradients: Write atomic gradients (negative of the atomic forces, as calculated by the engine) to the History section of ams.rkf.
:vartype WriteEngineGradients: BoolType | BoolKey
:ivar WriteMolecules: Write the results of molecule analysis to the .rkf file.
:vartype WriteMolecules: BoolType | BoolKey
:ivar WriteVelocities: Write velocities to the .rkf file. Disable this to reduce trajectory size if you do not need to analyze the velocities.
:vartype WriteVelocities: BoolType | BoolKey
"""
def __post_init__(self):
self.EngineResultsFreq: int | IntKey = IntKey(name='EngineResultsFreq', comment='Write MDStep*.rkf files with engine-specific results once every N steps. Setting this to zero disables writing engine results files except for one file at the end of the simulation. If unset or negative, defaults to the value of Checkpoint%Frequency.', gui_name='Engine results frequency:')
self.ExitConditionFreq: int | IntKey = IntKey(name='ExitConditionFreq', comment='Check the exit conditions every N steps. By default this is done every SamplingFreq steps.', gui_name='Exit condition frequency:')
self.PrintFreq: int | IntKey = IntKey(name='PrintFreq', comment='Print current thermodynamic properties to the output every N steps. By default this is done every SamplingFreq steps.', gui_name='Printing frequency:')
self.SamplingFreq: int | IntKey = IntKey(name='SamplingFreq', comment='Write the molecular geometry (and possibly other properties) to the ams.rkf file once every N steps.', gui_name='Sample frequency:', default=100)
self.TProfileGridPoints: int | IntKey = IntKey(name='TProfileGridPoints', comment='Number of points in the temperature profile. If TProfileGridPoints > 0, a temperature profile along each of the three lattice axes will be written to the .rkf file. The temperature at a given profile point is calculated as the total temperature of all atoms inside the corresponding slice of the simulation box, time-averaged over all MD steps since the previous snapshot.\u200b By default, no profile is generated.', default=0)
self.WriteBonds: BoolType | BoolKey = BoolKey(name='WriteBonds', comment='Write detected bonds to the .rkf file.', default=True)
self.WriteCharges: BoolType | BoolKey = BoolKey(name='WriteCharges', comment='Write current atomic point charges (if available) to the .rkf file. Disable this to reduce trajectory size if you do not need to analyze charges.', default=True)
self.WriteCoordinates: BoolType | BoolKey = BoolKey(name='WriteCoordinates', comment='Write atomic coordinates to the .rkf file.', default=True)
self.WriteEngineGradients: BoolType | BoolKey = BoolKey(name='WriteEngineGradients', comment='Write atomic gradients (negative of the atomic forces, as calculated by the engine) to the History section of ams.rkf.', default=False)
self.WriteMolecules: BoolType | BoolKey = BoolKey(name='WriteMolecules', comment='Write the results of molecule analysis to the .rkf file.', default=True)
self.WriteVelocities: BoolType | BoolKey = BoolKey(name='WriteVelocities', comment='Write velocities to the .rkf file. Disable this to reduce trajectory size if you do not need to analyze the velocities.', default=True)
def __post_init__(self):
self.NSteps: int | IntKey = IntKey(name='NSteps', comment='The number of steps to be taken in the MD simulation.', gui_name='Number of steps:', default=1000)
self.Restart: str | Path | StringKey = PathStringKey(name='Restart', comment='The path to the ams.rkf file from which to restart the simulation.', gui_name='Restart from:', ispath=True, gui_type='.rkf {{{AMS result file} .rkf}}')
self.TimeStep: float | FloatKey = FloatKey(name='TimeStep', comment='The time difference per step.', default=0.25, unit='Femtoseconds')
self.Checkpoint: Conformers._Generator._ANNEALING._MolecularDynamics._Checkpoint = self._Checkpoint(name='Checkpoint', comment='Sets the frequency for storing the entire MD state necessary for restarting the calculation.')
self.InitialVelocities: Conformers._Generator._ANNEALING._MolecularDynamics._InitialVelocities = self._InitialVelocities(name='InitialVelocities', comment='Sets the frequency for printing to stdout and storing the molecular configuration on the .rkf file.')
self.Preserve: Conformers._Generator._ANNEALING._MolecularDynamics._Preserve = self._Preserve(name='Preserve', comment='Periodically remove numerical drift accumulated during the simulation to preserve different whole-system parameters.')
self.Print: Conformers._Generator._ANNEALING._MolecularDynamics._Print = self._Print(name='Print', comment='This block controls the printing of additional information to stdout.')
self.Shake: Conformers._Generator._ANNEALING._MolecularDynamics._Shake = self._Shake(name='Shake', comment='Parameters of the Shake/Rattle algorithm.')
self.Thermostat: Conformers._Generator._ANNEALING._MolecularDynamics._Thermostat = self._Thermostat(name='Thermostat', comment="This block allows to specify the use of a thermostat during the simulation. Depending on the selected thermostat type, different additional options may be needed to characterize the specific thermostat's behavior.", unique=False)
self.Trajectory: Conformers._Generator._ANNEALING._MolecularDynamics._Trajectory = self._Trajectory(name='Trajectory', comment='Sets the frequency for printing to stdout and storing the molecular configuration on the .rkf file.')
def __post_init__(self):
self.Blocksize: int | IntKey = IntKey(name='Blocksize', comment='The spacing between the number of frames stored on the MD trajectory file, that will be used to generate conformers.', hidden=True, default=1)
self.Temperatures: Iterable[float] | FloatListKey = FloatListKey(name='Temperatures', comment='The minimum and maximum temperature of the annealing simulation. The simulation will start at the highest temperature, and cool down to the lowest.', default=[298.0, 798.0], unit='Kelvin')
self.UseShake: BoolType | BoolKey = BoolKey(name='UseShake', comment='Constrain all -H bonds with shake. If turned on, the MD timestep is automatically increased.', default=False)
self.MolecularDynamics: Conformers._Generator._ANNEALING._MolecularDynamics = self._MolecularDynamics(name='MolecularDynamics', comment='Configures molecular dynamics (with the velocity-Verlet algorithm) with and without thermostats. This block allows to specify the details of the molecular dynamics calculation. Default values will be ignored.')
[docs] class _CREST(FixedBlock):
r"""
Options for the CREST generator. The CREST generator performs a set of metadynamics simulations (using the METADYNAMICS generator), then a set of MD simulations (using the MD expander), and finally it does a combinatorial expansion of the generated conformers using the GC expander. This sequence is repeated in an iterative fashion until the lowest energy conformer no longer changes.
:ivar ConvergenceQualityCrude: The tightness of the convergence of the crude geometry pre-optimizations. If set to none it will be selected two levels below ConvergenceQuality.
:vartype ConvergenceQualityCrude: Literal["Normal", "Good", "VeryGood", "Excellent", "None"]
:ivar ConvergenceQualityTight: The tightness of the convergence of the final geometry optimizations. If set to none it will be selected the same as ConvergenceQuality.
:vartype ConvergenceQualityTight: Literal["Normal", "Good", "VeryGood", "Excellent", "None"]
:ivar GCStep: Wether or not to include the combinatorial expansion of the conformers using the GC Generator. For big systems this step can be very time consuming. By default it is set to True.
:vartype GCStep: BoolType | BoolKey
:ivar NCycles: The maximum number of CREST cycles (by default the number is 10). If the lowest conformer energy converges before then, Crest exits.
:vartype NCycles: int | IntKey
:ivar UseShake: Wether or not SHAKE should be turned on in the MD and Metadynamics simulations. If this is turned on, the MD timestep is automatically increased (from 2 to 5 fs).
:vartype UseShake: BoolType | BoolKey
"""
def __post_init__(self):
self.ConvergenceQualityCrude: Literal["Normal", "Good", "VeryGood", "Excellent", "None"] = MultipleChoiceKey(name='ConvergenceQualityCrude', comment='The tightness of the convergence of the crude geometry pre-optimizations. If set to none it will be selected two levels below ConvergenceQuality.', default='None', choices=['Normal', 'Good', 'VeryGood', 'Excellent', 'None'])
self.ConvergenceQualityTight: Literal["Normal", "Good", "VeryGood", "Excellent", "None"] = MultipleChoiceKey(name='ConvergenceQualityTight', comment='The tightness of the convergence of the final geometry optimizations. If set to none it will be selected the same as ConvergenceQuality.', default='None', choices=['Normal', 'Good', 'VeryGood', 'Excellent', 'None'])
self.GCStep: BoolType | BoolKey = BoolKey(name='GCStep', comment='Wether or not to include the combinatorial expansion of the conformers using the GC Generator. For big systems this step can be very time consuming. By default it is set to True.', default=True)
self.NCycles: int | IntKey = IntKey(name='NCycles', comment='The maximum number of CREST cycles (by default the number is 10). If the lowest conformer energy converges before then, Crest exits.', default=10)
self.UseShake: BoolType | BoolKey = BoolKey(name='UseShake', comment='Wether or not SHAKE should be turned on in the MD and Metadynamics simulations. If this is turned on, the MD timestep is automatically increased (from 2 to 5 fs).', default=True)
[docs] class _METADYNAMICS(FixedBlock):
r"""
Produces conformers by running a set of CREST-RMSD metadynamics simulations with different biases, extracting snapshots, and optimizing those.
:ivar Blocksize: The interval between the trajectory snapshots written to file that are extracted and optimized. By default all written snapshots are extracted.
:vartype Blocksize: int | IntKey
:ivar ConvergenceQualityCrude: The tightness of the convergence of the crude geometry pre-optimizations. If set to none it will be selected two levels below ConvergenceQuality.
:vartype ConvergenceQualityCrude: Literal["normal", "good", "verygood", "excellent", "none"]
:ivar MaxHeight: The maximum Gaussian height used in a metadynamics simulation.
:vartype MaxHeight: float | FloatKey
:ivar MaxWidth: The maximum Gaussian width used in a metadynamics simulation.
:vartype MaxWidth: float | FloatKey
:ivar MinHeight: The minimum Gaussian height used in a metadynamics simulation.
:vartype MinHeight: float | FloatKey
:ivar NCycles: The maximum number of cycles of metadynamics simulations. The generator stops when either this number is reached, or the conformer set is stable.
:vartype NCycles: int | IntKey
:ivar NWidthsHeights: The number of different Gaussian widths and heights respectively used in the metadynamics simulations. By default 4 different widths are used and 3 different heights, resulting in 12 different metadynamics simulations.
:vartype NWidthsHeights: Iterable[int] | IntListKey
:ivar Restartdir: A PLAMS folder containing the results from a previous conformers generation using the METADYNAMICS generator.
:vartype Restartdir: str | StringKey
:ivar SimulationSuccessFraction: The fraction of planned metadynamics steps that has to have succeeded in order for the metadynamics iteration to be considered a success.
:vartype SimulationSuccessFraction: float | FloatKey
:ivar UseShake: Constrain all -H bonds with shake. If turned on, the MD timestep is automatically increased.
:vartype UseShake: BoolType | BoolKey
:ivar UseXtb: Use Grimmes xTB code to perform the MD simulations instead of AMS
:vartype UseXtb: BoolType | BoolKey
:ivar WidthIncrement: The increment between Gaussian widths used in subsequent metadynamics simulations.
:vartype WidthIncrement: float | FloatKey
:ivar AdditionalGaussians: An additional set of Gaussian widths and heights, each representing the Gaussians of a single additional metadynamics simulation. By default, if nothing is provided, then two Gaussians are used: ([(width:0.1 Angstrom, height:0.001 Hartree), (width:0.8 Angstrom, height:0.005 Hartree)])
:vartype AdditionalGaussians: Conformers._Generator._METADYNAMICS._AdditionalGaussians
:ivar MolecularDynamics: Configures molecular dynamics (with the velocity-Verlet algorithm) with and without thermostats. This block allows to specify the details of the molecular dynamics calculation. Default values will be ignored.
:vartype MolecularDynamics: Conformers._Generator._METADYNAMICS._MolecularDynamics
"""
[docs] class _AdditionalGaussians(FixedBlock):
r"""
An additional set of Gaussian widths and heights, each representing the Gaussians of a single additional metadynamics simulation. By default, if nothing is provided, then two Gaussians are used: ([(width:0.1 Angstrom, height:0.001 Hartree), (width:0.8 Angstrom, height:0.005 Hartree)])
:ivar Height: The height of the Gaussians in an additional metadynamics simulation, in Hartree.
:vartype Height: float | FloatKey
:ivar Width: The width of the Gaussians in an additional metadynanics simulation, in Angstrom.
:vartype Width: float | FloatKey
"""
def __post_init__(self):
self.Height: float | FloatKey = FloatKey(name='Height', comment='The height of the Gaussians in an additional metadynamics simulation, in Hartree.')
self.Width: float | FloatKey = FloatKey(name='Width', comment='The width of the Gaussians in an additional metadynanics simulation, in Angstrom.')
[docs] class _MolecularDynamics(FixedBlock):
r"""
Configures molecular dynamics (with the velocity-Verlet algorithm) with and without thermostats. This block allows to specify the details of the molecular dynamics calculation. Default values will be ignored.
:ivar NSteps: The number of steps to be taken in the MD simulation.
:vartype NSteps: int | IntKey
:ivar Restart: The path to the ams.rkf file from which to restart the simulation.
:vartype Restart: str | Path | StringKey
:ivar TimeStep: The time difference per step.
:vartype TimeStep: float | FloatKey
:ivar Checkpoint: Sets the frequency for storing the entire MD state necessary for restarting the calculation.
:vartype Checkpoint: Conformers._Generator._METADYNAMICS._MolecularDynamics._Checkpoint
:ivar InitialVelocities: Sets the frequency for printing to stdout and storing the molecular configuration on the .rkf file.
:vartype InitialVelocities: Conformers._Generator._METADYNAMICS._MolecularDynamics._InitialVelocities
:ivar Preserve: Periodically remove numerical drift accumulated during the simulation to preserve different whole-system parameters.
:vartype Preserve: Conformers._Generator._METADYNAMICS._MolecularDynamics._Preserve
:ivar Print: This block controls the printing of additional information to stdout.
:vartype Print: Conformers._Generator._METADYNAMICS._MolecularDynamics._Print
:ivar Shake: Parameters of the Shake/Rattle algorithm.
:vartype Shake: Conformers._Generator._METADYNAMICS._MolecularDynamics._Shake
:ivar Thermostat: This block allows to specify the use of a thermostat during the simulation. Depending on the selected thermostat type, different additional options may be needed to characterize the specific thermostat's behavior.
:vartype Thermostat: Conformers._Generator._METADYNAMICS._MolecularDynamics._Thermostat
:ivar Trajectory: Sets the frequency for printing to stdout and storing the molecular configuration on the .rkf file.
:vartype Trajectory: Conformers._Generator._METADYNAMICS._MolecularDynamics._Trajectory
"""
[docs] class _Checkpoint(FixedBlock):
r"""
Sets the frequency for storing the entire MD state necessary for restarting the calculation.
:ivar Frequency: Write the MD state to the Molecule and MDResults sections on ams.rkf once every N steps. Setting this to zero disables checkpointing during the simulation, but one checkpoint at the very end of the simulation will always be written.
:vartype Frequency: int | IntKey
:ivar WriteProperties: Honor top-level Properties input block when writing engine results files.
DEPRECATED: This input option will be removed in AMS2026 and will be considered always enabled. If you rely on it being disabled, please contact [email protected].
:vartype WriteProperties: BoolType | BoolKey
"""
def __post_init__(self):
self.Frequency: int | IntKey = IntKey(name='Frequency', comment='Write the MD state to the Molecule and MDResults sections on ams.rkf once every N steps. Setting this to zero disables checkpointing during the simulation, but one checkpoint at the very end of the simulation will always be written.', gui_name='Checkpoint frequency:', default=1000)
self.WriteProperties: BoolType | BoolKey = BoolKey(name='WriteProperties', comment='Honor top-level Properties input block when writing engine results files.\n\nDEPRECATED: This input option will be removed in AMS2026 and will be considered always enabled. If you rely on it being disabled, please contact [email protected].', default=False)
[docs] class _InitialVelocities(FixedBlock):
r"""
Sets the frequency for printing to stdout and storing the molecular configuration on the .rkf file.
:ivar File: AMS RKF file containing the initial velocities.
:vartype File: str | Path | StringKey
:ivar RandomVelocitiesMethod: Specifies how are random velocities generated. Three methods are available.
Exact: Velocities are scaled to exactly match set random velocities temperature.
Boltzmann: Velocities are not scaled and sample Maxwell-Boltzmann distribution. However, the distribution is not corrected for constraints.
Gromacs: Velocities are scaled to match set random velocities temperature, but removal of net momentum is performed only after the scaling. Resulting kinetic energy is lower based on how much net momentum the system had.
:vartype RandomVelocitiesMethod: Literal["Exact", "Boltzmann", "Gromacs"]
:ivar Temperature: Sets the temperature for the Maxwell-Boltzmann distribution when the type of the initial velocities is set to random, in which case specifying this key is mandatory.
AMSinput will use the first temperature of the first thermostat as default.
:vartype Temperature: float | FloatKey
:ivar Type: Specifies the initial velocities to assign to the atoms. Three methods to assign velocities are available.
Zero: All atom are at rest at the beginning of the calculation.
Random: Initial atom velocities follow a Maxwell-Boltzmann distribution for the temperature given by the [MolecularDynamics%InitialVelocities%Temperature] keyword.
FromFile: Load the velocities from a previous ams result file.
Input: Atom's velocities are set to the values specified in the [MolecularDynamics%InitialVelocities%Values] block, which can be accessed via the Expert AMS panel in AMSinput.
:vartype Type: Literal["Zero", "Random", "FromFile", "Input"]
:ivar Values: This block specifies the velocity of each atom, in Angstrom/fs, when [MolecularDynamics%InitialVelocities%Type] is set to Input. Each row must contain three floating point values (corresponding to the x,y,z component of the velocity vector) and a number of rows equal to the number of atoms must be present, given in the same order as the [System%Atoms] block.
:vartype Values: str | Sequence[str] | FreeBlock
"""
[docs] class _Values(FreeBlock):
r"""
This block specifies the velocity of each atom, in Angstrom/fs, when [MolecularDynamics%InitialVelocities%Type] is set to Input. Each row must contain three floating point values (corresponding to the x,y,z component of the velocity vector) and a number of rows equal to the number of atoms must be present, given in the same order as the [System%Atoms] block.
"""
def __post_init__(self):
pass
def __post_init__(self):
self.File: str | Path | StringKey = PathStringKey(name='File', comment='AMS RKF file containing the initial velocities.', ispath=True, gui_type='{} {{{AMS result file} .rkf}}')
self.RandomVelocitiesMethod: Literal["Exact", "Boltzmann", "Gromacs"] = MultipleChoiceKey(name='RandomVelocitiesMethod', comment='Specifies how are random velocities generated. Three methods are available.\n\nExact: Velocities are scaled to exactly match set random velocities temperature. \n\nBoltzmann: Velocities are not scaled and sample Maxwell-Boltzmann distribution. However, the distribution is not corrected for constraints.\n\nGromacs: Velocities are scaled to match set random velocities temperature, but removal of net momentum is performed only after the scaling. Resulting kinetic energy is lower based on how much net momentum the system had.', gui_name='Velocity randomization method:', default='Exact', choices=['Exact', 'Boltzmann', 'Gromacs'])
self.Temperature: float | FloatKey = FloatKey(name='Temperature', comment='Sets the temperature for the Maxwell-Boltzmann distribution when the type of the initial velocities is set to random, in which case specifying this key is mandatory.\n\nAMSinput will use the first temperature of the first thermostat as default.', gui_name='Initial temperature:', unit='Kelvin')
self.Type: Literal["Zero", "Random", "FromFile", "Input"] = MultipleChoiceKey(name='Type', comment="Specifies the initial velocities to assign to the atoms. Three methods to assign velocities are available.\n\nZero: All atom are at rest at the beginning of the calculation.\n\nRandom: Initial atom velocities follow a Maxwell-Boltzmann distribution for the temperature given by the [MolecularDynamics%InitialVelocities%Temperature] keyword.\n\nFromFile: Load the velocities from a previous ams result file.\n\nInput: Atom's velocities are set to the values specified in the [MolecularDynamics%InitialVelocities%Values] block, which can be accessed via the Expert AMS panel in AMSinput.", gui_name='Initial velocities:', default='Random', choices=['Zero', 'Random', 'FromFile', 'Input'])
self.Values: str | Sequence[str] | FreeBlock = self._Values(name='Values', comment='This block specifies the velocity of each atom, in Angstrom/fs, when [MolecularDynamics%InitialVelocities%Type] is set to Input. Each row must contain three floating point values (corresponding to the x,y,z component of the velocity vector) and a number of rows equal to the number of atoms must be present, given in the same order as the [System%Atoms] block.')
[docs] class _Preserve(FixedBlock):
r"""
Periodically remove numerical drift accumulated during the simulation to preserve different whole-system parameters.
:ivar AngularMomentum: Remove overall angular momentum of the system. This option is ignored for 2D and 3D-periodic systems, and disabled by default for systems which are not translationally invariant (for example when frozen atoms are present).
:vartype AngularMomentum: BoolType | BoolKey
:ivar CenterOfMass: Translate the system to keep its center of mass at the coordinate origin. This option is not very useful for 3D-periodic systems.
:vartype CenterOfMass: BoolType | BoolKey
:ivar Momentum: Remove overall (linear) momentum of the system. This is disabled by default for systems which are not translationally invariant (for example when frozen atoms are present).
:vartype Momentum: BoolType | BoolKey
"""
def __post_init__(self):
self.AngularMomentum: BoolType | BoolKey = BoolKey(name='AngularMomentum', comment='Remove overall angular momentum of the system. This option is ignored for 2D and 3D-periodic systems, and disabled by default for systems which are not translationally invariant (for example when frozen atoms are present).', gui_name=': Angular momentum', default=True)
self.CenterOfMass: BoolType | BoolKey = BoolKey(name='CenterOfMass', comment='Translate the system to keep its center of mass at the coordinate origin. This option is not very useful for 3D-periodic systems.', gui_name=': Center of mass', default=False)
self.Momentum: BoolType | BoolKey = BoolKey(name='Momentum', comment='Remove overall (linear) momentum of the system. This is disabled by default for systems which are not translationally invariant (for example when frozen atoms are present).', gui_name='Preserve: Total momentum', default=True)
[docs] class _Print(FixedBlock):
r"""
This block controls the printing of additional information to stdout.
:ivar System: Print the chemical system before and after the simulation.
:vartype System: BoolType | BoolKey
:ivar Velocities: Print the atomic velocities before and after the simulation.
:vartype Velocities: BoolType | BoolKey
"""
def __post_init__(self):
self.System: BoolType | BoolKey = BoolKey(name='System', comment='Print the chemical system before and after the simulation.', default=False)
self.Velocities: BoolType | BoolKey = BoolKey(name='Velocities', comment='Print the atomic velocities before and after the simulation.', default=False)
[docs] class _Shake(FixedBlock):
r"""
Parameters of the Shake/Rattle algorithm.
:ivar All: Constraint description in one the following formats:
All [bondOrder] bonds at1 at2 [to distance]
All triangles at1 at2 at3
The first option constrains all bonds between atoms at1 at2 to a certain length, while the second - bonds at1-at2 and at2-at3 and the angle between them.
The [bondOrder] can be a number or a string such as single, double, triple or aromatic. If it's omitted then all bonds between specified atoms will be constrained. Atom names are case-sensitive and they must be as they are in the Atoms block, or an asterisk '*' denoting any atom. The distance, if present, must be in Angstrom. If it is omitted then the bond length from the initial geometry is used.
Important: only the bonds present in the system at certain points of the simulation (at the start or right after adding/removing atoms) can be constrained, which means that the bonds may need to be specified in the System block.
Warning: the triangles constraint should be used with care because each constrained bond or angle means removing one degree of freedom from the dynamics. When there are too many constraints (for example, "All triangles H C H" in methane) some of them may be linearly dependent, which will lead to an error in the temperature computation.
Valid examples:
All single bonds C C to 1.4
All bonds O H to 0.98
All bonds O H
All bonds H *
All triangles H * H
:vartype All: str | StringKey
:ivar ConvergeR2: Convergence criterion on the max squared difference, in atomic units.
:vartype ConvergeR2: float | FloatKey
:ivar ConvergeRV: Convergence criterion on the orthogonality of the constraint and the relative atomic velocity, in atomic units.
:vartype ConvergeRV: float | FloatKey
:ivar Iterations: Number of iterations.
:vartype Iterations: int | IntKey
:ivar ShakeInitialCoordinates: Apply constraints before computing the first energy and gradients.
:vartype ShakeInitialCoordinates: BoolType | BoolKey
"""
def __post_init__(self):
self.All: str | StringKey = StringKey(name='All', comment='Constraint description in one the following formats: \nAll [bondOrder] bonds at1 at2 [to distance]\nAll triangles at1 at2 at3\n\nThe first option constrains all bonds between atoms at1 at2 to a certain length, while the second - bonds at1-at2 and at2-at3 and the angle between them.\n\nThe [bondOrder] can be a number or a string such as single, double, triple or aromatic. If it\'s omitted then all bonds between specified atoms will be constrained. Atom names are case-sensitive and they must be as they are in the Atoms block, or an asterisk \'*\' denoting any atom. The distance, if present, must be in Angstrom. If it is omitted then the bond length from the initial geometry is used.\n\nImportant: only the bonds present in the system at certain points of the simulation (at the start or right after adding/removing atoms) can be constrained, which means that the bonds may need to be specified in the System block.\n\nWarning: the triangles constraint should be used with care because each constrained bond or angle means removing one degree of freedom from the dynamics. When there are too many constraints (for example, "All triangles H C H" in methane) some of them may be linearly dependent, which will lead to an error in the temperature computation. \n\nValid examples:\nAll single bonds C C to 1.4\nAll bonds O H to 0.98\nAll bonds O H\nAll bonds H *\nAll triangles H * H', unique=False, gui_name='Constrain all:')
self.ConvergeR2: float | FloatKey = FloatKey(name='ConvergeR2', comment='Convergence criterion on the max squared difference, in atomic units.', default=1e-08)
self.ConvergeRV: float | FloatKey = FloatKey(name='ConvergeRV', comment='Convergence criterion on the orthogonality of the constraint and the relative atomic velocity, in atomic units.', default=1e-08)
self.Iterations: int | IntKey = IntKey(name='Iterations', comment='Number of iterations.', default=100)
self.ShakeInitialCoordinates: BoolType | BoolKey = BoolKey(name='ShakeInitialCoordinates', comment='Apply constraints before computing the first energy and gradients.', default=True)
[docs] class _Thermostat(FixedBlock):
r"""
This block allows to specify the use of a thermostat during the simulation. Depending on the selected thermostat type, different additional options may be needed to characterize the specific thermostat's behavior.
:ivar BerendsenApply: Select how to apply the scaling correction for the Berendsen thermostat:
- per-atom-velocity (Local)
- on the molecular system as a whole (Global).
:vartype BerendsenApply: Literal["Local", "Global"]
:ivar ChainLength: Number of individual thermostats forming the NHC thermostat
:vartype ChainLength: int | IntKey
:ivar Duration: Specifies how many steps should a transition from a particular temperature to the next one in sequence take.
:vartype Duration: Iterable[int] | IntListKey
:ivar ExcludedDirection: Exclude a component of the velocities from rescaling by the thermostat. For example in NEMD simulations, when a shear force/velocity is applied in the x direction, the x-direction is often excluded from thermostatting. This currently only works for the Nose-Hoover thermostat.
:vartype ExcludedDirection: Literal["None", "X", "Y", "Z"]
:ivar Friction: Friction coefficient used in langevin dynamics
:vartype Friction: float | FloatKey
:ivar Region: The identifier of the region to thermostat. The default `*` applies the thermostat to the entire system. The value can by a plain region name, or a region expression, e.g. `*-myregion` to thermostat all atoms that are not in myregion, or `regionA+regionB` to thermostat the union of the 'regionA' and 'regionB'. Note that if multiple thermostats are used, their regions may not overlap.
:vartype Region: str | StringKey
:ivar ScaleFrequency: Optional parameter used only by the Scale thermostat.
If specified, the thermostat will be applied every N steps, using that step's ensemble temperature and the specified thermostat temperature to compute the scaling factor.
If not specified, the thermostat will be applied at every step, using the mean temperature of the ensemble and the specified thermostat temperature to compute the scaling factor.
:vartype ScaleFrequency: int | IntKey
:ivar Tau: The time constant of the thermostat.
:vartype Tau: float | FloatKey
:ivar Temperature: The target temperature of the thermostat.
You can specify multiple temperatures (separated by spaces). In that case the Duration field specifies how many steps to use for the transition from one T to the next T (using a linear ramp). For NHC thermostat, the temperature may not be zero.
:vartype Temperature: Iterable[float] | FloatListKey
:ivar Type: Selects the type of the thermostat.
:vartype Type: Literal["None", "Scale", "Berendsen", "NHC", "Langevin"]
"""
def __post_init__(self):
self.BerendsenApply: Literal["Local", "Global"] = MultipleChoiceKey(name='BerendsenApply', comment='Select how to apply the scaling correction for the Berendsen thermostat:\n\n- per-atom-velocity (Local)\n- on the molecular system as a whole (Global).', gui_name='Apply Berendsen:', default='Global', choices=['Local', 'Global'])
self.ChainLength: int | IntKey = IntKey(name='ChainLength', comment='Number of individual thermostats forming the NHC thermostat', gui_name='NHC chain length:', default=10)
self.Duration: Iterable[int] | IntListKey = IntListKey(name='Duration', comment='Specifies how many steps should a transition from a particular temperature to the next one in sequence take.', gui_name='Duration(s)')
self.ExcludedDirection: Literal["None", "X", "Y", "Z"] = MultipleChoiceKey(name='ExcludedDirection', comment='Exclude a component of the velocities from rescaling by the thermostat. For example in NEMD simulations, when a shear force/velocity is applied in the x direction, the x-direction is often excluded from thermostatting. This currently only works for the Nose-Hoover thermostat.', hidden=True, default='None', choices=['None', 'X', 'Y', 'Z'])
self.Friction: float | FloatKey = FloatKey(name='Friction', comment='Friction coefficient used in langevin dynamics', hidden=True, default=1.0)
self.Region: str | StringKey = StringKey(name='Region', comment="The identifier of the region to thermostat. The default `*` applies the thermostat to the entire system. The value can by a plain region name, or a region expression, e.g. `*-myregion` to thermostat all atoms that are not in myregion, or `regionA+regionB` to thermostat the union of the 'regionA' and 'regionB'. Note that if multiple thermostats are used, their regions may not overlap.", default='*', gui_type='region')
self.ScaleFrequency: int | IntKey = IntKey(name='ScaleFrequency', comment="Optional parameter used only by the Scale thermostat.\n\nIf specified, the thermostat will be applied every N steps, using that step's ensemble temperature and the specified thermostat temperature to compute the scaling factor.\n\nIf not specified, the thermostat will be applied at every step, using the mean temperature of the ensemble and the specified thermostat temperature to compute the scaling factor.", hidden=True)
self.Tau: float | FloatKey = FloatKey(name='Tau', comment='The time constant of the thermostat.', gui_name='Damping constant:', unit='Femtoseconds')
self.Temperature: Iterable[float] | FloatListKey = FloatListKey(name='Temperature', comment='The target temperature of the thermostat.\n\nYou can specify multiple temperatures (separated by spaces). In that case the Duration field specifies how many steps to use for the transition from one T to the next T (using a linear ramp). For NHC thermostat, the temperature may not be zero.', gui_name='Temperature(s)', unit='Kelvin')
self.Type: Literal["None", "Scale", "Berendsen", "NHC", "Langevin"] = MultipleChoiceKey(name='Type', comment='Selects the type of the thermostat.', gui_name='Thermostat:', default='None', choices=['None', 'Scale', 'Berendsen', 'NHC', 'Langevin'], hiddenchoices=['Scale', 'Langevin'])
[docs] class _Trajectory(FixedBlock):
r"""
Sets the frequency for printing to stdout and storing the molecular configuration on the .rkf file.
:ivar EngineResultsFreq: Write MDStep*.rkf files with engine-specific results once every N steps. Setting this to zero disables writing engine results files except for one file at the end of the simulation. If unset or negative, defaults to the value of Checkpoint%Frequency.
:vartype EngineResultsFreq: int | IntKey
:ivar ExitConditionFreq: Check the exit conditions every N steps. By default this is done every SamplingFreq steps.
:vartype ExitConditionFreq: int | IntKey
:ivar PrintFreq: Print current thermodynamic properties to the output every N steps. By default this is done every SamplingFreq steps.
:vartype PrintFreq: int | IntKey
:ivar SamplingFreq: Write the molecular geometry (and possibly other properties) to the ams.rkf file once every N steps.
:vartype SamplingFreq: int | IntKey
:ivar TProfileGridPoints: Number of points in the temperature profile. If TProfileGridPoints > 0, a temperature profile along each of the three lattice axes will be written to the .rkf file. The temperature at a given profile point is calculated as the total temperature of all atoms inside the corresponding slice of the simulation box, time-averaged over all MD steps since the previous snapshot. By default, no profile is generated.
:vartype TProfileGridPoints: int | IntKey
:ivar WriteBonds: Write detected bonds to the .rkf file.
:vartype WriteBonds: BoolType | BoolKey
:ivar WriteCharges: Write current atomic point charges (if available) to the .rkf file. Disable this to reduce trajectory size if you do not need to analyze charges.
:vartype WriteCharges: BoolType | BoolKey
:ivar WriteCoordinates: Write atomic coordinates to the .rkf file.
:vartype WriteCoordinates: BoolType | BoolKey
:ivar WriteEngineGradients: Write atomic gradients (negative of the atomic forces, as calculated by the engine) to the History section of ams.rkf.
:vartype WriteEngineGradients: BoolType | BoolKey
:ivar WriteMolecules: Write the results of molecule analysis to the .rkf file.
:vartype WriteMolecules: BoolType | BoolKey
:ivar WriteVelocities: Write velocities to the .rkf file. Disable this to reduce trajectory size if you do not need to analyze the velocities.
:vartype WriteVelocities: BoolType | BoolKey
"""
def __post_init__(self):
self.EngineResultsFreq: int | IntKey = IntKey(name='EngineResultsFreq', comment='Write MDStep*.rkf files with engine-specific results once every N steps. Setting this to zero disables writing engine results files except for one file at the end of the simulation. If unset or negative, defaults to the value of Checkpoint%Frequency.', gui_name='Engine results frequency:')
self.ExitConditionFreq: int | IntKey = IntKey(name='ExitConditionFreq', comment='Check the exit conditions every N steps. By default this is done every SamplingFreq steps.', gui_name='Exit condition frequency:')
self.PrintFreq: int | IntKey = IntKey(name='PrintFreq', comment='Print current thermodynamic properties to the output every N steps. By default this is done every SamplingFreq steps.', gui_name='Printing frequency:')
self.SamplingFreq: int | IntKey = IntKey(name='SamplingFreq', comment='Write the molecular geometry (and possibly other properties) to the ams.rkf file once every N steps.', gui_name='Sample frequency:', default=100)
self.TProfileGridPoints: int | IntKey = IntKey(name='TProfileGridPoints', comment='Number of points in the temperature profile. If TProfileGridPoints > 0, a temperature profile along each of the three lattice axes will be written to the .rkf file. The temperature at a given profile point is calculated as the total temperature of all atoms inside the corresponding slice of the simulation box, time-averaged over all MD steps since the previous snapshot.\u200b By default, no profile is generated.', default=0)
self.WriteBonds: BoolType | BoolKey = BoolKey(name='WriteBonds', comment='Write detected bonds to the .rkf file.', default=True)
self.WriteCharges: BoolType | BoolKey = BoolKey(name='WriteCharges', comment='Write current atomic point charges (if available) to the .rkf file. Disable this to reduce trajectory size if you do not need to analyze charges.', default=True)
self.WriteCoordinates: BoolType | BoolKey = BoolKey(name='WriteCoordinates', comment='Write atomic coordinates to the .rkf file.', default=True)
self.WriteEngineGradients: BoolType | BoolKey = BoolKey(name='WriteEngineGradients', comment='Write atomic gradients (negative of the atomic forces, as calculated by the engine) to the History section of ams.rkf.', default=False)
self.WriteMolecules: BoolType | BoolKey = BoolKey(name='WriteMolecules', comment='Write the results of molecule analysis to the .rkf file.', default=True)
self.WriteVelocities: BoolType | BoolKey = BoolKey(name='WriteVelocities', comment='Write velocities to the .rkf file. Disable this to reduce trajectory size if you do not need to analyze the velocities.', default=True)
def __post_init__(self):
self.NSteps: int | IntKey = IntKey(name='NSteps', comment='The number of steps to be taken in the MD simulation.', gui_name='Number of steps:', default=1000)
self.Restart: str | Path | StringKey = PathStringKey(name='Restart', comment='The path to the ams.rkf file from which to restart the simulation.', gui_name='Restart from:', ispath=True, gui_type='.rkf {{{AMS result file} .rkf}}')
self.TimeStep: float | FloatKey = FloatKey(name='TimeStep', comment='The time difference per step.', default=0.25, unit='Femtoseconds')
self.Checkpoint: Conformers._Generator._METADYNAMICS._MolecularDynamics._Checkpoint = self._Checkpoint(name='Checkpoint', comment='Sets the frequency for storing the entire MD state necessary for restarting the calculation.')
self.InitialVelocities: Conformers._Generator._METADYNAMICS._MolecularDynamics._InitialVelocities = self._InitialVelocities(name='InitialVelocities', comment='Sets the frequency for printing to stdout and storing the molecular configuration on the .rkf file.')
self.Preserve: Conformers._Generator._METADYNAMICS._MolecularDynamics._Preserve = self._Preserve(name='Preserve', comment='Periodically remove numerical drift accumulated during the simulation to preserve different whole-system parameters.')
self.Print: Conformers._Generator._METADYNAMICS._MolecularDynamics._Print = self._Print(name='Print', comment='This block controls the printing of additional information to stdout.')
self.Shake: Conformers._Generator._METADYNAMICS._MolecularDynamics._Shake = self._Shake(name='Shake', comment='Parameters of the Shake/Rattle algorithm.')
self.Thermostat: Conformers._Generator._METADYNAMICS._MolecularDynamics._Thermostat = self._Thermostat(name='Thermostat', comment="This block allows to specify the use of a thermostat during the simulation. Depending on the selected thermostat type, different additional options may be needed to characterize the specific thermostat's behavior.", unique=False)
self.Trajectory: Conformers._Generator._METADYNAMICS._MolecularDynamics._Trajectory = self._Trajectory(name='Trajectory', comment='Sets the frequency for printing to stdout and storing the molecular configuration on the .rkf file.')
def __post_init__(self):
self.Blocksize: int | IntKey = IntKey(name='Blocksize', comment='The interval between the trajectory snapshots written to file that are extracted and optimized. By default all written snapshots are extracted.', hidden=True, default=1)
self.ConvergenceQualityCrude: Literal["normal", "good", "verygood", "excellent", "none"] = MultipleChoiceKey(name='ConvergenceQualityCrude', comment='The tightness of the convergence of the crude geometry pre-optimizations. If set to none it will be selected two levels below ConvergenceQuality.', default='none', choices=['normal', 'good', 'verygood', 'excellent', 'none'])
self.MaxHeight: float | FloatKey = FloatKey(name='MaxHeight', comment='The maximum Gaussian height used in a metadynamics simulation.', hidden=True, default=0.003)
self.MaxWidth: float | FloatKey = FloatKey(name='MaxWidth', comment='The maximum Gaussian width used in a metadynamics simulation.', hidden=True, default=1.3)
self.MinHeight: float | FloatKey = FloatKey(name='MinHeight', comment='The minimum Gaussian height used in a metadynamics simulation.', hidden=True, default=0.00075)
self.NCycles: int | IntKey = IntKey(name='NCycles', comment='The maximum number of cycles of metadynamics simulations. The generator stops when either this number is reached, or the conformer set is stable.', default=5)
self.NWidthsHeights: Iterable[int] | IntListKey = IntListKey(name='NWidthsHeights', comment='The number of different Gaussian widths and heights respectively used in the metadynamics simulations. By default 4 different widths are used and 3 different heights, resulting in 12 different metadynamics simulations.', default=[4, 3])
self.Restartdir: str | StringKey = StringKey(name='Restartdir', comment='A PLAMS folder containing the results from a previous conformers generation using the METADYNAMICS generator.', hidden=True)
self.SimulationSuccessFraction: float | FloatKey = FloatKey(name='SimulationSuccessFraction', comment='The fraction of planned metadynamics steps that has to have succeeded in order for the metadynamics iteration to be considered a success.', default=0.4)
self.UseShake: BoolType | BoolKey = BoolKey(name='UseShake', comment='Constrain all -H bonds with shake. If turned on, the MD timestep is automatically increased.', default=False)
self.UseXtb: BoolType | BoolKey = BoolKey(name='UseXtb', comment='Use Grimmes xTB code to perform the MD simulations instead of AMS', hidden=True, default=False)
self.WidthIncrement: float | FloatKey = FloatKey(name='WidthIncrement', comment='The increment between Gaussian widths used in subsequent metadynamics simulations.', hidden=True, default=1.6666666666666667)
self.AdditionalGaussians: Conformers._Generator._METADYNAMICS._AdditionalGaussians = self._AdditionalGaussians(name='AdditionalGaussians', comment='An additional set of Gaussian widths and heights, each representing the Gaussians of a single additional metadynamics simulation. By default, if nothing is provided, then two Gaussians are used: ([(width:0.1 Angstrom, height:0.001 Hartree), (width:0.8 Angstrom, height:0.005 Hartree)])', hidden=True, unique=False)
self.MolecularDynamics: Conformers._Generator._METADYNAMICS._MolecularDynamics = self._MolecularDynamics(name='MolecularDynamics', comment='Configures molecular dynamics (with the velocity-Verlet algorithm) with and without thermostats. This block allows to specify the details of the molecular dynamics calculation. Default values will be ignored.')
[docs] class _Preoptimization(FixedBlock):
r"""
If this block is enabled geometries will be preoptimized. After preoptimization the high energy conformers will be discarded, and then from the remaining set the unoptimized geometries will be optimized at higher level. This is to prevent the preoptimizer from collapsing different conformers into a single false minimum. As a result, preoptimization is only useful if MaxEnergy is chosen low.
:ivar Enable: Perform preoptimization at a low level of accuracy.
:vartype Enable: BoolType | BoolKey
:ivar PreoptFactor: This factor is multiplied with MaxEnergy, to determine which high energy conformers can be discarded after preoptimization.
:vartype PreoptFactor: int | IntKey
:ivar Engine: The engine specifics to be used for preoptimization.
:vartype Engine: EngineBlock
"""
[docs] class _Engine(EngineBlock):
r"""
The engine specifics to be used for preoptimization.
"""
def __post_init__(self):
pass
def __post_init__(self):
self.Enable: BoolType | BoolKey = BoolKey(name='Enable', comment='Perform preoptimization at a low level of accuracy.', default=False)
self.PreoptFactor: int | IntKey = IntKey(name='PreoptFactor', comment='This factor is multiplied with MaxEnergy, to determine which high energy conformers can be discarded after preoptimization.', default=2)
self.Engine: EngineBlock = self._Engine(name='Engine', comment='The engine specifics to be used for preoptimization.')
[docs] class _RDKit(FixedBlock):
r"""
Options for the RDKit generator. This generator produces initial guesses for conformers using the RDKit ETKDG method, followed by AMS geometry optimizations.
:ivar InitialNConformers: Number of geometries initially created by RDKit, before AMS geometry optimization and filtering. If not set, the number will be automatically set, based on the number of rotational bonds.
:vartype InitialNConformers: int | IntKey
:ivar MaxConfs: If InitialNConformers is not set, then the number of conformers will be automatically set, with a maximum of MaxConfs.
:vartype MaxConfs: int | IntKey
:ivar MinConfs: If InitialNConformers is not set, then the number of conformers will be automatically set, with a minimum of MinConfs.
:vartype MinConfs: int | IntKey
:ivar NconfsEstimationFactor: If InitialNConformers is not set, then the number of conformers will be automatically set based on the number of rotational bonds. The resulting number is then multiplied by this factor (default: 100), to ensure that enough conformers will be created.
:vartype NconfsEstimationFactor: int | IntKey
:ivar Restartdir: A PLAMS folder containing the results from a previous conformers generation using this same generator. Currently only used to reread the initial conformers created by RDKit.
:vartype Restartdir: str | StringKey
:ivar Restartfilename: The name of the file containing geometries generated by RDKits ETKDG algorithm, in the Restartdir folder.
:vartype Restartfilename: str | StringKey
"""
def __post_init__(self):
self.InitialNConformers: int | IntKey = IntKey(name='InitialNConformers', comment='Number of geometries initially created by RDKit, before AMS geometry optimization and filtering. If not set, the number will be automatically set, based on the number of rotational bonds.', gui_name='Initial no. of conformers')
self.MaxConfs: int | IntKey = IntKey(name='MaxConfs', comment='If InitialNConformers is not set, then the number of conformers will be automatically set, with a maximum of MaxConfs.', default=5000)
self.MinConfs: int | IntKey = IntKey(name='MinConfs', comment='If InitialNConformers is not set, then the number of conformers will be automatically set, with a minimum of MinConfs.', default=10)
self.NconfsEstimationFactor: int | IntKey = IntKey(name='NconfsEstimationFactor', comment='If InitialNConformers is not set, then the number of conformers will be automatically set based on the number of rotational bonds. The resulting number is then multiplied by this factor (default: 100), to ensure that enough conformers will be created.', default=100)
self.Restartdir: str | StringKey = StringKey(name='Restartdir', comment='A PLAMS folder containing the results from a previous conformers generation using this same generator. Currently only used to reread the initial conformers created by RDKit.', hidden=True)
self.Restartfilename: str | StringKey = StringKey(name='Restartfilename', comment='The name of the file containing geometries generated by RDKits ETKDG algorithm, in the Restartdir folder.', hidden=True, default='unoptimized.dcd')
[docs] class _RDKitETKDG(FixedBlock):
r"""
Settings for the call to RDKits ETKDG conformer generator tool.
:ivar BestRMSDThreshold: After ETKDG conformer generation by RDKit, RDKit can be used to remove duplicates via the BestRMS algorithm. This filter does exactly the same as the RMSD equivalence detector in the Equivalence block.
:vartype BestRMSDThreshold: float | FloatKey
:ivar ConstrainedAtoms: The indices of the atoms to constrain during ETKDG conformer generation.
:vartype ConstrainedAtoms: Iterable[int] | IntListKey
:ivar Forcefield: The name of the RDKit forcefield to use for geometry optimization at the end of ETKDG conformer generation (by default no geometry optimization is performed). Using the RDKit internal optimization may make the subsequent geometry optimizations with AMS faster.
:vartype Forcefield: Literal["None", "UFF", "MMFF"]
:ivar Parallel: Experimental: Parallelize the RDKit generation step by calling the RDKit conformer generation method in parallel from multiple processes.
:vartype Parallel: BoolType | BoolKey
:ivar RMSDThreshold: Root Mean Square deviation threshold for removing similar/equivalent conformations during the RDKit ETKDG procedure. By default there is no pruning (value: -1).
:vartype RMSDThreshold: float | FloatKey
:ivar UseExpTorsionAnglePrefs: Impose experimental torsion angle preferences in RDKit ETKDG conformer generation. By default the RDKit version determines whether or not to switch this on.
:vartype UseExpTorsionAnglePrefs: str | StringKey
"""
def __post_init__(self):
self.BestRMSDThreshold: float | FloatKey = FloatKey(name='BestRMSDThreshold', comment='After ETKDG conformer generation by RDKit, RDKit can be used to remove duplicates via the BestRMS algorithm. This filter does exactly the same as the RMSD equivalence detector in the Equivalence block.', default=-1.0)
self.ConstrainedAtoms: Iterable[int] | IntListKey = IntListKey(name='ConstrainedAtoms', comment='The indices of the atoms to constrain during ETKDG conformer generation.')
self.Forcefield: Literal["None", "UFF", "MMFF"] = MultipleChoiceKey(name='Forcefield', comment='The name of the RDKit forcefield to use for geometry optimization at the end of ETKDG conformer generation (by default no geometry optimization is performed). Using the RDKit internal optimization may make the subsequent geometry optimizations with AMS faster.', default='None', choices=['None', 'UFF', 'MMFF'])
self.Parallel: BoolType | BoolKey = BoolKey(name='Parallel', comment='Experimental: Parallelize the RDKit generation step by calling the RDKit conformer generation method in parallel from multiple processes.', default=False)
self.RMSDThreshold: float | FloatKey = FloatKey(name='RMSDThreshold', comment='Root Mean Square deviation threshold for removing similar/equivalent conformations during the RDKit ETKDG procedure. By default there is no pruning (value: -1).', default=-1.0)
self.UseExpTorsionAnglePrefs: str | StringKey = StringKey(name='UseExpTorsionAnglePrefs', comment='Impose experimental torsion angle preferences in RDKit ETKDG conformer generation. By default the RDKit version determines whether or not to switch this on.', default='default')
[docs] class _TORSION(FixedBlock):
r"""
Options for the TorsionGenerator, which generates geometries by enumerative rotation around rotatable bonds. This is the slowest of all generator, and quickly becomes infeasible for large systems. Currently does not work for systems with interconnected rings.
:ivar BondDistortionThreshold: A factor multiplied by the original bondlength, used to check if a geometry is not too distorted. A new geometry is discarded if any of the bonds have become longer than this value times the original bond length.
:vartype BondDistortionThreshold: float | FloatKey
:ivar Dtheta: The angle over which the bonds are rotated, in order to create a new conformer.
:vartype Dtheta: float | FloatKey
:ivar TruncateRingtorsions: In producing conformers for rings, one can rotate over all the bonds in the ring, or one can save time by excluding the last three bonds in the ring, which share atoms with the first bonds in the ring. This should yield identical results, and by default this is done.
:vartype TruncateRingtorsions: BoolType | BoolKey
"""
def __post_init__(self):
self.BondDistortionThreshold: float | FloatKey = FloatKey(name='BondDistortionThreshold', comment='A factor multiplied by the original bondlength, used to check if a geometry is not too distorted. A new geometry is discarded if any of the bonds have become longer than this value times the original bond length.', hidden=True, default=2.0)
self.Dtheta: float | FloatKey = FloatKey(name='Dtheta', comment='The angle over which the bonds are rotated, in order to create a new conformer.', default=60.0)
self.TruncateRingtorsions: BoolType | BoolKey = BoolKey(name='TruncateRingtorsions', comment='In producing conformers for rings, one can rotate over all the bonds in the ring, or one can save time by excluding the last three bonds in the ring, which share atoms with the first bonds in the ring. This should yield identical results, and by default this is done.', hidden=True, default=True)
def __post_init__(self):
self.AdjustInputBonds: BoolType | BoolKey = BoolKey(name='AdjustInputBonds', comment='If geometry optimization of the initial conformer results in bond changes, adjust the reference connectivity. If the changes are too severe, the calculation will stop.', default=True)
self.MaxEnergy: float | FloatKey = FloatKey(name='MaxEnergy', comment='Threshold for filtering out high-energy conformers. If the relative energy of a conformer with respect to the lowest conformer is larger than this value, the conformer will be discarded.', unit='kcal/mol')
self.Method: Literal["RDKit", "CREST", "METADYNAMICS", "ANNEALING", "TORSION"] = MultipleChoiceKey(name='Method', comment='Method used to generate the conformers.\n\nThe RDKit generator is based on random distance matrix method. This is the recommended (and default) method.\n\nThe CREST Generator uses a multi-step workflow with meta-dynamics simulations to explore the conformers space of a molecule. This can be a powerful conformer search method, but it is generally computationally expensive compared to the RDKit generator.\n\nThe ANNEALING generator performs a simulated annealing simulation to explore conformer space.', gui_name='Generator method:', default='RDKit', choices=['RDKit', 'CREST', 'METADYNAMICS', 'ANNEALING', 'TORSION'], hiddenchoices=['METADYNAMICS', 'TORSION'])
self.RNGSeed: int | IntKey = IntKey(name='RNGSeed', comment='Initial guesses for conformers can be randomly generated by RDKit, using the ETKDG algorithm. For reproducibility, a random number seed can be provided here.')
self.Verbose: BoolType | BoolKey = BoolKey(name='Verbose', comment='If set to True, print additional info about conformer equivalence to standard output.', hidden=True, default=False)
self.ANNEALING: Conformers._Generator._ANNEALING = self._ANNEALING(name='ANNEALING', comment='Options for the annealing generator. This generator creates conformers by performing a simulated annealing simulation.')
self.CREST: Conformers._Generator._CREST = self._CREST(name='CREST', comment='Options for the CREST generator. The CREST generator performs a set of metadynamics simulations (using the METADYNAMICS generator), then a set of MD simulations (using the MD expander), and finally it does a combinatorial expansion of the generated conformers using the GC expander. This sequence is repeated in an iterative fashion until the lowest energy conformer no longer changes.')
self.METADYNAMICS: Conformers._Generator._METADYNAMICS = self._METADYNAMICS(name='METADYNAMICS', comment='Produces conformers by running a set of CREST-RMSD metadynamics simulations with different biases, extracting snapshots, and optimizing those.')
self.Preoptimization: Conformers._Generator._Preoptimization = self._Preoptimization(name='Preoptimization', comment='If this block is enabled geometries will be preoptimized. After preoptimization the high energy conformers will be discarded, and then from the remaining set the unoptimized geometries will be optimized at higher level. This is to prevent the preoptimizer from collapsing different conformers into a single false minimum. As a result, preoptimization is only useful if MaxEnergy is chosen low.')
self.RDKit: Conformers._Generator._RDKit = self._RDKit(name='RDKit', comment='Options for the RDKit generator. This generator produces initial guesses for conformers using the RDKit ETKDG method, followed by AMS geometry optimizations.')
self.RDKitETKDG: Conformers._Generator._RDKitETKDG = self._RDKitETKDG(name='RDKitETKDG', comment='Settings for the call to RDKits ETKDG conformer generator tool.')
self.TORSION: Conformers._Generator._TORSION = self._TORSION(name='TORSION', comment='Options for the TorsionGenerator, which generates geometries by enumerative rotation around rotatable bonds. This is the slowest of all generator, and quickly becomes infeasible for large systems. Currently does not work for systems with interconnected rings.')
[docs] class _GeometryOptimization(FixedBlock):
r"""
Some options / details regarding the optimization procedure.
:ivar ConvergenceQuality: The tightness of the convergence of the geometry optimizations. Lower quality levels may lead to badly converged geometries being classified as distinct conformers.
:vartype ConvergenceQuality: Literal["Normal", "Good", "VeryGood", "Excellent"]
:ivar Keep: Keep all the output files of the geometry optimizations. If set to 'all', must be used in combination with Output%KeepWorkDir.
:vartype Keep: Literal["None", "all"]
:ivar MaxConvergenceTime: The number of iterations for the geometry optimization, based on the number of atoms in the system. The default value is the general AMS value for geometry optimization. Often, for conformer generation, it needs to be set higher.
:vartype MaxConvergenceTime: Literal["Default", "High"]
:ivar MaxOptimizations: Set a maximum to the number of geometries accepted for optimization at once, per AMSWorker (so should be multiplied by the number of cores used). If not set, the disc size requirements can become too large.
:vartype MaxOptimizations: int | IntKey
:ivar OptimizationMethod: Select the optimization algorithm employed for the geometry relaxation. Currently supported are:
the Hessian-based Quasi-Newton-type BFGS algorithm,
the fast inertial relaxation method (FIRE),
the limited-memory BFGS method,
and the conjugate gradients method. The default is Quasi-Newton, which gives the most reliable results for conformers. The Auto method leaves it to the AMS GeometryOptimization task to select a method.
:vartype OptimizationMethod: Literal["Auto", "Quasi-Newton", "FIRE", "L-BFGS", "ConjugateGradients", "Dimer"]
:ivar UseAMSWorker: Whether the set of optimizations should be run via the AMSWorkerPool or via regular AMSJobs.
:vartype UseAMSWorker: BoolType | BoolKey
:ivar GeometryOptimization: Configures details of the geometry optimization and transition state searches.
:vartype GeometryOptimization: Conformers._GeometryOptimization._GeometryOptimization
:ivar WriteGeometries: Determines if and where optimized geometries will be written to file during optimization. When the AMSWorker is used, then the write interval depends on MaxOptimizations. If enabled, must be used in combination with Output%KeepWorkDir.
:vartype WriteGeometries: Conformers._GeometryOptimization._WriteGeometries
"""
[docs] class _GeometryOptimization(FixedBlock):
r"""
Configures details of the geometry optimization and transition state searches.
:ivar CalcPropertiesOnlyIfConverged: Compute the properties requested in the 'Properties' block, e.g. Frequencies or Phonons, only if the optimization (or transition state search) converged. If False, the properties will be computed even if the optimization did not converge.
:vartype CalcPropertiesOnlyIfConverged: BoolType | BoolKey
:ivar CoordinateType: Select the type of coordinates in which to perform the optimization. 'Auto' automatically selects the most appropriate CoordinateType for a given Method.
If 'Auto' is selected, Delocalized coordinates will be used for the Quasi-Newton method, while Cartesian coordinates will be used for all other methods.
:vartype CoordinateType: Literal["Auto", "Delocalized", "Cartesian"]
:ivar KeepIntermediateResults: Whether the full engine result files of all intermediate steps are stored on disk. By default only the last step is kept, and only if the geometry optimization converged. This can easily lead to huge amounts of data being stored on disk, but it can sometimes be convenient to closely monitor a tricky optimization, e.g. excited state optimizations going through conical intersections, etc. ...
:vartype KeepIntermediateResults: BoolType | BoolKey
:ivar MaxIterations: The maximum number of geometry iterations allowed to converge to the desired structure.
:vartype MaxIterations: int | IntKey
:ivar MaxRestarts: If a geometry optimization of a system with no symmetry operators (or with explicitly disabled symmetry: ``UseSymmetry False``) and enabled PES point characterization converges to a transition state (or higher order saddle point), it can be restarted automatically after a small displacement along the imaginary vibrational mode. In case the restarted optimization again does not find a minimum, this can happen multiple times in succession. This keyword sets the maximum number of restarts. The default value is 0, so the automatic restarting is disabled by default.
:vartype MaxRestarts: int | IntKey
:ivar Method: Select the optimization algorithm employed for the geometry relaxation. Currently supported are:
the Hessian-based Quasi-Newton-type BFGS algorithm,
the fast inertial relaxation method (FIRE),
the limited-memory BFGS method,
and the conjugate gradients method. The default is to choose an appropriate method automatically based on the engine's speed, the system size and the supported optimization options.
:vartype Method: Literal["Auto", "Quasi-Newton", "FIRE", "L-BFGS", "ConjugateGradients", "Dimer"]
:ivar OptimizeLattice: Whether to also optimize the lattice for periodic structures. This is currently supported with the Quasi-Newton, FIRE, and L-BFGS optimizers.
:vartype OptimizeLattice: BoolType | BoolKey
:ivar PretendConverged: Normally a non-converged geometry optimization is considered an error. If this keyword is set to True, the optimizer will only produce a warning and still claim that the optimization is converged. (This is mostly useful for scripting applications, where one might want to consider non-converged optimizations still successful jobs.)
:vartype PretendConverged: BoolType | BoolKey
:ivar RestartDisplacement: If a geometry optimization of a system with no symmetry operators (or with explicitly disabled symmetry: ``UseSymmetry False``) and enabled PES point characterization converges to a transition state (or higher order saddle point), it can be restarted automatically after a small displacement along the imaginary vibrational mode. This keywords sets the size of the displacement for the furthest moving atom.
:vartype RestartDisplacement: float | FloatKey
:ivar Convergence: Convergence is monitored for up to 4 quantities: the energy change, the Cartesian gradients, the Cartesian step size, and for lattice optimizations the stress energy per atom. Convergence criteria can be specified separately for each of these items.
:vartype Convergence: Conformers._GeometryOptimization._GeometryOptimization._Convergence
:ivar Dimer: Options for the Dimer method for transition state search.
:vartype Dimer: Conformers._GeometryOptimization._GeometryOptimization._Dimer
:ivar EngineAutomations: The optimizer can change some settings of the engine, based for instance on the error.
The idea is to allow the engine to be a bit quicker at the start, and more accurate towards the end.
Automations are always engine specific.
:vartype EngineAutomations: Conformers._GeometryOptimization._GeometryOptimization._EngineAutomations
:ivar FIRE: This block configures the details of the FIRE optimizer. The keywords name correspond the the symbols used in the article describing the method, see PRL 97, 170201 (2006).
:vartype FIRE: Conformers._GeometryOptimization._GeometryOptimization._FIRE
:ivar HessianFree: Configures details of the Hessian-free (conjugate gradients or L-BFGS) geometry optimizer.
:vartype HessianFree: Conformers._GeometryOptimization._GeometryOptimization._HessianFree
:ivar InitialHessian: Options for initial model Hessian when optimizing systems with the Quasi-Newton method.
:vartype InitialHessian: Conformers._GeometryOptimization._GeometryOptimization._InitialHessian
:ivar Quasi-Newton: Configures details of the Quasi-Newton geometry optimizer.
:vartype Quasi-Newton: Conformers._GeometryOptimization._GeometryOptimization._Quasi-Newton
"""
[docs] class _Convergence(FixedBlock):
r"""
Convergence is monitored for up to 4 quantities: the energy change, the Cartesian gradients, the Cartesian step size, and for lattice optimizations the stress energy per atom. Convergence criteria can be specified separately for each of these items.
:ivar Energy: The criterion for changes in the energy. The energy is considered converged when the change in energy is smaller than this threshold times the number of atoms.
:vartype Energy: float | FloatKey
:ivar Gradients: Threshold for nuclear gradients.
:vartype Gradients: float | FloatKey
:ivar Quality: A quick way to change convergence thresholds: 'Good' will reduce all thresholds by an order of magnitude from their default value. 'VeryGood' will tighten them by two orders of magnitude. 'Basic' and 'VeryBasic' will increase the thresholds by one or two orders of magnitude respectively.
:vartype Quality: Literal["VeryBasic", "Basic", "Normal", "Good", "VeryGood", "Excellent", "Custom"]
:ivar Step: The maximum Cartesian step allowed for a converged geometry.
:vartype Step: float | FloatKey
:ivar StressEnergyPerAtom: Threshold used when optimizing the lattice vectors. The stress is considered 'converged' when the maximum value of stress_tensor * cell_volume / number_of_atoms is smaller than this threshold (for 2D and 1D systems, the cell_volume is replaced by the cell_area and cell_length respectively).
:vartype StressEnergyPerAtom: float | FloatKey
"""
def __post_init__(self):
self.Energy: float | FloatKey = FloatKey(name='Energy', comment='The criterion for changes in the energy. The energy is considered converged when the change in energy is smaller than this threshold times the number of atoms.', gui_name='Energy convergence:', default=1e-05, unit='Hartree', range='value > 0')
self.Gradients: float | FloatKey = FloatKey(name='Gradients', comment='Threshold for nuclear gradients.', gui_name='Gradient convergence:', default=0.001, unit='Hartree/Angstrom', range='value > 0')
self.Quality: Literal["VeryBasic", "Basic", "Normal", "Good", "VeryGood", "Excellent", "Custom"] = MultipleChoiceKey(name='Quality', comment="A quick way to change convergence thresholds: 'Good' will reduce all thresholds by an order of magnitude from their default value. 'VeryGood' will tighten them by two orders of magnitude. 'Basic' and 'VeryBasic' will increase the thresholds by one or two orders of magnitude respectively.", gui_name='Convergence:', default='Custom', choices=['VeryBasic', 'Basic', 'Normal', 'Good', 'VeryGood', 'Excellent', 'Custom'], hiddenchoices=['Excellent'])
self.Step: float | FloatKey = FloatKey(name='Step', comment='The maximum Cartesian step allowed for a converged geometry.', gui_name='Step convergence:', default=0.01, unit='Angstrom', range='value > 0')
self.StressEnergyPerAtom: float | FloatKey = FloatKey(name='StressEnergyPerAtom', comment="Threshold used when optimizing the lattice vectors. The stress is considered 'converged' when the maximum value of stress_tensor * cell_volume / number_of_atoms is smaller than this threshold (for 2D and 1D systems, the cell_volume is replaced by the cell_area and cell_length respectively).", default=0.0005, unit='Hartree', range='value > 0')
[docs] class _Dimer(FixedBlock):
r"""
Options for the Dimer method for transition state search.
:ivar AngleThreshold: The rotation is considered converged when the the rotation angle falls below the specified threshold.
:vartype AngleThreshold: float | FloatKey
:ivar DimerDelta: Euclidian distance between the midpoint and the endpoint.
:vartype DimerDelta: float | FloatKey
:ivar ExtrapolateForces: Set to false to call engine to calculate forces at the extrapolated rotation angle instead of extrapolating them.
:vartype ExtrapolateForces: BoolType | BoolKey
:ivar LBFGSMaxVectors: Max number of vectors for the L-BFGS algorithm to save.
:vartype LBFGSMaxVectors: int | IntKey
:ivar MaxRotationIterations: Maximum number of rotation iterations for a single translation step.
:vartype MaxRotationIterations: int | IntKey
:ivar Region: Include only atoms of the specified region(s) in the rotations, which allows searching for a transition state involving selected atoms only.
:vartype Region: str | StringKey
:ivar RotationTrustRadius: L-BFGS trust radius during rotation iterations.
:vartype RotationTrustRadius: float | FloatKey
:ivar TranslationTrustRadius: L-BFGS trust radius during translation iterations.
:vartype TranslationTrustRadius: float | FloatKey
"""
def __post_init__(self):
self.AngleThreshold: float | FloatKey = FloatKey(name='AngleThreshold', comment='The rotation is considered converged when the the rotation angle falls below the specified threshold.', default=1.0, unit='Degree')
self.DimerDelta: float | FloatKey = FloatKey(name='DimerDelta', comment='Euclidian distance between the midpoint and the endpoint.', default=0.01, unit='Angstrom')
self.ExtrapolateForces: BoolType | BoolKey = BoolKey(name='ExtrapolateForces', comment='Set to false to call engine to calculate forces at the extrapolated rotation angle instead of extrapolating them.', default=True)
self.LBFGSMaxVectors: int | IntKey = IntKey(name='LBFGSMaxVectors', comment='Max number of vectors for the L-BFGS algorithm to save.', default=10)
self.MaxRotationIterations: int | IntKey = IntKey(name='MaxRotationIterations', comment='Maximum number of rotation iterations for a single translation step.', default=10)
self.Region: str | StringKey = StringKey(name='Region', comment='Include only atoms of the specified region(s) in the rotations, which allows searching for a transition state involving selected atoms only.', default='*')
self.RotationTrustRadius: float | FloatKey = FloatKey(name='RotationTrustRadius', comment='L-BFGS trust radius during rotation iterations.', default=0.1, unit='Angstrom')
self.TranslationTrustRadius: float | FloatKey = FloatKey(name='TranslationTrustRadius', comment='L-BFGS trust radius during translation iterations.', default=0.1, unit='Angstrom')
[docs] class _EngineAutomations(FixedBlock):
r"""
The optimizer can change some settings of the engine, based for instance on the error.
The idea is to allow the engine to be a bit quicker at the start, and more accurate towards the end.
Automations are always engine specific.
:ivar Enabled: Whether or not automations are enabled at all.
:vartype Enabled: BoolType | BoolKey
:ivar Gradient: A gradient-based automation.
:vartype Gradient: Conformers._GeometryOptimization._GeometryOptimization._EngineAutomations._Gradient
:ivar Iteration: Geometry step based automation.
:vartype Iteration: Conformers._GeometryOptimization._GeometryOptimization._EngineAutomations._Iteration
"""
[docs] class _Gradient(FixedBlock):
r"""
A gradient-based automation.
:ivar FinalValue: This value will be used whenever the gradient is less than GradientLow
:vartype FinalValue: float | FloatKey
:ivar HighGradient: Defines a large gradient. When the actual gradient is between GradientHigh and GradientLow a linear interpolation scheme is used for kT (on a log scale).
:vartype HighGradient: float | FloatKey
:ivar InitialValue: This value will be used at the first geometry, and whenever the gradient is higher than GradientHigh
:vartype InitialValue: float | FloatKey
:ivar LowGradient: Defines a small gradient, see GradientHigh
:vartype LowGradient: float | FloatKey
:ivar UseLogInterpolation: Whether to use interpolation on a log (y) scale or not
:vartype UseLogInterpolation: BoolType | BoolKey
:ivar Variable: variable to be tweaked for the engine.
:vartype Variable: str | StringKey
"""
def __post_init__(self):
self.FinalValue: float | FloatKey = FloatKey(name='FinalValue', comment='This value will be used whenever the gradient is less than GradientLow')
self.HighGradient: float | FloatKey = FloatKey(name='HighGradient', comment='Defines a large gradient. When the actual gradient is between GradientHigh and GradientLow a linear interpolation scheme is used for kT (on a log scale).', default=1.0, unit='Hartree/Angstrom')
self.InitialValue: float | FloatKey = FloatKey(name='InitialValue', comment='This value will be used at the first geometry, and whenever the gradient is higher than GradientHigh')
self.LowGradient: float | FloatKey = FloatKey(name='LowGradient', comment='Defines a small gradient, see GradientHigh', default=1.0, unit='Hartree/Angstrom')
self.UseLogInterpolation: BoolType | BoolKey = BoolKey(name='UseLogInterpolation', comment='Whether to use interpolation on a log (y) scale or not', default=True)
self.Variable: str | StringKey = StringKey(name='Variable', comment='variable to be tweaked for the engine.', default='')
[docs] class _Iteration(FixedBlock):
r"""
Geometry step based automation.
:ivar FinalValue:
:vartype FinalValue: float | FloatKey
:ivar FirstIteration: When the actual gradient is between the first and last iteration, a linear interpolation is used.
:vartype FirstIteration: int | IntKey
:ivar InitialValue: This value will be used when the iteration number is smaller or equal to FirstIteration
:vartype InitialValue: float | FloatKey
:ivar LastIteration: Where the automation should reach the FinalValue
:vartype LastIteration: int | IntKey
:ivar UseLogInterpolation: Whether to use interpolation on a log (y) scale or not
:vartype UseLogInterpolation: BoolType | BoolKey
:ivar Variable: variable to be tweaked for the engine.
:vartype Variable: str | StringKey
"""
def __post_init__(self):
self.FinalValue: float | FloatKey = FloatKey(name='FinalValue')
self.FirstIteration: int | IntKey = IntKey(name='FirstIteration', comment='When the actual gradient is between the first and last iteration, a linear interpolation is used.', default=1)
self.InitialValue: float | FloatKey = FloatKey(name='InitialValue', comment='This value will be used when the iteration number is smaller or equal to FirstIteration')
self.LastIteration: int | IntKey = IntKey(name='LastIteration', comment='Where the automation should reach the FinalValue', default=10)
self.UseLogInterpolation: BoolType | BoolKey = BoolKey(name='UseLogInterpolation', comment='Whether to use interpolation on a log (y) scale or not', default=True)
self.Variable: str | StringKey = StringKey(name='Variable', comment='variable to be tweaked for the engine.', default='')
def __post_init__(self):
self.Enabled: BoolType | BoolKey = BoolKey(name='Enabled', comment='Whether or not automations are enabled at all.', default=True)
self.Gradient: Conformers._GeometryOptimization._GeometryOptimization._EngineAutomations._Gradient = self._Gradient(name='Gradient', comment='A gradient-based automation.', unique=False)
self.Iteration: Conformers._GeometryOptimization._GeometryOptimization._EngineAutomations._Iteration = self._Iteration(name='Iteration', comment='Geometry step based automation.', unique=False)
[docs] class _FIRE(FixedBlock):
r"""
This block configures the details of the FIRE optimizer. The keywords name correspond the the symbols used in the article describing the method, see PRL 97, 170201 (2006).
:ivar AllowOverallRotation: Whether or not the system is allowed to freely rotate during the optimization. This is relevant when optimizing structures in the presence of external fields.
:vartype AllowOverallRotation: BoolType | BoolKey
:ivar AllowOverallTranslation: Whether or not the system is allowed to translate during the optimization. This is relevant when optimizing structures in the presence of external fields.
:vartype AllowOverallTranslation: BoolType | BoolKey
:ivar MapAtomsToUnitCell: Map the atoms to the central cell at each geometry step.
:vartype MapAtomsToUnitCell: BoolType | BoolKey
:ivar NMin: Number of steps after stopping before increasing the time step again.
:vartype NMin: int | IntKey
:ivar alphaStart: Steering coefficient.
:vartype alphaStart: float | FloatKey
:ivar atomMass: Fictitious atomic mass used for all atoms. There is no reason to change this, as it just corresponds to using a different integration timestep.
:vartype atomMass: float | FloatKey
:ivar dtMax: Maximum time step used for the integration. For ReaxFF and APPLE&P, this value is reduced by 50%.
:vartype dtMax: float | FloatKey
:ivar dtStart: Initial time step for the integration.
:vartype dtStart: float | FloatKey
:ivar fAlpha: Reduction factor for the steering coefficient.
:vartype fAlpha: float | FloatKey
:ivar fDec: Reduction factor for reducing the time step in case of uphill movement.
:vartype fDec: float | FloatKey
:ivar fInc: Growth factor for the integration time step.
:vartype fInc: float | FloatKey
:ivar strainMass: Fictitious relative mass of the lattice degrees of freedom. This controls the stiffness of the lattice degrees of freedom relative to the atomic degrees of freedom, with smaller values resulting in a more aggressive optimization of the lattice.
:vartype strainMass: float | FloatKey
"""
def __post_init__(self):
self.AllowOverallRotation: BoolType | BoolKey = BoolKey(name='AllowOverallRotation', comment='Whether or not the system is allowed to freely rotate during the optimization. This is relevant when optimizing structures in the presence of external fields.', default=True)
self.AllowOverallTranslation: BoolType | BoolKey = BoolKey(name='AllowOverallTranslation', comment='Whether or not the system is allowed to translate during the optimization. This is relevant when optimizing structures in the presence of external fields.', default=False)
self.MapAtomsToUnitCell: BoolType | BoolKey = BoolKey(name='MapAtomsToUnitCell', comment='Map the atoms to the central cell at each geometry step.', default=False)
self.NMin: int | IntKey = IntKey(name='NMin', comment='Number of steps after stopping before increasing the time step again.', default=5)
self.alphaStart: float | FloatKey = FloatKey(name='alphaStart', comment='Steering coefficient.', default=0.1)
self.atomMass: float | FloatKey = FloatKey(name='atomMass', comment='Fictitious atomic mass used for all atoms. There is no reason to change this, as it just corresponds to using a different integration timestep.', hidden=True, default=1.0, unit='Dalton')
self.dtMax: float | FloatKey = FloatKey(name='dtMax', comment='Maximum time step used for the integration. For ReaxFF and APPLE&P, this value is reduced by 50%.', default=1.0, unit='Femtoseconds')
self.dtStart: float | FloatKey = FloatKey(name='dtStart', comment='Initial time step for the integration.', default=0.25, unit='Femtoseconds')
self.fAlpha: float | FloatKey = FloatKey(name='fAlpha', comment='Reduction factor for the steering coefficient.', default=0.99)
self.fDec: float | FloatKey = FloatKey(name='fDec', comment='Reduction factor for reducing the time step in case of uphill movement.', default=0.5)
self.fInc: float | FloatKey = FloatKey(name='fInc', comment='Growth factor for the integration time step.', default=1.1)
self.strainMass: float | FloatKey = FloatKey(name='strainMass', comment='Fictitious relative mass of the lattice degrees of freedom. This controls the stiffness of the lattice degrees of freedom relative to the atomic degrees of freedom, with smaller values resulting in a more aggressive optimization of the lattice.', default=0.5)
[docs] class _HessianFree(FixedBlock):
r"""
Configures details of the Hessian-free (conjugate gradients or L-BFGS) geometry optimizer.
:ivar Step:
:vartype Step: Conformers._GeometryOptimization._GeometryOptimization._HessianFree._Step
"""
[docs] class _Step(FixedBlock):
r"""
:ivar MaxCartesianStep: Limit on a single Cartesian component of the step.
:vartype MaxCartesianStep: float | FloatKey
:ivar MinRadius: Minimum value for the trust radius.
:vartype MinRadius: float | FloatKey
:ivar TrialStep: Length of the finite-difference step when determining curvature. Should be smaller than the step convergence criterion.
:vartype TrialStep: float | FloatKey
:ivar TrustRadius: Initial value of the trust radius.
:vartype TrustRadius: float | FloatKey
"""
def __post_init__(self):
self.MaxCartesianStep: float | FloatKey = FloatKey(name='MaxCartesianStep', comment='Limit on a single Cartesian component of the step.', default=0.1, unit='Angstrom')
self.MinRadius: float | FloatKey = FloatKey(name='MinRadius', comment='Minimum value for the trust radius.', default=0.0, unit='Angstrom')
self.TrialStep: float | FloatKey = FloatKey(name='TrialStep', comment='Length of the finite-difference step when determining curvature. Should be smaller than the step convergence criterion.', default=0.0005, unit='Angstrom')
self.TrustRadius: float | FloatKey = FloatKey(name='TrustRadius', comment='Initial value of the trust radius.', default=0.2, unit='Angstrom')
def __post_init__(self):
self.Step: Conformers._GeometryOptimization._GeometryOptimization._HessianFree._Step = self._Step(name='Step')
[docs] class _InitialHessian(FixedBlock):
r"""
Options for initial model Hessian when optimizing systems with the Quasi-Newton method.
:ivar File: KF file containing the initial Hessian (or the results dir. containing it). This can be used to load a Hessian calculated in a previously with the [Properties%Hessian] keyword.
:vartype File: str | Path | StringKey
:ivar Type: Select the type of initial Hessian. Auto: let the program pick an initial model Hessian. UnitMatrix: simplest initial model Hessian, just a unit matrix in the optimization coordinates. Swart: model Hessian from M. Swart. FromFile: load the Hessian from the results of a previous calculation (see InitialHessian%File). Calculate: compute the initial Hessian (this may be computationally expensive and it is mostly recommended for TransitionStateSearch calculations). CalculateWithFastEngine: compute the initial Hessian with a faster engine.
:vartype Type: Literal["Auto", "UnitMatrix", "Swart", "FromFile", "Calculate", "CalculateWithFastEngine"]
"""
def __post_init__(self):
self.File: str | Path | StringKey = PathStringKey(name='File', comment='KF file containing the initial Hessian (or the results dir. containing it). This can be used to load a Hessian calculated in a previously with the [Properties%Hessian] keyword.', gui_name='Initial Hessian from:', ispath=True, gui_type='.rkf {{{RKF Result Files} .rkf} {{Any Files} *}}')
self.Type: Literal["Auto", "UnitMatrix", "Swart", "FromFile", "Calculate", "CalculateWithFastEngine"] = MultipleChoiceKey(name='Type', comment='Select the type of initial Hessian. Auto: let the program pick an initial model Hessian. UnitMatrix: simplest initial model Hessian, just a unit matrix in the optimization coordinates. Swart: model Hessian from M. Swart. FromFile: load the Hessian from the results of a previous calculation (see InitialHessian%File). Calculate: compute the initial Hessian (this may be computationally expensive and it is mostly recommended for TransitionStateSearch calculations). CalculateWithFastEngine: compute the initial Hessian with a faster engine.', gui_name='Initial Hessian:', default='Auto', choices=['Auto', 'UnitMatrix', 'Swart', 'FromFile', 'Calculate', 'CalculateWithFastEngine'])
[docs] class _Quasi_Newton(FixedBlock):
r"""
Configures details of the Quasi-Newton geometry optimizer.
:ivar EnforceConstraints: Whether to enforce constraints at each steps exactly or add them to the optimization space as Lagrange multipliers.
:vartype EnforceConstraints: BoolType | BoolKey
:ivar MaxGDIISVectors: Sets the maximum number of GDIIS vectors. Setting this to a number >0 enables the GDIIS method.
:vartype MaxGDIISVectors: int | IntKey
:ivar UpdateTSVectorEveryStep: Whether to update the TS reaction coordinate at each step with the current eigenvector.
:vartype UpdateTSVectorEveryStep: BoolType | BoolKey
:ivar Step:
:vartype Step: Conformers._GeometryOptimization._GeometryOptimization._Quasi-Newton._Step
"""
[docs] class _Step(FixedBlock):
r"""
:ivar TrustRadius: Initial value of the trust radius.
:vartype TrustRadius: float | FloatKey
:ivar VaryTrustRadius: Whether to allow the trust radius to change during optimization. By default True during energy minimization and False during transition state search.
:vartype VaryTrustRadius: BoolType | BoolKey
"""
def __post_init__(self):
self.TrustRadius: float | FloatKey = FloatKey(name='TrustRadius', comment='Initial value of the trust radius.')
self.VaryTrustRadius: BoolType | BoolKey = BoolKey(name='VaryTrustRadius', comment='Whether to allow the trust radius to change during optimization. By default True during energy minimization and False during transition state search.')
def __post_init__(self):
self.EnforceConstraints: BoolType | BoolKey = BoolKey(name='EnforceConstraints', comment='Whether to enforce constraints at each steps exactly or add them to the optimization space as Lagrange multipliers.', hidden=True, default=True)
self.MaxGDIISVectors: int | IntKey = IntKey(name='MaxGDIISVectors', comment='Sets the maximum number of GDIIS vectors. Setting this to a number >0 enables the GDIIS method.', default=0)
self.UpdateTSVectorEveryStep: BoolType | BoolKey = BoolKey(name='UpdateTSVectorEveryStep', comment='Whether to update the TS reaction coordinate at each step with the current eigenvector.', gui_name='Update TSRC vector every step:', default=True)
self.Step: Conformers._GeometryOptimization._GeometryOptimization._Quasi-Newton._Step = self._Step(name='Step')
def __post_init__(self):
self.CalcPropertiesOnlyIfConverged: BoolType | BoolKey = BoolKey(name='CalcPropertiesOnlyIfConverged', comment="Compute the properties requested in the 'Properties' block, e.g. Frequencies or Phonons, only if the optimization (or transition state search) converged. If False, the properties will be computed even if the optimization did not converge.", default=True)
self.CoordinateType: Literal["Auto", "Delocalized", "Cartesian"] = MultipleChoiceKey(name='CoordinateType', comment="Select the type of coordinates in which to perform the optimization. 'Auto' automatically selects the most appropriate CoordinateType for a given Method. \n\n If 'Auto' is selected, Delocalized coordinates will be used for the Quasi-Newton method, while Cartesian coordinates will be used for all other methods.", gui_name='Optimization space:', default='Auto', choices=['Auto', 'Delocalized', 'Cartesian'])
self.KeepIntermediateResults: BoolType | BoolKey = BoolKey(name='KeepIntermediateResults', comment='Whether the full engine result files of all intermediate steps are stored on disk. By default only the last step is kept, and only if the geometry optimization converged. This can easily lead to huge amounts of data being stored on disk, but it can sometimes be convenient to closely monitor a tricky optimization, e.g. excited state optimizations going through conical intersections, etc. ...', default=False)
self.MaxIterations: int | IntKey = IntKey(name='MaxIterations', comment='The maximum number of geometry iterations allowed to converge to the desired structure.', gui_name='Maximum number of iterations:', range='value >= 0')
self.MaxRestarts: int | IntKey = IntKey(name='MaxRestarts', comment='If a geometry optimization of a system with no symmetry operators (or with explicitly disabled symmetry: ``UseSymmetry False``) and enabled PES point characterization converges to a transition state (or higher order saddle point), it can be restarted automatically after a small displacement along the imaginary vibrational mode. In case the restarted optimization again does not find a minimum, this can happen multiple times in succession. This keyword sets the maximum number of restarts. The default value is 0, so the automatic restarting is disabled by default.', default=0)
self.Method: Literal["Auto", "Quasi-Newton", "FIRE", "L-BFGS", "ConjugateGradients", "Dimer"] = MultipleChoiceKey(name='Method', comment="Select the optimization algorithm employed for the geometry relaxation. Currently supported are: \n\nthe Hessian-based Quasi-Newton-type BFGS algorithm, \n\nthe fast inertial relaxation method (FIRE), \n\nthe limited-memory BFGS method, \n\nand the conjugate gradients method. The default is to choose an appropriate method automatically based on the engine's speed, the system size and the supported optimization options.", gui_name='Optimization method:', default='Auto', choices=['Auto', 'Quasi-Newton', 'FIRE', 'L-BFGS', 'ConjugateGradients', 'Dimer'])
self.OptimizeLattice: BoolType | BoolKey = BoolKey(name='OptimizeLattice', comment='Whether to also optimize the lattice for periodic structures. This is currently supported with the Quasi-Newton, FIRE, and L-BFGS optimizers.', default=False)
self.PretendConverged: BoolType | BoolKey = BoolKey(name='PretendConverged', comment='Normally a non-converged geometry optimization is considered an error. If this keyword is set to True, the optimizer will only produce a warning and still claim that the optimization is converged. (This is mostly useful for scripting applications, where one might want to consider non-converged optimizations still successful jobs.)', default=False)
self.RestartDisplacement: float | FloatKey = FloatKey(name='RestartDisplacement', comment='If a geometry optimization of a system with no symmetry operators (or with explicitly disabled symmetry: ``UseSymmetry False``) and enabled PES point characterization converges to a transition state (or higher order saddle point), it can be restarted automatically after a small displacement along the imaginary vibrational mode. This keywords sets the size of the displacement for the furthest moving atom.', default=0.05, unit='Angstrom')
self.Convergence: Conformers._GeometryOptimization._GeometryOptimization._Convergence = self._Convergence(name='Convergence', comment='Convergence is monitored for up to 4 quantities: the energy change, the Cartesian gradients, the Cartesian step size, and for lattice optimizations the stress energy per atom. Convergence criteria can be specified separately for each of these items.')
self.Dimer: Conformers._GeometryOptimization._GeometryOptimization._Dimer = self._Dimer(name='Dimer', comment='Options for the Dimer method for transition state search.')
self.EngineAutomations: Conformers._GeometryOptimization._GeometryOptimization._EngineAutomations = self._EngineAutomations(name='EngineAutomations', comment='The optimizer can change some settings of the engine, based for instance on the error.\nThe idea is to allow the engine to be a bit quicker at the start, and more accurate towards the end.\nAutomations are always engine specific.')
self.FIRE: Conformers._GeometryOptimization._GeometryOptimization._FIRE = self._FIRE(name='FIRE', comment='This block configures the details of the FIRE optimizer. The keywords name correspond the the symbols used in the article describing the method, see PRL 97, 170201 (2006).')
self.HessianFree: Conformers._GeometryOptimization._GeometryOptimization._HessianFree = self._HessianFree(name='HessianFree', comment='Configures details of the Hessian-free (conjugate gradients or L-BFGS) geometry optimizer.')
self.InitialHessian: Conformers._GeometryOptimization._GeometryOptimization._InitialHessian = self._InitialHessian(name='InitialHessian', comment='Options for initial model Hessian when optimizing systems with the Quasi-Newton method.')
self.Quasi_Newton: Conformers._GeometryOptimization._GeometryOptimization._Quasi-Newton = self._Quasi_Newton(name='Quasi-Newton', comment='Configures details of the Quasi-Newton geometry optimizer.')
[docs] class _WriteGeometries(FixedBlock):
r"""
Determines if and where optimized geometries will be written to file during optimization. When the AMSWorker is used, then the write interval depends on MaxOptimizations. If enabled, must be used in combination with Output%KeepWorkDir.
:ivar Dirname: The name of the folder that should contain the optimized geometries.
:vartype Dirname: str | StringKey
:ivar Enabled: Enables or disables the periodic writing of optimized geometries to file
:vartype Enabled: BoolType | BoolKey
"""
def __post_init__(self):
self.Dirname: str | StringKey = StringKey(name='Dirname', comment='The name of the folder that should contain the optimized geometries.', default='conf_tmpdir')
self.Enabled: BoolType | BoolKey = BoolKey(name='Enabled', comment='Enables or disables the periodic writing of optimized geometries to file', default=False)
def __post_init__(self):
self.ConvergenceQuality: Literal["Normal", "Good", "VeryGood", "Excellent"] = MultipleChoiceKey(name='ConvergenceQuality', comment='The tightness of the convergence of the geometry optimizations. Lower quality levels may lead to badly converged geometries being classified as distinct conformers.', gui_name='Convergence:', default='VeryGood', choices=['Normal', 'Good', 'VeryGood', 'Excellent'])
self.Keep: Literal["None", "all"] = MultipleChoiceKey(name='Keep', comment="Keep all the output files of the geometry optimizations. If set to 'all', must be used in combination with Output%KeepWorkDir.", default='None', choices=['None', 'all'])
self.MaxConvergenceTime: Literal["Default", "High"] = MultipleChoiceKey(name='MaxConvergenceTime', comment='The number of iterations for the geometry optimization, based on the number of atoms in the system. The default value is the general AMS value for geometry optimization. Often, for conformer generation, it needs to be set higher.', default='Default', choices=['Default', 'High'])
self.MaxOptimizations: int | IntKey = IntKey(name='MaxOptimizations', comment='Set a maximum to the number of geometries accepted for optimization at once, per AMSWorker (so should be multiplied by the number of cores used). If not set, the disc size requirements can become too large.', default=1000)
self.OptimizationMethod: Literal["Auto", "Quasi-Newton", "FIRE", "L-BFGS", "ConjugateGradients", "Dimer"] = MultipleChoiceKey(name='OptimizationMethod', comment='Select the optimization algorithm employed for the geometry relaxation. Currently supported are: \n\nthe Hessian-based Quasi-Newton-type BFGS algorithm, \n\nthe fast inertial relaxation method (FIRE), \n\nthe limited-memory BFGS method, \n\nand the conjugate gradients method. The default is Quasi-Newton, which gives the most reliable results for conformers. The Auto method leaves it to the AMS GeometryOptimization task to select a method.', default='Quasi-Newton', choices=['Auto', 'Quasi-Newton', 'FIRE', 'L-BFGS', 'ConjugateGradients', 'Dimer'])
self.UseAMSWorker: BoolType | BoolKey = BoolKey(name='UseAMSWorker', comment='Whether the set of optimizations should be run via the AMSWorkerPool or via regular AMSJobs.', default=True)
self.GeometryOptimization: Conformers._GeometryOptimization._GeometryOptimization = self._GeometryOptimization(name='GeometryOptimization', comment='Configures details of the geometry optimization and transition state searches.')
self.WriteGeometries: Conformers._GeometryOptimization._WriteGeometries = self._WriteGeometries(name='WriteGeometries', comment='Determines if and where optimized geometries will be written to file during optimization. When the AMSWorker is used, then the write interval depends on MaxOptimizations. If enabled, must be used in combination with Output%KeepWorkDir.')
[docs] class _LoadSystem(FixedBlock):
r"""
Block that controls reading the chemical system from a KF file instead of the [System] block.
:ivar File: The path of the KF file from which to load the system. It may also be the results directory containing it.
:vartype File: str | Path | StringKey
:ivar Section: The section on the KF file from which to load the system.
:vartype Section: str | StringKey
"""
def __post_init__(self):
self.File: str | Path | StringKey = PathStringKey(name='File', comment='The path of the KF file from which to load the system. It may also be the results directory containing it.', ispath=True)
self.Section: str | StringKey = StringKey(name='Section', comment='The section on the KF file from which to load the system.', default='Molecule')
[docs] class _Output(FixedBlock):
r"""
Options regarding the output and result files.
:ivar KeepWorkDir: Do not remove the working directories after the conformer generation is finished.
:vartype KeepWorkDir: BoolType | BoolKey
:ivar rkf: Save the final conformers in .rkf format. The file 'conformers.rkf' will be located in the results directory. You can visualize this file using the AMSMovie GUI module.
:vartype rkf: BoolType | BoolKey
:ivar sdf: Save the final conformers in .sdf format. The file 'conformers.sdf' will be located in the results directory.
:vartype sdf: BoolType | BoolKey
:ivar xyz: Save the final conformers in .xyz format. The file 'conformers.xyz' will be located in the results directory.
:vartype xyz: BoolType | BoolKey
"""
def __post_init__(self):
self.KeepWorkDir: BoolType | BoolKey = BoolKey(name='KeepWorkDir', comment='Do not remove the working directories after the conformer generation is finished.', default=False)
self.rkf: BoolType | BoolKey = BoolKey(name='rkf', comment="Save the final conformers in .rkf format. The file 'conformers.rkf' will be located in the results directory. You can visualize this file using the AMSMovie GUI module.", default=True)
self.sdf: BoolType | BoolKey = BoolKey(name='sdf', comment="Save the final conformers in .sdf format. The file 'conformers.sdf' will be located in the results directory.", default=True)
self.xyz: BoolType | BoolKey = BoolKey(name='xyz', comment="Save the final conformers in .xyz format. The file 'conformers.xyz' will be located in the results directory.", default=True)
[docs] class _Restraints(FixedBlock):
r"""
The Restraints block allows to add soft constraints to the system. A restraint is a potential energy function (a spring) attached to a certain coordinate, for example, an interatomic distance, with its minimum at the specified optimal value. A restraint is defined using one or two parameters: the ForceConstant and, for some types, the F(Inf) value. The ForceConstant parameter corresponds to second derivative of the restraint potential energy d2V(x)/dx^2 for any x (harmonic restraints) or only at at x=0 (other restraints). Here, x is a deviation from the restraint's optimal value.
:ivar Angle: Specify three atom indices i j k followed by an angle in degrees and, optionally, by the ForceConstant (default is 0.3 in a.u.), profile type and F(Inf) (in a.u.). This restraint will try to keep the i-j-k angle at the given value. For periodic systems this restraint follows the minimum image convention.
:vartype Angle: str | StringKey
:ivar DifDist: Specify four atom indices i j k l followed by the distance in Angstrom and, optionally, by the ForceConstant (default is 1.0 in a.u.), profile type and F(Inf) (in a.u.). This restraint will try to keep the difference R(ij)-R(kl) at the given value. For periodic systems this restraint follows the minimum image convention.
:vartype DifDist: str | StringKey
:ivar Dihedral: Specify four atom indices i j k l followed by an angle in degrees and, optionally, by the ForceConstant (default is 0.1 in a.u.), profile type and F(Inf) (in a.u.). This restraint will try to keep the i-j-k-l dihedral angle at the given value. For periodic systems this restraint follows the minimum image convention.
:vartype Dihedral: str | StringKey
:ivar Distance: Specify two atom indices followed by the distance in Angstrom and, optionally, by the ForceConstant (default is 1.0 in a.u.), profile type and F(Inf) (in a.u.). This restraint will try to keep the distance between the two specified atoms at the given value. For periodic systems this restraint follows the minimum image convention.
:vartype Distance: str | StringKey
:ivar FInfinity: Specify the default asymptotic value for the restraint force for the Hyperbolic and Erf profiles, in Hartree/Bohr or Hartree/radian.
A per-restraint value can be specified after the profile type on the corresponding restraint line.
:vartype FInfinity: float | FloatKey
:ivar Profile: Select the default type of restraint profile.
The harmonic profile is most suitable for geometry optimizations but may result is very large forces that can be problematic in molecular dynamic.
For MD simulations the Hyperbolic or Erf may be more suitable because the restraint force is bounded by a user-defined value.
A per-restraint profile type can be specified after the ForceConstant value on the corresponding restraint line.
:vartype Profile: Literal["Harmonic", "Hyperbolic", "Erf", "GaussianWell"]
:ivar SumDist: Specify four atom indices i j k l followed by the distance in Angstrom and, optionally, by the ForceConstant (default is 1.0 in a.u.), profile type and F(Inf) (in a.u.). This restraint will try to keep the sum R(ij)+R(kl) at the given value. For periodic systems this restraint follows the minimum image convention.
:vartype SumDist: str | StringKey
:ivar Units: Change units for energy, force and force constant values from the default (atomic units) to those often used in the MD community (based on kcal/mol and Angstrom). Units for the optimal distances are not affected and are always Angstrom.
:vartype Units: Literal["Default", "MD"]
"""
def __post_init__(self):
self.Angle: str | StringKey = StringKey(name='Angle', comment='Specify three atom indices i j k followed by an angle in degrees and, optionally, by the ForceConstant (default is 0.3 in a.u.), profile type and F(Inf) (in a.u.). This restraint will try to keep the i-j-k angle at the given value. For periodic systems this restraint follows the minimum image convention.', unique=False)
self.DifDist: str | StringKey = StringKey(name='DifDist', comment='Specify four atom indices i j k l followed by the distance in Angstrom and, optionally, by the ForceConstant (default is 1.0 in a.u.), profile type and F(Inf) (in a.u.). This restraint will try to keep the difference R(ij)-R(kl) at the given value. For periodic systems this restraint follows the minimum image convention.', unique=False)
self.Dihedral: str | StringKey = StringKey(name='Dihedral', comment='Specify four atom indices i j k l followed by an angle in degrees and, optionally, by the ForceConstant (default is 0.1 in a.u.), profile type and F(Inf) (in a.u.). This restraint will try to keep the i-j-k-l dihedral angle at the given value. For periodic systems this restraint follows the minimum image convention.', unique=False)
self.Distance: str | StringKey = StringKey(name='Distance', comment='Specify two atom indices followed by the distance in Angstrom and, optionally, by the ForceConstant (default is 1.0 in a.u.), profile type and F(Inf) (in a.u.). This restraint will try to keep the distance between the two specified atoms at the given value. For periodic systems this restraint follows the minimum image convention.', unique=False)
self.FInfinity: float | FloatKey = FloatKey(name='FInfinity', comment='Specify the default asymptotic value for the restraint force for the Hyperbolic and Erf profiles, in Hartree/Bohr or Hartree/radian.\n\nA per-restraint value can be specified after the profile type on the corresponding restraint line.', gui_name='Default F(inf):', default=1.0)
self.Profile: Literal["Harmonic", "Hyperbolic", "Erf", "GaussianWell"] = MultipleChoiceKey(name='Profile', comment='Select the default type of restraint profile.\n\nThe harmonic profile is most suitable for geometry optimizations but may result is very large forces that can be problematic in molecular dynamic.\n\nFor MD simulations the Hyperbolic or Erf may be more suitable because the restraint force is bounded by a user-defined value.\n\nA per-restraint profile type can be specified after the ForceConstant value on the corresponding restraint line.', gui_name='Default restraint profile:', default='Harmonic', choices=['Harmonic', 'Hyperbolic', 'Erf', 'GaussianWell'])
self.SumDist: str | StringKey = StringKey(name='SumDist', comment='Specify four atom indices i j k l followed by the distance in Angstrom and, optionally, by the ForceConstant (default is 1.0 in a.u.), profile type and F(Inf) (in a.u.). This restraint will try to keep the sum R(ij)+R(kl) at the given value. For periodic systems this restraint follows the minimum image convention.', unique=False)
self.Units: Literal["Default", "MD"] = MultipleChoiceKey(name='Units', comment='Change units for energy, force and force constant values from the default (atomic units) to those often used in the MD community (based on kcal/mol and Angstrom). Units for the optimal distances are not affected and are always Angstrom.', gui_name='Units:', default='Default', choices=['Default', 'MD'])
[docs] class _Rotamers(FixedBlock):
r"""
Options for the treatment of Grimme-rotamers.
:ivar Read: Whether to read all associated rotamers from disk when loading a set of conformers with the ``InputConformersSet`` keyword.
:vartype Read: BoolType | BoolKey
:ivar Write: Whether to write the geometries of all found conformers to the output files.
:vartype Write: BoolType | BoolKey
"""
def __post_init__(self):
self.Read: BoolType | BoolKey = BoolKey(name='Read', comment='Whether to read all associated rotamers from disk when loading a set of conformers with the ``InputConformersSet`` keyword.', default=False)
self.Write: BoolType | BoolKey = BoolKey(name='Write', comment='Whether to write the geometries of all found conformers to the output files.', default=False)
[docs] class _System(FixedBlock):
r"""
Specification of the chemical system. For some applications more than one system may be present in the input. In this case, all systems except one must have a non-empty string ID specified after the System keyword. The system without an ID is considered the main one.
:ivar AllowCloseAtoms: No longer functional. Just here for backwards compatibility.
:vartype AllowCloseAtoms: BoolType | BoolKey
:ivar Charge: The system's total charge in atomic units.
:vartype Charge: float | FloatKey
:ivar FractionalCoords: Whether the atomic coordinates in the Atoms block are given in fractional coordinates of the lattice vectors. Requires the presence of the Lattice block.
:vartype FractionalCoords: BoolType | BoolKey
:ivar GeometryFile: Read the geometry from a file (instead of from Atoms and Lattice blocks). Supported formats: .xyz
:vartype GeometryFile: str | Path | StringKey
:ivar GuessBonds: Equivalent to 'Modify%GuessBonds'. Please update input file to use 'Modify' block instead.
:vartype GuessBonds: BoolType | BoolKey
:ivar LatticeStrain: Equivalent to 'Modify%LatticeStrain'. Please update input file to use 'Modify' block instead.
:vartype LatticeStrain: Iterable[float] | FloatListKey
:ivar MapAtomsToUnitCell: Equivalent to 'Modify%MapAtomsToUnitCell'. Please update input file to use 'Modify' block instead.
:vartype MapAtomsToUnitCell: BoolType | BoolKey
:ivar PerturbCoordinates: Equivalent to 'Modify%PerturbCoordinates'. Please update input file to use 'Modify' block instead.
:vartype PerturbCoordinates: float | FloatKey
:ivar PerturbLattice: Equivalent to 'Modify%PerturbLattice'. Please update input file to use 'Modify' block instead.
:vartype PerturbLattice: float | FloatKey
:ivar ShiftCoordinates: Equivalent to 'Modify%Translate', but in the unit of bohr by default. Please update input file to use 'Modify' block instead.
:vartype ShiftCoordinates: Iterable[float] | FloatListKey
:ivar SuperCell: Equivalent to 'Modify%SuperCell'. Please update input file to use 'Modify' block instead.
:vartype SuperCell: Iterable[int] | IntListKey
:ivar SuperCellTrafo: Equivalent to 'Modify%SuperCellTrafo'. Please update input file to use 'Modify' block instead.
:vartype SuperCellTrafo: Iterable[int] | IntListKey
:ivar Symmetrize: Equivalent to 'Modify%Symmetrize'. Please update input file to use 'Modify' block instead.
:vartype Symmetrize: BoolType | BoolKey
:ivar Atoms: The atom types and coordinates. Unit can be specified in the header. Default unit is Angstrom.
:vartype Atoms: str | Sequence[str] | FreeBlock
:ivar BondOrders: Defined bond orders. Each line should contain two atom indices, followed by the bond order (1, 1.5, 2, 3 for single, aromatic, double and triple bonds) and (optionally) the cell shifts for periodic systems. May be used by MM engines and for defining constraints. If the system is periodic and none of the bonds have the cell shift defined then AMS will attempt to determine them following the minimum image convention.
:vartype BondOrders: str | Sequence[str] | FreeBlock
:ivar ElectrostaticEmbedding: Container for electrostatic embedding options, which can be combined.
:vartype ElectrostaticEmbedding: Conformers._System._ElectrostaticEmbedding
:ivar Lattice: Up to three lattice vectors. Unit can be specified in the header. Default unit is Angstrom.
:vartype Lattice: str | Sequence[str] | FreeBlock
:ivar Modify: Modifications to make to the chemical system after construction. This block is read like a script and the modifications applied top to bottom.
:vartype Modify: Conformers._System._Modify
"""
[docs] class _Atoms(FreeBlock):
r"""
The atom types and coordinates. Unit can be specified in the header. Default unit is Angstrom.
"""
def __post_init__(self):
pass
[docs] class _BondOrders(FreeBlock):
r"""
Defined bond orders. Each line should contain two atom indices, followed by the bond order (1, 1.5, 2, 3 for single, aromatic, double and triple bonds) and (optionally) the cell shifts for periodic systems. May be used by MM engines and for defining constraints. If the system is periodic and none of the bonds have the cell shift defined then AMS will attempt to determine them following the minimum image convention.
"""
def __post_init__(self):
pass
[docs] class _ElectrostaticEmbedding(FixedBlock):
r"""
Container for electrostatic embedding options, which can be combined.
:ivar ElectricField: External homogeneous electric field with three Cartesian components: ex, ey, ez, the default unit being V/Å.
In atomic units: Hartree/(e bohr) = 51.422 V/Angstrom; the relation to SI units is: 1 Hartree/(e bohr) = 5.14 ... e11 V/m.
Supported by the engines adf, band, dftb and mopac.
For periodic systems the field may only have nonzero components orthogonal to the direction(s) of periodicity (i.e. for 1D periodic system the x-component of the electric field should be zero, while for 2D periodic systems both the x and y components should be zero. This options cannot be used for 3D periodic systems.
:vartype ElectricField: Iterable[float] | FloatListKey
:ivar MultipolePotential: External point charges (and dipoles).
:vartype MultipolePotential: Conformers._System._ElectrostaticEmbedding._MultipolePotential
"""
[docs] class _MultipolePotential(FixedBlock):
r"""
External point charges (and dipoles).
:ivar ChargeModel: A multipole may be represented by a point (with a singular potential at its location) or by a spherical Gaussian distribution.
:vartype ChargeModel: Literal["Point", "Gaussian"]
:ivar ChargeWidth: The width parameter in a.u. in case a Gaussian charge model is chosen. A negative value means that the width will be chosen automatically.
:vartype ChargeWidth: float | FloatKey
:ivar Coordinates: Positions and values of the multipoles, one per line. Each line has the following format:
x y z q, or
x y z q µx µy µz.
Here x, y, z are the coordinates in Å, q is the charge (in atomic units of charge) and µx, µy, µz are the (optional) dipole moment components (in atomic units, i.e. e*Bohr).
Periodic systems are not supported.
:vartype Coordinates: str | Sequence[str] | FreeBlock
"""
[docs] class _Coordinates(FreeBlock):
r"""
Positions and values of the multipoles, one per line. Each line has the following format:
x y z q, or
x y z q µx µy µz.
Here x, y, z are the coordinates in Å, q is the charge (in atomic units of charge) and µx, µy, µz are the (optional) dipole moment components (in atomic units, i.e. e*Bohr).
Periodic systems are not supported.
"""
def __post_init__(self):
pass
def __post_init__(self):
self.ChargeModel: Literal["Point", "Gaussian"] = MultipleChoiceKey(name='ChargeModel', comment='A multipole may be represented by a point (with a singular potential at its location) or by a spherical Gaussian distribution.', default='Point', choices=['Point', 'Gaussian'])
self.ChargeWidth: float | FloatKey = FloatKey(name='ChargeWidth', comment='The width parameter in a.u. in case a Gaussian charge model is chosen. A negative value means that the width will be chosen automatically.', default=-1.0)
self.Coordinates: str | Sequence[str] | FreeBlock = self._Coordinates(name='Coordinates', comment='Positions and values of the multipoles, one per line. Each line has the following format:\n\nx y z q, or\nx y z q µx µy µz.\n\nHere x, y, z are the coordinates in Å, q is the charge (in atomic units of charge) and µx, µy, µz are the (optional) dipole moment components (in atomic units, i.e. e*Bohr). \n\nPeriodic systems are not supported.', header=True)
def __post_init__(self):
self.ElectricField: Iterable[float] | FloatListKey = FloatListKey(name='ElectricField', comment='External homogeneous electric field with three Cartesian components: ex, ey, ez, the default unit being V/Å.\n\nIn atomic units: Hartree/(e bohr) = 51.422 V/Angstrom; the relation to SI units is: 1 Hartree/(e bohr) = 5.14 ... e11 V/m.\n\nSupported by the engines adf, band, dftb and mopac.\n\nFor periodic systems the field may only have nonzero components orthogonal to the direction(s) of periodicity (i.e. for 1D periodic system the x-component of the electric field should be zero, while for 2D periodic systems both the x and y components should be zero. This options cannot be used for 3D periodic systems.', unit='V/Angstrom')
self.MultipolePotential: Conformers._System._ElectrostaticEmbedding._MultipolePotential = self._MultipolePotential(name='MultipolePotential', comment='External point charges (and dipoles).')
[docs] class _Lattice(FreeBlock):
r"""
Up to three lattice vectors. Unit can be specified in the header. Default unit is Angstrom.
"""
def __post_init__(self):
pass
[docs] class _Modify(FixedBlock):
r"""
Modifications to make to the chemical system after construction. This block is read like a script and the modifications applied top to bottom.
:ivar EnableAtomicProperties: Enables an atomic property group. This is only necessary if you want a group enabled, but no atom in the input is using any property from that group.
:vartype EnableAtomicProperties: Literal["gui", "adf", "band", "forcefield", "dftb", "reaxff", "qe"]
:ivar GuessBonds: Guesses bonds based on the atomic elements and the geometry. Keeps existing bonds.
:vartype GuessBonds: BoolType | BoolKey
:ivar LatticeStrain: Deform the input system by the specified strain. The strain elements are in Voigt notation, so one should specify 6 numbers for 3D periodic system (order: xx,yy,zz,yz,xz,xy), 3 numbers for 2D periodic systems (order: xx,yy,xy) or 1 number for 1D periodic systems.
:vartype LatticeStrain: Iterable[float] | FloatListKey
:ivar MapAtomsToUnitCell: For periodic systems the atoms will be moved to the central unit cell where all their fractional coordinates are in the range [start_range,start_range+1). No mapping will take place along non-periodic directions. If just a single number is given, it corresponds to start_range. If multiple numbers are given, they should match the number of lattice vectors and will be used as start ranges along the individual lattice vectors. If no number is given at all, the mapping will be done to the [-0.5:0.5) cell.
:vartype MapAtomsToUnitCell: Iterable[float] | FloatListKey
:ivar PerturbCoordinates: Perturb the atomic coordinates by adding random numbers between [-PerturbCoordinates,PerturbCoordinates] to each Cartesian component. This can be useful if you want to break the symmetry of your system (e.g. for a geometry optimization).
:vartype PerturbCoordinates: float | FloatKey
:ivar PerturbLattice: Perturb the lattice vectors by applying random strain with matrix elements between [-PerturbLattice,PerturbLattice]. This can be useful if you want to deviate from an ideal symmetric geometry, for example if you look for a phase change due to high pressure.
:vartype PerturbLattice: float | FloatKey
:ivar SuperCell: Create a supercell of the input system (only possible for periodic systems). The integer numbers represent the diagonal elements of the supercell transformation; you should specify as many numbers as lattice vectors (i.e. 1 number for 1D, 2 numbers for 2D and 3 numbers for 3D periodic systems).
:vartype SuperCell: Iterable[int] | IntListKey
:ivar SuperCellTrafo: Create a supercell of the input system (only possible for periodic systems) :math:`\vec{a}_i' = \sum_j T_{ij} \vec{a}_j`. The integer numbers represent the supercell transformation :math:`T_{ij}`: 1 number for 1D PBC, 4 numbers for 2D PBC corresponding to a 2x2 matrix (order: (1,1),(1,2),(2,1),(2,2)) and 9 numbers for 3D PBC corresponding to a 3x3 matrix (order: (1,1),(1,2),(1,3),(2,1),(2,2),(2,3),(3,1),(3,2),(3,3)).
:vartype SuperCellTrafo: Iterable[int] | IntListKey
:ivar Symmetrize: Symmetrizes the atomic coordinates to machine precision and rototranslates the molecule to the AMS standard orientation. This allows optimal use of the system's symmetry for calculations with the AMS driver and its engines.
:vartype Symmetrize: BoolType | BoolKey
:ivar Translate: Translate all atoms by a vector.
:vartype Translate: Iterable[float] | FloatListKey
"""
def __post_init__(self):
self.EnableAtomicProperties: Literal["gui", "adf", "band", "forcefield", "dftb", "reaxff", "qe"] = MultipleChoiceKey(name='EnableAtomicProperties', comment='Enables an atomic property group. This is only necessary if you want a group enabled, but no atom in the input is using any property from that group.', unique=False, choices=['gui', 'adf', 'band', 'forcefield', 'dftb', 'reaxff', 'qe'])
self.GuessBonds: BoolType | BoolKey = BoolKey(name='GuessBonds', comment='Guesses bonds based on the atomic elements and the geometry. Keeps existing bonds.', unique=False)
self.LatticeStrain: Iterable[float] | FloatListKey = FloatListKey(name='LatticeStrain', comment='Deform the input system by the specified strain. The strain elements are in Voigt notation, so one should specify 6 numbers for 3D periodic system (order: xx,yy,zz,yz,xz,xy), 3 numbers for 2D periodic systems (order: xx,yy,xy) or 1 number for 1D periodic systems.', unique=False)
self.MapAtomsToUnitCell: Iterable[float] | FloatListKey = FloatListKey(name='MapAtomsToUnitCell', comment='For periodic systems the atoms will be moved to the central unit cell where all their fractional coordinates are in the range [start_range,start_range+1). No mapping will take place along non-periodic directions. If just a single number is given, it corresponds to start_range. If multiple numbers are given, they should match the number of lattice vectors and will be used as start ranges along the individual lattice vectors. If no number is given at all, the mapping will be done to the [-0.5:0.5) cell.', unique=False)
self.PerturbCoordinates: float | FloatKey = FloatKey(name='PerturbCoordinates', comment='Perturb the atomic coordinates by adding random numbers between [-PerturbCoordinates,PerturbCoordinates] to each Cartesian component. This can be useful if you want to break the symmetry of your system (e.g. for a geometry optimization).', unique=False, unit='angstrom')
self.PerturbLattice: float | FloatKey = FloatKey(name='PerturbLattice', comment='Perturb the lattice vectors by applying random strain with matrix elements between [-PerturbLattice,PerturbLattice]. This can be useful if you want to deviate from an ideal symmetric geometry, for example if you look for a phase change due to high pressure.', unique=False)
self.SuperCell: Iterable[int] | IntListKey = IntListKey(name='SuperCell', comment='Create a supercell of the input system (only possible for periodic systems). The integer numbers represent the diagonal elements of the supercell transformation; you should specify as many numbers as lattice vectors (i.e. 1 number for 1D, 2 numbers for 2D and 3 numbers for 3D periodic systems).', unique=False)
self.SuperCellTrafo: Iterable[int] | IntListKey = IntListKey(name='SuperCellTrafo', comment="Create a supercell of the input system (only possible for periodic systems) :math:`\\vec{a}_i' = \\sum_j T_{ij} \\vec{a}_j`. The integer numbers represent the supercell transformation :math:`T_{ij}`: 1 number for 1D PBC, 4 numbers for 2D PBC corresponding to a 2x2 matrix (order: (1,1),(1,2),(2,1),(2,2)) and 9 numbers for 3D PBC corresponding to a 3x3 matrix (order: (1,1),(1,2),(1,3),(2,1),(2,2),(2,3),(3,1),(3,2),(3,3)).", unique=False)
self.Symmetrize: BoolType | BoolKey = BoolKey(name='Symmetrize', comment="Symmetrizes the atomic coordinates to machine precision and rototranslates the molecule to the AMS standard orientation. This allows optimal use of the system's symmetry for calculations with the AMS driver and its engines.", unique=False, default=False)
self.Translate: Iterable[float] | FloatListKey = FloatListKey(name='Translate', comment='Translate all atoms by a vector.', unique=False, unit='angstrom')
def __post_init__(self):
self.AllowCloseAtoms: BoolType | BoolKey = BoolKey(name='AllowCloseAtoms', comment='No longer functional. Just here for backwards compatibility.', hidden=True, default=True)
self.Charge: float | FloatKey = FloatKey(name='Charge', comment="The system's total charge in atomic units.", gui_name='Total charge:', default=0.0, engines='-forcefield')
self.FractionalCoords: BoolType | BoolKey = BoolKey(name='FractionalCoords', comment='Whether the atomic coordinates in the Atoms block are given in fractional coordinates of the lattice vectors. Requires the presence of the Lattice block.', default=False)
self.GeometryFile: str | Path | StringKey = PathStringKey(name='GeometryFile', comment='Read the geometry from a file (instead of from Atoms and Lattice blocks). Supported formats: .xyz', ispath=True)
self.GuessBonds: BoolType | BoolKey = BoolKey(name='GuessBonds', comment="Equivalent to 'Modify%GuessBonds'. Please update input file to use 'Modify' block instead.", hidden=True)
self.LatticeStrain: Iterable[float] | FloatListKey = FloatListKey(name='LatticeStrain', comment="Equivalent to 'Modify%LatticeStrain'. Please update input file to use 'Modify' block instead.", hidden=True)
self.MapAtomsToUnitCell: BoolType | BoolKey = BoolKey(name='MapAtomsToUnitCell', comment="Equivalent to 'Modify%MapAtomsToUnitCell'. Please update input file to use 'Modify' block instead.", hidden=True)
self.PerturbCoordinates: float | FloatKey = FloatKey(name='PerturbCoordinates', comment="Equivalent to 'Modify%PerturbCoordinates'. Please update input file to use 'Modify' block instead.", hidden=True, unit='angstrom')
self.PerturbLattice: float | FloatKey = FloatKey(name='PerturbLattice', comment="Equivalent to 'Modify%PerturbLattice'. Please update input file to use 'Modify' block instead.", hidden=True)
self.ShiftCoordinates: Iterable[float] | FloatListKey = FloatListKey(name='ShiftCoordinates', comment="Equivalent to 'Modify%Translate', but in the unit of bohr by default. Please update input file to use 'Modify' block instead.", hidden=True, unit='bohr')
self.SuperCell: Iterable[int] | IntListKey = IntListKey(name='SuperCell', comment="Equivalent to 'Modify%SuperCell'. Please update input file to use 'Modify' block instead.", hidden=True)
self.SuperCellTrafo: Iterable[int] | IntListKey = IntListKey(name='SuperCellTrafo', comment="Equivalent to 'Modify%SuperCellTrafo'. Please update input file to use 'Modify' block instead.", hidden=True)
self.Symmetrize: BoolType | BoolKey = BoolKey(name='Symmetrize', comment="Equivalent to 'Modify%Symmetrize'. Please update input file to use 'Modify' block instead.", hidden=True, default=False)
self.Atoms: str | Sequence[str] | FreeBlock = self._Atoms(name='Atoms', comment='The atom types and coordinates. Unit can be specified in the header. Default unit is Angstrom.', header=True)
self.BondOrders: str | Sequence[str] | FreeBlock = self._BondOrders(name='BondOrders', comment='Defined bond orders. Each line should contain two atom indices, followed by the bond order (1, 1.5, 2, 3 for single, aromatic, double and triple bonds) and (optionally) the cell shifts for periodic systems. May be used by MM engines and for defining constraints. If the system is periodic and none of the bonds have the cell shift defined then AMS will attempt to determine them following the minimum image convention.')
self.ElectrostaticEmbedding: Conformers._System._ElectrostaticEmbedding = self._ElectrostaticEmbedding(name='ElectrostaticEmbedding', comment='Container for electrostatic embedding options, which can be combined.')
self.Lattice: str | Sequence[str] | FreeBlock = self._Lattice(name='Lattice', comment='Up to three lattice vectors. Unit can be specified in the header. Default unit is Angstrom.', header=True)
self.Modify: Conformers._System._Modify = self._Modify(name='Modify', comment='Modifications to make to the chemical system after construction. This block is read like a script and the modifications applied top to bottom.', ordered=True)
def __post_init__(self):
self.InputConformersSet: str | Path | StringKey = PathStringKey(name='InputConformersSet', comment="The path to a file containing a set of conformers.\n\nThe file should be either an 'conformers.rkf' file (i.e. the results file of conformers), a concatenated .xyz file, a .sdf file, or even .dcd file. In the case of a .dcd file, an additional System block is required. If the specified file does not contain energies in the AMS conformers format (as produced by the conformers tool), all conformer energies will be set to zero.\n\nYou can specify multiple input conformers sets by including the InputConformersSet keyword multiple times.", unique=False, ispath=True)
self.InputMaxConfs: int | IntKey = IntKey(name='InputMaxConfs', comment='The maximum number of conformers to carry forward when loading conformer sets. If this input is not specified, this limit will not be imposed.')
self.InputMaxEnergy: float | FloatKey = FloatKey(name='InputMaxEnergy', comment='Threshold for filtering out high-energy conformers when loading conformers sets using the InputConformerSet keyword. Conformers with an larger relative energy will not be loaded.', unit='kcal/mol')
self.RNGSeed: int | IntKey = IntKey(name='RNGSeed', comment='Initial seed for the (pseudo)random number generator. If this is unset, the generator will be seeded randomly from external sources of entropy and the generated conformers will be non-deterministic.')
self.Task: Literal["Generate", "Optimize", "Filter", "Score", "Expand"] = MultipleChoiceKey(name='Task', comment="The task to be performed by the Conformers tool.\n\n'Generate': given a molecule, generate a set of conformers. Note: this task will automatically optimize, filter and score the conformers.\n\n'Optimize': given a previously generated set of conformers, optimize, filter and score the structures using the specified engine.\n\n'Filter': given one or more previously generated set of conformers, merge them into a single conformer set and filter out duplicate conformers. Note: this will not optimize or re-score the conformers.\n\n'Score' given one or more previously generated set of conformers, re-score them by computing the energy using the specified engine. Note: this will only do a single point calculation, and will not optimize the structures.\n\nIn case of 'Optimize', 'Filter' and 'Score' you can specify the input conformer set(s) using the 'InputConformersSet' keyword.", default='Generate', choices=['Generate', 'Optimize', 'Filter', 'Score', 'Expand'])
self.Constraints: Conformers._Constraints = self._Constraints(name='Constraints', comment='The Constraints block allows geometry optimizations and potential energy surface scans with constraints. The constraints do not have to be satisfied at the start of the calculation.', extra_info='not_in_fragment', shared_id='AMSConstraints')
self.Engine: EngineBlock = self._Engine(name='Engine', comment='The input for the computational engine used to compute energy and forces.', header=True, default_engine='ForceField')
self.EngineAddons: Conformers._EngineAddons = self._EngineAddons(name='EngineAddons', comment='This block configures all the engine add-ons.')
self.Equivalence: Conformers._Equivalence = self._Equivalence(name='Equivalence', comment='Options for the procedure determining whether two structures are equivalent or distinct conformers.')
self.Expander: Conformers._Expander = self._Expander(name='Expander', comment='Options for the conformer expander. The Expander expands an existing conformer set, by adding new conformers to it. The new conformers are generated from the original conformers in the set. Unlike the generators, the outcome of an expander is therefore very dependent on the input conformations.\n\nThe GC generator uses a genetic algorithm to create a combinatorial expansion by combining local substructures.\nThe MD expander start MD simulations from the conformers in the set, and extracts snapshots to create new conformers. Both these expanders are part of the CREST generator.')
self.Filter: Conformers._Filter = self._Filter(name='Filter', comment='Options for the conformer filtering.')
self.Generator: Conformers._Generator = self._Generator(name='Generator', comment='Options for the conformer generator.')
self.GeometryOptimization: Conformers._GeometryOptimization = self._GeometryOptimization(name='GeometryOptimization', comment='Some options / details regarding the optimization procedure.')
self.LoadSystem: Conformers._LoadSystem = self._LoadSystem(name='LoadSystem', comment='Block that controls reading the chemical system from a KF file instead of the [System] block.', unique=False, header=True, extra_info='not_in_fragment', shared_id='AMSLoadSystem')
self.Output: Conformers._Output = self._Output(name='Output', comment='Options regarding the output and result files.')
self.Restraints: Conformers._Restraints = self._Restraints(name='Restraints', comment="The Restraints block allows to add soft constraints to the system. A restraint is a potential energy function (a spring) attached to a certain coordinate, for example, an interatomic distance, with its minimum at the specified optimal value. A restraint is defined using one or two parameters: the ForceConstant and, for some types, the F(Inf) value. The ForceConstant parameter corresponds to second derivative of the restraint potential energy d2V(x)/dx^2 for any x (harmonic restraints) or only at at x=0 (other restraints). Here, x is a deviation from the restraint's optimal value.")
self.Rotamers: Conformers._Rotamers = self._Rotamers(name='Rotamers', comment='Options for the treatment of Grimme-rotamers.', hidden=True)
self.System: Conformers._System = self._System(name='System', comment='Specification of the chemical system. For some applications more than one system may be present in the input. In this case, all systems except one must have a non-empty string ID specified after the System keyword. The system without an ID is considered the main one.', unique=False, header=True, gui_type='Repeat at least once', shared_id='AMSSystem')