%% Generated by Sphinx.
\def\sphinxdocclass{report}
\documentclass[letterpaper,10pt,english]{sphinxmanual}
\ifdefined\pdfpxdimen
   \let\sphinxpxdimen\pdfpxdimen\else\newdimen\sphinxpxdimen
\fi \sphinxpxdimen=.75bp\relax

\PassOptionsToPackage{warn}{textcomp}
\usepackage[utf8]{inputenc}
\ifdefined\DeclareUnicodeCharacter
% support both utf8 and utf8x syntaxes
  \ifdefined\DeclareUnicodeCharacterAsOptional
    \def\sphinxDUC#1{\DeclareUnicodeCharacter{"#1}}
  \else
    \let\sphinxDUC\DeclareUnicodeCharacter
  \fi
  \sphinxDUC{00A0}{\nobreakspace}
  \sphinxDUC{2500}{\sphinxunichar{2500}}
  \sphinxDUC{2502}{\sphinxunichar{2502}}
  \sphinxDUC{2514}{\sphinxunichar{2514}}
  \sphinxDUC{251C}{\sphinxunichar{251C}}
  \sphinxDUC{2572}{\textbackslash}
\fi
\usepackage{cmap}
\usepackage[T1]{fontenc}
\usepackage{amsmath,amssymb,amstext}
\usepackage{babel}



\usepackage{times}
\expandafter\ifx\csname T@LGR\endcsname\relax
\else
% LGR was declared as font encoding
  \substitutefont{LGR}{\rmdefault}{cmr}
  \substitutefont{LGR}{\sfdefault}{cmss}
  \substitutefont{LGR}{\ttdefault}{cmtt}
\fi
\expandafter\ifx\csname T@X2\endcsname\relax
  \expandafter\ifx\csname T@T2A\endcsname\relax
  \else
  % T2A was declared as font encoding
    \substitutefont{T2A}{\rmdefault}{cmr}
    \substitutefont{T2A}{\sfdefault}{cmss}
    \substitutefont{T2A}{\ttdefault}{cmtt}
  \fi
\else
% X2 was declared as font encoding
  \substitutefont{X2}{\rmdefault}{cmr}
  \substitutefont{X2}{\sfdefault}{cmss}
  \substitutefont{X2}{\ttdefault}{cmtt}
\fi


\usepackage[Bjarne]{fncychap}
\usepackage{sphinx}

\fvset{fontsize=\small}
\usepackage{geometry}


% Include hyperref last.
\usepackage{hyperref}
% Fix anchor placement for figures with captions.
\usepackage{hypcap}% it must be loaded after hyperref.
% Set up styles of URL: it should be placed after hyperref.
\urlstyle{same}


\usepackage{sphinxmessages}
\setcounter{tocdepth}{1}



\title{ACAT}
\date{Mar 03, 2021}
\release{1.0.0}
\author{Shuang Han}
\newcommand{\sphinxlogo}{\vbox{}}
\renewcommand{\releasename}{Release}
\makeindex
\begin{document}

\pagestyle{empty}
\sphinxmaketitle
\pagestyle{plain}
\sphinxtableofcontents
\pagestyle{normal}
\phantomsection\label{\detokenize{index::doc}}


Welcome to ACAT documentation!

ACAT is a Python package for atomistic modelling of metal / alloy catalysts used in heterogeneous catalysis. The package is based on automatic identifications of adsorption sites and adsorbate coverages on surface slabs and nanoparticles. Synergized with ASE, ACAT provides useful tools for building atomistic models of alloy catalysts with and without adsorbates. The goal is to automate workflows so that the structure generations can be readily adapted in a global optimization.

ACAT has been developed by Shuang Han at the Section of Atomic Scale Materials Modelling, Department of Energy Conversion and Storage, Technical University of Denmark (DTU) in Lyngby, Denmark. The development is hosted on \sphinxhref{https://gitlab.com/shuanghan/acat.git}{gitlab}.


\chapter{Gallery}
\label{\detokenize{index:gallery}}
Various shapes and facets of nanoparticles identified by ACAT:

\noindent{\hspace*{\fill}\sphinxincludegraphics{{color_facets}.png}\hspace*{\fill}}

All unique adsorptions sites (in red) identified by ACAT on truncated octahedron (top left), fcc(311) surface (top right), hcp(10\sphinxhyphen{}10) surface (bottom left) and bcc(110) surface (bottom right):

\noindent{\hspace*{\fill}\sphinxincludegraphics[scale=0.5]{{unique_sites}.png}\hspace*{\fill}}

Well\sphinxhyphen{}defined adsorbate coverage patterns for various surfaces and nanoparticles generated by ACAT:

\noindent{\hspace*{\fill}\sphinxincludegraphics{{all_coverage_patterns}.png}\hspace*{\fill}}


\chapter{Contents}
\label{\detokenize{index:contents}}\phantomsection\label{\detokenize{installation:installation}}
\index{Installation@\spxentry{Installation}}\ignorespaces 

\section{Installation}
\label{\detokenize{installation:index-0}}\label{\detokenize{installation:id1}}\label{\detokenize{installation::doc}}

\subsection{Installing via pip}
\label{\detokenize{installation:installing-via-pip}}
In the most simple case, ACAT can be simply installed
via pip:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYGZdl{} pip install acat \PYGZhy{}\PYGZhy{}user
\end{sphinxVerbatim}


\subsection{Cloning the repository}
\label{\detokenize{installation:cloning-the-repository}}
If you want to get the absolutely latest version you can clone the
repo:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYGZdl{} git clone https://gitlab.com/shuanghan/acat.git
\end{sphinxVerbatim}

and then install ACAT via:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYGZdl{} cd acat/
\PYGZdl{} python3 setup.py install \PYGZhy{}\PYGZhy{}user
\end{sphinxVerbatim}

in the root directory. This will set up ACAT as a Python module
for the current user.


\subsection{Requirements}
\label{\detokenize{installation:requirements}}
ACAT requires Python3.6+ and depends on the following libraries
\begin{itemize}
\item {} 
\sphinxhref{https://wiki.fysik.dtu.dk/ase}{ASE}

\item {} 
\sphinxhref{https://wiki.fysik.dtu.dk/asap}{ASAP}

\item {} 
\sphinxhref{https://networkx.org}{NetworkX}

\end{itemize}

You can simply install these libraries via pip:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYGZdl{} pip install ase asap3 networkx \PYGZhy{}\PYGZhy{}user
\end{sphinxVerbatim}


\section{Base modules}
\label{\detokenize{modules:base-modules}}\label{\detokenize{modules::doc}}

\subsection{Adsorption sites}
\label{\detokenize{modules:module-acat.adsorption_sites}}\label{\detokenize{modules:adsorption-sites}}\index{module@\spxentry{module}!acat.adsorption\_sites@\spxentry{acat.adsorption\_sites}}\index{acat.adsorption\_sites@\spxentry{acat.adsorption\_sites}!module@\spxentry{module}}\index{ClusterAdsorptionSites (class in acat.adsorption\_sites)@\spxentry{ClusterAdsorptionSites}\spxextra{class in acat.adsorption\_sites}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorption_sites.ClusterAdsorptionSites}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class }}\sphinxcode{\sphinxupquote{acat.adsorption\_sites.}}\sphinxbfcode{\sphinxupquote{ClusterAdsorptionSites}}}{\emph{\DUrole{n}{atoms}}, \emph{\DUrole{n}{allow\_6fold}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{composition\_effect}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{label\_sites}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{proxy\_metal}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{tol}\DUrole{o}{=}\DUrole{default_value}{0.5}}}{}
Bases: \sphinxcode{\sphinxupquote{object}}

Base class for identifying adsorption sites on a nanoparticle.
Support common nanoparticle shapes including: Mackay icosahedron,
(truncated) octahedron and (Marks) decahedron.

The information of each site is stored in a dictionary with the
following keys:

\sphinxstylestrong{‘site’}: the site type, support ‘ontop’, ‘bridge’, ‘longbridge’,
‘shortbridge’, ‘fcc’, ‘hcp’, ‘3fold’, ‘4fold’, ‘5fold’, ‘6fold’.

\sphinxstylestrong{‘surface’}: the surface of the site, support ‘vertex’, ‘edge’,
‘fcc100’, ‘fcc111’.

\sphinxstylestrong{‘position’}: the 3D Cartesian coordinate of the site saved as a
numpy array.

\sphinxstylestrong{‘normal’}: the surface normal vector of the site saved as a numpy
array.

\sphinxstylestrong{‘indices’}: the indices of the atoms that constitute the site.

\sphinxstylestrong{‘composition’}: the elemental composition of the site. Always in
the order of atomic numbers.

\sphinxstylestrong{‘subsurf\_index’}: the index of the subsurface atom underneath an
hcp or 4fold site.

\sphinxstylestrong{‘subsurf\_element’}: the element of the subsurface atom underneath
an hcp or 4fold site

\sphinxstylestrong{‘label’}: the numerical label assigned to the site if label\_sites
is set to True.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{atoms}} (\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atoms object}}) \textendash{} The atoms object must be a non\sphinxhyphen{}periodic nanoparticle.
Accept any ase.Atoms object. No need to be built\sphinxhyphen{}in.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{allow\_6fold}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to allow the adsorption on 6\sphinxhyphen{}fold subsurf sites
underneath fcc hollow sites.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{composition\_effect}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to consider sites with different elemental
compositions as different sites. It is recommended to
set composition=False for monometallics.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{label\_sites}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to assign a numerical label to each site.
Labels for different sites are listed in acat.labels.
Use the bimetallic labels if composition\_effect=True,
otherwise use the monometallic labels.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{proxy\_metal}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The code is parameterized for pure transition metals.
The generalization of the code is achieved by mapping all
input atoms to a proxy transition metal that is supported
by the asap3.EMT calculator (Ni, Cu, Pd, Ag, Pt or Au).
Try changing the proxy metal when the site identification
is not satisfying.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{tol}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 0.5}}) \textendash{} The tolerence of neighbor distance (in Angstrom).
Might be helpful to adjust this if the site identification
is not satisfying. When the nanoparticle is small (less
than 300 atoms), Cu is normally the better choice, while
Au should be good for larger nanoparticles.

\end{itemize}

\end{description}\end{quote}
\subsubsection*{Example}

The following example illustrates the most important use of a
\sphinxtitleref{ClusterAdsorptionSites} object \sphinxhyphen{} getting all adsorption sites:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{adsorption\PYGZus{}sites} \PYG{k+kn}{import} \PYG{n}{ClusterAdsorptionSites}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{cluster} \PYG{k+kn}{import} \PYG{n}{Octahedron}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms} \PYG{o}{=} \PYG{n}{Octahedron}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Ni}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{n}{length}\PYG{o}{=}\PYG{l+m+mi}{7}\PYG{p}{,} \PYG{n}{cutoff}\PYG{o}{=}\PYG{l+m+mi}{2}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k}{for} \PYG{n}{atom} \PYG{o+ow}{in} \PYG{n}{atoms}\PYG{p}{:}
\PYG{g+gp}{... }    \PYG{k}{if} \PYG{n}{atom}\PYG{o}{.}\PYG{n}{index} \PYG{o}{\PYGZpc{}} \PYG{l+m+mi}{2} \PYG{o}{==} \PYG{l+m+mi}{0}\PYG{p}{:}
\PYG{g+gp}{... }        \PYG{n}{atom}\PYG{o}{.}\PYG{n}{symbol} \PYG{o}{=} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Pt}\PYG{l+s+s1}{\PYGZsq{}}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms}\PYG{o}{.}\PYG{n}{center}\PYG{p}{(}\PYG{n}{vacuum}\PYG{o}{=}\PYG{l+m+mf}{5.}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{cas} \PYG{o}{=} \PYG{n}{ClusterAdsorptionSites}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{allow\PYGZus{}6fold}\PYG{o}{=}\PYG{k+kc}{False}\PYG{p}{,}
\PYG{g+gp}{... }                             \PYG{n}{composition\PYGZus{}effect}\PYG{o}{=}\PYG{k+kc}{True}\PYG{p}{,}
\PYG{g+gp}{... }                             \PYG{n}{label\PYGZus{}sites}\PYG{o}{=}\PYG{k+kc}{True}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{sites} \PYG{o}{=} \PYG{n}{cas}\PYG{o}{.}\PYG{n}{get\PYGZus{}sites}\PYG{p}{(}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n+nb}{print}\PYG{p}{(}\PYG{n}{sites}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{p}{)}
\end{sphinxVerbatim}

Output:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{p}{\PYGZob{}}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{site}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{bridge}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{surface}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{fcc111}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{position}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{n}{array}\PYG{p}{(}\PYG{p}{[}\PYG{l+m+mf}{6.96}\PYG{p}{,}  \PYG{l+m+mf}{7.94}\PYG{p}{,} \PYG{l+m+mf}{11.86}\PYG{p}{]}\PYG{p}{)}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{normal}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{n}{array}\PYG{p}{(}\PYG{p}{[}\PYG{o}{\PYGZhy{}}\PYG{l+m+mf}{0.66666667}\PYG{p}{,} \PYG{o}{\PYGZhy{}}\PYG{l+m+mf}{0.66666667}\PYG{p}{,} \PYG{o}{\PYGZhy{}}\PYG{l+m+mf}{0.33333333}\PYG{p}{]}\PYG{p}{)}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{indices}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{p}{(}\PYG{l+m+mi}{0}\PYG{p}{,} \PYG{l+m+mi}{2}\PYG{p}{)}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{composition}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{PtPt}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{subsurf\PYGZus{}index}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{k+kc}{None}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{subsurf\PYGZus{}element}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{k+kc}{None}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{label}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+m+mi}{14}\PYG{p}{\PYGZcb{}}
\end{sphinxVerbatim}
\index{populate\_site\_list() (acat.adsorption\_sites.ClusterAdsorptionSites method)@\spxentry{populate\_site\_list()}\spxextra{acat.adsorption\_sites.ClusterAdsorptionSites method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorption_sites.ClusterAdsorptionSites.populate_site_list}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{populate\_site\_list}}}{}{}
Find all ontop, bridge and hollow sites (3\sphinxhyphen{}fold and 4\sphinxhyphen{}fold)
given an input nanoparticle based on CNA analysis of the suface
atoms and collect in a site list.

\end{fulllineitems}

\index{get\_site() (acat.adsorption\_sites.ClusterAdsorptionSites method)@\spxentry{get\_site()}\spxextra{acat.adsorption\_sites.ClusterAdsorptionSites method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorption_sites.ClusterAdsorptionSites.get_site}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_site}}}{\emph{\DUrole{n}{indices}}}{}
Get information of a site given its atom indices.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode
\sphinxstyleliteralstrong{\sphinxupquote{indices}} (\sphinxstyleliteralemphasis{\sphinxupquote{list}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}) \textendash{} The indices of the atoms that contribute to the site.

\end{description}\end{quote}

\end{fulllineitems}

\index{get\_sites() (acat.adsorption\_sites.ClusterAdsorptionSites method)@\spxentry{get\_sites()}\spxextra{acat.adsorption\_sites.ClusterAdsorptionSites method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorption_sites.ClusterAdsorptionSites.get_sites}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_sites}}}{\emph{\DUrole{n}{site}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{surface}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{composition}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{subsurf\_element}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
Get information of all sites.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{site}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} Only return sites that belongs to this site type.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{surface}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} Only return sites that are on this surface.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{composition}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} Only return sites that have this composition.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{subsurf\_element}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} Only return sites that have this subsurface element.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{get\_unique\_sites() (acat.adsorption\_sites.ClusterAdsorptionSites method)@\spxentry{get\_unique\_sites()}\spxextra{acat.adsorption\_sites.ClusterAdsorptionSites method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorption_sites.ClusterAdsorptionSites.get_unique_sites}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_unique\_sites}}}{\emph{\DUrole{n}{unique\_composition}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{unique\_subsurf}\DUrole{o}{=}\DUrole{default_value}{False}}}{}
Get all unique sites.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{unique\_composition}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Take site composition into consideration when
checking uniqueness.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{unique\_subsurf}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Take subsurface element into consideration when
checking uniqueness.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{get\_surface\_normal() (acat.adsorption\_sites.ClusterAdsorptionSites method)@\spxentry{get\_surface\_normal()}\spxextra{acat.adsorption\_sites.ClusterAdsorptionSites method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorption_sites.ClusterAdsorptionSites.get_surface_normal}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_surface\_normal}}}{\emph{\DUrole{n}{indices}}}{}
Get the surface normal vector of the plane from the indices
of 3 atoms that forms to that plane.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode
\sphinxstyleliteralstrong{\sphinxupquote{indices}} (\sphinxstyleliteralemphasis{\sphinxupquote{list of tuple}}) \textendash{} The indices of the atoms that forms the plane.

\end{description}\end{quote}

\end{fulllineitems}

\index{no\_atom\_too\_close\_to\_pos() (acat.adsorption\_sites.ClusterAdsorptionSites method)@\spxentry{no\_atom\_too\_close\_to\_pos()}\spxextra{acat.adsorption\_sites.ClusterAdsorptionSites method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorption_sites.ClusterAdsorptionSites.no_atom_too_close_to_pos}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{no\_atom\_too\_close\_to\_pos}}}{\emph{\DUrole{n}{pos}}, \emph{\DUrole{n}{mindist}}}{}
Returns True if no atoms are closer than mindist to pos,
otherwise False.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{pos}} (\sphinxstyleliteralemphasis{\sphinxupquote{numpy.array}}) \textendash{} The position to be checked.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{mindist}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}) \textendash{} The minimum distance (in Angstrom) that is not considered
as too close.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{get\_surface\_sites() (acat.adsorption\_sites.ClusterAdsorptionSites method)@\spxentry{get\_surface\_sites()}\spxextra{acat.adsorption\_sites.ClusterAdsorptionSites method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorption_sites.ClusterAdsorptionSites.get_surface_sites}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_surface\_sites}}}{}{}
Returns the indices of the surface atoms and a dictionary
with all the surface designations.

\end{fulllineitems}

\index{get\_subsurface() (acat.adsorption\_sites.ClusterAdsorptionSites method)@\spxentry{get\_subsurface()}\spxextra{acat.adsorption\_sites.ClusterAdsorptionSites method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorption_sites.ClusterAdsorptionSites.get_subsurface}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_subsurface}}}{}{}
Returns the indices of the subsurface atoms.

\end{fulllineitems}

\index{get\_fullCNA() (acat.adsorption\_sites.ClusterAdsorptionSites method)@\spxentry{get\_fullCNA()}\spxextra{acat.adsorption\_sites.ClusterAdsorptionSites method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorption_sites.ClusterAdsorptionSites.get_fullCNA}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_fullCNA}}}{\emph{\DUrole{n}{rCut}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
Get the CNA signatures of all atoms by asap3 full CNA
analysis.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode
\sphinxstyleliteralstrong{\sphinxupquote{rCut}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The cutoff radius in Angstrom. If not specified, the
asap3 CNA analysis will use a reasonable cutoff based
on the crystalline lattice constant of the material.

\end{description}\end{quote}

\end{fulllineitems}

\index{get\_connectivity() (acat.adsorption\_sites.ClusterAdsorptionSites method)@\spxentry{get\_connectivity()}\spxextra{acat.adsorption\_sites.ClusterAdsorptionSites method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorption_sites.ClusterAdsorptionSites.get_connectivity}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_connectivity}}}{}{}
Get the connection matrix.

\end{fulllineitems}

\index{get\_graph() (acat.adsorption\_sites.ClusterAdsorptionSites method)@\spxentry{get\_graph()}\spxextra{acat.adsorption\_sites.ClusterAdsorptionSites method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorption_sites.ClusterAdsorptionSites.get_graph}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_graph}}}{}{}
Get the graph representation of the nanoparticle.

\end{fulllineitems}

\index{get\_neighbor\_site\_list() (acat.adsorption\_sites.ClusterAdsorptionSites method)@\spxentry{get\_neighbor\_site\_list()}\spxextra{acat.adsorption\_sites.ClusterAdsorptionSites method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorption_sites.ClusterAdsorptionSites.get_neighbor_site_list}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_neighbor\_site\_list}}}{\emph{\DUrole{n}{neighbor\_number}\DUrole{o}{=}\DUrole{default_value}{1}}, \emph{\DUrole{n}{span}\DUrole{o}{=}\DUrole{default_value}{True}}}{}
Returns the site\_list index of all neighbor shell sites
for each site.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{neighbor\_number}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 1}}) \textendash{} Neighbor shell number.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{span}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default True}}) \textendash{} Whether to include all neighbors sites spanned within
the shell.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{update() (acat.adsorption\_sites.ClusterAdsorptionSites method)@\spxentry{update()}\spxextra{acat.adsorption\_sites.ClusterAdsorptionSites method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorption_sites.ClusterAdsorptionSites.update}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{update}}}{\emph{\DUrole{n}{atoms}}, \emph{\DUrole{n}{update\_composition}\DUrole{o}{=}\DUrole{default_value}{False}}}{}
Update the position and composition of each adsorption site
given an updated atoms object. Please only use this when the
indexing of the atoms object is preserved. Useful for updating
adsorption sites e.g. after geometry optimization.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{atoms}} (\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atoms object}}) \textendash{} The updated atoms object.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{update\_composition}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to update the composition as well. It is recommended
to only set update\_composition=True if the composition of
the surface is not fixed.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}


\end{fulllineitems}

\index{group\_sites\_by\_facet() (in module acat.adsorption\_sites)@\spxentry{group\_sites\_by\_facet()}\spxextra{in module acat.adsorption\_sites}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorption_sites.group_sites_by_facet}}\pysiglinewithargsret{\sphinxcode{\sphinxupquote{acat.adsorption\_sites.}}\sphinxbfcode{\sphinxupquote{group\_sites\_by\_facet}}}{\emph{\DUrole{n}{atoms}}, \emph{\DUrole{n}{sites}}, \emph{\DUrole{n}{all\_sites}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
A function that uses networkx to group one set of sites by
geometrical facets of the nanoparticle. Different geometrical
facets can have the same surface type. The function returns a
list of lists, each contains sites on a same geometrical facet.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{atoms}} (\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atoms object}}) \textendash{} The atoms object must be a non\sphinxhyphen{}periodic nanoparticle.
Accept any ase.Atoms object. No need to be built\sphinxhyphen{}in.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{sites}} (\sphinxstyleliteralemphasis{\sphinxupquote{list of dicts}}) \textendash{} The adsorption sites to be grouped by geometrical facet.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{all\_sites}} (\sphinxstyleliteralemphasis{\sphinxupquote{list of dicts}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The list of all sites. Provide this to make the grouping
much faster. Useful when the function is called many times.

\end{itemize}

\end{description}\end{quote}
\subsubsection*{Example}

The following example shows how to group all fcc sites of an
icosahedral nanoparticle by its 20 geometrical facets:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{adsorption\PYGZus{}sites} \PYG{k+kn}{import} \PYG{n}{ClusterAdsorptionSites}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{adsorption\PYGZus{}sites} \PYG{k+kn}{import} \PYG{n}{group\PYGZus{}sites\PYGZus{}by\PYGZus{}facet}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{cluster} \PYG{k+kn}{import} \PYG{n}{Icosahedron}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms} \PYG{o}{=} \PYG{n}{Icosahedron}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Pt}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{n}{noshells}\PYG{o}{=}\PYG{l+m+mi}{5}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms}\PYG{o}{.}\PYG{n}{center}\PYG{p}{(}\PYG{n}{vacuum}\PYG{o}{=}\PYG{l+m+mf}{5.}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{cas} \PYG{o}{=} \PYG{n}{ClusterAdsorptionSites}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{all\PYGZus{}sites} \PYG{o}{=} \PYG{n}{cas}\PYG{o}{.}\PYG{n}{get\PYGZus{}sites}\PYG{p}{(}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{fcc\PYGZus{}sites} \PYG{o}{=} \PYG{p}{[}\PYG{n}{s} \PYG{k}{for} \PYG{n}{s} \PYG{o+ow}{in} \PYG{n}{all\PYGZus{}sites} \PYG{k}{if} \PYG{n}{s}\PYG{p}{[}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{site}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]} \PYG{o}{==} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{fcc}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{groups} \PYG{o}{=} \PYG{n}{group\PYGZus{}sites\PYGZus{}by\PYGZus{}facet}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{fcc\PYGZus{}sites}\PYG{p}{,} \PYG{n}{all\PYGZus{}sites}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n+nb}{print}\PYG{p}{(}\PYG{n+nb}{len}\PYG{p}{(}\PYG{n}{groups}\PYG{p}{)}\PYG{p}{)}
\end{sphinxVerbatim}

Output:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{l+m+mi}{20}
\end{sphinxVerbatim}

\end{fulllineitems}

\index{SlabAdsorptionSites (class in acat.adsorption\_sites)@\spxentry{SlabAdsorptionSites}\spxextra{class in acat.adsorption\_sites}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorption_sites.SlabAdsorptionSites}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class }}\sphinxcode{\sphinxupquote{acat.adsorption\_sites.}}\sphinxbfcode{\sphinxupquote{SlabAdsorptionSites}}}{\emph{\DUrole{n}{atoms}}, \emph{\DUrole{n}{surface}}, \emph{\DUrole{n}{allow\_6fold}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{composition\_effect}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{label\_sites}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{proxy\_metal}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{tol}\DUrole{o}{=}\DUrole{default_value}{0.5}}}{}
Bases: \sphinxcode{\sphinxupquote{object}}

Base class for identifying adsorption sites on a surface slab.
Support 20 common surfaces: fcc100, fcc111, fcc110, fcc211,
fcc221, fcc311, fcc322, fcc331, fcc332, bcc100, bcc111, bcc110,
bcc210, bcc211, bcc310, hcp0001, hcp10m10t, hcp10m10h,
hcp10m11, hcp10m12.

The information of each site is stored in a dictionary with the
following keys:

\sphinxstylestrong{‘site’}: the site type, support ‘ontop’, ‘bridge’, ‘longbridge’,
‘shortbridge’, ‘fcc’, ‘hcp’, ‘3fold’, ‘4fold’, ‘5fold’, ‘6fold’.

\sphinxstylestrong{‘surface’}: the surface type (crystal structure + Miller indices)
of the slab. Support 20 surfaces as listed above.

\sphinxstylestrong{‘position’}: the 3D Cartesian coordinate of the site saved as a
numpy array.

\sphinxstylestrong{‘normal’}: the surface normal vector of the site saved as a numpy
array.

\sphinxstylestrong{‘indices’}: the indices of the atoms that constitute the site.

\sphinxstylestrong{‘composition’}: the elemental composition of the site. Always in
the order of atomic numbers.

\sphinxstylestrong{‘subsurf\_index’}: the index of the subsurface atom underneath an
hcp or 4fold site.

\sphinxstylestrong{‘subsurf\_element’}: the element of the subsurface atom underneath
an hcp or 4fold site

\sphinxstylestrong{‘label’}: the numerical label assigned to the site if label\_sites
is set to True.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{atoms}} (\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atoms object}}) \textendash{} The atoms object must be a periodic surface slab with at
least 3 layers (e.g. all surface atoms make up one layer).
Accept any ase.Atoms object. No need to be built\sphinxhyphen{}in.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{surface}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} The surface type (crystal structure + Miller indices)

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{allow\_6fold}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to allow the adsorption on 6\sphinxhyphen{}fold subsurf sites
underneath fcc hollow sites.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{composition\_effect}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to consider sites with different elemental
compositions as different sites. It is recommended to
set composition=False for monometallics.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{label\_sites}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to assign a numerical label to each site.
Labels for different sites are listed in acat.labels.
Use the bimetallic labels if composition\_effect=True,
otherwise use the monometallic labels.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{proxy\_metal}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The code is parameterized for pure transition metals.
The generalization of the code is achieved by mapping all
input atoms to a proxy transition metal that is supported
by the asap3.EMT calculator (Ni, Cu, Pd, Ag, Pt or Au).
Try changing the proxy metal when the site identification
is not satisfying. When the cell is small, Cu is normally
the better choice, while the Pt and Au should be good for
larger cells.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{tol}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 0.5}}) \textendash{} The tolerence of neighbor distance (in Angstrom).
Might be helpful to adjust this if the site identification
is not satisfying. The default 0.5 is usually good enough.

\end{itemize}

\end{description}\end{quote}
\subsubsection*{Example}

