smact Python package

smact Python package#

The core module of smact contains classes which are used as fundamental data types within the smact package, as well as several utility functions. Particular attention is drawn to smact.element_dictionary(), which returns a dictionary of smact.Element objects indexed by their chemical symbols. Generating this dictionary once and then performing lookups is generally the fastest way of accessing element data while enumerating possibilities in chemical space.

Semiconducting Materials from Analogy and Chemical Theory.

A collection of fast screening tools from elemental data

class smact.Element(symbol: str, oxi_states_custom_filepath: str | None = None)[source]#

Bases: object

Collection of standard elemental properties for given element.

Data is drawn from “data/element.txt”, part of the Open Babel package.

Atoms with a defined oxidation state draw properties from the “Species” class.

Attributes:#

Element.symbol (string) : Elemental symbol used to retrieve data

Element.name (string) : Full name of element

Element.number (int) : Proton number of element

Element.pauling_eneg (float) : Pauling electronegativity (0.0 if unknown)

Element.ionpot (float) : Ionisation potential in eV (0.0 if unknown)

Element.e_affinity (float) : Electron affinity in eV (0.0 if unknown)

Element.dipol (float) : Static dipole polarizability in 1.6488e-41 C m^2 / V (0.0 if unknown)

Element.eig (float) : Electron eigenvalue (units unknown) N.B. For Cu, Au and Ag this defaults to d-orbital

Element.eig_s (float) : Eigenvalue of s-orbital

Element.SSE (float) : Solid State Energy

Element.SSEPauling (float) : SSE based on regression fit with Pauling electronegativity

Element.oxidation_states (list)Default list of allowed oxidation

states for use in SMACT. In >3.0, these are the ICSD24 set. In <3.0, these are the SMACT14 set.

Element.oxidation_states_smact14 (list): Original list of oxidation

states that were manually compiled for SMACT in 2014 (default in SMACT < 3.0)

Element.oxidation_states_sp (list) : List of oxidation states recognised by the Pymatgen Structure Predictor

Element.oxidation_states_icsd16 (list) : List of oxidation states that appear in the 2016 version of ICSD

Element.oxidation_states_wiki (list): List of oxidation states that

appear on Wikipedia. See https://en.wikipedia.org/wiki/Template:List_of_oxidation_states_of_the_elements Data retrieved: 2022-09-22

Element.oxidation_states_custom (list | None ): List of oxidation

states that appear in the custom data file supplied (if any)

Element.oxidation_states_icsd24 (list): List of oxidation states that appear in the 2024 version of the ICSD

Element.coord_envs (list): The allowed coordination environments for the ion

Element.covalent_radius (float) : Covalent radius of the element

Element.mass (float) : Molar mass of the element

Element.crustal_abundance (float) : Crustal abundance in the earths crust mg/kg taken from CRC

Element.HHI_p (float) : Herfindahl-Hirschman Index for elemental production

Element.HHI_r (float) : Herfindahl-Hirschman Index for elemental reserves

Element.mendeleev (int): Mendeleev number

Element.AtomicWeight (float): Atomic weight

Element.MeltingT (float): Melting temperature in K

Element.num_valence (int): Number of valence electrons

Element.num_valence_modified (int): Number of valence electrons based on a modified definition

Raises:#

KeyError: Element not found in element.txt

AtomicWeight: float | None#
HHI_p: float | None#
HHI_r: float | None#
MeltingT: float | None#
SSE: float | None#
SSEPauling: float | None#
property atomic_weight: float | None#

Atomic weight (alias for AtomicWeight).

coord_envs: list[str] | None#
covalent_radius: float#
crustal_abundance: float#
dipol: float#
e_affinity: float#
eig: float#
eig_s: float#
property hhi_p: float | None#

Herfindahl-Hirschman Index for production (alias for HHI_p).

property hhi_r: float | None#

Herfindahl-Hirschman Index for reserves (alias for HHI_r).

ionpot: float#
mass: float#
property melting_t: float | None#

Melting temperature in K (alias for MeltingT).

mendeleev: int | None#
name: str#
num_valence: int | None#
num_valence_modified: int | None#
number: int#
oxidation_states: list[int] | None#
oxidation_states_custom: list[int] | None#
oxidation_states_icsd16: list[int] | None#
oxidation_states_icsd24: list[int] | None#
oxidation_states_smact14: list[int] | None#
oxidation_states_sp: list[int] | None#
oxidation_states_wiki: list[int] | None#
pauling_eneg: float | None#
property sse: float | None#

Solid State Energy (alias for SSE).

property sse_pauling: float | None#

SSE from Pauling electronegativity regression (alias for SSEPauling).

symbol: str#
class smact.Species(symbol: str, oxidation: int, coordination: int = 4, radii_source: str = 'shannon')[source]#

Bases: Element

