External Terms#

Additional pair interaction terms can be used to improve training convergence. EwaldTerm can be used to add an electrostatic pair term based on the Ewald summation, as implemented in pymatgen, and is particularly useful in ionic systems such as oxides.

Ewald Term#

The Ewald term can be used to add an Ewald electrostatic pair term to the fit. The Ewald sum is the sum of a reciprocal term, a real term, and a point term. It is possible to fit to the full sum or any of the individual terms.

Implementation of EwaldTerm.

Provides the functionality to fit an Ewald term as an additional feature in a cluster expansion as proposed refs below to improve convergence of expansions of ionic materials. Chapter 4.6 of W.D. Richard’s thesis. W. D. Richards, et al., Energy Environ. Sci., 2016, 9, 3272–3278

class EwaldTerm(eta=None, real_space_cut=None, recip_space_cut=None, use_term='total')[source]#

Bases: MSONable

EwaldTerm class that can be added to a ClusterSubspace.

This class can be used as an external term added to a ClusterSubspace using the add_external_term method. Doing so introduces Ewald electrostatic interaction energies as an additional feature to include when fitting a cluster expansion. This usually helps to increase accuracy and reduce complexity (number of orbits) required to fit ionic materials.

Initialize EwaldTerm.

Input parameters are standard input parameters to pymatgen EwaldSummation. See class documentation for more information.

Parameters:

  • eta (float) – parameter to override the EwaldSummation default screening parameter eta. If not given it is determined automatically.

  • real_space_cut (float) – real space cutoff radius. Determined automatically if not given.

  • recip_space_cut (float) – reciprocal space cutoff radius. Determined automatically if not given.

  • use_term (str) – optional the Ewald expansion term to use as an additional term in the expansion. Options are total, real, reciprocal, point.

as_dict()[source]#

Get Json-serialization dict representation.

Returns:

MSONable dict

Return type:

dict

ewald_term_options = ('total', 'real', 'reciprocal', 'point')#
classmethod from_dict(d)[source]#

Create EwaldTerm from MSONable dict.

(Over-kill here since only EwaldSummation params are saved).

get_ewald_matrix(ewald_summation)[source]#

Get the corresponding Ewald matrix for the given term to use.

Parameters:

ewald_summation (EwaldSummation) – pymatgen EwaldSummation instance

Returns:

ewald matrix for corresponding term

Return type:

ndarray

static get_ewald_occu(occu, num_ewald_sites, ewald_inds)[source]#

Get the Ewald indices from a given encoded occupancy string.

The Ewald indices indicate matrix elements (i.e. species) corresponding to the given occupancy.

Parameters:

  • occu (ndarray) – encoded occupancy string

  • num_ewald_sites (int) – number of total Ewald sites. This is the size of the Ewald matrix, the sum of the size of all site spaces for all sites in the cell.

  • ewald_inds (ndarray) – Ewald indices for the corresponding species in the occupancy array.

Returns:

indices of species in ewald matrix

Return type:

ndarray

static get_ewald_structure(structure)[source]#

Get the structure and site indices contributing to Ewald summation.

Creates a structure with overlapping sites for each species in the corresponding site space. This is used to construct single Ewald matrices for all possible configurations. The ewald_inds array is a 2D array where the first element is the index of the site in a supercell and the second is the encoded species occupancy

Removes vacancies and the corresponding indices to those sites from the original structure.

Parameters:

structure – Structure to compute Ewald interaction energy from

Returns:

(Structure, array) structure and indices of sites

Return type:

tuple

value_from_occupancy(occu, structure)[source]#

Obtain the Ewald interaction energy.

The size of the given structure is in terms of prims. The computed electrostatic interactions do not include the charged cell energy (which is only important for charged structures). See the pymatgen EwaldSummation class for further details. For more details also look at https://doi.org/10.1017/CBO9780511805769.034 (pp. 499–511).

Parameters:

  • occu (array) – occupation vector for the given structure

  • structure (Structure) – pymatgen Structure for which to compute the electrostatic interactions

Returns:

float