HTMACat.catkit.gen package

Subpackages

• HTMACat.catkit.gen.utils package
  • Submodules
  • HTMACat.catkit.gen.utils.connectivity module
    • get_cutoff_neighbors()
    • get_voronoi_neighbors()
  • HTMACat.catkit.gen.utils.coordinates module
    • expand_cell()
    • get_integer_enumeration()
    • get_unique_coordinates()
    • get_unique_xy()
    • matching_coordinates()
    • matching_sites()
    • trilaterate()
  • HTMACat.catkit.gen.utils.graph module
    • connectivity_to_edges()
    • isomorphic_molecules()
  • HTMACat.catkit.gen.utils.utilities module
    • ext_gcd()
    • get_atomic_numbers()
    • get_reference_energies()
    • list_gcd()
    • parse_slice()
    • running_mean()
    • to_gratoms()
  • HTMACat.catkit.gen.utils.utils_mdnm module
    • mol_to_graph()
    • solve_normal_vector_linearsvc()
  • HTMACat.catkit.gen.utils.vectors module
    • get_basis_vectors()
    • get_reciprocal_vectors()
    • plane_normal()
  • Module contents
    • connectivity_to_edges()
    • expand_cell()
    • ext_gcd()
    • get_atomic_numbers()
    • get_basis_vectors()
    • get_cutoff_neighbors()
    • get_integer_enumeration()
    • get_reciprocal_vectors()
    • get_reference_energies()
    • get_unique_coordinates()
    • get_unique_xy()
    • get_voronoi_neighbors()
    • isomorphic_molecules()
    • list_gcd()
    • matching_coordinates()
    • matching_sites()
    • mol_to_graph()
    • parse_slice()
    • plane_normal()
    • running_mean()
    • solve_normal_vector_linearsvc()
    • to_gratoms()
    • trilaterate()

Submodules

HTMACat.catkit.gen.adsorption module

class HTMACat.catkit.gen.adsorption.AdsorptionSites(slab, surface_atoms=None, tol=1e-05)

Bases: object

Adsorption site object.

Methods

ex_sites(index[, select, cutoff])	Get site indices inside or outside of a cutoff radii from a provided periodic site index.
get_adsorption_edges([symmetric, periodic])	Return the edges of adsorption sties defined as all regions with adjacent vertices.
get_adsorption_vectors([unique, screen])	Returns the vectors representing the furthest distance from the neighboring atoms.
get_connectivity([unique])	Return the number of connections associated with each site.
get_coordinates([unique])	Return the 3D coordinates associated with each site.
get_periodic_sites([screen])	Return an index of the coordinates which are unique by periodic boundary conditions.
get_symmetric_sites([unique, screen])	Determine the symmetrically unique adsorption sites from a list of fractional coordinates.
get_topology([unique])	Return the indices of adjacent surface atoms.
plot([savefile])	Create a visualization of the sites.

ex_sites(index, select='inner', cutoff=0)

Get site indices inside or outside of a cutoff radii from a provided periodic site index.

If two sites are provided, an option to return the mutually inclusive points is also available.

get_adsorption_edges(symmetric=True, periodic=True)

Return the edges of adsorption sties defined as all regions with adjacent vertices.

Parameters:

symmetricbool

Return only the symmetrically reduced edges.

periodicbool

Return edges which are unique via periodicity.

Returns:

edgesndarray (n, 2)

All edges crossing ridge or vertices indexed by the expanded unit slab.

get_adsorption_vectors(unique=True, screen=True)

Returns the vectors representing the furthest distance from the neighboring atoms.

Returns:

vectorsndarray (n, 3)

Adsorption vectors for surface sites.

get_connectivity(unique=True)

Return the number of connections associated with each site.

get_coordinates(unique=True)

Return the 3D coordinates associated with each site.

get_periodic_sites(screen=True)

Return an index of the coordinates which are unique by periodic boundary conditions.

Parameters:

screenbool

Return only sites inside the unit cell.

Returns:

periodic_matchndarray (n,)

Indices of the coordinates which are identical by periodic boundary conditions.

get_symmetric_sites(unique=True, screen=True)

Determine the symmetrically unique adsorption sites from a list of fractional coordinates.

Parameters:

uniquebool

Return only the unique symmetrically reduced sites.

screenbool

Return only sites inside the unit cell.

Returns:

sitesdict of lists

Dictionary of sites containing index of site

get_topology(unique=True)

Return the indices of adjacent surface atoms.

plot(savefile=None)

Create a visualization of the sites.

