5. ACErxn Settings¶
ACErxn has a very large number of possible settings.
As usual in AMS applications, the settings can be provided in an input text file in AMS format,
or as PLAMS Settings object if the program is used as a Python library.
Generally the default values will do, and the settings don’t need to be specified. A few of the most commonly used keywords are selected below.
5.1. Common Keywords¶
The block RunInfo describes which of the three ACErxn steps (intermediate generation, network creation, network minimization) should be performed, and if appropriate, where the restart information can be found.
RunInfo
MinNumberOfShortestPathsWritten integer
RestartDir string
Steps [GenerateIntermediates | CreateNetwork | MinimizeNetwork | AnalyzeNetwork | All]
End
RunInfo- Type
Block
- Description
General run and file-Info on creating an ACErxn network
MinNumberOfShortestPathsWritten- Type
Integer
- Default value
5
- Description
The minimum number of shortest paths written to the shortest_paths.rkf file. Only relevant with Steps=All,Steps=MinimizeNetwork, or Steps=AnalyzeNetwork.
RestartDir- Type
String
- Default value
- GUI name
Restart directory
- Description
Path to the folder containing the restart RKF files
Steps- Type
Multiple Choice
- Default value
All
- Options
[GenerateIntermediates, CreateNetwork, MinimizeNetwork, AnalyzeNetwork, All]
- Description
Which of the three ACErxn steps to run ((1) GenerateIntermediates, (2) CreateNetwork, (3) MinimizeNetwork, (4) AnalyzeNetwork). The default is to run the first three.
In the block BasicOptions the key MaxJobs determines the number of parallel processes spawned in the parallelized parts of the program.
BasicOptions
MaxJobs integer
End
BasicOptions- Type
Block
- Description
General options
MaxJobs- Type
Integer
- Description
The number of parallel calculations (geometry optimizations, matrix enumerations, and network construction processes).
In the block InterrmediateGeneration the subblock AmsOptions specifies details about the calls to AMS (geometry optimizations), stating whether the AMS driver should keep running in the background (default), or if a new AMS process should be created for each geometry optimization. In addition it can be specified wether AMS output files should be kept or thrown away (default).
IntermediateGeneration
AmsOptions
KeepAMSFiles Yes/No
KeepAMSRunning Yes/No
End
End
IntermediateGeneration- Type
Block
- Description
Options used exclusively in intermediate generation (Step 1)
AmsOptions- Type
Block
- Description
Options related to engine calls
KeepAMSFiles- Type
Bool
- Default value
No
- GUI name
Keep AMS files
- Description
Keep the files of all AMS calculations in the plams_workdir folder
KeepAMSRunning- Type
Bool
- Default value
Yes
- GUI name
Keep AMS running
- Description
Keep the AMS driver running in the background during the geometry optimizations
By default the ACErxn code will never try to form or break bonds within a fragment in the intermediate generation process. There are many situation where the user may wish to override this, and this can be done with the keyword FormBondsWithinFragment in the block IntermediateGeneration.
IntermediateGeneration
FormBondsWithinFragment Yes/No
End
IntermediateGeneration- Type
Block
- Description
Options used exclusively in intermediate generation (Step 1)
FormBondsWithinFragment- Type
Bool
- Default value
No
- Description
By default, bond-formation or bond-breaking between all atoms within a fragment is excluded in intermediate generation. If this keyword is set to true, it is possible to form new bonds within a fragment (e.g. create a ring from a chain), and to break them again. The original fragment bonds will always remain in tact.
5.2. Summary of all keywords¶
BasicOptions- Type
Block
- Description
General options
AcceptSaturatedActiveAtoms- Type
Bool
- Default value
No
- Description
Accept atoms as active even if they are fully saturated in the minimal fragments. By default this is turned off.
Covalent_Radii_Coeff- Type
Float
- Default value
1.1
- Description
The criterion for if a bond exists between a pair of atom. Example: Let D_ij is distance between atom i and atom j, R_i is covalent radius of atom i and R_j is covalent radius of atom j, if D_ij <= (Covalent_Radii_Coeff) x (R_i + R_j): bond exists else: bond does not exist (Dalton Trans., 2008, 2832-2838).
IM_MaxMolecule- Type
Integer
- Default value
10000
- Description
It is the number of constituent molecules in one intermediate state.
MaxJobs- Type
Integer
- Description
The number of parallel calculations (geometry optimizations, matrix enumerations, and network construction processes).
NProc- Type
Integer
- Default value
1
- Description
The number of cores that are used for the QM geometry optimization for each molecule.
TotalChargeMethod- Type
Multiple Choice
- Default value
SumofFragments
- Options
[SumofFragments, Ionic]
- Description
If SumofFragments the charge of the intermediate (sum of submolecules) is determined by summing the charges of constituent fragments. If Ionic the charge of the molecule is determined using bond orders.
DistanceOptions- Type
Block
- Description
BDE_scaling- Type
Float
- Default value
0.01
- Description
Engine- Type
Block
- Recurring
True
- Description
The input for the computational engine used to compute energy and forces.
IntermediateGeneration- Type
Block
- Description
Options used exclusively in intermediate generation (Step 1)
AmsOptions- Type
Block
- Description
Options related to engine calls
KeepAMSFiles- Type
Bool
- Default value
No
- GUI name
Keep AMS files
- Description
Keep the files of all AMS calculations in the plams_workdir folder
KeepAMSRunning- Type
Bool
- Default value
Yes
- GUI name
Keep AMS running
- Description
Keep the AMS driver running in the background during the geometry optimizations
CompareCharge- Type
Bool
- Default value
No
- Description
When deciding if a molecule has already been computed/created, take into account the charge of the molecule
FormBondsWithinFragment- Type
Bool
- Default value
No
- Description
By default, bond-formation or bond-breaking between all atoms within a fragment is excluded in intermediate generation. If this keyword is set to true, it is possible to form new bonds within a fragment (e.g. create a ring from a chain), and to break them again. The original fragment bonds will always remain in tact.
GenXYZ_MaxCycle- Type
Integer
- Default value
2
- Description
The number of adjacency matrix (AC) -> 3D process attempts
GeometryGenerationOptions- Type
Block
- Description
RDKitLogging- Type
Bool
- Default value
No
- Description
When the smilestrings are converted to coordinates using RDKit, logging can be switched on or off.
MaxBondsBroken- Type
Integer
- Default value
2
- Description
When generating new intermediates Y from intermediate X, this is the maximum number of bonds that can be broken in X to form Y.
MaxBondsFormed- Type
Integer
- Default value
2
- Description
When generating new intermediates Y from intermediate X, this is the maximum number of bonds that can be formed to create Y from X.
MaxPropagation_Iteration- Type
Integer
- Default value
-1
- Description
The maximum number of iterations in the propagation of intermediates. If set to default value of -1, ACErxn internally sets the value to 100. Generally, enumeration is terminated when no new intermediates are generated.
PropagationMethod- Type
Multiple Choice
- Default value
Class
- Options
[Class, Function]
- Description
Uses either the novel BondOrderMatrixGenerator for propagation and geometry recovery, or the old function PropogationFromReactant
PruningOptions- Type
Block
- Description
Details of screening of intermediates in IntermediateGeneration. There are three screening moments: (1) During the propagation process, (2) After propagation but before geometry optimization, and (3) after geometry optimization. The screening options in this block are concerned with (1).
MaxRingSize- Type
Integer
- Default value
10000
- Description
If the newly generated intermediate (or molecule) contains a ring larger than the provided value, it is screened.
MinRingSize- Type
Integer
- Default value
3
- Description
If the newly generated intermediate (or molecule) contains a ring smaller than the provided value, it is screened.
ScreenAndOptimizeIntermediates- Type
Bool
- Default value
Yes
- Description
If set to True, the generated intermediates will be screened based on a large set of criteria, the remaining intermediates will be converted to 3D structures, and optimized. If set to False, this entire step will be skipped, and 3D geometries and energies are never obtained.
UsePlamsParallelization- Type
Bool
- Default value
Yes
- Description
Use the novel GeometryGenerator class to generate 3D geometries from molecule bond matrices
UseReactantGeometries- Type
Bool
- Default value
Yes
- Description
Use the geometries for the reactants as passed as input. If not true the reactant geometries will be generated from smiles. Only works in combination with PropagationMethod=class
MappingOptions- Type
Block
- Description
The options used for the chemical distance computations. Currently only used in step2, but in future will also be available in step1.
Digression_Factor- Type
Integer
- Default value
-100
- Description
It can have positive integer. It is delta in the expression for the maximum chemical distance of an intermediate form reactants and products
FullMapping- Type
Multiple Choice
- Default value
Net
- Options
[Net, Y, N]
- Description
Net: When calculating chemical distance, we only consider submolecules that change upon reaction. N: When calculating chemical distance, we only consider some parts of intermediate (based on the keyword Kthneighbor).
Kthneighbor- Type
Integer
- Default value
1
- Description
When calculating chemical distance with FullMapping=N, ACErxn only considers atoms that are k unit away from the active atoms. The distance between two atoms are defined as the graphical distance (length of shortest path between two atoms)
UseActiveBonds- Type
Bool
- Default value
Yes
- Description
During the mapping process (computing the chemical distance, assume only the active bonds can be broken or formed)
MoleculeSpecificMatrixScreeningOptions- Type
Block
- Description
Molecule specific options that may be moved to System settings in future.
Elements_NoTerminus- Type
String
- Recurring
True
- Description
The name of an element. In the intermediates, elements of this type need to be bonded to more than 1 other atom. This key can occur multiple times
ForbiddenMetalElectronCount- Type
Integer
- Recurring
True
- Description
It prevents the metal from having certain electron counts (neutral counting). Multiple values can be provided by repeating this key multiple times. Note: Refer http://www.columbia.edu/cu/chemistry/groups/parkin/mlxz.htm for the statistics of the electron count of each metal.
LigandElectronCount- Type
Integer
- Recurring
True
- Description
When a transition metal complex is included in the intermediates state a user has to specify the ligand electrons contributed when using the neutral counting method. The key needs to be present a multiple of 2 times (the first instance is the index of an atom and the second is the corresponding electron contribution).
RangeOfValences- Type
Block
- Recurring
True
- Description
The user can provide the maximum and minimum number of bonds an atom of a certain element can have. If not set, default values are used.
Element- Type
String
- Description
The element for which the maximum and/or minimum allowed number of bonds is set.
MaxNumberOfBonds- Type
Integer
- Description
The maximum number of bonds allowed for this element.
MinNumberOfBonds- Type
Integer
- Description
The minimum number of bonds allowed for this element.
NetworkCreation- Type
Block
- Description
Options exclusively used for network creation (Step 2)
FindDelocalizedBonds- Type
Bool
- Default value
No
- Description
Seems to write information on bond delocalization into the Intermediate objects before the network is created.
Screening- Type
Block
- Description
Options related to the screening of intermediates
CutoffWRTReactantEnergy- Type
Float
- Description
It determines how much higher energy the intermediate state can have than the state of the reactant. If GeomGenRelatedScreeningOptions%EnergyScreening is set to True, then this value is already used at intermediate generation. Unit is kcal/mol.
NetworkMinimization- Type
Block
- Description
Options exclusively used for network minimization (Step 3)
Barrier_cutoff- Type
Float
- Default value
0.0
- Description
Pathlength_cutoff- Type
Integer
- Default value
-1
- Description
If this value is positive, only those paths are collected whose lengths are less than or equal to the given value in step3.
YenKSP_K- Type
Integer
- Default value
1
- Description
For given value k, the kth shortest paths are extracted in the final step of ACErxn.
ReactantFragmentation- Type
Block
- Description
Details on how the reactant is split into smallest fragments, and how those are assigned charges and stabilities
DepthElectronegativitySearch- Type
Integer
- Default value
1
- Description
The atoms in the reactant molecules are assigned charges based on the connectivity of the molecule and the electronegativity of the atoms. By default the electronegativity is assigned simply based on the element, but if the depth is selected larger than 1, the electronegativity of neighboring atoms (up to depth-1) is included in determining the final electronegativity value of the atoms. For example, in a regular C-C bond, the electrons in the bond are distributed equally over the two atoms. But if DepthElectronegativitySearch is selected higher than 1, then breaking the C-C bond in ethanol will result in a negatively charged C-OH group and a carbocation.
RunInfo- Type
Block
- Description
General run and file-Info on creating an ACErxn network
MinNumberOfShortestPathsWritten- Type
Integer
- Default value
5
- Description
The minimum number of shortest paths written to the shortest_paths.rkf file. Only relevant with Steps=All,Steps=MinimizeNetwork, or Steps=AnalyzeNetwork.
RestartDir- Type
String
- Default value
- GUI name
Restart directory
- Description
Path to the folder containing the restart RKF files
Steps- Type
Multiple Choice
- Default value
All
- Options
[GenerateIntermediates, CreateNetwork, MinimizeNetwork, AnalyzeNetwork, All]
- Description
Which of the three ACErxn steps to run ((1) GenerateIntermediates, (2) CreateNetwork, (3) MinimizeNetwork, (4) AnalyzeNetwork). The default is to run the first three.
System- Type
Block
- Recurring
True
- Description
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.
AllowCloseAtoms- Type
Bool
- Default value
No
- Description
If AllowCloseAtoms is set to False, the AMS driver will stop with an error if it detects almost-coinciding atomic coordinates. If set to True, the AMS driver will try to carry on with the calculation.
Atoms- Type
Non-standard block
- Description
The atom types and coordinates. Unit can be specified in the header. Default unit is Angstrom.
BondOrders- Type
Non-standard block
- Description
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.
Charge- Type
Float
- Default value
0.0
- GUI name
Total charge
- Description
The system’s total charge in atomic units.
ElectrostaticEmbedding- Type
Block
- Description
Container for electrostatic embedding options, which can be combined.
ElectricField- Type
Float List
- Unit
V/Angstrom
- Description
External homogeneous electric field with three Cartesian components: ex, ey, ez, the default unit being V/Å. In atomic units: Hartree/(e bohr) = 14.39964 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.
MultipolePotential- Type
Block
- Description
External point charges (and dipoles).
ChargeModel- Type
Multiple Choice
- Default value
Point
- Options
[Point, Gaussian]
- Description
A multipole may be represented by a point (with a singular potential at its location) or by a spherical Gaussian distribution.
ChargeWidth- Type
Float
- Default value
-1.0
- Description
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.
Coordinates- Type
Non-standard block
- Description
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.
FractionalCoords- Type
Bool
- Default value
No
- Description
Whether the atomic coordinates in the Atoms block are given in fractional coordinates of the lattice vectors. Requires the presence of the Lattice block.
GeometryFile- Type
String
- Description
Read the geometry from a file (instead of from Atoms and Lattice blocks). Supported formats: .xyz
GuessBonds- Type
Bool
- Default value
No
- Description
Whether or not UFF bonds should be guessed.
Lattice- Type
Non-standard block
- Description
Up to three lattice vectors. Unit can be specified in the header. Default unit is Angstrom.
LatticeStrain- Type
Float List
- Description
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.
LoadForceFieldAtomTypes- Type
Block
- Description
This is a mechanism to set the ForceField.Type attribute in the input. This information is currently only used by the ForceField engine.
File- Type
String
- Description
Name of the (kf) file. It needs to be the result of a forcefield calculation.
LoadForceFieldCharges- Type
Block
- Recurring
True
- Description
This is a mechanism to set the ForceField.Charge attribute in the input. This information is currently only used by the ForceField engine.
CheckGeometryRMSD- Type
Bool
- Default value
No
- Description
Whether the geometry RMSD test should be performed, see MaxGeometryRMSD. Otherwise only basic tests are performed, such as number and atom types. Not doing the RMSD test allows you to load molecular charges in a periodic system.
File- Type
String
- Description
Name of the (kf) file
MaxGeometryRMSD- Type
Float
- Default value
0.1
- Unit
Angstrom
- Description
The geometry of the charge producing calculation is compared to the one of the region, and need to be the same within this tolerance.
Region- Type
String
- Default value
*
- Description
Region for which the charges should be loaded
Section- Type
String
- Default value
AMSResults
- Description
Section name of the kf file
Variable- Type
String
- Default value
Charges
- Description
Variable name of the kf file
MapAtomsToUnitCell- Type
Bool
- Default value
No
- Description
For periodic systems the atoms will be moved to the central cell.
ModifyAlternativeElements- Type
Bool
- Default value
No
- Description
When using alternative elements (using the nuclear_charge attribute) set the element to the nearest integer Z. If you specify an H atom with a nuclear_charge of 2.9 it is replaced by a Li atom with the same nuclear charge.
PerturbCoordinates- Type
Float
- Default value
0.0
- Unit
Angstrom
- Description
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).
PerturbLattice- Type
Float
- Default value
0.0
- Description
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.
RandomizeAtomOrder- Type
Bool
- Default value
No
- Description
Whether or not the order of the atoms should be randomly changed. Intended for some technical testing purposes only. Does not work with bond information.
Region- Type
Block
- Recurring
True
- Description
Properties for each region specified in the Atoms block.
Properties- Type
Non-standard block
- Description
Properties for each region specified in the Atoms block.
ShiftCoordinates- Type
Float List
- Unit
Bohr
- Description
Translate the atoms by the specified shift (three numbers).
SuperCell- Type
Integer List
- Description
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).
SuperCellTrafo- Type
Integer List
- Description
Create a supercell of the input system (only possible for periodic systems) \(\vec{a}_i' = \sum_j T_{ij} \vec{a}_j\). The integer numbers represent the supercell transformation \(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)).
Symmetrize- Type
Bool
- Default value
No
- Description
Whether to symmetrize the input structure. This might also rototranslate the structure into a standard orientation. This will symmetrize the atomic coordinates to machine precision. Useful if the system is almost symmetric or to rototranslate a symmetric molecule into a standard orientation.
Symmetry- Type
Multiple Choice
- Default value
AUTO
- Options
[AUTO, NOSYM, C(LIN), D(LIN), C(I), C(S), C(2), C(3), C(4), C(5), C(6), C(7), C(8), C(2V), C(3V), C(4V), C(5V), C(6V), C(7V), C(8V), C(2H), C(3H), C(4H), C(5H), C(6H), C(7H), C(8H), D(2), D(3), D(4), D(5), D(6), D(7), D(8), D(2D), D(3D), D(4D), D(5D), D(6D), D(7D), D(8D), D(2H), D(3H), D(4H), D(5H), D(6H), D(7H), D(8H), I, I(H), O, O(H), T, T(D), T(H), S(4), S(6), S(8)]
- Description
Use (sub)symmetry with this Schoenflies symbol. Can only be used for molecules. Orientation should be correct for the (sub)symmetry. If used icw Symmetrize, the symmetrization will not reorient the molecule.