Cluster space¶
Setting up a cluster space¶
The cluster space serves as a basis for cluster expansions. Setting up a clusterspace object is commonly done via
>>> from icet import ClusterSpace
>>> from ase.build import bulk
>>> primitive_structure = bulk('Si')
>>> cs = ClusterSpace(primitive_structure, cutoffs=[7.0, 5.0], chemical_symbols=['Si', 'Ge'])
The cutoffs are set up to include pairs with an interatomic distance smaller than 7 Å and triplets for which all pair-wise interatomic distances are smaller than 5 Å. Here, Si and Ge are allowed to occupy the reference lattice.
Sublattices¶
A cluster space can also be constructed with multiple sublattices. Consider for example a rocksalt lattice, on which we want to allow mixing of Na and Li on the Na sublattice and Cl and F on the Cl sublattices. This can be achived by
>>> from ase.build import bulk
>>> atoms = bulk('NaCl', 'rocksalt', a=4.0)
>>> chemical_symbols = [['Na', 'Li'], ['Cl', 'F']]
>>> cs = ClusterSpace(atoms, [7.0, 5.0], chemical_symbols)
where chemical_symbols
now specifies which species are allowed
for each lattice site in atoms.
Inactive sites¶
The sublattice functionality also allows one to have inactive sites. For example, if we consider the system above but would like to keep the Cl lattice fixed it can be achived via
>>> chemical_symbols = [['Na', 'Li'], ['Cl']]
>>> cs = ClusterSpace(atoms, [7.0, 5.0], chemical_symbols)
2D systems¶
icet requires input structures to have periodic boundary conditions (PBCs). In order to treat two-dimensional systems, or more generally without PBCs in at least one direction, one has to surround the prototype structure with vacuum and then apply PBCs in all directions. This can easily be achived with the ASE functions
>>> from ase.build import surface
>>> atoms = surface('Cu', (1,1,1), layers=7)
which creates ase atoms object without PBC in the z-direction. The structure can be modified to have PBC in the z-direction with vacuum via
>>> atoms.pbc = [True, True, True]
>>> atoms.center(vacuum=20, axis=2)
which can now be used to create a cluster space.
Interface¶
- class icet.ClusterSpace(structure: ase.atoms.Atoms, cutoffs: List[float], chemical_symbols: Union[List[str], List[List[str]]], symprec: float = 1e-05, position_tolerance: Optional[float] = None)[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 nanoparticles it is therefore recommended to surround the structure with vacuum and use periodic boundary conditions. This can be done using e.g.,ase.Atoms.center()
.- Parameters
structure (ase.Atoms) – atomic structure
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 structure object and
chemical_symbols[i]
will correspond to the allowed species on lattice sitei
.symprec (float) – tolerance imposed when analyzing the symmetry using spglib
position_tolerance (float) – tolerance applied when comparing positions in Cartesian coordinates
Examples
The following snippets illustrate several common situations:
>>> from ase.build import bulk >>> from ase.io import read >>> 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(structure=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(structure=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(structure=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(structure=prim, cutoffs=[7.0, 5.0], ... chemical_symbols=[['Au', 'Cu', 'Pd']]) >>> print(cs)
- assert_structure_compatibility(structure: ase.atoms.Atoms, vol_tol: float = 1e-05) → None[source]¶
Raises error if structure is not compatible with ClusterSpace.
Todo
Add check for if structure is relaxed.
- Parameters
structure – structure to check if compatible with ClusterSpace
- property chemical_symbols: List[List[str]]¶
Species identified by their chemical symbols
- property cutoffs: List[float]¶
Cutoffs for different n-body clusters. The cutoff radius (in Angstroms) defines the largest interatomic distance in a cluster.
- evaluate_cluster_function()¶
Evaluates value of a cluster function.
- property fractional_position_tolerance: float¶
tolerance applied when comparing positions in fractional coordinates
- get_chemical_symbols()¶
Returns list of species associated with cluster space as chemical symbols.
- get_cluster_vector(structure: ase.atoms.Atoms) → numpy.ndarray[source]¶
Returns the cluster vector for a structure.
- Parameters
structure – atomic configuration
- Returns
- Return type
the cluster vector
- get_coordinates_of_representative_cluster(orbit_index: int) → List[Tuple[float]][source]¶
Returns the positions of atoms in the selected orbit
- Parameters
orbit_index – index of the orbit from which to calculate the positions of the atoms
- Returns
- Return type
list of positions of atoms in the selected orbit
- get_cutoffs()¶
- get_multi_component_vector_permutations()¶
- get_multi_component_vectors_by_orbit()¶
- get_number_of_allowed_species_by_site()¶
- get_number_of_orbits_by_order() → collections.OrderedDict[source]¶
Returns the number of orbits by order.
- Returns
an ordered dictionary where keys and values represent order and number
of orbits, respectively
- get_orbit()¶
- get_possible_orbit_occupations(orbit_index: int) → List[List[str]][source]¶
Returns possible occupation of the orbit.
- Parameters
orbit_index –
- get_sublattices(structure: ase.atoms.Atoms) → icet.core.sublattices.Sublattices[source]¶
Returns the sublattices of the input structure.
- Parameters
structure – structure the sublattices are based on
- is_supercell_self_interacting(structure: ase.atoms.Atoms) → bool[source]¶
Checks whether an structure has self-interactions via periodic boundary conditions.
- Parameters
structure – structure to be tested
- Returns
If True, the structure contains self-interactions via periodic boundary conditions, otherwise False.
- Return type
bool
- property orbit_data: List[collections.OrderedDict]¶
list of orbits with information regarding order, radius, multiplicity etc
- property orbit_list¶
Orbit list that defines the cluster in the cluster space
- property position_tolerance: float¶
tolerance applied when comparing positions in Cartesian coordinates
- property primitive_structure: ase.atoms.Atoms¶
Primitive structure on which cluster space is based
- print_overview(print_threshold: Optional[int] = None, print_minimum: int = 10) → None[source]¶
Print an overview of the cluster space in terms of the orbits (order, radius, multiplicity etc).
- Parameters
print_threshold – if the number of orbits exceeds this number print dots
print_minimum – number of lines printed from the top and the bottom of the orbit list if print_threshold is exceeded
- static read(filename: str)[source]¶
Reads cluster space from filename.
- Parameters
filename – name of file from which to read cluster space
- property space_group: str¶
space group of the primitive structure in international notion (via spglib)
- property species_maps¶
- property symprec: float¶
tolerance imposed when analyzing the symmetry using spglib