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