The following example illustrates the most important use of a
\sphinxtitleref{SlabAdsorptionSites} object \sphinxhyphen{} getting all adsorption sites:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{adsorption\PYGZus{}sites} \PYG{k+kn}{import} \PYG{n}{SlabAdsorptionSites}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{build} \PYG{k+kn}{import} \PYG{n}{fcc211}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms} \PYG{o}{=} \PYG{n}{fcc211}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Cu}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{p}{(}\PYG{l+m+mi}{3}\PYG{p}{,} \PYG{l+m+mi}{3}\PYG{p}{,} \PYG{l+m+mi}{4}\PYG{p}{)}\PYG{p}{,} \PYG{n}{vacuum}\PYG{o}{=}\PYG{l+m+mf}{5.}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k}{for} \PYG{n}{atom} \PYG{o+ow}{in} \PYG{n}{atoms}\PYG{p}{:}
\PYG{g+gp}{... }    \PYG{k}{if} \PYG{n}{atom}\PYG{o}{.}\PYG{n}{index} \PYG{o}{\PYGZpc{}} \PYG{l+m+mi}{2} \PYG{o}{==} \PYG{l+m+mi}{0}\PYG{p}{:}
\PYG{g+gp}{... }        \PYG{n}{atom}\PYG{o}{.}\PYG{n}{symbol} \PYG{o}{=} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Au}\PYG{l+s+s1}{\PYGZsq{}}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms}\PYG{o}{.}\PYG{n}{center}\PYG{p}{(}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{sas} \PYG{o}{=} \PYG{n}{SlabAdsorptionSites}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{surface}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{fcc211}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
\PYG{g+gp}{... }                          \PYG{n}{allow\PYGZus{}6fold}\PYG{o}{=}\PYG{k+kc}{False}\PYG{p}{,}
\PYG{g+gp}{... }                          \PYG{n}{composition\PYGZus{}effect}\PYG{o}{=}\PYG{k+kc}{True}\PYG{p}{,}
\PYG{g+gp}{... }                          \PYG{n}{label\PYGZus{}sites}\PYG{o}{=}\PYG{k+kc}{True}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{sites} \PYG{o}{=} \PYG{n}{sas}\PYG{o}{.}\PYG{n}{get\PYGZus{}sites}\PYG{p}{(}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n+nb}{print}\PYG{p}{(}\PYG{n}{sites}\PYG{p}{[}\PYG{o}{\PYGZhy{}}\PYG{l+m+mi}{1}\PYG{p}{]}\PYG{p}{)}
\end{sphinxVerbatim}

Output:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{p}{\PYGZob{}}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{site}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{hcp}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{surface}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{fcc211}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{geometry}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{sc\PYGZhy{}tc\PYGZhy{}h}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{position}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{n}{array}\PYG{p}{(}\PYG{p}{[} \PYG{l+m+mf}{4.51584136}\PYG{p}{,}  \PYG{l+m+mf}{0.63816387}\PYG{p}{,} \PYG{l+m+mf}{12.86014042}\PYG{p}{]}\PYG{p}{)}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{normal}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{n}{array}\PYG{p}{(}\PYG{p}{[}\PYG{o}{\PYGZhy{}}\PYG{l+m+mf}{0.33333333}\PYG{p}{,} \PYG{o}{\PYGZhy{}}\PYG{l+m+mf}{0.}        \PYG{p}{,}  \PYG{l+m+mf}{0.94280904}\PYG{p}{]}\PYG{p}{)}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{indices}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{p}{(}\PYG{l+m+mi}{0}\PYG{p}{,} \PYG{l+m+mi}{2}\PYG{p}{,} \PYG{l+m+mi}{3}\PYG{p}{)}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{composition}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{CuAuAu}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{subsurf\PYGZus{}index}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+m+mi}{9}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{subsurf\PYGZus{}element}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Cu}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{label}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+m+mi}{28}\PYG{p}{\PYGZcb{}}
\end{sphinxVerbatim}
\index{populate\_site\_list() (acat.adsorption\_sites.SlabAdsorptionSites method)@\spxentry{populate\_site\_list()}\spxextra{acat.adsorption\_sites.SlabAdsorptionSites method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorption_sites.SlabAdsorptionSites.populate_site_list}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{populate\_site\_list}}}{\emph{\DUrole{n}{allow\_obtuse}\DUrole{o}{=}\DUrole{default_value}{True}}, \emph{\DUrole{n}{cutoff}\DUrole{o}{=}\DUrole{default_value}{5.0}}}{}
Find all ontop, bridge and hollow sites (3\sphinxhyphen{}fold and 4\sphinxhyphen{}fold)
given an input slab based on Delaunay triangulation of the
surface atoms in a supercell and collect in a site list.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{allow\_obtuse}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default True}}) \textendash{} Whether simplices with obtuse angles are considered in the
Delaunay triangulation.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{cutoff}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 5.}}) \textendash{} Radius of maximum atomic bond distance to consider.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{get\_site() (acat.adsorption\_sites.SlabAdsorptionSites method)@\spxentry{get\_site()}\spxextra{acat.adsorption\_sites.SlabAdsorptionSites method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorption_sites.SlabAdsorptionSites.get_site}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_site}}}{\emph{\DUrole{n}{indices}}}{}
Get information of a site given its atom indices.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode
\sphinxstyleliteralstrong{\sphinxupquote{indices}} (\sphinxstyleliteralemphasis{\sphinxupquote{list}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}) \textendash{} The indices of the atoms that contribute to the site.

\end{description}\end{quote}

\end{fulllineitems}

\index{get\_sites() (acat.adsorption\_sites.SlabAdsorptionSites method)@\spxentry{get\_sites()}\spxextra{acat.adsorption\_sites.SlabAdsorptionSites method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorption_sites.SlabAdsorptionSites.get_sites}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_sites}}}{\emph{\DUrole{n}{site}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{geometry}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{composition}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{subsurf\_element}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
Get information of all sites.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{site}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} Only return sites that belongs to this site type.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{surface}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} Only return sites that are on this surface.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{composition}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} Only return sites that have this composition.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{subsurf\_element}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} Only return sites that have this subsurface element.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{get\_unique\_sites() (acat.adsorption\_sites.SlabAdsorptionSites method)@\spxentry{get\_unique\_sites()}\spxextra{acat.adsorption\_sites.SlabAdsorptionSites method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorption_sites.SlabAdsorptionSites.get_unique_sites}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_unique\_sites}}}{\emph{\DUrole{n}{unique\_composition}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{unique\_subsurf}\DUrole{o}{=}\DUrole{default_value}{False}}}{}
Get all unique sites.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{unique\_composition}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Take site composition into consideration when
checking uniqueness.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{unique\_subsurf}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Take subsurface element into consideration when
checking uniqueness.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{get\_connectivity() (acat.adsorption\_sites.SlabAdsorptionSites method)@\spxentry{get\_connectivity()}\spxextra{acat.adsorption\_sites.SlabAdsorptionSites method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorption_sites.SlabAdsorptionSites.get_connectivity}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_connectivity}}}{}{}
Get the connection matrix.

\end{fulllineitems}

\index{get\_termination() (acat.adsorption\_sites.SlabAdsorptionSites method)@\spxentry{get\_termination()}\spxextra{acat.adsorption\_sites.SlabAdsorptionSites method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorption_sites.SlabAdsorptionSites.get_termination}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_termination}}}{}{}
Return the indices of surface and subsurface atoms. This
function relies on coordination number and the connectivity
of the atoms. The top surface termination is singled out by
graph connectivity using networkx.

\end{fulllineitems}

\index{get\_surface\_normal() (acat.adsorption\_sites.SlabAdsorptionSites method)@\spxentry{get\_surface\_normal()}\spxextra{acat.adsorption\_sites.SlabAdsorptionSites method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorption_sites.SlabAdsorptionSites.get_surface_normal}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_surface\_normal}}}{\emph{\DUrole{n}{indices}}}{}
Get the surface normal vector of the plane from the indices
of 3 atoms that forms to that plane.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode
\sphinxstyleliteralstrong{\sphinxupquote{indices}} (\sphinxstyleliteralemphasis{\sphinxupquote{list of tuple}}) \textendash{} The indices of the atoms that forms the plane.

\end{description}\end{quote}

\end{fulllineitems}

\index{get\_graph() (acat.adsorption\_sites.SlabAdsorptionSites method)@\spxentry{get\_graph()}\spxextra{acat.adsorption\_sites.SlabAdsorptionSites method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorption_sites.SlabAdsorptionSites.get_graph}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_graph}}}{}{}
Get the graph representation of the nanoparticle.

\end{fulllineitems}

\index{get\_neighbor\_site\_list() (acat.adsorption\_sites.SlabAdsorptionSites method)@\spxentry{get\_neighbor\_site\_list()}\spxextra{acat.adsorption\_sites.SlabAdsorptionSites method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorption_sites.SlabAdsorptionSites.get_neighbor_site_list}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_neighbor\_site\_list}}}{\emph{\DUrole{n}{neighbor\_number}\DUrole{o}{=}\DUrole{default_value}{1}}, \emph{\DUrole{n}{span}\DUrole{o}{=}\DUrole{default_value}{True}}}{}
Returns the site\_list index of all neighbor shell sites
for each site.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{neighbor\_number}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 1}}) \textendash{} Neighbor shell number.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{span}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default True}}) \textendash{} Whether to include all neighbors sites spanned within
the shell.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{update() (acat.adsorption\_sites.SlabAdsorptionSites method)@\spxentry{update()}\spxextra{acat.adsorption\_sites.SlabAdsorptionSites method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorption_sites.SlabAdsorptionSites.update}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{update}}}{\emph{\DUrole{n}{atoms}}, \emph{\DUrole{n}{update\_composition}\DUrole{o}{=}\DUrole{default_value}{False}}}{}
Update the position and composition of each adsorption site
given an updated atoms object. Please only use this when the
indexing of the atoms object is preserved. Useful for updating
adsorption sites e.g. after geometry optimization.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{atoms}} (\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atoms object}}) \textendash{} The updated atoms object.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{update\_composition}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to update the composition as well. It is recommended
to only set update\_composition=True if the composition of
the surface is not fixed.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}


\end{fulllineitems}

\index{get\_adsorption\_site() (in module acat.adsorption\_sites)@\spxentry{get\_adsorption\_site()}\spxextra{in module acat.adsorption\_sites}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorption_sites.get_adsorption_site}}\pysiglinewithargsret{\sphinxcode{\sphinxupquote{acat.adsorption\_sites.}}\sphinxbfcode{\sphinxupquote{get\_adsorption\_site}}}{\emph{\DUrole{n}{atoms}}, \emph{\DUrole{n}{indices}}, \emph{\DUrole{n}{surface}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{return\_index}\DUrole{o}{=}\DUrole{default_value}{False}}}{}
A function that returns the information of a site given the
indices of the atoms that contribute to the site. The function
is generalized for both periodic and non\sphinxhyphen{}periodic systems
(distinguished by atoms.pbc).
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{atoms}} (\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atoms object}}) \textendash{} Accept any ase.Atoms object. No need to be built\sphinxhyphen{}in.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{indices}} (\sphinxstyleliteralemphasis{\sphinxupquote{list}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}) \textendash{} The indices of the atoms that contribute to the site.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{surface}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The surface type (crystal structure + Miller indices)
Only required for periodic surface slabs.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{return\_index}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to return the site index of the site list
together with the site.

\end{itemize}

\end{description}\end{quote}
\subsubsection*{Example}

This is an example of getting the site information of the
(24, 29, 31) 3\sphinxhyphen{}fold hollow site on a fcc110 surface:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{adsorption\PYGZus{}sites} \PYG{k+kn}{import} \PYG{n}{get\PYGZus{}adsorption\PYGZus{}site}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{build} \PYG{k+kn}{import} \PYG{n}{fcc110}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms} \PYG{o}{=} \PYG{n}{fcc110}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Cu}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{p}{(}\PYG{l+m+mi}{2}\PYG{p}{,} \PYG{l+m+mi}{2}\PYG{p}{,} \PYG{l+m+mi}{8}\PYG{p}{)}\PYG{p}{,} \PYG{n}{vacuum}\PYG{o}{=}\PYG{l+m+mf}{5.}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k}{for} \PYG{n}{atom} \PYG{o+ow}{in} \PYG{n}{atoms}\PYG{p}{:}
\PYG{g+gp}{... }    \PYG{k}{if} \PYG{n}{atom}\PYG{o}{.}\PYG{n}{index} \PYG{o}{\PYGZpc{}} \PYG{l+m+mi}{2} \PYG{o}{==} \PYG{l+m+mi}{0}\PYG{p}{:}
\PYG{g+gp}{... }        \PYG{n}{atom}\PYG{o}{.}\PYG{n}{symbol} \PYG{o}{=} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Au}\PYG{l+s+s1}{\PYGZsq{}}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms}\PYG{o}{.}\PYG{n}{center}\PYG{p}{(}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{site} \PYG{o}{=} \PYG{n}{get\PYGZus{}adsorption\PYGZus{}site}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{p}{(}\PYG{l+m+mi}{24}\PYG{p}{,} \PYG{l+m+mi}{29}\PYG{p}{,} \PYG{l+m+mi}{31}\PYG{p}{)}\PYG{p}{,} \PYG{n}{surface}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{fcc110}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n+nb}{print}\PYG{p}{(}\PYG{n}{site}\PYG{p}{)}
\end{sphinxVerbatim}

Output:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{p}{\PYGZob{}}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{site}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{fcc}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{surface}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{fcc110}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{geometry}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{sc\PYGZhy{}tc\PYGZhy{}h}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{position}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{n}{array}\PYG{p}{(}\PYG{p}{[} \PYG{l+m+mf}{3.91083333}\PYG{p}{,}  \PYG{l+m+mf}{1.91449161}\PYG{p}{,} \PYG{l+m+mf}{13.5088516} \PYG{p}{]}\PYG{p}{)}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{normal}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{n}{array}\PYG{p}{(}\PYG{p}{[}\PYG{o}{\PYGZhy{}}\PYG{l+m+mf}{0.57735027}\PYG{p}{,}  \PYG{l+m+mf}{0.}        \PYG{p}{,}  \PYG{l+m+mf}{0.81649658}\PYG{p}{]}\PYG{p}{)}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{indices}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{p}{(}\PYG{l+m+mi}{24}\PYG{p}{,} \PYG{l+m+mi}{29}\PYG{p}{,} \PYG{l+m+mi}{31}\PYG{p}{)}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{composition}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{CuCuAu}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{subsurf\PYGZus{}index}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{k+kc}{None}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{subsurf\PYGZus{}element}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{k+kc}{None}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{label}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{k+kc}{None}\PYG{p}{\PYGZcb{}}
\end{sphinxVerbatim}

\end{fulllineitems}

\index{enumerate\_adsorption\_sites() (in module acat.adsorption\_sites)@\spxentry{enumerate\_adsorption\_sites()}\spxextra{in module acat.adsorption\_sites}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorption_sites.enumerate_adsorption_sites}}\pysiglinewithargsret{\sphinxcode{\sphinxupquote{acat.adsorption\_sites.}}\sphinxbfcode{\sphinxupquote{enumerate\_adsorption\_sites}}}{\emph{\DUrole{n}{atoms}}, \emph{\DUrole{n}{surface}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{geometry}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{allow\_6fold}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{composition\_effect}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{label\_sites}\DUrole{o}{=}\DUrole{default_value}{False}}}{}
A function that enumerates all adsorption sites of the
input atoms object. The function is generalized for both
periodic and non\sphinxhyphen{}periodic systems (distinguished by atoms.pbc).
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{atoms}} (\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atoms object}}) \textendash{} Accept any ase.Atoms object. No need to be built\sphinxhyphen{}in.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{surface}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The surface type (crystal structure + Miller indices).
If the structure is a periodic surface slab, this is required.
If the structure is a nanoparticle, the function enumerates
only the sites on the specified surface.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{geometry}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The function enumerates only the sites of the specified
geometry. Only available for surface slabs.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{allow\_6fold}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to allow the adsorption on 6\sphinxhyphen{}fold subsurf sites
underneath fcc hollow sites.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{composition\_effect}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to consider sites with different elemental
compositions as different sites. It is recommended to
set composition=False for monometallics.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{label\_sites}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to assign a numerical label to each site.
Labels for different sites are listed in acat.labels.
Use the bimetallic labels if composition\_effect=True,
otherwise use the monometallic labels.

\end{itemize}

\end{description}\end{quote}
\subsubsection*{Example}

This is an example of enumerating all sites on the fcc100 surfaces
of a Marks decahedral nanoparticle:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{adsorption\PYGZus{}sites} \PYG{k+kn}{import} \PYG{n}{enumerate\PYGZus{}adsorption\PYGZus{}sites}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{cluster} \PYG{k+kn}{import} \PYG{n}{Decahedron}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms} \PYG{o}{=} \PYG{n}{Decahedron}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Pb}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{n}{p}\PYG{o}{=}\PYG{l+m+mi}{3}\PYG{p}{,} \PYG{n}{q}\PYG{o}{=}\PYG{l+m+mi}{2}\PYG{p}{,} \PYG{n}{r}\PYG{o}{=}\PYG{l+m+mi}{1}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k}{for} \PYG{n}{atom} \PYG{o+ow}{in} \PYG{n}{atoms}\PYG{p}{:}
\PYG{g+gp}{... }    \PYG{k}{if} \PYG{n}{atom}\PYG{o}{.}\PYG{n}{index} \PYG{o}{\PYGZpc{}} \PYG{l+m+mi}{2} \PYG{o}{==} \PYG{l+m+mi}{0}\PYG{p}{:}
\PYG{g+gp}{... }        \PYG{n}{atom}\PYG{o}{.}\PYG{n}{symbol} \PYG{o}{=} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Ag}\PYG{l+s+s1}{\PYGZsq{}}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms}\PYG{o}{.}\PYG{n}{center}\PYG{p}{(}\PYG{n}{vacuum}\PYG{o}{=}\PYG{l+m+mf}{5.}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{sites} \PYG{o}{=} \PYG{n}{enumerate\PYGZus{}adsorption\PYGZus{}sites}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{surface}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{fcc100}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
\PYG{g+gp}{... }                                   \PYG{n}{composition\PYGZus{}effect}\PYG{o}{=}\PYG{k+kc}{True}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n+nb}{print}\PYG{p}{(}\PYG{n}{sites}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{p}{)}
\end{sphinxVerbatim}

Output:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{p}{\PYGZob{}}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{site}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{4fold}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{surface}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{fcc100}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{position}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{n}{array}\PYG{p}{(}\PYG{p}{[}\PYG{l+m+mf}{22.63758191}\PYG{p}{,} \PYG{l+m+mf}{21.69793997}\PYG{p}{,} \PYG{l+m+mf}{13.75044642}\PYG{p}{]}\PYG{p}{)}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{normal}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{n}{array}\PYG{p}{(}\PYG{p}{[} \PYG{l+m+mf}{0.58778525}\PYG{p}{,}  \PYG{l+m+mf}{0.80901699}\PYG{p}{,} \PYG{o}{\PYGZhy{}}\PYG{l+m+mf}{0.}        \PYG{p}{]}\PYG{p}{)}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{indices}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{p}{(}\PYG{l+m+mi}{116}\PYG{p}{,} \PYG{l+m+mi}{117}\PYG{p}{,} \PYG{l+m+mi}{118}\PYG{p}{,} \PYG{l+m+mi}{119}\PYG{p}{)}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{composition}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{AgAgPbPb}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{subsurf\PYGZus{}index}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+m+mi}{75}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{subsurf\PYGZus{}element}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Pb}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{label}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{k+kc}{None}\PYG{p}{\PYGZcb{}}
\end{sphinxVerbatim}

\end{fulllineitems}



\subsection{Adsorbate coverage}
\label{\detokenize{modules:module-acat.adsorbate_coverage}}\label{\detokenize{modules:adsorbate-coverage}}\index{module@\spxentry{module}!acat.adsorbate\_coverage@\spxentry{acat.adsorbate\_coverage}}\index{acat.adsorbate\_coverage@\spxentry{acat.adsorbate\_coverage}!module@\spxentry{module}}\index{ClusterAdsorbateCoverage (class in acat.adsorbate\_coverage)@\spxentry{ClusterAdsorbateCoverage}\spxextra{class in acat.adsorbate\_coverage}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorbate_coverage.ClusterAdsorbateCoverage}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class }}\sphinxcode{\sphinxupquote{acat.adsorbate\_coverage.}}\sphinxbfcode{\sphinxupquote{ClusterAdsorbateCoverage}}}{\emph{\DUrole{n}{atoms}}, \emph{\DUrole{n}{adsorption\_sites}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{label\_occupied\_sites}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{dmax}\DUrole{o}{=}\DUrole{default_value}{2.5}}}{}
Bases: \sphinxcode{\sphinxupquote{object}}

Child class of \sphinxtitleref{ClusterAdsorptionSites} for identifying adsorbate
coverage on a nanoparticle. Support common nanoparticle shapes
including: Mackay icosahedron, (truncated) octahedron and (Marks)
decahedron.

The information of each occupied site stored in the dictionary is
updated with the following new keys:

\sphinxstylestrong{‘occupied’}: 1 if the site is occupied, otherwise 0.

\sphinxstylestrong{‘adsorbate’}: the name of the adsorbate that occupies this site.

\sphinxstylestrong{‘adsorbate\_indices’}: the indices of the adosorbate atoms that occupy
this site. If the adsorbate is multidentate, these atoms might
occupy multiple sites.

\sphinxstylestrong{‘bonding\_index’}: the index of the atom that directly bonds to the
site (closest to the site).

\sphinxstylestrong{‘fragment’}: the name of the fragment that occupies this site. Useful
for multidentate species.

\sphinxstylestrong{‘fragment\_indices’}: the indices of the fragment atoms that occupy
this site. Useful for multidentate species.

\sphinxstylestrong{‘bond\_length’}: the distance between the bonding atom and the site.

\sphinxstylestrong{‘dentate’}: dentate number.

\sphinxstylestrong{‘label’}: the updated label with the name of the occupying adsorbate
if label\_occupied\_sites is set to True.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{atoms}} (\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atoms object}}) \textendash{} The atoms object must be a non\sphinxhyphen{}periodic nanoparticle with at
least one adsorbate attached to it. Accept any ase.Atoms object.
No need to be built\sphinxhyphen{}in.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{adsorption\_sites}} (\sphinxstyleliteralemphasis{\sphinxupquote{acat.adsorption\_sites.ClusterAdsorptionSites object}}\sphinxstyleliteralemphasis{\sphinxupquote{,         }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} \sphinxtitleref{ClusterAdsorptionSites} object of the nanoparticle. Initialize a
\sphinxtitleref{ClusterAdsorptionSites} object if not specified.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{label\_occupied\_sites}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to assign a label to the occupied each site. The string
of the occupying adsorbate is concatentated to the numerical
label that represents the occpied site.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{dmax}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 2.5}}) \textendash{} The maximum bond length (in Angstrom) between the site and the
bonding atom  that should be considered as an adsorbate.

\end{itemize}

\end{description}\end{quote}
\subsubsection*{Example}

The following example illustrates the most important use of a
\sphinxtitleref{ClusterAdsorbateCoverage} object \sphinxhyphen{} getting occupied adsorption sites:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{adsorption\PYGZus{}sites} \PYG{k+kn}{import} \PYG{n}{ClusterAdsorptionSites}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{adsorbate\PYGZus{}coverage} \PYG{k+kn}{import} \PYG{n}{ClusterAdsorbateCoverage}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{build}\PYG{n+nn}{.}\PYG{n+nn}{actions} \PYG{k+kn}{import} \PYG{n}{add\PYGZus{}adsorbate\PYGZus{}to\PYGZus{}site}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{cluster} \PYG{k+kn}{import} \PYG{n}{Octahedron}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms} \PYG{o}{=} \PYG{n}{Octahedron}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Ni}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{n}{length}\PYG{o}{=}\PYG{l+m+mi}{7}\PYG{p}{,} \PYG{n}{cutoff}\PYG{o}{=}\PYG{l+m+mi}{2}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k}{for} \PYG{n}{atom} \PYG{o+ow}{in} \PYG{n}{atoms}\PYG{p}{:}
\PYG{g+gp}{... }    \PYG{k}{if} \PYG{n}{atom}\PYG{o}{.}\PYG{n}{index} \PYG{o}{\PYGZpc{}} \PYG{l+m+mi}{2} \PYG{o}{==} \PYG{l+m+mi}{0}\PYG{p}{:}
\PYG{g+gp}{... }        \PYG{n}{atom}\PYG{o}{.}\PYG{n}{symbol} \PYG{o}{=} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Pt}\PYG{l+s+s1}{\PYGZsq{}}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms}\PYG{o}{.}\PYG{n}{center}\PYG{p}{(}\PYG{n}{vacuum}\PYG{o}{=}\PYG{l+m+mf}{5.}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{cas} \PYG{o}{=} \PYG{n}{ClusterAdsorptionSites}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{composition\PYGZus{}effect}\PYG{o}{=}\PYG{k+kc}{True}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{sites} \PYG{o}{=} \PYG{n}{cas}\PYG{o}{.}\PYG{n}{get\PYGZus{}sites}\PYG{p}{(}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k}{for} \PYG{n}{s} \PYG{o+ow}{in} \PYG{n}{sites}\PYG{p}{:}
\PYG{g+gp}{... }    \PYG{k}{if} \PYG{n}{s}\PYG{p}{[}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{site}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]} \PYG{o}{==} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{fcc}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:}
\PYG{g+gp}{... }        \PYG{n}{add\PYGZus{}adsorbate\PYGZus{}to\PYGZus{}site}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{adsorbate}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{CO}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{n}{site}\PYG{o}{=}\PYG{n}{s}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{cac} \PYG{o}{=} \PYG{n}{ClusterAdsorbateCoverage}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{adsorption\PYGZus{}sites}\PYG{o}{=}\PYG{n}{cas}\PYG{p}{,}
\PYG{g+gp}{... }                               \PYG{n}{label\PYGZus{}occupied\PYGZus{}sites}\PYG{o}{=}\PYG{k+kc}{True}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{occupied\PYGZus{}sites} \PYG{o}{=} \PYG{n}{cac}\PYG{o}{.}\PYG{n}{get\PYGZus{}sites}\PYG{p}{(}\PYG{n}{occupied\PYGZus{}only}\PYG{o}{=}\PYG{k+kc}{True}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n+nb}{print}\PYG{p}{(}\PYG{n}{occupied\PYGZus{}sites}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{p}{)}
\end{sphinxVerbatim}

Output:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{p}{\PYGZob{}}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{site}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{fcc}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{surface}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{fcc111}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{position}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{n}{array}\PYG{p}{(}\PYG{p}{[} \PYG{l+m+mf}{6.41470446}\PYG{p}{,}  \PYG{l+m+mf}{8.17470446}\PYG{p}{,} \PYG{l+m+mf}{11.69470446}\PYG{p}{]}\PYG{p}{)}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{normal}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{n}{array}\PYG{p}{(}\PYG{p}{[}\PYG{o}{\PYGZhy{}}\PYG{l+m+mf}{0.57735027}\PYG{p}{,} \PYG{o}{\PYGZhy{}}\PYG{l+m+mf}{0.57735027}\PYG{p}{,} \PYG{o}{\PYGZhy{}}\PYG{l+m+mf}{0.57735027}\PYG{p}{]}\PYG{p}{)}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{indices}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{p}{(}\PYG{l+m+mi}{0}\PYG{p}{,} \PYG{l+m+mi}{2}\PYG{p}{,} \PYG{l+m+mi}{4}\PYG{p}{)}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{composition}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{PtPtPt}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{subsurf\PYGZus{}index}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{k+kc}{None}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{subsurf\PYGZus{}element}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{k+kc}{None}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{label}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{21CO}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{bonding\PYGZus{}index}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+m+mi}{201}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{bond\PYGZus{}length}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+m+mf}{1.3000000000000007}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{adsorbate}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{CO}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{fragment}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{CO}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{adsorbate\PYGZus{}indices}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{p}{(}\PYG{l+m+mi}{201}\PYG{p}{,} \PYG{l+m+mi}{202}\PYG{p}{)}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{occupied}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+m+mi}{1}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{dentate}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+m+mi}{1}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{fragment\PYGZus{}indices}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{p}{(}\PYG{l+m+mi}{201}\PYG{p}{,} \PYG{l+m+mi}{202}\PYG{p}{)}\PYG{p}{\PYGZcb{}}
\end{sphinxVerbatim}
\index{get\_hetero\_connectivity() (acat.adsorbate\_coverage.ClusterAdsorbateCoverage method)@\spxentry{get\_hetero\_connectivity()}\spxextra{acat.adsorbate\_coverage.ClusterAdsorbateCoverage method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorbate_coverage.ClusterAdsorbateCoverage.get_hetero_connectivity}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_hetero\_connectivity}}}{}{}
Get the connection matrix of slab + adsorbates.

\end{fulllineitems}

\index{get\_ads\_connectivity() (acat.adsorbate\_coverage.ClusterAdsorbateCoverage method)@\spxentry{get\_ads\_connectivity()}\spxextra{acat.adsorbate\_coverage.ClusterAdsorbateCoverage method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorbate_coverage.ClusterAdsorbateCoverage.get_ads_connectivity}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_ads\_connectivity}}}{}{}
Get the connection matrix for adsorbate atoms.

\end{fulllineitems}

\index{get\_site\_connectivity() (acat.adsorbate\_coverage.ClusterAdsorbateCoverage method)@\spxentry{get\_site\_connectivity()}\spxextra{acat.adsorbate\_coverage.ClusterAdsorbateCoverage method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorbate_coverage.ClusterAdsorbateCoverage.get_site_connectivity}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_site\_connectivity}}}{}{}
Get the connection matrix for adsorption sites.

\end{fulllineitems}

\index{populate\_occupied\_sites() (acat.adsorbate\_coverage.ClusterAdsorbateCoverage method)@\spxentry{populate\_occupied\_sites()}\spxextra{acat.adsorbate\_coverage.ClusterAdsorbateCoverage method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorbate_coverage.ClusterAdsorbateCoverage.populate_occupied_sites}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{populate\_occupied\_sites}}}{}{}
Find all the occupied sites, identify the adsorbate coverage
of those sites and collect in a heterogeneous site list.

\end{fulllineitems}

\index{get\_site() (acat.adsorbate\_coverage.ClusterAdsorbateCoverage method)@\spxentry{get\_site()}\spxextra{acat.adsorbate\_coverage.ClusterAdsorbateCoverage method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorbate_coverage.ClusterAdsorbateCoverage.get_site}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_site}}}{\emph{\DUrole{n}{indices}}}{}
Get information of a site given its atom indices.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode
\sphinxstyleliteralstrong{\sphinxupquote{indices}} (\sphinxstyleliteralemphasis{\sphinxupquote{list}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}) \textendash{} The indices of the atoms that contribute to the site.

\end{description}\end{quote}

\end{fulllineitems}

\index{get\_sites() (acat.adsorbate\_coverage.ClusterAdsorbateCoverage method)@\spxentry{get\_sites()}\spxextra{acat.adsorbate\_coverage.ClusterAdsorbateCoverage method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorbate_coverage.ClusterAdsorbateCoverage.get_sites}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_sites}}}{\emph{\DUrole{n}{occupied\_only}\DUrole{o}{=}\DUrole{default_value}{False}}}{}
Get information of all sites.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode
\sphinxstyleliteralstrong{\sphinxupquote{occupied\_only}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to only return occupied sites.

\end{description}\end{quote}

\end{fulllineitems}

\index{get\_adsorbates() (acat.adsorbate\_coverage.ClusterAdsorbateCoverage method)@\spxentry{get\_adsorbates()}\spxextra{acat.adsorbate\_coverage.ClusterAdsorbateCoverage method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorbate_coverage.ClusterAdsorbateCoverage.get_adsorbates}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_adsorbates}}}{}{}
Get a list of tuples that contains each adsorbate (string)
and the corresponding adsorbate indices (tuple).

