Calculators#

ClusterExpansionCalculator#

class mchammer.calculators.ClusterExpansionCalculator(structure, cluster_expansion, name='Cluster Expansion Calculator', scaling=None, use_local_energy_calculator=True)[source]#

A ClusterExpansionCalculator object enables the efficient calculation of properties described by a cluster expansion. It is specific to a particular supercell and is commonly used when setting up a Monte Carlo simulation, see Ensembles.

Cluster expansions, for example of the energy, typically yield property values per site. A Monte Carlo simulation, however, considers changes in the total energy of the system. The default behavior is therefore to multiply the output of the cluster expansion by the number of sites. This behavior can be changed via the scaling keyword parameter.

The calculator holds the occupations of its supercell and evaluates property changes against them. They are taken from the structure it is constructed with, so every site of that structure has to carry a species the cluster expansion defines. The held occupations change only through an explicit accept. The ensemble calls set_occupations() once at setup and accept_change() for every accepted move, and calculate_change() leaves the held occupations untouched, including when it raises. The compiled calculator behind this class, reachable as cpp_calc, states its thread contract in its own docstring. The section on the calculator interface describes how to drive the calculator without an ensemble.

Parameters:

  • structure (Atoms) – Structure for which to set up the calculator.

  • cluster_expansion (ClusterExpansion) – Cluster expansion from which to build the calculator.

  • name (str) – Human-readable identifier for this calculator.

  • scaling (float | None) – Scaling factor applied to the property value predicted by the cluster expansion. By default the number of sites in structure.

  • use_local_energy_calculator (bool) – Evaluate changes using only the local environment of the changed sites. This is generally much faster than evaluating the whole supercell twice. Unless you know what you are doing do not set this option to False.

Example

The following snippet sets up a calculator for an Ising-like cluster expansion and evaluates the energy of a configuration as well as the energy change of a swap. The parameters are made up to keep the example self-contained:

>>> from ase.build import bulk
>>> from icet import ClusterExpansion, ClusterSpace
>>> from mchammer.calculators import ClusterExpansionCalculator

>>> # prepare cluster expansion
>>> prim = bulk('Au')
>>> cs = ClusterSpace(prim, cutoffs=[4.3], chemical_symbols=['Ag', 'Au'])
>>> ce = ClusterExpansion(cs, [0, 0, 0.1, -0.02])

>>> # prepare a configuration
>>> structure = prim.repeat(3)
>>> for k in range(5):
...     structure[k].symbol = 'Ag'

>>> # the total energy of the configuration the calculator holds
>>> calculator = ClusterExpansionCalculator(structure, ce)
>>> occupations = structure.get_atomic_numbers()
>>> energy = calculator.calculate_total(occupations=occupations)

>>> # the energy change of swapping the species on sites 0 and 10,
>>> # which leaves the held configuration where it is
>>> sites = [0, 10]
>>> new_species = [occupations[10], occupations[0]]
>>> change = calculator.calculate_change(sites=sites,
...                                      current_occupations=occupations,
...                                      new_site_occupations=new_species)

>>> # adopt the swap
>>> calculator.accept_change(sites=sites, species=new_species)
accept_change(*, sites=None, species=None)[source]#

Advances the configuration this calculator describes by an accepted change, which is the only way it moves during a simulation.

Calling this method without stating which change was accepted raises instead of doing nothing. Silently not advancing would leave the calculator evaluating every subsequent change against a stale configuration, with no error anywhere. An empty list of sites is a legitimate empty change and does nothing.

Parameters:

  • sites (list[int] | None) – Indices of the sites whose occupations changed.

  • species (list[int] | None) – New occupations by atomic number on those sites.

Raises:

  • TypeError – If sites or species is omitted.

  • ValueError – If sites and species differ in length.

Return type:

None

calculate_change(*, sites, current_occupations, new_site_occupations)[source]#

Returns the change of the property caused by changing the occupations of the sites in sites.

The local calculation evaluates the change against the occupations this calculator holds, which the ensemble keeps equal to current_occupations through set_occupations() and accept_change(). When calling this method outside an ensemble, call set_occupations() first. The held occupations are left untouched, including when this method raises.

