How to read a poscar file which is a surface and add adsorbates using ASE

Question

I have a POSCAR file containing Co, Cr, Fe, Ni elements. It is a slab of 6 layers. The first 3 layers are mobile whiles the last three layers are fixed. I would like to add adsorbates at the FCC hollow sites. From my count, I would need 15 oxygen atoms at the different hollow sites. I don't want to include hcp hollow sites. How do I read the poscar file into ASE to maintain the surface and vacuum and only add the adsorbate? I have attached the poscar file.

CoCrFeNi
   1.00000000000000     
     9.9633502299999996    0.0000000000000000    0.0000000000000000
    -4.9733836199999999    8.6618479100000005    0.0000000000000000
     0.0000000000000000    0.0000000000000000   40.4368920000000003
   Co   Cr   Fe   Ni
    24    24    24    24
Selective dynamics
Direct
  0.5612360243849388  0.9099052137287840  0.6250221820654160   T   T   T
  0.2356071120850486  0.2518526753215678  0.5772064214469697   T   T   T
  0.2348146468815286  0.7507696751875000  0.5764034425400485   T   T   T
  0.4860087088559321  0.5025000099364838  0.5766204786838768   T   T   T
  0.4832051517095323  0.9985833850246899  0.5770138532476135   T   T   T
  0.4854835901844644  0.7512215609776637  0.5763813008840900   T   T   T
  0.2355456895711744  0.9978683794875377  0.5777498674746212   T   T   T
  0.9867436499750243  0.5059613373927444  0.5769244369303035   T   T   T
  0.9038462779907266  0.5846022973376531  0.5260416228921621   T   T   T
  0.5716581887774268  0.9201204041921329  0.4758342950788617   F   F   F
  0.5741257856744610  0.4187527924396477  0.4757376011984320   F   F   F
  0.8221917385325952  0.1698063756466937  0.4754235315612263   F   F   F
  0.8188510224305006  0.6661687044098628  0.4754012746578056   F   F   F
  0.8238998402551019  0.4200678697901523  0.4748374331044047   F   F   F
  0.5727204154956951  0.6689043793196774  0.4747973706782389   F   F   F
  0.3230897361863398  0.1691307692332842  0.4746252506250954   F   F   F
  0.2362167951761762  0.2470966960213019  0.4240635012206155   F   F   F
  0.9075250613866288  0.5865598256619577  0.3747389883475734   F   F   F
  0.9099926467579991  0.0851921908197042  0.3746422944671437   F   F   F
  0.1580586012731757  0.8362458075069128  0.3743282248299380   F   F   F
  0.1547179181243052  0.3326081258796876  0.3743059679265173   F   F   F
  0.1597667301860781  0.0865072797151001  0.3737421263731164   F   F   F
  0.9085872881049042  0.3353438007895022  0.3737020639469506   F   F   F
  0.6589565758423106  0.8355702010934962  0.3735299438938071   F   F   F
  0.8058501908443986  0.1604085948745253  0.6276226743697434   T   T   T
  0.0711651015373968  0.1740917158429164  0.6283794021117671   T   T   T
  0.5585537014512123  0.1589400490967113  0.6274647415475056   T   T   T
  0.8408195288613217  0.4120066169412361  0.6276226664037110   T   T   T
  0.8218106695859454  0.6771528044496808  0.6304296582071180   T   T   T
  0.0835097517099495  0.4214918947625969  0.6290440423670955   T   T   T
  0.2375735696515378  0.5010054481380813  0.5770179622858687   T   T   T
  0.7358517176793846  0.5001337489919461  0.5753017076229778   T   T   T
  0.1526774569984566  0.8311508061347753  0.5260862055103875   T   T   T
  0.4012780008378368  0.8374455841948802  0.5256159156652330   T   T   T
  0.9015458337759297  0.8318449292366887  0.5267321752290328   T   T   T
  0.1650345374797721  0.0820828245082830  0.5266625182108280   T   T   T
  0.1530715796942058  0.3284398123835934  0.5256954404458725   T   T   T
  0.4037759574840217  0.0881761973292648  0.5266741240986712   T   T   T
  0.5719291831091056  0.1671338512338281  0.4751517500405313   F   F   F
  0.0726206267831913  0.1688011628918105  0.4750530777686848   F   F   F
  0.4902349088201277  0.5006121147652394  0.4250452779605283   F   F   F
  0.7387644569889744  0.5022689205818693  0.4249752923642092   F   F   F
  0.2384726428149762  0.4987219869114483  0.4248748889998737   F   F   F
  0.4894111111794288  0.7512741008171346  0.4248244400187815   F   F   F
  0.4908000549497729  0.0025951829486672  0.4244191170775409   F   F   F
  0.7393419908448990  0.7494893777233287  0.4241708289549067   F   F   F
  0.9077960227650834  0.8335732830940472  0.3740564433092430   F   F   F
  0.4084875035752731  0.8352405947520296  0.3739577710373965   F   F   F
  0.0714088580284006  0.9241042308280607  0.6266688247630529   T   T   T
  0.0712936348301734  0.6734806713146717  0.6264448440732556   T   T   T
  0.5661143764171257  0.6694797179385326  0.6276482980086926   T   T   T
  0.5826565215444279  0.4197094481854535  0.6248967461469209   T   T   T
  0.9863437963371268  0.0049281853325266  0.5778527630146324   T   T   T
  0.7299839656132034  0.7483226508951495  0.5771810032009886   T   T   T
  0.9822818352016206  0.7481102940128979  0.5771714159167410   T   T   T
  0.4836853691620328  0.2504096534801669  0.5765478188719351   T   T   T
  0.4023001272576696  0.5849271527966273  0.5256599968038801   T   T   T
  0.4052342653716023  0.3382546586388231  0.5252451653467152   T   T   T
  0.9035134348127880  0.3352264766627390  0.5263625912611249   T   T   T
  0.9027949755174263  0.0791523962176613  0.5260593633310788   T   T   T
  0.3232407866261937  0.6702789128053368  0.4755137956695563   F   F   F
  0.0665275574938846  0.4173909583226560  0.4755078604953127   F   F   F
  0.3245013047405436  0.4173221508342095  0.4749788880906110   F   F   F
  0.8209027016053341  0.9159207229719186  0.4747226864023091   F   F   F
  0.7400046718620530  0.2526014105458927  0.4255408650100989   F   F   F
  0.7373990205197032  0.9972170014700694  0.4251333163785205   F   F   F
  0.2401126400303042  0.0008789443175559  0.4246560294495438   F   F   F
  0.2420278484524303  0.7522265534676222  0.4244614051940516   F   F   F
  0.6591076592354028  0.3367183342751616  0.3744184889382680   F   F   F
  0.4023944301030866  0.0838303797924809  0.3744125537640244   F   F   F
  0.6603682004010807  0.0837616184835568  0.3738835813593226   F   F   F
  0.1567695396708118  0.5823600289929374  0.3736276269699488   F   F   F
  0.8139283773437237  0.9179970463961956  0.6264927519830703   T   T   T
  0.3316971715924403  0.4206428344420928  0.6270248681347872   T   T   T
  0.3156932809260076  0.9156706536874418  0.6266447810285281   T   T   T
  0.3193842754680041  0.6705125009466922  0.6268440812499967   T   T   T
  0.3204197280025719  0.1699424665767754  0.6272751272551228   T   T   T
  0.7346622986391906  0.2521520822199035  0.5767044378177472   T   T   T
  0.7337753457319838 -0.0000484138730764  0.5764088122275434   T   T   T
  0.9859905944062034  0.2532340884891014  0.5767699223686655   T   T   T
  0.1520510767833566  0.5824068293232663  0.5262650644687904   T   T   T
  0.6539763846918202  0.0840366980125778  0.5258262367600025   T   T   T
  0.6540657686858518  0.5846162808349679  0.5256774417697333   T   T   T
  0.6542669891634135  0.3357645143656891  0.5254505398702217   T   T   T
  0.6510606874754463  0.8330745611877558  0.5256560801844358   T   T   T
  0.0765196813155740  0.9206583956286494  0.4765519565648120   F   F   F
  0.0658167894639234  0.6668927993218503  0.4761879325443701   F   F   F
  0.3165218299266357  0.9183686994568774  0.4733637787988272   F   F   F
  0.4845041515414152  0.2488359322854947  0.4251788193810739   F   F   F
  0.9902804335043385  0.7510055668940936  0.4248024304142888   F   F   F
  0.9888284822195317  0.2504328201717385  0.4244866296845942   F   F   F
  0.9943961297937989  0.9996431581306737  0.4242620822589416   F   F   F
  0.9866011241072812  0.4984118914182147  0.4231390978317506   F   F   F
  0.4123865539247760  0.5870978170984742  0.3754566498335237   F   F   F
  0.4016836620731254  0.3333322207916751  0.3750926258130818   F   F   F
  0.6523887025358377  0.5848081209267022  0.3722684720675389   F   F   F
 
 