\end{fulllineitems}

\index{get\_occupied\_labels() (acat.adsorbate\_coverage.ClusterAdsorbateCoverage method)@\spxentry{get\_occupied\_labels()}\spxextra{acat.adsorbate\_coverage.ClusterAdsorbateCoverage method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorbate_coverage.ClusterAdsorbateCoverage.get_occupied_labels}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_occupied\_labels}}}{\emph{\DUrole{n}{fragmentation}\DUrole{o}{=}\DUrole{default_value}{True}}}{}
Get a list of labels of all occupied sites. The label consists
of a numerical part that represents site, and a character part
that represents the occupying adsorbate.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode
\sphinxstyleliteralstrong{\sphinxupquote{fragmentation}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default True}}) \textendash{} Whether to cut multidentate species into fragments. This ensures
that multidentate species with different orientations have
different labels.

\end{description}\end{quote}

\end{fulllineitems}

\index{get\_graph() (acat.adsorbate\_coverage.ClusterAdsorbateCoverage method)@\spxentry{get\_graph()}\spxextra{acat.adsorbate\_coverage.ClusterAdsorbateCoverage method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorbate_coverage.ClusterAdsorbateCoverage.get_graph}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_graph}}}{\emph{\DUrole{n}{fragmentation}\DUrole{o}{=}\DUrole{default_value}{True}}}{}
Get the graph representation of the nanoparticle with adsorbates.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode
\sphinxstyleliteralstrong{\sphinxupquote{fragmentation}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default True}}) \textendash{} Whether to cut multidentate species into fragments. This ensures
that multidentate species with different orientations have
different graphs.

\end{description}\end{quote}

\end{fulllineitems}

\index{get\_coverage() (acat.adsorbate\_coverage.ClusterAdsorbateCoverage method)@\spxentry{get\_coverage()}\spxextra{acat.adsorbate\_coverage.ClusterAdsorbateCoverage method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorbate_coverage.ClusterAdsorbateCoverage.get_coverage}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_coverage}}}{}{}
Get the adsorbate coverage (ML) of the surface.

\end{fulllineitems}

\index{get\_subsurf\_coverage() (acat.adsorbate\_coverage.ClusterAdsorbateCoverage method)@\spxentry{get\_subsurf\_coverage()}\spxextra{acat.adsorbate\_coverage.ClusterAdsorbateCoverage method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorbate_coverage.ClusterAdsorbateCoverage.get_subsurf_coverage}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_subsurf\_coverage}}}{}{}
Get the adsorbate coverage (ML) of the subsurface.

\end{fulllineitems}


\end{fulllineitems}

\index{SlabAdsorbateCoverage (class in acat.adsorbate\_coverage)@\spxentry{SlabAdsorbateCoverage}\spxextra{class in acat.adsorbate\_coverage}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorbate_coverage.SlabAdsorbateCoverage}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class }}\sphinxcode{\sphinxupquote{acat.adsorbate\_coverage.}}\sphinxbfcode{\sphinxupquote{SlabAdsorbateCoverage}}}{\emph{\DUrole{n}{atoms}}, \emph{\DUrole{n}{adsorption\_sites}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{surface}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{label\_occupied\_sites}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{dmax}\DUrole{o}{=}\DUrole{default_value}{2.5}}}{}
Bases: \sphinxcode{\sphinxupquote{object}}

Child class of \sphinxtitleref{SlabAdsorptionSites} for identifying adsorbate
coverage on a surface slab. Support 20 common surfaces: fcc100,
fcc111, fcc110, fcc211, fcc221, fcc311, fcc322, fcc331, fcc332,
bcc100, bcc111, bcc110, bcc210, bcc211, bcc310, hcp0001,
hcp10m10t, hcp10m10h, hcp10m11, hcp10m12.

The information of each occupied site stored in the dictionary is
updated with the following new keys:

\sphinxstylestrong{‘occupied’}: 1 if the site is occupied, otherwise 0.

\sphinxstylestrong{‘adsorbate’}: the name of the adsorbate that occupies this site.

\sphinxstylestrong{‘adsorbate\_indices’}: the indices of the adosorbate atoms that occupy
this site. If the adsorbate is multidentate, these atoms might
occupy multiple sites.

\sphinxstylestrong{‘bonding\_index’}: the index of the atom that directly bonds to the
site (closest to the site).

\sphinxstylestrong{‘fragment’}: the name of the fragment that occupies this site. Useful
for multidentate species.

\sphinxstylestrong{‘fragment\_indices’}: the indices of the fragment atoms that occupy
this site. Useful for multidentate species.

\sphinxstylestrong{‘bond\_length’}: the distance between the bonding atom and the site.

\sphinxstylestrong{‘dentate’}: dentate number.

\sphinxstylestrong{‘label’}: the updated label with the name of the occupying adsorbate
if label\_occupied\_sites is set to True.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{atoms}} (\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atoms object}}) \textendash{} The atoms object must be a non\sphinxhyphen{}periodic nanoparticle with at
least one adsorbate attached to it. Accept any ase.Atoms object.
No need to be built\sphinxhyphen{}in.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{adsorption\_sites}} (\sphinxstyleliteralemphasis{\sphinxupquote{acat.adsorption\_sites.SlabAdsorptionSites object}}\sphinxstyleliteralemphasis{\sphinxupquote{,         }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} \sphinxtitleref{SlabAdsorptionSites} object of the nanoparticle. Initialize a
\sphinxtitleref{SlabAdsorptionSites} object if not specified.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{surface}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} The surface type (crystal structure + Miller indices).
Required if adsorption\_sites is not provided.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{label\_occupied\_sites}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to assign a label to the occupied each site. The string
of the occupying adsorbate is concatentated to the numerical
label that represents the occpied site.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{dmax}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 2.5}}) \textendash{} The maximum bond length (in Angstrom) between the site and the
bonding atom  that should be considered as an adsorbate.

\end{itemize}

\end{description}\end{quote}
\subsubsection*{Example}

The following example illustrates the most important use of a
\sphinxtitleref{SlabAdsorbateCoverage} object \sphinxhyphen{} getting occupied adsorption sites:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{adsorption\PYGZus{}sites} \PYG{k+kn}{import} \PYG{n}{SlabAdsorptionSites}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{adsorbate\PYGZus{}coverage} \PYG{k+kn}{import} \PYG{n}{SlabAdsorbateCoverage}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{build}\PYG{n+nn}{.}\PYG{n+nn}{actions} \PYG{k+kn}{import} \PYG{n}{add\PYGZus{}adsorbate}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{build} \PYG{k+kn}{import} \PYG{n}{fcc211}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms} \PYG{o}{=} \PYG{n}{fcc211}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Cu}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{p}{(}\PYG{l+m+mi}{3}\PYG{p}{,} \PYG{l+m+mi}{3}\PYG{p}{,} \PYG{l+m+mi}{4}\PYG{p}{)}\PYG{p}{,} \PYG{n}{vacuum}\PYG{o}{=}\PYG{l+m+mf}{5.}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k}{for} \PYG{n}{atom} \PYG{o+ow}{in} \PYG{n}{atoms}\PYG{p}{:}
\PYG{g+gp}{... }    \PYG{k}{if} \PYG{n}{atom}\PYG{o}{.}\PYG{n}{index} \PYG{o}{\PYGZpc{}} \PYG{l+m+mi}{2} \PYG{o}{==} \PYG{l+m+mi}{0}\PYG{p}{:}
\PYG{g+gp}{... }        \PYG{n}{atom}\PYG{o}{.}\PYG{n}{symbol} \PYG{o}{=} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Au}\PYG{l+s+s1}{\PYGZsq{}}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms}\PYG{o}{.}\PYG{n}{center}\PYG{p}{(}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{add\PYGZus{}adsorbate}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{adsorbate}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{CH3OH}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{n}{surface}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{fcc211}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
\PYG{g+gp}{... }              \PYG{n}{indices}\PYG{o}{=}\PYG{p}{(}\PYG{l+m+mi}{5}\PYG{p}{,} \PYG{l+m+mi}{7}\PYG{p}{,} \PYG{l+m+mi}{8}\PYG{p}{)}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{sac} \PYG{o}{=} \PYG{n}{SlabAdsorbateCoverage}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{surface}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{fcc211}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
\PYG{g+gp}{... }                            \PYG{n}{label\PYGZus{}occupied\PYGZus{}sites}\PYG{o}{=}\PYG{k+kc}{True}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{occupied\PYGZus{}sites} \PYG{o}{=} \PYG{n}{sac}\PYG{o}{.}\PYG{n}{get\PYGZus{}sites}\PYG{p}{(}\PYG{n}{occupied\PYGZus{}only}\PYG{o}{=}\PYG{k+kc}{True}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n+nb}{print}\PYG{p}{(}\PYG{n}{occupied\PYGZus{}sites}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{p}{)}
\end{sphinxVerbatim}

Output:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{p}{\PYGZob{}}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{site}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{bridge}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{surface}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{fcc211}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{geometry}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{tc\PYGZhy{}cc\PYGZhy{}h}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{position}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{n}{array}\PYG{p}{(}\PYG{p}{[} \PYG{l+m+mf}{2.08423447}\PYG{p}{,}  \PYG{l+m+mf}{3.82898322}\PYG{p}{,} \PYG{l+m+mf}{12.00043756}\PYG{p}{]}\PYG{p}{)}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{normal}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{n}{array}\PYG{p}{(}\PYG{p}{[}\PYG{o}{\PYGZhy{}}\PYG{l+m+mf}{0.33333333}\PYG{p}{,}  \PYG{l+m+mf}{0.}        \PYG{p}{,}  \PYG{l+m+mf}{0.94280904}\PYG{p}{]}\PYG{p}{)}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{indices}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{p}{(}\PYG{l+m+mi}{4}\PYG{p}{,} \PYG{l+m+mi}{7}\PYG{p}{)}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{composition}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{CuAu}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{subsurf\PYGZus{}index}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{k+kc}{None}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{subsurf\PYGZus{}element}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{k+kc}{None}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{label}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{17OH}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{bonding\PYGZus{}index}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+m+mi}{40}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{bond\PYGZus{}length}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+m+mf}{1.4378365786909804}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{adsorbate}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{CH3OH}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{fragment}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{OH}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{adsorbate\PYGZus{}indices}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{p}{(}\PYG{l+m+mi}{36}\PYG{p}{,} \PYG{l+m+mi}{37}\PYG{p}{,} \PYG{l+m+mi}{38}\PYG{p}{,} \PYG{l+m+mi}{39}\PYG{p}{,} \PYG{l+m+mi}{40}\PYG{p}{,} \PYG{l+m+mi}{41}\PYG{p}{)}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{occupied}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+m+mi}{1}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{dentate}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+m+mi}{2}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{fragment\PYGZus{}indices}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{p}{(}\PYG{l+m+mi}{40}\PYG{p}{,} \PYG{l+m+mi}{41}\PYG{p}{)}\PYG{p}{\PYGZcb{}}
\end{sphinxVerbatim}
\index{get\_hetero\_connectivity() (acat.adsorbate\_coverage.SlabAdsorbateCoverage method)@\spxentry{get\_hetero\_connectivity()}\spxextra{acat.adsorbate\_coverage.SlabAdsorbateCoverage method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorbate_coverage.SlabAdsorbateCoverage.get_hetero_connectivity}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_hetero\_connectivity}}}{}{}
Get the connection matrix of slab + adsorbates.

\end{fulllineitems}

\index{get\_ads\_connectivity() (acat.adsorbate\_coverage.SlabAdsorbateCoverage method)@\spxentry{get\_ads\_connectivity()}\spxextra{acat.adsorbate\_coverage.SlabAdsorbateCoverage method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorbate_coverage.SlabAdsorbateCoverage.get_ads_connectivity}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_ads\_connectivity}}}{}{}
Get the connection matrix for adsorbate atoms.

\end{fulllineitems}

\index{get\_site\_connectivity() (acat.adsorbate\_coverage.SlabAdsorbateCoverage method)@\spxentry{get\_site\_connectivity()}\spxextra{acat.adsorbate\_coverage.SlabAdsorbateCoverage method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorbate_coverage.SlabAdsorbateCoverage.get_site_connectivity}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_site\_connectivity}}}{}{}
Get the connection matrix for adsorption sites.

\end{fulllineitems}

\index{populate\_occupied\_sites() (acat.adsorbate\_coverage.SlabAdsorbateCoverage method)@\spxentry{populate\_occupied\_sites()}\spxextra{acat.adsorbate\_coverage.SlabAdsorbateCoverage method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorbate_coverage.SlabAdsorbateCoverage.populate_occupied_sites}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{populate\_occupied\_sites}}}{}{}
Find all the occupied sites, identify the adsorbate coverage
of those sites and collect in a heterogeneous site list.

\end{fulllineitems}

\index{get\_site() (acat.adsorbate\_coverage.SlabAdsorbateCoverage method)@\spxentry{get\_site()}\spxextra{acat.adsorbate\_coverage.SlabAdsorbateCoverage method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorbate_coverage.SlabAdsorbateCoverage.get_site}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_site}}}{\emph{\DUrole{n}{indices}}}{}
Get information of a site given its atom indices.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode
\sphinxstyleliteralstrong{\sphinxupquote{indices}} (\sphinxstyleliteralemphasis{\sphinxupquote{list}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}) \textendash{} The indices of the atoms that contribute to the site.

\end{description}\end{quote}

\end{fulllineitems}

\index{get\_sites() (acat.adsorbate\_coverage.SlabAdsorbateCoverage method)@\spxentry{get\_sites()}\spxextra{acat.adsorbate\_coverage.SlabAdsorbateCoverage method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorbate_coverage.SlabAdsorbateCoverage.get_sites}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_sites}}}{\emph{\DUrole{n}{occupied\_only}\DUrole{o}{=}\DUrole{default_value}{False}}}{}
Get information of all sites.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode
\sphinxstyleliteralstrong{\sphinxupquote{occupied\_only}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to only return occupied sites.

\end{description}\end{quote}

\end{fulllineitems}

\index{get\_adsorbates() (acat.adsorbate\_coverage.SlabAdsorbateCoverage method)@\spxentry{get\_adsorbates()}\spxextra{acat.adsorbate\_coverage.SlabAdsorbateCoverage method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorbate_coverage.SlabAdsorbateCoverage.get_adsorbates}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_adsorbates}}}{}{}
Get a list of tuples that contains each adsorbate (string)
and the corresponding adsorbate indices (tuple).

\end{fulllineitems}

\index{get\_occupied\_labels() (acat.adsorbate\_coverage.SlabAdsorbateCoverage method)@\spxentry{get\_occupied\_labels()}\spxextra{acat.adsorbate\_coverage.SlabAdsorbateCoverage method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorbate_coverage.SlabAdsorbateCoverage.get_occupied_labels}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_occupied\_labels}}}{\emph{\DUrole{n}{fragmentation}\DUrole{o}{=}\DUrole{default_value}{True}}}{}
Get a list of labels of all occupied sites. The label consists
of a numerical part that represents site, and a character part
that represents the occupying adsorbate.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode
\sphinxstyleliteralstrong{\sphinxupquote{fragmentation}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default True}}) \textendash{} Whether to cut multidentate species into fragments. This ensures
that multidentate species with different orientations have
different labels.

\end{description}\end{quote}

\end{fulllineitems}

\index{get\_graph() (acat.adsorbate\_coverage.SlabAdsorbateCoverage method)@\spxentry{get\_graph()}\spxextra{acat.adsorbate\_coverage.SlabAdsorbateCoverage method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorbate_coverage.SlabAdsorbateCoverage.get_graph}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_graph}}}{\emph{\DUrole{n}{fragmentation}\DUrole{o}{=}\DUrole{default_value}{True}}}{}
Get the graph representation of the nanoparticle with adsorbates.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode
\sphinxstyleliteralstrong{\sphinxupquote{fragmentation}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default True}}) \textendash{} Whether to cut multidentate species into fragments. This ensures
that multidentate species with different orientations have
different graphs.

\end{description}\end{quote}

\end{fulllineitems}

\index{get\_coverage() (acat.adsorbate\_coverage.SlabAdsorbateCoverage method)@\spxentry{get\_coverage()}\spxextra{acat.adsorbate\_coverage.SlabAdsorbateCoverage method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorbate_coverage.SlabAdsorbateCoverage.get_coverage}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_coverage}}}{}{}
Get the adsorbate coverage (ML) of the surface.

\end{fulllineitems}

\index{get\_subsurf\_coverage() (acat.adsorbate\_coverage.SlabAdsorbateCoverage method)@\spxentry{get\_subsurf\_coverage()}\spxextra{acat.adsorbate\_coverage.SlabAdsorbateCoverage method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorbate_coverage.SlabAdsorbateCoverage.get_subsurf_coverage}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_subsurf\_coverage}}}{}{}
Get the adsorbate coverage (ML) of the subsurface.

\end{fulllineitems}


\end{fulllineitems}

\index{enumerate\_occupied\_sites() (in module acat.adsorbate\_coverage)@\spxentry{enumerate\_occupied\_sites()}\spxextra{in module acat.adsorbate\_coverage}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{modules:acat.adsorbate_coverage.enumerate_occupied_sites}}\pysiglinewithargsret{\sphinxcode{\sphinxupquote{acat.adsorbate\_coverage.}}\sphinxbfcode{\sphinxupquote{enumerate\_occupied\_sites}}}{\emph{\DUrole{n}{atoms}}, \emph{\DUrole{n}{adsorption\_sites}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{surface}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{label\_occupied\_sites}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{dmax}\DUrole{o}{=}\DUrole{default_value}{2.5}}}{}
A function that enumerates all occupied adsorption sites of
the input atoms object. The function is generalized for both
periodic and non\sphinxhyphen{}periodic systems (distinguished by atoms.pbc).
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{atoms}} (\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atoms object}}) \textendash{} Accept any ase.Atoms object. No need to be built\sphinxhyphen{}in.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{adsorption\_sites}} (\sphinxstyleliteralemphasis{\sphinxupquote{acat.adsorption\_sites.ClusterAdsorptionSites         object}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{acat.adsorption\_sites.SlabAdsorptionSites object}}\sphinxstyleliteralemphasis{\sphinxupquote{,         }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The built\sphinxhyphen{}in adsorption sites class.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{surface}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The surface type (crystal structure + Miller indices)
If the structure is a periodic surface slab, this is required.
If the structure is a nanoparticle, the function enumerates
only the sites on the specified surface.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{label\_occupied\_sites}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to assign a label to the occupied each site. The string
of the occupying adsorbate is concatentated to the numerical
label that represents the occpied site.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{dmax}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 2.5}}) \textendash{} The maximum bond length (in Angstrom) between the site and the
bonding atom  that should be considered as an adsorbate.

\end{itemize}

\end{description}\end{quote}
\subsubsection*{Example}

This is an example of enumerating all occupied sites on a truncated
octahedral nanoparticle:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{adsorption\PYGZus{}sites} \PYG{k+kn}{import} \PYG{n}{ClusterAdsorptionSites}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{adsorbate\PYGZus{}coverage} \PYG{k+kn}{import} \PYG{n}{enumerate\PYGZus{}occupied\PYGZus{}sites}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{build}\PYG{n+nn}{.}\PYG{n+nn}{actions} \PYG{k+kn}{import} \PYG{n}{add\PYGZus{}adsorbate\PYGZus{}to\PYGZus{}site}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{cluster} \PYG{k+kn}{import} \PYG{n}{Octahedron}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms} \PYG{o}{=} \PYG{n}{Octahedron}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Ni}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{n}{length}\PYG{o}{=}\PYG{l+m+mi}{7}\PYG{p}{,} \PYG{n}{cutoff}\PYG{o}{=}\PYG{l+m+mi}{2}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k}{for} \PYG{n}{atom} \PYG{o+ow}{in} \PYG{n}{atoms}\PYG{p}{:}
\PYG{g+gp}{... }    \PYG{k}{if} \PYG{n}{atom}\PYG{o}{.}\PYG{n}{index} \PYG{o}{\PYGZpc{}} \PYG{l+m+mi}{2} \PYG{o}{==} \PYG{l+m+mi}{0}\PYG{p}{:}
\PYG{g+gp}{... }        \PYG{n}{atom}\PYG{o}{.}\PYG{n}{symbol} \PYG{o}{=} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Pt}\PYG{l+s+s1}{\PYGZsq{}}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms}\PYG{o}{.}\PYG{n}{center}\PYG{p}{(}\PYG{n}{vacuum}\PYG{o}{=}\PYG{l+m+mf}{5.}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{cas} \PYG{o}{=} \PYG{n}{ClusterAdsorptionSites}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{composition\PYGZus{}effect}\PYG{o}{=}\PYG{k+kc}{True}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{sites} \PYG{o}{=} \PYG{n}{cas}\PYG{o}{.}\PYG{n}{get\PYGZus{}sites}\PYG{p}{(}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k}{for} \PYG{n}{s} \PYG{o+ow}{in} \PYG{n}{sites}\PYG{p}{:}
\PYG{g+gp}{... }    \PYG{k}{if} \PYG{n}{s}\PYG{p}{[}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{site}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]} \PYG{o}{==} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{ontop}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:}
\PYG{g+gp}{... }        \PYG{n}{add\PYGZus{}adsorbate\PYGZus{}to\PYGZus{}site}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{adsorbate}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{OH}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{n}{site}\PYG{o}{=}\PYG{n}{s}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{sites} \PYG{o}{=} \PYG{n}{enumerate\PYGZus{}occupied\PYGZus{}sites}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{adsorption\PYGZus{}sites}\PYG{o}{=}\PYG{n}{cas}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n+nb}{print}\PYG{p}{(}\PYG{n}{sites}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{p}{)}
\end{sphinxVerbatim}

Output:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{p}{\PYGZob{}}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{site}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{ontop}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{surface}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{fcc111}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{position}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{n}{array}\PYG{p}{(}\PYG{p}{[} \PYG{l+m+mf}{6.76}\PYG{p}{,}  \PYG{l+m+mf}{8.52}\PYG{p}{,} \PYG{l+m+mf}{10.28}\PYG{p}{]}\PYG{p}{)}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{normal}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{n}{array}\PYG{p}{(}\PYG{p}{[}\PYG{o}{\PYGZhy{}}\PYG{l+m+mf}{0.57735027}\PYG{p}{,} \PYG{o}{\PYGZhy{}}\PYG{l+m+mf}{0.57735027}\PYG{p}{,} \PYG{o}{\PYGZhy{}}\PYG{l+m+mf}{0.57735027}\PYG{p}{]}\PYG{p}{)}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{indices}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{p}{(}\PYG{l+m+mi}{2}\PYG{p}{,}\PYG{p}{)}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{composition}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Pt}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{subsurf\PYGZus{}index}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{k+kc}{None}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{subsurf\PYGZus{}element}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{k+kc}{None}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{label}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{k+kc}{None}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{bonding\PYGZus{}index}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+m+mi}{201}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{bond\PYGZus{}length}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+m+mf}{1.7999999999999996}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{adsorbate}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{OH}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{fragment}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{OH}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{adsorbate\PYGZus{}indices}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{p}{(}\PYG{l+m+mi}{201}\PYG{p}{,} \PYG{l+m+mi}{202}\PYG{p}{)}\PYG{p}{,}
 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{occupied}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+m+mi}{1}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{dentate}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+m+mi}{1}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{fragment\PYGZus{}indices}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{p}{(}\PYG{l+m+mi}{201}\PYG{p}{,} \PYG{l+m+mi}{202}\PYG{p}{)}\PYG{p}{\PYGZcb{}}
\end{sphinxVerbatim}

\end{fulllineitems}



\section{Building things}
\label{\detokenize{build:building-things}}\label{\detokenize{build::doc}}

\subsection{Operate adsorbate}
\label{\detokenize{build:module-acat.build.actions}}\label{\detokenize{build:operate-adsorbate}}\index{module@\spxentry{module}!acat.build.actions@\spxentry{acat.build.actions}}\index{acat.build.actions@\spxentry{acat.build.actions}!module@\spxentry{module}}\index{add\_adsorbate() (in module acat.build.actions)@\spxentry{add\_adsorbate()}\spxextra{in module acat.build.actions}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{build:acat.build.actions.add_adsorbate}}\pysiglinewithargsret{\sphinxcode{\sphinxupquote{acat.build.actions.}}\sphinxbfcode{\sphinxupquote{add\_adsorbate}}}{\emph{\DUrole{n}{atoms}}, \emph{\DUrole{n}{adsorbate}}, \emph{\DUrole{n}{site}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{surface}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{geometry}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{indices}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{height}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{composition}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{orientation}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{tilt\_angle}\DUrole{o}{=}\DUrole{default_value}{0.0}}, \emph{\DUrole{n}{subsurf\_element}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{all\_sites}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
A general function for adding one adsorbate to the surface.
Note that this function adds one adsorbate to a random site
that meets the specified condition regardless of it is already
occupied or not. The function is generalized for both periodic
and non\sphinxhyphen{}periodic systems (distinguished by atoms.pbc).
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{atoms}} (\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atoms object}}) \textendash{} Accept any ase.Atoms object. No need to be built\sphinxhyphen{}in.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{adsorbate}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atom object}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atoms object}}) \textendash{} The adsorbate species to be added onto the surface.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{site}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The site type that the adsorbate should be added to.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{surface}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The surface type (crystal structure + Miller indices)
If the structure is a periodic surface slab, this is required.
If the structure is a nanoparticle, the function enumerates
only the sites on the specified surface.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{geometry}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The geometry type that the adsorbate should be added to.
Only available for surface slabs.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{indices}} (\sphinxstyleliteralemphasis{\sphinxupquote{list}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{tuple}}) \textendash{} The indices of the atoms that contribute to the site that
you want to add adsorbate to. This has the highest priority.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{height}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The height of the added adsorbate from the surface.
Use the default settings if not specified.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{composition}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The elemental of the site that should be added to.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{orientation}} (\sphinxstyleliteralemphasis{\sphinxupquote{list}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{numpy.array}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The vector that the multidentate adsorbate is aligned to.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{tilt\_angle}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 0.}}) \textendash{} Tilt the adsorbate with an angle (in degress) relative to
the surface normal.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{subsurf\_element}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The subsurface element of the hcp or 4fold hollow site that
should be added to.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{all\_sites}} (\sphinxstyleliteralemphasis{\sphinxupquote{list of dicts}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The list of all sites. Provide this to make the function
much faster. Useful when the function is called many times.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}


\sphinxstylestrong{Example}

To add a NO molecule to a bridge site consists of one Pt and
one Ni on the fcc111 surface of a truncated octahedron:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{build}\PYG{n+nn}{.}\PYG{n+nn}{actions} \PYG{k+kn}{import} \PYG{n}{add\PYGZus{}adsorbate}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{cluster} \PYG{k+kn}{import} \PYG{n}{Octahedron}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{visualize} \PYG{k+kn}{import} \PYG{n}{view}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms} \PYG{o}{=} \PYG{n}{Octahedron}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Ni}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{n}{length}\PYG{o}{=}\PYG{l+m+mi}{7}\PYG{p}{,} \PYG{n}{cutoff}\PYG{o}{=}\PYG{l+m+mi}{2}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k}{for} \PYG{n}{atom} \PYG{o+ow}{in} \PYG{n}{atoms}\PYG{p}{:}
\PYG{g+gp}{... }    \PYG{k}{if} \PYG{n}{atom}\PYG{o}{.}\PYG{n}{index} \PYG{o}{\PYGZpc{}} \PYG{l+m+mi}{2} \PYG{o}{==} \PYG{l+m+mi}{0}\PYG{p}{:}
\PYG{g+gp}{... }        \PYG{n}{atom}\PYG{o}{.}\PYG{n}{symbol} \PYG{o}{=} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Pt}\PYG{l+s+s1}{\PYGZsq{}}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{add\PYGZus{}adsorbate}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{adsorbate}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{NO}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{n}{site}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{bridge}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
\PYG{g+gp}{... }              \PYG{n}{surface}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{fcc111}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{n}{composition}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{NiPt}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{view}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{)}
\end{sphinxVerbatim}

Output:

\noindent{\hspace*{\fill}\sphinxincludegraphics[scale=0.7]{{add_adsorbate}.png}\hspace*{\fill}}
\index{add\_adsorbate\_to\_site() (in module acat.build.actions)@\spxentry{add\_adsorbate\_to\_site()}\spxextra{in module acat.build.actions}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{build:acat.build.actions.add_adsorbate_to_site}}\pysiglinewithargsret{\sphinxcode{\sphinxupquote{acat.build.actions.}}\sphinxbfcode{\sphinxupquote{add\_adsorbate\_to\_site}}}{\emph{\DUrole{n}{atoms}}, \emph{\DUrole{n}{adsorbate}}, \emph{\DUrole{n}{site}}, \emph{\DUrole{n}{height}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{orientation}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{tilt\_angle}\DUrole{o}{=}\DUrole{default_value}{0.0}}}{}
The base function for adding one adsorbate to a site.
Site must include information of ‘normal’ and ‘position’.
Useful for adding adsorbate to multiple sites or adding
multidentate adsorbates.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{atoms}} (\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atoms object}}) \textendash{} Accept any ase.Atoms object. No need to be built\sphinxhyphen{}in.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{adsorbate}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atom object}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atoms object}}) \textendash{} The adsorbate species to be added onto the surface.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{site}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}) \textendash{} The site that the adsorbate should be added to.
Must contain information of the position and the
normal vector of the site.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{height}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The height of the added adsorbate from the surface.
Use the default settings if not specified.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{orientation}} (\sphinxstyleliteralemphasis{\sphinxupquote{list}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{numpy.array}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The vector that the multidentate adsorbate is aligned to.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{tilt\_angle}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} Tilt the adsorbate with an angle (in degress) relative to
the surface normal.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}


