This is a short manual on how to use the EGHrun program.
The EGH stands for Energy Gradient Hessian. This program is intended for massively parallel numerical calculations of the indicated properties of PES provided by quantum chemistry programs.
The source code is available at the bitbucket.org. In order to download repository you should be included in the list of developers.
The program gets geometry and the template script which runs the desired external software to calculate energy. EGHrun generates required displacements and creates a list of tasks for the specified calculations. Using MPI-based parallelization, the program spreads the tasks between nodes and processors and collects results.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
usage: EGHrun.py [-h] -g XYZ_FILE MOL_FILE -rs SCRIPT_FILE -tdir TMP_PATH [-EGH_out [EGH_OUT]] [-run_out [RUN_OUT]] [--calc_grad] [--calc_hess] [--z_sym] [-incr INCR] [--print_script_out] optional arguments: -h, --help show this help message and exit required arguments: -g XYZ_FILE MOL_FILE Path to geometry files. -rs SCRIPT_FILE Path to script template. -tdir TMP_PATH Temporary root directory. optional arguments: -EGH_out [EGH_OUT] EGH output file. (default: print to stdout) -run_out [RUN_OUT] Run script output file. (default: output.out) --calc_grad Calculate gradients. --calc_hess Calculate hessians. --z_sym Indicate that molecule has z symmetry. -incr INCR Incriment for geometry displacements. (default: 1.e-3) --print_script_out Print output produced by script (if any). |
In order to launch parallel version of the EGHrun program, MPI software should be installed. A particular way to execute MPI programs can vary for different MPI packages and depends also on the machine itself. In general,
1 |
srun python EGHrun.py ... |
command should work well. Python version 3.6+ is required for execution of the program.
Calculation of gradients requires runs of the script file. Hessian will take runs. Therefore, a large computational resources can be required to perform calculations of molecules containing many atoms.
If the molecule of interest has planar symmetry, it should be oriented in z direction. The input flag --z_sym indicates to use the symmetry which can reduce number of required calculations.
Geometry files
The EGHrun program reads geometry from two input files: XYZ_FILE and MOL_FILE.
The XYZ file specifies the molecule geometry by giving the number of atoms with Cartesian coordinates that will be read on the first line, a comment on the second, and the lines of atomic coordinates in the following lines. Atomic coordinates are in ångströms.
As an example here we present the content of XYZ file for the propiolic acid molecule.
1 2 3 4 5 6 7 8 9 |
7 comment line C 0.0000000000 0.4933010000 0.0000000000 C -0.2834320000 -0.9672660000 0.0000000000 C -0.5742820000 -2.1399970000 0.0000000000 O 1.4085850000 0.7153070000 0.0000000000 O -0.8432820000 1.4260230000 0.0000000000 H -0.8301210000 -3.1916200000 0.0000000000 H 1.4539890000 1.7447600000 0.0000000000 |
The MOL file specifies atomic numbers and atomic masses of atoms. The first column must contain the same atomic labels as specified in XYZ file. Second and third columns contain atomic numbers and atomic masses, respectively.
1 2 3 4 5 6 7 |
C 6.0 12.011 C 6.0 12.011 C 6.0 12.011 O 8.0 15.9994 O 8.0 15.9994 H 1.0 1.00782504 H 1.0 1.00782504 |
Template script for external program
EGHrun uses an external quantum chemistry program to provide an energy which then will be used for evaluation of the gradient and Hessian. The script file which runs the desired external program should be provided by user. All parameters of the electronic structure calculations such as method, basis, active space etc. should be specified in this file. However, there are several variables which should be used in the input script to incorporate data generated by EGHrun program.
The molecular geometry must be specified using the following template format.
1 2 3 |
$geometry{ %X %Y %Z %AN %AL %AM }; |
In the required place of the input script user should insert $geometry{...} section with template line specifying the order of requested variables. The following template variables are available: %X, %Y, %Z – Cartesian coordinates of atoms in a molecule in ångströms, %AN – atomic number, %AL – atomic label, %AM – atomic mass. They can be used all or partially in the desired order depending on the format required by the quantum chemistry package.
The template variable %TMP_DIR can be used to specify temporary variable where the calculations will be performed.
The script must produce the output file specified by %RUN_OUT variable which contains energy of the state of interest in the following format.
1 2 |
$energy ... [single number in Hartree] |
Here we present simple example of SCRIPT_FILE which performs MP2 calculations of the ground electronic energy by gamess-uk package.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
#!/bin/bash #create temporary directory mkdir -p %TMP_DIR cd %TMP_DIR #perform SCF MP2 calculations; write output to gamess.out file gamess << EOF > gamess.out charge 0 geometry angstroms $geometry{ %X %Y %Z %AN %AL }; end BASIS 6-31G SCFTYPE MP2 EOF #search mp2 energy in gamess.out file mp2=`cat gamess.out | grep "total energy (mp2)" | awk '{print $4}'` #print energy output file cat <<- EOF > %RUN_OUT \$energy $mp2 EOF |
Output of EGHrun program
The program by default performs calculations only for the reference geometry. The energy output is in Hartree units. Additional flags --calc_grad and --calc_hess should be requested to calculate gradient and Hessian, respectively. The calculated gradient and Hessian are printed in Hartree/bohr and Hartree/bohr units.