Domain

Implementation of SiteSpace and functions to get spaces and allowed species.

Implementation functions to generate lists of site spaces and allowed species for a given disordered structure.

A site space is made up of the allowed species and their concentrations including special species such as vacancies. A site spaces makes up the domain of a site function and many site spaces make up the space of configurations.

class SiteSpace(composition)

Bases: Mapping, Hashable, MSONable

Represents a site space.

A site spaces is a set of allowed species at a site and their corresponding measure (composition in the disordered state).

This class is somewhat similar to pymatgen Composition. However a SiteSpace must always have a total composition = 1 since vacancies are explicitly included as species. A sorted order of the included species is also kept to ensure a consistent encoding when creating basis functions. Vacancies are always the last species. Key errors are raised for species not in the site space.

Initialize a site space.

Parameters:

composition (Composition) – Composition object that specifies the site space.

as_dict()

Get MSONable dict representation.

Return type:

dict

property codes

Return range of species (not necessarily sub-lattice encodings).

property composition

Return the underlying composition.

classmethod from_dict(d)

Create a SiteSpace from dict representation.

Return type:

SiteSpace

class Vacancy(symbol='A', oxidation_state=0, spin=None)

Bases: DummySpecies

Wrapper class around DummySpecie to treat vacancies as their own species.

Initialize a Vacancy.

Parameters:

• symbol (str) – an assigned symbol for the vacancy. Strict rules are applied to the choice of the symbol. The vacancy symbol cannot have any part of first two letters that will constitute an Element symbol. Otherwise, a composition may be parsed wrongly. E.g., “X” is fine, but “Vac” is not because Vac contains V, a valid Element.

• oxidation_state (float) – oxidation state for Vacancy. More like the charge of a point defect. Defaults to zero.

• spin (Optional[float]) – Spin associated with Species. Defaults to None.

get_allowed_species(structure)

Get the allowed species for each site in a disordered structure.

This will get all the allowed species for each site in a pymatgen structure. If the site composition does not add to 1, a Vacancy will be appended to the allowed species at that site.

Same as in a site space, the order of the allowed species at each site is important because that implicitly represents the code that will be used when evaluating site basis functions.

Parameters:

structure (Structure) – Structure to determine site spaces from. At least some sites should be disordered, otherwise there is no point in using this.

Returns:

list of allowed Species for each site

Return type:

list of Specie

get_site_spaces(structure, include_measure=False)

Get site spaces for each site in a disordered structure.

Method to obtain the single site spaces for the sites in a structure. The single site spaces are represented by the allowed species for each site and the measure/concentration for disordered sites. The order is important so the species need to be sorted, since that implicitly sets the code/index used to evaluate basis functions.

Vacancies are included in sites where the site element composition does not sum to 1 (i.e. the total occupation is not 1).

Parameters:

• structure (Structure) – Structure to determine site spaces from. At least some sites should be disordered, otherwise there is no point in using this.

• include_measure (bool) – optional if True, will take the site compositions as the site space measure, otherwise a uniform measure is assumed.

Returns:

Allowed species and their corresponding measure.

Return type:

SiteSpace

get_species(obj)

Get specie object.

Wraps pymatgen.core.periodic_table.get_el_sp to be able to catch and return Vacancies when needed.

Parameters:

obj (Element/Specie/str/int) – an arbitrary object. Supported objects are actual Element/Specie objects, integers (representing atomic numbers) or strings (element symbols or species strings).

Return type:

Species | Element | Vacancy | DummySpecies

Returns:

Specie, Element or Vacancy, with a bias for the maximum number of properties that can be determined.

Raises:

ValueError if obj cannot be converted into an Element or Specie. –