# Cluster space¶

class icet.ClusterSpace(atoms, cutoffs, chemical_symbols)[source]

This class provides functionality for generating and maintaining cluster spaces.

Note: In icet all ase.Atoms objects must have periodic boundary conditions. When carrying out cluster-expansions for surfaces and nano-particles it is therefore recommended to embed the atoms object in a vacuum and use periodic boundary conditions. This can be done using e.g., ase.Atoms.center().

Parameters: atoms (ase.Atoms) – atomic configuration cutoffs (list(float)) – cutoff radii per order that define the cluster space Cutoffs are specified in units of Angstrom and refer to the longest distance between two atoms in the cluster. The first element refers to pairs, the second to triplets, the third to quadruplets, and so on. cutoffs=[7.0, 4.5] thus implies that all pairs distanced 7 A or less will be included, as well as all triplets among which the longest distance is no longer than 4.5 A. chemical_symbols (list(str) or list(list(str))) – list of chemical symbols, each of which must map to an element of the periodic table If a list of chemical symbols is provided, all sites on the lattice will have the same allowed occupations as the input list. If a list of list of chemical symbols is provided then the outer list must be the same length as the atoms object and chemical_symbols[i] will correspond to the allowed species on lattice site i.

Examples

The following snippets illustrate several common situations:

from ase.build import bulk
from icet import ClusterSpace

# AgPd alloy with pairs up to 7.0 A and triplets up to 4.5 A
prim = bulk('Ag')
cs = ClusterSpace(atoms=prim, cutoffs=[7.0, 4.5],
chemical_symbols=[['Ag', 'Pd']])
print(cs)

# (Mg,Zn)O alloy on rocksalt lattice with pairs up to 8.0 A
prim = bulk('MgO', crystalstructure='rocksalt', a=6.0)
cs = ClusterSpace(atoms=prim, cutoffs=[8.0],
chemical_symbols=[['Mg', 'Zn'], ['O']])
print(cs)

# (Ga,Al)(As,Sb) alloy with pairs, triplets, and quadruplets
prim = bulk('GaAs', crystalstructure='zincblende', a=6.5)
cs = ClusterSpace(atoms=prim, cutoffs=[7.0, 6.0, 5.0],
chemical_symbols=[['Ga', 'Al'], ['As', 'Sb']])
print(cs)

# PdCuAu alloy with pairs and triplets
prim = bulk('Pd')
cs = ClusterSpace(atoms=prim, cutoffs=[7.0, 5.0],
chemical_symbols=[['Au', 'Cu', 'Pd']])
print(cs)

assert_structure_compatability(structure, vol_tol=1e-05)[source]

Raises if structure is not compatible with ClusterSpace.

TODO: Add check for if structure is relaxed

Parameters: structure (Atoms) – structure to check if compatible with ClusterSpace None
chemical_symbols

Chemical species considered

Return type: List[List[str]]
copy()[source]

Returns copy of ClusterSpace instance.

cutoffs

Cutoffs for the different n-body clusters. Each cutoff radii (in Angstroms) defines the largest inter-atomic distance in each cluster

Return type: List[float]
evaluate_cluster_function()

Evaluates value of a cluster function.

get_chemical_symbols()

Returns list of species associated with cluster space as chemical symbols.

get_cluster_space_info()
get_cluster_space_size()
get_cluster_vector(atoms)[source]

Returns the cluster vector for a structure.

Parameters: atoms (Atoms) – atomic configuration the cluster vector
get_cutoffs()
get_multi_component_vector_permutations()
get_number_of_allowed_species_by_site()
get_number_of_orbits_by_order()[source]

Returns the number of orbits by order.

Return type: OrderedDict an ordered dictionary where keys and values represent order and number of orbits, respectively
get_orbit()
get_possible_orbit_decorations(orbit_index)[source]

Returns possible decorations on the orbit

Parameters: orbit_index (int) – List[List[str]]
get_sublattices(structure)[source]

Returns the sublattices of the input structure

Parameters: structure (Atoms) – structure the sublattices are based on Sublattices
is_supercell_self_correlated(atoms)[source]

Check whether an atoms object self-interacts via periodic boundary conditions.

Parameters: atoms (Atoms) – An atoms object to check self-interaction for If True, the atoms object self-interacts via periodic boundary conditions, otherwise False. bool
orbit_data

list of orbits with information regarding order, radius, multiplicity etc

Return type: List[dict]
orbit_list

Orbit list that defines the cluster in the cluster space

primitive_structure

Primitive structure on which the cluster space is based

Return type: Atoms
print_overview(print_threshold=None, print_minimum=10)[source]

Print an overview of the cluster space in terms of the orbits (order, radius, multiplicity etc).

Parameters: print_threshold (Optional[int]) – if the number of orbits exceeds this number print dots print_minimum (int) – number of lines printed from the top and the bottom of the orbit list if print_threshold is exceeded None
static read(filename)[source]

Parameters: filename (str) – name of file from which to read cluster space
species_maps
write(filename)[source]

Saves cluster space to a file.

Parameters: filename (str) – name of file to which to write None

## Supplementary functions¶

cluster_space.get_singlet_info(return_cluster_space=False)

Retrieves information concerning the singlets in the input structure.

Parameters: atoms (Atoms) – atomic configuration return_cluster_space (bool) – if True return the cluster space created during the process list of dicts – each dictionary in the list represents one orbit ClusterSpace object (optional) – cluster space created during the process
cluster_space.view_singlets(to_primitive=False)

Visualize singlets in a structure using the ASE graphical user interface.

Parameters: atoms (Atoms) – atomic configuration to_primitive (bool) – if True the input structure will be reduced to its primitive unit cell before processing