5. ACErxn Settings¶

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
Description:	Info about running an ACErxn PLAMS job

RestartDir

Type:	String
Default value:
Description:	Path to the folder containing the restart RKF files

Steps

Type:	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

BasicOptions

Type:	Block
Description:	General options

Python_Nproc

Type:	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

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
Description:	Keep the files of all AMS calculations in the plams_workdir folder

KeepAMSRunning

Type:	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

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

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).

Forbidden_Bonds

Type:	String
Default value:	N
Description:	Whether there are any pairs of atoms that should not form a bond.

IM_MaxMolecule

Type:	Integer
Default value:	10000
Description:	It is the number of constituent molecules in one intermediate state.

OMP_NUM_THREADS

Type:	Integer
Default value:	1
Description:	The number of cores that are used for DFTB or semi-empirical calculation for each molecule.

Python_Nproc

Type:	Integer
Default value:	1
Description:	The number of cores that are used for matrix enumeration and constructing a network.

SaveMoleculelist

Type:	String
Default value:	Y
Description:	It determines whether to save output file named Molecule_list

Supermolecule_charge

Type:	String
Default value:
Description:

TotalChargeMethod

Type:	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.

DistanceOptions

Type:	Block
Description:

BDE_scaling

Type:	Float
Default value:	0.01
Description:

GeomGenRelatedScreeningOptions

Type:	Block
Description:

ScreenChangedConnectivity

Type:	String
Default value:	Y
Description:	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
Default value:	N
Description:	Y: If a calculation (UFF, DFTB, semi-empirical) is terminated with an error, it will be screened. N: No screening

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
Description:	Keep the files of all AMS calculations in the plams_workdir folder

KeepAMSRunning

Type:	Bool
Default value:	Yes
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

Edge_Threshold

Type:	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)

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

GeomGenOptions

Type:	Block
Description:

rdkit_logging

Type:	Bool
Default value:	No
Description:	When the smilestrings are converted to coordinates using RDKit, logging can be switched on or off.

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 valye to 100. Generally, enumeration is terminated when no new intermediates are generated.

Module

Type:	String
Default value:	rdkit
Description:	RDKit is the only option

Onthefly_Screening

Type:	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.

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:

Ringsizes

Type:	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.

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

Use_Fragments

Type:	String
Default value:	Y
Description:	For now should always be Y, because it is currently not possible to bypass fragments

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:	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

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)

MatrixRelatedScreeningOptions

Type:	Block
Description:

AllowAldehyde

Type:	String
Default value:	Y
Description:	Determines wether aldehyde anions are acceptable intermediates

AllowCarbenes

Type:	String
Default value:	Y
Description:	Y: No screening N: If a carbene is in an intermediate state, the intermediate state will be screened.

AllowChargedAtoms

Type:	String
Default value:	Y
Description:	Y: No screening N: If an atom in a molecule has a charge, the intermediates state will be screened.

AllowChargedMolecules

Type:	String
Default value:	Y
Description:	Y: No screening N: If a molecule in an intermediate state has a charge, the intermediate state will be screened.

AllowRadicals

Type:	Integer
Default value:	-1
Description:	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
Default value:	Y
Description:	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
Default value:	N
Description:	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
Default value:	N
Description:	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
Default value:	N
Description:	If this is ‘Y’, every molecule in intermediate must contain a ring

Discard_OverCharge

Type:	String
Default value:	N
Description:	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
Default value:	N
Description:	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
Default value:	N
Description:	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
Default value:	100
Description:	It has an integer. It is the maximum number of counted electrons of metal (neutral counting)

MaxRingNumber

Type:	Integer
Default value:	-1
Description:	It can have an integer (0, 1, 2, …). Maximum number of rings in a molecule.

MaxTotalRingNumber

Type:	Integer
Default value:	100000
Description:	It can have an integer (0, 1, 2, …). Maximum number of rings in an intermediate states

MetalMaxCoordination

Type:	Integer
Default value:	-1
Description:	Restricts the maximal number of coordinations of transition metals.

MetalMinCoordination

Type:	Integer
Default value:	-1
Description:	Restricts the minimal number of coordinations of transition metals.

MinMetalElectronCount

Type:	Integer
Default value:	0
Description:	It has an integer. It is the minimum number of counted electrons of metal (neutral counting)

MinTotalRingNumber

Type:	Integer
Default value:	-1
Description:	It can have an integer (0, 1, 2, …). Minimum number of rings in an intermediate states

Miscellaneous

Type:	Block
Description:

GenerateQST2Input

Type:	String
Default value:	N
Description:

MoleculeSpecificMatrixScreeningOptions

Type:	Block
Description:	Molecule specific options that may be moved to System settings in future.

Elements_NoTerminus

Type:	Integer List
Default value:	[]
Description:

ForbiddenMetalElectronCount

Type:	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

LigandElectronCount

Type:	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) …

UserDefinedMaxV

Type:	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)

UserDefinedMinV

Type:	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’

NetworkCreation

Type:	Block
Description:	Options exclusively used for network creation (Step 2)

Mapping

Type:	Block
Description:	Options related to mapping to 3D (not sure why this happens in step 2)

FindDelocalizedBonds

Type:	String
Default value:	N
Description:

Screening

Type:	Block
Description:	Options related to the screening of intermediates

Cutoff_wrt_Reactant_Energy

Type:	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.

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.

RunInfo

Type:	Block
Description:	Info about running an ACErxn PLAMS job

RestartDir

Type:	String
Default value:
Description:	Path to the folder containing the restart RKF files

Steps

Type:	Integer List
Default value:	[1, 2, 3]
Description:	Which of the three steps to run

SpeciesNetOptions

Type:	Block
Description:

Bond_Pick

Type:	Float
Default value:	1.0
Description:

Reactant_Pick

Type:	Float
Default value:	1.0
Description:

Uniform_Pick

Type:	String
Default value:	Y
Description:

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.