Prelude 1: Setting your general.py and adsorbate.py scripts

The Adsorber program reads in five input scripts that tell the program how to make the files required to study the adsorption of adsorbates on surfaces and clusters. Theses are:

  • general.py: Contains general settings required for all parts of running this program.

  • adsorbate.py: Contains information about the types and configurations of adsorbates.

  • partA.py: Contains settings regarding Part A.

  • partB.py: Contains settings regarding Part B.

  • partC.py: Contains settings regarding Part C.

In this page we will talk about how to set up the general.py and adsorbate.py scripts.

Setting your general.py scripts

We will explain what inputs need to be given in the general.py script by using the example shown below:

general.py
 1# ----------------------------------------------------------------------------------------------------------------
 2# General Information
 3# ----------------------------------------------------------------------------------------------------------------
 4# ----------------------------------------------------------------------------------------------------------------
 5# Initial inputs for the Adsorber program
 6cluster_or_surface_model = 'cluster'
 7
 8# Information about the surface/cluster
 9system_filename = '15-3-3629.xyz'
10add_vacuum = 6.0
11# ----------------------------------------------------------------------------------------------------------------

The following input variables are required in the general.py script:

  • cluster_or_surface_model (str.): This tells Adsorber if you are wanting to adsorb atoms and clusters to the surface of a cluster or a surface model.

    • If you are dealing with a cluster, set cluster_or_surface_model = 'cluster',

    • f you are dealing with a surface model, set cluster_or_surface_model = 'surface model' and make sure that your surface and vacuum point in the positive z direction. Adsorber will only attach adsorbates to surfaces from the positive z direction.

  • system_filename (str.): The name of the file of the cluster or the surface model that you will like to import into Adsorber. This file should be a .xyz or .traj file, but in reality any file type will do that ASE can read (see https://wiki.fysik.dtu.dk/ase/ase/io/io.html for more information on formats that ASE can read). For surfaces, you should have already performed surface convergence studies before proceeding with part A. If you want to constrain any atoms in your model, this should be done in this xyz/traj file.

  • add_vacuum (optional, float): This will add a vacuum around your cluster. This is optional, if you do not give this in your general.py script, your input will be left untouched.

Setting your adsorbate.py scripts

We will explain what inputs need to be given in the adsorbate.py script by using the example shown below:

adsorbates.py
  1# ----------------------------------------------------------------------------------------------------------------
  2# Give the Atoms objects for the atoms and molecules you want to adsorb to your cluster or surface model
  3from ase.build import molecule
  4
  5adsorbed_species = []
  6
  7COOH_symmetric = molecule('HCOOH') # note the carbon is index 1
  8COOH_symmetric.center(vacuum=10.0)
  9del COOH_symmetric[4] # remove the hydrogen atom
 10COOH_symmetric_axis = (0.1,-1,0)
 11distance_of_adatom_from_surface = 1.5
 12rotations = 'automatic' #range(0,360,10)
 13COOH_symmetric_adsorbed_species = {'name': 'COOH_symmetric', 'molecule': COOH_symmetric, 'distance_of_adatom_from_surface': distance_of_adatom_from_surface, 'index': 1, 'axis': COOH_symmetric_axis, 'rotations': rotations, 'sites_to_bind_adsorbate_to': ['Top_Sites','Bridge_Sites','Three_Fold_Sites']}
 14adsorbed_species.append(COOH_symmetric_adsorbed_species)
 15
 16COOH_O_tilted = molecule('HCOOH') # note the carbon is index 1
 17COOH_O_tilted.center(vacuum=10.0)
 18del COOH_O_tilted[4] # remove the hydrogen atom
 19COOH_O_tilted_axis = (-0.4,-1,0)
 20distance_of_adatom_from_surface = 1.5
 21rotations = 'automatic' #range(0,360,10)
 22#COOH_O_tilted_adsorbed_species = {'name': 'COOH_O_tilted', 'molecule': COOH_O_tilted, 'distance_of_adatom_from_surface': distance_of_adatom_from_surface, 'index': 1, 'axis': COOH_O_tilted_axis, 'rotations': rotations, 'sites_to_bind_adsorbate_to': 'Top_Sites'}
 23COOH_O_tilted_adsorbed_species = {'name': 'COOH_O_tilted', 'molecule': COOH_O_tilted, 'distance_of_adatom_from_surface': distance_of_adatom_from_surface, 'index': 1, 'axis': COOH_O_tilted_axis, 'rotations': rotations}
 24adsorbed_species.append(COOH_O_tilted_adsorbed_species)
 25
 26CO = molecule('CO') # note the carbon is index 1
 27CO.center(vacuum=10.0)
 28CO_axis = 'z'
 29distance_of_adatom_from_surface = 1.5
 30CO_adsorbed_species = {'name': 'CO', 'molecule': CO, 'distance_of_adatom_from_surface': distance_of_adatom_from_surface, 'index': 1, 'axis': CO_axis}
 31adsorbed_species.append(CO_adsorbed_species)
 32
 33# --------------------------------------------
 34# option1
 35COH = molecule('H2COH') # note the carbon is index 0
 36COH.center(vacuum=10.0)
 37del COH[4] # remove the hydrogen atom
 38del COH[3] # remove the hydrogen atom
 39COH_axis = '-x'
 40distance_of_adatom_from_surface = 1.5
 41rotations = 'automatic' #range(0,360,10)
 42COH_adsorbed_species = {'name': 'COH', 'molecule': COH, 'distance_of_adatom_from_surface': distance_of_adatom_from_surface, 'index': 0, 'axis': COH_axis, 'rotations': rotations}
 43adsorbed_species.append(COH_adsorbed_species)
 44
 45#option2
 46CHO = molecule('HCO') # note the carbon is index 0
 47CHO.center(vacuum=10.0)
 48CHO_axis = (-(3.0**0.5)/2.0,-1.0/2.0,0)
 49distance_of_adatom_from_surface = 2.5
 50rotations = 'automatic' #range(0,360,10)
 51CHO_adsorbed_species = {'name': 'CHO', 'molecule': CHO, 'distance_of_adatom_from_surface': distance_of_adatom_from_surface, 'index': 0, 'axis': CHO_axis, 'rotations': rotations}
 52adsorbed_species.append(CHO_adsorbed_species)
 53# --------------------------------------------
 54# option1
 55CH2O = molecule('H2CO') # note the carbon is index 1
 56CH2O.center(vacuum=10.0)
 57CH2O_axis = 'x'
 58distance_of_adatom_from_surface = 1.5
 59rotations = 'automatic' #range(0,360,10)
 60CH2O_adsorbed_species = {'name': 'CH2O', 'molecule': CH2O, 'distance_of_adatom_from_surface': distance_of_adatom_from_surface, 'index': 1, 'axis': CH2O_axis, 'rotations': rotations}
 61adsorbed_species.append(CH2O_adsorbed_species)
 62
 63# option1
 64CHOH = molecule('H2COH') # note the carbon is index 0
 65CHOH.center(vacuum=10.0)
 66del CHOH[3]
 67CHOH_axis = (-1,-1,0)
 68distance_of_adatom_from_surface = 1.5
 69rotations = range(0,360,90) #'automatic' #range(0,360,10)
 70CHOH_adsorbed_species = {'name': 'CHOH', 'molecule': CHOH, 'distance_of_adatom_from_surface': distance_of_adatom_from_surface, 'index': 0, 'axis': CHOH_axis, 'rotations': rotations}
 71adsorbed_species.append(CHOH_adsorbed_species)
 72# --------------------------------------------
 73# new option 1
 74CH3O = molecule('CH3O') # note the oxygen is index 1
 75CH3O.center(vacuum=10.0)
 76CH3O_axis = '-y'
 77distance_of_adatom_from_surface = 1.5
 78rotations = [0,60]
 79CH3O_adsorbed_species = {'name': 'CH3O', 'molecule': CH3O, 'distance_of_adatom_from_surface': distance_of_adatom_from_surface, 'index': 1, 'axis': CH3O_axis, 'rotations': rotations}
 80adsorbed_species.append(CH3O_adsorbed_species)
 81
 82# new option 2
 83CH2OH = molecule('CH3OH') # carbon is index 0
 84CH2OH.center(vacuum=10.0)
 85del CH2OH[2] # remove the hydrogen atom
 86CH2OH_axis = (1,-1,0)
 87distance_of_adatom_from_surface = 1.5
 88rotations = range(0,360,90) #'automatic' #range(0,360,10)
 89CH2OH_adsorbed_species = {'name': 'CH2OH', 'molecule': CH2OH, 'distance_of_adatom_from_surface': distance_of_adatom_from_surface, 'index': 0, 'axis': CH2OH_axis, 'rotations': rotations}
 90adsorbed_species.append(CH2OH_adsorbed_species)
 91# --------------------------------------------
 92# new new option 1
 93
 94CH = molecule('CO') # note the carbon is index 1
 95CH[0].symbol = 'H'
 96CH.center(vacuum=10.0)
 97CH_axis = 'z'
 98distance_of_adatom_from_surface = 1.5
 99CH_adsorbed_species = {'name': 'CH', 'molecule': CH, 'distance_of_adatom_from_surface': distance_of_adatom_from_surface, 'index': 1, 'axis': CH_axis}
100adsorbed_species.append(CH_adsorbed_species)
101
102CH2 = molecule('CH4') # carbon is index 0
103CH2.center(vacuum=10.0)
104del CH2[4] # remove the hydrogen atom
105del CH2[3] # remove the hydrogen atom
106CH2_axis = 'z'
107distance_of_adatom_from_surface = 1.5
108rotations = [0,90] #'automatic' #range(0,180,10)
109CH2_adsorbed_species = {'name': 'CH2', 'molecule': CH2, 'distance_of_adatom_from_surface': distance_of_adatom_from_surface, 'index': 0, 'axis': CH2_axis, 'rotations': rotations}
110adsorbed_species.append(CH2_adsorbed_species)
111
112CH3 = molecule('CH4') # carbon is index 0
113CH3.center(vacuum=10.0)
114del CH3[4] # remove the hydrogen atom
115CH3_axis = (1,-1,1)
116distance_of_adatom_from_surface = 1.5
117rotations = [0.60] #'automatic' #range(0,120,10)
118CH3_adsorbed_species = {'name': 'CH3', 'molecule': CH3, 'distance_of_adatom_from_surface': distance_of_adatom_from_surface, 'index': 0, 'axis': CH3_axis, 'rotations': rotations}
119adsorbed_species.append(CH3_adsorbed_species)
120
121# new new option 2
122O = molecule('O')
123O.center(vacuum=10.0)
124distance_of_adatom_from_surface = 1.5
125O_adsorbed_species = {'name': 'O', 'molecule': O, 'distance_of_adatom_from_surface': distance_of_adatom_from_surface}
126adsorbed_species.append(O_adsorbed_species)
127
128OH = molecule('OH') # note the oxygen is index 0
129OH.center(vacuum=10.0)
130OH_axis = '-z'
131distance_of_adatom_from_surface = 1.5
132OH_adsorbed_species = {'name': 'OH', 'molecule': OH, 'distance_of_adatom_from_surface': distance_of_adatom_from_surface, 'index': 0, 'axis': OH_axis}
133adsorbed_species.append(OH_adsorbed_species)
134
135C = molecule('C')
136C.center(vacuum=10.0)
137distance_of_adatom_from_surface = 1.5
138C_adsorbed_species = {'name': 'C', 'molecule': C, 'distance_of_adatom_from_surface': distance_of_adatom_from_surface}
139adsorbed_species.append(C_adsorbed_species)
140
141# ----------------------------------------------------------------------------------------------------------------

The only input that is needed from this script is the adsorbed_species list. This list contains all the information about each of the adsorbates you would like to adsorb to your system.

For each adsorbate given, you need to provide a dictionary that contains the following:

  • name (str.): This is the name of the molecule. Give the distinguishing chemical name at the start of this string. If you want to add any other information to the name, add this after a _. For example, if you have a COOH molecule that you would like to configure with the H atom pointing up or down, given these different configurations as 'name': 'COOH_up' and 'name': 'COOH_down'. Both of these configurations will be analysed together as 'COOH' by Adsorber, but allows you to begin with different configurations of the adsorbate upon your system.

  • molecule (ase.Atoms): The is the Atoms object for the atom or molecule, as obtained from the molecule or read method as mentioned above.

  • distance_of_adatom_from_surface (float): This is the binding distance that you would like the atom or molecule to be initially placed from the cluster or surface model before you perform further optimisation with DFT.

  • sites_to_bind_adsorbate_to (optional, list of str.): This list indicates those types of sites that you would like to bind adsorbates to, be it top, bridge, three-fold, and four-fold binding sites. Default: [‘Top_Sites’,’Bridge_Sites’,’Three_Fold_Sites’,’Four_Fold_Sites’’]

    • include 'Top_Sites' in this list if you want to attach adsorbate to top sites.

    • include 'Bridge_Sites' in this list if you want to attach adsorbate to bridge sites.

    • include 'Three_Fold_Sites' in this list if you want to attach adsorbate to three fold sites.

    • include 'Four_Fold_Sites' in this list if you want to attach adsorbate to four fold sites.

For single atoms, this is all that is needed. If you want to adsorb molecules that have two or more atoms in it, you want to give two or three additional inputs into this dictionary.

  • index (int.): This is the index of the atom in the molecule to adsorb to the surface for the cluster/surface model. See How to Bind Molecule to the Surface of your Cluster/Surface Model in Adsorber for more information on how to select the index of the atom in the molecule you would like to be adsorbed to the surface.

  • axis (str./list/tuple): This is the axis in your molecule that you would like to point away from the surface of the cluster/surface model, as well as to rotate your moleule around (if you would like to rotate your molecule around the axis). See How to Bind Molecule to the Surface of your Cluster/Surface Model in Adsorber for more information for how to specify this axis.

  • rotations (list/tuple, optional): These are the angles of rotation that you would like to rotate the molecules around the axis on the surface of your cluster/surface model. If you have a linear molecule that is alligned to the axis or you do not want to rotate your molecule around the axis, you do not need to add this as this is an optional input. See How to Bind Molecule to the Surface of your Cluster/Surface Model in Adsorber for more information about how to specify how to best rotate your molecule about the axis on the surface of your cluster/surface model.

See How to Bind Molecule to the Surface of your Cluster/Surface Model in Adsorber for more information about how to obtain the index, axis, and rotations inputs for your adsorbates.