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 2site clusters, corresponding to 1st nearest neighbor basis sites, 2nd nearest neighbor basis sites, 3rd nearest neighbor basis sites, etc. The same applies to 3site clusters, 4site 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 2site clusters, the n=3 “orbit branch” consists of all orbits of 3site clusters, etc.
Note on the cluster orbit generation method:
 Cluster orbits are generated recursively, meaning 2site cluster orbits are generated by attempting to add sites to 1site cluster orbits, 3site cluster orbits are generated by attempting to add sites to 2site 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 nsite orbit branchmax_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 2site, 3site, 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 2site, 3site, 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 themethod
chosen. See:
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. 2site, 3site, etc. clusters). The null cluster orbit and the 1site 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 theperiodic_max_length
method and then (2) finding theinvariant_group
of the desired phenomenal cluster printed for prototype clusters in theclust.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. Themax_length
parameter is not necessary for 1site 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.}
}
}
}