Core components#

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 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 active sublattices.

property allowed_species: list[list[str]]#

Lists of the allowed species on each sublattice in order.

assert_occupation_is_allowed(chemical_symbols)[source]#

Asserts that the current occupation obeys the sublattices.

get_allowed_numbers_on_site(index)[source]#

Returns the allowed atomic numbers on the site.

Parameters:

index (int) – Lattice site index.

Return type:

list[int]

get_allowed_symbols_on_site(index)[source]#

Returns the allowed symbols on the site.

Parameters:

index (int) – Lattice site index.

Return type:

list[str]

get_sublattice_index_from_site_index(index)[source]#

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

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 inactive sublattices.

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

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

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 (list[int] | None) – List of atomic numbers for allowed species.

  • allowed_sites (list[int] | None) – List of indices for allowed sites.

Return type:

tuple[int, int]

get_occupations_on_sublattice(sublattice_index)[source]#

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

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 (list[int] | None) – List of atomic numbers for allowed species.

  • allowed_sites (list[int] | None) – List of indices for allowed sites.

Return type:

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

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]#

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

Parameters:

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

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

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 rather than 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]#

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

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