class HTMACat.catkit.gen.adsorption.Builder(slab, surface_atoms=None, tol=1e-05)

Bases: AdsorptionSites

Initial module for creation of 3D slab structures with attached adsorbates.

Methods

add_adsorbate(adsorbate[, bonds, index, ...])	Add and adsorbate to a slab.
ex_sites(index[, select, cutoff])	Get site indices inside or outside of a cutoff radii from a provided periodic site index.
get_adsorption_edges([symmetric, periodic])	Return the edges of adsorption sties defined as all regions with adjacent vertices.
get_adsorption_vectors([unique, screen])	Returns the vectors representing the furthest distance from the neighboring atoms.
get_connectivity([unique])	Return the number of connections associated with each site.
get_coordinates([unique])	Return the 3D coordinates associated with each site.
get_periodic_sites([screen])	Return an index of the coordinates which are unique by periodic boundary conditions.
get_symmetric_sites([unique, screen])	Determine the symmetrically unique adsorption sites from a list of fractional coordinates.
get_topology([unique])	Return the indices of adjacent surface atoms.
plot([savefile])	Create a visualization of the sites.

add_adsorbates

add_adsorbate(adsorbate, bonds=None, index=0, auto_construct=True, **kwargs)

Add and adsorbate to a slab. If the auto_constructor flag is False, the atoms object provided will be attached at the active site.

Parameters:

adsorbategratoms object

Molecule to connect to the surface.

bondsint or list of 2 int

Index of adsorbate atoms to be bonded.

indexint

Index of the site or edge to use as the adsorption position. A value of -1 will return all possible structures.

auto_constructbool

Whether to automatically estimate the position of atoms in larger molecules or use the provided structure.

Returns:

slabsgratoms object

Slab(s) with adsorbate attached.

add_adsorbates(adsorbates, indices)

HTMACat.catkit.gen.adsorption.get_adsorption_sites(slab, surface_atoms=None, symmetry_reduced=True, tol=1e-05)

Get the adsorption sites of a slab as defined by surface symmetries of the surface atoms.

Parameters:

slabAtoms object

The slab to find adsorption sites for. Must have surface atoms defined.

surface_atomsarray_like (N,)

List of the surface atom indices.

symmetry_reducedbool

Return the symmetrically unique sites only.

adsorption_vectorsbool

Return the adsorption vectors.

Returns:

coordinatesndarray (N, 3)

Cartesian coordinates of activate sites.

connectivityndarray (N,)

Number of bonds formed for a given adsorbate.

symmetry_indexndarray (N,)

Arbitrary indices of symmetric sites.

HTMACat.catkit.gen.adsorption.symmetry_equivalent_points(fractional_coordinates, atoms, tol=1e-05)

Return the symmetrically equivalent points from a list of provided fractional coordinates.

Parameters:

fractional_coordinatesndarray (N ,3)

Fractional coordinates to find symmetrical equivalence between.

atomsAtoms object

Atoms object to use the unit cell, positions, and pbc of.

tolfloat

Float point precision tolerance.

Returns:

symmetry_matchndarray (N,)

Indices of fractional coordinates which are unique or matching.

HTMACat.catkit.gen.surface module

class HTMACat.catkit.gen.surface.SlabGenerator(bulk, miller_index, layers, vacuum=None, fixed=None, layer_type='ang', attach_graph=True, standardize_bulk=False, primitive=True, tol=1e-08)

Bases: object

Class for generation of slab unit cells from bulk unit cells.

Many surface operations rely upon / are made easier through the bulk basis cell they are created from. The SlabGenerator class is designed to house these operations.

Return the miller indices associated with the users requested values. Follows the following steps:

• Convert Miller-Bravais notation into standard Miller index.

• (optional) Ensure the bulk cell is in its standard form.

• Convert the indices to the cell for the primitive lattice.

• Reduce the indices by their greatest common divisor.

Parameters:

bulkAtoms object

Bulk system to be converted into slab.

miller_indexlist (3,) or (4,)

Miller index to construct surface from. If length 4, Miller-Bravais notation is assumed.

layersint

Number of layers to include in the slab. A slab layer is defined as a unique z-coordinate.

vacuumfloat

Angstroms of vacuum to apply to the slab.

fixedint

Number of slab layers to constrain.

layer_type‘angs’, ‘trim’, ‘stoich’, or ‘sym’

Determines how to perform slab layering.

