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 for a particular (supercell) structure and commonly employed when setting up a Monte Carlo simulation, see Ensembles.

Cluster expansions, e.g., of the energy, typically yield property values per site. When running a Monte Carlo simulation one, 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 synchronization contract with the ensemble machinery is that 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() is guaranteed to leave 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.

Parameters:

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

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

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

  • scaling (float | None) – Scaling factor applied to the property value predicted by the cluster expansion.

  • use_local_energy_calculator (bool) – Evaluate energy changes using only the local environment; this method is generally much faster. Unless you know what you are doing do not set this option to False.

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

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

Calling this method without stating which change was accepted raises rather than doing nothing, because 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 (atomic numbers) on those sites.

Return type:

None

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

Calculates and returns the sum of the contributions to the property due to the sites specified in sites.

The local calculation evaluates the change against the occupations this calculator holds, which the ensemble machinery keeps equal to current_occupations through set_occupations() and accept_change(); when calling this method outside an ensemble, call set_occupations() first.

Parameters:

  • sites (list[int]) – Indices of sites at which occupations will be changed.

  • current_occupations (list[int]) – Entire occupation vector (atomic numbers) before change. The local calculation does not read it; it exists for the calculator interface and for the fallback path below.

  • new_site_occupations (list[int]) – Atomic numbers after change at the sites defined by sites.

Raises:

ValueError – If sites and new_site_occupations differ in length.

Return type:

float

calculate_total(*, occupations)[source]#

Calculates and returns the total property value of the current configuration.

Parameters:

occupations (list[int]) – The entire occupation vector (i.e., list of atomic species).

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 once at setup and keeps the calculator in step afterwards through accept_change(); see the class docstring for the synchronization contract.

Parameters:

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

Return type:

None

property sublattices: Sublattices#

Sublattices of the calculator structure.

ConstituentStrainCalculator#

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

Calculator for handling cluster expansions with strain.

Parameters:

  • constituent_strain (ConstituentStrain) – ConstituentStrain object defining the strain energy properties of the system. The supercell used to create this object should correspond to the one used when running Monte Carlo simulations with this calculator

  • cluster_expansion (ClusterExpansion) – Cluster expansion based on which to set up ClusterExpansionCalculator.

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

  • scaling (float | None) – Scaling factor applied to the property value predicted by the cluster expansion.

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, such that the new structure factor can be stored.

Parameters:

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

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

Return type:

None

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

Calculates and returns the sum of the contributions to the property due to the sites specified in sites.

Parameters:

  • sites (list[int]) – Indices of sites at which occupations will be changed.

  • current_occupations (list[int]) – Entire occupation vector (atomic numbers) before change.

  • new_site_occupations (list[int]) – Atomic numbers after change at the sites defined by sites.

Return type:

float

calculate_total(*, occupations)[source]#

Calculates and returns the total property value of the current configuration.

Parameters:

occupations (ndarray) – The entire occupation vector (i.e., an array of atomic numbers as integers).

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 (atomic numbers).

Return type:

None

property sublattices: Sublattices#

Sublattices of the calculator structure.

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 enables evaluation of the similarity between a structure and a target cluster vector. 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 components in 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\).

Parameters:

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

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

  • target_vector (list[float]) – Vector to which any vector will be compared.

  • weights (list[float] | None) – Weighting of each component in cluster vector comparison. By default set to 1.0 for all components.

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

  • optimality_tol (float) – Tolerance for determining whether a perfect match has been achieved (used in conjunction with \(L\)).

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

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

Some calculators depend on the state of the occupations, in which case they need to be informed when an accepted change advances the configuration.

Parameters:

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

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

Return type:

None

calculate_total(occupations)[source]#

Calculates and returns the similarity value \(Q\) of the current configuration.

Parameters:

occupations (list[int]) – The entire occupation vector (i.e., list of atomic species).

Return type:

float

set_occupations(occupations)#

Sets the configuration a stateful calculator describes. Calculators that hold no configuration state ignore this.

Parameters:

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

Return type:

None

property sublattices: Sublattices#

Sublattices of the calculators structure.

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

Calculate a quantity that measures similarity between two cluster vecors.

Parameters:

  • cv_1 (ndarray) – Cluster vector 1.

  • cv_2 (ndarray) – Cluster vector 2.

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

  • weights (list[float] | None) – Weight assigned to each cluster vector element.

  • optimality_weight (float) – Wuantity \(L\) in [WalTiwJon13] (see mchammer.calculators.TargetVectorCalculator).

  • tol (float) – Numerical tolerance for determining whether two elements are equal.

Return type:

float