\sphinxstylestrong{Example}

To add CO to all fcc sites of an icosahedral nanoparticle:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{adsorption\PYGZus{}sites} \PYG{k+kn}{import} \PYG{n}{ClusterAdsorptionSites}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{build}\PYG{n+nn}{.}\PYG{n+nn}{actions} \PYG{k+kn}{import} \PYG{n}{add\PYGZus{}adsorbate\PYGZus{}to\PYGZus{}site}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{cluster} \PYG{k+kn}{import} \PYG{n}{Icosahedron}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{visualize} \PYG{k+kn}{import} \PYG{n}{view}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms} \PYG{o}{=} \PYG{n}{Icosahedron}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Pt}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{n}{noshells}\PYG{o}{=}\PYG{l+m+mi}{5}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms}\PYG{o}{.}\PYG{n}{center}\PYG{p}{(}\PYG{n}{vacuum}\PYG{o}{=}\PYG{l+m+mf}{5.}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{cas} \PYG{o}{=} \PYG{n}{ClusterAdsorptionSites}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{fcc\PYGZus{}sites} \PYG{o}{=} \PYG{n}{cas}\PYG{o}{.}\PYG{n}{get\PYGZus{}sites}\PYG{p}{(}\PYG{n}{site}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{fcc}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k}{for} \PYG{n}{site} \PYG{o+ow}{in} \PYG{n}{fcc\PYGZus{}sites}\PYG{p}{:}
\PYG{g+gp}{... }    \PYG{n}{add\PYGZus{}adsorbate\PYGZus{}to\PYGZus{}site}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{adsorbate}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{CO}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{n}{site}\PYG{o}{=}\PYG{n}{site}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{view}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{)}
\end{sphinxVerbatim}

Output:

\noindent{\hspace*{\fill}\sphinxincludegraphics{{add_adsorbate_to_site_1}.png}\hspace*{\fill}}

To add a bidentate CH3OH to the (54, 57, 58) site on a Pt fcc111
surface slab and rotate the orientation to a neighbor site:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{adsorption\PYGZus{}sites} \PYG{k+kn}{import} \PYG{n}{SlabAdsorptionSites}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{adsorption\PYGZus{}sites} \PYG{k+kn}{import} \PYG{n}{get\PYGZus{}adsorption\PYGZus{}site}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{build}\PYG{n+nn}{.}\PYG{n+nn}{actions} \PYG{k+kn}{import} \PYG{n}{add\PYGZus{}adsorbate\PYGZus{}to\PYGZus{}site}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{utilities} \PYG{k+kn}{import} \PYG{n}{get\PYGZus{}mic}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{build} \PYG{k+kn}{import} \PYG{n}{fcc111}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{visualize} \PYG{k+kn}{import} \PYG{n}{view}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms} \PYG{o}{=} \PYG{n}{fcc111}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Pt}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{p}{(}\PYG{l+m+mi}{4}\PYG{p}{,} \PYG{l+m+mi}{4}\PYG{p}{,} \PYG{l+m+mi}{4}\PYG{p}{)}\PYG{p}{,} \PYG{n}{vacuum}\PYG{o}{=}\PYG{l+m+mf}{5.}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{i}\PYG{p}{,} \PYG{n}{site} \PYG{o}{=} \PYG{n}{get\PYGZus{}adsorption\PYGZus{}site}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{indices}\PYG{o}{=}\PYG{p}{(}\PYG{l+m+mi}{54}\PYG{p}{,} \PYG{l+m+mi}{57}\PYG{p}{,} \PYG{l+m+mi}{58}\PYG{p}{)}\PYG{p}{,}
\PYG{g+gp}{... }                              \PYG{n}{surface}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{fcc111}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
\PYG{g+gp}{... }                              \PYG{n}{return\PYGZus{}index}\PYG{o}{=}\PYG{k+kc}{True}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{sas} \PYG{o}{=} \PYG{n}{SlabAdsorptionSites}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{surface}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{fcc111}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{sites} \PYG{o}{=} \PYG{n}{sas}\PYG{o}{.}\PYG{n}{get\PYGZus{}sites}\PYG{p}{(}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{nbsites} \PYG{o}{=} \PYG{n}{sas}\PYG{o}{.}\PYG{n}{get\PYGZus{}neighbor\PYGZus{}site\PYGZus{}list}\PYG{p}{(}\PYG{n}{neighbor\PYGZus{}number}\PYG{o}{=}\PYG{l+m+mi}{1}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{nbsite} \PYG{o}{=} \PYG{n}{sites}\PYG{p}{[}\PYG{n}{nbsites}\PYG{p}{[}\PYG{n}{i}\PYG{p}{]}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{p}{]} \PYG{c+c1}{\PYGZsh{} Choose the first neighbor site}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{ori} \PYG{o}{=} \PYG{n}{get\PYGZus{}mic}\PYG{p}{(}\PYG{n}{site}\PYG{p}{[}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{position}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]}\PYG{p}{,} \PYG{n}{nbsite}\PYG{p}{[}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{position}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]}\PYG{p}{,} \PYG{n}{atoms}\PYG{o}{.}\PYG{n}{cell}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{add\PYGZus{}adsorbate\PYGZus{}to\PYGZus{}site}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{adsorbate}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{CH3OH}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{n}{site}\PYG{o}{=}\PYG{n}{site}\PYG{p}{,}
\PYG{g+gp}{... }                      \PYG{n}{orientation}\PYG{o}{=}\PYG{n}{ori}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{view}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{)}
\end{sphinxVerbatim}

Output:

\noindent{\hspace*{\fill}\sphinxincludegraphics[scale=0.7]{{add_adsorbate_to_site_2}.png}\hspace*{\fill}}
\index{add\_adsorbate\_to\_label() (in module acat.build.actions)@\spxentry{add\_adsorbate\_to\_label()}\spxextra{in module acat.build.actions}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{build:acat.build.actions.add_adsorbate_to_label}}\pysiglinewithargsret{\sphinxcode{\sphinxupquote{acat.build.actions.}}\sphinxbfcode{\sphinxupquote{add\_adsorbate\_to\_label}}}{\emph{\DUrole{n}{atoms}}, \emph{\DUrole{n}{adsorbate}}, \emph{\DUrole{n}{label}}, \emph{\DUrole{n}{surface}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{height}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{orientation}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{tilt\_angle}\DUrole{o}{=}\DUrole{default_value}{0.0}}, \emph{\DUrole{n}{composition\_effect}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{all\_sites}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
Same as add\_adsorbate function, except that the site type is
represented by a numerical label. The function is generalized for
both periodic and non\sphinxhyphen{}periodic systems (distinguished by atoms.pbc).
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{atoms}} (\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atoms object}}) \textendash{} Accept any ase.Atoms object. No need to be built\sphinxhyphen{}in.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{adsorbate}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atom object}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atoms object}}) \textendash{} The adsorbate species to be added onto the surface.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{label}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} The label of the site that the adsorbate should be added to.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{surface}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The surface type (crystal structure + Miller indices)
If the structure is a periodic surface slab, this is required.
If the structure is a nanoparticle, the function enumerates
only the sites on the specified surface.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{height}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The height of the added adsorbate from the surface.
Use the default settings if not specified.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{orientation}} (\sphinxstyleliteralemphasis{\sphinxupquote{list}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{numpy.array}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The vector that the multidentate adsorbate is aligned to.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{tilt\_angle}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 0.}}) \textendash{} Tilt the adsorbate with an angle (in degress) relative to
the surface normal.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{composition\_effect}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether the label is defined in bimetallic labels or not.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{all\_sites}} (\sphinxstyleliteralemphasis{\sphinxupquote{list of dicts}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The list of all sites. Provide this to make the function
much faster. Useful when the function is called many times.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}


\sphinxstylestrong{Example}

To add a NH molecule to a site with bimetallic label 14 (an hcp
CuCuAu site) on a fcc110 surface slab:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{build}\PYG{n+nn}{.}\PYG{n+nn}{actions} \PYG{k+kn}{import} \PYG{n}{add\PYGZus{}adsorbate\PYGZus{}to\PYGZus{}label}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{build} \PYG{k+kn}{import} \PYG{n}{fcc110}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{visualize} \PYG{k+kn}{import} \PYG{n}{view}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms} \PYG{o}{=} \PYG{n}{fcc110}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Cu}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{p}{(}\PYG{l+m+mi}{3}\PYG{p}{,} \PYG{l+m+mi}{3}\PYG{p}{,} \PYG{l+m+mi}{8}\PYG{p}{)}\PYG{p}{,} \PYG{n}{vacuum}\PYG{o}{=}\PYG{l+m+mf}{5.}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k}{for} \PYG{n}{atom} \PYG{o+ow}{in} \PYG{n}{atoms}\PYG{p}{:}
\PYG{g+gp}{... }    \PYG{k}{if} \PYG{n}{atom}\PYG{o}{.}\PYG{n}{index} \PYG{o}{\PYGZpc{}} \PYG{l+m+mi}{2} \PYG{o}{==} \PYG{l+m+mi}{0}\PYG{p}{:}
\PYG{g+gp}{... }        \PYG{n}{atom}\PYG{o}{.}\PYG{n}{symbol} \PYG{o}{=} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Au}\PYG{l+s+s1}{\PYGZsq{}}
\PYG{g+gp}{... }\PYG{n}{atoms}\PYG{o}{.}\PYG{n}{center}\PYG{p}{(}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{add\PYGZus{}adsorbate\PYGZus{}to\PYGZus{}label}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{adsorbate}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{NH}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{n}{label}\PYG{o}{=}\PYG{l+m+mi}{14}\PYG{p}{,}
\PYG{g+gp}{... }                       \PYG{n}{surface}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{fcc110}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{n}{composition\PYGZus{}effect}\PYG{o}{=}\PYG{k+kc}{True}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{view}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{)}
\end{sphinxVerbatim}

Output:

\noindent{\hspace*{\fill}\sphinxincludegraphics[scale=0.7]{{add_adsorbate_to_label}.png}\hspace*{\fill}}
\index{remove\_adsorbate\_from\_site() (in module acat.build.actions)@\spxentry{remove\_adsorbate\_from\_site()}\spxextra{in module acat.build.actions}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{build:acat.build.actions.remove_adsorbate_from_site}}\pysiglinewithargsret{\sphinxcode{\sphinxupquote{acat.build.actions.}}\sphinxbfcode{\sphinxupquote{remove\_adsorbate\_from\_site}}}{\emph{\DUrole{n}{atoms}}, \emph{\DUrole{n}{site}}, \emph{\DUrole{n}{remove\_fragment}\DUrole{o}{=}\DUrole{default_value}{False}}}{}
The base function for removing one adsorbate from an
occupied site. The site must include information of
‘adsorbate\_indices’ or ‘fragment\_indices’. Note that if
you want to remove adsorbates from multiple sites, call
this function multiple times will return the wrong result.
Please use remove\_adsorbates\_from\_sites instead.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{atoms}} (\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atoms object}}) \textendash{} Accept any ase.Atoms object. No need to be built\sphinxhyphen{}in.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{site}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}) \textendash{} The site that the adsorbate should be removed from.
Must contain information of the adsorbate indices.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{remove\_fragment}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Remove the fragment of a multidentate adsorbate instead
of the whole adsorbate.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}


\sphinxstylestrong{Example}

To remove a CO molecule from a fcc111 surface slab with one
CO and one OH:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{adsorption\PYGZus{}sites} \PYG{k+kn}{import} \PYG{n}{SlabAdsorptionSites}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{adsorbate\PYGZus{}coverage} \PYG{k+kn}{import} \PYG{n}{SlabAdsorbateCoverage}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{build}\PYG{n+nn}{.}\PYG{n+nn}{actions} \PYG{k+kn}{import} \PYG{n}{add\PYGZus{}adsorbate\PYGZus{}to\PYGZus{}site}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{build}\PYG{n+nn}{.}\PYG{n+nn}{actions} \PYG{k+kn}{import} \PYG{n}{remove\PYGZus{}adsorbate\PYGZus{}from\PYGZus{}site}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{build} \PYG{k+kn}{import} \PYG{n}{fcc111}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{visualize} \PYG{k+kn}{import} \PYG{n}{view}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms} \PYG{o}{=} \PYG{n}{fcc111}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Pt}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{p}{(}\PYG{l+m+mi}{6}\PYG{p}{,} \PYG{l+m+mi}{6}\PYG{p}{,} \PYG{l+m+mi}{4}\PYG{p}{)}\PYG{p}{,} \PYG{l+m+mi}{4}\PYG{p}{,} \PYG{n}{vacuum}\PYG{o}{=}\PYG{l+m+mf}{5.}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms}\PYG{o}{.}\PYG{n}{center}\PYG{p}{(}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{sas} \PYG{o}{=} \PYG{n}{SlabAdsorptionSites}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{surface}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{fcc111}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{sites} \PYG{o}{=} \PYG{n}{sas}\PYG{o}{.}\PYG{n}{get\PYGZus{}sites}\PYG{p}{(}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{add\PYGZus{}adsorbate\PYGZus{}to\PYGZus{}site}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{adsorbate}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{OH}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{n}{site}\PYG{o}{=}\PYG{n}{sites}\PYG{p}{[}\PYG{l+m+mi}{0}\PYG{p}{]}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{add\PYGZus{}adsorbate\PYGZus{}to\PYGZus{}site}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{adsorbate}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{CO}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{n}{site}\PYG{o}{=}\PYG{n}{sites}\PYG{p}{[}\PYG{o}{\PYGZhy{}}\PYG{l+m+mi}{1}\PYG{p}{]}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{sac} \PYG{o}{=} \PYG{n}{SlabAdsorbateCoverage}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{sas}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{occupied\PYGZus{}sites} \PYG{o}{=} \PYG{n}{sac}\PYG{o}{.}\PYG{n}{get\PYGZus{}sites}\PYG{p}{(}\PYG{n}{occupied\PYGZus{}only}\PYG{o}{=}\PYG{k+kc}{True}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{CO\PYGZus{}site} \PYG{o}{=} \PYG{n+nb}{next}\PYG{p}{(}\PYG{p}{(}\PYG{n}{s} \PYG{k}{for} \PYG{n}{s} \PYG{o+ow}{in} \PYG{n}{occupied\PYGZus{}sites} \PYG{k}{if} \PYG{n}{s}\PYG{p}{[}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{adsorbate}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]} \PYG{o}{==} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{CO}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{remove\PYGZus{}adsorbate\PYGZus{}from\PYGZus{}site}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{site}\PYG{o}{=}\PYG{n}{CO\PYGZus{}site}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{view}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{)}
\end{sphinxVerbatim}

\noindent\sphinxincludegraphics[scale=0.6]{{remove_adsorbate_from_site}.png}
\index{remove\_adsorbates\_from\_sites() (in module acat.build.actions)@\spxentry{remove\_adsorbates\_from\_sites()}\spxextra{in module acat.build.actions}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{build:acat.build.actions.remove_adsorbates_from_sites}}\pysiglinewithargsret{\sphinxcode{\sphinxupquote{acat.build.actions.}}\sphinxbfcode{\sphinxupquote{remove\_adsorbates\_from\_sites}}}{\emph{\DUrole{n}{atoms}}, \emph{\DUrole{n}{sites}}, \emph{\DUrole{n}{remove\_fragments}\DUrole{o}{=}\DUrole{default_value}{False}}}{}
The base function for removing multiple adsorbates from
an occupied site. The sites must include information of
‘adsorbate\_indices’ or ‘fragment\_indices’.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{atoms}} (\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atoms object}}) \textendash{} Accept any ase.Atoms object. No need to be built\sphinxhyphen{}in.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{sites}} (\sphinxstyleliteralemphasis{\sphinxupquote{list of dicts}}) \textendash{} The site that the adsorbate should be removed from.
Must contain information of the adsorbate indices.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{remove\_fragments}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Remove the fragment of a multidentate adsorbate instead
of the whole adsorbate.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}


\sphinxstylestrong{Example}

To remove all CO species from a fcc111 surface slab covered
with both CO and OH:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{adsorption\PYGZus{}sites} \PYG{k+kn}{import} \PYG{n}{SlabAdsorptionSites}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{adsorbate\PYGZus{}coverage} \PYG{k+kn}{import} \PYG{n}{SlabAdsorbateCoverage}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{build}\PYG{n+nn}{.}\PYG{n+nn}{patterns} \PYG{k+kn}{import} \PYG{n}{random\PYGZus{}coverage\PYGZus{}pattern}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{build}\PYG{n+nn}{.}\PYG{n+nn}{actions} \PYG{k+kn}{import} \PYG{n}{remove\PYGZus{}adsorbates\PYGZus{}from\PYGZus{}sites}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{build} \PYG{k+kn}{import} \PYG{n}{fcc111}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{visualize} \PYG{k+kn}{import} \PYG{n}{view}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{slab} \PYG{o}{=} \PYG{n}{fcc111}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Pt}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{p}{(}\PYG{l+m+mi}{6}\PYG{p}{,} \PYG{l+m+mi}{6}\PYG{p}{,} \PYG{l+m+mi}{4}\PYG{p}{)}\PYG{p}{,} \PYG{l+m+mi}{4}\PYG{p}{,} \PYG{n}{vacuum}\PYG{o}{=}\PYG{l+m+mf}{5.}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{slab}\PYG{o}{.}\PYG{n}{center}\PYG{p}{(}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms} \PYG{o}{=} \PYG{n}{random\PYGZus{}coverage\PYGZus{}pattern}\PYG{p}{(}\PYG{n}{slab}\PYG{p}{,} \PYG{n}{adsorbate\PYGZus{}species}\PYG{o}{=}\PYG{p}{[}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{OH}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{CO}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]}\PYG{p}{,}
\PYG{g+gp}{... }                                \PYG{n}{surface}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{fcc111}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
\PYG{g+gp}{... }                                \PYG{n}{min\PYGZus{}adsorbate\PYGZus{}distance}\PYG{o}{=}\PYG{l+m+mf}{5.}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{sas} \PYG{o}{=} \PYG{n}{SlabAdsorptionSites}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{surface}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{fcc111}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{sac} \PYG{o}{=} \PYG{n}{SlabAdsorbateCoverage}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{sas}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{occupied\PYGZus{}sites} \PYG{o}{=} \PYG{n}{sac}\PYG{o}{.}\PYG{n}{get\PYGZus{}sites}\PYG{p}{(}\PYG{n}{occupied\PYGZus{}only}\PYG{o}{=}\PYG{k+kc}{True}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{CO\PYGZus{}sites} \PYG{o}{=} \PYG{p}{[}\PYG{n}{s} \PYG{k}{for} \PYG{n}{s} \PYG{o+ow}{in} \PYG{n}{occupied\PYGZus{}sites} \PYG{k}{if} \PYG{n}{s}\PYG{p}{[}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{adsorbate}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]} \PYG{o}{==} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{CO}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{remove\PYGZus{}adsorbates\PYGZus{}from\PYGZus{}sites}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{sites}\PYG{o}{=}\PYG{n}{CO\PYGZus{}sites}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{view}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{)}
\end{sphinxVerbatim}

Output:

\noindent\sphinxincludegraphics[scale=0.6]{{remove_adsorbates_from_sites}.png}
\index{remove\_adsorbates\_too\_close() (in module acat.build.actions)@\spxentry{remove\_adsorbates\_too\_close()}\spxextra{in module acat.build.actions}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{build:acat.build.actions.remove_adsorbates_too_close}}\pysiglinewithargsret{\sphinxcode{\sphinxupquote{acat.build.actions.}}\sphinxbfcode{\sphinxupquote{remove\_adsorbates\_too\_close}}}{\emph{\DUrole{n}{atoms}}, \emph{\DUrole{n}{adsorbate\_coverage}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{surface}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{min\_adsorbate\_distance}\DUrole{o}{=}\DUrole{default_value}{0.5}}}{}
Find adsorbates that are too close, remove one set of them.
The function is intended to remove atoms that are unphysically
close. Please do not use a min\_adsorbate\_distace larger than 2.
The function is generalized for both periodic and non\sphinxhyphen{}periodic
systems (distinguished by atoms.pbc).
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{atoms}} (\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atoms object}}) \textendash{} The nanoparticle or surface slab onto which the adsorbates are
added. Accept any ase.Atoms object. No need to be built\sphinxhyphen{}in.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{adsorbate\_coverage}} (\sphinxstyleliteralemphasis{\sphinxupquote{acat.adsorbate\_coverage.ClusterAdsorbateCoverage         object}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{acat.adsorbate\_coverage.SlabAdsorbateCoverage object}}\sphinxstyleliteralemphasis{\sphinxupquote{,         }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The built\sphinxhyphen{}in adsorbate coverage class.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{surface}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The surface type (crystal structure + Miller indices).
If the structure is a periodic surface slab, this is required.
If the structure is a nanoparticle, the function only add
adsorbates to the sites on the specified surface.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{min\_adsorbate\_distance}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 0.}}) \textendash{} The minimum distance between two atoms that is not considered to
be to close. This distance has to be small.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}


\sphinxstylestrong{Example}

To remove unphysically close adsorbates on the edges of a Marks
decahedron with 0.75 ML symmetric CO coverage:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{build}\PYG{n+nn}{.}\PYG{n+nn}{patterns} \PYG{k+kn}{import} \PYG{n}{symmetric\PYGZus{}coverage\PYGZus{}pattern}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{build}\PYG{n+nn}{.}\PYG{n+nn}{actions} \PYG{k+kn}{import} \PYG{n}{remove\PYGZus{}adsorbates\PYGZus{}too\PYGZus{}close}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{cluster} \PYG{k+kn}{import} \PYG{n}{Decahedron}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{visualize} \PYG{k+kn}{import} \PYG{n}{view}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms} \PYG{o}{=} \PYG{n}{Decahedron}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Pt}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{n}{p}\PYG{o}{=}\PYG{l+m+mi}{4}\PYG{p}{,} \PYG{n}{q}\PYG{o}{=}\PYG{l+m+mi}{3}\PYG{p}{,} \PYG{n}{r}\PYG{o}{=}\PYG{l+m+mi}{1}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms}\PYG{o}{.}\PYG{n}{center}\PYG{p}{(}\PYG{n}{vacuum}\PYG{o}{=}\PYG{l+m+mf}{5.}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{pattern} \PYG{o}{=} \PYG{n}{symmetric\PYGZus{}coverage\PYGZus{}pattern}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{adsorbate}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{CO}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
\PYG{g+gp}{... }                                     \PYG{n}{coverage}\PYG{o}{=}\PYG{l+m+mf}{0.75}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{remove\PYGZus{}adsorbates\PYGZus{}too\PYGZus{}close}\PYG{p}{(}\PYG{n}{pattern}\PYG{p}{,} \PYG{n}{min\PYGZus{}adsorbate\PYGZus{}distance}\PYG{o}{=}\PYG{l+m+mf}{1.}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{view}\PYG{p}{(}\PYG{n}{pattern}\PYG{p}{)}
\end{sphinxVerbatim}

Output:

\noindent\sphinxincludegraphics{{remove_adsorbates_too_close}.png}


\subsection{Generate adsorbate coverage patterns}
\label{\detokenize{build:module-acat.build.patterns}}\label{\detokenize{build:generate-adsorbate-coverage-patterns}}\index{module@\spxentry{module}!acat.build.patterns@\spxentry{acat.build.patterns}}\index{acat.build.patterns@\spxentry{acat.build.patterns}!module@\spxentry{module}}\index{StochasticPatternGenerator (class in acat.build.patterns)@\spxentry{StochasticPatternGenerator}\spxextra{class in acat.build.patterns}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{build:acat.build.patterns.StochasticPatternGenerator}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class }}\sphinxcode{\sphinxupquote{acat.build.patterns.}}\sphinxbfcode{\sphinxupquote{StochasticPatternGenerator}}}{\emph{\DUrole{n}{images}}, \emph{\DUrole{n}{adsorbate\_species}}, \emph{\DUrole{n}{image\_probabilities}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{species\_probabilities}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{min\_adsorbate\_distance}\DUrole{o}{=}\DUrole{default_value}{1.5}}, \emph{\DUrole{n}{adsorption\_sites}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{surface}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{heights}\DUrole{o}{=}\DUrole{default_value}{\{\textquotesingle{}3fold\textquotesingle{}: 1.3, \textquotesingle{}4fold\textquotesingle{}: 1.3, \textquotesingle{}5fold\textquotesingle{}: 1.5, \textquotesingle{}6fold\textquotesingle{}: 0.0, \textquotesingle{}bridge\textquotesingle{}: 1.5, \textquotesingle{}fcc\textquotesingle{}: 1.3, \textquotesingle{}hcp\textquotesingle{}: 1.3, \textquotesingle{}longbridge\textquotesingle{}: 1.5, \textquotesingle{}ontop\textquotesingle{}: 1.8, \textquotesingle{}shortbridge\textquotesingle{}: 1.5\}}}, \emph{\DUrole{n}{allow\_6fold}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{composition\_effect}\DUrole{o}{=}\DUrole{default_value}{True}}, \emph{\DUrole{n}{dmax}\DUrole{o}{=}\DUrole{default_value}{2.5}}, \emph{\DUrole{n}{species\_forbidden\_sites}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{species\_forbidden\_labels}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{fragmentation}\DUrole{o}{=}\DUrole{default_value}{True}}, \emph{\DUrole{n}{trajectory}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}patterns.traj\textquotesingle{}}}, \emph{\DUrole{n}{append\_trajectory}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{logfile}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}patterns.log\textquotesingle{}}}}{}
\sphinxtitleref{StochasticPatternGenerator} is a class for generating
adsorbate coverage patterns stochastically. Graph isomorphism
is implemented to identify identical coverage patterns.
4 adsorbate actions are supported: add, remove, move, replace.
The function is generalized for both periodic and non\sphinxhyphen{}periodic
systems (distinguished by atoms.pbc).
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{images}} (\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atoms object}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{list of ase.Atoms objects}}) \textendash{} The structure to perform the adsorbate actions on.
If a list of structures is provided, perform one
adsorbate action on one of the structures in each step.
Accept any ase.Atoms object. No need to be built\sphinxhyphen{}in.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{adsorbate\_species}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{list of strs}}) \textendash{} A list of adsorbate species to be randomly added to the surface.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{image\_probabilities}} (\sphinxstyleliteralemphasis{\sphinxupquote{listt}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} A list of the probabilities of selecting each structure.
Selecting structure with equal probability if not specified.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{species\_probabilities}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} A dictionary that contains keys of each adsorbate species and
values of their probabilities of adding onto the surface.
Adding adsorbate species with equal probability if not specified.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{min\_adsorbate\_distance}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 1.5}}) \textendash{} The minimum distance constraint between two atoms that belongs
to two adsorbates.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{adsorption\_sites}} (\sphinxstyleliteralemphasis{\sphinxupquote{acat.adsorption\_sites.ClusterAdsorptionSites object}}\sphinxstyleliteralemphasis{\sphinxupquote{         or }}\sphinxstyleliteralemphasis{\sphinxupquote{acat.adsorption\_sites.SlabAdsorptionSites object}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} Provide the built\sphinxhyphen{}in adsorption sites class to accelerate the
pattern generation. Make sure all the structures have the same
periodicity and atom indexing. If composition\_effect=True, you
should only provide adsorption\_sites when the surface composition
is fixed.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{surface}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The surface type (crystal structure + Miller indices).
Only required if the structure is a periodic surface slab.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{heights}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default acat.settings.site\_heights}}) \textendash{} A dictionary that contains the adsorbate height for each site
type. Use the default height settings if the height for a site
type is not specified.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{allow\_6fold}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to allow the adsorption on 6\sphinxhyphen{}fold subsurf sites
underneath fcc hollow sites.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{composition\_effect}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to consider sites with different elemental
compositions as different sites. It is recommended to
set composition=False for monometallics.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{dmax}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 2.5}}) \textendash{} The maximum bond length (in Angstrom) between the site and the
bonding atom  that should be considered as an adsorbate.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{species\_forbidden\_sites}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} A dictionary that contains keys of each adsorbate species and
values of the site (can be one or multiple site types) that the
speices is not allowed to add to. All sites are availabe for a
species if not specified. Note that this does not differentiate
sites with different compositions.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{species\_forbidden\_labels}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} Same as species\_forbidden\_sites except that the adsorption sites
are written as numerical labels according to acat.labels. Useful
when you need to differentiate sites with different compositions.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{fragmentation}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default True}}) \textendash{} Whether to cut multidentate species into fragments. This ensures
that multidentate species with different orientations are
considered as different coverage patterns.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{trajectory}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default \textquotesingle{}patterns.traj\textquotesingle{}}}) \textendash{} The name of the output ase trajectory file.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{append\_trajectory}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} 
Whether to append structures to the existing trajectory.
If only unique patterns are accepted, the code will also check
graph isomorphism for the existing structures in the trajectory.
This is also useful when you want to generate coverage patterns
stochastically but for all images systematically, e.g. generating
10 stochastic coverage patterns for each image:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{build}\PYG{n+nn}{.}\PYG{n+nn}{patterns} \PYG{k+kn}{import} \PYG{n}{StochasticPatternGenerator} \PYG{k}{as} \PYG{n}{SPG}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k}{for} \PYG{n}{atoms} \PYG{o+ow}{in} \PYG{n}{images}\PYG{p}{:}
\PYG{g+gp}{... }   \PYG{n}{spg} \PYG{o}{=} \PYG{n}{SPG}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{o}{.}\PYG{o}{.}\PYG{o}{.}\PYG{p}{,} \PYG{n}{append\PYGZus{}trajectory}\PYG{o}{=}\PYG{k+kc}{True}\PYG{p}{)}
\PYG{g+gp}{... }   \PYG{n}{spg}\PYG{o}{.}\PYG{n}{run}\PYG{p}{(}\PYG{n}{ngen} \PYG{o}{=} \PYG{l+m+mi}{10}\PYG{p}{)}
\end{sphinxVerbatim}