‘angs’: Layers denotes the thickness of the slab in Angstroms. ‘trim’: The slab will be trimmed to a number of layers equal to the exact number of unique z-coordinates. Useful for precision control. ‘stoich’ : Constraints any slab generated to have the same stoichiometric ratio as the provided bulk. ‘sym’ : Return a slab which is inversion symmetric. i.e. The same on both sides.

attach_graphbool

Attach the connectivity graph generated from the bulk structure. This is only necessary for fingerprinting and setting it to False can save time. Surface atoms will be found regardless.

standardize_bulkbool

Covert the bulk input to its standard form before and produce the cleave from it. This is highly recommended as Miller indices are not defined for non-standard cells.

tolfloat

Tolerance for floating point rounding errors.

Methods

adsorption_sites(slab, **kwargs)	Helper function to return the adsorption sites of the provided slab.
align_crystal(bulk, miller_index)	Return an aligned unit cell from bulk unit cell.
get_slab([size, iterm])	Generate a slab from the bulk structure.
get_slab_basis([iterm, maxn])	Return a list of all terminations which have been properly shifted and with an appropriate number of layers added.
get_unique_terminations()	Determine the fractional coordinate shift that will result in a unique surface termination.
make_symmetric(slab)	Returns a symmetric slab.
set_size(slab, size)	Set the size of a slab based one of three methods.

adsorption_sites(slab, **kwargs)

Helper function to return the adsorption sites of the provided slab.

Parameters:

slabatoms object

The slab to find adsorption sites for. Assumes you are using the same basis.

Returns:

outputtuple (n, n) | (n, n, n)

Coordinates and connectivity of the adsorption sites. The symmetry indices can also be returned.

align_crystal(bulk, miller_index)

Return an aligned unit cell from bulk unit cell. This alignment rotates the a and b basis vectors to be parallel to the Miller index.

Parameters:

bulkAtoms object

Bulk system to be standardized.

miller_indexlist (3,)

Miller indices to align with the basis vectors.

Returns:

new_bulkGratoms object

Standardized bulk unit cell.

get_slab(size=1, iterm=0)

Generate a slab from the bulk structure. This function is meant specifically for selection of an individual termination or enumeration through surfaces of various size.

This function will orthogonalize the c basis vector and align it with the z-axis which breaks bulk symmetry along the z-axis.

Parameters:

sizeint, array_like (2,) or (2, 2)

Size of the unit cell to create as described in set_size().

itermint

A termination index in reference to the list of possible terminations.

Returns:

slabGratoms object

The modified basis slab produced based on the layer specifications given.

get_slab_basis(iterm=0, maxn=20)

Return a list of all terminations which have been properly shifted and with an appropriate number of layers added. This function is mainly for performance, to prevent looping over other operations which are not related the size of the slab.

This step also contains periodically constrained orthogonalization of the c basis. This implementation only works if the a anb b basis vectors are properly aligned with the x and y axis. This is strictly to assist the correct identification of surface atoms.

Only produces the terminations requested as a lazy evaluator.

Parameters:

itermint

Index of the slab termination to return.

maxnint

The maximum integer component to search for a more orthogonal bulk.

Returns:

ibasisGratoms object

Prepared, ith basis.

get_unique_terminations()

Determine the fractional coordinate shift that will result in a unique surface termination. This is not required if bulk standardization has been performed, since all available z shifts will result in a unique termination for a primitive cell.

Returns:

unique_shiftarray (n,)

Fractional coordinate shifts which will result in unique terminations.

make_symmetric(slab)

Returns a symmetric slab.

Note, this will trim the slab potentially resulting in loss of stoichiometry.

set_size(slab, size)

Set the size of a slab based one of three methods.

1. An integer value performs a search of valid matrix operations to perform on the ab-basis vectors to return a set which with a minimal sum of distances and an angle closest to 90 degrees.

2. An array_like of length 2 will multiply the existing basis vectors by that amount.

3. An array of shape (2, 2) will be interpreted as matrix notation to multiply the ab-basis vectors by.

Parameters:

slabAtoms object

Slab to be made into the requested size.

sizeint, array_like (2,) or (2, 2)

Size of the unit cell to create as described above.

Returns:

supercellGratoms object

Supercell of the requested size.

HTMACat.catkit.gen.surface.convert_miller_index(miller_index, atoms1, atoms2)

Return a converted miller index between two atoms objects.

HTMACat.catkit.gen.surface.generate_indices(max_index)

Return an array of miller indices enumerated up to values plus or minus some maximum. Filters out lists with greatest common divisors greater than one. Only positive values need to be considered for the first index.

Parameters:

max_indexint

Maximum number that will be considered for a given surface.

