Core components#

Orbit list#

class icet.core.orbit_list.OrbitList(structure, cutoffs, chemical_symbols, symprec, position_tolerance, fractional_position_tolerance)[source]#

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.

An orbit list is immutable once constructed. The operations that edit it, without_orbits(), without_inactive_orbits(), and with_merged_orbits(), each return a new orbit list.

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 (list[int] | None) – Indices of the orbits for which counts are requested. By default all orbits are 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_orbit(self: _icet._OrbitList, index: SupportsInt | SupportsIndex) → _icet.Orbit#

Returns the orbit at the given position in the orbit list.

Parameters:: index (int) – Index of the orbit.
Returns:: The orbit at the given index.
Return type:: Orbit

get_supercell_orbit_list(structure, fractional_position_tolerance)#

Returns the orbit list for a supercell structure. For the interface see OrbitList.

Parameters:

structure (Atoms) – Atomic structure.
fractional_position_tolerance (float) – Tolerance applied when comparing positions in fractional coordinates.

Return type:

_OrbitList

property matrix_of_equivalent_positions#

Matrix of symmetry equivalent sites used to construct the orbit list (copy).

Type:: list[list[LatticeSite]]

property orbits#

Orbits of this orbit list.

Type:: list[Orbit]

property primitive_structure#: A copy of the primitive structure to which the lattice sites in the orbits are referenced to.

with_merged_orbits(self: _icet._OrbitList, groups: collections.abc.Mapping[SupportsInt | SupportsIndex, collections.abc.Sequence[SupportsInt | SupportsIndex]]) → _icet._OrbitList#

Returns a new orbit list in which each group of orbits has been merged into its first member and the merged-away orbits have been left out. This orbit list is not modified.

The removal of the merged-away orbits is part of this operation. An orbit list in which orbits had been merged but not removed would still match the length of any orbit list derived from this one while no longer corresponding to it orbit by orbit, which is an inconsistency that no length check could detect.

Parameters:: groups (dict[int, list[int]]) – Maps the index of an orbit to the indices of the orbits that are to be merged into it. All indices refer to this orbit list.
Returns:: The new orbit list.
Return type:: _OrbitList

without_inactive_orbits(self: _icet._OrbitList) → _icet._OrbitList#

Returns a new orbit list from which the orbits with inactive sites have been left out. A site is inactive when only one species is allowed on it. This orbit list is not modified.

Returns:: The new orbit list.
Return type:: _OrbitList

without_orbits(self: _icet._OrbitList, indices: collections.abc.Sequence[SupportsInt | SupportsIndex]) → _icet._OrbitList#

Returns a new orbit list from which the orbits with the given indices have been left out. This orbit list is not modified.

Parameters:: indices (list[int]) – Indices of the orbits to leave out, in any order.
Returns:: The new orbit list.
Return type:: _OrbitList

Sublattices#

class icet.core.sublattices.Sublattices(allowed_species, primitive_structure, structure, fractional_position_tolerance)[source]#

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

Sites that allow the same set of species form one sublattice. The sublattices are labeled with letters in the order of their species, with the active sublattices, on which more than one species is allowed, before the inactive ones. The class behaves as a sequence of Sublattice objects.

Note

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

Parameters:

allowed_species (list[list[str]]) – Species allowed on each site of the primitive structure, such as the chemical symbols of a cluster space.
primitive_structure (Atoms) – Primitive structure the allowed species refer to.
structure (Atoms) – Supercell the sublattices are based on.
fractional_position_tolerance (float) – Tolerance applied when comparing positions in fractional coordinates.

property active_sublattices: list[Sublattice]#: Sublattices on which more than one species is allowed.

property allowed_species: list[list[str]]#: Species allowed on each sublattice, in the order of the sublattices (copy).

assert_occupation_is_allowed(chemical_symbols)[source]#

Checks that an occupation of the supercell respects the sublattices.

Parameters:: chemical_symbols (list[str]) – Chemical symbol on each site of the supercell.
Raises:: ValueError – If the number of symbols differs from the number of sites, or if a site carries a species that is not allowed on its sublattice.
Return type:: None

