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:

# Clusters
CO_p = pz.Cluster( species=[CO_s], energy=-1.3 )
O_p = pz.Cluster( species=[O_s], 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:

 # 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, 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 (gas species are ignored) 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.
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

composition()¶: Returns a dictionary containing the number of atoms of each kind.

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(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=[], fileName=None, surface_species=None)¶

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.
fileName – Path to the zacros file name to load the cluster expansion, typically energetics_input.dat
surface_species – Surface species. It is required if the option fileName was used.

__fromZacrosFile(fileName, surface_species)¶: Creates a Mechanism from a Zacros input file energetics_input.dat

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 – Iterable with the clusters to extend the cluster expansion.

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

find(label)¶: Returns the list of clusters where the substring label is found in the clusters’ label

find_one(label)¶: Returns the first cluster where the substring label is found in the cluster’s label