surfaxe.generation module

surfaxe.generation.generate_slabs(structure, hkl, thicknesses, vacuums, save_slabs=True, save_metadata=True, json_fname=None, make_fols=False, make_input_files=False, max_size=500, center_slab=True, ox_states=None, is_symmetric=True, layers_to_relax=None, fmt='poscar', name='POSCAR', config_dict=None, user_incar_settings=None, user_kpoints_settings=None, user_potcar_settings=None, parallelise=True, **kwargs)

Generates all unique slabs for a specified Miller indices or up to a maximum Miller index with minimum slab and vacuum thicknesses. It includes all combinations for multiple zero dipole symmetric terminations for the same Miller index.

The function returns None by default and generates either:

1. POSCAR_hkl_slab_vac_index.vasp (default)

2. hkl/slab_vac_index folders with structure files

3. hkl/slab_vac_index with all VASP input files

Or if save_slabs=False a list of dicts of all unique slabs is returned.

Parameters

• structure (str or pmg Structure obj) – Filename of structure file in any format supported by pymatgen or pymatgen structure object.

• hkl (tuple, list or int) – Miller index as tuple, a list of Miller indices or a maximum index up to which the search should be performed. E.g. if searching for slabs up to (2,2,2) hkl=2

• thicknesses (list) – The minimum size of the slab in Angstroms.

• vacuums (list) – The minimum size of the vacuum in Angstroms.

• save_slabs (bool, optional) – Whether to save the slabs to file. Defaults to True.

• save_metadata (bool, optional) – Whether to save the slabs’ metadata to file. Saves the entire slab object to a json file Defaults to True.

• json_fname (str, optional) – Filename of json metadata file. Defaults to bulk_formula_metadata.json

• make_fols (bool, optional) –

  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

  Defaults to False.

• make_input_files (bool, optional) – 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.

• max_size (int, optional) – The maximum number of atoms in the slab specified to raise warning about slab size. Even if the warning is raised, it still outputs the slabs regardless. Defaults to 500.

• center_slab (bool, optional) –

  The position of the slab in the simulation cell.

  • True: the slab is centered with equal amounts of vacuum above and below.

  • False: the slab is at the bottom of the simulation cell with all of the vacuum on top of it.

  Defaults to True.

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

  Add oxidation states to the bulk 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.

• is_symmetric (bool, optional) – Whether the slabs cleaved should have inversion symmetry. If bulk is non-centrosymmetric, is_symmetric needs to be False - the function will return no slabs as it looks for inversion symmetry. Take care checking the slabs for mirror plane symmetry before just using them. Defaults to True.

• layers_to_relax (int, optional) – Specifies the number of layers at the top and bottom of the slab that should be relaxed, keeps the centre constrained using selective dynamics. NB only works for VASP files

• fmt (str, optional) – The format of the output structure 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’

• config_dict (dict or str, optional) – Specifies the dictionary used for the generation of the input files. Suppports already loaded dictionaires, yaml and json files. Surfaxe-supplied dictionaries are PBE (pe), PBEsol (ps) and HSE06 (hse06) for single shot calculations and PBE (pe_relax) and PBEsol (ps_relax) for relaxations. Not case sensitive. Defaults to PBEsol (ps).

• user_incar_settings (dict, optional) – Overrides the default INCAR parameter settings. Defaults to None.

• user_kpoints_settings (dict or Kpoints object, optional) – Overrides the default kpoints settings. If it is supplied as dict, it should be as {'reciprocal_density': 100}. Defaults to None.

• user_potcar_settings (dict, optional) – Overrides the default POTCAR settings. Defaults to None.

• parallelise (bool, optional) – Use multiprocessing to generate slabs. Defaults to True.

Returns

None (default) or unique_slabs (list of dicts)

surfaxe.generation.oxidation_states(structure, ox_states=None)

Adds oxidation states to the structure object if not already present

Parameters

• structure (obj) – Pymatgen structure object

• 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.

Returns

Structure decorated with oxidation states