nanoCAT.recipes.mark_surface

A recipe for identifying surface-atom subsets.

Index

replace_surface(mol, symbol[, symbol_new, ...])

A workflow for identifying all surface atoms in mol and replacing a subset of them.

API

nanoCAT.recipes.replace_surface(mol, symbol, symbol_new='Cl', nth_shell=0, f=0.5, mode='uniform', displacement_factor=0.5, **kwargs)[source]

A workflow for identifying all surface atoms in mol and replacing a subset of them.

Consists of three distinct steps:

Identifying which atoms, with a user-specified atomic symbol, are located on the surface of mol rather than in the bulk.
Define a subset of the newly identified surface atoms using one of CAT’s distribution algorithms.
Create and return a molecule where the atom subset defined in step 2 has its atomic symbols replaced with symbol_new.

Examples

Replace 75% of all surface "Cl" atoms with "I".

>>> from scm.plams import Molecule
>>> from CAT.recipes import replace_surface

>>> mol = Molecule(...)  # Read an .xyz file
>>> mol_new = replace_surface(mol, symbol='Cl', symbol_new='I', f=0.75)
>>> mol_new.write(...)  # Write an .xyz file

The same as above, except this time the new "I" atoms are all deleted.

>>> from scm.plams import Molecule
>>> from CAT.recipes import replace_surface

>>> mol = Molecule(...)  # Read an .xyz file
>>> mol_new = replace_surface(mol, symbol='Cl', symbol_new='I', f=0.75)

>>> del_atom = [at for at in mol_new if at.symbol == 'I']
>>> for at in del_atom:
...     mol_new.delete_atom(at)
>>> mol_new.write(...)  # Write an .xyz file

Parameters:

mol (Molecule) – The input molecule.
symbol (str or int) – An atomic symbol or number defining the super-set of the surface atoms.
symbol_new (str or int) – An atomic symbol or number which will be assigned to the new surface-atom subset.
nth_shell (int or Iterable [int]) – One or more integers denoting along which shell-surface(s) to search. For example, if symbol = "Cd" then nth_shell = 0 represents the surface, nth_shell = 1 is the first sub-surface "Cd" shell and nth_shell = 2 is the second sub-surface "Cd" shell. Using nth_shell = [1, 2] will search along both the first and second "Cd" sub-surface shells. Note that a Zscm.plams.core.errors.MoleculeError will be raised if the specified nth_shell is larger than the actual number of available sub-surface shells.
f (float) – The fraction of surface atoms whose atom types will be replaced with symbol_new. Must obey the following condition: \(0 < f \le 1\).
mode (str) –
How the subset of surface atoms will be generated. Accepts one of the following values:
- "random": A random distribution.
- "uniform": A uniform distribution; maximizes the nearest-neighbor distance.
- "cluster": A clustered distribution; minimizes the nearest-neighbor distance.
displacement_factor (float) –
The smoothing factor \(n\) for constructing a convex hull; should obey \(0 <= n <= 1\). Represents the degree of displacement of all atoms with respect to a spherical surface; \(n = 1\) is a complete projection while \(n = 0\) means no displacement at all.

A non-zero value is generally recomended here, as the herein utilized ConvexHull class requires an adequate degree of surface-convexness, lest it fails to properly identify all valid surface points.
**kwargs (Any) – Further keyword arguments for distribute_idx().

Returns:

A new Molecule with a subset of its surface atoms replaced with symbol_new.

Return type:

Molecule