surfaxe.io module

surfaxe.io.plot_bond_analysis(bond, df=None, filename=None, width=6, height=5, dpi=300, color=None, plt_fname='bond_analysis.png')

Plots the bond distance with respect to fractional coordinate. Used in conjunction with surfaxe.analysis.bond_analysis.

Parameters

• bond (list) – Bond to analyse; e.g. ['Y', 'O'] order of elements in the bond must be the same as in the Dataframe or provided file.

• df (pandas DataFrame, optional) – DataFrame from surfaxe.analysis.bond_analysis. Defaults to None.

• filename (str, optional) – Path to csv file with data from surfaxe.analysis.bond_analysis. Defaults to None. Either df or filename need to be supplied.

• width (float, optional) – Width of figure in inches. Defaults to 6.

• height (float, optional) – Height of figure in inches. Defaults to 5.

• dpi (int, optional) – Dots per inch. Defaults to 300.

• color (str, optional) – Color of marker. Defaults to None which defaults to surfaxe base style

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

Returns

None, saves plot to bond_analysis.png

surfaxe.io.plot_electrostatic_potential(df=None, filename=None, dpi=300, width=6, height=5, colors=None, plt_fname='potential.png')

Plots the planar and macroscopic electrostatic potential along one direction. Can take either a DataFrame or a potential.csv file as input.

Parameters

• df (pandas DataFrame, optional) – pandas DataFrame from surfaxe.analysis.electrostatic_potential. Defaults to None.

• filename (str, optional) – The filename of csv file with potential data. Defaults to None.

• dpi (int, optional) – Dots per inch. Defaults to 300.

• width (float, optional) – Width of figure in inches. Defaults to 6.

• height (float, optional) – Height of figure in inches. Defaults to 5.

• colors (list, optional) – A list of colours for planar and macroscopic potential plots. Defaults to None, which defaults to surfaxe base style.

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

Returns

None, saves plot to potential.png

surfaxe.io.plot_enatom(df, colors=None, dpi=300, width=6, height=5, plt_fname='energy_per_atom.png')

Plots the energy per atom for all terminations. Based on surfaxe.convergence parse_energies.

Parameters

• df (pandas DataFrame) – DataFrame from parse_fols, or any other Dataframe with headings ‘slab_thickness, ‘vac_thickness’, ‘slab_per_atom’, ‘time_taken’, ‘index’.

• colors (list, optional) – A list of colours for plots of different vacuum thicknesses. Defaults to None, which defaults to surfaxe base style.

• dpi (int, optional) – Dots per inch. Defaults to 300.

• width (float, optional) – Width of figure in inches. Defaults to 6.

• height (float, optional) – Height of figure in inches. Defaults to 5.

• plt_fname (str, optional) – The name of the plot. Defaults to energy_per_atom.png. If name with no format suffix is supplied, the format defaults to png.

Returns

None, saves energy_per_atom.png

surfaxe.io.plot_surfen(df, colors=None, dpi=300, width=8, height=8, plt_fname=None)

Plots the surface energy for all terminations. Based on surfaxe.convergence parse_energies.

Parameters

• df (pandas DataFrame) – DataFrame from parse_fols, or any other Dataframe with headings ‘slab_thickness’, ‘vac_thickness’, ‘surface_energy’,’surface_energy_boettger’, ‘surface_energy_fm’, ‘time_taken’, ‘index’.

• colors (list, optional) – A list of colours for plots of different surface energies. Defaults to None, which defaults to surfaxe base style.

• dpi (int, optional) – Dots per inch. Defaults to 300.

• width (float, optional) – Width of figure in inches. Defaults to 8.

• height (float, optional) – Height of figure in inches. Defaults to 8.

• plt_fname (str, optional) – The name of the plot. Defaults to None which is either surface_energy.png for one slab index or surface_energy_slab_index.png for multiple indices.

surfaxe.io.slab_from_file(structure, hkl)

Reads in structure from the file and returns slab object.

Parameters

• structure (str) – Structure file in any format supported by pymatgen. Will accept a pymatgen.Structure object directly.

• hkl (tuple) – Miller index of the slab in the input file.

Returns

Slab object

surfaxe.io.slabs_to_file(list_of_slabs, structure, make_fols, make_input_files, config_dict, fmt, name, **save_slabs_kwargs)

Saves the slabs to file, optionally creates input files. The function can take any relevant keyword argument for DictSet.

Parameters

• list_of_slabs (list) – a list of slab dictionaries made with either of surfaxe.generation get_slab functions

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

• make_fols (bool) –

  Makes folders for each termination and slab/vacuum thickness combinations containing structure files.

  • True: A Miller index folder is created, in which folders named slab_vac_index are created to which the relevant structure files are saved.

    E.g. for a (0,0,1) slab of index 1 with a slab thickness of 20 Å and vacuum thickness of 30 Å the folder structure would be: 001/20_30_1/POSCAR

  • False: The indexed structure files are put in a folder named after the bulk formula.

    E.g. for a (0,0,1) MgO slab of index 1 with a slab thickness of 20 Å and vacuum thickness of 30 Å the folder structure would be: MgO/POSCAR_001_20_30_1.vasp

• make_input_files (bool) – Makes INCAR, POTCAR and KPOINTS files in each folder. If make_input_files is True but make_files or save_slabs is False, files will be saved to folders regardless. This only works with VASP input files, other formats are not yet supported. Defaults to False.

• config_dict (dict or str) – Specifies the dictionary used for the generation of the input files.

• fmt (str, optional) – The format of the output files. Options include ‘cif’, ‘poscar’, ‘cssr’, ‘json’, not case sensitive. Defaults to ‘poscar’.

• name (str, optional) – The name of the surface slab structure file created. Case sensitive. Defaults to ‘POSCAR’

Returns

None, saves surface slabs to file