1. Introduction to PyFrag

The PyFrag program is a ‘wrap-around’ for the Amsterdam Density Functional (ADF) package and facilitates the extension of the fragment analysis method implemented in ADF along an entire potential energy surfaces. The original version of PyFrag was developed by Willem-Jan van Zeist, Lando P. Wolters, F. Matthias Bickelhaupt, and Célia Fonseca Guerra at the Theoretical Chemistry department at Vrije Universiteit Amsterdam. The new PyFrag program was rewritten by Xiaobo Sun and Thomas Soini using the PLAMS library in the ADF package and has been included in the script collection in ADF 2017 and later version. Compared to the old PyFrag, the new version is more compact and easy to be maintained, expanded and upgraded. Also, due to its high compatibility with other python library tools developed by SCM, such as, PLAMS and QMworks, it can be used as a module in line with these computational chemistry job management tools to streamline a large flow of job. For more information about PLAMS and QMworks, the user can refer to PyFrag has been mainly used for research in the group of F. M. Bickelhaupt to enable a user-friendly analysis of reaction paths in terms of the Extended Activation Strain model of chemical reactivity(ASM). The following papers give an example how PyFrag can be used in real reaction path analysis[1]  and a review of how Activation Strain model can help to resolve diverse chemistry problems[2-4].  For anyone who are interested in the old version of PyFrag or try to report a bug or add more functions to the new version of PyFrag, please visit


[1] (101) W.-J. van Zeist, C. Fonseca Guerra, F. M. Bickelhaupt, J. Comput. Chem. 200829, 312-315.

[2] I. Fernandez, F. M. Bickelhaupt, Chem. Soc. Rev. 201443, 4953-4967.

[3] L. P. Wolters, F. M. Bickelhaupt, WIRES Comput. Mol. Sci. 20155, 324-343.

[4] F. M. Bickelhaupt, K. N. Houk Angew. Chem. 2017129, 10204-10221Angew. Chem. Int. Ed. 201756, 10070-10086



2. How to Run PyFrag

PyFrag is a program written in the highly transferable Python programming language. Running it on any given system should pose no problems, provided Python and the ADF package have been installed. PyFrag can be easily run on command line and constructs the necessary ADF jobs from it by reading input statements. By reading or constructing a series of geometry points, a series of ADF fragment-analysis calculations will be performed, the results of which are gathered in a neat text data file. To run PyFrag on command line is much like to run any other python code, you just simply put command like “startpython pyfrag_job_script”, in which startpython is a wrap-up python version in ADF. All related files generated by ADF will be saved in a working directory, automatically generated by PLAMS.

Preparation of input of PyFrag is easy. PyFrag input can be divided into two parts, as shown by an example below. One part is to set up basic parameters such as how to define two fragments and specify which data should be printed later, etc. A second part is just normal ADF input for a single point calculation. It is the user's own responsibility to set all the right ADF environment variables, so that ADF can run properly. In principle, nothing needs to be changed compared to running a single ADF job. To run it in cluster, for example, with a job management like “Slurm”, one can write a bash script to call PyFrag.


Command line example to run PyFrag:

startpython –-ircpath --fragment 2 --fragment 1 3 4 5 6 --strain 0 --strain -554.1 --bondlength 1 6 1.093 --angle 2 1 6 180 --VDD 2 1 6 --hirshfeld frag1 --irrepOI AA --orbitalenergy frag2 LUMO --adfinput basis.type=TZ2P –adfinputfile adfinputfile


Bash script example to run PyFrag:


#SBATCH -J pyfrag_input


#SBATCH -t 1:00:00

#SBATCH --partition=tc5

#SBATCH --output=%job.stdout

#SBATCH --error=%job.stderr


export NSCM=16



startpython PathtoPyfrag/  \

--name filename \

--ircpath PathtoMolecule/ \

--fragment 2 --fragment 1 3 4 5 6 --strain 0 --strain -554.1 \

--bondlength 1 6 1.093 \

--angle 2 1 6 180 \

--VDD 2 1 6 \

--hirshfeld frag1 \

--irrepOI AA \

--irrepOI AAA \

--orbitalenergy frag1 HOMO \

--orbitalenergy frag2 LUMO \

--orbitalenergy AA frag2 5 \

--population frag1 HOMO \

--population AA frag2 5 \

--overlap frag1 HOMO frag2 LUMO \

--overlap S frag1 5 AA frag2 4 \

--adfinput basis.type=TZ2P --adfinputfile PathtoADFfile/adfinputfile



3. Options and specifications

On a line, everything after a '#' will be ignored, allowing for comments in your inputfile. The data file pyfrag.txt by default will contain, as columns:

