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_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
- rather than a reference to the cached object -- (dictionary,) –
- use copy=False in performance-sensitive code and where (only) –
- are certain the dictionary will not be modified! (you) –
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
- rather than a reference to the cached object -- (dictionary,) –
- use copy=False in performance-sensitive code and where (only) –
- are certain the dictionary will not be modified! (you) –
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,
- than a reference to a cached object -- only use (rather) –
- in performance-sensitive code and where you are (copy=False) –
- the dictionary will not be modified! (certain) –
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.