Sites

The Sites class help make graphs for modifiers to work on and also determine the surface site for modifications.

FlexibleSites

This is a simple sites class which returns either atoms which arent constrained as surface sites or you can specify specific index. Hardcoding of indexes isnt advisable as the atoms object changes during gcbh runs.

from gg.predefined_sites import FlexibleSites

FS = FlexibleSites(constraints=True,max_bond_ratio=1.2) #Define class to figure out surface

atoms = read("POSCAR")
list_sites = FS.get_sites(atoms)

Common usage patterns

  • Use constraints=True when the slab is fixed with ase.constraints.FixAtoms.

  • Use tag/opp_tag to include or exclude atoms with a specific tag (e.g., tag surface atoms in your input file).

  • Use com (e.g., com=0.6) to focus on atoms above the center of mass for clusters or slabs.

class gg.predefined_sites.FlexibleSites(constraints: bool = False, index: list[int] | None = None, tag: int | None = None, opp_tag: bool = False, com: float | None = None, max_bond_ratio: float | None = 1.2, max_bond: float | None = 0, contact_error: float | None = 0.3)[source]

Bases: Sites

Args:

constraints (bool, optional): If True, only unconstrained atoms are considered. Defaults to False. index (List[int], optional): A list of specific atom indices to consider. Defaults to None.

tag (int, optional): If provided, only atoms with this tag are considered. Defaults to None.

opp_tag (bool, optional): If True, considers atoms without the specified tag. Defaults to False.

com (float, optional): If provided, considers atoms above the center of mass (COM)

in the z-direction. The value determines the fraction of the z-range above the COM to consider. Defaults to None.

max_bond_ratio (float, optional): Tolerance for bond distances. Defaults to 1.2.

max_bond (float, optional): Maximum bond distance. Defaults to 0 (no limit).

contact_error (float, optional): Tolerance for atoms being too close. Defaults to 0.2.

get_sites(atoms: Atoms) → list[int][source]

Identifies sites based on the specified rules.

Args:

atoms (Atoms): The ASE Atoms object.

Returns:

List[int]: List of atom indices identified as sites.

SurfaceSites

This class uses co-ordination number to determine the surface sites. However, we need to specify the maximum co-ordination allowed for each atom.

from gg.predefined_sites import SurfaceSites

max_coord = {"Pt": 12, "O": 4, "H": 2}
SS = SurfaceSites(max_coord=max_coord,max_bond_ratio=1.2) #Define class to figure out surface

atoms = read("POSCAR")
list_sites = SS.get_sites(atoms)

Notes

  • com expects a fraction (e.g., 0.1 keeps atoms above the COM by 10% of the z-range).

  • Set com=None to keep all atoms regardless of height.

class gg.predefined_sites.SurfaceSites(max_coord: dict, max_bond_ratio: float | None = 1.2, max_bond: float | None = 0, contact_error: float | None = 0.3, com: bool | None = 0.1)[source]

Bases: Sites

Args: max_coord (dict): Dictionary of the maximum coordination of each element used. Only atoms with coordination less than this value will be considered.

max_bond_ratio (float): Tolerance in the sum of covallent radii between two atoms to be considered a bond. Defaults to 1.2 (equivalent to 20% tolerance)

max_bond (float): Maximum distance of a bond allowed, ignored if equal to zero. Defaults to 0

Contact Error (float): To ensure atoms arent too close to each other, the fraction of tolerance allowed. Defaults to 0.2 (equivalent to 20% tolerance)

com (Optional[bool], optional): If true atoms below the center of mass are ignored Defaults to True.

get_sites(atoms: Atoms, self_interaction: bool = False, bothways: bool = True) → list[source]
Args:

atoms (ase.Atoms): Atoms object to determine sites.

self_interaction (bool): Input of ase.neighborlist. Defaults to True.

bothways (bool): Input of ase.neighborlist. Defaults to False.

Returns:

list: list of atoms index considered for modifications.

RuleSites

This class can define complex Sites based on user defined rules.

from gg.sites import RuleSites, get_com_sites, get_surface_sites_by_coordination

#Define maximum co-odrination each species can have
max_coord = {"Al": 6, "Si": 4, "O": 4, "H": 1}

ss = RuleSites(
    index_parsers=[
        lambda atoms: get_com_sites(atoms, fraction=0.50, direction="above"),
        lambda atoms: get_surface_sites_by_coordination(
            atoms, max_coord, max_bond=2,
        ),
    ],
    combine_rules="intersection",
)
class gg.sites.RuleSites(index_parsers: Callable[[Atoms], list] | List[Callable[[Atoms], list]] | None = None, combine_rules: str = 'union', max_bond_ratio: float | None = 1.2, max_bond: float | None = 0, contact_error: float | None = 0.3)[source]
Args:

index_parsers (Union[Callable[[Atoms], list], List[Callable[[Atoms], list]]], optional): A single rule or a list of rules (functions) that take an Atoms object of indices representing the sites of interest. Defaults to a function that returns all indices. combine_rules (str, optional):How to combine the results of multiple rules. Options are:

  • “union”: Combine results using set union (default).

  • “intersection”: Combine results using set intersection.

Defaults to “union”.

max_bond_ratio (float, optional): While making bonds, how much error is allowed.

Defaults to 1.2.

max_bond (float, optional): Fixed bond distance to use, any distance above is ignored.

Defaults to 0. If 0, it is ignored.

contact_error (float, optional): Error allowed if atoms are too close to each other.

Defaults to 0.2.

members:

undoc-members:

show-inheritance: