MAZE Modules

Cif Download Module

cif_download.download_cif(code: str, data_dir='data')

Args:

code (str): data_dir:

Zeolite and Cluster Maker Module

class zeolite.ClusterMaker

Bases: abc.ABC

This is an abstract class that selects indices from a Zeolite to return a cluster. Multiple implementations of a cluster maker are possible.

static get_cluster(zeolite: zeolite.Zeolite, indices: Iterable[int], name='Cluster') → zeolite.Zeolite

Get a cluster from a zeolite :param zeolite: Zeolite from which to extract the cluster :type zeolite: Zeolite :param indices: the indices of the zeolite to construct the cluster :type indices: Iterable[int] :param name: the ztype of the created cluster :type name: string :return: The created cluster of type Zeolite :rtype: Zeolite

get_cluster_indices(zeolite: maze.perfect_zeolite.PerfectZeolite, start_site: int, **kwargs) → List[int]

Get the cluster indices of a zeo :param zeolite: zeolite to select the cluster from :type zeolite: Zeolite :param start_site: the start site (usually a T-site) from which to select the indices :type start_site: int :param kwargs: additional keyword arguments needed for other functions :type kwargs: Dict :return: list of indices :rtype: List[int]

static get_open_defect(zeolite: maze.perfect_zeolite.PerfectZeolite, indices: Iterable[int], name='Open Defect') → zeolite.Zeolite

Get an opendefect object from a zeolite :param zeolite: zeolite from which to get the open defect :type zeolite: Zeolite :param indices: the indices of the cluster (these indices are going to be deleted) :type indices: Iterable[int] :param name: the ztype of the open defect that will be created :type name: str :return: The created opendefect Zeolite :rtype: Zeolite

class zeolite.DefaultClusterMaker

Bases: zeolite.ClusterMaker

This is an implementation of a Cluster Maker that is used if no cluster maker object is specified

get_cluster_indices(zeolite: maze.perfect_zeolite.PerfectZeolite, start_site: int, **kwargs)

Get the cluster indices of a zeo :param zeolite: zeolite to select the cluster from :type zeolite: Zeolite :param start_site: the start site (usually a T-site) from which to select the indices :type start_site: int :param kwargs: additional keyword arguments needed for other functions :type kwargs: Dict :return: list of indices :rtype: List[int]

static get_cluster_indices_all_atoms(zeolite, index: int, max_size: int, max_neighbors: int) → List[int]

get the indices of a cluster from a zeolite when specifying the center atom index and size of the cluster

Parameters

• zeolite – the zeolite from which to build the cluster

• index – the centeral atom index

• max_size – the max number of atoms in the final cluster

• max_neighbors – the max number of neighbors from the starting cluster

Returns

a list of indices

static get_cluster_indices_multi_T_site(zeolite, T_indices: Iterable[int], max_size: int, max_neighbors: int) → List[int]

get the indices of a cluster from a zeolite when specifying the center atom index and size of the cluster

Parameters

• T_indices (Iterable[int]) – Indices of the T site

• zeolite – the zeolite from which to build the cluster

• index – the centeral atom index

• max_size – the max number of atoms in the final cluster

• max_neighbors – the max number of neighbors from the starting cluster

Returns

a list of indices

static get_oh_cluster_indices(zeolite: maze.perfect_zeolite.PerfectZeolite, t_site: int) → List[int]

Create a cluster that only includes one central T site and then Oxygen and Hydrogen atoms. This is different than the other cluster selection methods that take in other :param zeolite: The zeolite from which the cluster indices will be drawn :param t_site: The index of the T site around which the cluster will be built :return: The indices of the new cluster

classmethod get_oh_cluster_multi_t_sites(zeolite: maze.perfect_zeolite.PerfectZeolite, t_sites: Iterable[int]) → List[int]

get an OH cluster with multiple T sites :param zeolite: The MAZE-sim from which to extract the cluster :param t_sites: the central t site :return: A list of indices of the cluster

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)

Bases: maze.perfect_zeolite.PerfectZeolite

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

static build_cap_atoms(cap_atoms_dict: Dict[str, numpy.array]) → ase.atoms.Atoms

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

wrap_self(**wrap_kw) → zeolite.Zeolite

Perfect Zeolite Module

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)

Bases: ase.atoms.Atoms

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.

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

property atom_indices_to_sites

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

property site_to_atom_indices

update_nl(mult: float = 1) → None

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

Index Mapper Module

class index_mapper.IndexMapper(atom_indices: Iterable)

Bases: object

This class maps between the different atoms objects in a MAZE-sim project. It is essential for keeping track of the various

__init__(atom_indices: Iterable) → None

Parameters

atom_indices – A list of atom indices from a Zeotype

_make_none_dict() → Dict[str, None]

Get a dictionary full of None for each name :return: A dictionary full of None for each known name

_reverse_main_index(name: str) → Dict[int, int]

Internal function for making a reverse index map :param name: name of the item to make the key :return:a reverse index map where the indices of name are the key

add_atoms(name: str, new_atom_indices: Iterable[int]) → None

Add new atoms to the dictionary :param name: name of object with new atoms :param new_atom_indices: indices of the new atoms :return:

delete_atoms(name: str, atom_indices_to_delete: Iterable[int]) → None

Parameters

• name – name of with indices to delete

• atom_indices_to_delete – indices to delete

Returns

None

delete_name(name: str) → None

Delete zeolite from the index :param name: The name of the zeolite to delete from the index :return: None

extend(name: str, new_atom_indices: Iterable[int]) → None

This adds additional atom indices to the zeolite :param name: name to add indices to :type name: str :param new_atom_indices: list of indices :type new_atom_indices: Iterable[int] :return: None :rtype: None

static get_id()

Get a unique id :return:

get_index(sender_name: str, receiver_name: str, sender_index: int) → int

get the index of another object :param sender_name: name of the sender zeolite :param receiver_name: the name of the receiving zeolite :param sender_index: the index of the sender :return: the receiving index

get_name1_to_name2_map(name1: str, name2: str) → Dict[int, int]

Gets a map between the indices of name1 and the indices of name2 :param name1: name whose indices are the key in the map :param name2: name whose indices are the value in the map :return: name1.index -> name2.index map

get_overlap(name1: str, name2: str) → List[int]

Get the list of names that overlap :param name1: name of object 1 :param name2: name of object 2 :return: overlapping indices

get_reverse_main_index(name: str) → Dict[int, int]

Reverses an index so that the name indices are used as a key for the main index :param name: name of the item to make the key :return: a reverse index map where the indices of name are the key

static get_unique_name(name: str)

Get a unique name :param name: name :return: name + _ + unique id number

id = 0

pop(name: str, atom_index_to_delete: int) → int

Deletes a single atom index :param name: name of Zeotype to delete atom :type name: str :param atom_index_to_delete: index to delete (using own mapping) :type atom_index_to_delete: int :return: index deleted :rtype: int

register(old_name: str, new_name: str, old_to_new_map: Dict[int, int]) → None

Register a new object with the indexer :param old_name: name of object known by the indexer :param new_name: name of new object being registered :param old_to_new_map: a index mapping between the old map and the new map note that additional atoms in new will be added to the index :return:

register_with_main(new_name: str, main_to_new_map: Dict[int, int]) → None

Register a new object by using the main index in mapping. :param new_name: name of the new object being registered :param main_to_new_map: :return:

reregister_parent(main_to_parent_map) → None

Register a Zeolite as the parent using a main_to_parent_map This is useful when building a Perfect Zeolite from a file. :param main_to_parent_map: dict that maps between parent and the main indices :type main_to_parent_map: Dict[int, int] :return: None :rtype: None