Tutorial: Generate structures for substituent effects screeningΒΆ


Screening substituent patterns of a base compound is a common task in computer aided materials design. In the following short tutorial we demonstrate how you can use adfprep to automatize the replacement of substituents with just a few lines of simple shell scripting.



  • The library of substituents in ADFinput
  • Exchanging substituents with ADFprep
  • Combining ADFprep and ADFreport in shell script

The substituent library in ADFinput

ADFinput comes with a customizable library of common substituents that we can use for our screening purposes right away. It can be accessed via the structure builder tool in ADFinput:


Note how the entries are organized. For example the isocyanide functional group (“NC”) can be found in “Ligands”.

Its also possible to add your own compounds: Simply draw the structure of interest and select the atom which will serve as an anchor.

This is how you would add a carboxylic acid group:


ADFinput will always consider the atom that lies in the origin of the coordinate system to be the anchor. If you use the Save As Structure command this will be done for you. More information, including another example, can be found in the Building Molecules GUI tutorial.

Exchanging substituents with adfprep

Let us consider a simple benzene ring as the base compound:


The adfprep command to exchange Hydrogen atom #12 with an isocyanide group (“NC”) and create a runfile for a UFF geometry optimization is:

"$ADFBIN/adfprep" -t UFF-GO -m benzene.xyz -structure "12 Ligands/NC.adf" > "benzene_NC.run"

Remember that the “CN” group was located in the “Ligands” menu hence “Ligands/NC.adf”. In case the path contains whitespace, you need to escape the whitespace as in this example

"$ADFBIN/adfprep" -t UFF-GO -m benzene.xyz -structure "12 Alkyl\ Chains/Ethyl.adf" > "ethyl_benzene.run"

When using custom substituents, e.g. the hydroxylic_acid in the above example, a full path need to be provided to adfprep. The path is displayed when clicking on the Structure Tool in ADFinput and selecting “Manage your structures”. On an ubuntu linux system the path is “/home/[your_username]/.scm_gui/Structures” and the command to use your own structures becomes:

"$ADFBIN/adfprep" -t UFF-GO -m benzene.xyz -structure "12 /home/[your_username]/.scm_gui/Structures/carboxylic_acid.adf" > "benzoic_acid.run"

Bringing it all together

The following few lines of shell script demonstrate how to automatically exchange the substituents on a benzene ring, run a UFF optimization on the new structure and extract the optimized geometry with adfreport.

#! /bin/sh
# copy the file benzene.xyz from the ADF compounds database
cp "$ADFHOME/atomicdata/Molecules/ADF/Benzene.xyz" .
# loop through different substituents
for ligand in CN CO CO3 NC NH2 NH2CH3 NH3 OC OCH3 OH PH3 Pyridine; do
   # prepare the coordinates and the UFF calculation
   "$ADFBIN/adfprep" -t UFF-GO -m Benzene.xyz -structure "12 Ligands/$ligand.adf" > "benzene_$ligand.run"
   # run UFF GeoOpt
   sh "./benzene_$ligand.run"
   # extract the optimized geometry via adfreport
   "$ADFBIN/adfreport" uff.rkf SDF > "benzene_$ligand.mol"
   # rename the generic UFF output file
   mv uff.rkf "benzene_$ligand.rkf"

Running the script

Linux and Mac: Copy and paste the above into a file called substituents_script and execute it in the command line

sh substituents_script

Windows: Just use the pre-configured shell, adf_command_line.bat ,shipped with ADF to run the same command as the Linux and Mac users.