MAZE Key Classes

Zeolite class

class zeolite.Zeolite(symbols=None, positions=None, numbers=None, tags=None, momenta=None, masses=None, magmoms=None, charges=None, scaled_positions=None, cell=None, pbc=None, celldisp=None, constraint=None, calculator=None, info=None, velocities=None, site_to_atom_indices=None, atom_indices_to_site=None, additions=None, ztype=None, cluster_maker=None)

This Zeolite object inherits from PerfectZeolite. It represents a zeolite and consists of additional functionality for adding, removing and integrating other atoms.

__init__(symbols=None, positions=None, numbers=None, tags=None, momenta=None, masses=None, magmoms=None, charges=None, scaled_positions=None, cell=None, pbc=None, celldisp=None, constraint=None, calculator=None, info=None, velocities=None, site_to_atom_indices=None, atom_indices_to_site=None, additions=None, ztype=None, cluster_maker=None)

Constructor for Zeolite object. The majority of the functionality comes from ase.Atoms object # TODO: write out docstring

static _check_unique_positions(position_list)

A helper function to check that the positions of the atoms are unique. An error is thrown if there are overlapping atoms. This slows down the code, because it is O(N^2).

Parameters

(np.array[np.array]) (position_list) – an array of positions

Returns

None

add_additions_map_to_self(additions_map: Dict) → None

Add an additions map to the current Zeolite. This function has side effects and modifies the current Zeolite. This is useful in building a Zeolite from a saved file and reloading the additions map into memory. :param additions_map: an additions map (format is specified in the additions map function) :type additions_map: Dict[Dict] :return: None :rtype: None

add_atoms(atoms_to_add: ase.atoms.Atoms, atom_type: str, short_description: str = '') → zeolite.Zeolite

Adds additional atoms to current imperfect MAZE-sim

Parameters

• atoms_to_add – The new atoms to add

• atom_type – A str describing the type of atoms that are being added

• short_description – A short description of the atoms that are being added (optional)

Returns

A new imperfect MAZE-sim with the atoms added

apply(operation: Callable, *args, **kwargs) → zeolite.Zeolite

Applies a custom function to the atoms and returns a new self. Custom operation cannot change tags or else errors will occur!

Parameters

operation – applies a custom function to the atoms

Returns

zeolite with applied modifications

build_H_atoms_cap_dict(bonds_needed: Optional[Dict[str, int]] = None)

Build a dictionary of hydrogen caps

Parameters

bonds_needed – Number of bonds needed for each atom

Returns

A list of positions of H caps

build_O_atoms_cap_dict(bonds_needed: Optional[Dict[str, int]] = None)

Builds a dictionary of oxygen caps

Parameters

bonds_needed – Number of bonds needed for each atom

Returns

A list of oxygen cap positions

build_all_atoms_cap_dict(bonds_needed: Optional[Dict[str, int]] = None) → Dict[str, numpy.array]

Builds a dictionary for all atoms (not currently being used, but could be resurrected).

Parameters

bonds_needed – number of bonds needed for each atom type

Returns

A list of capping atoms to add

cap_atoms(cap_description: str = '') → zeolite.Zeolite

Cap all of the atoms in the zeolite

Parameters

cap_description – A short description for the caps that will be added

Returns

A copy of self with the correct parameters added

change_atom_properties(self_index: int, other_index: int, other: ase.atoms.Atoms) → None

Change the atom properties

Parameters

• self_index – index of self that needs to be changed

• other_index – index of other that holds the properties to change self

• other – other Atoms object that the other_indices corresponds to

Returns

None

create_silanol_defect(site_index) → zeolite.Zeolite

Creates a silanol defect by deleting an atom and capping the resulting imperfect MAZE-sim

Parameters

site_index –

Returns

An imperfect MAZE-sim with a silanol defect

delete_atoms(indices_to_delete) → zeolite.Zeolite

Delete atoms from imperfect MAZE-sim by returning a copy with atoms deleted

Parameters

indices_to_delete – Indices of atoms in current MAZE-sim to delete