\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{logfile}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default \textquotesingle{}patterns.log\textquotesingle{}}}) \textendash{} The name of the log file.

\end{itemize}

\end{description}\end{quote}
\index{run() (acat.build.patterns.StochasticPatternGenerator method)@\spxentry{run()}\spxextra{acat.build.patterns.StochasticPatternGenerator method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{build:acat.build.patterns.StochasticPatternGenerator.run}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{run}}}{\emph{\DUrole{n}{n\_gen}}, \emph{\DUrole{n}{actions}\DUrole{o}{=}\DUrole{default_value}{{[}\textquotesingle{}add\textquotesingle{}, \textquotesingle{}remove\textquotesingle{}, \textquotesingle{}move\textquotesingle{}{]}}}, \emph{\DUrole{n}{action\_probabilities}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{unique}\DUrole{o}{=}\DUrole{default_value}{True}}}{}
Run the pattern generator.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{n\_gen}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Number of patterns to generate.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{actions}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{list of strs}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default}}\sphinxstyleliteralemphasis{\sphinxupquote{ {[}}}\sphinxstyleliteralemphasis{\sphinxupquote{\textquotesingle{}add\textquotesingle{}}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{\textquotesingle{}remove\textquotesingle{}}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{\textquotesingle{}move\textquotesingle{}}}\sphinxstyleliteralemphasis{\sphinxupquote{{]}}}) \textendash{} Action(s) to perform.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{action\_probabilities}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} A dictionary that contains keys of each action and values of the
corresponding probabilities. Select actions with equal probability
if not specified.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{unique}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default True}}) \textendash{} Whether to discard duplicate patterns based on isomorphism.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}


\end{fulllineitems}


\sphinxstylestrong{Example}

The following example illustrates how to generate 100 stochastic
adsorbate coverage patterns with CO, OH, CH3 and CHO, based on
10 Pt fcc111 surface slabs with random C and O coverages, where
CH3 is forbidden to be added to ontop and bridge sites:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{build}\PYG{n+nn}{.}\PYG{n+nn}{patterns} \PYG{k+kn}{import} \PYG{n}{StochasticPatternGenerator} \PYG{k}{as} \PYG{n}{SPG}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{build}\PYG{n+nn}{.}\PYG{n+nn}{patterns} \PYG{k+kn}{import} \PYG{n}{random\PYGZus{}coverage\PYGZus{}pattern}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{build} \PYG{k+kn}{import} \PYG{n}{fcc111}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{io} \PYG{k+kn}{import} \PYG{n}{read}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{visualize} \PYG{k+kn}{import} \PYG{n}{view}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{slab} \PYG{o}{=} \PYG{n}{fcc111}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Pt}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{p}{(}\PYG{l+m+mi}{6}\PYG{p}{,} \PYG{l+m+mi}{6}\PYG{p}{,} \PYG{l+m+mi}{4}\PYG{p}{)}\PYG{p}{,} \PYG{l+m+mi}{4}\PYG{p}{,} \PYG{n}{vacuum}\PYG{o}{=}\PYG{l+m+mf}{5.}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{slab}\PYG{o}{.}\PYG{n}{center}\PYG{p}{(}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{images} \PYG{o}{=} \PYG{p}{[}\PYG{p}{]}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k}{for} \PYG{n}{\PYGZus{}} \PYG{o+ow}{in} \PYG{n+nb}{range}\PYG{p}{(}\PYG{l+m+mi}{10}\PYG{p}{)}\PYG{p}{:}
\PYG{g+gp}{... }    \PYG{n}{atoms} \PYG{o}{=} \PYG{n}{slab}\PYG{o}{.}\PYG{n}{copy}\PYG{p}{(}\PYG{p}{)}
\PYG{g+gp}{... }    \PYG{n}{image} \PYG{o}{=} \PYG{n}{random\PYGZus{}coverage\PYGZus{}pattern}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{adsorbate\PYGZus{}species}\PYG{o}{=}\PYG{p}{[}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{C}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{O}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]}\PYG{p}{,}
\PYG{g+gp}{... }                                    \PYG{n}{surface}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{fcc111}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
\PYG{g+gp}{... }                                    \PYG{n}{min\PYGZus{}adsorbate\PYGZus{}distance}\PYG{o}{=}\PYG{l+m+mf}{5.}\PYG{p}{)}
\PYG{g+gp}{... }    \PYG{n}{images}\PYG{o}{.}\PYG{n}{append}\PYG{p}{(}\PYG{n}{image}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{spg} \PYG{o}{=} \PYG{n}{SPG}\PYG{p}{(}\PYG{n}{images}\PYG{p}{,} \PYG{n}{adsorbate\PYGZus{}species}\PYG{o}{=}\PYG{p}{[}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{CO}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{OH}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{CH3}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{CHO}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]}\PYG{p}{,}
\PYG{g+gp}{... }          \PYG{n}{species\PYGZus{}probabilities}\PYG{o}{=}\PYG{p}{\PYGZob{}}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{CO}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:}\PYG{l+m+mf}{0.3}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{OH}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+m+mf}{0.3}\PYG{p}{,}
\PYG{g+gp}{... }                                 \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{CH3}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+m+mf}{0.2}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{CHO}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+m+mf}{0.2}\PYG{p}{\PYGZcb{}}\PYG{p}{,}
\PYG{g+gp}{... }          \PYG{n}{min\PYGZus{}adsorbate\PYGZus{}distance}\PYG{o}{=}\PYG{l+m+mf}{1.5}\PYG{p}{,}
\PYG{g+gp}{... }          \PYG{n}{surface}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{fcc111}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
\PYG{g+gp}{... }          \PYG{n}{composition\PYGZus{}effect}\PYG{o}{=}\PYG{k+kc}{False}\PYG{p}{,}
\PYG{g+gp}{... }          \PYG{n}{species\PYGZus{}forbidden\PYGZus{}sites}\PYG{o}{=}\PYG{p}{\PYGZob{}}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{CH3}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{p}{[}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{ontop}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{bridge}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]}\PYG{p}{\PYGZcb{}}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{spg}\PYG{o}{.}\PYG{n}{run}\PYG{p}{(}\PYG{n}{n\PYGZus{}gen}\PYG{o}{=}\PYG{l+m+mi}{100}\PYG{p}{,} \PYG{n}{actions}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{add}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{images} \PYG{o}{=} \PYG{n}{read}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{patterns.traj}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{n}{index}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{:}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{view}\PYG{p}{(}\PYG{n}{images}\PYG{p}{)}
\end{sphinxVerbatim}

Output:

\noindent{\hspace*{\fill}\sphinxincludegraphics[scale=0.6]{{StochasticPatternGenerator}.gif}\hspace*{\fill}}
\index{SystematicPatternGenerator (class in acat.build.patterns)@\spxentry{SystematicPatternGenerator}\spxextra{class in acat.build.patterns}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{build:acat.build.patterns.SystematicPatternGenerator}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class }}\sphinxcode{\sphinxupquote{acat.build.patterns.}}\sphinxbfcode{\sphinxupquote{SystematicPatternGenerator}}}{\emph{\DUrole{n}{images}}, \emph{\DUrole{n}{adsorbate\_species}}, \emph{\DUrole{n}{min\_adsorbate\_distance}\DUrole{o}{=}\DUrole{default_value}{1.5}}, \emph{\DUrole{n}{adsorption\_sites}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{surface}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{heights}\DUrole{o}{=}\DUrole{default_value}{\{\textquotesingle{}3fold\textquotesingle{}: 1.3, \textquotesingle{}4fold\textquotesingle{}: 1.3, \textquotesingle{}5fold\textquotesingle{}: 1.5, \textquotesingle{}6fold\textquotesingle{}: 0.0, \textquotesingle{}bridge\textquotesingle{}: 1.5, \textquotesingle{}fcc\textquotesingle{}: 1.3, \textquotesingle{}hcp\textquotesingle{}: 1.3, \textquotesingle{}longbridge\textquotesingle{}: 1.5, \textquotesingle{}ontop\textquotesingle{}: 1.8, \textquotesingle{}shortbridge\textquotesingle{}: 1.5\}}}, \emph{\DUrole{n}{allow\_6fold}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{composition\_effect}\DUrole{o}{=}\DUrole{default_value}{True}}, \emph{\DUrole{n}{dmax}\DUrole{o}{=}\DUrole{default_value}{2.5}}, \emph{\DUrole{n}{species\_forbidden\_sites}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{species\_forbidden\_labels}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{enumerate\_orientations}\DUrole{o}{=}\DUrole{default_value}{True}}, \emph{\DUrole{n}{trajectory}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}patterns.traj\textquotesingle{}}}, \emph{\DUrole{n}{append\_trajectory}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{logfile}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}patterns.log\textquotesingle{}}}}{}
\sphinxtitleref{SystematicPatternGenerator} is a class for generating
adsorbate coverage patterns systematically. This is useful to
enumerate all unique patterns at low coverage, but explodes at
higher coverages. Graph isomorphism is implemented to identify
identical coverage patterns. 4 adsorbate actions are supported:
add, remove, move, replace. The function is generalized for both
periodic and non\sphinxhyphen{}periodic systems (distinguished by atoms.pbc).
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{images}} (\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atoms object}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{list of ase.Atoms objects}}) \textendash{} The structure to perform the adsorbate actions on.
If a list of structures is provided, perform one
adsorbate action on one of the structures in each step.
Accept any ase.Atoms object. No need to be built\sphinxhyphen{}in.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{adsorbate\_species}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{list of strs}}) \textendash{} A list of adsorbate species to be randomly added to the surface.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{min\_adsorbate\_distance}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 1.5}}) \textendash{} The minimum distance constraint between two atoms that belongs
to two adsorbates.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{adsorption\_sites}} (\sphinxstyleliteralemphasis{\sphinxupquote{acat.adsorption\_sites.ClusterAdsorptionSites object}}\sphinxstyleliteralemphasis{\sphinxupquote{         or }}\sphinxstyleliteralemphasis{\sphinxupquote{acat.adsorption\_sites.SlabAdsorptionSites object}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} Provide the built\sphinxhyphen{}in adsorption sites class to accelerate the
pattern generation. Make sure all the structures have the same
periodicity and atom indexing. If composition\_effect=True, you
should only provide adsorption\_sites when the surface composition
is fixed.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{surface}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The surface type (crystal structure + Miller indices).
Only required if the structure is a periodic surface slab.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{heights}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default acat.settings.site\_heights}}) \textendash{} A dictionary that contains the adsorbate height for each site
type. Use the default height settings if the height for a site
type is not specified.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{allow\_6fold}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to allow the adsorption on 6\sphinxhyphen{}fold subsurf sites
underneath fcc hollow sites.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{composition\_effect}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to consider sites with different elemental
compositions as different sites. It is recommended to
set composition=False for monometallics.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{dmax}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 2.5}}) \textendash{} The maximum bond length (in Angstrom) between the site and the
bonding atom  that should be considered as an adsorbate.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{species\_forbidden\_sites}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} A dictionary that contains keys of each adsorbate species and
values of the site (can be one or multiple site types) that the
speices is not allowed to add to. All sites are availabe for a
species if not specified. Note that this does not differentiate
sites with different compositions.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{species\_forbidden\_labels}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} Same as species\_forbidden\_sites except that the adsorption sites
are written as numerical labels according to acat.labels. Useful
when you need to differentiate sites with different compositions.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{enumerate\_orientations}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default True}}) \textendash{} Whether to enumerate all orientations of multidentate species.
This ensures that multidentate species with different orientations
are all enumerated.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{trajectory}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default \textquotesingle{}patterns.traj\textquotesingle{}}}) \textendash{} The name of the output ase trajectory file.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{append\_trajectory}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to append structures to the existing trajectory.
If only unique patterns are accepted, the code will also check
graph isomorphism for the existing structures in the trajectory.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{logfile}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default \textquotesingle{}patterns.log\textquotesingle{}}}) \textendash{} The name of the log file.

\end{itemize}

\end{description}\end{quote}
\index{run() (acat.build.patterns.SystematicPatternGenerator method)@\spxentry{run()}\spxextra{acat.build.patterns.SystematicPatternGenerator method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{build:acat.build.patterns.SystematicPatternGenerator.run}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{run}}}{\emph{\DUrole{n}{max\_gen\_per\_image}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{action}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}add\textquotesingle{}}}, \emph{\DUrole{n}{unique}\DUrole{o}{=}\DUrole{default_value}{True}}}{}
Run the pattern generator.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{max\_gen\_per\_image}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} Maximum number of patterns to generate for each image. Enumerate
all possible patterns if not specified.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{action}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{defualt \textquotesingle{}add\textquotesingle{}}}) \textendash{} Action to perform.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{unique}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default True}}) \textendash{} Whether to discard duplicate patterns based on isomorphism.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}


\end{fulllineitems}


\sphinxstylestrong{Example}

The following example illustrates how to add CO to all unique sites on
a cuboctahedral bimetallic nanoparticle:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{adsorption\PYGZus{}sites} \PYG{k+kn}{import} \PYG{n}{ClusterAdsorptionSites}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{build}\PYG{n+nn}{.}\PYG{n+nn}{patterns} \PYG{k+kn}{import} \PYG{n}{SystematicPatternGenerator} \PYG{k}{as} \PYG{n}{SPG}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{cluster} \PYG{k+kn}{import} \PYG{n}{Octahedron}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{io} \PYG{k+kn}{import} \PYG{n}{read}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{visualize} \PYG{k+kn}{import} \PYG{n}{view}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms} \PYG{o}{=} \PYG{n}{Octahedron}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Cu}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{n}{length}\PYG{o}{=}\PYG{l+m+mi}{7}\PYG{p}{,} \PYG{n}{cutoff}\PYG{o}{=}\PYG{l+m+mi}{3}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k}{for} \PYG{n}{atom} \PYG{o+ow}{in} \PYG{n}{atoms}\PYG{p}{:}
\PYG{g+gp}{... }    \PYG{k}{if} \PYG{n}{atom}\PYG{o}{.}\PYG{n}{index} \PYG{o}{\PYGZpc{}} \PYG{l+m+mi}{2} \PYG{o}{==} \PYG{l+m+mi}{0}\PYG{p}{:}
\PYG{g+gp}{... }        \PYG{n}{atom}\PYG{o}{.}\PYG{n}{symbol} \PYG{o}{=} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Au}\PYG{l+s+s1}{\PYGZsq{}}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms}\PYG{o}{.}\PYG{n}{center}\PYG{p}{(}\PYG{n}{vacuum}\PYG{o}{=}\PYG{l+m+mf}{5.}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{cas} \PYG{o}{=} \PYG{n}{ClusterAdsorptionSites}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{composition\PYGZus{}effect}\PYG{o}{=}\PYG{k+kc}{True}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{spg} \PYG{o}{=} \PYG{n}{SPG}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{adsorbate\PYGZus{}species}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{CO}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
\PYG{g+gp}{... }          \PYG{n}{min\PYGZus{}adsorbate\PYGZus{}distance}\PYG{o}{=}\PYG{l+m+mf}{2.}\PYG{p}{,}
\PYG{g+gp}{... }          \PYG{n}{adsorption\PYGZus{}sites}\PYG{o}{=}\PYG{n}{cas}\PYG{p}{,}
\PYG{g+gp}{... }          \PYG{n}{composition\PYGZus{}effect}\PYG{o}{=}\PYG{k+kc}{True}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{spg}\PYG{o}{.}\PYG{n}{run}\PYG{p}{(}\PYG{n}{action}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{add}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{images} \PYG{o}{=} \PYG{n}{read}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{patterns.traj}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{n}{index}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{:}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{view}\PYG{p}{(}\PYG{n}{images}\PYG{p}{)}
\end{sphinxVerbatim}

Output:

\noindent\sphinxincludegraphics{{SystematicPatternGenerator}.gif}
\index{symmetric\_coverage\_pattern() (in module acat.build.patterns)@\spxentry{symmetric\_coverage\_pattern()}\spxextra{in module acat.build.patterns}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{build:acat.build.patterns.symmetric_coverage_pattern}}\pysiglinewithargsret{\sphinxcode{\sphinxupquote{acat.build.patterns.}}\sphinxbfcode{\sphinxupquote{symmetric\_coverage\_pattern}}}{\emph{\DUrole{n}{atoms}}, \emph{\DUrole{n}{adsorbate}}, \emph{\DUrole{n}{coverage}\DUrole{o}{=}\DUrole{default_value}{1.0}}, \emph{\DUrole{n}{surface}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{height}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{min\_adsorbate\_distance}\DUrole{o}{=}\DUrole{default_value}{0.0}}}{}
A function for generating representative symmetric adsorbate
coverage patterns. The function is generalized for both periodic
and non\sphinxhyphen{}periodic systems (distinguished by atoms.pbc).
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{atoms}} (\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atoms object}}) \textendash{} The nanoparticle or surface slab onto which the adsorbates are
added. Accept any ase.Atoms object. No need to be built\sphinxhyphen{}in.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{adsorbate}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atom object}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atoms object}}) \textendash{} The adsorbate species to be added onto the surface.
For now only support adding one type of adsorbate species.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{coverage}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 1.}}) \textendash{} The coverage (ML) of the adsorbate (N\_adsorbate / N\_surf\_atoms).
Support 4 coverage patterns (0.25 for p(2x2) pattern;
0.5 for c(2x2) pattern on fcc100 or honeycomb pattern on fcc111;
0.75 for (2x2) pattern on fcc100 or Kagome pattern on fcc111;
1 for p(1x1) pattern.
Note that for small nanoparticles, the function might give
results that do not correspond to the coverage. This is normal
since the surface area can be too small to encompass the
coverage pattern properly. We expect this function to work
well on large nanoparticles and surface slabs.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{surface}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The surface type (crystal structure + Miller indices).
For now only support 2 common surfaces: fcc100 and fcc111.
If the structure is a periodic surface slab, this is required.
If the structure is a nanoparticle, the function only add
adsorbates to the sites on the specified surface.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{height}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The height of the added adsorbate from the surface.
Use the default settings if not specified.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{min\_adsorbate\_distance}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 0.}}) \textendash{} The minimum distance between two atoms that belongs to two
adsorbates.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}


\sphinxstylestrong{Example}

To add a 0.5 ML CO coverage pattern on a cuboctahedron:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{build}\PYG{n+nn}{.}\PYG{n+nn}{patterns} \PYG{k+kn}{import} \PYG{n}{symmetric\PYGZus{}coverage\PYGZus{}pattern}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{cluster} \PYG{k+kn}{import} \PYG{n}{Octahedron}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{visualize} \PYG{k+kn}{import} \PYG{n}{view}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms} \PYG{o}{=} \PYG{n}{Octahedron}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Au}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{n}{length}\PYG{o}{=}\PYG{l+m+mi}{9}\PYG{p}{,} \PYG{n}{cutoff}\PYG{o}{=}\PYG{l+m+mi}{4}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms}\PYG{o}{.}\PYG{n}{center}\PYG{p}{(}\PYG{n}{vacuum}\PYG{o}{=}\PYG{l+m+mf}{5.}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{pattern} \PYG{o}{=} \PYG{n}{symmetric\PYGZus{}coverage\PYGZus{}pattern}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{adsorbate}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{CO}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
\PYG{g+gp}{... }                                     \PYG{n}{coverage}\PYG{o}{=}\PYG{l+m+mf}{0.5}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{view}\PYG{p}{(}\PYG{n}{pattern}\PYG{p}{)}
\end{sphinxVerbatim}

Output:

\noindent\sphinxincludegraphics{{symmetric_coverage_pattern_1}.png}

To add a 0.75 ML CO coverage pattern on a fcc111 surface slab:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{build}\PYG{n+nn}{.}\PYG{n+nn}{patterns} \PYG{k+kn}{import} \PYG{n}{symmetric\PYGZus{}coverage\PYGZus{}pattern}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{build} \PYG{k+kn}{import} \PYG{n}{fcc111}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{visualize} \PYG{k+kn}{import} \PYG{n}{view}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms} \PYG{o}{=} \PYG{n}{fcc111}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Cu}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{p}{(}\PYG{l+m+mi}{8}\PYG{p}{,} \PYG{l+m+mi}{8}\PYG{p}{,} \PYG{l+m+mi}{4}\PYG{p}{)}\PYG{p}{,} \PYG{n}{vacuum}\PYG{o}{=}\PYG{l+m+mf}{5.}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms}\PYG{o}{.}\PYG{n}{center}\PYG{p}{(}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{pattern} \PYG{o}{=} \PYG{n}{symmetric\PYGZus{}coverage\PYGZus{}pattern}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{adsorbate}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{CO}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
\PYG{g+gp}{... }                                     \PYG{n}{coverage}\PYG{o}{=}\PYG{l+m+mf}{0.5}\PYG{p}{,}
\PYG{g+gp}{... }                                     \PYG{n}{surface}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{fcc111}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{view}\PYG{p}{(}\PYG{n}{pattern}\PYG{p}{)}
\end{sphinxVerbatim}

Output:

\noindent\sphinxincludegraphics{{symmetric_coverage_pattern_2}.png}
\index{full\_coverage\_pattern() (in module acat.build.patterns)@\spxentry{full\_coverage\_pattern()}\spxextra{in module acat.build.patterns}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{build:acat.build.patterns.full_coverage_pattern}}\pysiglinewithargsret{\sphinxcode{\sphinxupquote{acat.build.patterns.}}\sphinxbfcode{\sphinxupquote{full\_coverage\_pattern}}}{\emph{\DUrole{n}{atoms}}, \emph{\DUrole{n}{adsorbate}}, \emph{\DUrole{n}{site}}, \emph{\DUrole{n}{surface}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{height}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{min\_adsorbate\_distance}\DUrole{o}{=}\DUrole{default_value}{0.0}}}{}
A function for generating adsorbate coverage patterns on sites
that are of a same type. The function is generalized for both
periodic and non\sphinxhyphen{}periodic systems (distinguished by atoms.pbc).
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{atoms}} (\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atoms object}}) \textendash{} The nanoparticle or surface slab onto which the adsorbates are
added. Accept any ase.Atoms object. No need to be built\sphinxhyphen{}in.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{adsorbate}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atom object}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atoms object}}) \textendash{} The adsorbate species to be added onto the surface.
For now only support adding one type of adsorbate species.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{site}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} The site type that the adsorbates should be added to.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{surface}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The surface type (crystal structure + Miller indices).
If the structure is a periodic surface slab, this is required.
If the structure is a nanoparticle, the function only add
adsorbates to the sites on the specified surface.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{height}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The height of the added adsorbate from the surface.
Use the default settings if not specified.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{min\_adsorbate\_distance}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 0.}}) \textendash{} The minimum distance between two atoms that belongs to two
adsorbates.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}


\sphinxstylestrong{Example}

To add CO to all hcp sites on a icosahedron:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{build}\PYG{n+nn}{.}\PYG{n+nn}{patterns} \PYG{k+kn}{import} \PYG{n}{full\PYGZus{}coverage\PYGZus{}pattern}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{cluster} \PYG{k+kn}{import} \PYG{n}{Icosahedron}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{visualize} \PYG{k+kn}{import} \PYG{n}{view}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms} \PYG{o}{=} \PYG{n}{Icosahedron}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Au}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{n}{noshells}\PYG{o}{=}\PYG{l+m+mi}{5}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms}\PYG{o}{.}\PYG{n}{center}\PYG{p}{(}\PYG{n}{vacuum}\PYG{o}{=}\PYG{l+m+mf}{5.}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{pattern} \PYG{o}{=} \PYG{n}{full\PYGZus{}coverage\PYGZus{}pattern}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{adsorbate}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{CO}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{n}{site}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{hcp}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{view}\PYG{p}{(}\PYG{n}{pattern}\PYG{p}{)}
\end{sphinxVerbatim}

Output:

\noindent\sphinxincludegraphics{{full_coverage_pattern_1}.png}

To add CO to all 3fold sites on a bcc110 surface slab:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{build}\PYG{n+nn}{.}\PYG{n+nn}{patterns} \PYG{k+kn}{import} \PYG{n}{full\PYGZus{}coverage\PYGZus{}pattern}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{build} \PYG{k+kn}{import} \PYG{n}{bcc110}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{visualize} \PYG{k+kn}{import} \PYG{n}{view}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms} \PYG{o}{=} \PYG{n}{bcc110}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Mo}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{p}{(}\PYG{l+m+mi}{8}\PYG{p}{,} \PYG{l+m+mi}{8}\PYG{p}{,} \PYG{l+m+mi}{4}\PYG{p}{)}\PYG{p}{,} \PYG{n}{vacuum}\PYG{o}{=}\PYG{l+m+mf}{5.}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms}\PYG{o}{.}\PYG{n}{center}\PYG{p}{(}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{pattern} \PYG{o}{=} \PYG{n}{full\PYGZus{}coverage\PYGZus{}pattern}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{adsorbate}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{CO}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
\PYG{g+gp}{... }                                \PYG{n}{surface}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{bcc110}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{n}{site}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{3fold}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{view}\PYG{p}{(}\PYG{n}{pattern}\PYG{p}{)}
\end{sphinxVerbatim}

Output:

\noindent\sphinxincludegraphics{{full_coverage_pattern_2}.png}
\index{random\_coverage\_pattern() (in module acat.build.patterns)@\spxentry{random\_coverage\_pattern()}\spxextra{in module acat.build.patterns}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{build:acat.build.patterns.random_coverage_pattern}}\pysiglinewithargsret{\sphinxcode{\sphinxupquote{acat.build.patterns.}}\sphinxbfcode{\sphinxupquote{random\_coverage\_pattern}}}{\emph{\DUrole{n}{atoms}}, \emph{\DUrole{n}{adsorbate\_species}}, \emph{\DUrole{n}{species\_probabilities}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{surface}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{min\_adsorbate\_distance}\DUrole{o}{=}\DUrole{default_value}{1.5}}, \emph{\DUrole{n}{heights}\DUrole{o}{=}\DUrole{default_value}{\{\textquotesingle{}3fold\textquotesingle{}: 1.3, \textquotesingle{}4fold\textquotesingle{}: 1.3, \textquotesingle{}5fold\textquotesingle{}: 1.5, \textquotesingle{}6fold\textquotesingle{}: 0.0, \textquotesingle{}bridge\textquotesingle{}: 1.5, \textquotesingle{}fcc\textquotesingle{}: 1.3, \textquotesingle{}hcp\textquotesingle{}: 1.3, \textquotesingle{}longbridge\textquotesingle{}: 1.5, \textquotesingle{}ontop\textquotesingle{}: 1.8, \textquotesingle{}shortbridge\textquotesingle{}: 1.5\}}}, \emph{\DUrole{n}{allow\_6fold}\DUrole{o}{=}\DUrole{default_value}{False}}}{}
A function for generating random coverage patterns with a
minimum distance constraint. The function is generalized for
both periodic and non\sphinxhyphen{}periodic systems (distinguished by
atoms.pbc).
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{atoms}} (\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atoms object}}) \textendash{} The nanoparticle or surface slab onto which the adsorbates are
added. Accept any ase.Atoms object. No need to be built\sphinxhyphen{}in.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{adsorbate\_species}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{list of strs}}) \textendash{} A list of adsorbate species to be randomly added to the surface.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{species\_probabilities}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} A dictionary that contains keys of each adsorbate species and
values of their probabilities of adding onto the surface.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{surface}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The surface type (crystal structure + Miller indices).
If the structure is a periodic surface slab, this is required.
If the structure is a nanoparticle, the function only add
adsorbates to the sites on the specified surface.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{heights}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default acat.settings.site\_heights}}) \textendash{} A dictionary that contains the adsorbate height for each site
type. Use the default height settings if the height for a site
type is not specified.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{min\_adsorbate\_distance}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 1.5}}) \textendash{} The minimum distance constraint between two atoms that belongs
to two adsorbates.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{allow\_6fold}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to allow the adsorption on 6\sphinxhyphen{}fold subsurf sites
underneath fcc hollow sites.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}


\sphinxstylestrong{Example}