get_allowed_numbers_on_site(index)[source]#

Returns the atomic numbers of the species allowed on a site.

Parameters:: index (int) – Index of the site in the supercell.
Return type:: list[int]

get_allowed_symbols_on_site(index)[source]#

Returns the chemical symbols of the species allowed on a site.

Parameters:: index (int) – Index of the site in the supercell.
Return type:: list[str]

get_sublattice_index_from_site_index(index)[source]#

Returns the index of the sublattice a site belongs to.

Parameters:: index (int) – Index of the site in the supercell.
Return type:: int

get_sublattice_sites(index)[source]#

Returns the indices of the sites that belong to a sublattice.

Parameters:: index (int) – Index of the sublattice.
Return type:: list[int]

property inactive_sublattices: list[Sublattice]#: Sublattices on which only one species is allowed.

class icet.core.sublattices.Sublattice(chemical_symbols, indices, symbol)[source]#

This class stores and provides information about one sublattice, which is a set of sites of a supercell that allow the same species. A sublattice is specific to a supercell, since it holds site indices.

Note

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

Parameters:

chemical_symbols (list[str]) – Species allowed on this sublattice.
indices (list[int]) – Indices of the sites of the supercell that belong to this sublattice.
symbol (str) – Letter that labels the sublattice, such as 'A' or 'B'.

property atomic_numbers: list[int]#: Atomic numbers of the species allowed on this sublattice (copy).

property chemical_symbols: list[str]#: Species allowed on this sublattice (copy).

property indices: list[int]#: Indices of the sites that belong to this sublattice (copy).

property symbol: str#: Letter that labels the sublattice, such as 'A' or 'B'.

Variable transformations#

icet.tools.variable_transformation.get_transformation_matrix(structure, full_orbit_list)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

The configuration manager owns the configuration a Monte Carlo simulation samples.

It holds the occupation vector together with the sites each species occupies on each sublattice, which lets it propose swap and flip trial moves in constant time through get_swapped_state() and get_flip_state(). Ensembles apply accepted moves through update_occupations() and restore a saved configuration through set_occupations(). The manager also enforces the neighbor constraint set through set_neighbor_sites_to_avoid().

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 that define the allowed occupations of the sites.

get_flip_state(sublattice_index, allowed_species=None, allowed_sites=None)[source]#

Proposes a flip of a randomly chosen site to another species allowed on it.

The configuration itself is not changed.

Parameters:

sublattice_index (int) – Index of the sublattice from which to pick the site.
allowed_species (list[int] | None) – Atomic numbers of the species that may take part in the flip. By default all species on the sublattice.
allowed_sites (list[int] | None) – Indices of the sites that may take part in the flip. By default all sites on the sublattice.

Returns:

The index of the site and its occupation after the flip.

Return type:

tuple[int, int]

get_occupations_on_sublattice(sublattice_index)[source]#

Returns the occupations on one sublattice by atomic number.

Parameters:: sublattice_index (int) – Index of the sublattice.
Return type:: list[int]

get_swapped_state(sublattice_index, allowed_species=None, allowed_sites=None)[source]#

Proposes a swap of two randomly chosen sites with different species.

The two sites are drawn from one sublattice, so the proposed configuration respects the allowed occupations of the sites. The configuration itself is not changed.

Parameters:

sublattice_index (int) – Index of the sublattice from which to pick the sites.
allowed_species (list[int] | None) – Atomic numbers of the species that may take part in the swap. By default all species on the sublattice.
allowed_sites (list[int] | None) – Indices of the sites that may take part in the swap. By default all sites on the sublattice.

Returns:

The indices of the two sites and their occupations after the swap.

Return type:

tuple[list[int], list[int]]

Raises:

SwapNotPossibleError – If the sublattice holds no site to swap or only one species.

is_constraint_violated(sites, species)[source]#

Checks whether a trial move would violate the neighbor constraint.