Returns

a copy of self with atoms deleted

find_missing_atom(oxygen_atom_to_cap_pi, atom_symbol_list) → int

Parameters

• atom_symbol_list – The symbols to look for in the parent MAZE-sim

• oxygen_atom_to_cap_pi –

Returns

parent atom Si index or H index

find_type(atom_type_name: str) → List[int]

Find the type of the atom in the parent zeolite list

Parameters

atom_type_name (str) – the name of a certain site

Returns

List of indices that match site description

Return type

List[int]

get_H_pos(atom_to_cap_self_i: int) → numpy.array

Parameters

atom_to_cap_self_i – atom to cap index (self index)

Returns

hydrogen position

get_cluster(start_index: int, cluster_indices=None, **kwargs) → Tuple[zeolite.Zeolite, zeolite.Zeolite]

Generates a Cluster of atoms around the specified index. The number of atoms in the cluster is given by the size parameter.

Parameters

• start_index (int) – center index of cluster

• cluster_indices – Indices of cluster to make

• max_size – max size of cluster

• index – index of the central atom in the cluster

• max_neighbors – number of neighbors from the host atom in the final cluster

Returns

index of the cluster in the MAZE-sim cluster array

get_hydrogen_cap_pos_simple(index) → numpy.array

Finds the position of a hydrogen cap position

Parameters

index – index of hydrogen cap

Returns

the hydrogen position to add the cap too

get_oxygen_cap_pos(atom_to_cap_self_i) → numpy.array

Find a position of an oxygen cap

Parameters

self_index – index of atom needing cap

Returns

A position array of the oxygen cap position

get_site_types() → List[str]

Get a list of all of the types in the parent zeolite :return: List of the names of all types :rtype: List[str]

get_type(index: int) → str

Get the type of atom at a certain index :param index: the atom index to get the type of :type index: int :return: the name of the type of index :rtype: str

integrate(other: maze.perfect_zeolite.PerfectZeolite) → zeolite.Zeolite

Integrate another MAZE-sim into the current MAZE-sim

Parameters

other – the other MAZE-sim to integrate

Returns

a new imperfect MAZE-sim with the other MAZE-sim integrated

integrate_adsorbate(adsorbate: ase.atoms.Atoms) → Tuple[zeolite.Zeolite, maze.adsorbate.Adsorbate]

Add an adsorbate into the imperfect MAZE-sim

Parameters

• adsorbate – Adsorbate object

• ads_name – name of the adsorbate

Returns

a copy of imperfect MAZE-sim with the adsorabte added

needs_cap(atom_index: int, bonds_needed: int) → bool

Finds if an atom needs a cap

Parameters

• atom_index – index of atom to check for cap

• bonds_needed – number of bonds an atom needs

Returns

boolean stating if an atom needs a cap

register_with_parent(parent_zeolite: maze.perfect_zeolite.PerfectZeolite, additions_map: Optional[Dict] = None) → None

Register a tagged zeolite with the parent zeolite/zeolite to register the zeolite with. For this to work the tags of the current zeolite must be equal to the parent indices. :param parent_zeolite: the parent zeolite to register the zeolite with. :type parent_zeolite: PerfectZeolite :param additions_map: Additions map containing addition names and their parent indices :type additions_map: Optional[Dict] :return: None :rtype: None

remove_addition(addition_name, addition_type) → zeolite.Zeolite

Removes an addition to the MAZE-sim

Parameters

• addition_name – name of the addition

• addition_type – the type of additon (h_cap, o_cap, ect.)

Returns

A new MAZE-sim with the additional atoms remvoed

remove_adsorbate(adsorbate: Union[maze.adsorbate.Adsorbate, str]) → zeolite.Zeolite

Removes an existing adsorbate from the Zeolite :param adsorbate: adsorbate object or str :return: new imperfect MAZE-sim with item removed

remove_caps(cap_type: str = 'cap', cap_name: Optional[str] = None) → zeolite.Zeolite