To add CO randomly onto a cuboctahedron with a minimum adsorbate
distance of 5 Angstrom:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{build}\PYG{n+nn}{.}\PYG{n+nn}{patterns} \PYG{k+kn}{import} \PYG{n}{random\PYGZus{}coverage\PYGZus{}pattern}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{cluster} \PYG{k+kn}{import} \PYG{n}{Octahedron}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{visualize} \PYG{k+kn}{import} \PYG{n}{view}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms} \PYG{o}{=} \PYG{n}{Octahedron}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Au}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{n}{length}\PYG{o}{=}\PYG{l+m+mi}{9}\PYG{p}{,} \PYG{n}{cutoff}\PYG{o}{=}\PYG{l+m+mi}{4}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms}\PYG{o}{.}\PYG{n}{center}\PYG{p}{(}\PYG{n}{vacuum}\PYG{o}{=}\PYG{l+m+mf}{5.}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{pattern} \PYG{o}{=} \PYG{n}{random\PYGZus{}coverage\PYGZus{}pattern}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{adsorbate\PYGZus{}species}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{CO}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
\PYG{g+gp}{... }                                  \PYG{n}{min\PYGZus{}adsorbate\PYGZus{}distance}\PYG{o}{=}\PYG{l+m+mf}{5.}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{view}\PYG{p}{(}\PYG{n}{pattern}\PYG{p}{)}
\end{sphinxVerbatim}

Output:

\noindent\sphinxincludegraphics{{random_coverage_pattern_1}.png}

To add C, N, O randomly onto a hcp0001 surface slab with probabilities
of 0.25, 0.25, 0.5, respectively, and a minimum adsorbate distance of
2 Angstrom:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{build}\PYG{n+nn}{.}\PYG{n+nn}{patterns} \PYG{k+kn}{import} \PYG{n}{random\PYGZus{}coverage\PYGZus{}pattern}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{build} \PYG{k+kn}{import} \PYG{n}{hcp0001}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{visualize} \PYG{k+kn}{import} \PYG{n}{view}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms} \PYG{o}{=} \PYG{n}{hcp0001}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Ru}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{p}{(}\PYG{l+m+mi}{8}\PYG{p}{,} \PYG{l+m+mi}{8}\PYG{p}{,} \PYG{l+m+mi}{4}\PYG{p}{)}\PYG{p}{,} \PYG{n}{vacuum}\PYG{o}{=}\PYG{l+m+mf}{5.}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms}\PYG{o}{.}\PYG{n}{center}\PYG{p}{(}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{pattern} \PYG{o}{=} \PYG{n}{random\PYGZus{}coverage\PYGZus{}pattern}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{adsorbate\PYGZus{}species}\PYG{o}{=}\PYG{p}{[}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{C}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{N}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{O}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]}\PYG{p}{,}
\PYG{g+gp}{... }                                  \PYG{n}{species\PYGZus{}probabilities}\PYG{o}{=}\PYG{p}{\PYGZob{}}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{C}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+m+mf}{0.25}\PYG{p}{,}
\PYG{g+gp}{... }                                                         \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{N}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+m+mf}{0.25}\PYG{p}{,}
\PYG{g+gp}{... }                                                         \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{O}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+m+mf}{0.5}\PYG{p}{\PYGZcb{}}\PYG{p}{,}
\PYG{g+gp}{... }                                  \PYG{n}{surface}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{hcp0001}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,}
\PYG{g+gp}{... }                                  \PYG{n}{min\PYGZus{}adsorbate\PYGZus{}distance}\PYG{o}{=}\PYG{l+m+mf}{2.}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{view}\PYG{p}{(}\PYG{n}{pattern}\PYG{p}{)}
\end{sphinxVerbatim}

Output:

\noindent\sphinxincludegraphics{{random_coverage_pattern_2}.png}


\subsection{Generate chemical orderings}
\label{\detokenize{build:module-acat.build.orderings}}\label{\detokenize{build:generate-chemical-orderings}}\index{module@\spxentry{module}!acat.build.orderings@\spxentry{acat.build.orderings}}\index{acat.build.orderings@\spxentry{acat.build.orderings}!module@\spxentry{module}}\index{SymmetricOrderingGenerator (class in acat.build.orderings)@\spxentry{SymmetricOrderingGenerator}\spxextra{class in acat.build.orderings}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{build:acat.build.orderings.SymmetricOrderingGenerator}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class }}\sphinxcode{\sphinxupquote{acat.build.orderings.}}\sphinxbfcode{\sphinxupquote{SymmetricOrderingGenerator}}}{\emph{\DUrole{n}{atoms}}, \emph{\DUrole{n}{species}}, \emph{\DUrole{n}{symmetry}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}spherical\textquotesingle{}}}, \emph{\DUrole{n}{cutoff}\DUrole{o}{=}\DUrole{default_value}{0.1}}, \emph{\DUrole{n}{secondary\_symmetry}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{secondary\_cutoff}\DUrole{o}{=}\DUrole{default_value}{0.1}}, \emph{\DUrole{n}{composition}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{layer\_threshold}\DUrole{o}{=}\DUrole{default_value}{20}}, \emph{\DUrole{n}{trajectory}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}orderings.traj\textquotesingle{}}}, \emph{\DUrole{n}{append\_trajectory}\DUrole{o}{=}\DUrole{default_value}{False}}}{}
\sphinxtitleref{SymmetricOrderingGenerator} is a class for generating
symmetric chemical orderings for a bimetallic catalyst.
As for now, only support clusters. Please align the z direction
to the symmetry axis of the cluster.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{atoms}} (\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atoms object}}) \textendash{} The nanoparticle to use as a template to generate symmetric
chemical orderings. Accept any ase.Atoms object. No need to be
built\sphinxhyphen{}in.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{species}} (\sphinxstyleliteralemphasis{\sphinxupquote{list of strs}}) \textendash{} The two metal species of the bimetallic catalyst.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{symmetry}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default \textquotesingle{}spherical\textquotesingle{}}}) \textendash{} Support 4 symmetries:
‘spherical’ = centrosymmetry (layers defined by the distances
to the geometric center);
‘planar’ = planar symmetry around z axis (layers defined by
the z coordinates);
‘cylindrical’ = cylindrical symmetry around z axis (layers
defined by the distances to the z axis);
‘chemical’ = symmetry w.r.t chemical environment (layers
defined by the atomic energy calculated by EMT).

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{cutoff}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 0.1}}) \textendash{} Minimum distance (in Angstrom) or energy difference (in eV)
that the code can recognize between two neighbor layers.
If the structure is irregular, use a higher cutoff.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{secondary\_symmetry}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} Add a secondary symmetry check to define layers hierarchically.
For example, even if two atoms are classifed in one layer that
defined by the primary symmetry, they can still end up in
different layers if they fall into two different layers that
defined by the secondary symmetry. Support same 4 symmetries.
Note that secondary symmetry has the same importance as the
primary symmetry, so you can set either of the two symmetries
of interest as the secondary symmetry.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{secondary\_cutoff}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 0.1}}) \textendash{} Same as cutoff, except that it is for the secondary symmetry.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{composition}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} Generate symmetric orderings only at a certain composition.
The dictionary contains the two speices as keys and their
concentrations as values. Generate orderings at all
compositions if not specified.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{layer\_threshold}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 20}}) \textendash{} Number of layers to switch to stochastic mode automatically.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{trajectory}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default \textquotesingle{}orderings.traj\textquotesingle{}}}) \textendash{} The name of the output ase trajectory file.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{append\_trajectory}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to append structures to the existing trajectory.

\end{itemize}

\end{description}\end{quote}
\index{run() (acat.build.orderings.SymmetricOrderingGenerator method)@\spxentry{run()}\spxextra{acat.build.orderings.SymmetricOrderingGenerator method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{build:acat.build.orderings.SymmetricOrderingGenerator.run}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{run}}}{\emph{\DUrole{n}{max\_gen}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{mode}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}systematic\textquotesingle{}}}, \emph{\DUrole{n}{verbose}\DUrole{o}{=}\DUrole{default_value}{False}}}{}
Run the chemical ordering generator.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{max\_gen}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} Maximum number of chemical orderings to generate. Enumerate
all symetric patterns if not specified.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{mode}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default \textquotesingle{}systematic\textquotesingle{}}}) \textendash{} Mode ‘systematic’ = enumerate all possible chemical orderings.
Mode ‘stochastic’ = sample chemical orderings stochastically.
Stocahstic mode is recommended when there are many layers.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{verbose}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to print out information about number of layers and
number of generated structures.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}


\end{fulllineitems}


\sphinxstylestrong{Example}

To generate 100 symmetric chemical orderings of a truncated
octahedral NiPt nanoalloy with spherical symmetry:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{build}\PYG{n+nn}{.}\PYG{n+nn}{orderings} \PYG{k+kn}{import} \PYG{n}{SymmetricOrderingGenerator} \PYG{k}{as} \PYG{n}{SOG}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{cluster} \PYG{k+kn}{import} \PYG{n}{Octahedron}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{io} \PYG{k+kn}{import} \PYG{n}{read}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{visualize} \PYG{k+kn}{import} \PYG{n}{view}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms} \PYG{o}{=} \PYG{n}{Octahedron}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Ni}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{n}{length}\PYG{o}{=}\PYG{l+m+mi}{8}\PYG{p}{,} \PYG{n}{cutoff}\PYG{o}{=}\PYG{l+m+mi}{3}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{sog} \PYG{o}{=} \PYG{n}{SOG}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{species}\PYG{o}{=}\PYG{p}{[}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Ni}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Pt}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]}\PYG{p}{,} \PYG{n}{symmetry}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{spherical}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{sog}\PYG{o}{.}\PYG{n}{run}\PYG{p}{(}\PYG{n}{max\PYGZus{}gen}\PYG{o}{=}\PYG{l+m+mi}{100}\PYG{p}{,} \PYG{n}{verbose}\PYG{o}{=}\PYG{k+kc}{True}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{images} \PYG{o}{=} \PYG{n}{read}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{orderings.traj}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{n}{index}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{:}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{view}\PYG{p}{(}\PYG{n}{images}\PYG{p}{)}
\end{sphinxVerbatim}

Output:
\begin{quote}

10 layers classified

100 symmetric chemical orderings generated
\end{quote}

\noindent{\hspace*{\fill}\sphinxincludegraphics[scale=0.6]{{SymmetricOrderingGenerator}.gif}\hspace*{\fill}}
\index{RandomOrderingGenerator (class in acat.build.orderings)@\spxentry{RandomOrderingGenerator}\spxextra{class in acat.build.orderings}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{build:acat.build.orderings.RandomOrderingGenerator}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class }}\sphinxcode{\sphinxupquote{acat.build.orderings.}}\sphinxbfcode{\sphinxupquote{RandomOrderingGenerator}}}{\emph{\DUrole{n}{atoms}}, \emph{\DUrole{n}{species}}, \emph{\DUrole{n}{composition}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{trajectory}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}orderings.traj\textquotesingle{}}}, \emph{\DUrole{n}{append\_trajectory}\DUrole{o}{=}\DUrole{default_value}{False}}}{}
\sphinxtitleref{RandomOrderingGenerator} is a class for generating random
chemical orderings for a bimetallic catalyst. The function is
generalized for both periodic and non\sphinxhyphen{}periodic systems.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{atoms}} (\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atoms object}}) \textendash{} The nanoparticle or surface slab to use as a template to
generate random chemical orderings. Accept any ase.Atoms
object. No need to be built\sphinxhyphen{}in.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{species}} (\sphinxstyleliteralemphasis{\sphinxupquote{list of strs}}) \textendash{} The two metal species of the bimetallic catalyst.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{composition}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{None}}) \textendash{} Generate random orderings only at a certain composition.
The dictionary contains the two speices as keys and their
concentrations as values. Generate orderings at all
compositions if not specified.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{trajectory}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default \textquotesingle{}patterns.traj\textquotesingle{}}}) \textendash{} The name of the output ase trajectory file.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{append\_trajectory}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to append structures to the existing trajectory.

\end{itemize}

\end{description}\end{quote}
\index{run() (acat.build.orderings.RandomOrderingGenerator method)@\spxentry{run()}\spxextra{acat.build.orderings.RandomOrderingGenerator method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{build:acat.build.orderings.RandomOrderingGenerator.run}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{run}}}{\emph{\DUrole{n}{n\_gen}}}{}
Run the chemical ordering generator.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode
\sphinxstyleliteralstrong{\sphinxupquote{n\_gen}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Number of chemical orderings to generate.

\end{description}\end{quote}

\end{fulllineitems}


\end{fulllineitems}


\sphinxstylestrong{Example}

To generate 100 random chemical orderings of a icosahedral Ni3Pt
nanoalloy:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{build}\PYG{n+nn}{.}\PYG{n+nn}{orderings} \PYG{k+kn}{import} \PYG{n}{RandomOrderingGenerator} \PYG{k}{as} \PYG{n}{ROG}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{cluster} \PYG{k+kn}{import} \PYG{n}{Icosahedron}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{io} \PYG{k+kn}{import} \PYG{n}{read}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{visualize} \PYG{k+kn}{import} \PYG{n}{view}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{atoms} \PYG{o}{=} \PYG{n}{Icosahedron}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Ni}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{n}{noshells}\PYG{o}{=}\PYG{l+m+mi}{5}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{rog} \PYG{o}{=} \PYG{n}{ROG}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{species}\PYG{o}{=}\PYG{p}{[}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Ni}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Pt}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]}\PYG{p}{,}
\PYG{g+gp}{... }          \PYG{n}{composition}\PYG{o}{=}\PYG{p}{\PYGZob{}}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Ni}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+m+mf}{0.75}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Pt}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+m+mf}{0.25}\PYG{p}{\PYGZcb{}}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{rog}\PYG{o}{.}\PYG{n}{run}\PYG{p}{(}\PYG{n}{n\PYGZus{}gen}\PYG{o}{=}\PYG{l+m+mi}{100}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{images} \PYG{o}{=} \PYG{n}{read}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{orderings.traj}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{n}{index}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{:}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}
\PYG{g+gp}{\PYGZgt{}\PYGZgt{}\PYGZgt{} }\PYG{n}{view}\PYG{p}{(}\PYG{n}{images}\PYG{p}{)}
\end{sphinxVerbatim}

Output:

\noindent{\hspace*{\fill}\sphinxincludegraphics[scale=0.6]{{RandomOrderingGenerator}.gif}\hspace*{\fill}}


\section{Genetic algorithm}
\label{\detokenize{ga:genetic-algorithm}}\label{\detokenize{ga::doc}}

\subsection{Adsorbate procreation operators}
\label{\detokenize{ga:module-acat.ga.adsorbate_operators}}\label{\detokenize{ga:adsorbate-procreation-operators}}\index{module@\spxentry{module}!acat.ga.adsorbate\_operators@\spxentry{acat.ga.adsorbate\_operators}}\index{acat.ga.adsorbate\_operators@\spxentry{acat.ga.adsorbate\_operators}!module@\spxentry{module}}
Adsorbate operators that adds an adsorbate to the surface
of a particle or given structure.
\index{AdsorbateOperator (class in acat.ga.adsorbate\_operators)@\spxentry{AdsorbateOperator}\spxextra{class in acat.ga.adsorbate\_operators}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{ga:acat.ga.adsorbate_operators.AdsorbateOperator}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class }}\sphinxcode{\sphinxupquote{acat.ga.adsorbate\_operators.}}\sphinxbfcode{\sphinxupquote{AdsorbateOperator}}}{\emph{\DUrole{n}{adsorbate\_species}}, \emph{\DUrole{n}{num\_muts}\DUrole{o}{=}\DUrole{default_value}{1}}}{}
Bases: \sphinxcode{\sphinxupquote{ase.ga.offspring\_creator.OffspringCreator}}

Base class for all operators that add, move or remove adsorbates.

Don’t use this operator directly!
\index{initialize\_individual() (acat.ga.adsorbate\_operators.AdsorbateOperator class method)@\spxentry{initialize\_individual()}\spxextra{acat.ga.adsorbate\_operators.AdsorbateOperator class method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{ga:acat.ga.adsorbate_operators.AdsorbateOperator.initialize_individual}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{classmethod }}\sphinxbfcode{\sphinxupquote{initialize\_individual}}}{\emph{\DUrole{n}{parent}}, \emph{\DUrole{n}{indi}\DUrole{o}{=}\DUrole{default_value}{None}}}{}
Initializes a new individual that inherits some parameters
from the parent, and initializes the info dictionary.
If the new individual already has more structure it can be
supplied in the parameter indi.

\end{fulllineitems}

\index{get\_new\_individual() (acat.ga.adsorbate\_operators.AdsorbateOperator method)@\spxentry{get\_new\_individual()}\spxextra{acat.ga.adsorbate\_operators.AdsorbateOperator method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{ga:acat.ga.adsorbate_operators.AdsorbateOperator.get_new_individual}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_new\_individual}}}{\emph{\DUrole{n}{parents}}}{}
Function that returns a new individual.
Overwrite in subclass.

\end{fulllineitems}

\index{add\_adsorbate() (acat.ga.adsorbate\_operators.AdsorbateOperator method)@\spxentry{add\_adsorbate()}\spxextra{acat.ga.adsorbate\_operators.AdsorbateOperator method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{ga:acat.ga.adsorbate_operators.AdsorbateOperator.add_adsorbate}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{add\_adsorbate}}}{\emph{\DUrole{n}{atoms}}, \emph{\DUrole{n}{hetero\_site\_list}}, \emph{\DUrole{n}{heights}}, \emph{\DUrole{n}{adsorbate\_species}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{min\_adsorbate\_distance}\DUrole{o}{=}\DUrole{default_value}{2.0}}, \emph{\DUrole{n}{tilt\_angle}\DUrole{o}{=}\DUrole{default_value}{0.0}}}{}
Adds the adsorbate in self.adsorbate to the supplied atoms
object at the first free site in the specified site\_list. A site
is free if no other adsorbates can be found in a sphere of radius
min\_adsorbate\_distance around the chosen site.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{atoms}} (\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atoms object}}) \textendash{} The atoms object that the adsorbate will be added to.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{hetero\_site\_list}} (\sphinxstyleliteralemphasis{\sphinxupquote{list}}) \textendash{} A list of dictionaries, each dictionary contains site
information given by acat.adsorbate\_coverage module.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{heights}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}) \textendash{} A dictionary that contains the adsorbate height for each site
type.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{adsorbate\_species}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{list of strs}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} One or a list of adsorbate species to be added to the surface.
Use self.adsorbate\_species if not specified.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{min\_adsorbate\_distance}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 2.}}) \textendash{} The radius of the sphere inside which no other adsorbates
should be found.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{tilt\_angle}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 0.}}) \textendash{} Tilt the adsorbate with an angle (in degress) relative to the
surface normal.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{remove\_adsorbate() (acat.ga.adsorbate\_operators.AdsorbateOperator method)@\spxentry{remove\_adsorbate()}\spxextra{acat.ga.adsorbate\_operators.AdsorbateOperator method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{ga:acat.ga.adsorbate_operators.AdsorbateOperator.remove_adsorbate}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{remove\_adsorbate}}}{\emph{\DUrole{n}{atoms}}, \emph{\DUrole{n}{hetero\_site\_list}}, \emph{\DUrole{n}{return\_site\_index}\DUrole{o}{=}\DUrole{default_value}{False}}}{}
Removes an adsorbate from the atoms object at the first occupied
site in hetero\_site\_list. If no adsorbates can be found, one will be
added instead.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{atoms}} (\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atoms object}}) \textendash{} The atoms object that the adsorbate will be added to

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{hetero\_site\_list}} (\sphinxstyleliteralemphasis{\sphinxupquote{list}}) \textendash{} A list of dictionaries, each dictionary contains site
information given by acat.adsorbate\_coverage module.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{return\_site\_index}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to return the site index of the hetero\_site\_list instead
of the site. Useful for moving or replacing adsorbate.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{get\_adsorbate\_indices() (acat.ga.adsorbate\_operators.AdsorbateOperator method)@\spxentry{get\_adsorbate\_indices()}\spxextra{acat.ga.adsorbate\_operators.AdsorbateOperator method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{ga:acat.ga.adsorbate_operators.AdsorbateOperator.get_adsorbate_indices}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_adsorbate\_indices}}}{\emph{\DUrole{n}{atoms}}, \emph{\DUrole{n}{position}}}{}
Returns the indices of the adsorbate at the supplied position.

\end{fulllineitems}


\end{fulllineitems}

\index{AddAdsorbate (class in acat.ga.adsorbate\_operators)@\spxentry{AddAdsorbate}\spxextra{class in acat.ga.adsorbate\_operators}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{ga:acat.ga.adsorbate_operators.AddAdsorbate}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class }}\sphinxcode{\sphinxupquote{acat.ga.adsorbate\_operators.}}\sphinxbfcode{\sphinxupquote{AddAdsorbate}}}{\emph{\DUrole{n}{adsorbate\_species}}, \emph{\DUrole{n}{heights}\DUrole{o}{=}\DUrole{default_value}{\{\textquotesingle{}3fold\textquotesingle{}: 1.3, \textquotesingle{}4fold\textquotesingle{}: 1.3, \textquotesingle{}5fold\textquotesingle{}: 1.5, \textquotesingle{}6fold\textquotesingle{}: 0.0, \textquotesingle{}bridge\textquotesingle{}: 1.5, \textquotesingle{}fcc\textquotesingle{}: 1.3, \textquotesingle{}hcp\textquotesingle{}: 1.3, \textquotesingle{}longbridge\textquotesingle{}: 1.5, \textquotesingle{}ontop\textquotesingle{}: 1.8, \textquotesingle{}shortbridge\textquotesingle{}: 1.5\}}}, \emph{\DUrole{n}{min\_adsorbate\_distance}\DUrole{o}{=}\DUrole{default_value}{2.0}}, \emph{\DUrole{n}{surface}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{allow\_6fold}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{composition\_effect}\DUrole{o}{=}\DUrole{default_value}{True}}, \emph{\DUrole{n}{site\_preference}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{surface\_preference}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{tilt\_angle}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{num\_muts}\DUrole{o}{=}\DUrole{default_value}{1}}, \emph{\DUrole{n}{dmax}\DUrole{o}{=}\DUrole{default_value}{2.5}}}{}
Bases: {\hyperref[\detokenize{ga:acat.ga.adsorbate_operators.AdsorbateOperator}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{acat.ga.adsorbate\_operators.AdsorbateOperator}}}}}

Use this operator to add adsorbates to the surface.
The surface is allowed to change during the algorithm run.

There is no limit of adsorbate species. You can either provide one
species or a list of species.

Site and surface preference can be supplied. If both are supplied site
will be considered first.

Supplying a tilt angle will tilt the adsorbate with an angle relative
to the standard perpendicular to the surface.

The operator is generalized for both periodic and non\sphinxhyphen{}periodic systems
(distinguished by atoms.pbc).
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{adsorbate\_species}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{list of strs}}) \textendash{} One or a list of adsorbate species to be added to the surface.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{heights}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default acat.settings.site\_heights}}) \textendash{} A dictionary that contains the adsorbate height for each site
type. Use the default height settings if the height for a site
type is not specified.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{min\_adsorbate\_distance}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 2.}}) \textendash{} The radius of the sphere inside which no other adsorbates
should be found.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{surface}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The surface type (crystal structure + Miller indices).
Only required if the structure is a periodic surface slab.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{allow\_6fold}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to allow the adsorption on 6\sphinxhyphen{}fold subsurf sites
underneath fcc hollow sites.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{composition\_effect}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default True}}) \textendash{} Whether to consider sites with different elemental compositions
as different sites. It is recommended to set composition=False
for monometallics. Since GA is commonly used for bimetallics,
the default is set to True.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{site\_preference}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{defualt None}}) \textendash{} The site type that has higher priority to attach adsorbates.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{surface\_preference}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The surface type that has higher priority to attach adsorbates.
Please only use this for nanoparticles.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{tilt\_angle}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 0.}}) \textendash{} Tilt the adsorbate with an angle (in degress) relative to the
surface normal.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{num\_muts}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 1}}) \textendash{} The number of times to perform this operation.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{dmax}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 2.5}}) \textendash{} The maximum bond length (in Angstrom) between the site and the
bonding atom  that should be considered as an adsorbate.

\end{itemize}

\end{description}\end{quote}
\index{get\_new\_individual() (acat.ga.adsorbate\_operators.AddAdsorbate method)@\spxentry{get\_new\_individual()}\spxextra{acat.ga.adsorbate\_operators.AddAdsorbate method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{ga:acat.ga.adsorbate_operators.AddAdsorbate.get_new_individual}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_new\_individual}}}{\emph{\DUrole{n}{parents}}}{}
Returns the new individual as an atoms object.

\end{fulllineitems}


\end{fulllineitems}

\index{RemoveAdsorbate (class in acat.ga.adsorbate\_operators)@\spxentry{RemoveAdsorbate}\spxextra{class in acat.ga.adsorbate\_operators}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{ga:acat.ga.adsorbate_operators.RemoveAdsorbate}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class }}\sphinxcode{\sphinxupquote{acat.ga.adsorbate\_operators.}}\sphinxbfcode{\sphinxupquote{RemoveAdsorbate}}}{\emph{\DUrole{n}{adsorbate\_species}}, \emph{\DUrole{n}{surface}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{allow\_6fold}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{composition\_effect}\DUrole{o}{=}\DUrole{default_value}{True}}, \emph{\DUrole{n}{site\_preference}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{surface\_preference}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{num\_muts}\DUrole{o}{=}\DUrole{default_value}{1}}, \emph{\DUrole{n}{dmax}\DUrole{o}{=}\DUrole{default_value}{2.5}}}{}
Bases: {\hyperref[\detokenize{ga:acat.ga.adsorbate_operators.AdsorbateOperator}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{acat.ga.adsorbate\_operators.AdsorbateOperator}}}}}

This operator removes an adsorbate from the surface. It works
exactly (but doing the opposite) as the AddAdsorbate operator.

The operator is generalized for both periodic and non\sphinxhyphen{}periodic systems
(distinguished by atoms.pbc).
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{adsorbate\_species}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{list of strs}}) \textendash{} One or a list of adsorbate species to be removed from the surface.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{surface}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The surface type (crystal structure + Miller indices).
Only required if the structure is a periodic surface slab.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{allow\_6fold}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to allow the adsorption on 6\sphinxhyphen{}fold subsurf sites underneath
fcc hollow sites.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{composition\_effect}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default True}}) \textendash{} Whether to consider sites with different elemental compositions as
different sites. It is recommended to set composition=False for
monometallics. Since GA is commonly used for bimetallics, the
default is set to True.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{site\_preference}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{defualt None}}) \textendash{} The site type that has higher priority to attach adsorbates.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{surface\_preference}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The surface type that has higher priority to attach adsorbates.
Please only use this for nanoparticles.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{tilt\_angle}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 0.}}) \textendash{} Tilt the adsorbate with an angle (in degress) relative to the
surface normal.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{num\_muts}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 1}}) \textendash{} The number of times to perform this operation.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{dmax}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 2.5}}) \textendash{} The maximum bond length (in Angstrom) between the site and the
bonding atom  that should be considered as an adsorbate.

\end{itemize}

\end{description}\end{quote}
\index{get\_new\_individual() (acat.ga.adsorbate\_operators.RemoveAdsorbate method)@\spxentry{get\_new\_individual()}\spxextra{acat.ga.adsorbate\_operators.RemoveAdsorbate method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{ga:acat.ga.adsorbate_operators.RemoveAdsorbate.get_new_individual}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_new\_individual}}}{\emph{\DUrole{n}{parents}}}{}
Function that returns a new individual.
Overwrite in subclass.

\end{fulllineitems}


\end{fulllineitems}

\index{MoveAdsorbate (class in acat.ga.adsorbate\_operators)@\spxentry{MoveAdsorbate}\spxextra{class in acat.ga.adsorbate\_operators}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{ga:acat.ga.adsorbate_operators.MoveAdsorbate}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class }}\sphinxcode{\sphinxupquote{acat.ga.adsorbate\_operators.}}\sphinxbfcode{\sphinxupquote{MoveAdsorbate}}}{\emph{\DUrole{n}{adsorbate\_species}}, \emph{\DUrole{n}{heights}\DUrole{o}{=}\DUrole{default_value}{\{\textquotesingle{}3fold\textquotesingle{}: 1.3, \textquotesingle{}4fold\textquotesingle{}: 1.3, \textquotesingle{}5fold\textquotesingle{}: 1.5, \textquotesingle{}6fold\textquotesingle{}: 0.0, \textquotesingle{}bridge\textquotesingle{}: 1.5, \textquotesingle{}fcc\textquotesingle{}: 1.3, \textquotesingle{}hcp\textquotesingle{}: 1.3, \textquotesingle{}longbridge\textquotesingle{}: 1.5, \textquotesingle{}ontop\textquotesingle{}: 1.8, \textquotesingle{}shortbridge\textquotesingle{}: 1.5\}}}, \emph{\DUrole{n}{min\_adsorbate\_distance}\DUrole{o}{=}\DUrole{default_value}{2.0}}, \emph{\DUrole{n}{surface}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{allow\_6fold}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{composition\_effect}\DUrole{o}{=}\DUrole{default_value}{True}}, \emph{\DUrole{n}{site\_preference\_from}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{surface\_preference\_from}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{site\_preference\_to}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{surface\_preference\_to}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{tilt\_angle}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{num\_muts}\DUrole{o}{=}\DUrole{default_value}{1}}, \emph{\DUrole{n}{dmax}\DUrole{o}{=}\DUrole{default_value}{2.5}}}{}
Bases: {\hyperref[\detokenize{ga:acat.ga.adsorbate_operators.AdsorbateOperator}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{acat.ga.adsorbate\_operators.AdsorbateOperator}}}}}

This operator removes an adsorbate from the surface and adds it
again to a different site, i.e. effectively moving the adsorbate.

The operator is generalized for both periodic and non\sphinxhyphen{}periodic systems
(distinguished by atoms.pbc).
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{adsorbate\_species}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{list of strs}}) \textendash{} One or a list of adsorbate species to be added to the surface.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{heights}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default acat.settings.site\_heights}}) \textendash{} A dictionary that contains the adsorbate height for each site
type. Use the default height settings if the height for a site
type is not specified.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{min\_adsorbate\_distance}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 2.}}) \textendash{} The radius of the sphere inside which no other adsorbates
should be found.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{surface}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The surface type (crystal structure + Miller indices).
Only required if the structure is a periodic surface slab.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{allow\_6fold}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to allow the adsorption on 6\sphinxhyphen{}fold subsurf sites
underneath fcc hollow sites.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{composition\_effect}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default True}}) \textendash{} Whether to consider sites with different elemental compositions
as different sites. It is recommended to set composition=False
for monometallics. Since GA is commonly used for bimetallics,
the default is set to True.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{site\_preference\_from}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{defualt None}}) \textendash{} The site type that has higher priority to detach adsorbates.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{surface\_preference\_from}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The surface type that has higher priority to detach adsorbates.
Please only use this for nanoparticles.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{site\_preference\_to}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{defualt None}}) \textendash{} The site type that has higher priority to attach adsorbates.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{surface\_preference\_to}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The surface type that has higher priority to attach adsorbates.
Please only use this for nanoparticles.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{tilt\_angle}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 0.}}) \textendash{} Tilt the adsorbate with an angle (in degress) relative to the
surface normal.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{num\_muts}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 1}}) \textendash{} The number of times to perform this operation.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{dmax}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 2.5}}) \textendash{} The maximum bond length (in Angstrom) between the site and the
bonding atom  that should be considered as an adsorbate.

