# 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
RestartDir string
Steps integer_list
End

RunInfo
Type: Block Info about running an ACErxn PLAMS job
RestartDir
Type: String Path to the folder containing the restart RKF files
Steps
Type: Integer List [1, 2, 3] Which of the three steps to run

In the block BasicOptions the key Python_Nproc determines the number of parallel processes spawned in the parallelized parts of the program.

BasicOptions
Python_Nproc integer
End

BasicOptions
Type: Block General options
Python_Nproc
Type: Integer 1 The number of cores that are used for matrix enumeration and constructing a network.

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 Options used exclusively in intermediate generation (Step 1)
AmsOptions
Type: Block Options related to engine calls
KeepAMSFiles
Type: Bool No Keep the files of all AMS calculations in the plams_workdir folder
KeepAMSRunning
Type: Bool Yes 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 Options used exclusively in intermediate generation (Step 1)
FormBondsWithinFragment
Type: Bool No 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 General options
Covalent_Radii_Coeff
Type: Float 1.1 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).
Forbidden_Bonds
Type: String N Whether there are any pairs of atoms that should not form a bond.
IM_MaxMolecule
Type: Integer 10000 It is the number of constituent molecules in one intermediate state.
OMP_NUM_THREADS
Type: Integer 1 The number of cores that are used for DFTB or semi-empirical calculation for each molecule.
Python_Nproc
Type: Integer 1 The number of cores that are used for matrix enumeration and constructing a network.
SaveMoleculelist
Type: String Y It determines whether to save output file named Molecule_list
Supermolecule_charge
Type: String
TotalChargeMethod
Type: String SumofFragments It has two options: SumofFragments and Ionic if TotalChargeMethod == SumofFragments: It determines the charge of the molecule adding the charges of constituent fragments elif TotalChargeMethod == Ionic: It determines the charge of the molecule using bond orders.
DistanceOptions
Type: Block
BDE_scaling
Type: Float 0.01
GeomGenRelatedScreeningOptions
Type: Block
ScreenChangedConnectivity
Type: String Y Y: If the connecitvity of an molecule has been changed during the AC->3D process, it will be screened N: No screening. (FIXME: Perhaps it makes sense to make the default ‘Y’! If optimization changes connectivity, then the geometry of the intermediate created makes little sense.)
ScreenErrorTermination
Type: String N Y: If a calculation (UFF, DFTB, semi-empirical) is terminated with an error, it will be screened. N: No screening
IntermediateGeneration
Type: Block Options used exclusively in intermediate generation (Step 1)
AmsOptions
Type: Block Options related to engine calls
KeepAMSFiles
Type: Bool No Keep the files of all AMS calculations in the plams_workdir folder
KeepAMSRunning
Type: Bool Yes Keep the AMS driver running in the background during the geometry optimizations
CompareCharge
Type: Bool No When deciding if a molecule has already been computed/created, take into account the charge of the molecule
Edge_Threshold
Type: Integer List [2, 2] It is used to limit the number of broken and formed bonds. It can have one positive integer or two positive integers. (If it has two integers, each integer should be separated by a space)
FormBondsWithinFragment
Type: Bool No 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 2 The number of adjacency matrix (AC) -> 3D process attempts
GeomGenOptions
Type: Block
rdkit_logging
Type: Bool No When the smilestrings are converted to coordinates using RDKit, logging can be switched on or off.
MaxPropagation_Iteration
Type: Integer -1 The maximum number of iterations in the propagation of intermediates. If set to default value of -1, ACErxn internally sets the valye to 100. Generally, enumeration is terminated when no new intermediates are generated.
Module
Type: String rdkit RDKit is the only option
Onthefly_Screening
Type: String Y It can have either N or Y. N: No screening during the AC matrix enumeration step. Y: Doing the on-the-fly screening (or pruning) during the AC matrix step.
PropagationMethod
Type: Multiple Choice Class [Class, Function] Uses either the novel BondOrderMatrixGenerator for propagation and geometry recovery, or the old function PropogationFromReactant
PruningOptions
Type: Block
Ringsizes
Type: Integer List [3, 10000] Range of ringsize. If the intermediate (or molecule) that contains a ring with a size outside the given range, it is screened.
UsePlamsParallelization
Type: Bool Yes Use the novel GeometryGenerator class to generate 3D geometries from molecule bond matrices
UseReactantGeometries
Type: Bool Yes 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
Use_Fragments
Type: String Y For now should always be Y, because it is currently not possible to bypass fragments
MappingOptions
Type: Block 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 -100 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: String Net Net: When calculating chemical distance, we only consider molecules within intermediates that are not in common. N: When calculating chemical distance, we only consider some parts of intermediate. It is cooperated with Kth neighbor
Kthneighbor
Type: Integer 1 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 Yes During the mapping process (computing the chemical distance, assume only the active bonds can be broken or formed)
MatrixRelatedScreeningOptions
Type: Block
AllowAldehyde
Type: String Y Determines wether aldehyde anions are acceptable intermediates
AllowCarbenes
Type: String Y Y: No screening N: If a carbene is in an intermediate state, the intermediate state will be screened.
AllowChargedAtoms
Type: String Y Y: No screening N: If an atom in a molecule has a charge, the intermediates state will be screened.
AllowChargedMolecules
Type: String Y Y: No screening N: If a molecule in an intermediate state has a charge, the intermediate state will be screened.
AllowRadicals
Type: Integer -1 If the value is positive, it also allows radical species during enumeration. It counts the number of radicals and if the number exceeds the AllowRadical value, the intermediate is screened.
ChargeConservation
Type: String Y If Y, charge conservation is considered during screening. Here, it screens out intermediates with a charge unequal to sum of formal charges of atoms.
CheckElectronegativity
Type: String N Y: If an atoms has positive charge to more electronegative atom, the intermediate state will be screened. (except carbon monoxide) N: No screening
Digression_Screening
Type: String N If this is ‘Y’, ACErxn applies digression screening (screening based on the chamical distance of an intermediate from reactant and product) for screening (in step2) and when enumerating intermediates (in step1)
Discard_Acyclic
Type: String N If this is ‘Y’, every molecule in intermediate must contain a ring
Discard_OverCharge
Type: String N Y: If a formal charge for an atom in a molecule is smaller than -2 or bigger than +2, it will be screened. N: No screening.
Discard_OverTotalCharge
Type: String N Y: If the total charge for an molecule in a intermediate state is smaller than -2 or bigger than +2, it will be screened. N: No screening.
Energy_Screening
Type: String N If this is ‘Y’, ACErxn applies energy screening (screening based on the relative energy of an intermediate to the reactant) for screening (in step2) when enumerating intermediates (in step1).
MaxMetalElectronCount
Type: Integer 100 It has an integer. It is the maximum number of counted electrons of metal (neutral counting)
MaxRingNumber
Type: Integer -1 It can have an integer (0, 1, 2, …). Maximum number of rings in a molecule.
MaxTotalRingNumber
Type: Integer 100000 It can have an integer (0, 1, 2, …). Maximum number of rings in an intermediate states
MetalMaxCoordination
Type: Integer -1 Restricts the maximal number of coordinations of transition metals.
MetalMinCoordination
Type: Integer -1 Restricts the minimal number of coordinations of transition metals.
MinMetalElectronCount
Type: Integer 0 It has an integer. It is the minimum number of counted electrons of metal (neutral counting)
MinTotalRingNumber
Type: Integer -1 It can have an integer (0, 1, 2, …). Minimum number of rings in an intermediate states
Miscellaneous
Type: Block
GenerateQST2Input
Type: String N
MoleculeSpecificMatrixScreeningOptions
Type: Block Molecule specific options that may be moved to System settings in future.
Elements_NoTerminus
Type: Integer List []
ForbiddenMetalElectronCount
Type: Integer List [] It can have a series of integers. It prevents the metal from having a specific electron counts (neutral counting). Note: Refer http://www.columbia.edu/cu/chemistry/groups/parkin/mlxz.htm. The statistics of the electron count of each metal are shown here
LigandElectronCount
Type: Integer List [] It is for the case when the transition metal complex is included in the intermediates state. A user have to specify the ligand electrons contributed when using neutral counting method. It is a series of integers. It has a following formation. (index of atom A in Reactants xyz file) (electron contribution of atom A) (index of Atom B in Reactants xyz file) (electron contribution of atom B) …
UserDefinedMaxV
Type: Integer List [] Formation is the same with UserDefinedMinV. (Type of atom A) (max number of bonds A has) (Type of Atom B) (max number of bonds B has)
UserDefinedMinV
Type: Integer List [] It has a following formation. (Type of atom A) (min number of bonds A has) (Type of Atom B) (min number of bonds B has). Example: ‘O 2 C 3’
NetworkCreation
Type: Block Options exclusively used for network creation (Step 2)
Mapping
Type: Block Options related to mapping to 3D (not sure why this happens in step 2)
FindDelocalizedBonds
Type: String N
Screening
Type: Block Options related to the screening of intermediates
Cutoff_wrt_Reactant_Energy
Type: String It determines how much higher energy the intermediate state can have than the state of the reactant. Unit is kcal/mol.
NetworkMinimization
Type: Block Options exclusively used for network minimization (Step 3)
Barrier_cutoff
Type: Float 0.0
Pathlength_cutoff
Type: Integer -1 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 1 For given value k, the kth shortest paths are extracted in the final step of ACErxn.
RunInfo
Type: Block Info about running an ACErxn PLAMS job
RestartDir
Type: String Path to the folder containing the restart RKF files
Steps
Type: Integer List [1, 2, 3] Which of the three steps to run
SpeciesNetOptions
Type: Block
Bond_Pick
Type: Float 1.0
Reactant_Pick
Type: Float 1.0
Uniform_Pick
Type: String Y
System
Type: Block True 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 No 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 The atom types and coordinates. Unit can be specified in the header. Default unit is Angstrom.
BondOrders
Type: Non-standard block 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 0.0 Total charge The system’s total charge in atomic units.
ElectrostaticEmbedding
Type: Block Container for electrostatic embedding options, which can be combined.
ElectricField
Type: Float List V/Angstrom 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 External point charges (and dipoles).
ChargeModel
Type: Multiple Choice Point [Point, Gaussian] A multipole may be represented by a point (with a singular potential at its location) or by a spherical Gaussian distribution.
ChargeWidth
Type: Float -1.0 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 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 No 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 Read the geometry from a file (instead of from Atoms and Lattice blocks). Supported formats: .xyz
GuessBonds
Type: Bool No Whether or not UFF bonds should be guessed.
Lattice
Type: Non-standard block Up to three lattice vectors. Unit can be specified in the header. Default unit is Angstrom.
LatticeStrain
Type: Float List 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 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 Name of the (kf) file. It needs to be the result of a forcefield calculation.
LoadForceFieldCharges
Type: Block True 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 No 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 Name of the (kf) file
MaxGeometryRMSD
Type: Float 0.1 Angstrom 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 * Region for which the charges should be loaded
Section
Type: String AMSResults Section name of the kf file
Variable
Type: String Charges Variable name of the kf file
MapAtomsToUnitCell
Type: Bool No For periodic systems the atoms will be moved to the central cell.
ModifyAlternativeElements
Type: Bool No 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 0.0 Angstrom 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 0.0 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 No 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 True Properties for each region specified in the Atoms block.
Properties
Type: Non-standard block Properties for each region specified in the Atoms block.
ShiftCoordinates
Type: Float List Bohr Translate the atoms by the specified shift (three numbers).
SuperCell
Type: Integer List 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 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 No 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 AUTO [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)] 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.