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: Optional[str] = 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.

symbol

Elemental symbol used to retrieve data

Type

string

name

Full name of element

Type

string

number

Proton number of element

Type

int

pauling_eneg

Pauling electronegativity (0.0 if unknown)

Type

float

ionpot

Ionisation potential in eV (0.0 if unknown)

Type

float

e_affinity

Electron affinity in eV (0.0 if unknown)

Type

float

dipol

Static dipole polarizability in 1.6488e-41 C m^2 / V (0.0 if unknown)

Type

float

eig

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

Type

float

eig_s

Eigenvalue of s-orbital

Type

float

SSE

Solid State Energy

Type

float

SSEPauling

SSE based on regression fit with Pauling electronegativity

Type

float

oxidation_states

Default list of allowed oxidation states for use in SMACT

Type

list

oxidation_states_sp

List of oxdation states recognised by the Pymatgen Structure Predictor

Type

list

oxidation_states_icsd

List of oxidation states that appear in the ICSD

Type

list

oxidation_states_wiki

List of oxidation states that appear wikipedia (https://en.wikipedia.org/wiki/Template:List_of_oxidation_states_of_the_elements) Data retrieved: 2022-09-22

Type

list

oxidation_states_custom

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

Type

list | None

coord_envs

The allowed coordination enviroments for the ion

Type

list

covalent_radius

Covalent radius of the element

Type

float

mass

Molar mass of the element

Type

float

crustal_abundance

Crustal abundance in the earths crust mg/kg taken from CRC

Type

float

HHI_p

Herfindahl-Hirschman Index for elemental production

Type

float

HHI_r

Hirfindahl-Hirschman Index for elemental reserves

Type

float

Raises

  • NameError – Element not found in element.txt

  • Warning – Element not found in Eigenvalues.csv

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.

symbol

Elemental symbol used to retrieve data

name

Full name of element

oxidation

Oxidation state of species (signed integer)

coordination

Coordination number of species (integer)

pauling_eneg

Pauling electronegativity (0.0 if unknown)

ionpot

Ionisation potential in eV (0.0 if unknown)

e_affinity

Electron affinity in eV (0.0 if unknown)

eig

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

shannon_radius

Shannon radius of Species.

ionic_radius

Ionic radius of Species.

average_shannon_radius

An average shannon radius for the species. The average is taken over all coordination environments.

average_ionic_radius

An average ionic radius for the species. The average is taken over all coordination environments.

Raises

  • NameError – Element not found in element.txt

  • Warning – Element not found in Eigenvalues.csv

smact.are_eq(A: list, B: list, tolerance: float = 0.0001)[source]

Check two arrays for tolerance [1,2,3]==[1,2,3]; but [1,3,2]!=[1,2,3]

Parameters

  • A (lists) – 1-D list of values for approximate equality comparison

  • B (lists) – 1-D list of values for approximate equality comparison

  • tolerance – numerical precision for equality condition

Returns

boolean

smact.element_dictionary(elements: Optional[Iterable[str]] = None, oxi_states_custom_filepath: Optional[str] = None)[source]

Create a dictionary of initialised smact.Element objects

Accessing an Element from a dict is significantly faster than repeadedly 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, lattice2, tolerance=0.0001)[source]

Checks for the equivalence of two lattices

Parameters

  • lattice1 – ASE crystal class

  • lattice2 – ASE crystal class

Returns

boolean

smact.neutral_ratios(oxidations: List[int], stoichs: Union[bool, List[List[int]]] = False, threshold=5)[source]

Get a list of charge-neutral compounds

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.

Given a list of oxidation states of arbitrary length it searches for neutral ratios in a given ratio of sites (stoichs) or up to a given threshold.

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

exists bool:

True ifc any ratio exists, otherwise False

allowed_ratios list of tuples:

Ratios of atoms in given oxidation states which yield a charge-neutral structure

Return type

(exists, allowed_ratios) (tuple)

smact.neutral_ratios_iter(oxidations: List[int], stoichs: Union[bool, List[List[int]]] = False, threshold: Optional[int] = 5)[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

Yields

tuple – 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 :param x: integers :param y: integers

Returns

Ordered list of element symbols

Return type

list

Submodules