Remove caps from an imperfect MAZE-sim, if no arguments are provided all caps are removed from the Zeolite

Parameters

• cap_type – The type of cap (h_cap, o_cap or cap for both) partial matching will work

• cap_name – The name of the cap

Returns

A copy of self with the caps removed

retag_self() → None

Add tags to the Zeolite that correspond to their main index in the index mapper :return: None :rtype: None

static set_attrs_source(new_z: zeolite.Zeolite, source: zeolite.Zeolite) → None

Set the attributes of a new imperfect MAZE-sim to that of its source

Parameters

• new_z – Newly created zeolite without attributes set

• source – the source from which new_z was created

Returns

None

translate_self(displacement) → zeolite.Zeolite

Returns a copy of self with applied translation :param displacement: atomic positions :type displacement: Iterable :return: new self translatedß :rtype: Zeolite

Perfect Zeolite class

class perfect_zeolite.PerfectZeolite(symbols=None, positions=None, numbers=None, tags=None, momenta=None, masses=None, magmoms=None, charges=None, scaled_positions=None, cell=None, pbc=None, celldisp=None, constraint=None, calculator=None, info=None, velocities=None, site_to_atom_indices=None, atom_indices_to_site=None, additions=None, _is_zeotype=True, ztype=None)

A class that inherits from ase.Atoms, which represents an ‘perfect’ zeolite. If a zeolite is built from a cif file from the zeolite structure database, then the atoms are tagged according to their unique site and the dictionaries site_to_atom_indices and atom_indices_to_site are filled. If not these dictionaries are set to none. This class contains a bunch of static methods for identifying different types of atoms in the zeolite as well as as methods to build an imperfect MAZE-sim from a parent Zeotype class. Imperfect zeotypes have additional functionality and are dependent on a parent MAZE-sim class.

__init__(symbols=None, positions=None, numbers=None, tags=None, momenta=None, masses=None, magmoms=None, charges=None, scaled_positions=None, cell=None, pbc=None, celldisp=None, constraint=None, calculator=None, info=None, velocities=None, site_to_atom_indices=None, atom_indices_to_site=None, additions=None, _is_zeotype=True, ztype=None)

Initialize self. See help(type(self)) for accurate signature.

static _get_available_symbols(atom_list: List[str]) → List[str]

Parameters

atom_list – A list of atom symbols to be excluded from returned list

Returns

a list of all possible atom symbols that do not include items from

the original list

static _get_old_to_new_map(old: ase.atoms.Atoms, new: ase.atoms.Atoms) → Dict[int, int]

Get the index mapping between old and new self. his matching is done by position, so it is essential that the atom positions have not changed. It is also essential that new <= old

Returns

A mapping between old and new

static _read_cif_note_siteJan2021Update(fileobj: str, store_tags=False, primitive_cell=False, subtrans_included=True, fractional_occupancies=True, reader='ase') → Tuple[ase.atoms.Atoms, Dict[str, int], Dict[int, str]]

The helper function used by build_from_cif_with_labels when using an ASE version 3.21.0 or higher. This loads a CIF file using ase.io.cif.parse_cif and then finds the T-site information. After finding the T-site information it then replaces each atom in the T-site with another atom type not found in the cif file. The crystal is then generated and then the resulting atoms object atoms are replaced by the original atoms. The mapping between the T-site names and the atom objects in the final atoms object are recored in two dictionaries.

A note about capability: ASE Version 3.21.0 released Jan 18, 2021 refactored the cif reading functions on on which the older function relies. The major change (from this function’s perspective) is that ase.io.cif.parse_cif now returns a generator rather than a list, which contains a CIFBlock object.

Parameters

• fileobj – CIF file location

• store_tags – store the tags in resulting atoms object

• primitive_cell – An option for the reader

• subtrans_included – An option for the reader

• fractional_occupancies – an option for the final crystal

• reader – the reader used (ase works others have not been tested)

Returns

atoms, site_to_atom_indices, atom_indices_to_site

