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.

Semiconducting Materials from Analogy and Chemical Theory

A collection of fast screening tools from elemental data

class smact.Element(symbol)[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
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, oxidation, coordination=4, radii_source='shannon')[source]

Bases: smact.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, B, tolerance=0.0001)[source]

Check two arrays for tolerance [1,2,3]==[1,2,3]; but [1,3,2]!=[1,2,3] :param A, B: 1-D list of values for approximate equality comparison :type A, B: lists :param tolerance: numerical precision for equality condition

Returns:boolean
smact.element_dictionary(elements=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.
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,lattice2 – ASE crystal class
Returns:boolean
smact.neutral_ratios(oxidations, stoichs=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, stoichs=False, threshold=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, y)[source]

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

Returns:Ordered list of element symbols
Return type:list