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]
UseAllIntermediatesForPaths Yes/No
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.
UseAllIntermediatesForPaths- Type:
Bool
- Default value:
Yes
- Description:
If set (default), if two paths are found with the same chemical distance, then only the one including the most intermediates will be kept.
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).
MinimumBondOrder- Type:
Float
- Default value:
0.3
- Description:
The minimum bond order to be considered a bond
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.
UseAllIntermediatesForPaths- Type:
Bool
- Default value:
Yes
- Description:
If set (default), if two paths are found with the same chemical distance, then only the one including the most intermediates will be kept.
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) = 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.
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.