Parameters:

  • sites (list[int]) – Indices of the sites whose occupations change.

  • current_occupations (list[int]) – The entire occupation vector by atomic number before the change. The local calculation does not read it. It is part of the calculator interface and is used when use_local_energy_calculator is False.

  • new_site_occupations (list[int]) – Atomic numbers after the change on the sites in sites.

Raises:

ValueError – If sites and new_site_occupations differ in length.

Return type:

float

calculate_total(*, occupations)[source]#

Returns the total property value of a configuration.

The configuration is given in full and is not adopted, so the configuration the calculator holds is left where it is.

Parameters:

occupations (list[int]) – The entire occupation vector by atomic number.

Return type:

float

property cluster_expansion: ClusterExpansion#

Cluster expansion this calculator evaluates (copy).

The orbits whose parameters are all zero are left out of it, see ClusterExpansion.prune().

It is handed out as a copy, so the calculator cannot be steered through it. Editing its parameters, pruning it, or editing a value nested in its metadata changes neither what the calculator computes nor what the next read of this property reports.

set_occupations(occupations)[source]#

Sets the configuration this calculator describes.

An ensemble calls this method once at setup and keeps the calculator in step afterwards through accept_change().

Parameters:

occupations (list[int]) – The entire occupation vector by atomic number.

Return type:

None

property sublattices: Sublattices#

Sublattices of the structure the calculator describes.

ConstituentStrainCalculator#

class mchammer.calculators.ConstituentStrainCalculator(constituent_strain, cluster_expansion, name='Constituent Strain Calculator', scaling=None)[source]#

Calculator for a cluster expansion combined with constituent strain.

The property this calculator evaluates is the sum of the cluster expansion energy and the constituent strain energy, both for the whole supercell. The constituent strain energy is evaluated by the ConstituentStrain object, which describes the strain energy of a coherent structure in reciprocal space. The section on constituent strain describes the method and shows the calculator in a Monte Carlo simulation.

The ConstituentStrain object stores one structure factor per k-point and reads it as the value before a change instead of recomputing it. The calculator therefore rebuilds the structure factors in set_occupations() and advances them in accept_change(). Only changes of a single site can be evaluated, so the calculator works with ensembles that flip one site per trial step, such as SemiGrandCanonicalEnsemble and VCSGCEnsemble.

Parameters:

  • constituent_strain (ConstituentStrain) – Object that defines the strain energy of the system. Its supercell is the structure the calculator is set up for, so it has to be the one the Monte Carlo simulation samples.

  • cluster_expansion (ClusterExpansion) – Cluster expansion from which to build the calculator.

  • name (str) – Human-readable identifier for this calculator.

  • scaling (float | None) – Scaling factor applied to the property value predicted by the cluster expansion. By default the number of sites in the supercell.

accept_change(*, sites=None, species=None)[source]#

Advances the configuration held by the underlying cluster expansion calculator and informs the ConstituentStrain object that the most recent change was accepted, so that it stores the new structure factors.

Parameters:

  • sites (list[int] | None) – Indices of the sites whose occupations changed.

  • species (list[int] | None) – New occupations by atomic number on those sites.

Return type:

None

calculate_change(*, sites, current_occupations, new_site_occupations)[source]#

Returns the change of the property caused by changing the occupation of the site in sites.

Parameters:

  • sites (list[int]) – Index of the site whose occupation changes, as a list of length one.

  • current_occupations (list[int]) – The entire occupation vector by atomic number before the change.

  • new_site_occupations (list[int]) – Atomic number after the change, as a list of length one.

Raises:

NotImplementedError – If more than one site changes.

Return type:

float

calculate_total(*, occupations)[source]#

Returns the total property value of a configuration, which is the sum of the cluster expansion energy and the constituent strain energy of the whole supercell.

The configuration is given in full and is not adopted, so the configuration the calculator holds is left where it is.

Parameters:

occupations (ndarray) – The entire occupation vector by atomic number.

Return type:

float

property cluster_expansion: ClusterExpansion#

Cluster expansion this calculator evaluates (copy).

The orbits whose parameters are all zero are left out of it, see ClusterExpansion.prune().

It is handed out as a copy, so the calculator cannot be steered through it. Editing its parameters, pruning it, or editing a value nested in its metadata changes neither what the calculator computes nor what the next read of this property reports.

set_occupations(occupations)[source]#

