hetero2d.manipulate package

Submodules

hetero2d.manipulate.heterotransmuter module

These modules are used to create the heterostructure configurations given a 2d and substrate slab. The code is adopted from the MPInterfaces to ensure the code is compatible with the FireWorks and atomate architecture, to fix minor bugs in the original code, and return interface matching criteria.

hetero2d.manipulate.heterotransmuter.rotate_to_acute(structure)

If the angle for a 2D structure is obtuse, reflect the b vector to -b to make it acute.

Parameters

structure (Structure) – structure to rotate.

Returns

rotated structure

hetero2d.manipulate.heterotransmuter.aligned_hetero_structures(struct_2d, struct_sub, max_mismatch=0.01, max_area=200, nlayers_2d=3, nlayers_sub=2, r1r2_tol=0.02, max_angle_diff=1, separation=3.4)

Given the 2 slab structures and the alignment parameters, return slab structures with lattices that are aligned with respect to each other.

Parameters

  • slab_2d (Structure) – Two dimensional slab structure object.

  • slab_sub (Structure) – Substrate slab structure object.

  • max_area (float) – The maximum area you want to search for a matching lattice. Defaults to 200 sqr. Angstroms.

  • max_mismatch (float) – The maximum mismatch between the a and b lattice vectors of the aligned 2D and substrate lattice vectors. Defaults to 0.01, multiply by 100 to obtain percent.

  • max_angle_diff (float) – The angle deviation between the a and b lattice vectors between the old lattice vectors and the new lattice vectors. Defaults to 1 degree.

  • r1r2_tol (float) – Allowed area approximation tolerance for the two lattices. Defaults to 0.02.

  • nlayers_substrate (int) – number of substrate layers. Defaults to 2 layers.

  • nlayers_2d (int) – number of 2d material layers. Defaults to 3 layers.

  • separation (float) – separation between the substrate and the 2d material. Defaults to 3.4 angstroms.

Returns

aligned_sub, aligned_2d, alignment_info

hetero2d.manipulate.heterotransmuter.generate_all_configs(mat2d, substrate, nlayers_2d=3, nlayers_substrate=2, separation=3.4)

For the given lattice matched 2D material and substrate structures, this functions computes all unique (Wyckoff) sites of the mat2d and substrate. The unique sites are iteratively matched between the mat2d and substrate stacking the unique sites on top of each other separated by the separation distance parameter. This subsequently generates all possible 2d/substrate heterostructure configurations stacked over high symmetry points. All unique structures are returned.

Parameters

  • mat2d (Structure) – Lattice and symmetry-matched 2D material structure.

  • substrate (Structure) – Lattice and symmetry-matched 2D substrate structure.

  • nlayers_substrate (int) – number of substrate layers. Defaults to 2 layers.

  • nlayers_2d (int) – number of 2d material layers. Defaults to 3 layers.

  • separation (float) – separation between the substrate and the 2d material. Defaults to 3.4 angstroms.

Returns

list of hetero_interface configurations

hetero2d.manipulate.heterotransmuter.hetero_interfaces(struct_2d, struct_sub, max_mismatch=0.01, max_area=200, nlayers_2d=3, nlayers_sub=2, r1r2_tol=0.02, max_angle_diff=1, separation=3.4)

The given the 2D material and the substrate slab, the 2 slabs are combined to generate all possible unique structures for the 2D material on the substrate surface generating all unique hetero_structures.

