# Enumeration of Independent Clusters and Cluster Function Forms

Using the cluster-search interface, symmetrically nonequivalent clusters, element configurations on clusters, and cluster-function configurations can be enumerated.
These clusters are used to compute cluster (correlation) functions and to count the number of clusters distinguished by their elemental species.

The input parameters for performing a cluster search include the maximum cluster order, the cutoff distance for each cluster body, and the primitive lattice representation of the target lattice.


The maximum cluster order is specified by the `--order` option.
Cutoff distances are provided using the `--cutoffs` option, listed in order for pairs, triplets, and so on.
The number of cutoff distances must be equal to the maximum cluster order minus one.
The primitive lattice is supplied using the `-p` or `--poscar` option in POSCAR format.


## Search of Clusters and Binary Cluster Functions on an FCC Lattice

In the following example, unique clusters and cluster-function forms for a binary system on an FCC lattice are enumerated.

```shell
# > cat fcc-primitive
# Generated by pyclupan
# 4.0
#   0.000000000  0.5000000000  0.5000000000
#   0.5000000000  0.000000000  0.5000000000
#   0.5000000000  0.5000000000  0.000000000
#  Ag
#   1
# Direct
#   0.000000000 0.000000000 0.000000000

> pyclupan-cluster -p fcc-primitive -e 0 1
> pyclupan-cluster -p fcc-primitive -e 0 1 --order 4 --cutoffs 6.0 6.0 5.0
> pyclupan-cluster -p fcc-primitive -e 0 1 --order 5 --cutoffs 6.0 6.0 5.0 4.0
```
The option `-e 0 1` indicates that binary elements 0 and 1 are considered on the (first) sublattice of the FCC lattice.

## Search of Clusters and Ternary Cluster Functions on an FCC Lattice

The following example is used to enumerate unique clusters and cluster-function forms for a ternary system on an FCC lattice.

```shell
> pyclupan-cluster -p fcc-primitive -e 0 1 2 --order 4 --cutoffs 6.0 6.0 6.0
```
The option `-e 0 1 2` indicates that ternary elements 0, 1, and 2 are considered on the
FCC lattice.

## Search of Clusters and Cluster Functions on a Lattice with Multiple Sublattices
In the following example, binary nonequivalent clusters on the anion sites are enumerated in the cubic perovskite structure.
The elements Sr (index 0) and Ti (index 1) are fixed, and configurations of two elements (indices 2 and 3) are considered on the third sublattice.
The order of the `-e` options is important for controlling the sublattices on which configurations are considered.

```shell
# > cat perovskite-unitcell
# Perovskite unit cell
# 1.0
#   4.000000000  0.000000000  0.000000000
#   0.000000000  4.000000000  0.000000000
#   0.000000000  0.000000000  4.000000000
#   Sr Ti O
#   1  1  3
# Direct
#   0.000000000 0.000000000 0.000000000
#   0.5000000000 0.5000000000 0.5000000000
#   0.5000000000 0.5000000000 0.000000000
#   0.000000000 0.5000000000 0.5000000000
#   0.5000000000 0.000000000 0.5000000000

> pyclupan-cluster -p perovskite-unitcell -e 0 -e 1 -e 2 3 --order 4 --cutoffs 6.0 6.0 6.0
```
In the next example, ternary configurations on the cation A and B sublattices and binary configurations on the anion sublattice are considered to enumerate clusters for the perovskite structure.
Configurations involving three elements (indices 0, 1, and 2) on the first and second sublattices, and two elements (indices 3 and 4) on the third sublattice, are included.

```shell
> pyclupan-cluster -p perovskite-unitcell -e 0 1 2 -e 0 1 2 -e 3 4 --order 4 --cutoffs 6.0 6.0 6.0
```