\end{itemize}

\end{description}\end{quote}
\index{get\_new\_individual() (acat.ga.adsorbate\_operators.MoveAdsorbate method)@\spxentry{get\_new\_individual()}\spxextra{acat.ga.adsorbate\_operators.MoveAdsorbate method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{ga:acat.ga.adsorbate_operators.MoveAdsorbate.get_new_individual}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_new\_individual}}}{\emph{\DUrole{n}{parents}}}{}
Function that returns a new individual.
Overwrite in subclass.

\end{fulllineitems}


\end{fulllineitems}

\index{ReplaceAdsorbate (class in acat.ga.adsorbate\_operators)@\spxentry{ReplaceAdsorbate}\spxextra{class in acat.ga.adsorbate\_operators}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{ga:acat.ga.adsorbate_operators.ReplaceAdsorbate}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class }}\sphinxcode{\sphinxupquote{acat.ga.adsorbate\_operators.}}\sphinxbfcode{\sphinxupquote{ReplaceAdsorbate}}}{\emph{\DUrole{n}{adsorbate\_species}}, \emph{\DUrole{n}{heights}\DUrole{o}{=}\DUrole{default_value}{\{\textquotesingle{}3fold\textquotesingle{}: 1.3, \textquotesingle{}4fold\textquotesingle{}: 1.3, \textquotesingle{}5fold\textquotesingle{}: 1.5, \textquotesingle{}6fold\textquotesingle{}: 0.0, \textquotesingle{}bridge\textquotesingle{}: 1.5, \textquotesingle{}fcc\textquotesingle{}: 1.3, \textquotesingle{}hcp\textquotesingle{}: 1.3, \textquotesingle{}longbridge\textquotesingle{}: 1.5, \textquotesingle{}ontop\textquotesingle{}: 1.8, \textquotesingle{}shortbridge\textquotesingle{}: 1.5\}}}, \emph{\DUrole{n}{min\_adsorbate\_distance}\DUrole{o}{=}\DUrole{default_value}{2.0}}, \emph{\DUrole{n}{surface}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{allow\_6fold}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{composition\_effect}\DUrole{o}{=}\DUrole{default_value}{True}}, \emph{\DUrole{n}{site\_preference\_from}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{surface\_preference\_from}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{tilt\_angle}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{num\_muts}\DUrole{o}{=}\DUrole{default_value}{1}}, \emph{\DUrole{n}{dmax}\DUrole{o}{=}\DUrole{default_value}{2.5}}}{}
Bases: {\hyperref[\detokenize{ga:acat.ga.adsorbate_operators.AdsorbateOperator}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{acat.ga.adsorbate\_operators.AdsorbateOperator}}}}}

This operator removes an adsorbate from the surface and adds another
species to the same site, i.e. effectively replacing the adsorbate.

The operator is generalized for both periodic and non\sphinxhyphen{}periodic systems
(distinguished by atoms.pbc).
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{adsorbate\_species}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{list of strs}}) \textendash{} One or a list of adsorbate species to be added to the surface.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{heights}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default acat.settings.site\_heights}}) \textendash{} A dictionary that contains the adsorbate height for each site
type. Use the default height settings if the height for a site
type is not specified.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{min\_adsorbate\_distance}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 2.}}) \textendash{} The radius of the sphere inside which no other adsorbates
should be found.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{surface}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The surface type (crystal structure + Miller indices).
Only required if the structure is a periodic surface slab.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{allow\_6fold}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to allow the adsorption on 6\sphinxhyphen{}fold subsurf sites
underneath fcc hollow sites.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{composition\_effect}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default True}}) \textendash{} Whether to consider sites with different elemental compositions
as different sites. It is recommended to set composition=False
for monometallics. Since GA is commonly used for bimetallics,
the default is set to True.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{site\_preference\_from}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{defualt None}}) \textendash{} The site type that has higher priority to replace adsorbates.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{surface\_preference\_from}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The surface type that has higher priority to replace adsorbates.
Please only use this for nanoparticles.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{tilt\_angle}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 0.}}) \textendash{} Tilt the adsorbate with an angle (in degress) relative to the
surface normal.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{num\_muts}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 1}}) \textendash{} The number of times to perform this operation.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{dmax}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 2.5}}) \textendash{} The maximum bond length (in Angstrom) between the site and the
bonding atom  that should be considered as an adsorbate.

\end{itemize}

\end{description}\end{quote}
\index{get\_new\_individual() (acat.ga.adsorbate\_operators.ReplaceAdsorbate method)@\spxentry{get\_new\_individual()}\spxextra{acat.ga.adsorbate\_operators.ReplaceAdsorbate method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{ga:acat.ga.adsorbate_operators.ReplaceAdsorbate.get_new_individual}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_new\_individual}}}{\emph{\DUrole{n}{parents}}}{}
Function that returns a new individual.
Overwrite in subclass.

\end{fulllineitems}


\end{fulllineitems}

\index{CutSpliceCrossoverWithAdsorbates (class in acat.ga.adsorbate\_operators)@\spxentry{CutSpliceCrossoverWithAdsorbates}\spxextra{class in acat.ga.adsorbate\_operators}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{ga:acat.ga.adsorbate_operators.CutSpliceCrossoverWithAdsorbates}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{class }}\sphinxcode{\sphinxupquote{acat.ga.adsorbate\_operators.}}\sphinxbfcode{\sphinxupquote{CutSpliceCrossoverWithAdsorbates}}}{\emph{\DUrole{n}{adsorbate\_species}}, \emph{\DUrole{n}{blmin}}, \emph{\DUrole{n}{keep\_composition}\DUrole{o}{=}\DUrole{default_value}{True}}, \emph{\DUrole{n}{fix\_coverage}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{min\_adsorbate\_distance}\DUrole{o}{=}\DUrole{default_value}{2.0}}, \emph{\DUrole{n}{allow\_6fold}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{composition\_effect}\DUrole{o}{=}\DUrole{default_value}{True}}, \emph{\DUrole{n}{rotate\_vectors}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{rotate\_angles}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{dmax}\DUrole{o}{=}\DUrole{default_value}{2.5}}}{}
Bases: {\hyperref[\detokenize{ga:acat.ga.adsorbate_operators.AdsorbateOperator}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{acat.ga.adsorbate\_operators.AdsorbateOperator}}}}}

Crossover that cuts two particles with adsorbates through a plane
in space and merges two halfes from different particles together.

It keeps the correct composition by randomly assigning elements in
the new particle. If some of the atoms in the two particle halves
are too close, the halves are moved away from each other perpendicular
to the cutting plane.

The complexity of crossover with adsorbates makes this operator not
robust enough. The adsorption site identification will fail once the
nanoparticle shape becomes too irregular after crossover.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{adsorbate\_species}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{list of strs}}) \textendash{} One or a list of adsorbate species to be added to the surface.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{blmin}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}) \textendash{} Dictionary of minimum distance between atomic numbers.
e.g. \{(28,29): 1.5\}

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{keep\_composition}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default True}}) \textendash{} Should the composition be the same as in the parents.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{fix\_coverage}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Should the adsorbate coverage be the same as in the parents.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{min\_adsorbate\_distance}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 2.}}) \textendash{} The radius of the sphere inside which no other adsorbates
should be found.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{allow\_6fold}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to allow the adsorption on 6\sphinxhyphen{}fold subsurf sites
underneath fcc hollow sites.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{composition\_effect}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default True}}) \textendash{} Whether to consider sites with different elemental compositions
as different sites. It is recommended to set composition=False
for monometallics. Since GA is commonly used for bimetallics,
the default is set to True.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{rotate\_vectors}} (\sphinxstyleliteralemphasis{\sphinxupquote{list}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} A list of vectors that the part of the structure that is cut
is able to rotate around, the size of rotation is set in
rotate\_angles. Default None meaning no rotation is performed.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{rotate\_angles}} (\sphinxstyleliteralemphasis{\sphinxupquote{list}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} A list of angles that the structure cut can be rotated. The
vector being rotated around is set in rotate\_vectors. Default
None meaning no rotation is performed.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{dmax}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 2.5}}) \textendash{} The maximum bond length (in Angstrom) between the site and the
bonding atom  that should be considered as an adsorbate.

\end{itemize}

\end{description}\end{quote}
\index{get\_new\_individual() (acat.ga.adsorbate\_operators.CutSpliceCrossoverWithAdsorbates method)@\spxentry{get\_new\_individual()}\spxextra{acat.ga.adsorbate\_operators.CutSpliceCrossoverWithAdsorbates method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{ga:acat.ga.adsorbate_operators.CutSpliceCrossoverWithAdsorbates.get_new_individual}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_new\_individual}}}{\emph{\DUrole{n}{parents}}}{}
Function that returns a new individual.
Overwrite in subclass.

\end{fulllineitems}

\index{get\_vectors\_below\_min\_dist() (acat.ga.adsorbate\_operators.CutSpliceCrossoverWithAdsorbates method)@\spxentry{get\_vectors\_below\_min\_dist()}\spxextra{acat.ga.adsorbate\_operators.CutSpliceCrossoverWithAdsorbates method}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{ga:acat.ga.adsorbate_operators.CutSpliceCrossoverWithAdsorbates.get_vectors_below_min_dist}}\pysiglinewithargsret{\sphinxbfcode{\sphinxupquote{get\_vectors\_below\_min\_dist}}}{\emph{\DUrole{n}{atoms}}}{}
Generator function that returns each vector (between atoms)
that is shorter than the minimum distance for those atom types
(set during the initialization in blmin).

\end{fulllineitems}


\end{fulllineitems}



\subsection{Usage}
\label{\detokenize{ga:usage}}
All the adsorbate operators can be easily used with other ASE operators. \sphinxcode{\sphinxupquote{AddAdsorbate}}, \sphinxcode{\sphinxupquote{RemoveAdsorbate}}, \sphinxcode{\sphinxupquote{MoveAdsorbate}} and \sphinxcode{\sphinxupquote{ReplaceAdsorbate}} operators can be used for both non\sphinxhyphen{}periodic nanoparticles and periodic surface slabs. \sphinxcode{\sphinxupquote{CutSpliceCrossoverWithAdsorbates}} operator only works for nanoparticles, and it is not recommonded as it is not stable yet.

As an example we will find the stable structures of a Ni110Pt37 icosahedral nanoparticle with adsorbate species of H, C, O, OH, CO, CH, CH2 and CH3 using the EMT calculator.

The script for the genetic algorithm looks as follows:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{settings} \PYG{k+kn}{import} \PYG{n}{adsorbate\PYGZus{}elements}
\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{adsorbate\PYGZus{}coverage} \PYG{k+kn}{import} \PYG{n}{ClusterAdsorbateCoverage}
\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{build}\PYG{n+nn}{.}\PYG{n+nn}{orderings} \PYG{k+kn}{import} \PYG{n}{RandomOrderingGenerator} \PYG{k}{as} \PYG{n}{ROG}
\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{build}\PYG{n+nn}{.}\PYG{n+nn}{patterns} \PYG{k+kn}{import} \PYG{n}{random\PYGZus{}coverage\PYGZus{}pattern}
\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{ga}\PYG{n+nn}{.}\PYG{n+nn}{adsorbate\PYGZus{}operators} \PYG{k+kn}{import} \PYG{n}{AddAdsorbate}\PYG{p}{,} \PYG{n}{RemoveAdsorbate}
\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{ga}\PYG{n+nn}{.}\PYG{n+nn}{adsorbate\PYGZus{}operators} \PYG{k+kn}{import} \PYG{n}{MoveAdsorbate}\PYG{p}{,} \PYG{n}{ReplaceAdsorbate}
\PYG{k+kn}{from} \PYG{n+nn}{acat}\PYG{n+nn}{.}\PYG{n+nn}{ga}\PYG{n+nn}{.}\PYG{n+nn}{adsorbate\PYGZus{}operators} \PYG{k+kn}{import} \PYG{n}{CutSpliceCrossoverWithAdsorbates}
\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{ga}\PYG{n+nn}{.}\PYG{n+nn}{particle\PYGZus{}mutations} \PYG{k+kn}{import} \PYG{n}{RandomPermutation}\PYG{p}{,} \PYG{n}{COM2surfPermutation}
\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{ga}\PYG{n+nn}{.}\PYG{n+nn}{particle\PYGZus{}mutations} \PYG{k+kn}{import} \PYG{n}{Rich2poorPermutation}\PYG{p}{,} \PYG{n}{Poor2richPermutation}
\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{ga}\PYG{n+nn}{.}\PYG{n+nn}{particle\PYGZus{}comparator} \PYG{k+kn}{import} \PYG{n}{NNMatComparator}
\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{ga}\PYG{n+nn}{.}\PYG{n+nn}{standard\PYGZus{}comparators} \PYG{k+kn}{import} \PYG{n}{SequentialComparator}
\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{ga}\PYG{n+nn}{.}\PYG{n+nn}{adsorbate\PYGZus{}comparators} \PYG{k+kn}{import} \PYG{n}{AdsorptionSitesComparator}
\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{ga}\PYG{n+nn}{.}\PYG{n+nn}{offspring\PYGZus{}creator} \PYG{k+kn}{import} \PYG{n}{OperationSelector}
\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{ga}\PYG{n+nn}{.}\PYG{n+nn}{population} \PYG{k+kn}{import} \PYG{n}{Population}\PYG{p}{,} \PYG{n}{RankFitnessPopulation}
\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{ga}\PYG{n+nn}{.}\PYG{n+nn}{convergence} \PYG{k+kn}{import} \PYG{n}{GenerationRepetitionConvergence}
\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{ga}\PYG{n+nn}{.}\PYG{n+nn}{utilities} \PYG{k+kn}{import} \PYG{n}{closest\PYGZus{}distances\PYGZus{}generator}
\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{ga}\PYG{n+nn}{.}\PYG{n+nn}{data} \PYG{k+kn}{import} \PYG{n}{DataConnection}\PYG{p}{,} \PYG{n}{PrepareDB}
\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{io} \PYG{k+kn}{import} \PYG{n}{read}\PYG{p}{,} \PYG{n}{write}
\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{cluster} \PYG{k+kn}{import} \PYG{n}{Icosahedron}
\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{calculators}\PYG{n+nn}{.}\PYG{n+nn}{emt} \PYG{k+kn}{import} \PYG{n}{EMT}
\PYG{k+kn}{from} \PYG{n+nn}{ase}\PYG{n+nn}{.}\PYG{n+nn}{optimize} \PYG{k+kn}{import} \PYG{n}{BFGS}
\PYG{k+kn}{from} \PYG{n+nn}{collections} \PYG{k+kn}{import} \PYG{n}{defaultdict}
\PYG{k+kn}{from} \PYG{n+nn}{random} \PYG{k+kn}{import} \PYG{n}{choices}\PYG{p}{,} \PYG{n}{uniform}

\PYG{c+c1}{\PYGZsh{} Generate 50 icosahedral Ni110Pt37 nanoparticles with random orderings}
\PYG{n}{pop\PYGZus{}size} \PYG{o}{=} \PYG{l+m+mi}{50}
\PYG{n}{particle} \PYG{o}{=} \PYG{n}{Icosahedron}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Ni}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{n}{noshells}\PYG{o}{=}\PYG{l+m+mi}{4}\PYG{p}{)}
\PYG{n}{particle}\PYG{o}{.}\PYG{n}{center}\PYG{p}{(}\PYG{n}{vacuum}\PYG{o}{=}\PYG{l+m+mf}{5.}\PYG{p}{)}
\PYG{n}{rog} \PYG{o}{=} \PYG{n}{ROG}\PYG{p}{(}\PYG{n}{particle}\PYG{p}{,} \PYG{n}{species}\PYG{o}{=}\PYG{p}{[}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Ni}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Pt}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]}\PYG{p}{,}
          \PYG{n}{composition}\PYG{o}{=}\PYG{p}{\PYGZob{}}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Ni}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+m+mf}{0.75}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Pt}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{l+m+mf}{0.25}\PYG{p}{\PYGZcb{}}\PYG{p}{)}
\PYG{n}{rog}\PYG{o}{.}\PYG{n}{run}\PYG{p}{(}\PYG{n}{n\PYGZus{}gen}\PYG{o}{=}\PYG{n}{pop\PYGZus{}size}\PYG{p}{)}

\PYG{c+c1}{\PYGZsh{} Generate random coverage on each nanoparticle}
\PYG{n}{species}\PYG{o}{=}\PYG{p}{[}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{H}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{C}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{O}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{OH}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{CO}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{CH}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{CH2}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{CH3}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]}
\PYG{n}{images} \PYG{o}{=} \PYG{n}{read}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{orderings.traj}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{n}{index}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{:}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}
\PYG{n}{patterns} \PYG{o}{=} \PYG{p}{[}\PYG{p}{]}
\PYG{k}{for} \PYG{n}{atoms} \PYG{o+ow}{in} \PYG{n}{images}\PYG{p}{:}
    \PYG{n}{dmin} \PYG{o}{=} \PYG{n}{uniform}\PYG{p}{(}\PYG{l+m+mf}{3.5}\PYG{p}{,} \PYG{l+m+mf}{8.5}\PYG{p}{)}
    \PYG{n}{pattern} \PYG{o}{=} \PYG{n}{random\PYGZus{}coverage\PYGZus{}pattern}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{adsorbate\PYGZus{}species}\PYG{o}{=}\PYG{n}{species}\PYG{p}{,}
                                      \PYG{n}{min\PYGZus{}adsorbate\PYGZus{}distance}\PYG{o}{=}\PYG{n}{dmin}\PYG{p}{)}
    \PYG{n}{patterns}\PYG{o}{.}\PYG{n}{append}\PYG{p}{(}\PYG{n}{pattern}\PYG{p}{)}

\PYG{c+c1}{\PYGZsh{} Instantiate the db}
\PYG{n}{db\PYGZus{}name} \PYG{o}{=} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{emt\PYGZus{}ridge\PYGZus{}Ni110Pt37\PYGZus{}ads.db}\PYG{l+s+s1}{\PYGZsq{}}

\PYG{n}{db} \PYG{o}{=} \PYG{n}{PrepareDB}\PYG{p}{(}\PYG{n}{db\PYGZus{}name}\PYG{p}{,} \PYG{n}{cell}\PYG{o}{=}\PYG{n}{particle}\PYG{o}{.}\PYG{n}{cell}\PYG{p}{,} \PYG{n}{population\PYGZus{}size}\PYG{o}{=}\PYG{n}{pop\PYGZus{}size}\PYG{p}{)}

\PYG{k}{for} \PYG{n}{atoms} \PYG{o+ow}{in} \PYG{n}{patterns}\PYG{p}{:}
    \PYG{k}{if} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{data}\PYG{l+s+s1}{\PYGZsq{}} \PYG{o+ow}{not} \PYG{o+ow}{in} \PYG{n}{atoms}\PYG{o}{.}\PYG{n}{info}\PYG{p}{:}
        \PYG{n}{atoms}\PYG{o}{.}\PYG{n}{info}\PYG{p}{[}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{data}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]} \PYG{o}{=} \PYG{p}{\PYGZob{}}\PYG{p}{\PYGZcb{}}
    \PYG{n}{db}\PYG{o}{.}\PYG{n}{add\PYGZus{}unrelaxed\PYGZus{}candidate}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{data}\PYG{o}{=}\PYG{n}{atoms}\PYG{o}{.}\PYG{n}{info}\PYG{p}{[}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{data}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]}\PYG{p}{)}

\PYG{c+c1}{\PYGZsh{} Connect to the db}
\PYG{n}{db} \PYG{o}{=} \PYG{n}{DataConnection}\PYG{p}{(}\PYG{n}{db\PYGZus{}name}\PYG{p}{)}

\PYG{c+c1}{\PYGZsh{} Define operators}
\PYG{n}{soclist} \PYG{o}{=} \PYG{p}{(}\PYG{p}{[}\PYG{l+m+mi}{1}\PYG{p}{,} \PYG{l+m+mi}{1}\PYG{p}{,} \PYG{l+m+mi}{2}\PYG{p}{,} \PYG{l+m+mi}{1}\PYG{p}{,} \PYG{l+m+mi}{1}\PYG{p}{,} \PYG{l+m+mi}{1}\PYG{p}{,} \PYG{l+m+mi}{1}\PYG{p}{]}\PYG{p}{,}
           \PYG{p}{[}\PYG{n}{Rich2poorPermutation}\PYG{p}{(}\PYG{n}{elements}\PYG{o}{=}\PYG{p}{[}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Ni}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Pt}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]}\PYG{p}{,} \PYG{n}{num\PYGZus{}muts}\PYG{o}{=}\PYG{l+m+mi}{5}\PYG{p}{)}\PYG{p}{,}
            \PYG{n}{Poor2richPermutation}\PYG{p}{(}\PYG{n}{elements}\PYG{o}{=}\PYG{p}{[}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Ni}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Pt}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]}\PYG{p}{,} \PYG{n}{num\PYGZus{}muts}\PYG{o}{=}\PYG{l+m+mi}{5}\PYG{p}{)}\PYG{p}{,}
            \PYG{n}{RandomPermutation}\PYG{p}{(}\PYG{n}{num\PYGZus{}muts}\PYG{o}{=}\PYG{l+m+mi}{5}\PYG{p}{)}\PYG{p}{,}
            \PYG{n}{AddAdsorbate}\PYG{p}{(}\PYG{n}{species}\PYG{p}{,} \PYG{n}{num\PYGZus{}muts}\PYG{o}{=}\PYG{l+m+mi}{5}\PYG{p}{)}\PYG{p}{,}
            \PYG{n}{RemoveAdsorbate}\PYG{p}{(}\PYG{n}{species}\PYG{p}{,} \PYG{n}{num\PYGZus{}muts}\PYG{o}{=}\PYG{l+m+mi}{5}\PYG{p}{)}\PYG{p}{,}
            \PYG{n}{MoveAdsorbate}\PYG{p}{(}\PYG{n}{species}\PYG{p}{,} \PYG{n}{num\PYGZus{}muts}\PYG{o}{=}\PYG{l+m+mi}{5}\PYG{p}{)}\PYG{p}{,}
            \PYG{n}{ReplaceAdsorbate}\PYG{p}{(}\PYG{n}{species}\PYG{p}{,} \PYG{n}{num\PYGZus{}muts}\PYG{o}{=}\PYG{l+m+mi}{5}\PYG{p}{)}\PYG{p}{,}\PYG{p}{]}\PYG{p}{)}

\PYG{n}{op\PYGZus{}selector} \PYG{o}{=} \PYG{n}{OperationSelector}\PYG{p}{(}\PYG{o}{*}\PYG{n}{soclist}\PYG{p}{)}

\PYG{n}{comp} \PYG{o}{=} \PYG{n}{SequentialComparator}\PYG{p}{(}\PYG{p}{[}\PYG{n}{AdsorptionSitesComparator}\PYG{p}{(}\PYG{l+m+mi}{10}\PYG{p}{)}\PYG{p}{,}
                             \PYG{n}{NNMatComparator}\PYG{p}{(}\PYG{l+m+mf}{0.2}\PYG{p}{,}\PYG{p}{[}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Ni}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Pt}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]}\PYG{p}{)}\PYG{p}{]}\PYG{p}{,}
                            \PYG{p}{[}\PYG{l+m+mf}{0.5}\PYG{p}{,} \PYG{l+m+mf}{0.5}\PYG{p}{]}\PYG{p}{)}

\PYG{k}{def} \PYG{n+nf}{get\PYGZus{}ads}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{)}\PYG{p}{:}
    \PYG{l+s+sd}{\PYGZdq{}\PYGZdq{}\PYGZdq{}Returns a list of adsorbate names and corresponding indices.\PYGZdq{}\PYGZdq{}\PYGZdq{}}

    \PYG{k}{if} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{data}\PYG{l+s+s1}{\PYGZsq{}} \PYG{o+ow}{not} \PYG{o+ow}{in} \PYG{n}{atoms}\PYG{o}{.}\PYG{n}{info}\PYG{p}{:}
        \PYG{n}{atoms}\PYG{o}{.}\PYG{n}{info}\PYG{p}{[}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{data}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]} \PYG{o}{=} \PYG{p}{\PYGZob{}}\PYG{p}{\PYGZcb{}}
    \PYG{k}{if} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{adsorbates}\PYG{l+s+s1}{\PYGZsq{}} \PYG{o+ow}{in} \PYG{n}{atoms}\PYG{o}{.}\PYG{n}{info}\PYG{p}{[}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{data}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]}\PYG{p}{:}
        \PYG{n}{adsorbates} \PYG{o}{=} \PYG{n}{atoms}\PYG{o}{.}\PYG{n}{info}\PYG{p}{[}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{data}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]}\PYG{p}{[}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{adsorbates}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]}
    \PYG{k}{else}\PYG{p}{:}
        \PYG{n}{cac} \PYG{o}{=} \PYG{n}{ClusterAdsorbateCoverage}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{)}
        \PYG{n}{adsorbates} \PYG{o}{=} \PYG{n}{cac}\PYG{o}{.}\PYG{n}{get\PYGZus{}adsorbates}\PYG{p}{(}\PYG{p}{)}

    \PYG{k}{return} \PYG{n}{adsorbates}

\PYG{k}{def} \PYG{n+nf}{vf}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{)}\PYG{p}{:}
    \PYG{l+s+sd}{\PYGZdq{}\PYGZdq{}\PYGZdq{}Returns the descriptor that distinguishes candidates in the}
\PYG{l+s+sd}{    niched population.\PYGZdq{}\PYGZdq{}\PYGZdq{}}

    \PYG{k}{return} \PYG{n+nb}{len}\PYG{p}{(}\PYG{n}{get\PYGZus{}ads}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{)}\PYG{p}{)}

\PYG{c+c1}{\PYGZsh{} Define population}
\PYG{n}{pop\PYGZus{}size} \PYG{o}{=} \PYG{n}{db}\PYG{o}{.}\PYG{n}{get\PYGZus{}param}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{population\PYGZus{}size}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}

\PYG{c+c1}{\PYGZsh{} Give fittest candidates at different coverages equal fitness}
\PYG{n}{pop} \PYG{o}{=} \PYG{n}{RankFitnessPopulation}\PYG{p}{(}\PYG{n}{data\PYGZus{}connection}\PYG{o}{=}\PYG{n}{db}\PYG{p}{,}
                            \PYG{n}{population\PYGZus{}size}\PYG{o}{=}\PYG{n}{pop\PYGZus{}size}\PYG{p}{,}
                            \PYG{n}{comparator}\PYG{o}{=}\PYG{n}{comp}\PYG{p}{,}
                            \PYG{n}{variable\PYGZus{}function}\PYG{o}{=}\PYG{n}{vf}\PYG{p}{,}
                            \PYG{n}{exp\PYGZus{}function}\PYG{o}{=}\PYG{k+kc}{True}\PYG{p}{,}
                            \PYG{n}{logfile}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{log.txt}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}

\PYG{c+c1}{\PYGZsh{} Normal fitness ranking regardless of coverage}
\PYG{c+c1}{\PYGZsh{}pop = Population(data\PYGZus{}connection=db,}
\PYG{c+c1}{\PYGZsh{}                 population\PYGZus{}size=pop\PYGZus{}size,}
\PYG{c+c1}{\PYGZsh{}                 comparator=comp,}
\PYG{c+c1}{\PYGZsh{}                 logfile=\PYGZsq{}log.txt\PYGZsq{})}

\PYG{c+c1}{\PYGZsh{} Set convergence criteria}
\PYG{n}{cc} \PYG{o}{=} \PYG{n}{GenerationRepetitionConvergence}\PYG{p}{(}\PYG{n}{pop}\PYG{p}{,} \PYG{l+m+mi}{5}\PYG{p}{)}

\PYG{c+c1}{\PYGZsh{} Calculate chemical potentials}
\PYG{n}{chem\PYGZus{}pots} \PYG{o}{=} \PYG{p}{\PYGZob{}}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{CH4}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{o}{\PYGZhy{}}\PYG{l+m+mf}{24.039}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{H2O}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{o}{\PYGZhy{}}\PYG{l+m+mf}{14.169}\PYG{p}{,} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{H2}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{:} \PYG{o}{\PYGZhy{}}\PYG{l+m+mf}{6.989}\PYG{p}{\PYGZcb{}}