•    The filenames of the fragment analysis calculations, which are numbered for each step in the calculations. 
•    The total interaction energy (kcal/mol)
•    The Pauli repulsion (kcal/mol)
•    The Electrostatic interaction (kcal/mol)
•    The Orbital interaction (kcal/mol


Provide name for the directory, otherwise the directory will be named by PID.

•    --name  filename 


User can also rerun the same calculation to extract more information from the t21 files in the old job, as long as the right path is provided.

•     --restart   path to old job

for example:

•  --restart /Users/Desktop/plams.13018


Specify the filename of the LT or IRC output file you wish to analyze, both tape 21 and normal output files can be given. A tape 21 file should have a .t21 extension! Please make sure this is the case. You can specify two output files for an IRC t21 (backward and forward). A text file containing coordinates of an IRC calculation is also acceptable, for example, a text file generated by ADFmovie or Gaussian.

•    --ircpath   

•    --irct21  filename.t21

•     --lt  filename.t21


These following statements allow you to define the fragments in the analysis. For each of the fragments you supply a list of the numbers for the atoms as they exist on the LT or IRC file. The program will check if they match with the order as in the IRC or LT calculation file. It will print a statement in the error log if it thinks the order is wrong.

•   --fragment atomnrs

for example:

•  --fragment 2 --fragment 1 3 4 5 6


There are two ways to specify a parameter set for an ADF calculation.  Either one can directly set it or one can provide a file containing all information which can be used repeatedly. 

•   --adfinput adfparameter

•   –adfinputfile adfinputfile

for example:

•   --adfinput basis.type=TZ2P

•   –adfinputfile adfinputfile


The adfinputfile simply lists all parameters, ADF will need to do any type of calculation. It is similar to a normal ADF input except here all options are connected by “=”. One example file is shown as follows:








eprint.sfo=eig ovl


The following possibilities are optional. Users can choose what information to print after a PyFrag calculation. For instance, one can specify if the strain energy is to be printed for the fragments. Or one can specify the equilibrium energies (in kcal/mol) for the fragments. Beware that the order of this specification should correspond to the order of the fragment definition. This value will then simply be subtracted from the energy of the fragment in question. The program will print the individual strain values for each fragment, plus the total strain and total energy.


•   --strain fragenergy

for example:

•  --strain -301.01
•  --strain -19.02


To specify the bond length to be printed for each geometry step, just indicate the atom numbers as they appear in the input order of the total molecule. Specifying bond_diff as well subtracts this value from the actual bond length.

•  --bondlength  atomnr1 atomnr2 bond_diff


To specify the angle between atoms 1, 2 and 3 to be printed for each geometry step, just indicate the atom numbers as they appear in the input order of the total molecule. Specifying angle_diff as well subtracts this value from the actual angle.

•   --angle atomnr1 atomnr2 atomnr3 angle_diff


The following will print the Hirshfeld charges for the fragment. Note that the order of the fragments as used internally by ADF may differ from what you would expect. Note also that Hirshfeld charges as computed in a fragment analysis differ from those obtained in a ‘normal’ calculation from basic (spherical average-of configurations) ADF atoms like simple single point calculations.

•   -- hirshfeld frag1

The following prints the VDD charges on the atoms with numbers as given by atomnrs. Note also that VDD charges as computed in a fragment analysis differ from those obtained in a ‘normal’ calculation from basic (spherical average-of configurations) atoms like single point calculation.

•  -- VDD atomnrs

for example:

•  -- VDD 1 2

Through in the input below, the value of the orbital interaction energy will be printed for certain available irrep. The irrep symbol relates to the symmetry of the whole molecule.


•  -- irrepOI oi irrep

for example:

•  -- irrepOI AA


The statement below will print the overlap between orbital numbers orb1 on frag1 and orb2 on frag2 in irrep as they appear in the fragment analysis calculation. It can also print the overlap between the HOMO's of fragment one (frag1) and the LUMOs of fragment two (orbitals as found on the fragment calculations). If the orbitals found in this way differ in symmetry, an overlap value of zero is returned. It should be noted that irrep and orbital number refers to each fragment, rather than the whole molecule. Especially, when it comes to frozen core situation, the count of orbital number should not include core orbitals. This rule also applies to the situation of printing orbital energy and population for orbitals of certain fragment.


•   --overlap frag1 HOMO/LUMO frag2 HOMO/LUMO

•   --overlap irrep1 frag1 orb1 irrp2 frag2 orb2 

for example:

•  --overlap frag1 HOMO frag2 LUMO

•  --overlap S frag1 5 AA frag2 4


Through the input below, the orbital energy for a fragment orbital will be printed in available irrep.

•  -- orbitalenergy frag HOMO/LUMO

•  -- orbitalenergy irrep frag orb

for example:

•  -- orbitalenergy frag1 HOMO

•  -- orbitalenergy AA frag2 5


Through the input below, the Mulliken population for a fragment orbital will be printed in available irrep.


•  -- population frag HOMO/LUMO

•  -- population irrep frag orb

for example:

•  -- population frag1 HOMO

•  -- population AA frag2 5



© Bickelhaupt 1997-1999, 1999-2003, 2003-2014, 2014-2019