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
RunInfoType: Block Description: Info about running an ACErxn PLAMS job RestartDirType: String Default value: Description: Path to the folder containing the restart RKF files StepsType: Integer List Default value: [1, 2, 3] Description: 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
BasicOptionsType: Block Description: General options Python_NprocType: Integer Default value: 1 Description: 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
IntermediateGenerationType: Block Description: Options used exclusively in intermediate generation (Step 1) AmsOptionsType: Block Description: Options related to engine calls KeepAMSFilesType: Bool Default value: No Description: Keep the files of all AMS calculations in the plams_workdir folder KeepAMSRunningType: Bool Default value: Yes 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
IntermediateGenerationType: Block Description: Options used exclusively in intermediate generation (Step 1) FormBondsWithinFragmentType: 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¶
BasicOptionsType: Block Description: General options Covalent_Radii_CoeffType: 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). Forbidden_BondsType: String Default value: N Description: Whether there are any pairs of atoms that should not form a bond. IM_MaxMoleculeType: Integer Default value: 10000 Description: It is the number of constituent molecules in one intermediate state. OMP_NUM_THREADSType: Integer Default value: 1 Description: The number of cores that are used for DFTB or semi-empirical calculation for each molecule. Python_NprocType: Integer Default value: 1 Description: The number of cores that are used for matrix enumeration and constructing a network. SaveMoleculelistType: String Default value: Y Description: It determines whether to save output file named Molecule_list Supermolecule_chargeType: String Default value: Description: TotalChargeMethodType: String Default value: SumofFragments Description: 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.
DistanceOptionsType: Block Description: BDE_scalingType: Float Default value: 0.01 Description:
IntermediateGenerationType: Block Description: Options used exclusively in intermediate generation (Step 1) AmsOptionsType: Block Description: Options related to engine calls KeepAMSFilesType: Bool Default value: No Description: Keep the files of all AMS calculations in the plams_workdir folder KeepAMSRunningType: Bool Default value: Yes Description: Keep the AMS driver running in the background during the geometry optimizations
CompareChargeType: Bool Default value: No Description: When deciding if a molecule has already been computed/created, take into account the charge of the molecule Edge_ThresholdType: Integer List Default value: [2, 2] Description: 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) FormBondsWithinFragmentType: 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_MaxCycleType: Integer Default value: 2 Description: The number of adjacency matrix (AC) -> 3D process attempts GeomGenOptionsType: Block Description: rdkit_loggingType: Bool Default value: No Description: When the smilestrings are converted to coordinates using RDKit, logging can be switched on or off.
MaxPropagation_IterationType: 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 valye to 100. Generally, enumeration is terminated when no new intermediates are generated. ModuleType: String Default value: rdkit Description: RDKit is the only option Onthefly_ScreeningType: String Default value: Y Description: 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. PropagationMethodType: Multiple Choice Default value: Class Options: [Class, Function] Description: Uses either the novel BondOrderMatrixGenerator for propagation and geometry recovery, or the old function PropogationFromReactant PruningOptionsType: Block Description: RingsizesType: Integer List Default value: [3, 10000] Description: Range of ringsize. If the intermediate (or molecule) that contains a ring with a size outside the given range, it is screened.
UsePlamsParallelizationType: Bool Default value: Yes Description: Use the novel GeometryGenerator class to generate 3D geometries from molecule bond matrices UseReactantGeometriesType: 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 Use_FragmentsType: String Default value: Y Description: For now should always be Y, because it is currently not possible to bypass fragments
MappingOptionsType: 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_FactorType: 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 FullMappingType: String Default value: Net Description: 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 KthneighborType: 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) UseActiveBondsType: Bool Default value: Yes Description: During the mapping process (computing the chemical distance, assume only the active bonds can be broken or formed)
MiscellaneousType: Block Description: GenerateQST2InputType: String Default value: N Description:
MoleculeSpecificMatrixScreeningOptionsType: Block Description: Molecule specific options that may be moved to System settings in future. Elements_NoTerminusType: Integer List Default value: [] Description: ForbiddenMetalElectronCountType: Integer List Default value: [] Description: 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 LigandElectronCountType: Integer List Default value: [] Description: 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) … UserDefinedMaxVType: Integer List Default value: [] Description: 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) UserDefinedMinVType: Integer List Default value: [] Description: 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’
NetworkCreationType: Block Description: Options exclusively used for network creation (Step 2) MappingType: Block Description: Options related to mapping to 3D (not sure why this happens in step 2) FindDelocalizedBondsType: String Default value: N Description:
ScreeningType: Block Description: Options related to the screening of intermediates Cutoff_wrt_Reactant_EnergyType: String Default value: Description: It determines how much higher energy the intermediate state can have than the state of the reactant. Unit is kcal/mol.
NetworkMinimizationType: Block Description: Options exclusively used for network minimization (Step 3) Barrier_cutoffType: Float Default value: 0.0 Description: Pathlength_cutoffType: 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_KType: Integer Default value: 1 Description: For given value k, the kth shortest paths are extracted in the final step of ACErxn.
RunInfoType: Block Description: Info about running an ACErxn PLAMS job RestartDirType: String Default value: Description: Path to the folder containing the restart RKF files StepsType: Integer List Default value: [1, 2, 3] Description: Which of the three steps to run
SpeciesNetOptionsType: Block Description: Bond_PickType: Float Default value: 1.0 Description: Reactant_PickType: Float Default value: 1.0 Description: Uniform_PickType: String Default value: Y Description:
SystemType: 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. AllowCloseAtomsType: 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. AtomsType: Non-standard block Description: The atom types and coordinates. Unit can be specified in the header. Default unit is Angstrom. BondOrdersType: 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. ChargeType: Float Default value: 0.0 GUI name: Total charge Description: The system’s total charge in atomic units. ElectrostaticEmbeddingType: Block Description: Container for electrostatic embedding options, which can be combined. ElectricFieldType: 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. MultipolePotentialType: Block Description: External point charges (and dipoles). ChargeModelType: 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. ChargeWidthType: 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. CoordinatesType: 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.
FractionalCoordsType: 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. GeometryFileType: String Description: Read the geometry from a file (instead of from Atoms and Lattice blocks). Supported formats: .xyz GuessBondsType: Bool Default value: No Description: Whether or not UFF bonds should be guessed. LatticeType: Non-standard block Description: Up to three lattice vectors. Unit can be specified in the header. Default unit is Angstrom. LatticeStrainType: 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. LoadForceFieldAtomTypesType: 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. FileType: String Description: Name of the (kf) file. It needs to be the result of a forcefield calculation.
LoadForceFieldChargesType: 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. CheckGeometryRMSDType: 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. FileType: String Description: Name of the (kf) file MaxGeometryRMSDType: 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. RegionType: String Default value: * Description: Region for which the charges should be loaded SectionType: String Default value: AMSResults Description: Section name of the kf file VariableType: String Default value: Charges Description: Variable name of the kf file
MapAtomsToUnitCellType: Bool Default value: No Description: For periodic systems the atoms will be moved to the central cell. ModifyAlternativeElementsType: 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. PerturbCoordinatesType: 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). PerturbLatticeType: 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. RandomizeAtomOrderType: 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. RegionType: Block Recurring: True Description: Properties for each region specified in the Atoms block. PropertiesType: Non-standard block Description: Properties for each region specified in the Atoms block.
ShiftCoordinatesType: Float List Unit: Bohr Description: Translate the atoms by the specified shift (three numbers). SuperCellType: 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). SuperCellTrafoType: 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)). SymmetrizeType: 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. SymmetryType: 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.