smact.data_loader module
Provide data from text files while transparently caching for efficiency.
This module handles the loading of external data used to initialise the core smact.Element and smact.Species classes. It implements a transparent data-caching system to avoid a large amount of I/O when naively constructing several of these objects. It also implements a switchable system to print verbose warning messages about possible missing data (mainly for debugging purposes). In general these fuctions are used in the background and it is not necessary to use them directly.
- smact.data_loader.lookup_element_data(symbol, copy=True)[source]
Retrieve tabulated data for an element.
The table “data/element_data.txt” contains a collection of relevant atomic data. If a cache exists in the form of the module-level variable _element_data, this is returned. Otherwise, a dictionary is constructed from the data table and cached before returning it.
- Parameters
symbol (str) – Atomic symbol for lookup
copy (Optional(bool)) – if True (default), return a copy of the data dictionary, rather than a reference to the cached object – only used copy=False in performance-sensitive code and where you are certain the dictionary will not be modified!
- Returns (dict)Dictionary of data for given element, keyed by
column headings from data/element_data.txt.
- smact.data_loader.lookup_element_hhis(symbol)[source]
Retrieve the HHI_R and HHI_p scores for an element.
- Parameters
symbol – the atomic symbol of the element to look up.
- Returns
(HHI_p, HHI_R)
Return None if values for the elements were not found in the external data.
- Return type
tuple
- smact.data_loader.lookup_element_oxidation_states(symbol, copy=True)[source]
Retrieve a list of known oxidation states for an element. The oxidation states list used is the SMACT default and most exhaustive list.
- Parameters
symbol (str) – the atomic symbol of the element to look up.
copy (Optional(bool)) – if True (default), return a copy of the oxidation-state list, rather than a reference to the cached data – only use copy=False in performance-sensitive code and where the list will not be modified!
- Returns
List of known oxidation states for the element.
Returns None if oxidation states for the Element were not found in the external data.
- Return type
list
- smact.data_loader.lookup_element_oxidation_states_custom(symbol, filepath, copy=True)[source]
Retrieve a list of known oxidation states for an element. The oxidation states list is specified by the user in a text file.
- Parameters
symbol (str) – the atomic symbol of the element to look up.
copy (Optional(bool)) – if True (default), return a copy of the oxidation-state list, rather than a reference to the cached data – only use copy=False in performance-sensitive code and where the list will not be modified!
- Returns
List of known oxidation states for the element.
Return None if oxidation states for the Element were not found in the external data.
- Return type
list
- smact.data_loader.lookup_element_oxidation_states_icsd(symbol, copy=True)[source]
Retrieve a list of known oxidation states for an element. The oxidation states list used contains only those found in the ICSD (and judged to be non-spurious).
- Parameters
symbol (str) – the atomic symbol of the element to look up.
copy (Optional(bool)) – if True (default), return a copy of the oxidation-state list, rather than a reference to the cached data – only use copy=False in performance-sensitive code and where the list will not be modified!
- Returns
List of known oxidation states for the element.
Return None if oxidation states for the Element were not found in the external data.
- Return type
list
- smact.data_loader.lookup_element_oxidation_states_sp(symbol, copy=True)[source]
Retrieve a list of known oxidation states for an element. The oxidation states list used contains only those that are in the Pymatgen default lambda table for structure prediction.
- Parameters
symbol (str) – the atomic symbol of the element to look up.
copy (Optional(bool)) – if True (default), return a copy of the oxidation-state list, rather than a reference to the cached data – only use copy=False in performance-sensitive code and where the list will not be modified!
- Returns
List of known oxidation states for the element.
Return None if oxidation states for the Element were not found in the external data.
- Return type
list
- smact.data_loader.lookup_element_oxidation_states_wiki(symbol, copy=True)[source]
Retrieve a list of known oxidation states for an element. The oxidation states list used contains only those that are on Wikipedia (https://en.wikipedia.org/wiki/Template:List_of_oxidation_states_of_the_elements).
- Parameters
symbol (str) – the atomic symbol of the element to look up.
copy (Optional(bool)) – if True (default), return a copy of the oxidation-state list, rather than a reference to the cached data – only use copy=False in performance-sensitive code and where the list will not be modified!
- Returns
List of known oxidation states for the element.
Return None if oxidation states for the Element were not found in the external data.
- Return type
list
- smact.data_loader.lookup_element_shannon_radius_data(symbol, copy=True)[source]
Retrieve Shannon radii for known states of an element.
Retrieve Shannon radii for known oxidation states and coordination environments of an element.
- Parameters
symbol (str) – the atomic symbol of the element to look up.
copy (Optional(bool)) – if True (default), return a copy of the data
dictionary –
-- (rather than a reference to the cached object) –
where (only use copy=False in performance-sensitive code and) –
modified! (you are certain the dictionary will not be) –
- Returns
Shannon radii datasets.
Returns None if the element was not found among the external data.
Shannon radii datasets are dictionaries with the keys:
- charge
int charge
- coordination
int coordination
- crystal_radius
float
- ionic_radius
float
- comment
str
- Return type
list
- smact.data_loader.lookup_element_shannon_radius_data_extendedML(symbol, copy=True)[source]
Retrieve the machine learned extended Shannon radii for known states of an element.
Retrieve Shannon radii for known oxidation states and coordination environments of an element.
Source of extended radii 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. arXiv preprint arXiv:2101.00269.
- Parameters
symbol (str) – the atomic symbol of the element to look up.
copy (Optional(bool)) – if True (default), return a copy of the data
dictionary –
-- (rather than a reference to the cached object) –
where (only use copy=False in performance-sensitive code and) –
modified! (you are certain the dictionary will not be) –
- Returns
Extended Shannon radii datasets.
Returns None if the element was not found among the external data.
Shannon radii datasets are dictionaries with the keys:
- charge
int charge
- coordination
int coordination
- ionic_radius
float
- comment
str
- Return type
list
- smact.data_loader.lookup_element_sse2015_data(symbol, copy=True)[source]
Retrieve SSE (2015) data for element in oxidation state.
Retrieve the solid-state energy (SSE2015) data for an element in an oxidation state. Taken from J. Solid State Chem., 2015, 231, pp138-144, DOI: 10.1016/j.jssc.2015.07.037.
- Parameters
symbol – the atomic symbol of the element to look up.
copy – if True (default), return a copy of the data dictionary,
use (rather than a reference to a cached object -- only) –
are (copy=False in performance-sensitive code and where you) –
modified! (certain the dictionary will not be) –
- Returns
- SSE datasets for the element, or None
if the element was not found among the external data.
SSE datasets are dictionaries with the keys:
- OxidationState
int
- SolidStateEnergy2015
float SSE2015
- Return type
list
- smact.data_loader.lookup_element_sse_data(symbol)[source]
Retrieve the solid-state energy (SSE) data for an element.
Taken from J. Am. Chem. Soc., 2011, 133 (42), pp 16852-16960, DOI: 10.1021/ja204670s
- Parameters
symbol – the atomic symbol of the element to look up.
- Returns
- SSE datasets for the element, or None
if the element was not found among the external data.
SSE datasets are dictionaries with the keys:
- AtomicNumber
int
- SolidStateEnergy
float SSE
- IonisationPotential
float
- ElectronAffinity
float
- MullikenElectronegativity
str
- SolidStateRenormalisationEnergy
float
- Return type
list
- smact.data_loader.lookup_element_sse_pauling_data(symbol)[source]
Retrieve Pauling SSE data
Retrieve the solid-state energy (SSEPauling) data for an element from the regression fit when SSE2015 is plotted against Pauling electronegativity. Taken from J. Solid State Chem., 2015, 231, pp138-144, DOI: 10.1016/j.jssc.2015.07.037
Args: symbol (str) : the atomic symbol of the element to look up.
- Returns: A dictionary containing the SSE2015 dataset for the
element, or None if the element was not found among the external data.