# Cluster / Cluster Expansion¶

In a Zacros simulation, clusters (also referred to as patterns) are used as the base of a cluster expansion Hamiltonian for calculating the energy of a given lattice configuration. The energy is calculated based on the number of times that each cluster/pattern is found on the catalytic surface during the simulation. A cluster consists of a collection of binding sites, their connectivity, the surface species bonded to those sites, and the energetic contribution thereof.

For our example (see use case system), the following lines create the two needed clusters; the CO* and O* individual adsorbates:

 1 2 3 4 # Clusters CO_p = pz.Cluster( species=[CO_s], cluster_energy=-1.3 ) O_p = pz.Cluster( species=[O_s], cluster_energy=-2.3 ) print(CO_p) 

which produce the following output:

cluster CO*_0-0
sites 1
lattice_state
1 CO* 1
site_types 1
graph_multiplicity 1
cluster_eng -1.30000e+00
end_cluster


Please consult Zacros’ user guide (\$AMSHOME/scripting/scm/pyzacros/doc/ZacrosManual.pdf) for more details about the specific meaning of the keywords used in the previous lines. Notice that the function print() in line 4 shows the cluster CO_p as it is going to be used in the Zacros input files. The label CO*_0-0 is automatically generated except if the user specifies it by the parameter label in the constructor. This label is used as a unique identifier to avoid duplicates.

Note

pyZacros lists are always numbered from 0 to be consistent with the Python language. However, notice that Zacros input files require all elements should be numbered from 1; pyZacros takes care internally of this transformation.

The ClusterExpansion object is formally a list of clusters and as such inherits all properties of Python lists. The following lines illustrate an example:

 1 2 3  # Cluster Expansion ce = pz.ClusterExpansion([CO_p, O_p]) print(ce) 

which produce the following output:

energetics

cluster CO*_0-0
sites 1
lattice_state
1 CO* 1
site_types 1
graph_multiplicity 1
cluster_eng -1.30000e+00
end_cluster

cluster O*_0-0
sites 1
lattice_state
1 O* 1
site_types 1
graph_multiplicity 1
cluster_eng -2.30000e+00
end_cluster

end_energetics


These lines will be used to create the Zacros input file energetics_input.dat.

## API¶

class Cluster(species, site_types=None, entity_number=None, neighboring=None, multiplicity=1, cluster_energy=0.0, label=None)

Creates a new Cluster object. As in Zacros, each cluster is represented as a graph pattern, consisting of a collection of connected sites onto which surface species can bind. This pattern involves multi/mono-dentate species bound to neighboring sites of different types.

• species – List of species bound to the sites, e.g. [ Species("H*",1), Species("H*",1) ]
• site_types – Specifies the name of the sites in the graph pattern representing the cluster. Notice that the order is essential and it should agree with the species option, e.g. ['fcc','hcp'].
• entity_number – List of the molecular entities ids bound to each site. Notice that the order is essential and should agree with the site_types option. For example, if a bidentate species is bound to sites 1 and 2 ( species=[ Species("H**",2), Species("H**",2) ] ), both of these sites will have the same entity numbers, i.e. entity_number=[0,0]. By default, the list of entity numbers is created by assuming that species with the same symbol belong to the same entity.
• neighboring – Specifies the neighboring between sites, if more than one sites appear in the graph pattern, e.g. [ (0,1) ]
• multiplicity – The multiplicity of the pattern, namely the number of times that the exact same pattern will be counted for a given lattice configuration.
• cluster_energy – The energy contribution of the pattern in eV.
• label – If None, a unique label is generated based on its composition.
label()

Returns the label of the cluster

mass()

Returns the mass of the cluster in Da

gas_species()

Returns the gas species.

surface_species()

Returns the surface species.

site_types_set()

Returns the set of the sites types

replace_site_types_names(site_types_old, site_types_new)

Replaces the site types names

• site_types_old – List of strings containing the old site_types to be replaced
• site_types_new – List of strings containing the new site_types which would replace old site_types_old.
class ClusterExpansion(data=[])

Creates a new ClusterExpansion object which is formally a list of Clusters. It implements all python list operations.

• data – List of Clusters to initially include.
append(item)

Appends a cluster to the end of the sequence. Appends a cluster to the end of the sequence. Notice that duplicate items are not accepted. In case of duplicity, the new cluster is just ignored.

extend(other)

Extend sequence by appending elements from the iterable

• other
insert(i, item)

Inserts item to the list at the i-th index.

• i – The index where item needs to be inserted.
• item – The cluster to be inserted in the list.
gas_species()

Returns the gas species.

surface_species()

Returns the surface species.

site_types_set()

Returns the set of the sites types

replace_site_types_names(site_types_old, site_types_new)

Replaces the site types names

• site_types_old – List of strings containing the old site_types to be replaced
• site_types_new – List of strings containing the new site_types which would replace old site_types_old.