Parameters

  • struct_2d – The 2-dimensions slab structure to combine with the substrate slab.

  • struct_sub – The substrate slab structure which the 2D structure will be placed on top of.

  • max_mismatch (float) – The maximum allowed lattice strain applied to the struct_2d. Defaults to 0.01, multiply by 100 to obtain percent strain.

  • max_area (float) – The maximum surface area of the supercell to search for potential lattice matches between struct_2d and struct_sub. Typical values 30-200 Angstroms.

  • max_angle_diff (float) – The maximum allowed deviation between the new superlattice and the old lattice a and b vectors. Angle between a and b vectors: arccos[a.b/(|a||b|)]. Default value 1 degree.

  • r1r2_tol (float) – The maximum allowed deviation between the scaled surface area of the 2d and substrate. Typical values range from 0.01 to 0.1.

  • nlayers_2d (int) – The number of layers of the 2D materials which you want to relax during the relaxation. Defaults to 3 layers.

  • nlayers_sub (int) – The number of layers of the substrate surface which you want to relax during the relaxation. Defaults to 2 layers with bottom layer frozen.

  • separation (float) – Separation distance between struct_sub and struct_2d. Default 3.4 Angstroms.

Returns

Unique hetero_structures list, last entry contains lattice alignment information. Site properties contain iface name.

hetero2d.manipulate.heterotransmuter.iface_name(mat2d, substrate)

Helper function used to generate a unique interface name for a set of interfaces. The substrate’s name will always be the same but the 2d materials indices shit and these are changed from one configuration to the next.

hetero2d.manipulate.heterotransmuter.remove_duplicates(uv_list, tm_list)

Remove duplicates based on a, b, alpha matching. Helper function.

Parameters

  • uv_list (list) – the a and b lattice vectors to transform.

  • tm_list (list) – a list of transformation matrices.

Returns

new_uv_list, new_tm_list

hetero2d.manipulate.layersolver module

Analyze an existing structure and parse it based on atomic layers. The cutoff can be changed but defaults to 0.5 Angstroms. Returns a LayeredStructure dictionary.

hetero2d.manipulate.layersolver.LayerSolver(structure, cutoff=0.5)

Group sites in a structure into layers according to z-coordinate. Return layer specific data such as the z-coordinate of layer, a list of sites, the species of elements in the layer and the atom indices of that layer.

Parameters

  • structure (Structure) – Input structure to be analyzed.

  • cutoff (float) – The inter-layer separation distance that the algorithm searches for.

Returns

each layer information is encoded with dictionary key num_layers (int): number of layers in the structure and Layer{i} with sub-keys avg_z (float): average z-coordinate of the layer sites (list of PeriodicSite): PeriodicSites for each site within the layer species (list): elemental species of each site within the layer site_idx (list): atom indices for species within the layer wyckoffs (list): wyckoff symbols for each site in the layer

Return type

Layers dictionary returning layer specific information

hetero2d.manipulate.utils module

Useful utilities to view, analyze, and change structures. Some functions are not intended for the user.

hetero2d.manipulate.utils.get_mongo_client(db_file, db_type=None)

Connect to the database using mongoclient. Has multiple connection modes for URI (the url string) and ATLAS credentials.

Parameters

  • db_file (str) – The db.json file location.

  • db_type (str) – String describing the type of connection you are trying to make. Options - ATLAS or URI. For a private MongoDB server, ignore this tag.

Returns

client, database_name

hetero2d.manipulate.utils.average_z_sep(structure, iface_idx, initial=None)

Get the average z separation distance between 2 layers in a structure. If provided an initial structure the change in the post-adsorbed z separation distance is calculated. Typically used for 2D-substrate heterostructures in AnalysisToDb.

Parameters

  • structure (Structure) – the final structure to analyze.

  • iface_idx (dict) – Dictionary containing a list of atom indices for each layer. Computed using tag_iface.

Other Parameters

initial (Structure) – the initial structure prior to DFT optimization.

Returns

z-separation, delta_2d_z

hetero2d.manipulate.utils.center_slab(structure)

Centers the atoms in a slab structure around 0.5 fractional height.

Parameters

structure (Structure) – Structure to center.

Returns

Centered Structure object

hetero2d.manipulate.utils.get_fu(struct_sub, struct_2d, sub_aligned, td_aligned)

