Cluster Specs

Description

Cluster specifications define which orbits of clusters should be used by CASM in multiple contexts. It is represented by CASM internally using the ClusterSpecs class and its subclasses.

The following methods are implemented for generating orbits of clusters from input files. The particular context determines which methods are allowed:

"periodic_max_length": For generating orbits of clusters with the translational symmetry of the prim lattice and using the prim factor group.
"local_max_length": For generating orbits in the local environment of a particular “phenomenal cluster” using a subgroup of the prim factor group that leaves the phenomenal cluster invariant.

Project files

This format is used for the cluster_specs attribute of the bspecs.json file.

JSON Attributes List

Cluster Specs (“cluster_specs”) attributes:

Name	Description	Format
`method`	Cluster orbit generating method	string
`params`	Method parameters	dict

Parameters for the "periodic_max_length" method:

Name	Description	Format
`orbit_branch_specs`	Orbit branch cutoff distances	dict
`orbit_specs`	Particular orbits to include	array of [IntegralClusterOrbitGenerator]

Parameters for the "local_max_length" method:

Name	Description	Format
`generating_group`	Specifies the point group used to generate local clusters	array of int
`orbit_branch_specs`	Orbit branch cutoff distances	dict
`orbit_specs`	Particular orbits to include	array of [IntegralClusterOrbitGenerator]
`phenomenal`	Phenomenal cluster about which local clusters are generated	[IntegralClusterOrbitGenerator]

JSON Attributes Description

ClusterSpecs JSON object

Terminology:

An “orbit” is the set of all equivalent objects under some generating symmetry group. It is a general term, and in different contexts within CASM could be used for orbits of clusters, orbits of functions, or orbits of other objects.
There are infinitely many orbits of 2-site clusters, corresponding to 1st nearest neighbor basis sites, 2nd nearest neighbor basis sites, 3rd nearest neighbor basis sites, etc. The same applies to 3-site clusters, 4-site clusters, etc.
The “orbit tree” of all cluster orbits is made up of “orbit branches” where each “branch” of the “orbit tree” is made up of all orbits of clusters with the same number of sites. For example, the n=2 “orbit branch” consists of all orbits of 2-site clusters, the n=3 “orbit branch” consists of all orbits of 3-site clusters, etc.

Note on the cluster orbit generation method:

Cluster orbits are generated recursively, meaning 2-site cluster orbits are generated by attempting to add sites to 1-site cluster orbits, 3-site cluster orbits are generated by attempting to add sites to 2-site cluster orbits, etc. This means that some (n+1)-site cluster orbits that would otherwise be included may not be if the (n+1) orbit branch max_length is greater than the n-site orbit branch max_length.

method: string (required)

Specify which cluster orbit generating method will be used. One of:
- "periodic_max_length": Clusters differing by a lattice translation are considered equivalent. Cluster generation is truncated by specifying the maximum distance between sites in a cluster for 2-site, 3-site, etc. clusters. The site clusters comprising the asymmetric unit of the prim are always included. This is the appropriate method for cluster expansions of crystal properties.
- "local_max_length": Clusters differing by a lattice translation are considered distinct. Cluster generation is truncated by specifying for 2-site, 3-site, etc. clusters the radius of sites from “phenomenal” cluster include, and the maximum distance between sites in a cluster. This is the appropriate method for cluster expansions of properties associated with the “phenomenal” cluster.
params: dict (required)

Specifies parameters for the method selected by method. Options depend on the method chosen. See:
- "periodic_max_length"
- "local_max_length"

Parameters for the `"periodic_max_length"` method

orbit_branch_specs: dict (optional, default={})

Cluster generation is truncated by specifying the maximum distance between sites in a cluster for each orbit branch (i.e. 2-site, 3-site, etc. clusters). The null cluster orbit and the 1-site clusters are always included.
Example:
```
"orbit_branch_specs": {
    "2": { "max_length": 10.0 },
    "3": { "max_length": 8.0 }
}
```
orbit_specs: array of IntegralClusterOrbitGenerator (optional, default=[])

An array of clusters which are used to generate and include orbits of clusters whether or not they meet the orbit_branch_specs truncation criteria. See the IntegralClusterOrbitGenerator JSON input format.

Parameters for the `"local_max_length"` method

generating_group: array of int (required)

An array of indices into the prim factor group specifying the invariant group of the “phenomenal” cluster which should be used to generate local cluster orbits. Given the factor group operations indicated, the translational components of the symmetry operations are determined which leave the cluster sites invariant.

The generating group is typically generated by some other method for use here and not determined manually. For example, the indices for the point group that leaves cluster sites invariant can be obtained by: (1) using casm bset to generate a basis set using the periodic_max_length method and then (2) finding the invariant_group of the desired phenomenal cluster printed for prototype clusters in the clust.json file.
orbit_branch_specs: dict (optional, default={})

All sites within cutoff_radius distance of any site in the phenomenal cluster are considered candidates for inclusion in clusters of a particular orbit branch. Cluster generation is truncated by specifying the maximum distance between sites in a cluster for each orbit branch. The max_length parameter is not necessary for 1-site clusters and ignored if present. The null cluster orbit is always included.
Example:
```
"orbit_branch_specs": {
    "1": { "cutoff_radius": 6.0 },
    "2": { "max_length": 9.0, "cutoff_radius": 6.0 },
    "3": { "max_length": 8.0, "cutoff_radius": 6.0 }
}
```
orbit_specs: array of IntegralClusterOrbitGenerator (optional, default=[])

An array of clusters which are used to generate and include orbits of clusters whether or not they meet the orbit_branch_specs truncation criteria. See the IntegralClusterOrbitGenerator JSON input format.
phenomenal: IntegralClusterOrbitGenerator (required)

The “phenomenal” cluster about which local clusters are generated. See the IntegralClusterOrbitGenerator JSON input format for cluster input ("include_subclusters" is not allowed).
Example:
```
{
    "coordinate_mode" : "Integral",
    "sites" : [
        [ 0, 0, 0, 0 ],
        [ 0, 1, 0, 0 ]]
}
```

Examples

Example 1) Periodic clusters

{
  "method": "periodic_max_length",
  "params": {
    "orbit_branch_specs": {
      "2" : {"max_length" : 6.},
      "3" : {"max_length" : 3.}
    },
    "orbit_specs": [
      {
        "coordinate_mode" : "Integral",
        "sites" : [
          [ 0, 0, 0, 0 ],
          [ 1, 0, 0, 0 ],
          [ 0, 1, 0, 0 ],
          [ 1, 1, 0, 0 ]],
        "include_subclusters": true
      }
    ]
  }
}

Example 2) Local clusters

{
  "method": "local_max_length",
  "params": {
    "phenomenal": {
      "coordinate_mode": "Integral",
      "sites": [
        [ 1, 0, 0, 0 ],
        [ 0, 1, 0, 0 ]
      ]
    },
    "generating_group": [ 0, 7, 11, 17, 18, 19, 26, 27, 28, 33, 37, 47 ],
    "orbit_branch_specs": {
      "1" : {"cutoff_radius": 6.},
      "2" : {"cutoff_radius": 3., "max_length" : 3.}
    }
  }
}