\PYG{c+c1}{\PYGZsh{} Define the relax function}
\PYG{k}{def} \PYG{n+nf}{relax}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{single\PYGZus{}point}\PYG{o}{=}\PYG{k+kc}{False}\PYG{p}{)}\PYG{p}{:}
    \PYG{n}{atoms}\PYG{o}{.}\PYG{n}{center}\PYG{p}{(}\PYG{n}{vacuum}\PYG{o}{=}\PYG{l+m+mf}{5.}\PYG{p}{)}
    \PYG{n}{atoms}\PYG{o}{.}\PYG{n}{calc} \PYG{o}{=} \PYG{n}{EMT}\PYG{p}{(}\PYG{p}{)}
    \PYG{k}{if} \PYG{o+ow}{not} \PYG{n}{single\PYGZus{}point}\PYG{p}{:}
        \PYG{n}{opt} \PYG{o}{=} \PYG{n}{BFGS}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{logfile}\PYG{o}{=}\PYG{k+kc}{None}\PYG{p}{)}
        \PYG{n}{opt}\PYG{o}{.}\PYG{n}{run}\PYG{p}{(}\PYG{n}{fmax}\PYG{o}{=}\PYG{l+m+mf}{0.1}\PYG{p}{)}

    \PYG{n}{Epot} \PYG{o}{=} \PYG{n}{atoms}\PYG{o}{.}\PYG{n}{get\PYGZus{}potential\PYGZus{}energy}\PYG{p}{(}\PYG{p}{)}
    \PYG{n}{num\PYGZus{}H} \PYG{o}{=} \PYG{n+nb}{len}\PYG{p}{(}\PYG{p}{[}\PYG{n}{s} \PYG{k}{for} \PYG{n}{s} \PYG{o+ow}{in} \PYG{n}{atoms}\PYG{o}{.}\PYG{n}{symbols} \PYG{k}{if} \PYG{n}{s} \PYG{o}{==} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{H}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]}\PYG{p}{)}
    \PYG{n}{num\PYGZus{}C} \PYG{o}{=} \PYG{n+nb}{len}\PYG{p}{(}\PYG{p}{[}\PYG{n}{s} \PYG{k}{for} \PYG{n}{s} \PYG{o+ow}{in} \PYG{n}{atoms}\PYG{o}{.}\PYG{n}{symbols} \PYG{k}{if} \PYG{n}{s} \PYG{o}{==} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{C}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]}\PYG{p}{)}
    \PYG{n}{num\PYGZus{}O} \PYG{o}{=} \PYG{n+nb}{len}\PYG{p}{(}\PYG{p}{[}\PYG{n}{s} \PYG{k}{for} \PYG{n}{s} \PYG{o+ow}{in} \PYG{n}{atoms}\PYG{o}{.}\PYG{n}{symbols} \PYG{k}{if} \PYG{n}{s} \PYG{o}{==} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{O}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]}\PYG{p}{)}
    \PYG{n}{mutot} \PYG{o}{=} \PYG{n}{num\PYGZus{}C} \PYG{o}{*} \PYG{n}{chem\PYGZus{}pots}\PYG{p}{[}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{CH4}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]} \PYG{o}{+} \PYG{n}{num\PYGZus{}O} \PYG{o}{*} \PYG{n}{chem\PYGZus{}pots}\PYG{p}{[}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{H2O}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]} \PYG{o}{+} \PYG{p}{(}
            \PYG{n}{num\PYGZus{}H} \PYG{o}{\PYGZhy{}} \PYG{l+m+mi}{4} \PYG{o}{*} \PYG{n}{num\PYGZus{}C} \PYG{o}{\PYGZhy{}} \PYG{l+m+mi}{2} \PYG{o}{*} \PYG{n}{num\PYGZus{}O}\PYG{p}{)} \PYG{o}{*} \PYG{n}{chem\PYGZus{}pots}\PYG{p}{[}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{H2}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]} \PYG{o}{/} \PYG{l+m+mi}{2}
    \PYG{n}{f} \PYG{o}{=} \PYG{n}{Epot} \PYG{o}{\PYGZhy{}} \PYG{n}{mutot}

    \PYG{n}{atoms}\PYG{o}{.}\PYG{n}{info}\PYG{p}{[}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{key\PYGZus{}value\PYGZus{}pairs}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]}\PYG{p}{[}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{raw\PYGZus{}score}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]} \PYG{o}{=} \PYG{o}{\PYGZhy{}}\PYG{n}{f}
    \PYG{n}{atoms}\PYG{o}{.}\PYG{n}{info}\PYG{p}{[}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{key\PYGZus{}value\PYGZus{}pairs}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]}\PYG{p}{[}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{potential\PYGZus{}energy}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]} \PYG{o}{=} \PYG{n}{Epot}

    \PYG{k}{return} \PYG{n}{atoms}

\PYG{c+c1}{\PYGZsh{} Relax starting generation}
\PYG{k}{while} \PYG{n}{db}\PYG{o}{.}\PYG{n}{get\PYGZus{}number\PYGZus{}of\PYGZus{}unrelaxed\PYGZus{}candidates}\PYG{p}{(}\PYG{p}{)} \PYG{o}{\PYGZgt{}} \PYG{l+m+mi}{0}\PYG{p}{:}
    \PYG{n}{atoms} \PYG{o}{=} \PYG{n}{db}\PYG{o}{.}\PYG{n}{get\PYGZus{}an\PYGZus{}unrelaxed\PYGZus{}candidate}\PYG{p}{(}\PYG{p}{)}
    \PYG{k}{if} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{data}\PYG{l+s+s1}{\PYGZsq{}} \PYG{o+ow}{not} \PYG{o+ow}{in} \PYG{n}{atoms}\PYG{o}{.}\PYG{n}{info}\PYG{p}{:}
        \PYG{n}{atoms}\PYG{o}{.}\PYG{n}{info}\PYG{p}{[}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{data}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]} \PYG{o}{=} \PYG{p}{\PYGZob{}}\PYG{p}{\PYGZcb{}}
    \PYG{n}{nncomp} \PYG{o}{=} \PYG{n}{atoms}\PYG{o}{.}\PYG{n}{get\PYGZus{}chemical\PYGZus{}formula}\PYG{p}{(}\PYG{n}{mode}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{hill}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}
    \PYG{n+nb}{print}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Relaxing }\PYG{l+s+s1}{\PYGZsq{}} \PYG{o}{+} \PYG{n}{nncomp}\PYG{p}{)}
    \PYG{n}{relax}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{,} \PYG{n}{single\PYGZus{}point}\PYG{o}{=}\PYG{k+kc}{True}\PYG{p}{)} \PYG{c+c1}{\PYGZsh{} Single point for simplification}
    \PYG{n}{db}\PYG{o}{.}\PYG{n}{add\PYGZus{}relaxed\PYGZus{}step}\PYG{p}{(}\PYG{n}{atoms}\PYG{p}{)}
\PYG{n}{pop}\PYG{o}{.}\PYG{n}{update}\PYG{p}{(}\PYG{p}{)}

\PYG{c+c1}{\PYGZsh{} Number of generations}
\PYG{n}{num\PYGZus{}gens} \PYG{o}{=} \PYG{l+m+mi}{1000}

\PYG{c+c1}{\PYGZsh{} Below is the iterative part of the algorithm}
\PYG{n}{gen\PYGZus{}num} \PYG{o}{=} \PYG{n}{db}\PYG{o}{.}\PYG{n}{get\PYGZus{}generation\PYGZus{}number}\PYG{p}{(}\PYG{p}{)}
\PYG{k}{for} \PYG{n}{i} \PYG{o+ow}{in} \PYG{n+nb}{range}\PYG{p}{(}\PYG{n}{num\PYGZus{}gens}\PYG{p}{)}\PYG{p}{:}
    \PYG{c+c1}{\PYGZsh{} Check if converged}
    \PYG{k}{if} \PYG{n}{cc}\PYG{o}{.}\PYG{n}{converged}\PYG{p}{(}\PYG{p}{)}\PYG{p}{:}
        \PYG{n+nb}{print}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Converged}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}
        \PYG{k}{break}

    \PYG{n+nb}{print}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Creating and evaluating generation }\PYG{l+s+si}{\PYGZob{}0\PYGZcb{}}\PYG{l+s+s1}{\PYGZsq{}}\PYG{o}{.}\PYG{n}{format}\PYG{p}{(}\PYG{n}{gen\PYGZus{}num} \PYG{o}{+} \PYG{n}{i}\PYG{p}{)}\PYG{p}{)}
    \PYG{n}{new\PYGZus{}generation} \PYG{o}{=} \PYG{p}{[}\PYG{p}{]}
    \PYG{k}{for} \PYG{n}{\PYGZus{}} \PYG{o+ow}{in} \PYG{n+nb}{range}\PYG{p}{(}\PYG{n}{pop\PYGZus{}size}\PYG{p}{)}\PYG{p}{:}
        \PYG{c+c1}{\PYGZsh{} Select an operator and use it}
        \PYG{n}{op} \PYG{o}{=} \PYG{n}{op\PYGZus{}selector}\PYG{o}{.}\PYG{n}{get\PYGZus{}operator}\PYG{p}{(}\PYG{p}{)}
        \PYG{c+c1}{\PYGZsh{} Select parents for a new candidate}
        \PYG{n}{p1}\PYG{p}{,} \PYG{n}{p2} \PYG{o}{=} \PYG{n}{pop}\PYG{o}{.}\PYG{n}{get\PYGZus{}two\PYGZus{}candidates}\PYG{p}{(}\PYG{p}{)}
        \PYG{n}{parents} \PYG{o}{=} \PYG{p}{[}\PYG{n}{p1}\PYG{p}{,} \PYG{n}{p2}\PYG{p}{]}

        \PYG{c+c1}{\PYGZsh{} Pure or bare nanoparticles are not considered}
        \PYG{k}{if} \PYG{n+nb}{len}\PYG{p}{(}\PYG{n+nb}{set}\PYG{p}{(}\PYG{n}{p1}\PYG{o}{.}\PYG{n}{numbers}\PYG{p}{)}\PYG{p}{)} \PYG{o}{\PYGZlt{}} \PYG{l+m+mi}{3}\PYG{p}{:}
            \PYG{k}{continue}
        \PYG{n}{offspring}\PYG{p}{,} \PYG{n}{desc} \PYG{o}{=} \PYG{n}{op}\PYG{o}{.}\PYG{n}{get\PYGZus{}new\PYGZus{}individual}\PYG{p}{(}\PYG{n}{parents}\PYG{p}{)}
        \PYG{c+c1}{\PYGZsh{} An operator could return None if an offspring cannot be formed}
        \PYG{c+c1}{\PYGZsh{} by the chosen parents}
        \PYG{k}{if} \PYG{n}{offspring} \PYG{o+ow}{is} \PYG{k+kc}{None}\PYG{p}{:}
            \PYG{k}{continue}

        \PYG{n}{nncomp} \PYG{o}{=} \PYG{n}{offspring}\PYG{o}{.}\PYG{n}{get\PYGZus{}chemical\PYGZus{}formula}\PYG{p}{(}\PYG{n}{mode}\PYG{o}{=}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{hill}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{)}
        \PYG{n+nb}{print}\PYG{p}{(}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{Relaxing }\PYG{l+s+s1}{\PYGZsq{}} \PYG{o}{+} \PYG{n}{nncomp}\PYG{p}{)}
        \PYG{k}{if} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{data}\PYG{l+s+s1}{\PYGZsq{}} \PYG{o+ow}{not} \PYG{o+ow}{in} \PYG{n}{offspring}\PYG{o}{.}\PYG{n}{info}\PYG{p}{:}
            \PYG{n}{offspring}\PYG{o}{.}\PYG{n}{info}\PYG{p}{[}\PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{data}\PYG{l+s+s1}{\PYGZsq{}}\PYG{p}{]} \PYG{o}{=} \PYG{p}{\PYGZob{}}\PYG{p}{\PYGZcb{}}
        \PYG{n}{relax}\PYG{p}{(}\PYG{n}{offspring}\PYG{p}{,} \PYG{n}{single\PYGZus{}point}\PYG{o}{=}\PYG{k+kc}{True}\PYG{p}{)} \PYG{c+c1}{\PYGZsh{} Single point for simplification}
        \PYG{n}{new\PYGZus{}generation}\PYG{o}{.}\PYG{n}{append}\PYG{p}{(}\PYG{n}{offspring}\PYG{p}{)}

    \PYG{c+c1}{\PYGZsh{} We add a full relaxed generation at once, this is faster than adding}
    \PYG{c+c1}{\PYGZsh{} one at a time}
    \PYG{n}{db}\PYG{o}{.}\PYG{n}{add\PYGZus{}more\PYGZus{}relaxed\PYGZus{}candidates}\PYG{p}{(}\PYG{n}{new\PYGZus{}generation}\PYG{p}{)}

    \PYG{c+c1}{\PYGZsh{} update the population to allow new candidates to enter}
    \PYG{n}{pop}\PYG{o}{.}\PYG{n}{update}\PYG{p}{(}\PYG{p}{)}
\end{sphinxVerbatim}


\section{Other utilities}
\label{\detokenize{utilities:module-acat.utilities}}\label{\detokenize{utilities:other-utilities}}\label{\detokenize{utilities::doc}}\index{module@\spxentry{module}!acat.utilities@\spxentry{acat.utilities}}\index{acat.utilities@\spxentry{acat.utilities}!module@\spxentry{module}}\index{neighbor\_shell\_list() (in module acat.utilities)@\spxentry{neighbor\_shell\_list()}\spxextra{in module acat.utilities}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{utilities:acat.utilities.neighbor_shell_list}}\pysiglinewithargsret{\sphinxcode{\sphinxupquote{acat.utilities.}}\sphinxbfcode{\sphinxupquote{neighbor\_shell\_list}}}{\emph{\DUrole{n}{atoms}}, \emph{\DUrole{n}{dx}\DUrole{o}{=}\DUrole{default_value}{0.3}}, \emph{\DUrole{n}{neighbor\_number}\DUrole{o}{=}\DUrole{default_value}{1}}, \emph{\DUrole{n}{different\_species}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{mic}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{radius}\DUrole{o}{=}\DUrole{default_value}{None}}, \emph{\DUrole{n}{span}\DUrole{o}{=}\DUrole{default_value}{False}}}{}
Make dict of neighboring shell atoms for both periodic and
non\sphinxhyphen{}periodic systems. Possible to return neighbors from defined
neighbor shell e.g. 1st, 2nd, 3rd by changing the neighbor number.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{atoms}} (\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atoms object}}) \textendash{} Accept any ase.Atoms object. No need to be built\sphinxhyphen{}in.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{dx}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 0.3}}) \textendash{} Buffer to calculate nearest neighbor pairs.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{neighbor\_number}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 1}}) \textendash{} Neighbor shell number.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{different\_species}} (\sphinxstyleliteralemphasis{\sphinxupquote{boolean}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether each neighbor pair are different species.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{mic}} (\sphinxstyleliteralemphasis{\sphinxupquote{boolean}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to apply minimum image convention. Remember to set
mic=True for periodic systems.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{radius}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default None}}) \textendash{} The radius of each shell. Works exactly as a conventional
neighbor list when specified. If not specified, use covalent
radii instead.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{span}} (\sphinxstyleliteralemphasis{\sphinxupquote{boolean}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to include all neighbors spanned within the shell.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{get\_connectivity\_matrix() (in module acat.utilities)@\spxentry{get\_connectivity\_matrix()}\spxextra{in module acat.utilities}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{utilities:acat.utilities.get_connectivity_matrix}}\pysiglinewithargsret{\sphinxcode{\sphinxupquote{acat.utilities.}}\sphinxbfcode{\sphinxupquote{get\_connectivity\_matrix}}}{\emph{\DUrole{n}{neighborlist}}}{}
Returns a connectivity matrix from a neighborlist object.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode
\sphinxstyleliteralstrong{\sphinxupquote{neighborlist}} (\sphinxstyleliteralemphasis{\sphinxupquote{dict}}) \textendash{} A neighborlist (dictionary) that contains keys of each
atom index and values of their neighbor atom indices.

\end{description}\end{quote}

\end{fulllineitems}

\index{get\_mic() (in module acat.utilities)@\spxentry{get\_mic()}\spxextra{in module acat.utilities}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{utilities:acat.utilities.get_mic}}\pysiglinewithargsret{\sphinxcode{\sphinxupquote{acat.utilities.}}\sphinxbfcode{\sphinxupquote{get\_mic}}}{\emph{\DUrole{n}{p1}}, \emph{\DUrole{n}{p2}}, \emph{\DUrole{n}{cell}}, \emph{\DUrole{n}{pbc}\DUrole{o}{=}\DUrole{default_value}{{[}1, 1, 0{]}}}, \emph{\DUrole{n}{max\_cell\_multiples}\DUrole{o}{=}\DUrole{default_value}{100000.0}}, \emph{\DUrole{n}{return\_squared\_distance}\DUrole{o}{=}\DUrole{default_value}{False}}}{}
A highly efficient function for getting all vectors from p1
to p2. Also able to calculate the squared distance using the
minimum image convention (mic). This function is useful when you
want to constantly calculate mic between two given positions.
Please use ase.geometry.find\_mic if you want to calculate an
array of vectors all at a time (useful for e.g. neighborlist).
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{p1}} (\sphinxstyleliteralemphasis{\sphinxupquote{numpy.array}}) \textendash{} The 3D Cartesian coordinate of the position 1.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{p2}} (\sphinxstyleliteralemphasis{\sphinxupquote{numpy.array}}) \textendash{} The 3D Cartesian coordinate of the position 2.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{cell}} (\sphinxstyleliteralemphasis{\sphinxupquote{numpy.array}}) \textendash{} The 3D parallel epipedal unit cell.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{pbc}} (\sphinxstyleliteralemphasis{\sphinxupquote{numpy.array}}\sphinxstyleliteralemphasis{\sphinxupquote{ or }}\sphinxstyleliteralemphasis{\sphinxupquote{list}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default}}\sphinxstyleliteralemphasis{\sphinxupquote{ {[}}}\sphinxstyleliteralemphasis{\sphinxupquote{1}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{1}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{0}}\sphinxstyleliteralemphasis{\sphinxupquote{{]}}}) \textendash{} Whether cell is periodic in each direction.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{max\_cell\_multiples}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 1e5}}) \textendash{} A large number to account for the maximum repetitions of each
of the lattice vectors. The minimum number of repetitions is
hence calculated by the algorithm using the intersection of a
sphere and the unit cell.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{return\_squared\_distance}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to return the squared mic distance instead of the
mic vector.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{get\_close\_atoms() (in module acat.utilities)@\spxentry{get\_close\_atoms()}\spxextra{in module acat.utilities}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{utilities:acat.utilities.get_close_atoms}}\pysiglinewithargsret{\sphinxcode{\sphinxupquote{acat.utilities.}}\sphinxbfcode{\sphinxupquote{get\_close\_atoms}}}{\emph{\DUrole{n}{atoms}}, \emph{\DUrole{n}{cutoff}\DUrole{o}{=}\DUrole{default_value}{0.5}}, \emph{\DUrole{n}{mic}\DUrole{o}{=}\DUrole{default_value}{False}}, \emph{\DUrole{n}{delete}\DUrole{o}{=}\DUrole{default_value}{False}}}{}
Get a list of close atoms and delete one set of them if requested.
Identify all atoms that lie within the cutoff radius of each other.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{atoms}} (\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atoms object}}) \textendash{} Accept any ase.Atoms object. No need to be built\sphinxhyphen{}in.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{cutoff}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 0.5}}) \textendash{} The cutoff radius. Two atoms are too close if the distance between
them is less than this cutoff

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{mic}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to apply minimum image convention. Remember to set
mic=True for periodic systems.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{delete}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to delete one set of the close atoms.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{atoms\_too\_close() (in module acat.utilities)@\spxentry{atoms\_too\_close()}\spxextra{in module acat.utilities}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{utilities:acat.utilities.atoms_too_close}}\pysiglinewithargsret{\sphinxcode{\sphinxupquote{acat.utilities.}}\sphinxbfcode{\sphinxupquote{atoms\_too\_close}}}{\emph{\DUrole{n}{atoms}}, \emph{\DUrole{n}{cutoff}\DUrole{o}{=}\DUrole{default_value}{0.5}}, \emph{\DUrole{n}{mic}\DUrole{o}{=}\DUrole{default_value}{False}}}{}
Check if there are atoms that are too close to each other.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{atoms}} (\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atoms object}}) \textendash{} Accept any ase.Atoms object. No need to be built\sphinxhyphen{}in.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{cutoff}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 0.5}}) \textendash{} The cutoff radius. Two atoms are too close if the distance between
them is less than this cutoff

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{mic}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to apply minimum image convention. Remember to set
mic=True for periodic systems.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{atoms\_too\_close\_after\_addition() (in module acat.utilities)@\spxentry{atoms\_too\_close\_after\_addition()}\spxextra{in module acat.utilities}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{utilities:acat.utilities.atoms_too_close_after_addition}}\pysiglinewithargsret{\sphinxcode{\sphinxupquote{acat.utilities.}}\sphinxbfcode{\sphinxupquote{atoms\_too\_close\_after\_addition}}}{\emph{\DUrole{n}{atoms}}, \emph{\DUrole{n}{n\_added}}, \emph{\DUrole{n}{cutoff}\DUrole{o}{=}\DUrole{default_value}{1.5}}, \emph{\DUrole{n}{mic}\DUrole{o}{=}\DUrole{default_value}{False}}}{}
Check if there are atoms that are too close to each other after
adding some new atoms.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{atoms}} (\sphinxstyleliteralemphasis{\sphinxupquote{ase.Atoms object}}) \textendash{} Accept any ase.Atoms object. No need to be built\sphinxhyphen{}in.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{n\_added}} (\sphinxstyleliteralemphasis{\sphinxupquote{int}}) \textendash{} Number of newly added atoms.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{cutoff}} (\sphinxstyleliteralemphasis{\sphinxupquote{float}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default 1.5}}) \textendash{} The cutoff radius. Two atoms are too close if the distance between
them is less than this cutoff

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{mic}} (\sphinxstyleliteralemphasis{\sphinxupquote{bool}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default False}}) \textendash{} Whether to apply minimum image convention. Remember to set
mic=True for periodic systems.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{get\_angle\_between() (in module acat.utilities)@\spxentry{get\_angle\_between()}\spxextra{in module acat.utilities}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{utilities:acat.utilities.get_angle_between}}\pysiglinewithargsret{\sphinxcode{\sphinxupquote{acat.utilities.}}\sphinxbfcode{\sphinxupquote{get\_angle\_between}}}{\emph{\DUrole{n}{v1}}, \emph{\DUrole{n}{v2}}}{}
Returns the angle in radians between vectors ‘v1’ and ‘v2’.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{v1}} (\sphinxstyleliteralemphasis{\sphinxupquote{numpy.array}}) \textendash{} Vector 1.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{v2}} (\sphinxstyleliteralemphasis{\sphinxupquote{numpy.array}}) \textendash{} Vector 2.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{get\_rejection\_between() (in module acat.utilities)@\spxentry{get\_rejection\_between()}\spxextra{in module acat.utilities}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{utilities:acat.utilities.get_rejection_between}}\pysiglinewithargsret{\sphinxcode{\sphinxupquote{acat.utilities.}}\sphinxbfcode{\sphinxupquote{get\_rejection\_between}}}{\emph{\DUrole{n}{v1}}, \emph{\DUrole{n}{v2}}}{}
Calculate the vector rejection of vector ‘v1’ perpendicular
to vector ‘v2’.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{v1}} (\sphinxstyleliteralemphasis{\sphinxupquote{numpy.array}}) \textendash{} Vector 1.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{v2}} (\sphinxstyleliteralemphasis{\sphinxupquote{numpy.array}}) \textendash{} Vector 2.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{get\_rotation\_matrix() (in module acat.utilities)@\spxentry{get\_rotation\_matrix()}\spxextra{in module acat.utilities}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{utilities:acat.utilities.get_rotation_matrix}}\pysiglinewithargsret{\sphinxcode{\sphinxupquote{acat.utilities.}}\sphinxbfcode{\sphinxupquote{get\_rotation\_matrix}}}{\emph{\DUrole{n}{v1}}, \emph{\DUrole{n}{v2}}}{}
Return the rotation matrix R that rotates unit vector v1 onto
unit vector v2.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{v1}} (\sphinxstyleliteralemphasis{\sphinxupquote{numpy.array}}) \textendash{} Vector 1.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{v2}} (\sphinxstyleliteralemphasis{\sphinxupquote{numpy.array}}) \textendash{} Vector 2.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{get\_rodrigues\_rotation\_matrix() (in module acat.utilities)@\spxentry{get\_rodrigues\_rotation\_matrix()}\spxextra{in module acat.utilities}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{utilities:acat.utilities.get_rodrigues_rotation_matrix}}\pysiglinewithargsret{\sphinxcode{\sphinxupquote{acat.utilities.}}\sphinxbfcode{\sphinxupquote{get\_rodrigues\_rotation\_matrix}}}{\emph{\DUrole{n}{axis}}, \emph{\DUrole{n}{angle}}}{}
Return the Rodrigues rotation matrix associated with
counter\sphinxhyphen{}clockwise rotation about the given axis by an angle.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{axis}} (\sphinxstyleliteralemphasis{\sphinxupquote{numpy.array}}) \textendash{} The axis (vector) to rotate around with.

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{angle}} (\sphinxstyleliteralemphasis{\sphinxupquote{numpy.array}}) \textendash{} The angle (in radians) to rotate around.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}

\index{get\_total\_masses() (in module acat.utilities)@\spxentry{get\_total\_masses()}\spxextra{in module acat.utilities}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{utilities:acat.utilities.get_total_masses}}\pysiglinewithargsret{\sphinxcode{\sphinxupquote{acat.utilities.}}\sphinxbfcode{\sphinxupquote{get\_total\_masses}}}{\emph{\DUrole{n}{symbol}}}{}
Get the total molar mass given the chemical symbol of a
molecule.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode
\sphinxstyleliteralstrong{\sphinxupquote{symbol}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} Chemical symbol of the molecule.

\end{description}\end{quote}

\end{fulllineitems}

\index{string\_fragmentation() (in module acat.utilities)@\spxentry{string\_fragmentation()}\spxextra{in module acat.utilities}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{utilities:acat.utilities.string_fragmentation}}\pysiglinewithargsret{\sphinxcode{\sphinxupquote{acat.utilities.}}\sphinxbfcode{\sphinxupquote{string\_fragmentation}}}{\emph{\DUrole{n}{adsorbate}}}{}
A function for generating a fragment list (list of strings)
from a given adsorbate (string).
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode
\sphinxstyleliteralstrong{\sphinxupquote{adsorbate}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}) \textendash{} The string of the adsorbate molecule.

\end{description}\end{quote}

\end{fulllineitems}

\index{draw\_graph() (in module acat.utilities)@\spxentry{draw\_graph()}\spxextra{in module acat.utilities}}

\begin{fulllineitems}
\phantomsection\label{\detokenize{utilities:acat.utilities.draw_graph}}\pysiglinewithargsret{\sphinxcode{\sphinxupquote{acat.utilities.}}\sphinxbfcode{\sphinxupquote{draw\_graph}}}{\emph{\DUrole{n}{G}}, \emph{\DUrole{n}{savefig}\DUrole{o}{=}\DUrole{default_value}{\textquotesingle{}graph.png\textquotesingle{}}}}{}
Draw the graph using matplotlib.pyplot.
\begin{quote}\begin{description}
\item[{Parameters}] \leavevmode\begin{itemize}
\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{G}} (\sphinxstyleliteralemphasis{\sphinxupquote{networkx.Graph object}}) \textendash{} The graph object

\item {} 
\sphinxstyleliteralstrong{\sphinxupquote{savefig}} (\sphinxstyleliteralemphasis{\sphinxupquote{str}}\sphinxstyleliteralemphasis{\sphinxupquote{, }}\sphinxstyleliteralemphasis{\sphinxupquote{default \textquotesingle{}graph.png\textquotesingle{}}}) \textendash{} The name of the figure to be saved.

\end{itemize}

\end{description}\end{quote}

\end{fulllineitems}



\section{Notes}
\label{\detokenize{notes:notes}}\label{\detokenize{notes::doc}}\begin{enumerate}
\sphinxsetlistlabels{\arabic}{enumi}{enumii}{}{.}%
\item {} 
Some functions distinguishes between nanoparticle and surface slabs based on periodic boundary condition (PBC). Therefore, before using the code, it is recommended to \sphinxstylestrong{set all directions as non\sphinxhyphen{}periodic for nanoparticles and at least one direction periodic for surface slabs, and also add vacuum layers to all non\sphinxhyphen{}periodic directions. Note that the half\sphinxhyphen{}top half\sphinxhyphen{}bottom slab model is not supported by the code. Please make sure the slab is a unity.}

\item {} 
ACAT uses a regularized adsorbate string representation. In each adsorbate string, \sphinxstylestrong{the first element must set to the bonded atom. If the adsorbate is multi\sphinxhyphen{}dentate, the order follows the order of their atomic numbers. Hydrogen should always follow the element that it bonds to.} For example, water should be written as ‘OH2’, hydrogen peroxide should be written as ‘OHOH’, ethanol should be written as ‘CH3CH2OH’, formyl should be written as ‘CHO’, hydroxymethylidyne should be written as ‘COH’. If the string is not supported by the code, it will return the ase.build.molecule instead, which could result in a weird orientation. If the string is not supported by this code nor ASE, you can make your own molecules in the adsorbate\_molecule function in acat.settings.

\item {} 
There is a bug that causes \sphinxcode{\sphinxupquote{get\_neighbor\_site\_list()}} to not return the correct neighbor site indices with ASE version \textless{}= 3.18. This is most likely due to shuffling of indices in some ASE functions, which is solved after the release of ASE 3.19.0.

\end{enumerate}


\chapter{Indices and tables}
\label{\detokenize{index:indices-and-tables}}\begin{itemize}
\item {} 
\DUrole{xref,std,std-ref}{genindex}

\item {} 
\DUrole{xref,std,std-ref}{modindex}

\item {} 
\DUrole{xref,std,std-ref}{search}

\end{itemize}


\renewcommand{\indexname}{Python Module Index}
\begin{sphinxtheindex}
\let\bigletter\sphinxstyleindexlettergroup
\bigletter{a}
\item\relax\sphinxstyleindexentry{acat.adsorbate\_coverage}\sphinxstyleindexpageref{modules:\detokenize{module-acat.adsorbate_coverage}}
\item\relax\sphinxstyleindexentry{acat.adsorption\_sites}\sphinxstyleindexpageref{modules:\detokenize{module-acat.adsorption_sites}}
\item\relax\sphinxstyleindexentry{acat.build.actions}\sphinxstyleindexpageref{build:\detokenize{module-acat.build.actions}}
\item\relax\sphinxstyleindexentry{acat.build.orderings}\sphinxstyleindexpageref{build:\detokenize{module-acat.build.orderings}}
\item\relax\sphinxstyleindexentry{acat.build.patterns}\sphinxstyleindexpageref{build:\detokenize{module-acat.build.patterns}}
\item\relax\sphinxstyleindexentry{acat.ga.adsorbate\_operators}\sphinxstyleindexpageref{ga:\detokenize{module-acat.ga.adsorbate_operators}}
\item\relax\sphinxstyleindexentry{acat.utilities}\sphinxstyleindexpageref{utilities:\detokenize{module-acat.utilities}}
\end{sphinxtheindex}

\renewcommand{\indexname}{Index}
\printindex
\end{document}