Sets the configuration this calculator describes, both for the underlying cluster expansion calculator and for the ConstituentStrain object.

Parameters:

occupations (list[int]) – The entire occupation vector by atomic number.

Return type:

None

property sublattices: Sublattices#

Sublattices of the structure the calculator describes.

TargetVectorCalculator#

class mchammer.calculators.TargetVectorCalculator(structure, cluster_space, target_vector, weights=None, optimality_weight=1.0, optimality_tol=1e-05, name='Target vector calculator')[source]#

A TargetVectorCalculator evaluates the similarity between a structure and a target cluster vector. It is used by TargetClusterVectorAnnealing to generate special quasirandom structures and other structures with a prescribed cluster vector, see the section on special quasirandom structures. Such a comparison can be carried out in many ways, and this implementation follows the measure proposed by van de Walle et al. in Calphad 42, 13 (2013) [WalTiwJon13]. Specifically, the objective function \(Q\) is calculated as

\[Q = - \omega L + \sum_{\alpha} \left||\Gamma_{\alpha} - \Gamma^{\text{target}}_{\alpha}\right||.\]

Here, \(\Gamma_{\alpha}\) are the components of the cluster vector and \(\Gamma^\text{target}_{\alpha}\) the corresponding target values. The factor \(\omega\) is the radius of the largest pair cluster such that all clusters with the same or smaller radii have \(\Gamma_{\alpha} - \Gamma^\text{target}_{\alpha} = 0\).

The objective function depends on the whole cluster vector, so the calculator evaluates full configurations only and does not implement calculate_change().

Parameters:

  • structure (Atoms) – Structure for which to set up the calculator.

  • cluster_space (ClusterSpace) – Cluster space from which to build the calculator.

  • target_vector (list[float]) – Cluster vector that the cluster vector of a configuration is compared to.

  • weights (list[float] | None) – Weight of each component in the comparison of the cluster vectors. By default 1.0 for all components.

  • optimality_weight (float) – Factor \(L\). A high value favors a complete series of optimal cluster correlations for the smallest pairs.

  • optimality_tol (float) – Tolerance for determining whether a component matches the target exactly, used in conjunction with \(L\).

  • name (str) – Human-readable identifier for this calculator.

accept_change(*, sites=None, species=None)#

Advances the configuration a stateful calculator describes by an accepted change.

An ensemble calls this method for every accepted trial move. Calculators that hold no configuration state ignore this.

Parameters:

  • sites (list[int] | None) – Indices of the sites whose occupations changed.

  • species (list[int] | None) – New occupations by atomic number on those sites.

Return type:

None

calculate_change(*, sites, current_occupations, new_site_occupations)[source]#

Not implemented, since the objective function is not a sum of local contributions. Evaluate the changed configuration with calculate_total() instead.

Raises:

NotImplementedError – Always.

Return type:

float

calculate_total(*, occupations)[source]#

Returns the objective function \(Q\) of a configuration.

Parameters:

occupations (list[int]) – The entire occupation vector by atomic number.

Return type:

float

set_occupations(occupations)#

Sets the configuration a stateful calculator describes.

The occupations are given in full, so anything the calculator derives from the configuration has to be rebuilt from them. An ensemble calls this method once when it starts and again when it restarts from a data container. Calculators that hold no configuration state ignore this.

Parameters:

occupations (list[int]) – The entire occupation vector by atomic number.

Return type:

None

property sublattices: Sublattices#

Sublattices of the structure the calculator describes.

mchammer.calculators.compare_cluster_vectors(cv_1, cv_2, as_list, weights=None, optimality_weight=1.0, tol=1e-05)[source]#

Returns a measure of the similarity between two cluster vectors.

The measure is the objective function \(Q\) defined in the docstring of TargetVectorCalculator. A smaller value means a closer match.

Parameters:

  • cv_1 (ndarray) – First cluster vector.

  • cv_2 (ndarray) – Second cluster vector.

  • as_list (list[OrderedDict]) – Orbit data as obtained from ClusterSpace.as_list.

  • weights (list[float] | None) – Weight assigned to each cluster vector element. By default 1.0 for all elements.

  • optimality_weight (float) – Quantity \(L\) in [WalTiwJon13]. By default 1.0.

  • tol (float) – Numerical tolerance for determining whether two elements are equal. By default 1e-5.

Return type:

float