static _read_cif_note_sites(fileobj, store_tags=False, primitive_cell=False, subtrans_included=True, fractional_occupancies=True, reader='ase') → Tuple[ase.atoms.Atoms, Dict[str, int], Dict[int, str]]

The helper function used by build_from_cif_with_labels. This loads a CIF file using ase.io.cif.parse_cif and then finds the T-site information. After finding the T-site information it then replaces each atom in the T-site with another atom type not found in the cif file. The crystal is then generated and then the resulting atoms object atoms are replaced by the original atoms. The mapping between the T-site names and the atom objects in the final atoms object are recored in two dictionaries.

Parameters

• fileobj – CIF file location

• store_tags – store the tags in resulting atoms object

• primitive_cell – An option for the reader

• subtrans_included – An option for the reader

• fractional_occupancies – an option for the final crystal

• reader – the reader used (ase works others have not been tested)

Returns

atoms, site_to_atom_indices, atom_indices_to_site

build_additions_map()

Build a serializable additions map that can be used to rebuild the Zeolite from file :return: additions map :rtype: Dict

classmethod build_from_cif_with_labels(filepath: str, **kwargs) → perfect_zeolite.PerfectZeolite

Takes a filepath/fileobject of a cif file and returns a Zeotype or child class with T-sites labeled as specified in the cif file. The dictionaries for T site labels are also filled in these map from the T-site to a list of atom indices. The atom indices to t sites maps atom indices to T-sites.

Parameters

filepath – Filepath of the cif file

Returns

Zeotype with labeled sites

static count_atomtypes(atomtype_list: List[str]) → Tuple[Dict[str, List[int]], Dict[str, int]]

Counts the number of different atoms of each type in a list of atom symbols

Parameters

atomtype_list – A list of atom chemical symbols

Returns

A tuple of two dictionaries the first containing a mapping between the chemical symbol and the indices in the symbol and the second containing a mapping between the chemical symbol and the number of symbols of that type in the input list

count_elements() → Tuple[Dict[str, List[int]], Dict[str, int]]

Returns

a dictionary where the key is the element symbol and the value is the number in the MAZE-sim

extend(other)

This extends the current Zeotype with additional atoms :param other: atoms like object to extend with :type other: Atoms :return: None :rtype: None

get_atom_types() → Dict[str, List[int]]

Returns

Returns a dictionary of atom types where the key consists of the atom category

(framework, adsorbate, extraframework or other) followed by -atom chemical symbol. For example a Sn atom is a framework atom so the key is “framework-Sn”. The value of the returned dictionary is a list of the indices of all of the atoms that belong to the category.

get_hetero_atoms(hetero_atoms_list: Optional[List[str]] = None) → List[int]

Returns

Returns a list of all of the hetero-atoms in the MAZE-sim

static get_indices(atoms_object: ase.atoms.Atoms) → List[int]

Get the indices in an atoms object

Parameters

atoms_object – Atoms object to get Indices of

Returns

List of indices in Atoms object

static get_indices_compliment(zeotype: perfect_zeolite.PerfectZeolite, indices: Iterable[int]) → List[int]

Gets the compliment of indices in a Zeotype

Parameters

• zeotype – Zeotype containing all indices

• indices – Indices to get the compliment of

Returns

Compliment of indices

get_site_type(index: int) → str

Get the identity of a site

Parameters

index – Index of site in self

Returns

Label for the site (comes from CIF) file

classmethod make(iza_code: str, data_dir='data')

Builds an Zeolite from iza code :param iza_zeolite_code: zeolite iza code :type iza_zeolite_code: str :return: An imperfect zeolite class or subclass :rtype: cls

pop(index: int = - 1)

This removes :param index: index to pop :type index: int :return: Atom :rtype: Atom

update_nl(mult: float = 1) → None

Builds and updates neighborlist :param mult: The mult (multiply) parameter for natural cutoffs (Default 1) :return: None

Adsorbate class

class adsorbate.Adsorbate(symbols=None, positions=None, numbers=None, tags=None, momenta=None, masses=None, magmoms=None, charges=None, scaled_positions=None, cell=None, pbc=None, celldisp=None, constraint=None, calculator=None, info=None, velocities=None, host_zeotype=None, name='', description='')

