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.

Variables:

  • 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, loaded from the static oxidation_states_icsd24_filtered.txt file (species with >5 reports in ICSD 2024). This is a stricter cut-off than the consensus=3 default applied dynamically by smact.screening.ICSD24FilterConfig in smact_validity; the two paths can therefore return different lists for the same element. For a configurable threshold use smact.utils.oxidation.ICSD24OxStatesFilter. 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.

Variables:

  • 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.

Parameters:

  • 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:

Dictionary with element symbols as keys and smact.Element

objects as data

Return type:

dict

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.

Parameters:

  • 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:

Ratios of atoms in given oxidation states which yield

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

Return type:

list of tuples

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.

Parameters:

  • 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:

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

Return type:

filter

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#