Answer 1

I remember running into exactly the same issue like you when I just started my PhD. In ASE, there is this ase.build.add_adsorbate function that allows placing a single adsorbate on a surface site. However, this function has the following limitations:

• the clean surface slab must be generated by ase.build;
• only allow one pre-defined position for each type of site;
• for alloy systems it does not differentiate two sites of the same type (e.g. bridge) but different elemental compositions (e.g. AA, BB and AB);
• limited number of supported surfaces;
• nanoparticles/clusters are not supported.

I then looked into other codes with similar functions, e.g. Pymatgen, CatKit, etc, but to the best of my knowledge, they all require a pre-defined bulk/surface structure to identify adsorption sites. So I decided to develop a code by myself, namely ACAT.

ACAT overcomes all aforementioned limitations, providing a general way of identifying adsorption sites on an arbitrary surface structure (i.e. any ase.Atoms object) that can represent a wide variety of surfaces and nanoparticles. In detail, ACAT implements the adsorption site identification for 20 common low-index surfaces (including fcc, bcc and hcp crystal structures) in acat.adsorption_sites.SlabAdsorptionSites and for 3 common nanoparticle motifs (fcc, icosahedron, and decahedron) in acat.adsorption_sites.ClusterAdsorptionSites.

Let's come back to your question. You can first read the POSCAR using ASE:

from ase.io import read
from ase.visualize import view

atoms = read('POSCAR')
view(atoms)

And your clean alloy fcc(111) surface looks like this

You can then use ACAT to identify all high-symmetry adsorption sites on the fcc(111) surface, i.e. ontop, bridge, fcc and hcp sites.

from acat.adsorption_sites import SlabAdsorptionSites

sas = SlabAdsorptionSites(atoms, surface='fcc111')
sites = sas.get_sites()

This sites object is a list of dictionaries. Each dictionary stores the information of one site. If you print out one dictionary, you will see something like this:

print(sites[0])
# {'site': 'ontop', 'surface': 'fcc111', 'morphology': 'terrace', 'position': array([ 1.06648339,  7.88146057, 25.27395447]), 'normal': array([-0.00176619, -0.00244269,  0.99999546]), 'indices': (0,), 'composition': None, 'subsurf_index': None, 'subsurf_element': None, 'label': None}

where the 'site', 'surface', 'morphology', 'position', 'normal', 'indices' and 'composition' keys contain information of the type, the locating surface, the local geometric environment, the Cartesian coordinate, the normal vector, the atomic indices and the elemental composition of the site, respectively.

Now that we want to add adsorbates to specific sites, e.g. adding O to all fcc sites as you requested, we can just use a for loop with the acat.build.add_adsorbate_to_site function (you can change the height parameter to adjust the bond distance between the adsorbates and the surface):

from acat.build import add_adsorbate_to_site

for st in sites:
    if st['site'] == 'fcc':
        add_adsorbate_to_site(atoms, adsorbate='O', site=st, height=1.)
view(atoms)

Just like that, you get the structure you want

The code can be installed simply by pip install acat. For more usage of the ACAT package, I strongly recommend this Jupyter notebook tutorial. Remember to cite if you find the code useful for your research :)