This is an adsorbate class which represents an adsorbate

__init__(symbols=None, positions=None, numbers=None, tags=None, momenta=None, masses=None, magmoms=None, charges=None, scaled_positions=None, cell=None, pbc=None, celldisp=None, constraint=None, calculator=None, info=None, velocities=None, host_zeotype=None, name='', description='')

Initialize self. See help(type(self)) for accurate signature.

avg_distance(ads_position)

average distance from position to all host atoms :param ads_position: np.array x,y,z of adsorbate position :return: float, average distance of host MAZE-sim atoms to adsorbate position

Args:

ads_position:

find_best_place(index, radius, cutoff, num_pts=500)

picks the best location to place an adsorbate around the host atom :param index: index of host atom at center :param radius: radius around host atom to tests points :param cutoff: minimum distance from other host atoms allowed for tests points :param num_pts: number of points to try :return: array. x,y,z position of best location

Args:

index: radius: cutoff: num_pts:

find_void(void_position_guess)

finds nearest empty region in host MAZE-sim :param void_position_guess: An initial guess for the center of the void as a np.array with x,y,z position :return: np.array position of center of empty void

Args:

void_position_guess:

get_donor_vec(donor_index)

finds direction of lone pair electrons on an adsorbate donor atom :return: vector direction of donor atoms

Args:

donor_index:

get_viable_pos_cluster_centers(index, radius, cutoff, num_pts=None)

finds positions near host atom far enough from other framework atoms, clusters these viable positions and returns the centers of these clusters. If number of points is too small will return error :param index: index of host atom at center :param radius: radius around host atom to tests points :param cutoff: minimum distance from other host atoms allowed for tests points :param num_pts: number of points to try :return: list. center positions of clusters of points which meet criteria

Args:

index: radius: cutoff: num_pts:

get_viable_positions(index, radius, cutoff, num_pts=None)

finds positions near host atom far enough from other framework atoms. :param index: index of host atom at center :param radius: radius around host atom to tests points :param cutoff: minimum distance from other host atoms allowed for tests points :param num_pts: number of points to try :return: list. positions of points which meet cutoff criteria

Args:

index: radius: cutoff: num_pts:

min_distance(ads_position) → float

minimum distance from atom in a host to adsorbate :param ads_position: np.array x,y,z of adsorbate position :return: float, minimum distance between an atom in host MAZE-sim and adsorbate position

Args:

ads_position:

pick_ads_position(donor_ind, host_ind, radius=None, cutoff=None)

Finds a good position to add adsorbate to host :param donor_ind: index of donor atom on adsorbate :param host_ind: index of host binding site :param radius: distance between host atom and donor atom :param cutoff: minimum distance donor atom must be from host atoms :return: vector of best position to place adsorbate

Args:

donor_ind: host_ind: radius: cutoff:

pick_donor()

finds atom in adsorbate most likely to bind to metal Heuristic: N > O > P > S > X > C > H :param ads: adsorbate atoms object :return: index of donor atom in adsorbate

pick_host_atom() → int

picks element with largest atomic number higher than 14 (Si) if one exists. If none exist,

pick Al as a donor atom.

Returns:

index of host atom

position_ads(donor_ind=None, host_ind=None, pos=None) → adsorbate.Adsorbate

Rotates and positions adsorbate according to specified parameters if no parameters are provided, a reasonable position is found :param pos: vector, the position to place adsorbate’s donor atom :param host_ind: integer, index of site in host which adsorbate will be bound :param donor_ind: integer, index of donor atom on adsorbate :return: atoms object with adsorbate in host

Args:

donor_ind: host_ind: pos:

static sphere_sample(radius, num_pts=500)

generates random positions on the surface of a sphere of certain radius :param radius: radius of sphere surface to sample :param num_pts: number of points to try :return: list of x,y,z positions on surface of sphere

Args:

radius: num_pts: