Core

OrbitList

class core.orbit_list.OrbitList(structure, cutoffs, chemical_symbols, symprec, position_tolerance, fractional_position_tolerance)

The orbit list object handles an internal list of orbits.

An orbit has a list of equivalent sites with the restriction that at least one site is in the cell of the primitive structure.

Note

As a user you will usually not interact directly with objects of this type.

Parameters:

• structure (Atoms) – This structure will be used to construct a primitive structure on which all the lattice sites in the orbits are based.

• cutoffs (List[float]) – The i-th element of this list is the cutoff for orbits with order i+2.

• chemical_symbols (List[List[str]]) –

  List of chemical symbols, each of which must map to an element of the periodic table.

  The outer list must be the same length as the structure object and chemical_symbols[i] will correspond to the allowed species on lattice site i.

• symprec (float) – Tolerance imposed when analyzing the symmetry using spglib.

• position_tolerance (float) – Tolerance applied when comparing positions in Cartesian coordinates.

• fractional_position_tolerance (float) – Tolerance applied when comparing positions in fractional coordinates.

get_cluster_counts(structure, fractional_position_tolerance, orbit_indices=None)

Counts all clusters in a structure by finding their local orbit list.

Parameters:

• structure (Atoms) – Structure for which to count clusters. This structure needs to be commensurate with the structure this orbit list is based on.

• fractional_position_tolerance (float) – Tolerance applied when comparing positions in fractional coordinates.

• orbit_indices (Optional[List[int]]) – Indices of orbits, for which counts are requested; if None all orbits will be counted.

Return type:

Dict[int, Counter]

Returns:

Dictionary, the keys of which are orbit indices and the values cluster counts. The latter are themselves dicts, with tuples of chemical symbols as keys and the number of such clusters as values.

get_supercell_orbit_list(structure, fractional_position_tolerance)

Returns the orbit list for a supercell structure.

Parameters:

• structure (Atoms) – Atomic structure.

• fractional_position_tolerance (float) – Tolerance applied when comparing positions in fractional coordinates.

property primitive_structure

A copy of the primitive structure to which the lattice sites in the orbits are referenced to.

Orbit

class core.orbit.Orbit

This class handles an orbit. An orbit consists of one or more clusters that are equivalent by the symmetries of the underlying structure. One of these clusters (the first in the list of clusters handed to the constructor) will be treated as the “representative cluster”. All clusters need to have sites that are permuted in a manner consistent with the representative cluster. This is the responsibility of the user when constructing an orbit. Normally, however, orbits are constructed internally, in which case the user does not need to think about this permutation.

Parameters:

• structure (Structure) – Structure from which this orbit is derived.

• clusters (List[List[LatticeSite]]) – A list of groups of sites, where each group is a cluster.

• allowed_permutations (List[List[int]]) – A list of the permutations allowed for this orbit. For example, if [0, 2, 1] is in this list, the multi-component vector [0, 1, 0] is the same as [0, 0, 1].

property all_distances: list[list[float]]

Distances between all sites in all clusters.

property all_positions: list[list[ndarray[Any, dtype[float]]]]

Positions of all sites in all clusters.

property all_site_offsets: list[list[ndarray[Any, dtype[int]]]]

Unit cell offsets of all sites in all clusters.

property all_sites: list[list[int]]

The site indices of all sites in all clusters.

property allowed_permutations

List of equivalent permutations for this orbit. If this orbit is a triplet and the permutation [0, 2, 1] exists this means that the lattice sites [s1, s2, s3] are equivalent to [s1, s3, s2]. This will have the effect that for a ternary cluster expansion the multi-component vector (0, 1, 0) will not be considered separately since it is equivalent to (0, 0, 1).

property clusters

List of the clusters in this orbit.

property distances: list[float]

Distances between all sites in the representative cluster.

get_cluster_counts()

Count clusters in this orbit for a structure.

Parameters:

• structure (Structure) – Input structure.

• site_index_for_double_counting_correction (int) – Avoid double counting clusters containing this index. Default: -1, i.e., no such correction.

property order

Number of sites in the representative cluster.

property positions: list[ndarray[Any, dtype[float]]]

Positions of all sites in the representative cluster.

property radius

Radius of the representative cluster.

property representative_cluster

Cluster to which all other symmetry equivalent clusters can be related.

property site_offsets: list[ndarray[Any, dtype[int]]]

Unit cell offsets of all sites in the representative cluster.

property sites: list[int]

The indices of all sites in the representative cluster.

translate()

Translate the clusters in the orbit by a constant offset.

Parameters:

offset (List[int]) – Offset in multiples of the cell vectors of the structure used to define the clusters in this orbit (typically the primitive structure).

Sublattices

class icet.core.sublattices.Sublattices(allowed_species, primitive_structure, structure, fractional_position_tolerance)

This class stores and provides information about the sublattices of a structure.

Note

As a user you will usually not interact directly with objects of this type.

Parameters:

• allowed_species (List[List[str]]) – List of the allowed species on each site of the primitve structure. For example this can be the chemical_symbols from a cluster space.

• primitive_structure (Atoms) – The primitive structure the allowed species reference to.

• structure (Atoms) – The structure that the sublattices will be based on.

• fractional_position_tolerance (float) – Tolerance applied when comparing positions in fractional coordinates.

property active_sublattices: List[Sublattice]

List of the active sublattices.

property allowed_species: List[List[str]]

Lists of the allowed species on each sublattice in order.

assert_occupation_is_allowed(chemical_symbols)

Asserts that the current occupation obeys the sublattices.

get_allowed_numbers_on_site(index)

Returns the allowed atomic numbers on the site.

Parameters:

index (int) – Lattice site index.

Return type:

List[int]

get_allowed_symbols_on_site(index)

Returns the allowed symbols on the site.

Parameters:

index (int) – Lattice site index.

Return type:

List[str]

get_sublattice_index_from_site_index(index)

Returns the index of the sublattice the index in the structure belongs to.

Parameters:

index (int) – Index of site in the structure.

Return type:

int

get_sublattice_sites(index)

Returns the sites that belong to the sublattice with the corresponding index.

Parameters:

index (int) – Index of the sublattice.

Return type:

List[int]

property inactive_sublattices: List[Sublattice]

List of the active sublattices.

class icet.core.sublattices.Sublattice(chemical_symbols, indices, symbol)

This class stores and provides information about a specific sublattice. A sublattice is always supercell specific since it contains lattice indices.

Note

As a user you will usually not interact directly with objects of this type.

Parameters:

• chemical_symbols (List[str]) – The allowed species on this sublattice.

• indices (List[int]) – The lattice indices the sublattice consists of.

• symbol (str) – String used to mark the sublattice.

property symbol

Symbol representation of sublattice, i.e. A, B, C, etc.

Variable transformations

icet.tools.variable_transformation.get_transformation_matrix(structure, full_orbit_list)

Determines the matrix that transforms the cluster functions in the form of spin variables, \(\sigma_i\in\{-1,1\}\), to their binary equivalents, \(x_i\in\{0,1\}\). The form is obtained by performing the substitution (\(\sigma_i=1-2x_i\)) in the cluster expansion expression of the predicted property (commonly the energy).

Parameters:

• structure (Atoms) – Atomic configuration.

• full_orbit_list (OrbitList) – Full orbit list.

Return type:

ndarray

icet.tools.variable_transformation.transform_parameters(structure, full_orbit_list, parameters)

Transforms the list of parameters, obtained using cluster functions in the form of of spin variables, \(\sigma_i\in\{-1,1\}\), to their equivalents for the case of binary variables, \(x_i\in\{0,1\}\).

Parameters:

• structure (Atoms) – Atomic configuration.

• full_orbit_list (OrbitList) – Full orbit list.

