surfaxe.analysis module

surfaxe.analysis.bond_analysis(structure, bond, nn_method=<Mock name='mock()' id='140141499432528'>, ox_states=None, save_csv=True, csv_fname='bond_analysis.csv', save_plt=False, plt_fname='bond_analysis.png', **kwargs)[source]

Parses the structure looking for bonds between atoms. Check the validity of the nearest neighbour method on the bulk structure before using it on slabs.

Parameters

  • structure (str) – filename of structure, takes all pymatgen-supported formats, including pmg structure object

  • bond (list) – Bond to analyse e.g. ['Y', 'O']

  • nn_method (class, optional) – The coordination number prediction algorithm used. Because the nn_method is a class, the class needs to be imported from pymatgen.analysis.local_env before it can be instantiated here. Defaults to CrystalNN().

  • ox_states (None, list or dict, optional) –

    Add oxidation states to the structure. Different types of oxidation states specified will result in different pymatgen functions used. The options are:

    • if supplied as list: The oxidation states are added by site

      e.g. [3, 2, 2, 1, -2, -2, -2, -2]

    • if supplied as dict: The oxidation states are added by element

      e.g. {'Fe': 3, 'O':-2}

    • if None: The oxidation states are added by guess.

    Defaults to None.

  • save_csv (bool, optional) – Makes a csv file with the c coordinate of the first atom and bond length. Defaults to True.

  • csv_fname (str, optional) – Filename of the csv file. Defaults to 'bond_analysis.csv'.

  • save_plt (bool, optional) – Make and save the bond analysis plot. Defaults to False.

  • plt_fname (str, optional) – Filename of the plot. Defaults to 'bond_analysis.png'.

Returns

DataFrame with the c coordinate of the first atom and bond length

surfaxe.analysis.cart_displacements(start, end, max_disp=0.1, save_txt=True, txt_fname='cart_displacements.txt')[source]

Produces a text file with all the magnitude of displacements of atoms in Cartesian space

Parameters

  • start (str) – Filename of initial structure file in any format supported by pymatgen or pymatgen structure object.

  • end (str) – Filename of final structure file in any format supported by pymatgen or pymatgen structure object.

  • max_disp (float, optional) – The maximum displacement shown. Defaults to 0.1 Å.

  • save_txt (bool, optional) – Save the displacements to file. Defaults to True.

  • txt_fname (str, optional) – Filename of the csv file. Defaults to 'cart_displacement.txt'.

Returns

None (default) or DataFrame of displacements of atoms in Cartesian space

surfaxe.analysis.complex_nn(start, cut_off_dict, end=None, ox_states=None, save_csv=True, csv_fname='nn_data.csv')[source]

Finds the nearest neighbours for more complex structures. Uses CutOffDictNN() class as the nearest neighbour method. Check validity on bulk structure before applying to surface slabs.

The site_index in the produced DataFrame or csv file is one-indexed and represents the atom index in the structure.

Parameters

  • start (str) – filename of structure, takes all pymatgen-supported formats.

  • cut_off_dict (dict) –

    Dictionary of bond lengths. The bonds should be specified with the oxidation states

    e.g. {('Bi3+', 'O2-'): 2.46, ('V5+', 'O2-'): 1.73}

  • end (str, optional) – filename of structure to analyse, use if comparing initial and final structures. The structures must have same constituent atoms and number of sites. Defaults to None.

  • ox_states (None, list or dict, optional) –

    Add oxidation states to the structure. Different types of oxidation states specified will result in different pymatgen functions used. The options are:

    • if supplied as list: The oxidation states are added by site

      e.g. [3, 2, 2, 1, -2, -2, -2, -2]

    • if supplied as dict: The oxidation states are added by element

      e.g. {'Fe': 3, 'O':-2}

    • if None: The oxidation states are added by guess.

    Defaults to None

  • save_csv (bool, optional) – Save to a csv file. Defaults to True.

  • csv_fname (str, optional) – Filename of the csv file. Defaults to 'nn_data.csv'

Returns

None (default) or DataFrame containing coordination data.

surfaxe.analysis.electrostatic_potential(locpot='./LOCPOT', lattice_vector=None, save_csv=True, csv_fname='potential.csv', save_plt=True, plt_fname='potential.png', **kwargs)[source]

Reads LOCPOT to get the planar and optionally macroscopic potential in c direction.

Parameters

  • locpot (str, optional) – The path to the LOCPOT file. Defaults to './LOCPOT'

  • lattice_vector (float, optional) – The periodicity of the slab, calculates macroscopic potential with that periodicity

  • save_csv (bool, optional) – Saves to csv. Defaults to True.

  • csv_fname (str, optional) – Filename of the csv file. Defaults to 'potential.csv'.

  • save_plt (bool, optional) – Make and save the plot of electrostatic potential. Defaults to True.

  • plt_fname (str, optional) – Filename of the plot. Defaults to 'potential.png'.

Returns

DataFrame

surfaxe.analysis.simple_nn(start, end=None, ox_states=None, nn_method=<Mock name='mock()' id='140141499432528'>, save_csv=True, csv_fname='nn_data.csv')[source]

Finds the nearest neighbours for simple structures. Before using on slabs make sure the nn_method works with the bulk structure.

The site_index in the produced DataFrame or csv file is one-indexed and represents the atom index in the structure.

Parameters

  • start (str) – Filename of structure file in any format supported by pymatgen

  • end (str, optional) – Filename of structure file in any format supported by pymatgen. Use if comparing initial and final structures. The structures must have same constituent atoms and number of sites. Defaults to None.

  • ox_states (None, list or dict, optional) –

    Add oxidation states to the structure. Different types of oxidation states specified will result in different pymatgen functions used. The options are:

    • if supplied as list: The oxidation states are added by site

      e.g. [3, 2, 2, 1, -2, -2, -2, -2]

    • if supplied as dict: The oxidation states are added by element

      e.g. {'Fe': 3, 'O':-2}

    • if None: The oxidation states are added by guess.

    Defaults to None.

  • nn_method (class, optional) – The coordination number prediction algorithm used. Because the nn_method is a class, the class needs to be imported from pymatgen.analysis.local_env before it can be instantiated here. Defaults to CrystalNN().

  • save_csv (bool, optional) – Save to a csv file. Defaults to True.

  • csv_fname (str, optional) – Filename of the csv file. Defaults to 'nn_data.csv'

Returns

None (default) or DataFrame containing coordination data