Class providing data for elements in a given chemical environment.

In addition to the standard properties from the periodic table (inherited from the Element class), Species objects use the oxidation state and coordination environment to provide further properties. The Species object can be created with either a default set of shannon radii (radii_source=’shannon’) or with a set of machine-learnt shannon radii (radii_source=’extended’). The source of the machine-learnt shannon radii set is Baloch, A.A., Alqahtani, S.M., Mumtaz, F., Muqaibel, A.H., Rashkeev, S.N. and Alharbi, F.H., 2021. Extending Shannon’s ionic radii database using machine learning. Physical Review Materials, 5(4), p.043804.

Attributes:#

Species.symbol: Elemental symbol used to retrieve data

Species.name: Full name of element

Species.oxidation: Oxidation state of species (signed integer)

Species.coordination: Coordination number of species (integer)

Species.pauling_eneg: Pauling electronegativity (0.0 if unknown)

Species.ionpot: Ionisation potential in eV (0.0 if unknown)

Species.e_affinity: Electron affinity in eV (0.0 if unknown)

Species.eig: Electron eigenvalue (units unknown)

N.B. For Cu, Au and Ag this defaults to d-orbital.

Species.shannon_radius: Shannon radius of Species.

Species.ionic_radius: Ionic radius of Species.

Species.average_shannon_radius: An average shannon radius for

the species. The average is taken over all coordination environments.

Species.average_ionic_radius: An average ionic radius for

the species. The average is taken over all coordination environments.

Raises:#

KeyError: Element not found in element.txt

smact.are_eq(a: Sequence[float], b: Sequence[float], tolerance: float = 0.0001) → bool[source]#

Check two arrays for approximate element-wise equality.

Parameters:

  • a – 1-D sequence of values.

  • b – 1-D sequence of values.

  • tolerance – Absolute tolerance for equality.

Returns:

True if arrays are element-wise equal within tolerance, False otherwise.

smact.element_dictionary(elements: Iterable[str] | None = None, oxi_states_custom_filepath: str | None = None) → dict[str, Element][source]#

Create a dictionary of initialised smact.Element objects.

Accessing an Element from a dict is significantly faster than repeatedly initialising them on-demand within nested loops.

Args:#

elements (iterable of strings)Elements to include. If None,

use all elements up to 103.

oxi_states_custom_filepath (str): Path to custom oxidation states file

Returns:#

dict: Dictionary with element symbols as keys and smact.Element

objects as data

smact.lattices_are_same(lattice1: Sequence, lattice2: Sequence, tolerance: float = 0.0001) → bool[source]#

Check whether two ASE lattices contain the same sites.

Parameters:

  • lattice1 – ASE crystal class.

  • lattice2 – ASE crystal class.

  • tolerance – Absolute tolerance for position equality.

Returns:

True if every site in lattice1 has a matching site in lattice2.

smact.neutral_ratios(oxidations: Sequence[int], stoichs: Sequence[Sequence[int]] | None = None, threshold: int | None = 5) → list[tuple[int, ...]][source]#

Get a list of charge-neutral compounds.

Given a list of oxidation states of arbitrary length, return ratios in which these form a charge-neutral compound. Stoichiometries may be provided as a set of legal stoichiometries per site (e.g. a known family of compounds); otherwise all unique ratios are tried up to a threshold coefficient.

Args:#

oxidations (list of ints): Oxidation state of each site stoichs (list of positive ints): A selection of valid stoichiometric

ratios for each site

threshold (int): Maximum stoichiometry coefficient; if no ‘stoichs’

argument is provided, all combinations of integer coefficients up to this value will be tried.

Returns:#

list of tuples: Ratios of atoms in given oxidation states which yield

a charge-neutral structure. Empty list if no ratios exist.

smact.neutral_ratios_iter(oxidations: Sequence[int], stoichs: Sequence[Sequence[int]] | None = None, threshold: int | None = 5) → Iterator[tuple[int, ...]][source]#

Iterator for charge-neutral stoichiometries.

Given a list of oxidation states of arbitrary length, yield ratios in which these form a charge-neutral compound. Stoichiometries may be provided as a set of legal stoichiometries per site (e.g. a known family of compounds); otherwise all unique ratios are tried up to a threshold coefficient.

Args:#

oxidations : list of integers stoichs : stoichiometric ratios for each site (if provided) threshold : single threshold to go up to if stoichs are not provided

Returns:#

filter: Iterator of tuples; each tuple is a ratio that gives neutrality

smact.ordered_elements(x: int, y: int) → list[str][source]#

Return a list of element symbols, ordered by proton number in the range x -> y.

Parameters:

  • x – Start of range (inclusive, 1-indexed proton number).

  • y – End of range (inclusive, 1-indexed proton number).

Returns:

Ordered list of element symbols.

Return type:

list

Submodules#