smact.screening module

smact.screening.eneg_states_test(ox_states: List[int], enegs: List[float])[source]

Internal function for checking electronegativity criterion

This implementation is fast as it ‘short-circuits’ as soon as it finds an invalid combination. However it may be that in some cases redundant comparisons are made. Performance is very close between this method and eneg_states_test_alternate.

Parameters

  • ox_states (list) – oxidation states corresponding to species in compound

  • enegs (list) – Electronegativities corresponding to species in compound

Returns

True if anions are more electronegative than

cations, otherwise False

Return type

bool

smact.screening.eneg_states_test_alternate(ox_states: List[int], enegs: List[float])[source]

Internal function for checking electronegativity criterion

This implementation appears to be slightly slower than eneg_states_test, but further testing is needed.

Parameters

  • ox_states (list) – oxidation states corresponding to species in compound

  • enegs (list) – Electronegativities corresponding to species in compound

Returns

True if anions are more electronegative than

cations, otherwise False

Return type

bool

smact.screening.eneg_states_test_threshold(ox_states: List[int], enegs: List[float], threshold: Optional[float] = 0)[source]

Internal function for checking electronegativity criterion

This implementation is fast as it ‘short-circuits’ as soon as it finds an invalid combination. However it may be that in some cases redundant comparisons are made. Performance is very close between this method and eneg_states_test_alternate.

A ‘threshold’ option is added so that this constraint may be relaxed somewhat.

Parameters

  • ox_states (list) – oxidation states corresponding to species in compound

  • enegs (list) – Electronegativities corresponding to species in compound

  • threshold (Option(float)) – a tolerance for the allowed deviation from the Pauling criterion

Returns

True if anions are more electronegative than

cations, otherwise False

Return type

bool

smact.screening.ml_rep_generator(composition: Union[List[Element], List[str]], stoichs: Optional[List[int]] = None)[source]

Function to take a composition of Elements and return a list of values between 0 and 1 that describes the composition, useful for machine learning.

The list is of length 103 as there are 103 elements considered in total in SMACT.

e.g. Li2O –> [0, 0, 2/3, 0, 0, 0, 0, 1/3, 0 ….]

Inspired by the representation used by Legrain et al. DOI: 10.1021/acs.chemmater.7b00789

Parameters

  • composition (list) – Element objects in composition OR symbols of elements in composition

  • stoichs (list) – Corresponding stoichiometries in the composition

Returns

List of floats representing the composition that sum

to one

Return type

norm (list)

smact.screening.pauling_test(oxidation_states: List[int], electronegativities: List[float], symbols: List[str] = [], repeat_anions: bool = True, repeat_cations: bool = True, threshold: float = 0.0)[source]
Check if a combination of ions makes chemical sense,

(i.e. positive ions should be of lower electronegativity).

Parameters

  • ox (list) – oxidation states of elements in the compound

  • paul (list) – the corresponding Pauling electronegativities of the elements in the compound

  • symbols (list) – chemical symbols of each site

  • threshold (float) – a tolerance for the allowed deviation from the Pauling criterion

  • repeat_anions – boolean, allow an anion to repeat in different oxidation states in the same compound

  • repeat_cations – as above, but for cations

Returns

True if anions are more electronegative than cations, otherwise False

Return type

bool

smact.screening.pauling_test_old(ox: List[int], paul: List[float], symbols: List[str], repeat_anions: bool = True, repeat_cations: bool = True, threshold: float = 0.0)[source]

Check if a combination of ions makes chemical sense, (i.e. positive ions should be of lower Pauling electronegativity). This function should give the same results as pauling_test but is not optimised for speed.

Parameters

  • ox (list) – oxidation states of the compound

  • paul (list) – the corresponding Pauling electronegativities of the elements in the compound

  • symbols (list) – chemical symbols of each site.

  • threshold (float) – a tolerance for the allowed deviation from the Pauling criterion

  • repeat_anions – boolean, allow an anion to repeat in different oxidation states in the same compound.

  • repeat_cations – as above, but for cations.

Returns

True if anions are more electronegative than cations, otherwise False

Return type

(bool)

smact.screening.smact_filter(els: Union[Tuple[Element], List[Element]], threshold: Optional[int] = 8, stoichs: Optional[List[List[int]]] = None, species_unique: bool = True, oxidation_states_set: str = 'default', comp_tuple: bool = False) → Union[List[Tuple[str, int, int]], List[Tuple[str, int]]][source]

Function that applies the charge neutrality and electronegativity tests in one go for simple application in external scripts that wish to apply the general ‘smact test’.

Parameters

  • els (tuple/list) – A list of smact.Element objects

  • threshold (int) – Threshold for stoichiometry limit, default = 8

  • stoichs (list[int]) – A selection of valid stoichiometric ratios for each site.

  • species_unique (bool) – Whether or not to consider elements in different oxidation states as unique in the results.

  • oxidation_states_set (string) – A string to choose which set of oxidation states should be chosen. Options are ‘default’, ‘icsd’, ‘pymatgen’ and ‘wiki’ for the default, icsd, pymatgen structure predictor and Wikipedia (https://en.wikipedia.org/wiki/Template:List_of_oxidation_states_of_the_elements) oxidation states respectively. A filepath to an oxidation states text file can also be supplied as well.

  • comp_tuple (bool) – Whether or not to return the results as a named tuple of elements and stoichiometries (True) or as a normal tuple of elements and stoichiometries (False).

Returns

Allowed compositions for that chemical system in the form [(elements), (oxidation states), (ratios)] if species_unique=True or in the form [(elements), (ratios)] if species_unique=False.

Return type

allowed_comps (list)

Example usage:
>>> from smact.screening import smact_filter
>>> from smact import Element
>>> els = (Element('Cs'), Element('Pb'), Element('I'))
>>> comps = smact_filter(els, threshold =5 )
>>> for comp in comps:
>>>     print(comp)
[('Cs', 'Pb', 'I'), (1, -4, -1), (5, 1, 1)]
[('Cs', 'Pb', 'I'), (1, 2, -1), (1, 1, 3)]
[('Cs', 'Pb', 'I'), (1, 2, -1), (1, 2, 5)]
[('Cs', 'Pb', 'I'), (1, 2, -1), (2, 1, 4)]
[('Cs', 'Pb', 'I'), (1, 2, -1), (3, 1, 5)]
[('Cs', 'Pb', 'I'), (1, 4, -1), (1, 1, 5)]
Example (using stoichs):
>>> from smact.screening import smact_filter
>>> from smact import Element
>>> comps = smact_filter(els, stoichs = [[1],[1],[3]], comp_tuple=True )
>>> for comp in comps:
>>>     print(comp)
Composition(element_symbols=('Cs', 'Pb', 'I'), oxidation_states=(1, 2, -1), stoichiometries=(1, 1, 3))