Returns:

unique_indexndarray (n, 3)

Unique miller indices

HTMACat.catkit.gen.surface.get_degenerate_indices(bulk, miller_index)

Return the miller indices which are degenerate to a given miller index for a particular bulk structure.

Parameters:

bulkAtoms object

Bulk structure to get the degenerate miller indices.

miller_indexarray_like (3,)

Miller index to get the degenerate indices for.

Returns:

degenerate_indicesarray (N, 3)

Degenerate miller indices to the provided index.

HTMACat.catkit.gen.surface.get_unique_indices(bulk, max_index)

Returns an array of miller indices which will produce unique surface terminations based on a provided bulk structure.

Parameters:

bulkAtoms object

Bulk structure to get the unique miller indices.

max_indexint

Maximum number that will be considered for a given surface.

Returns:

unique_millersndarray (n, 3)

Symmetrically distinct miller indices for a given bulk.

HTMACat.catkit.gen.surface.transform_ab(slab, matrix, tol=1e-05)

Transform the slab basis vectors parallel to the z-plane by matrix notation. This can result in changing the slabs cell size. This can also result in very unusual slab dimensions, use with caution.

Parameters:

slabAtoms object

The slab to be transformed.

matrixarray_like (2, 2)

The matrix notation transformation of the a and b basis vectors.

tolfloat

Float point precision tolerance.

Returns:

slabAtoms object

Slab after transformation.

HTMACat.catkit.gen.symmetry module

class HTMACat.catkit.gen.symmetry.Symmetry(atoms, tol=1e-05, ang_tol=-1)

Bases: object

Wrapper for the spglib package.

Methods

get_lattice_name()	Return the lattice name of an atoms object based on its spacegroup number: https://en.wikipedia.org/wiki/List_of_space_groups.
get_pointgroup([check_laue])	Return the point group operations of a systems.
get_symmetry_operations([affine])	Return the symmetry operations for a given atomic structure.

get_lattice_name()

Return the lattice name of an atoms object based on its spacegroup number: https://en.wikipedia.org/wiki/List_of_space_groups.

Returns:

latticestr

The name of the structures lattice.

get_pointgroup(check_laue=False)

Return the point group operations of a systems.

Parameters:

check_lauebool

Return if the pointgroup is a laue symmetry.

Returns:

pointgroupstr

The pointgroup symmetry of the atomic structure.

is_lauebool

Whether the pointgroup is a laue symmetry.

get_symmetry_operations(affine=True)

Return the symmetry operations for a given atomic structure.

Parameters:

affinebool

Whether to return the affine matrix operations.

Returns:

rotationsndarray (N, 3, 3)

Rotation matices of the symmetry operations.

translations ndarray (N, 3)

Translation vector components of the symmetry operations.

affine_matrices ndarray (N, 4, 4)

Affine matrix operations, combinations of the rotation and translation with ones along the diagonal.

HTMACat.catkit.gen.symmetry.get_modified_spin_symbols(numbers, magmoms)

Return a representation of atomic symbols which is unique to the magnetic moment as well.

This is effectivly creating a single integer which contains the atomic number and the magnetic moment multiplied by 10.

Parameters:

numbersndarray (N,)

Atomic numbers to be joined with the magnetic moments.

magmomsndarray (N,)

Magnetic moments to be joined to the atomic numbers.

Returns:

spin_mod_symbolsndarray (N,)

The spin modified symbols representation for each atom.

HTMACat.catkit.gen.symmetry.get_standardized_cell(atoms, primitive=False, tol=1e-05)

Atoms object interface with spglib primitive cell finder: https://atztogo.github.io/spglib/python-spglib.html#python-spglib.

The function also builds in limited functionality for initial magnetic moments. Only integer values are supported.

Parameters:

atomsobject

Atoms object to search for a primitive unit cell.

primitivebool

Reduce the atoms object into a primitive form.

tolfloat

Tolerance for floating point rounding errors.

Returns:

primitive cellobject

The primitive unit cell returned by spglib if one is found.

HTMACat.catkit.gen.symmetry.get_unmodified_spin_symbols(spin_mod_symbols)

Return the origional atomic numbers and magnetic moments from the get_modified_spin_symbols function.

Parameters:

spin_mod_symbolsndarray (N,)

Joint symbol and spin representation of an atomic structure.

Returns:

symbolsndarray (N,)

The origional atomic numbers of the atoms object.

magmomsndarray (N,)

The magnetic moments of the origional atoms object.

Module contents

Catalysis Generator.