• parameters (ndarray) – Parameter vector (spin variables).

Return type:

ndarray

Constituent strain

class icet.tools.constituent_strain.KPoint(kpt, multiplicity, structure_factor, strain_energy_function, damping)

Class for handling each k point in a supercell separately.

Parameters:

• kpt (ndarray) – k-point coordinates.

• multiplicity (float) – Multiplicity of this k-point.

• structure_factor (float) – Current structure associated with this k-point.

• strain_energy_function (Callable[[float, List[float]], float]) – Function that takes a concentration and a list of parameters and returns strain energy.

• damping (float) – Damping at this k-point in units of Ångstrom.

icet.tools.constituent_strain_helper_functions.redlich_kister(x, *coeffs)

Evaluate Redlich-Kister polynomial with coefficients coeff at point(s) x.

Parameters:

• x (float) – Point in interval [0, 1] where polynomial should be evaluated.

• coeffs (float) – Redlich-Kister coefficients, coeffs[0] (1 - 2x)^0 x (1 - x) + coeffs[1] * (1 - 2x)^1 x (1 - x) + ...

Return type:

float

icet.tools.constituent_strain_helper_functions.redlich_kister_vector(x, *coeffs)

Evaluate Redlich-Kister polynomial with coefficients coeff at points(s) x.

Parameters:

• x (ndarray) – Array of points in interval [0, 1] where polynomial should be evaluated.

• coeffs (float) – Redlich-Kister coefficients, coeffs[0] (1 - 2x)^0 x (1 - x) + coeffs[1] * (1 - 2x)^1 x (1 - x) + ...

Return type:

float

Configuration manager

class mchammer.ConfigurationManager(structure, sublattices)

The ConfigurationManager owns and handles information pertaining to a configuration being sampled in a Monte Carlo simulation.

Note

As a user you will usually not interact directly with objects of this type.

Parameters:

• structure (Atoms) – Configuration to be handled.

• sublattices (Sublattices) – Sublattices used to define allowed occupations and handle related information.

get_flip_state(sublattice_index, allowed_species=None, allowed_sites=None)

Returns a site index and a new species for the site.

Parameters:

• sublattice_index (int) – Index of sublattice from which to pick a site.

• allowed_species (Optional[List[int]]) – List of atomic numbers for allowed species.

• allowed_sites (Optional[List[int]]) – List of indices for allowed sites.

Return type:

Tuple[int, int]

get_occupations_on_sublattice(sublattice_index)

Returns the occupations on one sublattice.

Parameters:

sublattice_index (int) – Sublattice by index for which the occupations should be returned.

Return type:

List[int]

get_swapped_state(sublattice_index, allowed_species=None, allowed_sites=None)

Returns two random sites (first element of tuple) and their occupation after a swap (second element of tuple). The new configuration will obey the occupation constraints associated with the ConfigurationManager object.

Parameters:

• sublattice_index (int) – Sublattice by index from which to pick sites.

• allowed_species (Optional[List[int]]) – List of atomic numbers for allowed species.

• allowed_sites (Optional[List[int]]) – List of indices for allowed sites.

Return type:

Tuple[List[int], List[int]]

is_swap_possible(sublattice_index, allowed_species=None)

Checks if a swap trial move is possible on a specific sublattice.

Parameters:

• sublattice_index (int) – Index of sublattice to be checked.

• allowed_species (Optional[List[int]]) – List of atomic numbers for allowed species.

Return type:

bool

property occupations: ndarray

Occupation vector of the configuration (copy).

property structure: Atoms

Atomic structure associated with configuration (copy).

property sublattices: Sublattices

Sublattices of the configuration.

update_occupations(sites, species)

Updates the occupation vector of the configuration being sampled. This will change the state in both the configuration in the calculator and the configuration manager.

Parameters:

• sites (List[int]) – Indices of sites of the configuration to change.

• species (List[int]) – New occupations by atomic number.

Return type:

None