Given superlattice structures and original unit cell structures return the number of formula units of the aligned 2d and substrate based on the original substrate and 2d component structures.

Parameters

  • struct_sub (Structure) – Unit cell for the substrate structure to be aligned to another structure.

  • struct_2d (Structure) – Unit cell for the 2d material to be aligned to the substrate structure.

  • aligned_sub (Structure) – Superlattice for the substrate aligned to the 2d material.

  • aligned_2d (Structure) – Superlattice for the 2d material aligned to the substrate structure.

Returns

fu_2d, fu_sub

hetero2d.manipulate.utils.set_sd_flags(interface=None, n_layers=2, top=True, bottom=True, lattice_dir=2)

Set the relaxation flags for top and bottom layers of interface.

The upper and lower bounds of the z coordinate are determined based on the slab. All layers above and below the bounds will be relaxed. This means if there is a ligand on top of the slab, all of its atoms will also be relaxed.

Parameters

  • interface (Structure) – input structure file.

  • n_layers (int) – number of layers to be relaxed.

  • top (bool) – whether n_layers from top are be relaxed.

  • bottom (bool) – whether n_layers from bottom are be relaxed.

  • lattice_dir (str) – whether to search the a, b, or c axis for layers.

Returns

sd_flags

hetero2d.manipulate.utils.get_key(my_dict, val)

Function returns the key corresponding to a dictionary value.

hetero2d.manipulate.utils.round_decimals_down(number: float, decimals: int = 2)

Returns a value rounded down to a specific number of decimal places.

hetero2d.manipulate.utils.slab_from_struct(structure, hkl=None)

Reads a pymatgen structure object and returns a Slab object. Useful for reading in 2d/substrate structures from atomate wf’s.

Parameters

  • hkl (list) – miller index of the slab in the input file.

  • structure (Structure) – structure file in any format supported by pymatgen.

Returns

Slab structure object

hetero2d.manipulate.utils.struct_from_str(string)

Given a string serialized pymatgen structure object, return a structure object. Fixes a conversion error when j_sanitizing structure objects not in dictionary format. Probably due to my ignorance.

Parameters

string (str) – A string representation of a structure object.

Returns

pymatgen structure object

hetero2d.manipulate.utils.tag_iface(structure, nlayers_2d, nlayers_sub=2)

Find the atom indices in a heterostructure by specifying how many layers there are for the 2D material. Returns a dictionary of atom ids for each layer of the 2D material and nlayers_sub of the substrate surface.

Parameters

  • structure (Structure) – The hetero_interface structure. Should be an unrelaxed structure.

  • nlayers_2d (int) – The number of layers contained within the 2d material.

  • nalyers_sub (int) – The number of layers of the substrate surface to include in the interface tags.

Returns

layer_indices

hetero2d.manipulate.utils.show_struct_ase(structure)

Creates a pop up structure model for a pymatgen structure object using ase’s viewer. Created for use in jupyter notebooks and might not work over remote access.

Parameters

structure (Structure) – Structure to show.

class hetero2d.manipulate.utils.nn_site_indices(structure, NN, target_sites, cation_anion=False, oxi_states=None, image=True, duplicate=True, **kwargs)

Bases: pymatgen.analysis.local_env.CrystalNN

This function returns the nearest neighbor atom id’s for a given atom id. This function searches from [start,end] using the NN variable.

Parameters

  • structure (Structure) – pymatgen structure object to perform analysis on.

  • NN (list) – A list indicating the radius from [start,end] to search for valid anions/cations. This is used to set the search_cutoff which will be given by the end value.

  • target_sites ([int]) – A list of atom ids which you want to search around for NN cations/anions. Atom id’s can be visualized using ASE.

  • cation_anion (bool) – Whether to match anion and cation pairs. Defaults to False.

  • oxi_states (dict) – If anion_cation true, provide a dictionary of the oxidation states for each cation/anion species.

  • image (bool) – Whether to return data from image cells. Defaults to True.

  • duplicated (bool) – Remove duplicated sites and return only the unique site_indices for the structure. Defaults to True.