The constraint forbids two sites that appear in each other’s avoid list from being occupied at the same time, where a site counts as occupied when it is not held by a vacancy. Provided that the current configuration satisfies the constraint, only the sites touched by the trial move can introduce a violation, which is what allows this check to be local.

Parameters:

sites (list[int]) – Indices of the sites that the trial move would change.
species (list[int]) – Occupations by atomic number that the trial move would assign to sites.

Return type:

bool

Returns:

True if applying the trial move would place occupants on two sites
that appear in each other’s avoid list, False otherwise.
Always False when no constraint is set.

is_swap_possible(sublattice_index, allowed_species=None)[source]#

Returns whether a swap trial move is possible on a sublattice, which requires at least two different species on it.

Parameters:

sublattice_index (int) – Index of the sublattice.
allowed_species (list[int] | None) – Atomic numbers of the species that may take part in the swap. By default all species on the sublattice.

Return type:

bool

property neighbor_sites_to_avoid: dict[int, list[int]] | None#: Sites that must not be occupied simultaneously, keyed by site index (copy).

property occupations: ndarray#: Occupation vector of the configuration (copy).

set_neighbor_sites_to_avoid(neighbor_sites_to_avoid)[source]#

Sets the neighbor constraint that trial moves have to respect.

The constraint belongs to the configuration instead of to an individual trial move, so that it cannot apply to some moves and not to others. It governs the trial steps of ThermodynamicBaseEnsemble that carry out a swap, an SGC flip or a VCSGC flip. Thermodynamic integration, Wang-Landau sampling and target cluster vector annealing generate their trial moves differently and are not subject to it.

Rejecting a trial move leaves the proposal unchanged and therefore symmetric, so the acceptance criterion stays exact and the constraint introduces no bias of its own. That alone does not guarantee that the whole constrained space is sampled: a restrictive mapping can leave the allowed configurations disconnected under the available trial moves, in which case the simulation only reaches the part it starts in.

Parameters:: neighbor_sites_to_avoid (dict[int, list[int]] | None) – Sites that must not be occupied simultaneously, keyed by site index. Sites that are absent from the mapping are unconstrained. None removes the constraint. The mapping is copied, so changing it afterwards does not change the constraint.
Raises:: ValueError – If the constraint is not usable, see validate_constraint().
Return type:: None

set_occupations(occupations)[source]#

Replaces the occupations of the whole configuration.

This is the absolute counterpart of update_occupations(), which expresses a change relative to the current configuration. It is what a restart needs, since restoring a saved configuration is not the acceptance of a move. The occupations are checked before anything changes, so a rejected input leaves the configuration as it was.

Parameters:: occupations (list[int]) – New occupations by atomic number, one per site of the configuration.
Raises:: ValueError – If the length does not match the configuration, or if a species is not allowed on the site it is given for.
Return type:: None

property structure: Atoms#: Atomic structure associated with configuration (copy).

property sublattices: Sublattices#: Sublattices of the configuration.

update_occupations(sites, species)[source]#

Changes the occupations of the given sites.

The whole update is checked before any of it is applied, so a rejected update leaves the configuration as it was.

Parameters:

sites (list[int]) – Indices of the sites to change.
species (list[int]) – New occupations of those sites by atomic number.

Raises:

ValueError – If the two lists differ in length, if a site appears twice, if a site index is out of range, or if a species is not allowed on the site it is given for.

Return type:

None

validate_constraint(neighbor_sites_to_avoid)[source]#

Checks that a neighbor constraint is usable for the current configuration.

The configuration has to satisfy the constraint already. Each trial move is only checked against the sites it touches, which assumes that the rest of the configuration satisfies the constraint. A violating configuration is not stuck, since emptying an offending site is never rejected, but the sampling is biased until the violations happen to be cleared.

Parameters:: neighbor_sites_to_avoid (dict[int, list[int]]) – Sites that must not be occupied simultaneously, keyed by site index. Sites that are absent from the mapping are unconstrained.
Raises:: ValueError – If the constraint refers to a site that does not exist, if a site is listed against itself, if it is not symmetric, or if the current configuration already violates it.
Return type:: None