# 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:

1. Identifying which atoms, with a user-specified atomic symbol, are located on the surface of mol rather than in the bulk.

2. Define a subset of the newly identified surface atoms using one of CAT’s distribution algorithms.

3. 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

distribute_idx()

Create a new distribution of atomic indices from idx of length f * len(idx).

identify_surface()

Take a molecule and identify which atoms are located on the surface, rather than in the bulk.

identify_surface_ch()

Identify the surface of a molecule using a convex hull-based approach.