Returns

A dictionary containing the atom id which was searched around and the corresponding list of NN atom ids of the cation/anions.

Return type

site_data (dict)

Initialize CrystalNN with desired parameters. Default parameters assume “chemical bond” type behavior is desired. For geometric neighbor finding (e.g., structural framework), set (i) distance_cutoffs=None, (ii) x_diff_weight=0.0 and (optionally) (iii) porous_adjustment=False which will disregard the atomic identities and perform best for a purely geometric match.

Parameters

  • weighted_cn – (bool) if set to True, will return fractional weights for each potential near neighbor.

  • cation_anion – (bool) if set True, will restrict bonding targets to sites with opposite or zero charge. Requires an oxidation states on all sites in the structure.

  • distance_cutoffs – ([float, float]) - if not None, penalizes neighbor distances greater than sum of covalent radii plus distance_cutoffs[0]. Distances greater than covalent radii sum plus distance_cutoffs[1] are enforced to have zero weight.

  • x_diff_weight – (float) - if multiple types of neighbor elements are possible, this sets preferences for targets with higher electronegativity difference.

  • porous_adjustment – (bool) - if True, readjusts Voronoi weights to better describe layered / porous structures

  • search_cutoff – (float) cutoff in Angstroms for initial neighbor search; this will be adjusted if needed internally

  • fingerprint_length – (int) if a fixed_length CN “fingerprint” is desired from get_nn_data(), set this parameter

avg_site_bond_dist(bonded_elm=None, return_avg_list=True)

Give the site-dependent bond distance from the target site. If return_avg_list is True, an average bond distance is provided for each target sites nearest neighbor list entry returned by the all_nn_info method. Bonding distance dictionary returned with the format {nn_target_site_index: {nn_bonded_atom_index: bond_distance_value}. Bond distance is computed from the all_nn_info() method.

Parameters

  • bonded_elm (list) – List of elements that you want to determine bond lengths for. If empty finds all nearby elements. If empty, all elements are considered for analysis.

  • return_avg_list (bool) – Whether to return the average bond distance.

Returns

dictionary of NN bond distances for each target specie. If return_avg_list=True, returns the avg bond distance of each target specie.

image_filter(data)

Filter out all sites that are not bonded within the (0,0,0) unit cell. Triggered by image = False.

Parameters

data (dict) – the cNN.all_nninfo data type.

remove_duplicates(data)

Return only the unique site indices from the all_nninfo cNN returned for each site. Truggered by duplicates=True.

Parameters

data (dict) – the cNN.all_nninfo data type.

all_nn_info()

Return the get_nn_data attribute from CrystalNN with or without image data, with options to remove duplicated site_indices. Example: [{‘site’:’PeriodicSite’, ‘image’:(int,int,int), ‘weight’:float, ‘site_index’:int}, ..]

Returns

nn_data (dict)

site_indices()

Returns the nearest neighbor site indices subject to the NN search criteria.

site_elements()

Returns the nearest neighbor elements that correspond to the site indices.

hetero2d.manipulate.utils.iface_layer_locator(structure, cutoff, iface_elements)

Helper function used to locate the iface layers from the layer solver.

Parameters

  • structure (Structure) – input structure to find the interface layers for.

  • cutoff (float) – the layer separation cutoff distance.

  • iface_elements (list) – A list of element species that compose the top and bottom iface layers.

Returns

LayerSolver object, top_layer specie, bottom_layer specie

hetero2d.manipulate.utils.atomic_distance(structure, dist=2)

Given a structure and an interatomic separation distance all sites which have a spacing less than dist will be printed out.

Parameters

  • structure (Structure) – The structure to analyze.

  • dist (float) – A cut-off value which defines the minimum inter_atomic spacing.

Module contents